Telelogic Tau 4.4

Installation Guide

Telelogic
http://www.telelogic.com


Introduction

About this Manual

This volume, Installation Guide, contains all the information that is needed to install the Telelogic Tau software and license on your computer system. This includes:

  • information on system prerequisites before you start the installation.
  • information on how to setup your system for using Telelogic Tau.
  • a primer on licensing with trouble-shooting advice and a list of licensing management procedures.

Documentation Overview

A general description of the Telelogic Tau documentation can be found in "Telelogic Tau Documentation".

Typographic Conventions

The typographic conventions that are used in the Telelogic Tau documentation are described in "Typographic Conventions".

How to Contact Customer Support

Detailed contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".


1 Platforms and Products

This chapter lists the hardware and software prerequisites that must be fulfilled for a successful installation of the components in Telelogic Tau.

Compatibility information for platforms and products is also included in this chapter.


Hardware Prerequisites

This section describes the hardware requirements for Telelogic Tau.

Supported Architectures

  • Sun SPARC
  • HP 9000/700-800 series (PA-RISC). 1
  • PC's running Microsoft Windows 98, Windows NT 4.0, Windows 2000 or Windows XP.

UNIX Installation Prerequisites

Telelogic Tau on UNIX includes binaries for several different computer architectures, examples and on-line help files. During the installation, you may choose what parts to install.

The amount of disk space the different components will require is shown in the installation.

Windows Installation Prerequisites

Telelogic Tau for Windows includes binaries for four different computer architectures (Windows 98, Windows NT, Windows 2000 and Windows XP), examples and on-line help files. During the installation, you may choose what parts to install.

The amount of disk space the different components will require is shown in the installation.

The Telelogic Tau files can be installed once on a network server for all users, or locally on each user's PC.

To limit the required disk space in local PC installations, the Help files can be installed once on a network server. They do not have to be installed locally on each PC where the Telelogic Tau binaries are installed.

Run-time Prerequisites

To run the Telelogic Tau tools properly you need a certain amount of main memory and swap size; see "Operating System" .

Pointing Device

A pointing device is required in order to run Telelogic Tau.

1

The Japanese version of Telelogic Tau does not support the HP UNIX platform.


Software Prerequisites

This section describes the software requirements for Telelogic Tau.

Operating System

Architecture | OS Version | Minimum Main Memory | Virtual Memory (swap) Size
Sun SPARC | Solaris 2.6/7/8 | 64 MB | 128 MB
HP 9000/700-800 | HP-UX 10.20 up to 11.00 | 64 | 128
PC | Windows NT 4.0, Windows 2000, Windows XP | 641 | 1282
PC | Windows 98 | 323 | Set by Windows
1

Although the exact memory needs for a high-performance installation (meaning execution with little swap page faults) on a given PC are impossible to tell, the following memory requirements could be expected:
- 32 MB for Windows NT/2000/XP systems
- 20 MB for the Telelogic Tau graphical applications + 1 kB / line of SDL/PR input to the Analyzer.
- Add approx. 30 MB for the Borland or Microsoft C compiler environment (if C code is to be generated from the SDL system).
- Add memory requirements for other applications that you want to run in the session (Microsoft Word, Netscape, etc.)

2

To double the main memory size is a good starting point.

3

Similar to a. The Windows 98 system requires only 16 MB, though.

UNIX Graphical Environment

On UNIX, Telelogic Tau is a X Window System application to be executed under the Motif Window Manager (Mwm).

Telelogic Tau require the X Window System, version R5 or later. The X Window System is provided by your workstation supplier.

Required HTML Viewers

The Telelogic Tau on-line help requires an HTML viewer. Telelogic Tau on UNIX supports Internet Explorer version 4 and 5 and Netscape version 2 and above. On Windows Internet Explorer version 4 and 5 are supported.


Telelogic Tau Compatibility Matrix

Telelogic Tau 4.4

 | SDL Suite 4.4 | TTCN Suite 4.4 | UML Suite 4.7 | Logiscope 5.0
SDL Suite 4.4 | -- | Integrated | Integrated1 | Not integrated
TTCN Suite 4.4 | Integrated | -- | Not integrated | Not integrated
UML Suite 4.7 | Integrated2 | Not integrated | -- | Integrated
Logiscope 5.0 | Not integrated | Not integrated | Integrated | --
1

Not tested with SDL Suite Japanese version.

2

Not tested with SDL Suite Japanese version.

Other Telelogic Products

 | SDL Suite 4.4 | TTCN Suite 4.4 | UML Suite 4.7 | Logiscope 5.0
DOORS 5.1 | Integrated1 | Integrated | Integrated | Not integrated
CM Synergy 5.0 | Integrated2 | Integrated | Integrated | Not integrated
DocExpress 3.0 | Integrated3 | Not integrated | Integrated | Not integrated
1

Not tested with SDL Suite Japanese version.

2

Not tested with SDL Suite Japanese version.

3

Not tested with SDL Suite Japanese version.


Build and Certification Matrices

The SDL Suite Compiler Environment

A C/C++ compiler is required for the TTCN Link, the SDL suite simulation and validation features, and for Cadvanced SDL to C compiler for host and target environments.

For information regarding installation, see the compiler documentation.

The libraries included in the distribution of the TTCN Link, the simulation and validation features were built using the following C compilers. You are advised to install and use the same compilers, or closely compatible ones. It may be possible to use other compilers, but this is not tested or supported by Telelogic.

SDL Suite 4.4 (UNIX)

Table legend:

  • The software will execute on the platforms defined in the table header.
  • The Build environment is the compiler/s and OS environment used to build the software.
  • Precompiled kernels and Postmaster objects/lib indicate which compiler/s to build, and which compiler/s that should be compatible.
  • Word processors indicate which word processors that can be used for editing and which word processors that can handle the printed information.
  • Requirement Management tool and Version Control and Configuration Management indicates versions used during certification.

SDL Suite | Solaris 2.6 | Solaris 7/8 | HP-UX 10.201 | HP-UX 11.002
Build
Build environment | cc SUNWspro (ANSI-C)/CC (v5.0) compiler | -- | gcc (ANSI-C)/g++ 2.95.2 | --
Precompiled kernels and postmaster object/lib
C | cc SUNWspro v5.0 (build and test) gcc 2.95.2 (build and test) | cc SUNWspro v5.0 (test) gcc 2.95.2 (test) | c89 (ANSI-C) (build and test) gcc 2.95.2 (build and test) | c89 (ANSI-C) (test) gcc 2.95.2 (test)
C++ | CC SUNWspro v5.0 (build and test) g++ 2.95.2 (build and test) | CC SUNWspro v5.0 (test) g++ 2.95.2 (test) | HP native aC++ (A.01.21) (build and test) g++ 2.95.2 (build and test) | HP native aC++ (A.01.21) (test) g++ 2.95.2 (test)
Word processors
Editing | GNU emacs 19.31 or later | GNU emacs 19.31 or later | GNU emacs 19.31 or later | GNU emacs 19.31 or later
Printing | FrameMaker 6.0 Interleaf | FrameMaker 6.0 Interleaf | FrameMaker 6.0 Interleaf | FrameMaker 6.0 Interleaf
Requirement Management tool
DOORS | 5.1 | 5.1 | 5.1 | 5.1
Version Control and Configuration Management
CM Synergy | 5.1 | 5.1 | 5.1 | 5.1
Clearcase | 4.1 | 4.1 | 4.1 | 4.1
RCS | 5 or later | 5 or later | 5 or later | 5 or later
Licensing
FLEXlm | 8.0d | 8.0d | 8.0d | 8.0d
1

Not supported with Japanese version.

2

Not supported with Japanese version.

SDL Suite 4.4 (Windows)

SDL Suite1 | Windows NT 4 | Windows 2000/XP | Windows 98
Build |  |  |
Build environment | MS Visual C++ 6.0 SP4 | -- | --
Precompiled kernels and postmaster object/lib |  |  |
C | Borland 5.02 (build and test) Borland Builder 3 (test) Visual C++ 5 (build and test) Visual C++ 6 (test) | Borland 5.02 (test) Borland Builder 3 (test) Visual C++ 5 (test) Visual C++ 6 (test) | Borland 5.02 (test) Borland Builder 3 (test) Visual C++ 5 (test) Visual C++ 6 (test)
C++ | Borland Builder 3 (test) Visual C++ 5 (build and test) Visual C++ 6 (test) | Borland Builder 3 (test) Visual C++ 5 (test) Visual C++ 6 (test) | Borland Builder 3 (test) Visual C++ 5 (test) Visual C++ 6 (test)
Word processors |  |  |
Editing and Printing2 | MS Word 7, MS Word 97 | MS Word 2000 | MS Word 7, MS Word 97
Requirement Management tool |  |  |
DOORS | 5.1 | 5.1 | 5.1
Version Control and Configuration Management
CM Synergy | 5.1 | 5.1 | 5.1
Clearcase | 4.1 | 4.1 | 4.1
RCS | 5 or later | 5 or later | 5 or later
PVCS | 6.5 | 6.5 | 6.5
Licensing
FLEXlm | 8.0d | 8.0d | 8.0d
1

SDL Suite Japanese version is supported for Japanese versions of Windows NT, 2000, XP and 98.

2

MS Word 98 is supported for SDL Suite Japanese version on Windows NT and 98.

RTOS integrations

The following tables define the host and target environments where the integration types have been developed and tested.

Please see Integration with Operating Systems for important information about support for OS integrations.

Tight Integrations Templates

 | OSE | VxWorks | Solaris | Win32
Version | 4.2.2 | VxWorks 5.4 | Solaris 2.6 | WinNT
OS | MS Windows NT 4.0 SP 6 | MS Windows NT 4.0 SP 6 | Solaris | MS Windows NT 4.0 SP 6
Environment |  | MS Windows NT 4.0 SP 6 | Solaris Workshop 4.2 | MS Visual Studio SP4
Simulation (soft-kernel) | SoftKernel on MS Windows NT 4.0 SP 6 | VxSim on MS Windows NT 4.0 SP 6 | Like target | Like target
Target |  |  | Sun Sparc with Solaris 2.6/7/8 | x86-PC with Win98Se, Me, NT4.0, 2000

Threaded Integrations

 | OSE | VxWorks | Solaris | Win32
Version | 4.4 | VxWorks 5.4 | Solaris 2.6 | WinNT
OS | Solaris | Solaris | Solaris | MS Windows NT 4.0 SP 6
Environment | gcc 2.95.7 | Solaris Workshop 4.2 | Solaris Workshop 4.2 | MS Visual Studio SP4
Simulation (soft-kernel) | SoftKernel on Solaris | VxSim on Solaris | Like target | Like target
Target |  |  | Sun Sparc with Solaris 2.6/7/8 | x86-PC with Win98Se, Me, NT4.0, 2000

Posix Support in Tight and Threaded Integrations

The generic POSIX integration is developed on Solaris and uses the following basic POSIX primitives:

  • pthreads,
  • semaphores,
  • message-queues.

The generic POSIX integration is available and tested on the following Host/Target platforms:

 | Solaris Host/ Solaris Target | HP_UX Host/ HP_UX Target | Solaris Host/ Linux Target1
Tight | Supported | -- | --
Threaded (default signaling model) | Supported | Supported | Supported
Threaded (alternative signaling model) | Supported | -- | --
1

Source files and makefile are generated with TAEX on Solaris. They must be transferred to Linux and manually compiled and linked there using the generated makefile.

The TTCN Suite Compiler Environment

An ANSI-C compiler is required for the TTCN-SDL Co-simulation feature and for C code generation for host and target environments. A C++ compiler is required for building TTCN Access applications (UNIX only).

For information regarding installation, see the compiler documentation.

The binaries included in the distribution of the TTCN-SDL Co-simulator were built using the C compilers listed below, and the TTCN Access libraries were built using the C++ compilers listed below. You are advised to install and use the same compilers, or closely compatible ones. It may be possible to use other compilers, but this is not tested or supported by Telelogic.

TTCN Suite 4.4 (UNIX)

For table legend, see "SDL Suite 4.4 (UNIX)" .

TTCN Suite | Solaris 2.6 | Solaris 7/8 | HP-UX 10.20 | HP-UX 11.00
Build
Build environment | cc SUNWspro (ANSI-C) (v5.0) compiler | -- | aC++ (A.01.21) | --
Precompiled kernels and postmaster object/lib
C | cc SUNWspro v5.0 (build and test) gcc 2.95.2 (build and test) | cc SUNWspro v5.0 (test) gcc 2.95.2 (test) | c89 (ANSI-C) (build and test) gcc 2.95.2 (build and test) | c89 (ANSI-C) (test) gcc 2.95.2 (test)

TTCN Suite 4.4 (Windows)

TTCN Suite | Windows NT 4 | Windows 2000/XP | Windows 98
Build |  |  |
Build environment | MS Visual C++ 6.0 | -- | --
Precompiled kernels and postmaster object/lib |  |  |
C | Borland 5.02 (build and test) Borland Builder 3 (test) Visual C++ 5 (build and test) Visual C++ 6 (test) | Borland 5.02 (test) Borland Builder 3 (test) Visual C++ 5 (test) Visual C++ 6 (test) | Borland 5.02 (test) Borland Builder 3 (test) Visual C++ 5 (test) Visual C++ 6 (test)


2 Installation Procedure for UNIX

This chapter contains step-wise instructions for installing Telelogic Tau SDL suite and Telelogic Tau TTCN suite on UNIX systems, including the software licenses.

For instructions on installing the SDL and TTCN suites for Windows, see 3 Installation Procedure for Windows.

In case you encounter problems, contact Telelogic Customer Support, see "How to Contact Customer Support".


Overview

This chapter's installation procedure will help you install the SDL suite and the TTCN suite on your UNIX system. You can do a full installation or customize it to meet your needs.

The process involves installing the actual software, as well as installing and activating your licenses.

Before You Start

Before starting your installation, determine which UNIX system(s) your installation will run on (HP or Sun).

Have the license materials at hand before starting the installation. Your Telelogic Tau delivery should contain a hardcopy of your FLEXlm license key.

If you have not yet received a FLEXlm license key, see the box marked Important!.

For general information on licensing, see 6 A Primer on Licensing.

Installation Options

When installing the software you will be asked what components to install. You can always add components afterwards by running the installation procedure again (see "Adding Telelogic Tau Components to an Existing Installation" ).

The Telelogic Tau components are:

  • The SDL suite application for the supported UNIX systems. See "Operating System" .
  • The SDL suite collection of example files. Using these files, you will be able to follow the SDL suite tutorials and other complete examples in the documentation
  • The TTCN suite application and example files, for the supported UNIX systems. See "Operating System" .
  • The TTCN suite collection of example files. Using these files, you will be able to follow the TTCN suite tutorials and other complete examples in the documentation
  • On-line help files in HTML format.

Note: PDF documentation

The complete user documentation is also available in PDF format in the directory pdf/files on the Telelogic Tau CD-ROM.


Installation Procedure

The flowchart below shows the basic steps of the installation procedure.

Figure 1 : Flowchart for installation

Important!

If you have not received a FLEXlm license key, you will not be able to install Telelogic Tau.

To obtain a license key you have to provide Telelogic Customer Support with the hostname and hostID of the machine on which the license server will run. To obtain this information:

  1. Log in on the license server machine.
  2. Insert the Telelogic Tau CD-ROM.
  3. Mount the CD-ROM.
  4. Change directory to the top level of the CD-ROM, and execute the script called lmhostid.unx. You will now get information about your hostname and hostID.
  5. EMAIL or FAX this information, and if possible the name of the directory where Telelogic Tau will be installed, to Telelogic Customer Support (see "How to Contact Customer Support").

Alternatively, if you wish to first install the software from the CD-ROM, you can do the following:

  1. Perform all steps in the installation procedure up until you reach "Installing the FLEXlm License" .
  2. If you do not want the license server to be the same machine as the one you have used for installing, now log in on the license server machine.
  3. Run the script $telelogic/bin/gethostinfo (where $telelogic is the installation directory).
  4. EMAIL or FAX the information to Telelogic Customer Support (see "How to Contact Customer Support").

When you have obtained the license key, you can complete the entire installation and run Telelogic Tau.

Mounting the CD-ROM on HP

  1. Insert the Telelogic Tau CD into the CD-ROM drive.
  2. If necessary, create a directory to be the mount point for the CD. The examples below use the directory /cdrom.
  3. To mount the CD-ROM on HP systems, type:

/etc/mount -F cdfs -o cdcase -r /dev/dsk/c0t2d0 /cdrom

If any of the device names are unknown on your system, consult your system manager.
  4. To check if this worked, type ls /cdrom. You should see, among other things, tarfiles/ and tauinst.cd.

Mounting the CD-ROM on Sun

  1. Insert the Telelogic Tau CD into the CD-ROM drive.
  2. If necessary, create a directory to be the mount point for the CD. The examples below use the directory /cdrom.
  3. To mount the CD-ROM on Sun systems, there are two possibilities:
    • If you are using the Sun vold feature (Volume Management daemon), it will automatically mount the CD-ROM at the location /cdrom/Tau44
    • Do manual mounting by typing:
      mount -r -f hsfs /dev/sr0 /cdrom
      If the device name is unknown on your system, consult your system manager.
  4. To check if this worked, type ls /cdrom. You should see, among other things, tarfiles/ and tauinst.cd.

Installing the Software

Before starting the installation script, you should find a location in your file system where to store the installation. This directory is called the installation directory.

Therefore, if you already have the TTCN suite installed, you should use the same installation directory when installing the SDL suite, and vice versa. The installation procedure will create a subdirectory to this directory, called sdt or itex, depending on the chosen product.

/appl/telelogic will be used as an example installation directory for this installation.

The $telelogic variable is used to refer to the installation directory throughout this chapter. You may want to add this setting to your shell startup file.

Note:

Telelogic Tau 4.4 cannot be installed in the same directory as an older version of Telelogic Tau.
When you receive the license.dat file for 4.4, this license file can be used to run both Telelogic Tau 4.4 and a prior version (from the 3.02 version).

Installation Steps

Perform all the 11 steps below:

  1. Decide upon an installation directory. Also, check the amount of available disk space and verify it against the required space (see "UNIX Installation Prerequisites" ).
  2. Set the environment variable $telelogic to your installation directory:

If you run | Type
C shell-compatible shell (e.g. csh or tcsh) | setenv telelogic /appl/telelogic
Bourne shell-compatible shell (e.g. sh, ksh, zsh or bash) | telelogic=/appl/telelogic export telelogic

  3. Start the installation script, which will guide you through the installation. The script will also print some information during the installation procedure.

If you run | Type
SunOS with vold (Volume Management daemon) | cd /cdrom/Tau44 ./tauinst.cd
SunOS without vold | cd /cdrom ./tauinst.cd
HP-UX | cd /cdrom ./tauinst.cd

  4. Specify the installation directory:
Specify the root-directory for your Telelogic products?

>>    Enter path-name: [x]: /appl/telelogic

    • If you want to add components to an existing installation, specify the same directory as you did the first time. See "Adding Telelogic Tau Components to an Existing Installation" .
  5. Specify which components you want to install:
>> What would you like to install ?
>> 1: SDL and TTCN Suite
>>        2: SDL Suite
>>        3: TTCN Suite
>>        --------------------------------
>>        Please enter your choice [1]:

    • Enter the number of your selection. Continue the installation by pressing <Return>.
  6. Choose the platform(s) to install:
>> For which platform(s) do you want to install ?
>> 1: SUN
>> 2: HP
>> 3: SUN and HP
>> ----------------------------------------------
>> Please enter your choice [1]:

    • Specify the selected architectures by entering the number of your selection and pressing <Return>.
  7. Choose which components to install. The default answer for each component is Yes to install it. See "Installation Options" for more information.
  8. A list of the currently selected components and the required amount of disk space is displayed:
>> The following components will be installed.
SDL_SUNOS5 SDL_HP700 SDL_DEMO
TTCN_SUNO5 TTCN_HP700 HELP_HTML

!! This installation will require: xxx MB
!! of disk space at file system: /appl/telelogic

>> Are you satisfied with the following setup? (y/n) [y]:

    • Enter y or press <Return> if the selection is correct.
    • To change the selection, enter n and you will be prompted again to answer the questions.
  9. After the message "No further questions will be asked", information is displayed regarding the progress of the installation procedure.
  10. The message "Completed..." is displayed when the installation script has finished executing.
  11. To check that the installation was successful, do a ls $telelogic (where $telelogic is your installation directory). You should at least see:
bin/ bitmaps/ flex/ fontinfo/ include/ lib/ license.dat X11/

There can be other files and directories visible, depending on the chosen installation (for example an sdt/ or itex/ directory).

Installing the FLEXlm License

Follow the directions below to install your textual FLEXlm license file. The license file contains the license key you have received from Telelogic Customer Support.

If you have not yet received a FLEXlm license key, contact Telelogic Customer Support (see "How to Contact Customer Support").

Caution!

All information in the license.dat file is case significant, so be careful not to accidentally invalidate any of the encryption codes. Otherwise you will not be able to start the Telelogic Tau tools.

You have two options in installing your FLEXlm license:

  • In a shared license file, which is shared with other FLEXlm licensed software, see "Using a Shared License File" . You may consider this option if you have other software products that make use of FLEXlm licensing.
  • As a Telelogic specific license, which only handles licenses for Telelogic Tau, see "Using a Telelogic Specific License File" . This is the default option if you only will use FLEXlm for the Telelogic Tau licenses.

Using a Shared License File

If you have other products that make use of FLEXlm you may wish to install your Telelogic Tau license features into the existing FLEXlm license.dat file. To install the license key:

  1. Copy the following lines from the license key you received from Telelogic Customer Support into the existing license.dat file:
    • the VENDOR line; make sure to change the path to the /flex/{arch}flex subdirectory in your Telelogic Tau installation directory (where {arch} is the architecture of your server, i.e. "sunos5" or "hppa")
    • the FEATURE line(s)
      You must do this since your existing license server's "lmgrd" daemon is not in the same directory as the "telelogic" daemon (for information, see "FLEXlm Licensing Pitfalls to Avoid" ).
  2. Set the environment variable LM_LICENSE_FILE to point to the location of the existing license.dat file.
    It can also be a <port>@<hostname> setting, where <port> and <hostname> are the port number and hostname from the SERVER line in the license file, e.g. 7598@server.

If you run | Type
C shell-compatible shell (e.g. csh or tcsh) | setenv LM_LICENSE_FILE /your/directory/license.dat or setenv LM_LICENSE_FILE <port>@<hostname>
Bourne shell-compatible shell (e.g. sh, ksh, zsh or bash) | LM_LICENSE_FILE=/your/directory/license.dat export LM_LICENSE_FILE or LM_LICENSE_FILE=<port>@<hostname> export LM_LICENSE_FILE

  3. There must not be a license.dat file in the top level of the Telelogic Tau installation. If there is, remove or rename the file $telelogic/license.dat
  4. When you have changed any information in the license.dat file, you must update the license server to let it know about the changes. To do this, run the following script:
$telelogic/bin/updatelicd

The license installation is finished. Continue with "Installing a C Compiler" .

Using a Telelogic Specific License File

If you will only use FLEXlm for Telelogic Tau licenses, or wish to run a separate FLEXlm license server for Telelogic Tau, do the following:

  1. Log in on the computer where the license server is to run.
  2. Save or copy the FLEXlm license key you received from Telelogic Customer Support into a text file called license.dat, and store the file in the default location, which is the Telelogic Tau installation directory ($telelogic/license.dat).
  3. If you wish to place this file in another location, you must set the environment variable LM_LICENSE_FILE to point to this location.
    It can also be a <port>@<hostname> setting, where <port> and <hostname> are the port number and hostname from the SERVER line in the license file, e.g. 7598@server.

If you run | Type
C shell-compatible shell (e.g. csh or tcsh) | setenv LM_LICENSE_FILE /your/directory/license.dat or setenv LM_LICENSE_FILE <port>@<hostname>
Bourne shell-compatible shell (e.g. sh, ksh, zsh or bash) | LM_LICENSE_FILE=/your/directory/license.dat export LM_LICENSE_FILE or LM_LICENSE_FILE=<port>@<hostname> export LM_LICENSE_FILE

After the file has been placed in the new directory, make sure to remove or rename the file $telelogic/license.dat.
  4. Make sure that the information in the license.dat file is correct according to your server and installation:
    • The SERVER line must have the correct hostname and hostID.
    • The VENDOR line must have the correct path to the "telelogic" daemon. This daemon is located in the /flex/{arch}flex subdirectory in your Telelogic Tau installation directory (where {arch} is the architecture of your server, i.e. "sunos5" or "hppa")

Starting the License Server

You will now start the FLEXlm license server:

Note:

If you are using an evaluation license, or if the word "DEMO" ends each FEATURE line in your license.dat file, you do not need to start the license server.

  1. Make sure no license servers for the Telelogic Tau tools are currently running. Search for the license daemons lmgrd and telelogic in the current process list, for instance by using the command
    ps -ae | egrep '(lmgrd|telelog)'    . If you have any license daemons running, terminate them using the kill command and the PID number(s).
  2. Change to your installation directory:
cd $telelogic
  3. Start the license server:
./bin/startlicd
  4. Check that the license server has been started correctly with the following command:
./bin/stat -a

The license server statistics is displayed containing the server, the vendor daemon telelogic and the features available in your license.dat file.
  5. If the startup has failed, check the license.dat file for errors and omissions; see "FLEXlm Licensing Pitfalls to Avoid" . Double-check your file with the original sent from Telelogic Customer Support. Especially check the "company name" information in the quote-field of the first FEATURE line in the file.
    There is also a license.log file in the Telelogic Tau installation directory, where all actions concerning the license server are logged. The events to be logged includes:
    • Startup and shutdown of the license server
    • Checking licenses in and out
    • Denying licenses
      Each event involving a license also specifies:
    • The Telelogic Tau tool (license controlled tools only)
    • The user
    • The node
    • The date and time
    • The usage time (for check-in log entries)

Note:

The log file will grow as users run Telelogic Tau. You may consider deleting the head of the file from time to time to save disk space.

  6. The license server has to be restarted every time the server computer is rebooted. To do this automatically, see "Automatic Server Startup (UNIX)" .

The license installation is now finished.

Installing a C Compiler

You must also install a C compiler to be able to use certain features of the Telelogic Tau tools, such as Simulation and code generation. How to install a C compiler is described in the compiler documentation.

For information on which C compiler you need, see "The SDL Suite Compiler Environment" and "The TTCN Suite Compiler Environment" .


Starting Up the Telelogic Tau Tools

We recommend you to add the Telelogic Tau binary directory to your existing PATH variable.

Note:

The X Windows System and Motif Window Manger have to be started before you start Telelogic Tau.
In the case the computers on which you run the X Windows server and the client (the Telelogic Tau tools) coincide, make sure the environment variable DISPLAY is set to unix:0.0 before starting Telelogic Tau. Do not use the notation hostname:0.0

  • Below the Telelogic Tau installation directory, you will find a subdirectory called bin. This directory should be added to the user's path, e.g.
set path = ( $path $telelogic/bin )

  • Start the SDL suite, the TTCN suite and Telelogic Tau with the respective command:
    tau
    • You can also start the SDL suite, the TTCN suite and Telelogic Tau with:
      $telelogic/bin/tau


Adding Telelogic Tau Components to an Existing Installation

If you want to add components to your installation, follow the instructions below. For more information on available components, see "Installation Options" .

  1. Insert and mount the CD-ROM, as described in "Installation Procedure" .
  2. Follow all steps described in "Installing the Telelogic Tau Software" .
    • Enter the same installation directory as you did when you installed Telelogic Tau for the first time.
    • You will be asked the following question:
This directory already contains a sub-directory: sdt/(itex/)
>> Do you wish to update your existing SDL Suite (TTCN Suite) installation? [y]:

Answer y or press <Return>.
  • If you answer "No", the script will back up your old directory by renaming it to sdt.old (or itex.old) and then install the product. If you install a component that is already installed, the existing component will be overwritten.
  3. If you have received a new Telelogic Tau Product License Key, perform the actions described in "Installing the FLEXlm License" .


3 Installation Procedure for Windows

This chapter contains step-wise instructions for installing Telelogic Tau SDL suite and Telelogic Tau TTCN suite on either Windows XP, Windows NT 4.0, Windows 2000, or Windows 98, including the software licenses.

For instructions on installing the SDL suite and the TTCN suite on UNIX systems, see 2 Installation Procedure for UNIX.

In case you encounter problems, contact Telelogic Customer Support, see "How to Contact Customer Support".


Overview

This chapter's installation procedure will help you install the SDL suite and the TTCN suite on your system. You can do a full installation or customize it to meet your needs.

The process involves installing the actual Telelogic Tau software, as well as installing and activating your licenses.

Before You Start

Have the license materials at hand before starting the installation. You should have received your FLEXlmTM license key by e-mail.

For general information on licensing, see 6 A Primer on Licensing.

If you have not yet received a FLEXlm license key, see the box marked Important!.

Caution!

At some points in the installation you must supply directory names where Telelogic Tau or license components will reside. Telelogic Tau does not support file or directory names that contain space characters, so do not to use such names.

Installation Options

When installing the software you can choose what components to include. You can always add components afterwards by running the installation procedure again (see "Adding Telelogic Tau Components to an Existing Installation" ).

The Telelogic Tau components are:

  • SDL suite program files (binary executables).
  • TTCN suite program files (binary executables).
  • Example files. With these files, you will be able to follow the tutorials and other complete examples described in the documentation.
  • On-line help files in HTML format.

Note: PDF documentation

The complete Telelogic Tau documentation is also available in PDF format in the directory \PDF\files on the Telelogic Tau CD-ROM.

  • SDL suite application files necessary to run the tools.
  • TTCN suite application files necessary to run the tools.

Note: Limiting disk space

To limit local disk space usage in a multi-user environment, you may optionally put the on-line help files on a network server, if you are not performing a network installation. See "Configuring the Help Environment.


Installation Procedure

The flowchart below shows the basic steps of the installation procedure.

Figure 2 : Flowchart for installation

Important!

If you have not received a FLEXlm license key you will not be able to start Telelogic Tau after the installation is performed. Please see below for information on how to obtain the license key.

How to obtain a license key

To obtain a license key you have to provide Telelogic Customer Support with the hostname and hostID of the machine on which the license server will run. To obtain this information:

  1. Log in on the license server machine.
  2. Insert the Telelogic Tau CD-ROM.
  3. Change directory to the top level of the CD-ROM, and execute the batch file called lmhostid.bat.
  4. A utility called lmtools starts; select the System Settings tab (see Figure 3).
    • If you want the license to be locked to your network card, note the 12-character hex code in the Ethernet Address field.
      (example: "00abcde12345").
    • Use the 14-character code in the FLEXID8 field of lmtools (example: "8-5E700060F63D"). Lmtools is also included on the CD-ROM. The FLEXID can also be read on the dongle.
      For information on how to install the dongle, see "Installing the dongle and drivers" .

Figure 3 : lmtools dialog

  5. EMAIL or FAX this information to Telelogic Customer Support.

For contact information, see "How to Contact Customer Support".

When you have obtained a FLEXlm license key, you can complete the entire installation and run Telelogic Tau.

Log On as Administrator (Windows NT/2000 only)

To install Telelogic Tau on Windows NT and Windows 2000, you do not need to be logged on as the Administrator, but your login ID must be a member of the local or domain Administrators group.

  • Log on as Administrator, or make sure you have administrative privileges. To grant administrative privileges, use the Windows NT/2000 User Manager feature (see Windows NT/2000 System Guide).

Mounting the CD-ROM

  • Insert the Telelogic Tau CD into the CD-ROM drive or mount it if it resides on a network drive.
    In the rest of this chapter, we assume that the CD-ROM drive is mounted on drive D:\

Installing the Telelogic Tau Software

An installation utility, SETUP.EXE, is enclosed in the Telelogic Tau distribution.

The Telelogic Tau files are compressed and require the installation utility to be run. You will only be able to install Telelogic Tau if you run SETUP.EXE.

Installation Steps

Perform all the steps below:

  1. Start your Windows environment. If you are using Windows NT/2000, follow the directions in "Log On as Administrator (Windows NT/2000 only)" .
  2. Exit all running Windows programs.

Note: Starting the installation script

The instructions below describe how to start the installation script from the Windows Start menu. The script can also be started from the Telelogic Tau CD HTML interface. In that case, click the Install on Windows link on the Installation page and proceed with step 5 below.

  3. From the Windows Start menu, select Run.
  4. In the dialog that appears, specify:
    D:\sdl_ttcn\setup.exe
    and press <Return>. A welcome screen is opened.
  5. Click Next to continue the setup.
  6. Click Yes to accept the software license agreement.
  7. Select the installation directory. The default installation directory is:
    C:\Telelogic\SDL_TTCN_Suite4.4
    where `C' is the local hard drive on which Windows is installed. You may also change to a network drive to perform a single network installation for all users on your network.
  8. Click on Next to select the Setup Type:
    • Typical installation will install all SDL suite and TTCN suite files, including the Help files.
    • Compact installation will install SDL suite and TTCN suite files, excluding example files and on-line help files.
    • Custom installation enables you to choose components to install.
      If you want to add components to an existing Telelogic Tau 4.4 installation, use the Custom installation. See "Adding Telelogic Tau Components to an Existing Installation" .
  9. Select an option and click Next. The disk space requirements and which files to install before proceeding are determined. If you have chosen the Custom installation, select which components to install (see "Installation Options" for more information).
  10. Specify the program folder where the program shortcuts are to be placed.
  11. Click Next. Setup will now install the selected files, create shortcuts and update the registry.
  12. If not already defined, you will be asked for the license server and port number used. This information is found on the first line of the FLEXlm license key.
    If you have not received the license key, you can later add the license server and the port number to the file license.dat in the installation directory.
  13. Click Finish.

The installation of the SDL suite and the TTCN suite is now completed. If you have selected to install the UML Suite as well, the UML Suite Installation Wizard will start automatically. Further instructions regarding the UML Suite installation can be obtained in the UML Suite Installation Guide.

If you are using a host ID to identify your license, continue with "Installing a FLEXlm License" .

Installing the dongle and drivers

If you are using a dongle continue with the following steps.

  1. Turn off the computer.
  2. Find the parallel port on the back of the computer and plug in the dongle.
  3. Turn on the computer.
  4. Run Setup.exe located in d:\FLEX.
  5. Select the setup type Server Hardware key Nodelock.
  6. Select the installation directory and finish the installation.

Note: Install manually

If you are using Windows NT/2000/XP and want to install manually, you need to install drivers from d:\FLEX\FLEXID8\WINNTDRV.
If you are using Windows 98 and want to install manually, you might need to install drivers from the CD also. For more information see d:\FLEX\FLEXID8\WIN95DRV\Readme.txt.

Installing a FLEXlm License

Follow the directions below to install your textual FLEXlm license file. The license file contains the license key you have received from Telelogic Customer Support.

If you have not yet received a FLEXlm license key, see "How to obtain a license key" .

Caution!

All information in the license.dat file is case significant, so be careful not to accidentally invalidate any of the encryption codes. Otherwise you will not be able to start the Telelogic Tau tools.

You have two options in installing your FLEXlm license:

  • In a shared license file, which is shared with other FLEXlm licensed software, see "Using a Shared License File" . You may consider this option if you have other software products that make use of FLEXlm licensing.
  • As a Telelogic specific license, which only handles licenses for Telelogic Tau, see "Using a Telelogic Specific License File" . This is the default option if you only will use FLEXlm for the Telelogic Tau licenses.

Using a Shared License File

Make sure the global installation is FLEXlm 8.0d or higher. Otherwise install it from the included CD.

If you have other products that make use of FLEXlm you may wish to install your Telelogic Tau license features into the existing FLEXlm license.dat file. To install the license key:

  1. Copy the following lines from the license key you received from Telelogic Customer Support into the existing license.dat file:
    • the VENDOR line. Change the path to the \flex subdirectory in your Telelogic Tau installation directory (e.g. C:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex).
    • the FEATURE line(s)
      You must do this since your existing license server's "lmgrd" daemon is not in the same directory as the "telelogic" daemon (for information, see "FLEXlm Licensing Pitfalls to Avoid" ).
  2. When you have changed any information in the license.dat file, you must update the license server to let it know about the changes. To do this, start the FLEXlm utility in:
C:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex\lmtools.exe
and select Reread.

The license installation is finished. Continue with "Installing a C Compiler" .

Using a Telelogic Specific License File

If you will only use FLEXlm for Telelogic Tau licenses, or wish to run a separate FLEXlm license server for Telelogic Tau, do the following:

  1. Save or copy the FLEXlm license key you received from Telelogic Customer Support into a text file called license.dat.
  2. Store the file, for instance in the directory where Telelogic Tau is installed.

Starting the License Server

You will now start the FLEXlm license server:

Note:

If you are using an evaluation license, or if the word "DEMO" ends each FEATURE line in your license.dat file, you do not need to start the license server.

  1. Log in on the computer where the license server is to run.
  2. Make sure no license servers for the Telelogic Tau tools are currently running. Search for the license daemons lmgrd.exe and telelogic.exe in the Processes list in the Windows Task Manager (see "Automatic Server Startup (Windows)" ).
  3. Start a Command Prompt.
  4. Change to the FLEXlm directory in the Telelogic Tau installation, e.g.:
cd c:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex

  5. Start the license server:
c:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex> lmgrd -app

  6. Check that the license server has been started correctly. Execute
    c:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex> lmtools.exe and select Status.
    The license server statistics is displayed containing the server, the vendor daemon telelogic and the features available in your license.dat file.
  7. If the startup has failed, check the license.dat file for errors and omissions; see "FLEXlm Licensing Pitfalls to Avoid" . Double-check your file with the original sent from Telelogic Customer Support. Especially check the "company name" information in the quote-field of the first FEATURE line in the file.
    As an additional debugging help, the log for the license server will be displayed from where the license server was started. Unfortunately, when the server is started manually this way, there is no way to "close" this console window. It can be "minimized" at best.
  8. For Windows NT/2000/XP users, install the license server as a service using lmtools.exe; Windows 98 users should use the Startup folder. See "Automatic Server Startup (Windows)" for more information.

The license installation is now finished.

Installing a C Compiler

You must also install a C compiler to be able to use certain features of the Telelogic Tau tools, such as Simulation and code generation. How to install a C compiler is described in the compiler documentation.

For information on which C compiler you need, see "The SDL Suite Compiler Environment" and "The TTCN Suite Compiler Environment" .


Starting Up the Telelogic Tau Tools

Telelogic Tau can be started from an icon in Start menu > Programs. An alternative way is to double-click an .sdt file.


Post Installation

Limiting On-Line Help Disk Space

If you have installed Telelogic Tau locally on several PC's, you may wish to limit the disk space usage in a multi-user environment. Instead of storing the Telelogic Tau on-line help files locally on every PC where you have installed Telelogic Tau, you may put a single copy of the on-line help files on a network server. This is further described in "Configuring the Help Environment.


Adding Telelogic Tau Components to an Existing Installation

If you want to add components to your installation, follow the instructions below. For more information on available components, see "Installation Options" .

  1. Mount the CD, as described in "Mounting the CD-ROM" .
  2. Follow all steps described in "Installing the Telelogic Tau Software" .
    • In the Destination Location dialog, enter the same installation directory as you did when you installed Telelogic Tau the first time.
    • Choose Custom installation in the Setup Type dialog.
    • Deselect the components you do not want to install in the Select Components dialog. If you install a component that is already installed, the existing component will be overwritten.


4 System Setup

In this chapter, you will find information about what UNIX command-line tools and what OS environment variables Telelogic Tau takes advantage of.

You can also find information about factors in X Windows, OSF/Motif and Microsoft Windows that may affect the behavior of Telelogic Tau.

For UNIX, some of the setup information in this chapter is applicable on a user level and may thereby be required to be performed by each Telelogic Tau user on UNIX.


UNIX Command-Line Tools

All the Telelogic Tau tools that are possible to start from the UNIX prompt are invoked via commands in the $telelogic/bin directory ($telelogic is the Telelogic Tau installation directory). By adding this directory to the PATH variable, the user will be able to conveniently start all the Telelogic Tau tools with exception for stand-alone generated Simulators and Validators; see "Source Files" .

The start script $telelogic/bin/.tlwrapper is a common start script for Telelogic products that make use of the PostMaster, the integration mechanism of the SDL suite and the TTCN suite. It also sets up all environment variables needed to run the Telelogic products.

Caution!

The .tlwrapper script should never be invoked manually; it is only supposed to be executed via the Telelogic Tau commands.

The following table lists the most important command-line tools to use for controlling licensing and starting Telelogic Tau.

Command
Description

 gethostinfo
Obtain useful system information for FLEXlm licensing. See the box Important! in 2 Installation Procedure for UNIX for more information.

 startlicd
Start license server. See "Manually Starting the FLEXlm Server (UNIX)" for more information.

 updatelicd
Reread the license.dat file, useful after the license file has been edited. See "Updating the FLEXlm Server (UNIX)" for more information.

 stat
Show statistics about the license server; useful optional parameters [-a | -A | -f `feature']. See step 4. in 2 Installation Procedure for UNIX for an example.

 tau
Start the Telelogic Organizer.

 sdt
Start the Telelogic Organizer.

 itex
Start the Telelogic Organizer.


UNIX User Setup

For each Telelogic Tau user on UNIX, the following setups should be made.

Source Files

The Telelogic Tau installation provides a file which is suitable to be "sourced" at login, when the user's .cshrc or .profile file is executed. This source file will make the following environment variables visible in the terminal shell:

telelogic
telelogicbin
sdtrelease
sdtdir
sdtbin
itexrelease
itexlib
itexaccess
itexaccessroot
itexaccesscompiler

These environment variables are useful for the Telelogic Tau users. They can easily be used as pointers into the Telelogic Tau installation, without knowing were the installation is placed in the file system.

Note:

You do not need to set these variables to be able to run the SDL suite or the TTCN suite, except if you want to run a generated SDL Simulator or SDL Validator stand-alone, that is, run from the UNIX prompt without the graphical user interface.

To read the source file (/appl/telelogic is assumed to be the installation directory for Telelogic Tau):

If you run | Type
C shell-compatible shell (e.g. csh or tcsh) | source /appl/telelogic/bin/telelogic.sou
Bourne shell-compatible shell (e.g. sh, ksh, zsh or bash) | . /appl/telelogic/bin/telelogic.profile

Path and Display Variables

For each user, the Telelogic Tau bin directory should be contained in the list of directories defined by the PATH environment variable:

set path = ( $path $telelogic/bin )

This should be done in the shell startup files, as described above.

In the case the computers on which you run the X Windows server and the client (the Telelogic Tau tools) coincide, the environment variable DISPLAY should be set to unix:0.0 before starting Telelogic Tau. Do not use the notation hostname:0.0


Environment Variables

Environment variables common to UNIX and Windows:

  • HOME is used by the SDL suite applications to find preference files. On UNIX, it is also used to find validator/simulator command and button files and other files.
  • TMPDIR is used by Telelogic Tau applications when temporary files are created.

Note:

An ending slash (`/') or backslash (`\') is mandatory. Example:
On UNIX: setenv TMPDIR /usr/tmp/
In Windows: set TMPDIR=c:\tmp\

  • SDT_STORAGE_FORMAT is used by the SDL suite applications to decide what format to use when storing diagrams. The value ASCII means to use only printable ASCII characters in stored diagrams. Otherwise, the diagrams are binary files.
  • LM_LICENSE_FILE is used by the FLEXlm license mechanism in the Telelogic Tau tools.
    If this variable is set, the Telelogic Tau tools will append the search path to the license file in LM_LICENSE_FILE. If it is not set, the Telelogic Tau tools start-up command sets the variable.

UNIX-specific environment variables, in addition to the ones listed in "Source Files" :

  • TeleLOGIC_USEEXTVAR is used to make it possible to use already existing settings for the environment variables LM_LICENSE_FILE, sdtrelease and itexrelease. If the variable is set (it may be set to any value), the Telelogic Tau tools start-up script will not overwrite these variables.
  • XFILESEARCHPATH is used by X applications in the Telelogic Tau tools to find X resources. If it is set (before starting Telelogic Tau) the Telelogic Tau tools will append the search path to the Telelogic Tau tools resource files in XFILESEARCHPATH. If it is not set, the Telelogic Tau tools start up command sets the variable.
  • SDTTMPMNT is used by Telelogic Tau applications to strip the prefix which is added to directory names by some auto-mounters. When this variable is not set /tmp_mnt is stripped from directory names. Setting SDTTMPMNT to, for example /my_prefix, will strip /my_prefix from directory names.
  • SDLENOGRAPHICS is used by the SDL Editor's Signal Dictionary window to turn off the use of SDL icons and to use textual notation instead. This variable should be used when running the SDL suite on terminals with limited graphical capabilities.


Preferences

You may specify the default behavior of the SDL suite tools, and also for the Telelogic Tau common tools (such as the Organizer), by using the Preference Manager. You may define preferences in such way that they apply to an entire company, a specific project that uses Telelogic Tau, or to an individual user only. See Managing Preferences for how to customize Telelogic Tau.


Microsoft Windows System Factors

The SDL suite for Windows requires a display resolution of at least 640 * 480 pixels (VGA resolution).

The SDL suite for Windows can use any of the TrueType fonts that are installed in Microsoft Windows. For more information, see "Font Preference (Windows only).

Bindings between Microsoft Windows Explorer file types and the SDL suite for Windows files is performed through system files (with the .sdt extension).


X Window System Factors (UNIX only)

Display Resolution

The SDL suite relies on the display resolution reported by the X Server for mapping between screen (pixel) coordinates and diagram unit coordinates. If the X Server has erroneous resolution information, the screen image of an SDL suite document will have the wrong scale.

If required, the X Server must be adjusted to report the correct display resolution. See the documentation from the computer/software vendor for instructions.

Installed Fonts

The Telelogic Tau tools assumes that the fonts included in the MIT distribution of X11R5 are available.

Font Scaling

Note:

Font scaling is used by the SDL suite only - not the TTCN suite.

To achieve WYSIWYG between screen and printout, the SDL suite can use scalable fonts in conjunction with AFM (Adobe Font Metrics) files. Not all fonts scale well without the use of an X11R5 font server. Therefore, it is possible to turn off font scaling (at the price of the WYSIWYG capabilities), in which case the SDL suite will try to use only pre-scaled X fonts.

To turn on font scaling, edit the X resource file
$telelogic/X11/app-defaults/SDT and change the line:

SDT*sdtUseScalableFonts: false

into:

SDT*sdtUseScalableFonts: true

X Server Version

The Telelogic Tau tools have been tested with the MIT X11R5 server. No interoperability with earlier or later versions of X11 is guaranteed.

Window Manager

The Telelogic Tau tools are tested with Mwm, the Motif window manager, version 1.2. It is the recommended window manager to use with the Telelogic Tau tools.

Color Allocation

In the case of another X application having allocated all available color cells, the Telelogic Tau tools might fail to allocate colors for its windows and icons. The Telelogic Tau tools will try to allocate colors as close as possible to the ideal in the case of icons, but window colors cannot be guaranteed. To avoid this problem, a user might consider closing color-intensive applications that are not necessary to run in conjunction with the Telelogic Tau tools.

Changing the Color Settings

The color settings for the SDL suite are specified in the file $telelogic/X11/app-defaults/SDT and the color settings for the TTCN suite are specified in the file $telelogic/X11/app-defaults/Itex. You can change the colors by modifying the color resources settings; the color settings are found at the end of this file. When changing the colors, you may find some help about usable color names in the file $telelogic/X11/rgb.txt

How to modify resources is described in "Work Order for Modifying the Telelogic Tau Tools Resources" .


OSF/Motif Factors (UNIX only)

Event Translations

The X resource files SDT and Itex uses both OSF/Motif virtual bindings and ordinary X event specifications in translation tables. Refer to the OSF/Motif documentation for a discussion of virtual bindings.

Work Order for Modifying the Telelogic Tau Tools Resources

Modification of the Telelogic Tau tools resources is only recommended for users who have good knowledge about the X Window System.

  1. Exit the Telelogic Tau tools.
  2. Copy the resources you wish to modify from the default resource file(s) $telelogic/X11/app-defaults/SDT and/or $telelogic/X11/app-defaults/Itex and paste them into the file $HOME/.Xdefaults, or into local files $HOME/SDT and/or $HOME/Itex, by using a text editor.
  3. Restart the Telelogic Tau tools by typing either of the following:
tau
sdt
itex

The X-resources will now be taken from the default SDT and/or Itex files. The modified resource values in .Xdefaults, SDT or Itex will then override the values from the default resource file(s).1

The system.mwmrc File

The /usr/lib/X11/system.mwmrc file is the default Motif Window Manager startup file. In this file, which contains definitions of the button bindings and the root menu, your system manager may, for instance, add a menu choice for starting the Telelogic Tau tools.

Any user can override the settings in this file by creating his own .mwmrc file in his login directory.

Note:

On Sun workstations you will find the system.mwmrc file in the Telelogic Tau distribution. This file is placed in $telelogic/X11 and is only used if you run the X Window and Motif software provided by the Telelogic Tau tools.

The app-defaults/Mwm File

The /usr/lib/X11/app-defaults/Mwm file contains the default resource specifications for Motif Window Manager. This file contains the names of the button bindings which are defined in the system.mwmrc file, mentioned above.

If you want to add resources to Mwm, you can create your own .Xdefaults in your home directory, containing your personal resource definitions.

Example 1 : Changing pointer focus policy

For example, to indicate the current window by pointing to it with the cursor, instead of clicking in the window, add the following line to .Xdefaults

Mwm*keyboardFocusPolicy: pointer

Note:

On Sun workstations you will find the Mwm file in the Telelogic Tau distribution. This file is located in
$telelogic/X11/app-defaults and is only used if you run the X Window and Motif software provided by the Telelogic Tau tools.

1

It is also possible to use the XAPPLRESDIR and XUSERFILESEARCHPATH to control X resources. Please refer to the X11 manuals for more information.


5 Licensing Management

This chapter gives you more information about the procedures for managing the licenses that are used in Telelogic Tau.

The following topics are discussed:

  • How to update and start the FLEXlm license server
  • What will happen if the FLEXlm license server goes down
  • Where you will find FLEXlm log information


FLEXlm Management Procedures

Updating the FLEXlm Server (UNIX)

Every time you edit your license.dat file to add features, replace expired FEATURE lines, etc., you must advise the "lmgrd" daemon of the changes. To do this, use the updatelicd utility:

$telelogic/bin/updatelicd

(where $telelogic is the Telelogic Tau installation directory)

Updating the FLEXlm Server (Windows)

Every time you edit your license.dat file to add features, replace expired FEATURE lines, etc., you must advise the "lmgrd" daemon of the changes. To do this, use the FLEXlm utility:

C:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex\lmtools.exe

and select the Stop/Reread tab to update your running license server with the new information.

Automatic Server Startup (UNIX)

In order to start up the Telelogic Tau tool License Server automatically at boot time, the following should be performed:

SunOS 5

  1. Copy the file $telelogic/flex/sunos5flex/sdtlmgrd to /etc/init.d/sdtlmgrd. (Where $telelogic is the Telelogic Tau installation directory.)
  2. Change the file permissions with the following commands:
chmod 744 /etc/init.d/sdtlmgrd
chown root /etc/init.d/sdtlmgrd
chgrp sys /etc/init.d/sdtlmgrd

  3. Set up the following links:
ln -s /etc/init.d/sdtlmgrd /etc/rc3.d/S17sdtlmgrd
ln -s /etc/init.d/sdtlmgrd /etc/rc3.d/K17sdtlmgrd

HP

  1. Copy the file $telelogic/flex/hppaflex/sdtlmgrd to /sbin/init.d/sdtlmgrd. (Where $telelogic is the Telelogic Tau installation directory.)
  2. Change the file permissions with the following commands:
chmod 744 /sbin/init.d/sdtlmgrd
chown bin /sbin/init.d/sdtlmgrd
chgrp bin /sbin/init.d/sdtlmgrd

  3. Set up the following links:
ln -s /sbin/init.d/sdtlmgrd /sbin/rc3.d/S17sdtlmgrd
ln -s /sbin/init.d/sdtlmgrd /sbin/rc3.d/K17sdtlmgrd

Automatic Server Startup (Windows)

The FLEXlm master daemon, "lmgrd", can be installed as a service on a Windows system so that it can be managed from the Control Panel. To install lmgrd as a service:

  1. Double-click C:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex\lmtools.exe
  2. Select Configuration Using Services.
  3. Select the Configure Services tab and fill out the paths.
  4. Select the Start/Stop/Reread tab and click Start Server.

The lmgrd is now installed as a Windows service and will be started automatically each time your system is booted. The account must have the privilege to log on as a service or otherwise the operation will fail.

Note:

Beware that when running "lmgrd" as a service, it is possible for the user to inadvertently shut down the license server by pressing the Stop Server button when running lmtools.exe from a client machine.

Manually Starting the FLEXlm Server (UNIX)

If the license server goes down for some reason (but the computer does not need to be restarted), you will have to restart the license server manually.

You can start the license server from command line. Proceed as follows:

  1. Log in on the computer where the license server is to run.
  2. Type:
$telelogic/bin/startlicd

(where $telelogic is the Telelogic Tau installation directory)

Manually Starting the FLEXlm Server (Windows)

If you have not installed lmgrd as a service on Windows NT/2000/XP, or in a Windows 98 batch file, or if the license server goes down for some reason (but the computer does not need to be restarted), you will have to restart the license server manually.

You can start the license server as an application from the Windows console with the -app option. Proceed as follows:

  1. Log in on the computer where the license server is to run.
  2. Type:
cd c:\Telelogic\SDL_TTCN_Suite4.4\flex
c:\Telelogic\SDL_TTCN_Suite4.4\flex> lmgrd -app > license.log

Adding FEATUREs to an Existing Server

Make sure you are running FLEXlm 8.0d or higher.

If your system is already using FLEXlm for general license management it is sufficient to add any VENDOR and FEATURE lines you receive in a license file from Telelogic Customer Support to your existing license.dat file.


If the FLEXlm Server Goes Down

In some cases, the Telelogic Tau tools may lose contact with the license server. This could happen, for instance, if there is a communication failure in your network, or if the license control processes terminate for some reason. A recovery mechanism is provided - currently running sessions of the Telelogic Tau tools will only have to wait for the license server to come up again. (They will not have to perform any special operations.)

Losing Contact with the License Server

From a Telelogic Tau user's point of view, the following will happen if the license server goes down:

  • Telelogic Tau tool disables the Organizer's menu commands. Some other functionality which is managed by the Organizer is disabled as well. It is however possible to finish the current session (saving and printing diagrams for instance).
  • The license failure is reported in the Organizer Log window.

Regaining Contact with the License Server

When the license server comes back up, the Telelogic Tau tools can be used again. Users are notified by a message in the Organizer Log window and the Telelogic Tau tools resume normal functionality.


FLEXlm Event Logging

On UNIX: All events that lmgrd administrates are logged in a file named license.log, available in the $telelogic directory. (Where $telelogic is the Telelogic Tau installation directory.)

In Windows: When the license server has been installed as a service on Windows NT/2000/XP (see "Updating the FLEXlm Server (Windows)" ) all events that it administrates are logged in a file named lmgrd.log, available in the system32 directory. For Windows 98, you can specify the directory and file name for the log file, by using the `>' sign (see "Automatic Server Startup (Windows)" ). Our default location is
c:\Telelogi c\SDL_TTCN_Suite4.4\fle x\wini386flex\license.log

The events logged include:

  • Startup and shutdown of the license server
  • Checking in and checking out licenses
  • Denying licenses

Each event involving a license also specifies:

  • The corresponding Telelogic Tau tool (license controlled tools only)
  • The user
  • The node
  • The date and time
  • The usage time (for check-in log entries)

Note:

The log file will grow as users run Telelogic Tau. You may consider deleting the head of the file from time to time to save disk space.


6 A Primer on Licensing

This chapter introduces the licensing system used in Telelogic Tau. Provided are both background material and practical tips on setting up and maintaining your licenses.

The following topics are discussed:

  • A general overview of the FLEXlm licensing system.
  • Details about the FLEXlm system, including types of licenses, usage options and possibilities, structure of a license key and pitfalls to avoid.


Telelogic Tau Licensing - A General Overview

The FLEXlm Licensing System

FLEXlm, made by Globetrotter Software, provides either a node-locked or network-based "floating" license system. This system allows users on a network to check out individual licenses from a common shared set. When a user ends a software session, all licenses used by that session are returned to the pool of available licenses. The system is available for both the UNIX and Windows versions of Telelogic Tau. It is possible to share licenses between the platforms; that is, both UNIX and Windows users can share licenses from the same common shared set.

The licensing system is introduced in detail below. You should have received your licensing materials with your delivery of Telelogic Tau.

If you have not yet received your license materials, or, if after reading this chapter you have questions, contact Telelogic Customer Support (see "How to Contact Customer Support").

Expirations and Renewals

The FLEXlm licensing system uses license keys which have individual expiration dates set by Telelogic, and can be renewed when needed.

Typically, license keys given for evaluation of the tool set are set for 30 days, renewable upon request and with approval from the appropriate Telelogic Area Manager.

Post-purchase license keys are typically set for one year, and are renewed. Customers with maintenance agreements will receive updated license keys for new versions of the tool upon their release. Customers without maintenance agreements will receive renewed keys for the version of Telelogic Tau that they initially purchased (that is, license keys for newer, up-to-date versions of Telelogic Tau will not be delivered).

Speak with your Telelogic Area Manager for further details on license renewals.

Licensing by Feature

Licensing is done by "features", which are individual components of the Telelogic Tau tool set, such as the SDL Simulator or the TTCN suite's TTCN to C compiler.

A license key specifies the number of "seats" (simultaneously available licenses) for each feature of the tool set listed in the license key. FLEXlm (floating) licenses allow the number of licenses available to be specified on a feature-by-feature basis.


FLEXlm Licensing Details

General Information About FLEXlm

FLEXlm can either provide node-locked (dongle) or a network licensing system which consists of one or several license keys, license server "daemons", and the application(s) for which licenses are served. Licenses dynamically float around the network as needed.

The license "daemons" are background processes which run on a chosen "license server" machine. They administer the check-in and check-out of licenses for each feature of each application which uses FLEXlm.

Each machine on a network has two attributes which distinguish it uniquely from all other machines: the hostname and hostID. Host names are usually straightforward names for machines given by, perhaps, a system administrator. Examples are "einstein" and "suns20". The hostID is a number that uniquely identifies the machine and is obtained from different sources within a machine depending on the architecture. Examples are "80874ab9" (typical Sun style) and "080009734a85" (typical HP style).

There is one main FLEXlm daemon called "lmgrd", and one "vendor" daemon for each vendor whose software on the system uses FLEXlm. Telelogic's vendor daemon is simply called "telelogic". The "lmgrd" daemon will manage the vendor daemons, which in turn manage the licenses for their respective vendors' software. The "lmgrd" daemon and the vendor daemon(s) must run on the same physical node of the network, but they can run on any node; that is, you can choose any node on your network to be the FLEXlm license server.

A FLEXlm license key is a specially formatted text file containing:

  • Information about the machine on which the license daemons will run (the hostname and hostID).
  • The UNIX path information for the vendor daemon(s).
  • A line for each feature in the tool set of the vendor(s) which specifies the number of available licenses and the expiration date for that feature.

Details of the structure of a FLEXlm license key are covered below.

Types of FLEXlm Keys

FLEXlm license keys can come in three categories: "license keys", "evaluation license keys", and "DEMO license keys".

Both "license keys" and "evaluation license keys" require a valid hostname and hostID and require that the "lmgrd" and vendor daemon are correctly running on the license server specified in the license key file. The only difference between them is their durations; evaluation keys, of course, last for a much shorter time than "real" post-purchase keys.

"DEMO license keys" are used in uncommon situations when it may be difficult or impossible to obtain a proper hostname and/or hostID. This type of key does not require a specific hostname and hostID, nor does it require that the license daemons be running. This type of key is distinguished with the keyword "DEMO" appearing at the end of each feature line of the license key file. Also, the field in each feature line showing the number of seats is set to zero, although the feature can still be used. This type of key is typically reserved for emergency situations.

License keys for Telelogic training sessions will typically be evaluation license keys with very short durations (perhaps 5 days or so).

Installation and Network Possibilities

It is not necessary to install your Telelogic Tau software on the same node of the network that your license server runs on, although this is a common situation. You could install Telelogic Tau on a local disk and have your licenses served by another node on the network (to put it differently, you do not have to install Telelogic Tau on a disk that belongs to the same machine on which the license server will run). This is useful in situations when one member or a small part of a large organization will be using Telelogic Tau exclusively, but there is already an organization-wide FLEXlm license server on the network.

Since FLEXlm is designed for the possibility to manage many software packages from many vendors, it allows all license and daemon information for all vendors to be combined into one license key text file, instead of having to deal with a separate file for each vendor. If you already use FLEXlm for other software when you install Telelogic Tau, our Installation Guide will tell you how to add the license information you receive from Telelogic to your master license key text file.

If Telelogic Tau brings you to FLEXlm for the first time, then you will have only the "lmgrd" and "telelogic" daemons running, and the license key information you receive from Telelogic will make up your entire license key text file.

We suggest using the FLEXlm software included in the Telelogic Tau CD-ROM; for first time FLEXlm users this is of course what you will do. Existing FLEXlm users, however, may wish to upgrade their license server software with the Telelogic Tau-included version, if they are running an older version. Although this will cause a temporary interruption in availability for all FLEXlm administered software, it is a good idea since newer versions of the system are quite different. Although Telelogic keys are always backwards compatible, we cannot speak for other vendors, so it is generally best to make sure you run the latest daemons so as to be able to take advantage of new FLEXlm features.

Structure of a FLEXlm License Key

On the following pages we give two examples of typical FLEXlm license keys as they appear when received from Telelogic. The first is a "real" license key (one requiring a valid hostname and hostID) and the second example is a DEMO key. Each example describes the "anatomy" of the license key. Being familiar with the different parts is very useful when trying to install the key properly.

Note:

The license keys you receive may contain additional or slightly different information compared to the descriptions on the following pages.

When installed, the license key text file received from Telelogic should be saved with the filename license.dat. While this is not strictly necessary, some startup scripts may search for the license file using this name. This name is the standard in the FLEXlm "lingo" anyway.

Note:

The default location for the license.dat file on UNIX is $telelogic/license.dat; i.e. the Telelogic Tau top-level installation directory. In Windows 98, NT, 2000 and XP, it is C:\Telelogic\SDL_TTCN_Suite4.4\license.dat.

FLEXlm License Key - First Example

Here is a FLEXlm "real" license key as it would appear when delivered by Telelogic.

Example 2 : "Real" license key

SERVER test 12345678 7598
VENDOR telelogic /usr/appl/telelogic/flex/archflex
FEATURE Telelogic telelogic 3.400 15-dec-99 2 1B5890E1960AFE22A57B ck=116
FEATURE SDT-Base telelogic 3.400 15-dec-99 1 0B58E0922F3034C3C29F ck=89
FEATURE SDT-MSCE telelogic 2.200 15-dec-99 1 AB58C08192E26573643B ck=133
FEATURE SDT-OME telelogic 1.100 15-dec-99 1 DBC8C061034073C86AD4 ck=68
FEATURE SDT-Cbasic telelogic 2.200 15-dec-99 3 DBC322E12E1F4E6A7DC9 ck=124
FEATURE SDT-Simulator telelogic 2.200 15-dec-99 1 5BA830E2597AAED4E6DF ck=48
FEATURE SDT-Validator telelogic 2.200 15-dec-99 1 5BB3F0A11CDD96D4C1FF ck=182
FEATURE SDT-TTCN-Link telelogic 1.200 15-dec-99 1 DBB87061BDA40AF3D222 ck=154
FEATURE TTCN Framework telelogic 3.300 15-dec-99 1 FBF53071C228F9AF0CA7 ck=112

Here are detailed explanations for this license key example:

  • SERVER line: This line has 4 fields; the SERVER label, the hostname and hostID of the machine on which the license daemons will run, and a TCP/IP port number. Here we see that the machine test has hostID 12345678. The TCP/IP port number is 7598, which is the port number on which the license daemons will communicate.
  • VENDOR line: This line has 3 fields; the VENDOR label, the name of the vendor daemon (in this case telelogic), and a field to hold the path to the vendor daemon executable. In this case, the path is a "dummy" path generated by default when the license key is made. When you install your key, you must supply the correct path, which depends on your choice of installation directory and architecture. See "FLEXlm Licensing Pitfalls to Avoid" for additional information.
  • FEATURE lines: It is here that the actual permissions are specified for each component of Telelogic Tau that the customer has. A FEATURE line has eight fields:
    • The FEATURE keyword.
    • The name of the licensed component.
    • The name of the vendor daemon responsible for handling the feature (in all Telelogic Tau cases this is telelogic).
    • The version number of the feature.
    • The expiration date (inclusive) of the license for the feature.
    • The number of licenses or "seats" available for that feature.
    • A 20-character (hex) encryption code for the FEATURE line; this is determined by the exact character-by-character makeup of the FEATURE line, and by the hostID of the license server, specified on the SERVER line.
    • A double-quoted field which can contain a "note" for the line.

Caution!

Licenses delivered from Telelogic have a brief label for the key (company name/contact person, etc.) usually in the quote field of the first FEATURE line only. All FEATURE lines after the first will have nothing between the quotes. This does not have to be the case in general; any number of FEATURE lines can have something in the quotes. It is possible that sometime you might receive such a key from Telelogic. Do not delete any such information in quotes; this will invalidate the FEATURE line.

FLEXlm License Key - Second Example

Here is a FLEXlm DEMO license key as it would appear when delivered by Telelogic.

Example 3 : DEMO license key

SERVER hostname hostid 7598
VENDOR telelogic /usr/appl/telelogic/flex/archflex
FEATURE Telelogic telelogic 3.400 15-aug-98 0 4BF862B1049767F837DE ck=116 DEMO
FEATURE SDT-Base telelogic 3.400 15-aug-98 0 0B98B051C0144041B74C ck=89 DEMO
FEATURE SDT-MSCE telelogic 2.200 15-aug-97 0 EB98B0F1BF88E260FE2A ck=133 DEMO
FEATURE SDT-OME telelogic 1.100 15-aug-97 0 7B58E0C15A7D37B767B4 ck=68 DEMO
FEATURE SDT-Cbasic telelogic 2.200 15-aug-97 0 3BAB8081FEC65F761608 ck=124 DEMO
FEATURE SDT-Simulator telelogic 2.200 15-aug-97 0 8B28405166A00320F584 ck=48 DEMO
FEATURE SDT-Validator telelogic 2.200 15-aug-97 0 0B9810F1EB7103F3EA94 ck=182 DEMO
FEATURE SDT-TTCN-Link telelogic 1.200 15-aug-97 0 FB5820C123607B34A759 ck=154 DEMO
FEATURE ITEX-Base telelogic 3.300 15-aug-97 0 EBB8F0B71216A0C373E6 ck=112 DEMO

Here are detailed explanations for this license key example:

  • SERVER line: This line has 4 fields; the SERVER label, two dummy placeholders for where a specific hostname and hostID would be placed in a "real" key, and a TCP/IP port number. Of course the port number is irrelevant, since with a DEMO key no license daemons need to be running, and thus do not need a port on which to communicate.
  • VENDOR line: This line has 3 fields; the VENDOR label, the name of the vendor daemon (in this case telelogic), and a field to hold the path to the vendor daemon executable. The path is again a "dummy" when you get your key from Telelogic Customer Support, but you will not need to put in the correct path for the telelogic daemon since the master lmgrd daemon never needs to start it - neither daemon needs to run when you use a DEMO key.
  • FEATURE lines: These are very similar to the FEATURE lines in a "real" key, except for the addition of the word DEMO at the end of each. Also, the number of seats available is set to 0 (zero) on each FEATURE line. This is merely an implementation that "tricks" Telelogic Tau into allowing you to run the software even though the FLEXlm system is not operational. As before, the quoted field of the first FEATURE line will contain some text describing the license key (customer name, perhaps a contact person's name, etc.). All FEATURE lines after the first will have nothing between the quotes. Note, however, that the encryption codes are still valid for a DEMO key.
    The number of licenses specified for some features is dependent on the number specified for certain others. For each seat of the SDT-Simulator, SDT-Validator, and SDT-TTCN-Link features, there should be one seat of the SDT-Cbasic feature. For each SDT-Base or TTCN Framework, there should be one Telelogic feature (which is the Organizer). So, for example, a customer who has 3 each of the SDL Simulator, Validator, and TTCN-Link should have 9 seats of Cbasic. A customer with 3 SDL Framework licenses and 2 TTCN Framework licenses should have 5 Organizers.

FLEXlm Licensing Pitfalls to Avoid

When installing a new FLEXlm license key from Telelogic there are a few "pitfalls" to watch out for:

  • Since FLEXlm license keys are text files and are often sent to customers via email, usually some line wraparound occurs during the transmission. Recall that each FEATURE line has a unique encryption code as its seventh field. When a line wraps, this introduces a newline character into the FEATURE line and invalidates the encryption code. To check for wraparound, make sure that each FEATURE line begins with the keyword FEATURE and ends with a double-quote field (remember the first FEATURE line will have the customer name in this field).
  • FLEXlm license files are case significant.
  • It is easy to forget to put the full path to the "telelogic" daemon in the VENDOR line. This must be done when the license daemons are running on a UNIX machine, and depends on the choice of Telelogic installation directory and machine architecture. The correct path is not specified when you receive your key since your installation directory is not known to Telelogic Customer Support. A correct example for a SunOS 5 machine with Telelogic Tau installed in /appl/telelogic would be:
/appl/telelogic/flex/sunos5flex/telelogic

On a Windows machine, if you use the FLEXlm software included with Telelogic Tau (i.e. you are not adding your FEATURE lines to a preexisting server) it is not necessary to specify the exact path (although you can, if you want to be thorough). Since both daemon executables are in the same directory within the Telelogic Tau installation (\flex), the "lmgrd" master daemon can find the "telelogic" vendor daemon to start it up even when the path is unspecified:
VENDOR telelogic telelogic.exe

This is how the VENDOR line looks when the license key comes from Telelogic Customer Support since your choice of installation directory is unknown to us. A full path example (with the default case of \Telelogic\SDL_TTCN_Suite4.4 on the C: drive as the installation directory) is:
VENDOR telelogic C:\Telelogic\SDL_TTCN_Suite4.4\flex\wini386flex\telelogic.exe

If for any reason you move the "telelogic" daemon from its normal place (\Telelogic\SDL_TTCN_Suite4.4\flex) or if you make use of a preexisting FLEXlm server you must specify the complete path to it.
  • An uncommon problem is a TCP/IP port conflict with another application (recall that the last field of the FLEXlm license key's SERVER line is the TCP/IP port number). An error message will be logged in the license.log file if the conflict occurs. You can change the port number without invalidating your key. While this is purely a trial-and-error affair, as a "rule of thumb", numbers above 5000 (but below 20000) should not cause conflicts (most applications use numbers below port number 5000). Port number 7598 is often the "default" found in keys delivered by Telelogic.
  • Often customers whom for whatever reason need to use a DEMO license key believe that they must enter their actual machine hostname and hostID in place of the dummy hostname and hostid found in the key delivered from Telelogic Customer Support. This is not the case. The encryption codes for each FEATURE line are actually generated based on a hostID value of "hostid", so inserting your actual hostID will invalidate the key.
  • If the FLEXlm manager cannot find your dongle ID, check that the sentinel drivers are installed. They are located in D:\Flex\Win32\FLEXID8 on the Telelogic Tau CD.

Additional Information

For direct-from-the-maker information on FLEXlm, including a FAQ (Frequently Asked Questions) document and the FLEXlm End User Manual, we suggest the following World Wide Web addresses at Globetrotter Software:

http://www.globetrotter.com/flxlmfaq/TOC.htm
http://www.globetrotter.com/manual.htm


Telelogic Tau 4.4

Release Guide

© 2002 by Telelogic AB. All rights reserved.

Terms of use

Telelogic grants you the right to use the Program on one computer or in one local computer network at any one time. The Program and the enclosed written material are owned by Telelogic and are protected by national copyright laws and international copyright treaties. This License does not convey to you an interest in or to the Program and the enclosed written material, but only a limited right of use in accordance with the terms of this License.

No part of this written material may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language in any form except as provided in this License.

Telelogic does not warrant that this written material will meet your requirements or that the operation of the Program will be according to this written material, uninterrupted and error free. You are solely responsible for the selection and operation of the Program to achieve your intended results and for the results actually obtained.

Information in this written material is subject to change without notice.

Trademarks

Telelogic and Telelogic Tau are registered trademarks of Telelogic AB
DOORS and CM Synergy are trademarks of Telelogic AB

All other names of products, companies and services mentioned are trademarks or registered trademarks of their respective holders.

Credits

The IBM XML Parser for C++ Edition is incorporated in Telelogic Tau.

Credits to OBJ System, Italy.

GMP Library

Telelogic Tau uses the GNU Multiple Precision (GMP) library. The use of the GMP library is controlled by the GNU Lesser General Public License (LGPL). A copy of the GNU LGPL text is available in the installation of Telelogic Tau in the file gnu/lesser.txt and also at http://www.gnu.org/copyleft/lesser.html

About GMP

To enable extended support for large integers, Telelogic Tau uses the GNU Multiple Precision (GMP) library. GMP was originally developed by staff working for SWOX AB. GMP is provided under the terms and conditions in the GNU Lesser General Public License (LGPL). The installation of Telelogic Tau includes a GMP Library that is dynamically linked, so there is no need for you to take further actions to have Telelogic Tau use GMP in a proper way.

Support

Please note that GMP is not covered by the Support and Maintenance Agreement for Telelogic Tau. Although Telelogic has thoroughly tested GMP and our conclusion is that it complies to high quality standards and should meet the expectations from software professionals, Telelogic does not support GMP. Should you have any enquiries, requests, or want to report anomalies or bugs in GMP, you should do so by e-mailing to bug-gmp@gnu.org

How to report bugs on GMP is described at http://swox.com/gmp/manual/Reporting-Bugs.html

Version

Telelogic Tau 4.4 uses version 4.0.1 of GMP. Should you want to update, modify or upgrade the GMP Library used by Telelogic Tau, need access to documentation, or simply read more about GMP, we recommend that you visit the GMP home page at http://swox.com/gmp

How to build GMP

Telelogic has built GMP using the default build configuration and makefiles that came with GMP 4.0.1.


How to Contact Customer Support

The Help Desk is the single point of contact for all support related communication regarding the Telelogic Tau products:

  • Telelogic Help Desk at our offices.
  • Distributor Help Desk if you have received the Telelogic products from a local distributor.

Contact the Help Desk if you:

  • need to obtain a License Key or other licensing materials.
  • have questions, suggestions or problems related to the installation, setup or performance of the Telelogic Tau software.
    Try to provide the following information:
    • Telelogic Tau product version (e.g. 4.4, 4.3, etc.)
    • Operating system (e.g. Solaris 2.5.1, Windows NT 4.0, etc.)
    • Module or tool (e.g. SDL Editor, on-line help, etc.)
    • Compiler, if applicable (e.g. Borland C++ 5.0, Sun cc, gcc, etc.)

The address to the Telelogic Help Desk can be obtained from the Telelogic home page on the World Wide Web:
http://www.telelogic.com/support
This option is also available in the Help menu in the Organizer.


Telelogic Tau Documentation

The complete user documentation for the Telelogic Tau products is available on-line. Selected parts are delivered in printed format.

On-Line Documentation

The on-line documentation consists of HTML files, which are included in the Telelogic Tau CD-ROM distribution.

The HTML files can be accessed from the Telelogic Tau software as a result of a context-sensitive help request. This requires that an on-line help viewer has been installed and set up properly.

Printed Documentation

The printed documentation consists of a collection of wire-bound books.

The printed documentation as well as the online documentation is available in PDF format on the Telelogic Tau 4.4 CD. Use them for quick viewing or printing selected parts of the documentation.

Contents of the Included Volumes

The following volumes are included in the Telelogic Tau documentation:

  • Installation Guide:
    Describes the installation of the Telelogic Tau software, how to configure the computer environment, and how to handle licensing.
  • Release Guide (this volume):
    General information about the product release, new features, limitations, and compatibility issues. Compatibility is described between Telelogic Tau 4.4 and previous versions, and also between the languages supported in Telelogic Tau and the published standards of these languages.
  • SDL Suite Methodology Guidelines:
    Practical guidelines on how to use SDL and related notations in software development using the SDL suite. The SDL-92 object oriented concepts are described as well as handling of data types.
  • TTCN Suite Methodology Guidelines:
    Describes a methodology that will assist you in taking advantage of the TTCN language in a TTCN suite environment. The TTCN language, concepts and data types are described.
  • SDL Suite Getting Started:
    Introduction to the SDL suite, and the supported languages and notations. By reading and practising the included tutorials, you will get more familiar with the basic SDL suite tools.
    This volume will also assist you in getting familiar with the SOMT method and Cmicro targeting. Lectures are combined with practical exercises.
  • TTCN Suite Getting Started:
    Introduction to TTCN and the TTCN suite, as well as tutorials on the TTCN suite tools that will help you in getting familiar with the TTCN suite.
  • User's Manual:
    Reference information and guideline material about all Telelogic Tau tools and features. All windows, dialogs, menus, commands, files, storage formats, options, etc. are described. There are also guides on how to use the tools and perform various tasks.


Typographic Conventions

This section describes the typographic conventions used in all volumes of the Telelogic Tau user documentation.

Menu Commands and UI Objects

Telelogic Tau user interface objects, such as labels, menu names, menu items and button texts, are shown in italics:

The Edit menu provides a Paste command ...
Click the OK button ...

Menu commands can also be expressed in a single form by separating the menu, submenu and menu item by a `>' character:

Select Edit > Paste to ...
The command Tools > Link > Traverse is used for ...

File Names, Variables, etc.

Names of files and directories, variables, source code literals, file keywords, etc. are usually shown in a typewriter font :

The sdt.ssl file ...
Set the $telelogic variable ...

Textual Input/Output, Listings, etc.

Listings of source code, file contents and textual output from the computer is shown in a typewriter font:

State1:
Sig1:INPUT
Sig2:SAVED
State2:
Sig3:INPUT
Sig1:UNHANDLED

When you are asked to type in characters from the keyboard during an interactive session, a bold typewriter font is used:

Now enter Convert, Demon, System
C:\Telelogic\SDL_TTCN_Suite4.4> mkdir example

Placeholders

Information within angle brackets "< >" denotes symbolic names (placeholders) which should be replaced by actual names:

The syntax is "<process instance> <variable name>" ...

Keys

Special keys or key combinations are shown in a typewriter font within angle brackets. Keys to be pressed together are separated by `+':

To execute the command, press <Return> ...
Press <Ctrl+C> to ...
The shortcut is <Ctrl+Meta+V> ...

Platform Differences

The Telelogic Tau documentation is common to both UNIX and Windows. The differences that exist between the platforms are usually indicated in the text by a platform indicator (a bold, sans-serif font) which always contains the word UNIX or Windows. Examples:

The information is stored in the file .sdtpref (on UNIX) or sdt.ini (in Windows).
XYZ consists of the following:
  • Alpha
  • Beta (UNIX only)
  • Gamma
  • Delta (Windows only)
  • Etc.

If a complete section of text is platform specific, the platform is indicated in the section heading:

Performing the Operation (on UNIX)

Performing the Operation (in Windows)

Screenshots are shown in either a UNIX or Windows version. Even if the appearance and layout may differ slightly between the platforms or different screen setups, the functionality is identical.


1 Compatibility Notes

In this chapter you can read about compatibility issues between the Telelogic Tau 4.3 release and the 4.4 release, as well as between the 2.3 release and the 3.X releases. It also describes the compatibility issues for the supported languages in the SDL suite.

This chapter concentrates on issues of storage formats and language support. For the TTCN suite, this chapter describes how to upgrade an old TTCN suite database, and how to open a TTCN suite database with an old version of the TTCN suite.

For information regarding platform and product compatibility, see "Telelogic Tau Compatibility Matrix and "Build and Certification Matrices.


Licensing Compatibility

FLEXlm License Keys

Telelogic Tau 4.4 is using the 8.0d version of FLEXlm.

The FLEXlm Product License Keys that come with the Telelogic Tau products in version 4.4 - 3.1X and 3.02 are not compatible with license keys used in versions earlier than 3.02 of ITEX and SDT.

This means that you cannot run earlier versions of ITEX and SDT (i.e. 3.0 and 3.01) using the FLEXlm FEATURES in the license.dat file in the Telelogic Tau 4.4 distribution.

If you want to be able to switch between versions 3.0/3.01 of ITEX and SDT and version 4.4 of Telelogic Tau, you must do as follows:

  1. Save the existing (3.0 / 3.01) license.dat file before updating it with the new FEATURES that come in the 4.4 Product License Key from Telelogic Customer Support.
  2. Assign the environment variable LM_LICENSE_FILE a value that designates the appropriate license.dat file before starting the tool set.

Telelogic Tau 3.2 and later versions use the same license feature names both on UNIX and in Windows. This was not true for SDT and ITEX of versions 3.1X and earlier.

You may experience some problems trying to get the Windows version 3.1X of ITEX and SDT to run together with later versions. If so, please contact Customer Support for help (see "How to Contact Customer Support" in this volume).

Note:

FLEXlm packages can only be handled by 3.1 and newer versions

FLEXlm License Daemon

Telelogic Tau 4.4 comes with version 8.0d of the FLEXlm license daemon (lmgrd). If you are using FLEXlm licensing for other products than Telelogic Tau, or if you plan to use two different versions of Telelogic Tau in parallel, you must use the latest version of the FLEXlm license daemon that you have received (version 8.0d or later).

For more information, see the FLEXlm FAQ at http://www.globetrotter.com/flxlmfaq/chap3.htm


File Name Compatibility

The following text concerns file name compatibility between UNIX and Windows using the Organizer in Telelogic Tau 3.3, 3.4, 3.5 and 3.6, as compared to earlier versions. Therefore, it does not apply to ITEX tools in Windows.

Windows/UNIX Compatibility

The preference SDT*MixedPlatform (used in Telelogic Tau 3.2 and earlier versions) is no longer read by the Organizer. For systems using only relative paths, the Organizer now automatically converts file names between UNIX and Windows syntax, i.e. exchanging slashes and backslashes. The system file is always written in the format native to the platform used. Before version 3.3, the system file was always written in UNIX format.

For file names using absolute paths, the functionality of the Organizer's PC Drives dialog was extended in 3.3 to support general Windows paths instead of only drive letters, UNC paths (\\hostname\path), and quoted paths containing spaces. Files with absolute paths not found in the PC Drives dialog are presented in the Organizer as invalid diagram icons.

The special feature of always converting files to lowercase that the MixedPlatform preference used to provide must now be enabled separately, using the preference SDT*UseLowerCaseInFileNames. This means that it is now possible to share systems between UNIX and Windows without forcing file names to lower case.

It is now possible to make Telelogic Tau handle file names containing spaces. This feature has to be explicitly turned on as the possibility of using this feature may depend on the support for spaces in file names in other tools and executables integrated with Telelogic Tau. Support for spaces in file names is controlled by the preference SDT*AllowSpaceInFileNames.

To Avoid Problems

If you are sharing systems between UNIX and Windows, and want to manipulate system files without using the Organizer, do not assume that paths are always written in UNIX format.


Storage Format Compatibility

System Files

The file format for system files (.sdt) has changed in Telelogic Tau 4.4 as compared to Telelogic Tau 4.3. Telelogic Tau 4.4 can read older system files (3.0X - 4.3), but previous versions of Telelogic Tau cannot read the new 4.4 system files.

When saving older system files with the Telelogic Tau 4.4 Organizer, a conversion to the new 4.4 format is performed.

SDL/GR and MSC/GR

The storage format for SDL diagrams did change in 4.1. This means that diagrams created with 4.1 cannot be opened in previous versions. SDL Suite 4.1 can still read all previous formats.

The storage format for SDL diagrams did change in 4.0. This means that diagrams created with 4.0 cannot be opened in previous versions.

The storage format for SDL and MSC diagrams did change in SDT 3.1X as compared to SDT 3.0X (and SDT 2.X). SDT 3.1X and later versions of Telelogic Tau can read older files, but previous versions of SDT cannot read the new format introduced in the 3.1X version.

In addition, the storage format for MSC diagrams was changed in version 3.5. Version 3.5 and 3.6 of the MSC Editor can handle the same formats as version 3.4 of the editor, but version 3.4 and earlier of the MSC Editor cannot read the new MSC format.

SDL and MSC diagrams stored in SDT 2.X and SDT 3.0X format may be opened as is into SDT 3.1X and later versions of the editors (using commands such as the SDL Editor's Open). To preserve the original diagram structure, you must however import them into the Organizer, by using the command Import SDL to build a diagram structure that may be stored on a system file.

When saving the opened SDT 2.X or 3.0X diagrams on file with SDT 3.1X and later versions of the editors, a conversion to the 3.1X format is performed. Conversion to the 3.1X format may also be performed automatically when importing the diagrams into the Organizer. The option Save imported diagrams in SDT 3.X format is used for this purpose.

Caution!

It is not possible to open files in the SDT 3.1X format in previous versions of SDT, e.g. SDT 3.0x or SDT 2.3, or to open MSC diagrams in the new 3.5 format in previous versions of the MSC Editor. Make sure you have backup copies of your diagrams.

Generated SDL Simulators and Validators

Simulators and validators should be generated with the same version of the SDL suite as they are supposed to be executed in. They might not execute as expected when executed under a SDL Simulator Graphical User Interface of a different version. To re-generate, use the Full Make facility to make sure all C files are re-generated properly.

The SDL/GR trace in the SDL Editor requires the SDL diagrams to be saved in order to function properly. (The reference mechanism in SDT 3.X assumes the existence of information that is not stored in SDT 2.X files.)

Deployment Diagrams

The 4.2 Deployment Diagram file format (*.sdp) was extended. The 4.2 Deployment Editor can read and convert .sdp files created with older versions of the Deployment Editor. However, older Deployment Editor versions can not read diagrams created with this new version.

In the 4.1 release, the Deployment Diagram file format (*.sdp) was extended. The Deployment Editor in the 4.1 release can read and convert .sdp files created with older versions of the Deployment Editor. However, older Deployment Editor versions can not read Deployment Diagrams created with the 4.1 version.

Buildscript generation is no longer supported by the Deployment Editor since the 4.1 release. Buildscripts are replaced by a feature which translates Deployment Diagrams into the Partitioning Diagram Models, which are used by the Targeting Expert. This makes it possible to utilize a partitioning configuration in a Deployment Diagram when building SDL systems using the Targeting Expert.

As buildscript generation is no longer supported, build settings on node and component level are ignored when an old Deployment Diagram is converted into 4.1 format. Qualifier data on object level is automatically translated.

The TTCN Suite Database Compatibility

This section describes the different versions of the ITEX database formats and how they are converted to each other. The following table shows the what formats are used in each ITEX version:

ITEX version | Database version | Description
2.0, 2.1 | 0 | Base version.
2.2 | 1 | This version stores additional analyzer info.
3.0x | 2 | Corrected order of DefaultsRef and Configuration in TestCase.
3.1x | 3 | Support for Modular TTCN and encoding/decoding added. Changed to the compound format containing both the structure and the tables.
3.2, 3.3, 3.4, 3.5, 3.6, 4.0 | 4 | Store some additional analyzer info and also restructured the content a little.
4.1, 4.2, 4.3, 4.4 | 5 | Changed parse data structure.

The Database Upgrade

When the TTCN suite opens an old database, it checks if it is possible to convert the database to the current version via the TTCN suite TTCN-MP format. A conversion program for this old database version must be available. The name of this program has a suffix which indicates the version number of the database. For example the program which is used to convert a database of version 4 is called mp-output-old4.

This program is installed in the TTCN suite 4.4 release. It is used to convert databases of version 4 to MP format. The resulting MP file is then converted to GR format as usual. This mechanism solves the problem of backward compatibility. The TTCN suite or a newer TTCN suite version can open an old version of the TTCN suite database.

Forward Compatibility

A special problem occurs when an old ITEX version needs to open a new version of the ITEX database (forward compatibility). This problem is not relevant between database versions 0, 1 and 2 since the transfer format (MP) is the same. But the MP format which is used in 3.1 and later releases have extensions. Another problem occurs because the 3.1 and later databases are stored in a single file (compound format) with extension .itex instead of the .itex/.itex-tables combo of previous versions.

In the TTCN suite 4.4, the database contains documents of one of these types:

  • Test suite
  • Modular test suite
  • Module

Conversion of a new database of type Module to an old 3.0x or earlier database is not possible. The only forward compatibility which is supported is for the databases of type Test Suite or Modular Test Suite.

This conversion mechanism is possible to retrofit into an older existing 3.X installation by copying the programs mp-output-old5 and
convert-to-old5 from the 4.4 installation's binary directory for the architecture(s) installed and put these copied files into the corresponding directory in the old 3.X installation tree (these files are present in the current release for primarily this reason).

To make a 3.0x version able to convert from 4.4 databases it also needs the companion file with the extension .itex-tables to exist beside the 3.6 database file. Fortunately this file may be a dummy file containing nothing at all.


Application Programmers Interface

Telelogic
http://www.telelogic.com


Code Generation Compatibility

The default way of generating code for SDL operators was changed in Telelogic Tau 4.2. This method replaces generated functions for assignments, equal test, free and predefined operators in generators with generic functions.

This means that parameter passing has changed. Parameters are passed as addresses not as values, and data structures describing the data types are needed.

This method is backward incompatible with SDL systems that uses inline C code. The function calls must be manually changed.

An old-style code generation for SDL operators option is available, enabling compatibility with SDL operator code generation of previous Tau releases.


Compatibility with ITU SDL

The SDL language support in the SDL suite includes nearly all of SDL'92, as defined in the ITU-T Z.100 recommendation.

The main divergencies between SDL supported in the SDL suite and the Z.100 recommendation are:

  • The concept of a generic system is only partially supported.
  • Macro calls are only allowed within flowchart diagrams.
  • The names of diagrams and diagram pages must conform to the lexical rules of SDL, except that spaces are not allowed.

More detailed limitations can be found in "SDL Restrictions" and "SDL Editor" .

The SDL Editor supports a few extensions to the SDL/GR notation:

  • An additional heading symbol, intended for defining inheritance, specialization, formal parameters, signalsets, etc.
  • An operator reference symbol, making operators visible in the SDL structure handled by the Organizer.

The SDL suite supports several new SDL concepts, some of which are defined in an addendum to the latest Z.100 Recommendation, known as SDL-96, and some others which are Telelogic-specific extensions to SDL. The extensions are supported in all relevant tools.

SDL-96 Extensions

  • Remote procedures on channels and signal routes: This extension allows names of remote procedures to be put in signal lists of channels and signal routes. This has the main advantage that it enables processes to call remote procedures implemented in the environment of the SDL system, and also the other way around; remote procedures can be called from the environment of the SDL system.
  • External procedures: External procedures are called like normal SDL procedures, but they are implemented in the target language (C). This makes it easier to use C functions in SDL.
  • External operators: External operators are called like normal SDL operators, but they are implemented in the target language (C). This makes it easier to use C functions in SDL.

Other SDL-96 features are not supported in the SDL suite.

Telelogic-Specific Extensions

The following extensions to SDL are Telelogic-specific. A detailed description of these extensions can be found in 2 Data Types and Using SDL Extensions.

  • Choice: With this construct you can define types with values where only one of a number of components can be present. Choice types replace the #UNION code generator directive (although #UNION is still supported for backward compatibility reasons).
  • Optional/default components in structs: It is now possible to specify that fields of struct types are optional, or have a default value. This feature is useful in the design and implementation of protocols.
  • Size constraints: With this construct it is possible to define types that should have a limited length.
  • Bit fields: Integer fields in struct types can be specified as bit fields, very similar to C. This is useful when reusing C data types that contains bit fields in SDL.
  • Z.105 types and generators: The following new predefined data types and generators from Z.105 have been added: Bit, Bit_String, Octet, Octet_String, Object_Identifier, IA5String, NumericString, PrintableString, VisibleString, Null, and the Bag generator.
  • Powerset operators: Powerset has been extended with Length and Take operators, which make it possible to iterate over powersets and thereby make powersets more useful.
  • Pointers: There are syntactic extensions that make it easier to work with pointers in SDL. In order to use pointers, the Ref generator from the package ctypes should be used.
  • Own and ORef: The generators Own and ORef support safe pointers, making it possible to speed up applications by sending pointer values instead of copying data during signal sending. Allocation and deallocation of memory is handled automatically.
  • Algorithms in SDL: A number of new constructs have been added to allow algorithms to be expressed within a Task symbol, e.g. if-then-else, loops and decisions.
  • Extended operator: Added support for operators without parameter, operators without result, and in/out parameters to operators (both operator signatures and diagrams). As an alternative to an assignment statement an operator application statement may invoke a non value returning operator.
  • External variables supported.
  • Latin One: ISO-Latin-1 supported in predefined sort character.
  • I18n: Predefined sort charstring supports multi-byte character literals.
  • Names: Underscore may be used without restrictions in names.
  • A make operator has been added to the predefined items String, Powerset, Bag, and Object_identifier. The operator takes a variable number of arguments (0 and up). It is invoked by the "(. .)" notation. The signatures for the operators are:
make! : * Itemsort -> String;
make! : * Itemsort -> Powerset;
make! : * Itemsort -> Bag;
make! : * Natural -> Object_identifier;
The * above indicate a variable argument (0 or more occurrences allowed).
  • New operator in predefined type Object_identifier:
append : in/out Object_identifier, Natural;

SDL-2000 Extensions

  • Binary and hexadecimal literals for Integer, Bit_string, Octet, and Octet_string sorts. Examples `'b `1001'B `'H `Fe'h.
  • Mix of block and process:
    • System may contain process (without intervening block).
    • Block may contain block (without intervening substructure).
    • Channels may be connected to processes.


Compatibility with ITU MSC

The MSC language support in the SDL suite includes full support for basic MSCs (MSC'93), and also parts of MSC'96, as defined in the ITU-T Z.120 recommendation.

The key points for the MSC'96 support are:

  • Roadmaps, or High-level Message Sequence Charts (HMSC), are supported in the HMSC Editor with the exception of the comment symbol and the parallel frame symbol.
  • MSC diagrams support the reference symbol with MSC reference expressions, allowing references to other (H)MSC diagrams.
  • MSC diagrams support qualifiers.
  • MSC diagrams support inline expressions, allowing several scenarios to be expressed in the same diagram. Since the MSC Editor does not support gates, the inline expressions always cover all instances.
  • Separate timer symbols are supported in MSC diagrams.
  • MSC diagrams support lost and found messages (black and white holes).

Limitations to the MSC support can be found in "UML and MSC Restrictions" and "MSC Editor" .

The MSC Editor also supports a few extensions to Z.120:

  • Messages and timers may be assigned additional statuses that map the Z.100 recommendation, allowing to express a graphical trace in a more intuitive way.
  • Messages are allowed to be sent to self, where the out event and the in event resides on the same instance (Z.120 does neither explicitly allow or forbid this).

MSC'96 Reserved Words

The following words are reserved in MSC'96:

action, all, alt, as, before, begin, block, by, comment, concurrent, condition, connect, create, decomposed, empty, end, endconcurrent, endmsc, endexpr, env, exc, expr, external, found, from, gate, in, inf, inline, inst, instance, loop, lost, msc, mscdocument, msg, opt, order, par, process, reference, related, reset, service, seq, set, shared, stop, subst, system, text, timeout, tim, to, via

The reserved words may not be used as names/identifiers even if the MSC Editor does not support the corresponding language construct; this to avoid compatibility problems either when the editors support more of the MSC'96 language or if the MSC/PR is to be exported to other tools with a different subset of the language supported.

MSC'93 Reserved Words

The following words are also treated as reserved words in the (H)MSC Editors but are mapped to (corresponding) MSC'96 reserved words.

MCS'93 | MSC'96
instancehead | instance

This mapping is done to give old scripts and MSC/PR generators a chance to work.

Unsupported Reserved words

The following reserved words are not supported by the (H)MSC Editors (i.e. they are treated as reserved words with respect to names/identifiers but the Editors have no support for the constructs that can be created with these words).

before, begin, external, found, gate, lost, order, related, via

In addition, the Validator does not support the following reserved words:

subst, by, msg

Parameter Lists

Note that MSC/PR import in Telelogic Tau allows empty parameter lists and an empty duration name when setting a timer, due to backward compatibility. This is not in accordance with either MSC'93 or MSC'96.


2 Release Notes

This chapter contains information related to the SDL Suite and TTCN Suite 4.4 releases, in terms of:

  • Included components
  • New and changed functionality
  • Known limitations
  • Recommendation of use


Included Components

The SDL Suite 4.4 and TTCN Suite 4.4 release features the following tools and documents:

Common SDL Suite and TTCN Suite Tools and Features

  • Organizer
  • Print utility
  • Preference Manager
  • Postmaster Libraries
  • ASN.1 Utilities
  • DOORS Integration

The SDL Suite Tools and Features

  • SDL Editor
  • CIF Converters
  • ispell integration
  • Emacs integration (UNIX only)
  • MS Word Integration (Windows only)
  • Link Manager
  • Type Viewer
  • SDL Coverage Viewer
  • Index Viewer
  • SDL Analyzer
  • SDL Access (not included in the standard distribution)
  • CPP2SDL Utility
  • SDL to C Compilers (Cbasic/Cadvanced/Cmicro)
  • Targeting Expert
  • SDL C Compiler Driver (SCCD)
  • Simulation Library and GUI
  • Validation Library and GUI
  • Application Library
  • Master Library
  • Cmicro Package
  • Threaded Integration
  • ASN.1 BER/PER Encoding/Decoding
  • OM Editor
  • SC Editor
  • MSC Editor
  • HMSC Editor
  • Deployment Editor
  • Text Editor
  • UML2SDL Utility
  • OM Access

The TTCN Suite Tools and Features

  • Browser
  • Finder (Windows only)
  • Table Editor
  • TTCN Link
  • Autolink
  • Data Dictionary
  • Analyzer
  • TTCN to C compiler
  • Simulation Library and GUI
  • TTCN Access
  • TTCN Exerciser
  • ASN.1 BER/PER Encoding/Decoding
  • TCP/IP Module for adaptation

User Documentation

  • Installation Guide - printed book, on-line help and PDF files on the installation CD
  • Release Guide - on-line help and PDF files on the installation CD
  • Getting Started (tutorials) - printed books, on-line help and PDF files on the installation CD
  • Methodology Guidelines - printed books, on-line help and PDF files on the installation CD
  • User's Manual - on-line help and PDF files on the installation CD


New and Changed Functionality

This section contains a list of new and changed functionality in SDL Suite and TTCN Suite 4.4. The issues documented here are added or modified since the SDL Suite and TTCN Suite 4.3 (4.3.0) release.

Common SDL Suite and TTCN Suite Tools Features

Licensing

  • FLEXlm version is changed to 8.0d.

Patches and Error Descriptions

  • Patches to the SDL suite and TTCN suite software, as well as descriptions of known errors and corrected errors, are available on the Telelogic Help Desk web page.
    This page can be directly accessed with the Organizer Help menu command Help Desk. It also possible to manually login on the page http://www.telelogic.com/usersupp/custarea.asp
    Use your personal user name and password, or obtain a personal user name and password by using the information found in the dialog box Telelogic License Information, which is opened with the Organizer Help menu command License Information.
    Note that this feature requires a valid maintenance agreement.

Organizer

  • New options for the Semantic Analysis
    In the Semantic Analysis dialog there are two new toggle options. These are to control if checks should be made for missing else answers in decisions and to check for missing answer values.
  • A new symbol type in the Organizer for test script has been introduced. The Organizer Add New dialog has a new alternative: Add New::Text::Test Script. The Test Script symbol is similar to a plain text symbol. The main differences are that the Test Script symbol has the default extension *.cui instead of *.txt and has the menu choice "Simulator Test" in the pop up menu for the symbol. Double-clicking a CUI script symbol opens the text editor.
  • Two new preferences have been introduced that are used to make sure that characters with fixed sizes are used in text symbols. These are Editor*FontText*TextSymbolFontFamily and OME*TextSymbolFontFamily. These preferences control the appearance of text symbols in the SDL Editor and OM/SC/HMSC/MSC/DP Editors respectively. The selected font is displayed in both screen versions and printed versions of the diagrams.
    Print only changed entities of a compare operation. A "Select and print differences" option has been added to the "Organizer::Tools::Compare SDL Diagrams" dialog. This will print all pages with differences and is started from the Organizer.
    The "Select and print differences" option in the "SDL Editor Compare Diagrams" dialog is updated to the same behavior as in the Organizer, i.e. to only print pages with differences.
    The second "Compare Diagrams" dialog is always used when doing a graphical compare. It does not matter if the compare operation was started from the SDL Editor, the Organizer or the command line. The second "Compare Diagrams" dialog will be updated with a print button, to print the page or pages from the current page pair that has differences.
    For symbol differences, the symbol background will be colored instead of the symbol border. This makes it easier to find the differences on the pages, both on screen and in print.
  • The Organizer::Tools::Compare State Machines operation has previously compared state charts with SDL processes. The operation can now also compare state charts with SDL services. In the cases where an SDL system contains a process with the same name as a service, it is possible in the state chart to decide which one to match by introducing a comment before the name of the diagram. Use either /* service */ myDiagramName or /* process */ myDiagramName.
  • Functionality for compare:
    The text compare is integrated in the normal diagram compare. It is available regardless where the compare is started, in the Organizer or in the SDL Editor. When two diagrams are compared side by side a small dialog is used to navigate between differences. This dialog has been updated to include an extra button "TextCompare". Normally this button will be greyed but when two text symbols differ it will be available and the user can enter the text compare dialog.
    The text compare dialog is made up from two lists of text that are placed side by side with a "gutter" that will contain extra information about the differences this information consists of:
    • A "-" indicates that there is no corresponding line in the text compared to the other text.
    • A "|" character indicates that the line differs in the two texts.
      The current differences are highlighted. There are buttons that make it possible to navigate to "Previous" and "Next" difference items.
  • Functionality to merge:
    The merge will be conducted on "per page" basis, text symbols that can be selected from either of the compared diagrams will have the options to be merged together into a new text symbol.
    When manual merges are conducted the option to merge text symbols will always be available in the navigation dialog. An extra button will be added similar to the compare function. As in compare the button will mostly be greyed. When a text symbol is selected the user has the option to select either a symbol or merge the text in the symbols into a new symbol. If the text merge is selected a text merge dialog is displayed with three text lists, the two source texts and the result text. It is possible to navigate between the unresolved differences or between all differences. This works in the same way as in the normal merge. The buttons "<<" and ">>" will jump between the unresolved differences and the "previous" and "next" buttons will jump between all differences.
    The use of "Accept 1/Reject 1", "Accept 2/Reject 2" buttons will select neither, either or both the texts for merge. The selections from the source files are presented in the result list. The "gutter" will show what version that is selected. It is also possible to edit the result line-by-line by selecting a line and edit it below the list. Clicking the "Change" button will replace the changed line.
  • The search in the SDL Index Viewer has been optimized.
  • It is now possible to search for text in the Organizer View. Invoke search by pressing Ctrl+F. Type the text to search for, and a node with a matching text will immediately be selected. To search again, press Ctrl+F again or press return.

Printing

  • The printing in SDL Suite has been changed.
    The following are the differences compared to the previous versions: "Table of contents" is now called "Contents", written in a bold, left-aligned and larger text.
    Pages described in the "Contents" list are now not grouped in groups of five anymore. Instead, there is a dotted line making it easy to find the page number for a given page name. The position for items in the table of contents has been updated. The appearance of textual chapters has been changed. The chapter header text size depends on the level of the chapter number.
  • New Preference variables
    • Print*TextIndentation1: Used by text pages for presenting chapter numbers. Default: 44 mm from the left paper edge.
    • Print*TextIndentation2: Used by text pages for presenting chapter names and normal text. Also used by the table of contents for presenting chapter numbers. Default: 67 mm from the left paper edge.
    • Print*TextIndentation3: Used by the table of contents for presenting chapter names. Default: 90 mm from the left paper edge.

ASN.1 Utilities

  • A new functionality for -c option has been added: Generation of a configuration file named asn1_cfg.h. This file contains compile switches that are used inside the coders code. When asn1_cfg.h is used by the build process the preprocessor automatically throws away useless parts of the code from encoding and decoding related files. This helps to reduce the code size and improve the performance of encoding and decoding procedures.
    See "Configuration file generation" and "Encoding configuration" for more information.

The SDL Suite Tools and Features

SDL to C Compiler

  • The compile switch XCALENDERCLOCK was misspelled. This is corrected and the new spelling is XCALENDARCLOCK.
  • The Cmicro code generator can be instructed to generate a short string parameter to the XTRACEDECISION by setting the environment variable CMICRO_SHORT_DECISION_TRACE.

SDL Analyzer

  • The selection of packages in the SDL analyze/build process executed from the Organizer can be altered by a filter command if the environment variable SDTSAN_FILTER_USE is set.
  • The following commands are new
    • SDL-Keyword-File
    • Set-Predefined-XRef
    • Set-Warn-Else-Answer
    • Set-Warn-Match-Answer
  • The semantic analysis phase has been speeded up.

H2SDL to CPP2SDL migration

  • As stated earlier the h2sdl utility is retired and replaced with the cpp2sdl utility.
    cpp2sdl provides several major improvements, including the ability to import C++, enhanced mapping from C to SDL and exact control over which parts of a C or C++ interface that are imported.
    A new command has been added to be used during migration from h2sdl to cpp2sdl. The command changes the case of all words in a system, with some restrictions, to the case used in the declaration of the word. This is useful if a system is developed in case-insensitive mode and you need to make it case-sensitive. For further information see "CPP2SDL Migration Guide.

CPP2SDL

The -supportfunctions option (Make support functions available in generate target code in the cpp2sdl options dialog) has been removed. If this option is specified in the import specification it will be ignored by the tool. With the usage of generic functions in the code generator there is no longer any need for the ADT directive that previously could be generated by cpp2sdl.

ASN.1 Encoding/Decoding

Detailed error messages

Error messages include a type name with a path to the field where an error has occurred. The path contains sequence of SET/CHOICE/SEQUENCE fields and open type objects from the root type up to the field where an error has occurred.

There are two possible representations for the path:

  • path fields are represented by their names, for example,
ERROR 21 No more data for read at BOOLEAN, type: BOOLEAN, path: yASN1_Type1.field2.comp1
  • path fields are represented by their indexes - in this case root type is named "undef" and path contains indexes of SEQUENCE/SET components, CHOICE alternatives and open type objects, for example,
ERROR 21 No more data for read at BOOLEAN, type: undef, path: SEQUENCE.2.1

Names representation is enabled by the CODER_TI_NAMES compile switch. By default the second representation with indexes is used. See "Detailed error messages.

User defined Error Handling

A new functionality has been added that allows to call a user defined error handling function inside the decoding procedure. If an error occurs then right away this function will be called. The error handling function gives an opportunity to insert a default value to the field for which the decoding failed. See "User defined Error Handling.

User Data

There is an option to include your own data fields into the buffer type. C-type tUserData is defined in the user_data.h file and it can be included into the buffer by CODER_USER_DATA compile switch. By default type tUserData is defined as void*, but you can redefine it according to your needs. See "User Data.

User defined Memory Handling

There are two new BMS user-specific memory handling procedures that are referenced through macros defined in the mms_user.h:

#define USER_BMS_ALLOC_FUNC(buffer, size, type) UserBmsAlloc(buffer,size)
#define USER_BMS_FREE_FUNC(coder, ptr, size, type) UserBmsFree(buffer,ptr,size)

These interfaces are referenced only from the buffer functions. See "User defined Memory Handling.

Threaded Integration

  • The integration "Threaded Light" has been renamed "Threaded" in order to avoid confusion with the "Light" integration.
  • Textual SDL trace, similar to the textual trace in the SDL simulator, is now available for the Threaded Integration. It is enabled by selecting the "SDL trace" check box in the "Target Library/Kernel" page in the Targeting Expert (this sets the THREADED_XTRACE flag).
  • On-line MSC trace is now available when running an application under a soft-kernel on Windows or Unix. This is enabled by selecting the "MSC trace" check box in the "Target Library/Kernel" page in the Targeting Expert (this sets the THREADED_MSCTRACE flag).
  • A new API is available. It contains a number of functions/macros to make it easier to send and receive SDL signals in an external task/thread.

SDL Simulator

  • It is now possible to save the state of the current simulation in a file and restore it at a later time. This is done with the new commands Save-State and Restore-State.
  • The time for merging coverage files (*.cov) in the Coverage Viewer has been decreased by introducing a hash table of SDT references to find the correct transition or symbol to add execution information to the coverage file.
  • A restart quick button has been added to the Simulator User Interface which makes it easy to restart the Simulator. A re-run script quick button has also been added that will re-run the last top level simulator script (input history (*.cui) or command history (*.com)).
  • The speed when opening coverage files in the Coverage Viewer has been improved, mainly due to not parsing SDT references until the information is needed.
  • When running a simulator through the Simulator UI, and not all external synonym values have been specified, the Simulator UI will ask for values with dialogs, before starting the execution. To make it easy to get a correct synonym file, the Simulator UI now lists all missing synonyms and the value they were given in the dialogs. For missing external synonyms that were not given values, the type is specified instead of the value.
  • A new Simulator UI command has been introduced: set-synonym-file, that can be used without parameters (then a dialog will pop up and ask for a synonym file to use) or with one parameter (then the specified synonym file will be used). The new Simulator UI command can be used from input history scripts. The Simulator UI menu bar has been updated to include a SimUI::Change::Synonym File menu choice for this operation. The new syn-file will be used the next time the Simulator is restarted.

The TTCN Suite Tools and Features

Import/Export

  • Generate import/export functionality previously exclusive to UNIX versions has now been ported to Win32 versions as well. To generate Imports declarations, open the Modular Test Suite in the browser. From Import Part - Import Declarations, open the Module. Imports are generated by selecting Edit->Generate Import. To generate Exports, open a TTCN Module in the browser. From TTCN Module Overview, open TTCN Module Exports. Exports are generated by selecting Edit->Generate Export.

ASN.1 Types By Reference

  • There is now tool support for automated declaration of ASN.1 Types By Reference. Given one (all platforms) or several (Windows only) ASN.1 module(s), TTCN Suite will generate entries in the ASN.1 Types by Reference tables in the test suite. This functionality can be accessed in the File menu of the TTCN Suite GUI. If the Organizer is running, the ASN.1 module will be added to the system and a dependency to the Test Suite will be created. The tool can be run in batch mode as well: On Win32 platforms, the application name is asn1import.exe. On UNIX platforms, the name is ASN1import. It takes as arguments first the Test Suite, followed by one or more ASN.1 modules (all platforms) to be referenced. If the Test Suite does not exist, it will be created.


Known Limitations

The following sections contain a list of known limitations and restrictions for the tools and parts of SDL Suite and TTCN Suite 4.4.

SDL Suite and TTCN Suite Limitations

Operating System and Windowing Environment

  • In Windows, SDL suite and TTCN suite have been built and tested using the following service packs:
    • Windows 98: Second edition
    • Windows NT 4.0: Service pack 6
    • Windows 2000
    • Windows XP
      You may encounter problems when running SDL suite and TTCN suite if you do not have these service packs installed on your system.
  • When you run SDL suite and TTCN suite on X terminals or PCs with X server software, mouse-clicks are sometimes not transmitted quickly enough for SDL suite and TTCN suite to recognize it.
    The X resource *multiClickTime can be used to change the default threshold of 250 ms if you have a UNIX terminal with the DISPLAY environment variable set to your local X server. You can write:
xrdb -merge
*multiClickTime: 1000
^D
The appropriate value (in milliseconds) may depend on your hardware/network.
  • The X server delivered with HP-UX 10.20 need to be updated with patch PHSS_12470 from HP, to prevent the X server from crashing when you run SDL suite and TTCN suite.

On-Line Help and Documentation

  • When links are followed from the index in the on-line help, the positioning in the HTML help file may not always be exact. In some cases, the positioning is made a few lines down in the describing text. In the case of tables, the positioning may be after the table.
    The workaround is to scroll the text up to find the heading, bulleted item or table row describing the corresponding topic.
  • In SOMT Tutorial, it is assumed that you have basic knowledge of the Link Manager. However, this tool is not covered in the earlier tutorials. For information about the Link Manager, see "Implinks and Endpoints.
  • There are no tutorials on the State Chart and HMSC Editors.
  • In the MSC Editor, the appearance of some MSC symbols and lines has been updated but all MSC diagrams depicted in the documentation have not been updated accordingly.
  • All dialogs and diagrams in the documentation containing the previous release versions in paths, etc. have not been updated to reflect SDL Suite 4.4.
  • If the last instance of Netscape was an application other than the browser, help files will not open. The work around is to change the preference for Help*NetscapeCommand to netscape -noraise -remote 'openURL(URLTOOPEN,new-window)'.

Licensing

  • The license timeout facility does not support the TTCN suite or tools that are run in stand-alone mode. In general, stand-alone tools do not release their licenses immediately when they do not need them any longer, with the exception of the Cadvanced/Cbasic SDL to C Compiler.

ASN.1 Utilities

The ASN.1 Utilities handle all constructs of ASN.1 as defined in ITU-T recommendation X.680 with extensibility features, X.681 and X.682. Some of the X.683 construct are also supported. See restrictions below for unsupported constructs. There is no support for features defined in the old ASN.1 version X.208.

Restrictions to X.680

ASN.1 Utilities handle all constructs defined in X.680, the following semantic concepts of X.680 are not supported:

  • Modules are distinguished from each other only by module name. Object identifier following the module name in GlobalModuleReference is ignored and module name is always considered definitive.
  • Values can not be assigned to EmbeddedPDVType, ExternalType and UnrestrictedCharacterStringType, these types can not be constrained.
  • The contents of character strings representing GeneralizedTime and UniversalTime types is not checked.

Restrictions to X.681

  • Object class references (X.681, 7.1) can contain lower-case letters. Object class reference consist of a sequence of characters as specified for a type reference.
  • Lower-case letters and digits can be included to Word item (X.681, 7.9). Word consists of a sequence of characters as specified for a type reference.

Restrictions to X.682

  • At-notation is not checked when assigning values to the types with component relations.
  • Multiple table constraints on one type are not allowed, for example "MY-CLASS.&TypeField ( {MY-SET1} ) ( {MY-SET2} )" is not allowed.

Restrictions to X.683

  • Parameterized object classes, objects and object sets and value set types are not supported; only parameterized types and values can be specified, though all of the above entities can be used as parameters themselves.
  • Dummy governors are not supported.

Restrictions to X.690 and X.691

  • Only one reference to identifier component is supported by ASN.1 coders. For the components restricted by two or more component relations in the AtNotationList (see X.681, 10.7), only the first restriction will be handled by the ASN.1 coders.
  • X.690 8.11.3 restriction. The order of data values in a set value decoding restricted by canonical order (X.680 8.4) as default compile configuration. Use CODER_BER_CANONICAL_OFF compile switch to avoid of this restriction.
  • The following ASN.1 types defined in X.680 are NOT supported by ASN.1 encoders and decoders:
    • BMPString
    • GeneralString
    • GraphicString
    • ISO646String
    • TeletexString
    • T61String
    • UniversalString
    • UTF8String
    • VideotexString
    • UnrestrictedCharacterStringType
    • EmbeddedPDVType
    • ExternalType
    • InstanceOfType
    • ObjectDescriptor

Restrictions to Z.105

  • The following concepts of Z.105 are not supported by the ASN.1 Utilities:
  • ASN.1 definitions can not be put in text symbols in SDL diagrams; they can only be placed in separate ASN.1 modules, whereas Z.105 allows free mixing of SDL and ASN.1 definitions.
  • Value notations for types defined in another module are not supported. For example; val X ::= 3 is only allowed if X is defined in the same module. External value references should be used instead.
  • Use of the ASN.1 value notation within SDL expressions is not supported for bit string, octet string, set, set of, sequence, and sequence of.
  • Value notation for SEQUENCE/SET where optional/default components have been assigned a value cannot be mapped to SDL unless SDL optional support in make operator is switched ON.
  • UniversalString, GraphicString, and EXTERNAL are translated to SDL types with the same name, but no implementation for these types is available (have to be provided by you). The reason is that Telelogic considers the mapping in Z.105 as insufficient (does not really allow extended character sets).
  • PLUS-INFINITY and MINUS-INFINITY are translated to some large numbers. If these are not large enough for a specific platform/application, you must define these SDL synonyms yourself.
  • If there are name clashes between named bits, named numbers or ASN.1 values, only the first occurrence of the synonym will be generated to SDL, for example, for ASN.1 definitions T1 ::= BIT STRING { a(3) }, b INTEGER ::= 11 and T2 ::= INTEGER { a(4), b(5) } only synonyms a from BIT STRING and b for INTEGER value will be generated to SDL with warning messages because generation of all synonyms according to the Z.105 standard will result in an SDL analyzer error.
  • In SDL (Analyzer) literals and synonyms with the same name will clash if they have the same name. So, for the following ASN.1 definitions T ::= ENUMERATED {x, y} x INTEGER ::= 15 val T ::= x generated SDL newtype T literals x,y operators ordering; endnewtype; synonym x Integer = 15; synonym val T = x; will not compile: ERROR 375 Type mismatch for synonym or literal: synonym val T = ? x INFO 352 x is one of the visible definitions. Although a simple workaround for this problem is to add a qualifier before value x to the generated SDL : synonym val T = <<type T>>x; .

Print

  • When printing to EPS files (one per page) the files will be named after the page in a case sensitive way. On Windows, when pages have the same name only differed by case, only one file will be printed containing the last page, due to the limitation in Windows concerning case.
  • Colors are not supported for FrameMaker or Interleaf printing.

SDL Restrictions

This section describes the major SDL restrictions with respect to the ITU-T Z.100 recommendation of 1992. The restrictions lie in one or several specific tools. This means that even if a concept is not fully supported, it may sometimes be possible to use it in a limited part of the tool set.

This listing deals with restrictions in the following tools:

  • SDL Editor
  • GR to PR Converter
  • SDL Analyzer
  • SDL to C Compiler (Cbasic and Cadvanced)

For more detailed information on the SDL restrictions in the Analyzer and the SDL to C Compiler, see "SDL Analyzer" and "SDL to C Compiler" .

For a description of SDL restrictions regarding the Simulator, the Validator, the TTCN Link kernels and the Cmicro SDL to C Compiler, please see the following sections in the User's Manual:

  • "Restrictions" .
  • "Restrictions" .
  • "SDL Restrictions" .
  • "SDL Restrictions" .

Z.100 Chapter | Concept and Restriction | Affected Tools
2.2.2 Visibility rules, names and identifiers | <name>: spaces in <name>s are not supported (a space is a shorthand for <underline>) | SDL Editor, Analyzer, SDL to C Compiler
2.4.1.2 Package | <interface> definitions, and <definition selection list> in use statements, are not supported. | Analyzer, SDL to C Compiler
2.5.1 Channel | nodelay: channels with delay and channels with nodelay are treated the same. | SDL to C Compiler
2.7.4 Output | via all to a <block instance set> only sends a single signal. | SDL to C Compiler
2.9 Internal input and output | The <internal input symbol> and the <internal output symbol> are not available. | SDL Editor
3.2 Partitioning | <channel substructure definition> is not supported in generated code. | SDL to C Compiler
 | In substructures with both process definitions and block definitions, the process definitions will be ignored. | Analyzer, SDL to C Compiler
3.3 Refinement | <signal refinement> is not supported. | SDL to C Compiler
4.2 Macro | <macro definition>: macros and macro calls are transformed to PR and expanded in PR form, which restricts the usability of macros. | Analyzer
 | <any area>: graphical macros can only contain flow symbols in one single flow. | SDL Editor, GR to PR converter
 | <macro call>: graphical macro calls are not allowed in a higher scope than processes. | SDL Editor, GR to PR converter
4.3.3 Optional definition | <select definition>: textual optional definitions are supported, but not graphical. Any (external) synonyms used in the select expression must be defined in the system definition which may not be type based. | SDL Editor, Analyzer, SDL to C Compiler
4.3.4 Optional transition string | <alternative question>: question part in transition option must not contain external synonyms. | Analyzer, SDL to C Compiler
5.2.3 Axioms | <axioms>: not supported. | Analyzer, SDL to C Compiler
5.2.4 Conditional equations | <conditional equation>: not supported. | Analyzer, SDL to C Compiler
5.3.1.14 Name class literals | <name class literal>: not supported. | Analyzer, SDL to C Compiler
5.3.1.15 Literal mapping | <literal mapping>: not supported. | Analyzer, SDL to C Compiler
5.4.4.5 Timer active expression | <timer active expression>: cannot be used for timers with parameter. | SDL to C Compiler
6.2 Context parameter | <formal context parameters> and <actual context parameters> are not supported. | Analyzer, SDL to C Compiler

The SDL Suite Tool Limitations

SDL Editor

  • Diagram names may not exceed 255 characters.
  • If the colors red and blue are used for some symbols, you may find it hard to interpret the graphical view resulting from the Diff operation, as these colors are used for highlighting the differences between two diagrams. To avoid this problem, do not use the colors red and blue on symbols when you compare diagrams.
  • The special graphical symbols for internal input and output are not available, as the use of them is explicitly discouraged in Z.100. The same behavior can be achieved with the normal input and output symbols.
  • Graphical macros (macro diagrams) can only contain flow symbols in one single flow, without branches. Graphical macro calls are not allowed in a higher scope than process (system, block, etc.).
  • The option symbol (dashed polygon) is not available.
  • Nested diagrams are not supported, that is, diagrams must contain reference symbols to diagrams at lower levels. For instance, a system with a block must be drawn as two diagrams, where the system diagram contains a block reference symbol to the block diagram.

Print

  • The FrameMaker or Interleaf integration do not support colors.
  • It is only possible to change the font used to print text files by using the preference SDT*PrintFontFamily.

Emacs Integration (UNIX only)

  • To function properly, the SDL suite assumes GNU Emacs 19.31 or later.
  • Undo is not supported for the link handling commands.
  • If Emacs is started from SDL suite and TTCN suite and SDL suite and TTCN suite is shut down, but not Emacs, the Emacs session cannot be re-connected to another SDL suite and TTCN suite session.

Microsoft Word Integration (Windows only)

  • MS Word 7.0, MS Word 8.0 and MS Word 2000 are supported, see certification matrix.
  • When a MS Word document becomes modified, its icon is not marked as "modified" in the Organizer.
  • A new MS Word document is always named "Document<x>", where <x> is an integer, independently of what name it was given in the Organizer.
  • Undo is not supported for the link handling commands.
  • Endpoints in MS Word documents sometimes need to be synchronized with the Link Manager manually: Use the Update menu choice.
  • In the Organizer, multiple instances of MS Word cannot be handled.
  • Due to problems with recognizing read/write security permissions on NTFS files/directories, some odd behavior in the communication with MS Word may occur. This shows up as two error boxes with almost the same contents, one in MS Word and one in the Organizer. In the Organizer, the access rights on such files are incorrectly marked as "rw".
  • Since part of the implementation is done with MS Word macros, conflicts may arise when combined with other templates/macros. This must be considered on a case-to-case basis and possibly the different macros may have to be merged. The implementation does not work with for example "Macro Virus Protection Tool" from Microsoft.
  • If MS Word is started from SDL suite and TTCN suite and SDL suite and TTCN suite is shut down, but not MS Word, the MS Word session cannot be re-connected to another SDL suite and TTCN suite session.

SDL Analyzer

Implementation Restrictions

The present version of the Analyzer is an SDL-92 analyzer. The restrictions and the implementation limits are described in this section. When possible, a work-around is described.

  • Macros and macro calls are transformed to PR and expanded in PR form. This restricts the usability of macros, for instance the number of inlets and outlets must be 0 or 1. A common case that fails is a macro with states that is called from a branch of a decision. It fails because the GR to PR converter does not know the contents of the macro and treats the call like a task symbol. Other things not supported because of this, are variable declarations and type definitions.
  • The Analyzer assumes the layout of external properties to follow the example below. That is, each external formalism name should be on the same line as the alternative keyword and the external data descriptions should be on lines of their own.

Example 1

alternative a,b;
abc abc t5;
abc abc t5-2;
endalternative;
b;

The PR to GR Converter

  • The PR system will be changed to have all its definitions referenced to match the way the SDL suite handles diagrams. A referenced definition needs a qualifier if name and type are not unique in the system. Such qualifiers are not supplied automatically: use the Update Heading command in the Organizer.
  • Comments in PR files /* comment text */ may sometimes be skipped during conversion into GR format.

Restrictions on Syntactic Analysis

  • The Analyzer cannot handle spaces in names (a space is a shorthand for an underline). Replace spaces with explicit underlines.

Restrictions on Semantic Analysis

  • The semantics of virtual types is unclear.
  • Gate constraints on implicit signal routes are not checked.
  • Implicit gate connections are not checked.
  • Signals of global procedures are not properly checked.
  • Only limited tests on output via.
  • It is not checked that instantiated types have signals in the gate constraints.
  • Context parameters are not implemented.
  • Conditional equations are not implemented.
  • Some checks may be lost in nested virtual definitions.
  • Package interfaces and definition selection list in USE statements are not implemented.
  • Remote procedure calls are not checked against imported procedure specifications.
  • Imported procedure specifications are not checked against exported procedures.
  • Import expressions are not checked against imported variable specifications.
  • Imported variables are not checked against exporting processes.
  • The check that substructure name in subtype and supertype must be the same is not implemented, since it would make the use of "block in block" useless for inheritance.
  • Operator definitions are not checked against operator signatures.
  • Name class literals in user defined data types cannot be handled in the Semantic Analyzer. A nameclass literal is a shorthand for writing a (possibly infinite) set of literal names defined by a regular expression. List the literals explicitly or use inheritance from the predefined data types.
  • Question and answers in decisions are always considered formal, that is, informal text is considered to be a character string.
  • Inheritance from data type definitions containing qualifiers referencing that type definition is not allowed, since qualifiers are copied and not changed during the expansion of inheritance.
  • When analyzing part of a system, checks depending on the omitted parts will not be performed.
  • When a substructure contains both processes and blocks, it should be possible to select which implementation that is preferred. This is not possible; the process definitions will not be analyzed.
  • Signal refinement is not supported.

Semantic Checks that are not Performed

Analysis of the following semantic SDL rules is not performed:

  • The consistent partitioning subset must be a consistent refinement subset.
  • The decision answers must be mutually exclusive. This is not tested for all possible data types.
  • An exported variable must exist for each imported variable.
  • The type check and the evaluation and check of the equivalence classes in axioms is not performed.
  • Generator names and generator formal parameters must not be used in a qualifier, qualified, followed by an exclamation, or used in a default assignment.

SDL to C Compiler

  • Channel substructures are not allowed.
  • Signal refinements are not supported.
  • Context parameters are not supported.
  • Timer active expressions for timers with parameters are not allowed.
  • In generated code there will be no difference between a channel with delay and a channel with NODELAY.
  • Integer and Real are restricted in range and precision, as they are implemented using the C int (32 bit integers) and double types. Charstrings may not contain the character NUL, as Charstring is implemented using char * in C, and char * is terminated by NUL (=0).
  • Axioms and literal mappings may be part of an abstract data type definition, but that information is not used in any way by the SDL to C Compiler.
  • In abstract data types, the following concepts cannot be handled:
    • Name class literals
    • Naming a literal using a Charstring literal
  • A sort definition may not refer to itself, directly or indirectly.
  • A component of a struct will, in the generated code, have the same name as in SDL. Characters that are not letters, numerals or underscore characters will, however, be removed. The remaining part of the name must be a valid C identifier to be accepted by the C compiler, that is:
    • It should start with a letter.
    • It should not coincide with a C reserved word.
    • It should be unique within the C struct representing the struct.
  • Multiple paths from a decision for a certain decision expression value are not checked. A simulation program will simply choose one of the existing paths.
  • Overflow of integer and real values are checked at the C level if the actual C system performs these checks.
  • A process that exports procedures cannot call (directly or indirectly) a global procedure containing states.
  • Output VIA ALL C, where C leads to a block instance set, is not handled correctly. One signal should be sent to each block instance, but only a single signal will be sent.
  • The .ifc file contains #define definitions for the kind of SDL units for which this is possible. All the SDL to C Compilers follow this principle. This can, depending on the C compiler, lead to compilation errors/warnings or to runtime errors in some cases. The following example shows how the problem may occur:
newtype x
literals green, blue;
endnewtype x;

newtype y
literals blue, green;
endnewtype y;

The both literals green and blue will then be created like this:
/* For newtype x */
#define green 0
#define blue 1

/* For newtype y */
#define blue 0
#define green 1

The C compiler then usually complains that the macros blue and green are redefined with a different value. Some C compilers will continue in any case and produce an executable. Runtime errors are the consequence on this, because when green and blue are used together with the first newtype x, the literal values from the second newtype y are used by the C compiler. In order to avoid this problem, a prefix for each literal should be manually added, like this:
newtype x
literals x_green, x_blue;
endnewtype x;

newtype y
literals y_blue, y_green;
endnewtype y;

The green and blue example is not a good one, because it is possible to avoid the problem by using the inherit construct. The literals from the newtype x could be inherited into the newtype y. More problems will occur if several entity classes are mixed up from the C compiler, like if there would for example be a signal called green, which is also created as a #define. You are strongly recommended to avoid name conflicts in the .ifc file by manually adding prefixes.
  • any(Sort) where Sort is a syntype is only implemented if the syntype contains at most one range condition which is of the form a:b, that is one limited range. If it is a syntype of a real type, e.g. Real or Time, with a range condition it is not implemented.
  • any(Real) does not generate random decimal values, only whole numbers.
  • When the preference SDT*RelativeSDTREF is on, and Edit Separation is used with a separate file name, compile errors may occur requesting a file that does not exist. This can be resolved by either not using a separate name or turning the Relative SDT References off.

Targeting Expert

  • The automatic and manual configuration/scaling for the Cadvanced libraries will not be used per default in all pre-defined integrations. The compiler flag -DUSER_CONFIG must be set to use configurations.

CPP2SDL

  • The following C/C++ dialects are supported by the tool:
    • ANSI C/C++
    • Microsoft Visual C/C++
    • Borland C/C++
    • Gnu C/C++
  • The tool performs a complete syntactic analysis of the input C/C++ program, but only parts of the semantic analysis is done.
  • C++ exceptions are not supported.
  • C++ template declarations are not translated to SDL directly. Instead, instantiations of the templates must be provided, and these will be translated.
  • The support for function pointers is limited. Function pointer types are represented in SDL (as untyped pointers), but it is for example not possible to call the functions pointed at.
  • Expressions containing usages of the sizeof operator are not always correctly evaluated.
  • C++ cast expressions are not fully supported.
  • Members inherited from a virtual base class are sometimes not accessible in the SDL translation.
  • Classes that inherit from multiple template instantiations of the same template are not fully supported.

SDL Simulator

  • If you have already generated an SDL simulator from the Organizer, and want to generate a new one with other options or with another selection, you should perform a Full Make, as changes in options or selection is not handled by the build process. Otherwise compilation or link errors might be the result of the build process.
  • There are no range checks implemented for general arrays. General arrays are implemented as linked-lists because the code generator can not determine whether or not it can be implemented as an ordinary array. This occurs if a synonym translated to a variable is used in a range condition of a syntype and the syntype is used as an index sort in an array or powerset instantiation. The reason for this is that the length of the array cannot depend on a variable in C.
    An example:
SYNONYM Lo NATURAL = 1;
SYNONYM Hi NATURAL = 10;
SYNTYPE BufferType = NATURAL
CONSTANTS Lo , Hi
ENDSYNTYPE;
NEWTYPE MessageBufferType
Array( BufferType, CharString)
ENDNEWTYPE;

Validator/Autolink

  • Bitfields in struct that also contains pointers are not handled.
  • C unions are not allowed to contain pointers.
  • Encoding/Decoding functionality cannot be used together with the Validator kernel.
  • Validation of MSCs containing a signal sending a parameter of type ptr_char, or Charstar will give the following error: "No reference to dynamically allocated memory."
    The RefError occurs because when you read in the MSC diagram there is a parameter of type Charstar and reading this will create the dynamic memory which can not be handled correctly.

Examples

  • On UNIX, the phone example cannot be used together with the graphical SimUI if the Phone application is compiled and linked with the ApplicationDebug kernel.

Real-Time Operating System Support

Light Integration

The same restrictions as for the SDL to C Compiler apply. See "SDL to C Compiler" .

Threaded Integration

The same restrictions as for the SDL to C Compiler apply. See "SDL to C Compiler"

  • Threaded Integration can only be generated with the Deployment Editor and Targeting Expert i.e. the make feature in the Organizer can NOT be used.
  • The Threaded Integration for VxWorks uses POSIX library functions i.e. the VxWorks kernel must be compiled with the POSIX libraries.
  • In a Threaded Integration, the xInEnv function is invoked when a state transition occurs in the SDL system. This means that intervals between the xInEnv calls are irregular and depend on the properties of the running SDL system. When writing external code for input into an SDL system, it is recommended that the code is run in a thread of its own, using xGetSignal and SDL_Output for inserting signals into the system.
  • On-line MSC trace under VxWorks softkernel does not work.

TCP/IP Communication Module

  • On VxWorks, the TCP/IP communication module has been tested on a softkernel running on Solaris. In order to connect to a Vxworks softkernel application, the loopback IP address of the host machine must be used. In most cases, this IP address is "127.0.1.0".
  • On OSE, the TCP/IP communication module has been tested on a softkernel running on Solaris. In order to connect to a remote component from an OSE softkernel application, the IP address of the remote host must be given explicitly. A regular hostname, e.g. "the_computer.the_company.com", will not suffice.

Tight Integration

  • The tight integrations in the SDL suite are only applicable for Cadvanced - not for Cmicro.
  • Only Solaris (Posix 4), Win32, VxWorks, and OSE delta integrations are available as downloads.
  • Priority input is not handled.
  • Continuous signals are not handled.
  • Services are not handled.
  • An RPC call of value returning procedure without parameters does not work.
  • The SDL ANY construct is not properly implemented.
  • The timer set construct SET(5,T1) is not supported. Instead use SET(NOW+5,T1)
  • ADT Library files located in $telelogic/sdt/include/ADT:
    • file.pr:
      Should work if supported in the RTOS environment. It might be necessary to enclose the function xGetValue with the following code to be able to compile with some compilers.
#ifdef XMONITOR
...
#endif

    • list1.pr and list2.pr:
      Should not be used since they are implemented with dynamic pointers which could lead to memory leaks.
    • byte.pr:
      Works OK.
    • unsigned.pr, unsigned_long.pr, longint.pr:
      Works OK.
    • pidlist.pr:
      Works OK but only with the version supplied in the RTOS delivery: $telelogic/sdt/sdtdir/RTOS/INCLUDE/pidlist.pr.
    • idnode.pr:
      The functions FirstPId and NoOfProcesses may work under some conditions, the rest of the functions do not.
    • pointer.pr:
      Should not be used since there is a big risk of memory leaks.
  • Support for Kernighan & Ritchie C is discontinued.
  • The integration code does not check the upper limit for the number of process instances as declared in the SDL system.
  • The same data type is used to represent TIME and DURATION; in most operating system this is an unsigned integer. Thus TIME or DURATION expressions may not evaluate to negative values. This also applies to intermediate expression results.
  • The SDL error term is not supported in Cadvanced Tight Integrations. E.g. "return error;" can not be used in Cadvanced Tight Integrations.
  • REVEAL and VIEW are not supported. Applications using this concept may crash or behave in an undefined way due to concurrency problems.
  • EXPORT and IMPORT are not supported. Applications using this concept may crash or behave in an undefined way due to concurrency problems.
  • In addition, the same restrictions as for the SDL to C Compiler also apply. See "SDL to C Compiler" .

SDL C Compiler Driver (SCCD)

  • RESTRICTION: SCCD under DOS/Windows does not handle include paths in double quotes.

Cmicro SDL to C Compiler and Library

  • The names of processes in different blocks must not be the same. The reason for this restriction is the missing symbol tree in Cmicro. It is impossible to address for example two processes with the same name in the same C module (in the SDL environment). As a work-around, you should always have different names for the different processes in the system. You can easily accomplished this by adding a prefix to each process name.
  • Predefined sort carray:
    It is impossible to return variables of the predefined sort carray from an SDL procedure because the ANSI C language cannot handle this. It is however possible to enclose the carray into a newtype struct value as a workaround.
  • Timers with parameters and the preemptive Cmicro Kernel do not work together.
  • If a procedure returns a value of a sort that is passed as address, an assignment like call prd(invar, retvar); is not supported. Instead use retvar := call prd(invar); .

SDL Target Tester

  • When the target system is suspended (by sending the suspend command), any signal that is sent to the target will be discarded.
  • When, with the Output-PAR/NPAR command, you want to send a signal to the target system, a list with all the signals that are defined in the system is presented. You should keep in mind that you always have to address the right process instance when specifying the parameters of the SDL Target Tester's output command.
  • It is not possible to send charstrings or pointers with the Output-PAR command to the target.
  • Several compilers, e.g. the Tasking 80166, are giving incorrect information about the message length.
    This error is detected by the SDL Target Tester and displayed once. The trace of SDL events will be correct as only the CRC check is not involved in the following communication.
  • The SDL Target Tester should only be started from the Targeting Expert's Tools menu since there may be problems when the SDL Target Tester is invoked standalone.
  • Page file and convert file in SDL Target Tester does not work.
  • On Unix: The Cmicro Postmaster leaves temporary files below /tmp. You should remove these files from time to time by hand (rm /tmp/.sdt.cmicro.*)
  • It is impossible to specify a breakpoint on a timer input.
  • If the debug mode of Cmicro Postmaster is used, there might be too long messages, in which case the Postmaster will crash with a core dump.
  • If the line numbering in the SDL Target Tester is switched on and off again, sometimes the first columns in the text area are split. As a work around and to prevent this, line numbering always should be switched on at the beginning and never switched off again.
  • The context sensitive help sometimes indicates that a command may be used, though the command cannot be used in current context (setting a breakpoint is allowed although no target system is connected and running).
  • On UNIX: If the sdtmt.btn file contains too many entries that are marked as ":MENU", the SDL Target Tester is not able to scale its window size when it is invoked. If you resize the window manually, the size will be correct.
  • The Parametertrace is restricted to Predefined Sorts, Syntypes, Enums, Newtype Structs and Newtype Array.
    If the SDL Target Tester encounters an unknown data type, the rest of the parameters is shown as hex-buffer.
    Limitations:
    It is not possible to show the contents of a Charstring.
    If you use wrong values for LENGTH_, ALIGN_ and ENDIAN_ in the file sdtmt.opt it is possible that the Tester decodes all parameters, but the shown values are wrong.
  • Searching the Text trace in the Target Tester with regular expressions is disabled by default. The Tester crashes if reaching the end of the trace, i.e. there is no more regular expression found in the trace.
    The feature can be enabled by setting the environment variable TT_REGEXP to 1 before starting the Target Tester.

Application Generation with Cmicro

  • Not all possible errors are checked by the Targeting Expert. In most cases, a compilation error is the result you will get from an incorrect configuration. The on-line help will support you to configure correctly.
  • If you try to #include "systemname.ifc" in ml_typ.h, or for some other reason, there may be further naming conflicts, for example during preprocessing:
sctpred.c: In function `yAss_SDL_Object_Identifier':
ml_pred.c:2109: parse error before `0'
ml_pred.c:2109: parse error before `0'
The reason for the error above (and other behavior that is impossible to foresee) was that there was a signal named "SIn". This will be generated as a #define SIn 0. In the sctpred.c file, there is a variable called SIn (in the macro yAss_SDL_Object_Identifier). The C preprocessor then replaces the variable name with the #define value of SIn, which ended up in the parse error above.
In order to avoid that, you should never include code generated header or .ifc files in any part of the Cmicro Library itself or in the generated C code. The .ifc file should only be included in the SDL environment files (like env.c).
  • In the generated C code, the following warning is repeated for each variable that is unused:
"Unused Variable : <variablename>"

These warnings in generated C code are not that easy to remove because it is difficult to calculate this during code generation. These warnings should not produce real problems (except that it is sometimes impossible to read the large C compiler output). The following variables are sometimes referred:
warning: unused variable `yOutputSignal'
warning: unused variable `yVarP'
warning: unused variable `ySVarP'

The same warning as above is thrown from C compilers when signals without parameters are used.
This warning is accepted in the mk_outp.c module:
mk_outp.c:warning: unused variable `P_Parameter'

A similar warning (accepted also) is within mk_stim.c:
mk_stim.c:warning: `SystemTime' defined but not used

  • Warnings like: "Control reaches end of non-void function"
    As the SDL to C Compiler basically creates a switch() construct in C, and every return from the process activity description function (PAD function) occurs in all the case branches of that switch, the PAD function contains no return statement after the switch. This is the reason why some C compilers complain that the "Control reaches end of non-void function". This is an accepted warning. It is possible for you to remove that warning in the ml_typ.h or user_cc.h file by modifying the END_PAD macro like this:
#define END_PAD(PrsNameWithPrefix) return (SDL_DASH_NEXTSTATE);

  • Warnings: missing braces around initializer for xSTATE_INDEX_zyyyy_xxxxxxx[0]
    This is an accepted error so far, because each known C compiler handles this correctly. The reason why the SDL to C Compiler generates like this is that is still should be conform to not just only ANSI C, but also Kernighan & Ritchie C.
  • Some C compilers fail in preprocessing of very long macro definitions (like all the C Compilers available on the market for the 8051 family of CPU's). Such long macro calls occur in the predefined generators (String, Powerset, Bag).
    If the C compiler (or specifically the C preprocessor) complains about a macro definition that is too long, or produces erroneous output, it is not possible to use these kind of generators. The macro X_LONG_MACROS should be set with the Targeting Expert.
  • It could also be impossible for some C compilers for embedded systems to compile recursive macro calls. Recursive macro calls appear for SDL statements like for example:
a:=b and c and d;

If such a problem occurs, it is strongly recommended to avoid such statements for example with the following work around:
tmp:=b and c, a := tmp and d;

  • When it comes to target applications, you always have to specify how memory is allocated (see C module mk_cpu.c in the template directory) and what should happen if there is no more memory available. As the template C files does not know what you want to do, there is a C macro called NO_MORE_MEMORY that you must define. Any reaction on such a fatal error might be appropriate, like "Hang up the program", or "Reset", or "Print out an error message". Printing out error messages may however fail as well, if the print function allocates memory.
  • The default values for variables are not set in a procedure when XMK_USE_KERNEL_INIT is defined. This is a problem which cannot be solved easily.
    There are two work-arounds:
    • Do not define XMK_USE_KERNEL_INIT
    • Do not use default values for variables in a procedure, e.g. this is forbidden in a procedure (in a process it does work very well):
DCL a integer;
DCL b integer;
task b:=a+b; /* non deterministic results */
This is better:
DCL a integer = 0;
DCL b integer = 0;
task b:=a+b; /* deterministic result ! */

Use of ADTs from the SDL suite in Cmicro

The packages and ADTs delivered with the SDL suite are mainly to be used in Cbasic/Cadvanced applications. Some of these ADTs may however also be useful for Cmicro applications. Others cannot be used together with Cmicro as they contain references to C code from Cbasic/Cadvanced. A list of restrictions and recommendations can be found in "Abstract Data Types.

Combining Cadvanced / Cmicro Code

Mixing C code from different SDL to C compilers is not possible as they use their own runtime model and runtime data structures. Trying to mix up the C code will sooner or later lead to compilation errors. This restriction is true for any kind of combination of C code, including sdth2sdl.

TTCN Restrictions

  • The TTCN language supported in the TTCN suite is according to an interim version of the new TTCN standard labeled Delivery 8.3, August 2, 1996, with the exception of the Modular TTCN features that are according to the Delivery 9.6 version.
  • Due to the Delivery 9.6 Modular TTCN features, the support for the TTCN Package document type has been dropped.
  • The import/export mechanism of the Modular TTCN feature is currently not able to handle import that uses the "xxx[yyy]" construct needed for importing named numbers, and neither able to handle the "xxx::yyy" construct for importing objects with name collisions.

More general restrictions and modifications to the TTCN and ASN.1 support in the TTCN suite is described in Languages Supported in the TTCN Suite.

The TTCN Suite Tool Limitations

Color Problems on UNIX

  • On computers where the display hardware limits the number of concurrent displayed colors, the TTCN suite might run out of colors. It will in this case start to use what appears to be random colors. This should have no effect on the usability of the TTCN suite, but can be somewhat annoying.

Table Editor on UNIX

  • The Table Editor can only display up to approximately 1000 rows. This limitation is only present in the Table Editor, so conversion to or from MP, printing, analysis, etc. is not affected.

Analyzer

  • Special characters in strings, for example "CR" and "ESC", are not checked during analyze.
  • The use of the R variable in expressions is only allowed in the dynamic part, not in declarations. The TTCN Analyzer does not detect the use of R in declarations.
  • The TTCN Analyzer check of send value is incomplete, wild cards in send values are not detected.
  • The types BMPString and UniversalString are not supported.
  • The Analyzer currently only implements a very basic analysis of the imports and externals tables used for Modular TTCN, and in addition the export tables are not analyzed at all.
  • The Analyzer does not support encoding/decoding variations.

External ASN.1 Reference

The definition of the ASN.1 type that is referred is limited:

  • References of the form Module.Type are not allowed in the definition.
  • References to types/values in the same or other ASN.1 module is not allowed in the definition, unless separately defined.
  • The limitations for the types and values referenced from TTCN also include those described in "ASN.1 Utilities" .
  • When using ASN.1 PDU Type Definitions By Reference, you cannot employ BER or PER ASN.1 encoding/decoding if you are mapping the PDU names to other names local to the test suite. (The PDU names will not be recognized by the runtime system.)

TTCN ASN.1 BER Encoding/Decoding

  • The following composite ASN.1 types are not supported:
    • EXTERNAL
    • EMBEDDED PDV
    • CHARACTER STRING
    • ObjectDescriptor
    • UTCTime
    • GeneralizedTime
    • TeletexString
    • VideotexString
    • GraphicString
    • GeneralString
    • T61String
    • ISO646String
    • BMPString
    • UniversalString
    • UTF8String (from X.680/1997)
      It is not possible to Encode/Decode values of these types.

The TTCN to C Compiler

The language supported by the TTCN to C compiler is a subset of the language covered by the Analyzer. This means that in some cases, constructions that have been analyzed correctly are not supported in the code generation phase. The following list describes the known limitations in the current TTCN to C compiler.

  • Single value restrictions of SEQUENCE OF, SET OF and CHOICE are not supported.
  • The INTEGER data type is restricted in range and precision, as it is implemented using the C int data type (usually 32 bit signed integers).
  • The use of choice values in brace lists in the constraints or in assignments is not allowed. The way to work-around this is to do the assignments field-wise in the constraints.
  • SUBSET, SUPERSET and COMPLEMENT are not supported as values for fields in any structured type.
  • The EXTERNAL type is not supported.
  • IS_PRESENT, IS_CHOSEN and SUBSTR are not supported.
  • The REPLACE ... BY and OMIT ... constructs are not supported. As this is only a shorthand for writing out the constraint, the obvious work-around is to define the constraint in its entirety.
  • The MIN/MAX and the inclusive/exclusive (that is <) syntax in ASN.1 value range sub types are not supported.
  • INFINITY, in all its uses, is not supported.
  • COMPONENTS OF is not supported.
  • Selection type and their values are not supported.
  • Values of the REAL data type is not supported.
  • To specify values of the data type BIT STRING as a list of named bits is not supported.
  • Value length restrictions are not supported.
  • Encoding/decoding variations are not supported.
  • The maximum number of parameters to a PTC is restricted to 8.

MSC Logging

The MSC generation part of an ETS is limited in scope and applicability to some particular applications. This list of limitations may be circumvented by manually editing the code in the files mscgen.h, mscgen.c, static.c and gci.c. Such edits are not supported by Telelogic, though suggestions of improvements are welcome.

  • Distributed concurrent test component logs are not supported.
    The reason for this is that it would require additional communication in-between the distributed test components. The required features for a common log of any kind are not available through the architecture of TTCN or the GCI Interface. The result of applying MSC logs for truly distributed ETSs is not defined. Note that the Composed mode may work but it will produce logs only of one component at a time.
    The internal concurrency mode of the TTCN suite is fully supported by the MSC Generator.
  • Re-start of test components
    Concurrent test suites in which one given component is created more than once, will result in MSC/PR that may not be supported by the MSC Editor.
    The generated MSC log will contain multiple instances with the same name, though presumably not at the same time. It is conceivable to write a text processing script which renames instances that are created multiple times. The limitation applies only to the Decomposed mode.
  • Value notation limitations
    These are limitations to the value encoding for MSC/PR form. For information on how the value encoding can be completely disabled, see "Compiling an ETS with MSC Generation.
    • Some types may not be supported for the logging of values with the events of the MSC log. If they are encountered, a warning message will be appended to the event log. See the mscgen.c:MscEncodeValue function for details.
    • Some minor type encodings may differ from the one produced by the SDL Simulator. These differences can be fixed by editing the mscgen.c:MscEncodeValue function. Note that such changes are not supported by Telelogic.
    • Some types that are not supported by the SDL suite are handled. The HEXSTRING and derived TTCN types are not recognized by the SDL suite.
    • The tool has a fixed size buffer for MSC value encoding. The result is that some values may be truncated (values that print to strings longer than approximately 4000 characters). See "Compiling an ETS with MSC Generation for a description of the definitions that need be changed for increasing the buffer size. If the buffer is filled up, syntactic errors in the generated MSC/PR may be the result.
    • The use of message types that have names equal to MSC keywords may result in incorrect MSCs. There is no functionality for detection of this in the MSC Generator or TTCN Analyzer. The MSC Editor will detect the problem if trying to read MSC/PR form files where the problem is present. It is recommended to avoid ASP, PDU and CM names that are such names. Examples of these names include "reset", "RESET", "stop", "msc", "TimeOut" etc.
  • Concurrent TTCN configurations
    • The instances used in a generated MSC always include all the PCOs declared in the test suite. As a consequence, even though a PCO may not be defined to be used in a test case with a configuration, it will still be part of the generated MSC.
  • The MSC Editor logging lacks some error control and may also result in excessive memory consumption by the MSC Editor in long test runs. Also, it slows down the tester significantly since it performs an extra 2 RPCs for each event that is logged. It is recommended to use this option only when developing or testing test scripts.
  • It is possible to "reverse" the components used in the "composed mode" by editing the MscIn and MscOut functions such that they in the composed mode do not switch the "from" and "to" parameters. The reversed view may be conceptually more natural, though it may not be possible to process with some of the other tools of the SDL suite and TTCN suite family.
  • There is an additional compile-time definition that is for debugging purposes: DEBUG_POST_COMMUNICATION. If set, there will be printouts to stderr of messages sent and received from the SDL suite and TTCN suite Postmaster. See also " POSTDEBUG. If events seem to be missing in an MSC Editor log, these may be used to determine if there is an unhandled error condition.
  • The MSC Editor has a built-in maximum number of simultaneously open diagrams. Since each test case generates a separate MSC diagram, this limit may eventually be reached when large numbers of test cases are run. The result of reaching this limit is not defined. As a consequence, it is recommended not to use MSC Editor logging when running large numbers of test cases.

Simulator on UNIX

The entire list of SDL to C Compiler limitations applies also to the Simulator, see "TTCN ASN.1 BER Encoding/Decoding" .

  • Monitoring of other test components can only be viewed together in the main screen log.
  • Test suite variables and timers cannot be modified or viewed.
  • The contents of channels cannot be modified.
  • An entire test suite cannot be selected for execution. You have to do this manually, for example by selecting all test groups or all test cases.
  • If you abort the execution of the TTCN-SDL Co-simulator when the SDL Simulator is running, further communication may be inhibited. Always restart the SDL Simulator when you abort the execution of the TTCN-SDL Co-simulator.

TTCN-SDL Co-Simulator

  • ASN.1 modules that have been joined/merged within the SDL system will not always work for SDL-TTCN Co-simulation, as the same join/merge functionality does not work the same way on the TTCN side. This means that name clashes will be solved differently on the SDL and the TTCN sides respectively.

TTCN Exerciser

Timer Duration Limitations

  • If a timer has a duration exceeding approximately 2000000000 (2^31-1) time units - as defined with the timer declaration - the condition may not be noticed, and it may result in erroneous behavior.
  • If a timer duration exceeds the theoretical maximum period, the condition may not be noticed, and it may result in erroneous behavior.

Value Encoding and Decoding Limitations

In general, the value encoding and decoding has been designed to be a general mechanism for reading and writing almost any value, including ones that are not part of the type system of a generated test suite. This is for being able to input totally unexpected or irregular messages. The consequence of this is also that it may be easy to "break" test suites or even the kernel by providing wildly unexpected message contents. In order to get valuable results of the simulation runs, there may be a bit of effort needed to specify the messages. While doing that, the following notes and limitations may be helpful to avoid some pitfalls:

  • There is limited error checking in the value encoding and decoding, which may result in ambiguous messages being encoded or decoded, or even possibly crashes if some invalid combinations are used.
    For example, if asp1 is an ASP (base type is sequence), then these value encodings are likely to cause a runtime error or crash if fed into the kernel:

asp1 24
IA5String TRUE

This error situation is not handled, since in general the kernel is designed to allow for arbitrary objects to be input. In the general case, the situation above will be created if assigning a refined type to an object with a different base type.
  • For simple types, the actual type name is not part of the encoding. This particular choice of implementation was made to improve the readability of encoded values, but it may result in ambiguities when decoding the same message.
    An example: The value VideotexString "Hello" is encoded as "Hello" only, without the actual type name. Decoding of the same message will result in an object with the default string type IA5String. In order to specify the actual type, use a prefix of the actual type, such as VideotexString "Hello".
  • ENUMERATED values are not encoded or decoded by name, but rather as integer values.
  • CHOICE values must be possible to distinguish by value, rather than by tag since tagging is not incorporated in the encodings and decodings of the TTCN Exerciser.
  • The type OBJECT IDENTIFIER is not supported.

Concurrent TTCN

  • There is a built-in limit in the TTCN Exerciser to how many concurrent test components may be simultaneously active. The limit is more than 10 but less than 25. The reason for this limit is the implementation of thread scheduling in which there is a built-in overhead which grows by the number of threads. There should be no problems running up to maybe 6-8 simultaneous test components, but more may seriously degrade the performance of the kernel. To work around this for real-time testing, do consider an alternative adaptation strategy at this time (using a deterministic and fair real-time system scheduler).
  • Cancelling a test case from the context of a parallel test component may lead to unexpected behavior (such as hanging or livelocked PTC threads). It is recommended to always run a concurrent test case to a SNAPSHOT state before cancelling.
  • Multiple readers/writers on a PCO or CP is not detected by the kernel, though it is a test case error according to TTCN.
  • The result of terminating the MTC prior to all PTCs have terminated is undefined. The condition should be reported by the TTCN Exerciser, but the test result may be invalid. Terminating the MTC prior to all MTCs are terminated is illegal according to TTCN.
  • There is no way to list the contents of a CP with the TTCN Exerciser.

TTCN Link

  • Encoding/Decoding functionality cannot be used together with the TTCN Link kernel.
  • ASN.1 modules that have been joined are not supported by TTCN Link.

Auto Link

  • ASN.1 modules that have been joined are not supported by Auto Link.

UML and MSC Restrictions

This section lists the major UML and MSC restrictions in the SDL suite, with respect to the OMG specification for UML, and the ITU-T recommendation for MSC.

References below are to sections in the OMG document "ad/99-06-08" (UML Notation Guide, version 1.3, June 1999), and the Z.120 recommendation.

UML Class Diagrams

The following features of UML 1.3 Static Structure (Class) diagrams are not supported:

  • Packages (section 3.13), but package references are allowed in class names
  • Interfaces (section 3.28)
  • Parametrized class, or template (section 3.29)
  • Composite objects (section 3.39)
  • Xor-associations (section 3.41.5)
  • Navigability in associations (section 3.42.2)
  • N-ary associations (section 3.46)
  • Constraints in generalizations (section 3.49.2)
  • Dependency, i.e. dashed arrows (section 3.50)

UML Statechart Diagrams

The following features of UML 1.3 Statechart diagrams are not supported:

  • Hidden decomposition indicator icon (section 3.76)
  • Substate compartment with concurrent states (section 3.76)
  • Transition times (section 3.78)
  • Concurrent transitions (section 3.79)
  • History state indicator (section 3.80)
  • Stubbed transitions (section 3.80)
  • Factored transition paths (section 3.81)
  • Submachine states (section 3.82)
  • Synch states (section 3.83)

UML Implementation Diagrams

The notation used in the DP Editor diagrams is based on UML 1.3 Implementation diagrams. The major differences are the following:

  • No dashed-arrow dependencies (on nodes and components)
  • No interfaces (on components)
  • No migration (of components from node to node or of objects from component to component)
  • No graphical nesting (only composite aggregation) to show containment
  • The thread concept has been added

MSC and HMSC

  • General ordering for events is not supported (Z.120 chapter 4.5).
  • Gates are not supported (Z.120 chapter 4.4).
  • Comment symbols in HMSC diagrams are not supported.
  • Parallel frames in HMSC diagrams are not supported (Z.120 chapter 5.5).

Tool Limitations

All Editors

  • Diagram names may not exceed 255 characters.

MSC Editor

  • The inline expressions always cover all instance axis. The reason for this limitation is that gates (and specifically inline gate interfaces) are not supported.
  • The column-form of instances and coregions is not supported, only the line-form.
  • The storage format for MSC diagrams has changed in this release. Version 3.5 of the MSC Editor can handle the same formats as version 3.4, but the 3.4 MSC Editor and earlier versions cannot read the new 3.5 MSC format.
    Make sure you have backup copies of your MSC diagrams in case you wish to continue working with version 3.4 or earlier for MSC diagrams saved with version 3.5.
  • A syntax error occurs when logging to MSC if an SDL page name contains two consecutive underscores, like "pg__name". Error message should begin, `MSCE: Service INSERTOBJECT failed.'

OM Editor

  • Use Browse&Edit Class dialog with care if the symbol contains syntax errors.
    The syntax checker on attributes and operations have error recovery functionality, and can sometimes "recover" in an unwanted way. Use the Browse&Edit Class dialog for editing purposes only with special care if a syntax error is detected. In the drawing area, syntax errors are highlighted with a red underlining in the symbol's corresponding text compartments. The browsing functionality of the Browse&Edit Class dialog can however be used without considerations even if syntax errors are detected.

Text Editor

  • When you edit large portions of text containing many endpoints, updates can become slow in the Text Editor.
    As a work-around, turn off endpoint display if you encounter performance problems.


Telelogic Tau 4.4

SDL Suite
Methodology Guidelines


Introduction

About this Manual

This volume, SDL Suite Methodology Guidelines, contains some practical guidelines on how to use SDL and related notations in software development using the SDL suite.

The SDL-92 object oriented concepts are introduced, including converting an SDL-88 system into SDL-92. Some Telelogic-specific extensions to SDL are described, as well as the handling of SDL, C and ASN.1 data types in the SDL suite. Finally, how to manage the diagram files in a project that includes several project members is explained and exemplified.

Documentation Overview

A general description of the Telelogic Tau documentation can be found in "Telelogic Tau Documentation".

Typographic Conventions

The typographic conventions that are used in the Telelogic Tau documentation are described in "Typographic Conventions".

How to Contact Customer Support

Detailed contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".


1 Object Oriented Design Using SDL

This methodology chapter will take you into the world of object oriented SDL, as introduced in the 1992 version of the language. It will follow one case (a simple Access Control system) from the specification to the final SDL design. A simple OO analysis (according to the SOMT method) is performed, followed by an object oriented design using SDL.

The object oriented SDL concepts are introduced step by step by developing different versions of the Access Control system. The first version will make use of the OO concepts block types and process types only. The final version will use more advanced OO concepts, such as inheritance (specialization), virtual types and type libraries (package diagrams).

Note that this chapter does not deal with all parts of the SOMT method described in the SOMT Methodology Guidelines in chapters 68-76 in the User's Manual; it mainly focuses on the usage of object oriented SDL in the design activities of SOMT.


Requirements on the Access Control System

This section should only be viewed as a background for the design of the system and not as a description of a complete requirements analysis phase.

Description of the System to be Built

This application is chosen because it is a good example of an embedded system, with features that make it very suitable to be specified using SDL and the object oriented extensions (introduced in the 1992 version of the language).

The Access Control system is a system to control the access to a building. To enter the building, a user must have a registered card and a personal code (four digits). The device used for entering the card and personal code consists of a card reader, a keypad and a display.

The main characteristics of the system are:

  • Moderate real-time demands
  • Mostly signal oriented
  • Simple data representation
  • Simple interface to the environment (hardware)
  • A non-distributed system
  • Adding new features to the system can be achieved in an easy way by adding new program logic, while the interface to the environment remains the same
  • The system can be simulated in the host environment by using a graphical user interface (see Figure 1).

Figure 1 : Graphical interface to the Access Control system

Textual Requirements

This description serves as an initial set of requirements. These requirements are normally collected and refined to a standardized form to make the requirements analysis easier to deal with and each requirement easier to refer to. Only the initial set of requirements will be shown for this simple example.

We will also focus only on the functional requirements and leave out the non-functional requirements (like performance, reliability, availability, etc.).

Basic Requirements

The hardware devices consists of the following components:

  • An 8751 microcontroller
  • 64 kilobytes of program memory (RAM or ROM)
  • 64 kilobytes of data memory (RAM)
  • A card reader for credit cards
    The card reader reads track 2. Data is stored as 40 five-bit words according to the most common standard.
  • A keypad
    The keys are organized according to normal telephone standard. Valid keys are the digits 0-9. In the basic version, the function keys "*" and "#" are not recognized.
  • A display unit
    The display unit can display 2 lines each consisting of 16 characters.
  • 4 LEDs
    Four light emitting diodes will indicate the status of the controlled doors. Off = closed, on = open.

The system should be able to fulfill the following tasks for a user:

  • Reading the code on the back of a standard credit card.
  • Reading a personal code, consisting of 4 digits, typed from the keypad.
  • Validate that the card and the personal code are registered.
  • If the system is configured to control more than one door, give the user the possibility to choose which door to open after the card and code have been validated.

The system should be able to fulfill the following tasks for a system administrator/supervisor:

  • Registration of a user card and a personal code. Only one code is allowed for each user card.
  • Registration of the supervisor card at system startup time. Only one supervisor card is allowed for each system.

General requirements:

  • The system must be designed in such a way that it is easy, at system generation time, to configure the system to handle from one to four doors.

Additional Requirements

The system should be able to fulfill the following tasks for a user:

  • Displaying time.
  • Displaying which category (see below) of card is valid in the current situation.

The system should be able to fulfill the following tasks for a system administrator/supervisor:

  • Stopping the opening of one door (only the supervisor can open the door after this).
  • Stopping the opening of all doors (only the supervisor can open a door after this).
  • Removing the blocking of one or all the doors.
  • Allowing free access through one or several doors.
  • Specifying different categories of cards permitting different access possibilities during a 24-hour period
  • Displaying the time.
  • Setting of the current time.
  • Blocking a user card.
  • Remove the blocking of a user card.

Use Cases

The most interesting functional requirements are described by a number of use cases. These use cases describe the interaction between the system and its environment and formalizes (to some extent) the functional requirements.

The outside entities that communicate with the system are usually called the actors of the use cases. Actors are often

  • human users
  • other systems
  • hardware

There are two different actors of the Access Control system that are relevant (the hardware is not taken into account in this simple example): user and supervisor.

  • The user functions are the services available for all users, such as reading the card code, reading the four digit personal code, etc.
  • The supervisor functions are only available for suitable privileged personnel (e.g. a supervisor) and perform services such as registration of a new card and code.

The use cases could be described either textually or by MSCs or by a combination of the two notations. An example of a use case with the user actor is the Open Door use case (described by the MSC OpenDoor in Figure 2). The use case ends with the fulfillment of the goal of the use case: the opening of the door.

Figure 2 : Requirements use case OpenDoor

Use cases that describe requirements usually show only the interaction between the actors and the system. When the use cases are refined in later activities, they can also express the inner behavior of the system.

Object Model

The requirements object model is a simple object model that relates the known domain entities of an access control system and its environment. The environment of the system could be anything that is related to the system as long as it is relevant for understanding the problem, typically the actors of the use cases that describe the wanted behavior of the system. The objective of the model is to give a simple picture of the problem without going into details.

Figure 3 : Requirements object model

When elaborating the requirements object model into an analysis object model, concern about the system properties rather than the real world properties will affect the model. In the requirements activity, it is not known what a certain class will result in or if it should be modeled at all. When analyzing the requirements and the system to be built, classes can be mapped to software entities, hardware entities or not mapped at all.


System Analysis of the Access Control System

The system analysis is based on the results after analyzing the requirements and the problem domain on a high level. The models in the system analysis focuses more on the internal structure of the system to be built, without taking design decisions (or at least as few as possible).

Analysis Object Model: Basic Version

The inheritance concept is not used in the basic version because the information that needs to be modeled has a very simple structure. What can be seen in Figure 4 is the aggregation and the association relations between the classes and the attributes and operations for the individual classes.

Compared to the requirements object model, the following changes have been made:

  • The actors are removed from the object model to simplify the reading.
  • Classes have been structured in a way that makes the mapping to an SDL design easier. Especially the aggregation hierarchy is designed with this in mind; the structure will basically be kept when making an SDL design.
  • Classes from the requirements object model that are redundant (only introduced to increase the understanding of the problem) are removed.
  • A difference between active and passive objects has been taken into account. The active objects have behavior while the passive objects only have data structure and data manipulation. The classes in the aggregation hierarchy are all active, while the classes in the information structure are passive.
  • Attributes and operations have been added to the classes.
  • The analysis object model is structured into three parts, each part showing a different view of the relationship between the classes: containment, communication and information.

Figure 4 : The analysis object model of the Access Control system (basic version)

The Analysis Use Case Model

The following MSC describes the use case for opening a door and is a part of the complete analysis use case model. The level of granularity can either be very detailed (each involved leaf object is represented by an MSC instance) or general (each subsystem of the aggregation hierarchy is described by an instance). This choice between readability and expressiveness is dependent of the application area and design customs. In this case, the subsystem representation was chosen (see Figure 2).

Figure 5 : Analysis use case OpenDoor

Note that the MSC instances are, in fact, instances, i.e. they represent objects. To indicate this, the naming of the instances include both an object name and the correspondent class name.

It should also be noticed that all MSC messages do not map strictly to class operations. In some cases, the operation is synchronous, that is demands a return message. This return message is also described in the MSC use case in Figure 2 (e.g. the operation ValidateCard is described by the messages ValidateCard and OK).

Analysis Object Model: Enhanced Version

The following example is how an analysis of the additional requirement of time handling can be performed. The addition of a clock function will mainly add a new operation to the class Display (display of current time). A new class Clock must also be introduced. The properties of this class handle the clock and update the current time. Figure 6 describes the enhanced analysis object model for the Access Control system.

When adding behavior, the other models must of course also be extended, including the internal textual requirements and the use case models of the requirements and system analysis.

Figure 6 : The analysis object model of the Access Control system
(extended version with time handling)


Object Oriented Design of the Access Control System

System Design

The system design activity aims at producing a design architecture and to refine the use cases into use cases that could give a better help during the detailed design. Another purpose for refining the use cases is to make them suitable for verifying the design by means of the SDL Validator functionality Verify MSC.

Since the goal of this methodology handbook is to describe the object oriented features of SDL during the design, the description of a complete system design has been left out.

Object Design

We will now introduce the new SDL concepts step by step.

  • In the first version of the Access Control system we will only use the new type concept for blocks and processes.
  • In Version 2 we will make use of the new procedure concepts, such as remote procedures, value returning procedures and global procedures. We will also introduce the package concept, the specialization concept and the virtual concept.

Version 1: Block Types and Process Types

According to the analysis object model, the top class of the aggregation hierarchy has been mapped to an SDL system. The leaf nodes of the aggregation hierarchy have been mapped to processes and the classes between the top and the leave nodes have been SDL blocks. Note that even if there are no classes between the top class and a leave class in an aggregation chain, an SDL process still has to be contained in an SDL block.

Six processes (CardReader, Controller, Display, Door, KeyPad and RegisteredCard) have been identified from the analysis object model and three blocks (LocalPanel, Doors and RegisteredCard) have been created in order to preserve the structure described by the aggregation hierarchy of the analysis object model (see Figure 7).

Figure 7 : System diagram AccessControlOOA

Block Types and Process Types

A type definition can be placed anywhere in a system. For this example, the choice was to place them on the system level so that they will have maximum visibility. Normally, they would have been placed in separate packages to support parallel editing and analysis of the separate subsystems (block types).

To place a type at a high level (in a system or package) means that they can be instantiated anywhere where they are visible, and also be used for specialization anywhere in the system.

Block Type LocalPanel

Even if the types are placed on the same level, the structure is kept by instantiating the types according to the analysis object model. This means that the instantiation of the process types CardReader, Display, KeyPad and Controller is made inside the block type LocalPanel (see Figure 8).

Figure 8 : The block type LocalPanel

Block Type RegisteredCard

The block type RegisteredCard will only contain an instance of the process type RegisteredCard. It is perfectly legal in SDL to use the same name for a block type and a process type because they are of different entity classes (see Figure 9).

Figure 9 : The block type RegisteredCard

The Classes CardDBType and CardType

As previously mentioned there are classes that will mainly contain data and data manipulation operations. The classes CardDBType and CardType are of this type and they are implemented in the design as abstract data types. The data type CardDbType has a number of operators defined to validate a card and a code, and to register a new card and a new code. These operators are implemented in-line, as "C" functions (see Figure 10).

Figure 10 : The data types CardType and CardDbType

An instance of the type CardDbType is declared in the process type RegisteredCard. The operations ValidateCard, ValidateCode and RegisterCardAndCode for the class RegisteredCard are now implemented as operators for the data type CardDbType (see Figure 11).

Figure 11 : Call of operators inside the Process RegisteredCard

Block Type Doors and Process Type Door

A requirement for the Access Control system is that it should be able to control up to four doors. In our object oriented SDL design, this can be accomplished by creating a block set of the block type Doors. The Synonym NOOFDOORS is by default 1 but can be assigned any value between 1 and 4. Block type Doors consists of an instance of the process type Door. To follow the OO analysis, the process type Door will control how long a door should be opened (attribute DoorTimeOut) and also the opening and closing of a door (operations OpenDoor and CloseDoor).

Version 2: Procedures, Specialization and Packages

A general rule when designing an SDL process is to keep the transitions as short as possible. Using procedures is often the solution.

The Use of Procedures in Version 1

In the first version procedures are frequently used and we shall now take a look at two of them, namely RegisterCard and ReadCode. Both are declared and called by the Controller process.

Procedure RegisterCard

This procedure is called when a new card should be registered (user cards or the supervisor's credit card). The function of this procedure is as follows:

  • First it calls the procedure ReadCode to read the four user digits in the user's code.
  • In the case of a successful return from the ReadCode (ReadCodeResult=Successful), send a request for the registration of a new card (signal RegisterCardAndCode) to the process RegisteredCard.
  • Wait for the result of the Registration (return signals Registered or NotRegistered) and return (see Figure 12).

Figure 12 : Procedure RegisterCard

Procedure ReadCode

This is a procedure to read four digits from the keypad. The digits read will be stored in an array named CodeData. If four digits are successfully received, the ReadCodeResult is assigned "Successful", and a return to the calling process or procedure will take place.

This procedure is called both by the procedure RegisterCard and by the process Controller in the sequence of validating card and code (see Figure 13).

Figure 13 : Procedure ReadCode

Remote Procedures and Value Returning Procedures

The idea in version 2 is to move the procedure RegisterCard from the process Controller to the process RegisterCard. There are two reasons for doing this:

  1. This is the most natural place for it, because this procedure is called whenever a card is to be registered.
  2. No signals have to be exchanged between process Controller and process RegisterCard to announce when to start and stop the registration procedure.

The procedure ReadCode must also be moved, because there will be a deadlock situation when the RegisterCard procedure calls the ReadCode procedure.

Note:

When a process calls a remote procedure, it enters a new implicit state where it will wait for an (implicit) return signal indicating that the procedure call has been executed. Any new signals, including calls to remote procedures, will be saved. This can easily lead to deadlock situations!

The ReadCode procedure can be placed in the KeyPad process and FlashMessage (another procedure also called by the RegisterCard) can be placed in the Display process.

Remote Procedures in SDL

Normally a procedure can only be called from the declaring process (or procedure) but by declaring it as EXPORTED it can be called from any process or procedure in the system. The remote procedure concept is modeled with an exchange of signals.

The Save Concept

The service process (the process with the EXPORTED procedure) can only handle a remote procedure call when it is in a state. If it is essential that a process is not interrupted with a remote procedure call in certain states, it is possible to use the SAVE symbol to save the call and handle it in a later state. This will mean that you cannot be sure that a remote procedure call will be handled directly. The model for the calling process is also that a new implicit state is introduced for each remote procedure call. The process will remain in this state until the remote procedure call is handled and executed.

How to Declare an Exported Procedure

  1. Declare it as EXPORTED in the procedure heading.
  2. Make an import procedure specification in each process/procedure that wants to call the remote procedure.
  3. Introduce the name and signature (FPAR) of exported and imported procedures by making a remote procedure definition. This could be done in the system diagram, in a block diagram or inside a package. This declaration determines the visibility of the remote procedure by placing it in a certain scope.

Figure 14 : Declaration of a remote procedure

Value Returning Procedures in SDL

Any procedure can be called as a value returning procedure provided the last parameter is of IN/OUT type. The recommended way is to declare it as value returning if it is intended to be used as such. A call to a value returning procedure can be used directly in an expression, e.g. in an assignment (see Figure 15).

Figure 15 : Use of value returning procedures

In version 2 we have declared the procedure ReadCode as a value returning procedure, and it will return a ReadCodeResultType value. We want to return this result from the procedure RegisterCard also, so we save it in a variable. (See Figure 15.)

Global Procedures in SDL

A procedure can also be defined globally in SDL. The conceptual model is that a local copy of the procedure is created in each process where it is called.

A Global Procedure for Sending a Signal

It is mostly the process Controller that displays messages. But the procedure RegisterCard (in process RegisteredCard) and the process Door also send messages.

The process Controller acts as an intermediate conveyer of the signal Display to the process Display in version 1. It is tempting to declare a global procedure that can send any message on the signal Display, and to call this procedure from process Display, process Door and the procedure RegisterCard. Unfortunately, this will not work. The reason is the above mentioned model with the creation of an implicit local model of the procedure. Calling the procedure from, for example, the process Door will in fact result in sending the signal from the calling process. Besides obscuring the signal sending, nothing will be gained by this; the signal must still be declared on the outgoing channel, etc. An alternative is of course to declare the procedure as an EXPORTED procedure and call it as a Remote procedure, but the remote procedure concept should be used with moderation and definitely not in this case, with the sole purpose of hiding signal sending.

When to Use the Different Kinds of Procedures

Local Procedures

  • To keep the transitions short in order to highlight the signal interactions.
  • To describe local routines.

Remote and Value Returning Procedures

  • To make a local routine globally accessible.
  • Use value returning procedures to simplify expressions.
  • Use remote procedure calls instead of signals to access and manipulate data.

Global Procedures

  • An alternative to macros.
  • An alternative to a remote procedure if there is no natural "owner" of the procedure.

Specialization: Adding/Redefining Properties

One of the major benefits of using an object oriented language is the possibility to, in a very simple and intuitive way, create new objects by adding new properties to existing objects, or to redefine properties of existing objects. This is what is commonly referred to as specialization.

In SDL, specialization of types can be accomplished in two ways:

  • A subtype may add properties not defined in the supertype. One may, for example, add new transitions to a process type1, add new processes to a block type, etc.
  • A subtype may redefine virtual types and virtual transitions defined in the supertype. One may, for example, redefine the contents of a transition in a process type, redefine the contents/structure of a block type, etc.

Behavior (i.e. transitions) can be added to a process type using the adding mechanism. For example, the process type TimeDisplay (Figure 16) is a subtype of Display with the addition of a new transition. The keyword INHERITS defines the new type DisplayTime as a subtype of Display, stating that all definitions inside the process type Display is inherited by DisplayTime.

The gates A and B are dashed in order to indicate that they refer to the gate definitions in the process type Display, with the addition of the signal DisplayTime.

Figure 16 : The process type TimeDisplay

In some cases it may be necessary not only to add properties, but also to redefine properties of a supertype. In Figure 16, the process type Door has to be redefined in order to send the signals OpenDoor and CloseDoor respectively to the new process DoorOpener. Therefore, the corresponding transitions of Door have to be defined as virtual transitions, as depicted in Figure 17.

Figure 17 : The process type Door with virtual transitions

Then, in the definition of the new block type SpecialDoor, the corresponding transitions of the process type Door are redefined as shown in Figure 18.

Figure 18 : The redefined process type Door

In addition to virtual transitions, it is also possible to specify start transitions, saves, continuous signals, spontaneous transitions, priority inputs, remote procedure inputs and remote procedure saves as virtual. All of the above concepts have in common that they define how a transition should be initiated or if it should be initiated (Save). Furthermore, a virtual save can be redefined into an input transition or vice versa.

Example: Adding a Clock to the Access Control System

The Access Control system described in the previous sections can be extended to contain a clock which holds the current time. The time is displayed on the display in the format "HH:MM", and the time can be set from the panel by first entering a "#" followed by the time in the format "HHMM".

After an analysis of the problem, e.g. using OOA as described earlier, it is decided that the clock functionality is easiest realized by adding a clock to the local panel. Each minute the clock sends the current time to the controller, which displays the time on the display. Furthermore, the controller is extended to cope with the setting of the time from the key pad.

In order to apply the SDL concepts of specialization to this problem, the original access control specification has to be slightly modified. Since an access control system containing a clock can be regarded as a specialization of the original access control specification, it must be possible to inherit the properties of the original access control system when defining the new system. Therefore, it is necessary that the original Access Control system is defined as a system type (named BaseAccessControl), as depicted in Figure 19.

Figure 19 : The system type BaseAccessControl

Since the specialization of BaseAccessControl requires changes to the block type LocalPanel, it is defined as virtual. For the same reason, the process types used in the block type LocalPanel (i.e. CardReader, Display, KeyPad and Controller) are all defined as virtual. Finally, for reasons of clarity, the definitions of process types that previously where made on the system level are now made in the block types where they are used.

Now, a definition of the access control system containing a clock (named TimeAccessControl) can be based on the system type BaseAccessControl, as depicted in Figure 20.

Figure 20 : The system type TimeAccessControl

The system type TimeAccessControl inherits BaseAccessControl with the addition of a new signal DisplayTime, which is sent from the block Lp (of type LocalPanel) to the environment. Furthermore, the block type LocalPanel is redefined in TimeAccessControl; as depicted in Figure 21.

Figure 21 : The redefined block type LocalPanel

LocalPanel is redefined to contain a process Clock which sends the signal DisplayTime to Cl (of type Controller) and receives the signal SetTime from Cl. Furthermore, Cl is extended to send the signal DisplayTime to Dl (of type Display), which in turn sends it on to the environment via gate C.

The redefinition of Display is straightforward. As depicted in Figure 22, a new transition for the signal DisplayTime is added.

Figure 22 : The redefined process type Display

The redefinition of Controller (Figure 23) involves two issues: the addition of functionality to treat the signal DisplayTime, and the addition of functionality to read a new time from the KeyPad and correspondingly set the clock.

Figure 23 : The redefined process type Controller

To cope with the signal DisplayTime, a transition is added to every state that, upon receipt of DisplayTime, sends it on to the process Dl (via gate E). Furthermore, a transition for the signal ReadCode is also added to state Idle in order to realize the setting of the clock. If the key pressed on the key pad is "#" then the new time is read (in the procedure ReadTime). If the new time was read successfully, then the signal SetTime is sent to the process Clock.

Finally, the process Clock is defined as depicted in Figure 24.

Figure 24 : The process Clock

The variable CurrentTime of type Time, holds the current time in minutes. Every minute (duration 60), a timer expires which causes the variable CurrentTime to be incremented by 1, and the signal DisplayTime to be sent to process Cl. Receipt of the signal SetTime causes the variable CurrentTime to be updated with the new value. Since the time outside process Clock (i.e. the parameter of the signals DisplayTime and SetTime) is represented as a charstring, there is a need for functions converting Time to Charstring and vice versa. These functions can be defined in the following way:

NEWTYPE TimeOperators
LITERALS Dummy;
OPERATORS
TimeToString : Time -> Charstring;
/* Converts time to Charstring. The result
is on the form 'HH:MM' */
/*#OP (B) */

StringToTime : Charstring -> Time;
/* Converts Charstring to Time. Assumes that
the Charstring is on the form 'HHMM'. */
/*#OP (B) */
/*#ADT (B)
#BODY

SDL_Charstring #(TimeToString)(T)
SDL_Time T;
{
SDL_Charstring result:=NULL;
int Hours, Minutes;
char tmp1[4], tmp2[4];

Hours = (T.s/60/60)%24;
Minutes = (T.s/60)%60;
tmp1[0]='V';
tmp2[0]='V';
sprintf(&(tmp1[1]),"%2ld",Hours);
sprintf(&(tmp2[1]), "%2ld",Minutes);
xAss_SDL_Charstring(&result,tmp1,XASS);
xAss_SDL_Charstring(&result,xConcat_SDL_Charstring(result,xMkString_SDL_Charstring(`:')));
xAss_SDL_Charstring(&result,xConcat_SDL_Charstring(result,tmp2));
result[0]='V';
if(Hours<10)
result[1]='0';
if(Minutes<10)
result[4]='0';
return result;
}

SDL_Time #(StringToTime)(C)
SDL_Charstring C;
{
SDL_Time T;
SDL_Charstring tmpstr;
tmpstr=xSubString_SDL_Charstring(C,1,2);
T.s = atoi(++tmpstr)*60*60;
tmpstr=xSubString_SDL_Charstring(C,3,2);
T.s = T.s + atoi(++tmpstr)*60;
return T;
}
*/
ENDNEWTYPE;

Packages

The concept of packages enables a mechanism to handle a collection of different types. The different type definitions that are possible to define in a package are:

  • Diagram types (system type, block type, process type, service type and procedure)
  • Abstract data types and synonyms
  • Signals and signal lists

The definitions in a package are included into the system (or into another package) by a USE clause.

The SDL Analyzer supports semantic analysis for packages. This means that large systems can be divided into several packages to enable a more easy handling of large projects.

An important thing to remember is that it must be possible to analyze a type where it is defined. This means that if a process type is placed in a package, the data types and signals that the process type uses must also be visible in the package. In Figure 25, the use of packages are exemplified.

Figure 25 : The use of packages in the Access Control system

1

SDL differs from most other object oriented languages in the sense that SDL offers possibilities to specialize behavior specifications. In most other languages this is accomplished by redefining virtual methods in subclasses; in SDL this is easily accomplished by adding new transitions to a process type.


2 Data Types

This chapter describes how data types are handled in the SDL suite. An overview of all supported SDL data types is given, including examples and guidelines. It is also explained how to use C/C++ and ASN.1, in combination with the SDL suite.

Important!

Please note that the H2SDL utility is replaced with the more flexible and improved CPP2SDL utility described in The CPP2SDL Tool.


Introduction

An important and often difficult aspect of system design and implementation is how to handle data in the system.

The SDL suite offers several ways to use data:

  • SDL-specific data types can be used
  • Access to C/C++ data types and functions is supported
  • ASN.1 data types can be used

This chapter gives an overview of all available data types, together with some guidelines of how to use these different data types, illustrated with a number of examples.


Using SDL Data Types

In this section, an overview is given of the data types that are available in SDL. SDL contains a number of predefined data types. Based on these predefined types it is possible to define user-specific data types. Types, or according to SDL terminology, "sorts", are defined using the keywords newtype and endnewtype.

Example 1 : Newtype definition

newtype example1 struct
a integer;
b character;
endnewtype;

A newtype definition introduces a new distinct type, which is not compatible with any other type. So if we would have another newtype otherexample with exactly the same definition as example1 above, it would not be possible to assign a value of example1 to a variable of otherexample.

It is also possible to introduce types, syntypes, that are compatible with their base type, but contain restrictions on the allowed value set for the type. Syntypes are defined using the keywords syntype and endsyntype.

Example 2 : Syntype definition

syntype example2 = integer
constants 0:10
endsyntype;

The syntype example2 is an integer type, but a variable of this type is only allowed to contain values in the specified range 0 to 10. Such a constant clause is called a range condition. The range check is performed when the SDL system is interpreted. Without a range condition a syntype definition just introduces a new name for the same sort.

For every sort or syntype defined in SDL, the following operators are always defined:

  • := (assignment)
  • = (test for equality)
  • /= (test for non-equality)

These operators are not mentioned among the available operators in the rest of this section. Operators are defined in SDL by a type of algebra according to the following example:

"+" : Integer, Integer -> Integer;
num : Character -> Integer;

The double quotes around the + indicate that this is an infix operator. The above + takes two integer parameters and returns an integer value. The second operator, num, is a prefix operator taking one Character and returning an Integer value. The operators above can be called within expressions in, for example, task statements:

task i := i+1;
task n := num('X');

where it is assumed that i and n are integer variables. It is also allowed to call an infix operator as a prefix operator:

task i := "+"(i, 1);

This means the same as i:= i+1.

Predefined Sorts

The predefined sorts in SDL are defined in an appendix to the SDL Recommendation Z100. Some more predefined sorts are introduced in the Recommendation Z105, where it is specified how ASN.1 is to be used in SDL. These types should not be used if the SDL system must conform to Z.100. The SDL suite also offers Telelogic-specific operators for some types. These operators should not either be used if your SDL system must be Z.100 compliant. The rest of this chapter describes all predefined sorts. Unless stated otherwise, the sort is part of recommendation Z.100.

Bit

The predefined Bit can only take two values, 0 and 1. Bit is defined in Z.105 for the definition of bit strings, and is not part of Z.100. The operators that are available for Bit values are:

"not" : Bit -> Bit
"and" : Bit, Bit -> Bit
"or" : Bit, Bit -> Bit
"xor" : Bit, Bit -> Bit
"=>" : Bit, Bit -> Bit

These operators are defined according to the following:

  • not :
    inverts the bit; 0 becomes 1 and 1 becomes 0,
    not 0 gives 1, not 1 gives 0
  • and :
    if both parameters are 1, the result is 1, else it is 0,
    0 and 0 gives 0, 0 and 1 gives 0, 1 and 1 gives 1
  • or :
    if both parameters are 0, the result is 0, else it is 1,
    0 or 0 gives 0, 0 or 1 gives 1, 1 or 1 gives 1
  • xor :
    if parameters are different, the result is 1, else it is 0,
    0 xor 0 gives 0, 0 xor 1 gives 1, 1 xor 1 gives 0
  • => (implication) :
    if first parameter is 1 and second is 0, the result is 0, else it is 1,
    0 => 0 gives 1, 1 => 0 gives 0, 0 => 1 gives 1, 1 => 1 gives 1

The Bit type has most of its properties in common with the Boolean type, which is discussed below. By replacing 0 with false and 1 with true the sorts are identical.

Bit and Boolean should be used to represent properties in a system that can only take two values, like on - off. In the choice between Bit and Boolean, Boolean is recommended except if the property to be represented is about bits and the literals 0 and 1 are more adequate than false and true.

Bit_string

The predefined sort Bit_string is used to represent a string or sequence of Bits. Bit_string is defined in Z.105 to support the ASN.1 BIT STRING type, and is not part of Z.100. There is no limit on the number of elements in the Bit_string.

The following operators are defined in Bit_string:

mkstring : Bit -> Bit_string
length : Bit_string -> Integer
first : Bit_string -> Bit
last : Bit_string -> Bit
"//" : Bit_string, Bit_string -> Bit_string
substring : Bit_string, Integer, Integer
-> Bit_string
bitstr : Charstring -> Bit_string
hexstr : Charstring -> Bit_string
"not" : Bit_string -> Bit_string
"and" : Bit_string, Bit_string -> Bit_string
"or" : Bit_string, Bit_string -> Bit_string
"xor" : Bit_string, Bit_string -> Bit_string
"=>" : Bit_string, Bit_string -> Bit_string

These operators are defined as follows:

  • mkstring :
    This operator takes a Bit value and converts it to a Bit_string of length 1.
    mkstring (0) gives a Bit_string of one element, i.e. 0
  • length :
    The number of Bits in the Bit_string passed as parameter.
    length (bitstr('0110')) = 4
  • first :
    The value of the first Bit in the Bit_string passed as parameter. If the length of the Bit_string is 0, then it is an error to call the first operator.
    first (bitstr ('10')) = 1
  • last :
    The value of the last Bit in the Bit_string passed as parameter. If the length of the Bit_string is 0, then it is an error to call the last operator.
    last (bitstr ('10')) = 0
  • // (concatenation) :
    The result is a Bit_string with all the elements in the first parameter, followed by all the elements in the second parameter.
    bitstr('01')//bitstr('10') = bitstr('0110')
  • substring :
    The result is a copy of a part of the Bit_string passed as first parameter. The copy starts at the index given as second parameter. The first Bit has index 0. The length of the copy is specified by the third parameter. It is an error to try to access elements outside of the true length of the first parameter.
    substring (bitstr('0110'), 1, 2) = Bitstr('11')
  • bitstr :
    This Telelogic-specific operator converts a charstring containing only characters 0 and 1, to a Bit_string with the same length and with the Bit elements set to the corresponding values.
  • hexstr :
    This Telelogic-specific operator converts a charstring containing HEX values (0 -9, A-F, a-f) to a Bit_string. Each HEX value is converted to four Bit elements in the Bit_string.
    hexstr('a') = bitstr('1010'),
    hexstr('8f') = bitstr('10001111')
  • not :
    The result is a Bit_string with the same length as the parameter, where the not operator in the Bit sort has been applied to each element, that is each element has been inverted.
    not bitstr ('0110') = bitstr ('1001')
  • and :
    The result is a Bit_string with the same length as the longest of the two parameters. Each Bit element in the result is computed by applying the and operator in Bit sort to the corresponding Bit elements in the parameters. This calculation is performed up to the length of the shortest parameter. The remaining Bits in the result (if any) are set to 0.
    bitstr('01101') and bitstr('101') = bitstr('00100')
  • or :
    The result is a Bit_string with the same length as the longest of the two parameters. Each Bit element in the result is computed by applying the or operator in Bit sort to the corresponding Bit elements in the parameters. This calculation is performed up to the length of the shortest parameter. The remaining Bits in the result (if any) are set to 1.
    bitstr('0110') or bitstr('00110') = bitstr('01111')
  • xor :
    The result is a Bit_string with the same length as the longest of the two parameters. Each Bit element in the result is computed by applying the xor operator in Bit sort to the corresponding Bit elements in the parameters. This calculation is performed up to the length of the shortest parameter. The remaining Bits in the result (if any) are set to 1.
    bitstr('10100') xor bitstr('1001') = bitstr('00111')
  • => (implication) :
    The result is a Bit_string with the same length as the longest of the two parameters. Each Bit element in the result is computed by applying the => operator in Bit sort to the corresponding Bit elements in the parameters. This calculation is performed up to the length of the shortest parameter. The remaining Bits in the result (if any) are set to 1.
    bitstr ('1100') => bitstr ('0101') = bitstr ('0111')

It is also possible to access Bit elements in a Bit_string by indexing a Bit_string variable. Assume that B is a Bit_string variable. Then it is possible to write:

task B(2) := B(3);

This would mean that Bit number 2 is assigned the value of Bit number 3 in the variable B. Is is an error to index a Bit_string outside of its length.

Note:

The first Bit in a Bit_string has index 0, whereas most other string types in SDL start with index 1!

Boolean

The newtype Boolean can only take two values, false and true. The operators that are available for Boolean values are:

"not" : Boolean -> Boolean
"and" : Boolean, Boolean -> Boolean
"or" : Boolean, Boolean -> Boolean
"xor" : Boolean, Boolean -> Boolean
"=>" : Boolean, Boolean -> Boolean

These operators are defined according to the following:

  • not :
    inverts the value.
not false = true
not true = false
  • and :
    If both parameters are true then the result is true, else it is false.
false and false = false
false and true = false
true and false = false
true and true = true
  • or :
    If both parameters are false then the result is false, else it is true.
false or false = false
false or true = true
true or false = true
true or true = true
  • xor :
    If parameters are different then the result is true, else it is false.
false xor false = false
false xor true = true
true xor false = true
true xor true = false
  • => (implication) :
    If the first parameter is true and second is false then the result is false, else it is true.
false => false = true
false => true = true
true => false = false
true => true = true

The Bit sort, discussed above, has most of its properties in common with the Boolean sort. By replacing 0 with false and 1 with true the sorts are identical. Normally it is recommended to use Boolean instead of Bit; for a more detailed discussion see "Bit" .

Character

The character sort is used to represent the ASCII characters. The printable characters have literals according to the following example:

'a' '-' '?' '2' 'P' ''''

Note that the character ' is written twice in the literal. For the non-printable characters, specific literal names have been included in the Character sort. The following:

NUL, SOH, STX, ETX, EOT, ENQ, ACK, BEL,
BS, HT, LF, VT, FF, CR, SO, SI,
DLE, DC1, DC2, DC3, DC4, NAK, SYN, ETB,
CAN, EM, SUB, ESC, IS4, IS3, IS2, IS1

correspond to the characters with number 0 to 31, while the literal

DEL

corresponds to the character number 127.

The operators available in the Character sort are:

"<" : Character, Character -> Boolean;
"<=" : Character, Character -> Boolean;
">" : Character, Character -> Boolean;
">=" : Character, Character -> Boolean;
num : Character -> Integer;
chr : Integer -> Character;

The interpretation of these operators are:

  • <, <=, >, >= :
    These relation operators work with the character numbers according to the ASCII table.
  • num :
    This operator converts a Character value to its corresponding character number. For example: num('A') = 65
  • chr :
    This operator converts an Integer value to its corresponding character. If the parameter is less than 0 or bigger than 255, it is first taken modulo 256 (using the mod operator in sort Integer). For example:
    chr(65) = 'A'

In Z.100 characters in the range 0 to 127 are supported. However Telelogic has introduced support for characters in the range 0 to 255. This means two things

The operator num works modulo 256, not modulo 128 as it is defined in Z.100.

The following literals (128 to 255) are added to the Character sort:

E_NUL, E_SOH, E_STX, E_ETX, E_EOT, E_ENQ, E_ACK, E_BEL,
E_BS, E_HT, E_LF, E_VT, E_FF, E_CR, E_SO, E_SI,
E_DLE, E_DC1, E_DC2, E_DC3, E_DC4, E_NAK, E_SYN, E_ETB,
E_CAN, E_EM, E_SUB, E_ESC, E_IS4, E_IS3, E_IS2, E_IS1,
' ', '¡', '¢', '£', '¤', '¥', '¦', '§',
'¨', '©', 'ª', '«', '¬', '\x7f ', '®', '¯',
'°', '±', '²', '³', '´', 'µ', '¶', '·',
'¸', '¹', 'º', '»', '¼', '½', '¾', '¿',
'À', 'Á', 'Â', 'Ã', 'Ä', 'Å', 'Æ', 'Ç',
'È', 'É', 'Ê', 'Ë', 'Ì', 'Í', 'Î', 'Ï',
'Ð', 'Ñ', 'Ò', 'Ó', 'Ô', 'Õ', 'Ö', '× ',
'Ø', 'Ù', 'Ú', 'Û', 'Ü', 'Ý', 'Þ', 'ß',
'à', 'á', 'â', 'ã', 'ä', 'å', 'æ', 'ç',
'è', 'é', 'ê', 'ë', 'ì', 'í', 'î', 'ï',
'ð', 'ñ', 'ò', 'ó', 'ô', 'õ', 'ö', '÷',
'ø', 'ù', 'ú', 'û', 'ü', 'ý', 'þ', 'ÿ';

Charstring

The Charstring sort is used to represent strings or sequences of characters. There is no limit for the length of a Charstring value. Charstring literals are written as a sequence of characters enclosed between two single quotes: 'abc'. If the Charstring should contain a quote (') it must be written twice.

'abcdef 0123'
'$%@^&'
'1''2''3' /* denotes 1'2'3 */
'' /* empty Charstring */

The following operators are available for Charstrings:

mkstring : Character -> Charstring;
length : Charstring -> Integer;
first : Charstring -> Character;
last : Charstring -> Character;
"//" : Charstring, Charstring -> Charstring;
substring : Charstring, Integer, Integer
-> Charstring;

These operators are defined as follows:

  • mkstring :
    This operator takes one Character value and converts it to a Charstring of length 1. For example: if c is a variable of type Character, then mkstring(c) is a Charstring containing character c.
  • length :
    This operator takes a Charstring as parameter and returns its number of characters.
    length ('hello') = 5
  • first :
    The value of the first Character in the Charstring passed as parameter. If the length of the Charstring is 0, then it is an error to call the first operator.
    first ('hello') = 'h'
  • last :
    The value of the last Character in the Charstring passed as parameter. If the length of the Charstring is 0, then it is an error to call the last operator.
    last ('hello') = 'o'
  • // (concatenation) :
    The result is a Charstring with all the elements in the first parameter, followed by all the elements in the second parameter.
    'he' // 'llo' = 'hello'.
  • substring :
    The result is a copy of a part of the Charstring passed as first parameter. The copy starts at the index given as second parameter (Note: first Character has index 1). The length of the copy is specified by the third parameter. It is an error to try to access elements outside of the true length of the first parameter.
    substring ('hello', 3, 2) = 'll'

It is also possible to access Character elements in a Charstring by indexing a Charstring variable. Assume that C is a Charstring variable. Then it is possible to write:

task C(2) := C(3);

This would mean that Character number 2 is assigned the value of Character number 3 in the variable C.

Note:

The first Character in a Charstring has index 1.

IA5String, NumericString, PrintableString, VisibleString

These Z.105 specific character string types are all syntypes of Charstring with restrictions on the allowed Characters that may be contained in a value. These sorts are mainly used as a counterpart of the ASN.1 types with the same names. The restrictions are:

  • IA5String :
    only NUL:DEL, i.e only characters in the range 0 to 127.
  • NumericString :
    only '0':'9' and ' '
  • PrintableString :
    only 'A':'Z', 'a':'z', '0':'9', ' ', '''':')', '+':'/', ':', '=', '?'
  • VisibleString:
    only ' ':'~'

It is recommended to use these types only in relation with ASN.1 or TTCN. In other cases use Charstring.

Duration, Time

The Time and Duration sorts have their major application area in connection with timers. The first parameter in a Set statement is the time when the timer should expire. This value should be of sort Time.

Both Time and Duration have literals with the same syntax as real values. Example:

245.72 0.0032 43

The following operators are available in the Duration sort:

"+" : Duration, Duration -> Duration;
"-" : Duration -> Duration;
"-" : Duration, Duration -> Duration;
"*" : Duration, Real -> Duration;
"*" : Real, Duration -> Duration;
"/" : Duration, Real -> Duration;
">" : Duration, Duration -> Boolean;
"<" : Duration, Duration -> Boolean;
">=" : Duration, Duration -> Boolean;
"<=" : Duration, Duration -> Boolean;

The following operators are available in the Time sort:

"+" : Time, Duration -> Time;
"+" : Duration, Time -> Time;
"-" : Time, Duration -> Time;
"-" : Time, Time -> Duration;
"<" : Time, Time -> Boolean;
"<=" : Time, Time -> Boolean;
">" : Time, Time -> Boolean;
">=" : Time, Time -> Boolean;

The interpretation of these operators are rather straightforward, as they correspond directly to the ordinary mathematical operators for real numbers. There is one "operator" in SDL that returns a Time value; now which returns the current global system time.

Time should be used to denote "a point in time", while Duration should be used to denote a "time interval". SDL does not specify what the unit of time is. In the SDL suite, the time unit is usually 1 second.

Example 3 : Timers in SDL

SET (now + 2.5, MyTimer)

After the above statement, SDL timer MyTimer will expire after 2.5 time units (usually seconds) from now.

You should note that according to SDL, Time and Duration (and Real) possess the true mathematical properties of real numbers. In an implementation, however, there are of course limits on the range and precision of these values.

Integer, Natural

The Integer sort in SDL is used to represent the mathematical integers. Natural is a syntype of Integer, allowing only integers greater than or equal to zero.

Integer literals are defined using the ordinary integer syntax. Example:

0 5 173 1000000

Negative integers are obtained by using the unary - operator given below. The following operators are defined in the Integer sort:

"-" : Integer -> Integer;
"+" : Integer, Integer -> Integer;
"-" : Integer, Integer -> Integer;
"*" : Integer, Integer -> Integer;
"/" : Integer, Integer -> Integer;
"mod" : Integer, Integer -> Integer;
"rem" : Integer, Integer -> Integer;
"<" : Integer, Integer -> Boolean;
">" : Integer, Integer -> Boolean;
"<=" : Integer, Integer -> Boolean;
">=" : Integer, Integer -> Boolean;
float : Integer -> Real;
fix : Real -> Integer;

The interpretation of these operators are given below:

  • - (unary, i.e. one parameter) :
    Negate a value, e.g. -5.
  • +, -, * :
    These operators correspond directly to their mathematical counterparts.
  • / :
    Integer division, e.g. 10/5 = 2, 14/5 = 2, -8/5 = -1
  • mod, rem :
    modulus and remainder at integer division. mod always returns a positive value, while rem may return negative values, e.g.
    14 mod 5 = 4, 14 rem 5 = 4, -14 mod 5 = 1, -14 rem 5 = -4
  • <, <=, >, >= :
    These operators correspond directly to their mathematical counterparts.
  • float :
    This operator converts an integer value to the corresponding Real number, for example:
    float (3) = 3.0
  • fix :
    This operator converts a real value to the corresponding Integer number. It is performed by removing the decimal part of the Real value.
    fix(3.65) = 3, fix(-3.65) = -3

NULL

NULL is a sort coming from ASN.1, defined in Z.105. NULL does occur rather frequently in older protocols specified with ASN.1. ASN.1 has later been extended with better alternatives, so NULL should normally not be used. The sort NULL only contains one value, NULL.

Object_identifier

The Z.105-specific sort Object_identifier also comes from ASN.1. Object identifiers usually identify some globally well-known definition, for example a protocol, or an encoding algorithm. Object identifiers are often used in open-ended applications, for example in a protocol where one party could say to the other "I support protocol version X". "Protocol version X" could be identified by means of an object identifier.

An Object_identifier value is a sequence of Natural values. This sort contains one literal, emptystring, that is used to represent an Object_identifier with length 0. The operators defined in this sort are:

mkstring : Natural -> Object_identifier
length : Object_identifier -> Integer
first : Object_identifier -> Natural
last : Object_identifier -> Natural
"//" : Object_identifier, Object_identifier
-> Object_identifier
substring : Object_identifier, Integer, Integer
-> Object_identifier
append : in/out Object_identifier, Natural;
(. .) : * Natural -> Object_identifier

These operators are defined as follows:

  • mkstring :
    This operator takes one Natural value and converts it to an Object_identifier of length 1.
    mkstring (8) gives an Object_identifier consisting of one element, i.e. 8.
  • length :
    This operator takes an Object_identifier as parameter and returns its number of object elements, i.e. Natural values.
    length (mkstring (8)//mkstring(6)) = 2
    length (emptystring) = 0
  • first :
    The value of the first Natural in the Object_identifier passed as parameter. If the length of the Object_identifier is 0, then it is an error to call the first operator.
    first (mkstring (8)//mkstring(6)) = 8
  • last :
    The value of the last Natural in the Object_identifier passed as parameter. If the length of the Object_identifier is 0, then it is an error to call the last operator.
    last (mkstring (8)//mkstring(6)) = 6
  • // (concatenation) :
    The result is a Object_identifier with all the elements in the first parameter, followed by all the elements in the second parameter.
    mkstring (8) // mkstring (6) gives an Object_identifier of two elements, 8 followed by 6.
  • substring :
    The result is a copy of a part of the Object_identifier passed as first parameter. The copy starts at the index given as second parameter (Note: first Natural has index 1). The length of the copy is specified by the third parameter. It is an error to try to access elements outside of the true length of the first parameter.
    substring(mkstring(8)//mkstring(6),2,1) =mkstring(6)
  • append :
    append is a Telelogic extension and can be used to add a new component to the end of an existing Object_identifier. append takes a variable as first parameter and a Natural value as second. The variable is then updated to include the second parameter as last component in the Object_identifier. The reason for introducing this operator is that:
    task append(V, 12);
    is much more efficient than performing the same calculation as
    task V := V // mkstring(12);
  • (. .):
    The (. .) expression, which is a Telelogic extension, is an application of the implicit make operator. The make operator takes a sequence of Natural values and returns an Object_identifier that contains these value in the order they are given.
    Obj_id_var := (. 1, 2, 3 .) would give an Object_identifier containing 1, 2 and 3.

It is also possible to access the Natural elements in an Object_identifier by indexing an Object_identifier variable. Assume that C is a Object_identifier variable. Then it is possible to write:

task C(2) := C(3);

This would mean that the Natural at index 2 is assigned the value of the Natural at index 3 in the variable C. Note that the first Natural in an Object_identifier has index 1. It is an error to index an Object_identifier outside of its length.

Octet

The Z.105-specific sort Octet is used to represent eight-bit values, i.e. values between 0 and 255. In C this would correspond to unsigned char. There are no explicit literals for the Octet sort. Values can, however, easily be constructed using the conversion operators i2o and o2i discussed below.

The following operators are defined in Octet:

"not" : Octet -> Octet;
"and" : Octet, Octet -> Octet;
"or" : Octet, Octet -> Octet;
"xor" : Octet, Octet -> Octet;
"=>" : Octet, Octet -> Octet;
"<" : Octet, Octet -> Boolean;
"<=" : Octet, Octet -> Boolean;
">" : Octet, Octet -> Boolean;
">=" : Octet, Octet -> Boolean;
shiftl : Octet, Integer -> Octet;
shiftr : Octet, Integer -> Octet;
"+" : Octet, Octet -> Octet;
"-" : Octet, Octet -> Octet;
"*" : Octet, Octet -> Octet;
"/" : Octet, Octet -> Octet;
"mod" : Octet, Octet -> Octet;
"rem" : Octet, Octet -> Octet;
i2o : Integer -> Octet;
o2i : Octet -> Integer;
bitstr : Charstring -> Octet;
hexstr : Charstring -> Octet;

The interpretation of these operators is as follows:

  • not, and, or, xor, => :
    Apply the corresponding Bit operator for each of the eight bits in the Octet. For example:
    not bitstr ('00110101') = bitstr ('11001010')
  • <, <=, >, >= :
    Ordinary relation operators for the Octet values.
  • shiftl, shiftr :
    These Telelogic-specific operators are defined as left and right shift in C, so shiftl(a,b) is defined as a<<b in C.
    shiftl (bitstr('1'), 4) = bitstr('10000')
    shiftr (bitstr('1010'), 2) = bitstr ('10')
  • +, -, *, /, mod, rem :
    These operators are the mathematical corresponding operators. All operations are, however, performed modulus 256.
    i2o(250) + i2o(10) = i2o(4), o2i(i2o(4)-i2o(6)) = 254
  • i2o :
    This Telelogic-specific operator converts an Integer value to the corresponding Octet value.
    i2o (128) = hexstr ('80')
  • o2i :
    This Telelogic-specific operator converts an Octet value to the corresponding Integer value.
    o2i (hexstr ('80')) = 128
  • bitstr :
    This Telelogic-specific operator converts a charstring containing eight Bit values ("0" and "1") to an Octet value.
    bitstr('00000011') = i2o(3)
  • hexstr :
    This Telelogic-specific operator converts a charstring containing two HEX values ("0"-"9", "a"- "f", "A"- "F") to an Octet value.
    hexstr('01') = i2o(1), hexstr('ff') = i2o(255)

It is also possible to read the individual bits in an Octet value by indexing an Octet variable. The index should be in the range 0 to 7.

Octet_string

The Z.105-specific sort Octet_string represents a sequence of Octet values. There is no limit on the length of the sequence. The operators defined in the Octet_string sort are:

mkstring : Octet -> Octet_string;
length : Octet_string -> Integer;
first : Octet_string -> Octet;
last : Octet_string -> Octet;
"//" : Octet_string, Octet_string
-> Octet_string;
substring : Octet_string, Integer, Integer
-> Octet_string;
bitstr : Charstring -> Octet_string;
hexstr : Charstring -> Octet_string;
bit_string : Octet_string -> Bit_string;
octet_string : Bit_string -> Octet_string;

These operators are defined as follows:

  • mkstring :
    This operator takes an Octet value and converts it to a Octet_string of length 1.
    mkstring (i2o(10)) gives an Octet_string containing one element.
  • length :
    The number of Octets in the Octet_string passed as parameter.
    length (i2o (8)//i2o (6)) = 2
    length ( hexstr ('0f3d88')) = 3
    length ( bitstr ('')) = 0
  • first :
    The value of the first Octet in the Octet_string passed as parameter. If the length of the Octet_string is 0, then it is an error to call the first operator.
    first ( hexstr ('0f3d88')) = hexstr('0f') (= i2o(15))
  • last :
    The value of the last Octet in the Octet_string passed as parameter. If the length of the Octet_string is 0, then it is an error to call the last operator.
    last ( hexstr ('0f3d88')) = hexstr('88') (= i2o(136))
  • // (concatenation) :
    The result is an Octet_string with all the elements in the first parameter, followed by all the elements in the second parameter.
    hexstr('0f3d')//hexstr('884F') = hexstr(''0f3d884f')
  • substring :
    The result is a copy of a part of the Octet_string passed as first parameter. The copy starts at the index given as the second parameter. The length of the copy is specified by the third parameter. It is an error to try to access elements outside of the true length of the first parameter.
    substring(hexstr('0f3d889C'), 3, 2) = hexstr('889c')
  • bitstr :
    This Telelogic-specific operator converts a charstring containing only characters 0 and 1, to an Octet_string with an appropriate length and with the Octet elements set to the value defined in the sequences of eight bits. If the Charstring length is not a multiple of eight, it is padded with zeros.
    bitstr ('101') = bitstr ('10100000')
  • hexstr :
    This Telelogic-specific operator converts a charstring containing HEX values (0 -9, A-F, a-f) to an Octet_string. Each pair of HEX values are converted to one Octet element in the Octet_string. If the Charstring length is not a multiple of two, it is padded with a zero.
    hexstr ('f') = hexstr ('f0')
  • bit_string and octet_string :
    These two operators convert values between Bit_string and Octet_string.

It is also possible to access the Octet elements in an Octet_string by indexing an Octet_string variable. Assume that C is an Octet_string variable. Then it is possible to write:

task C(2) := C(3);

This would mean that the Octet at index 2 is assigned the value of Octet at index 3 in the variable C. It is an error to index an Octet_string outside of its length.

Note:

The first Octet in an Octet_string has index 1.

Pid

The sort Pid is used as a reference to process instances. Pid has only one literal, Null. All other values are obtained from the SDL predefined variables Self, Sender, Parent, and Offspring.

Real

Real is used to represent the mathematical real values. In an implementation there are of course always restrictions in size and precision of such values. Examples of Real literals:

2.354 0.9834 23 1000023.001

The operators defined in the Real sort are:

"-" : Real -> Real;
"+" : Real, Real -> Real;
"-" : Real, Real -> Real;
"*" : Real, Real -> Real;
"/" : Real, Real -> Real;
"<" : Real, Real -> Boolean;
">" : Real, Real -> Boolean;
"<=" : Real, Real -> Boolean;
">=" : Real, Real -> Boolean;

All these operators have their ordinary mathematical meaning.

User Defined Sorts

All the predefined sorts and syntypes discussed in the previous section can be directly used in, for example, variable declarations. In many circumstances it is however suitable to introduce new sorts and syntypes into a system to describe certain properties of the system. A user-defined sort or syntype can be used in the unit where it is defined, and also in all its subunits.

Syntypes

A syntype definition introduces a new type name which is fully compatible with the base type. This means that a variable of the syntype may be used in any position where a variable of the base type may be used. The only difference is the range check in the syntype. One exception exists. The actual parameter that corresponds to a formal in/out parameter must be of the same syntype as the formal parameter. Otherwise proper range tests cannot be performed.

Syntypes are useful for:

  • Introducing a new name for an existing type
  • Introducing a new type that has the same properties as an existing type, but with a restricted value range
  • Defining index sorts used in arrays

Example 4 : Syntype definition

syntype smallint = integer
constants 0:10
endsyntype;

In this example smallint is the new type name, integer is the base type, and 0:10 is the range condition. Range conditions can be more complex than the one above. It may consist of a list of conditions, where each condition can be (assume X to be a suitable value):

  • =X a single value X is allowed
  • X same as =X
  • /=X all values except X are allowed
  • >X all values >X are allowed
  • >=X all values >=X are allowed
  • <X all values <X are allowed
  • <=X all values <=X are allowed
  • X:Y all values >=X and <=Y are allowed

Example 5 : Syntype definition

syntype strangeint = integer
constants <-5, 0:3, 5, 8, >=13
endsyntype;

In this example all values <-5, 0, 1, 2, 3, 5, 8, >=13 are allowed.

The range check introduced in a syntype is tested in the following cases (assuming that the variable, signal parameter, formal parameter involved is defined as a syntype):

  • Assignment to a variable
  • Assigning a value to a signal parameter in an output (also for the implicit signals used in connection with import and remote procedure calls)
  • Assigning a value to an IN parameter in a procedure call
  • Assigning a value to a process parameter in a create request action
  • Assigning a value to a variable in an input
  • Assigning a value to an operator parameter (also for the operator result)
  • Assigning a value to a timer parameter in set, reset, or active

Enumeration Sorts

An enumeration sort is a sort containing only the values enumerated in the sort. If some property of the system can take a relatively small number of distinct values and each value has a name, an enumeration sort is probably suitable to describe this property. Assume for example a key with three positions; off, stand-by, and service-mode. A suitable sort to describe this would be:

Example 6 : Enumeration sort

newtype KeyPosition
literals Off, Stand_by, Service_mode
endnewtype;

A variable of sort KeyPosition can take any of the three values in the literal list, but no other.

Struct

The struct concept in SDL can be used to make an aggregate of data that belongs together. Similar features can be found in most programming languages. In C, for example, it is also called struct, while in Pascal it is the record concept that has these properties. If, for example, we would like to describe a person and would like to give him a number of properties or attributes, such as name, address, and phone number, we can write:

newtype Person struct
Name Charstring;
Address Charstring;
PhoneNumber Charstring;
endnewtype;

A struct contains a number of components, each with a name and a type. If we now define variables of this struct type,

dcl p1, p2 Person;

it is possible to work directly with complete struct values, like in assignments, or in tests for equality. Also individual components in the struct variable can be selected or changed.

task p1 := (. 'Peter', 'Main Road, Smalltown',
'+46 40 174700' .);
task BoolVar := p1 = p2;
task p2 ! Name := 'John';
task CharstringVar := p2 ! Name;

The first task is an assignment on the struct level. The right hand side, i.e. the (. .) expression, is an application of the implicit make operator, that is present in all structs. The make operator takes a value of the first component sort, followed by a value of the second component sort, and so on, and returns a struct value where the components are given the corresponding values. In the example above, the component Name in variable p1 is given the value 'Peter'. The second task shows a test for equality between two struct expressions. The third and fourth task shows how to access a component in a struct. A component is selected by writing:

VariableName ! ComponentName

Such component selection can be performed both in a expression (then usually called extract) and in the left hand side of an assignment (then usually called modify).

Bit Fields

A bit field defines the size in bits for a struct component. This feature is not part of the SDL Recommendation, but rather introduced by Telelogic to enable the generation of C bit fields from SDL. This means that the syntax and semantics of bit fields follow the C counterpart very much.

Example 7 : Bit fields

newtype example struct
a Integer : 4;
b UnsignedInt : 2;
c UnsignedInt : 1;
: 0;
d Integer : 4;
e Integer;
endnewtype;

The following rules apply to bit fields:

  • The meaning of the bit field size, i.e. the : X (where X is an integer number) is the same as in C. When generating C code from SDL, the : X is just copied to the C struct that is generated from the SDL struct.
  • : 0 in SDL is translated to int : 0 in C.
  • As C only allows int and unsigned int for bit field components the same rule is valid in SDL: only Integer and UnsignedInt (from package ctypes) may be used.

Bit fields should only be used when it is necessary to generate C bit fields from SDL. Bit fields should not be used as an alternative to syntypes with a constants clause; the SDL suite does not check violations to the size of the bit fields.

Optional and Default values

To simplify the translation of ASN.1 types to SDL sorts, two new features have been introduced into structs. Struct components can be optional and they can have default values. Note that these features have their major application area in connection with ASN.1 data types and applying them in other situations is probably not a good idea, as they are not standard SDL-96.

Example 8 : Optional and default values

newtype example struct
a Integer optional;
b Charstring;
c Boolean := true;
d Integer := 4;
e Integer optional;
endnewtype;

The default values for component c and d, means that these components are initialized to the given values.

An optional component may or may not be present in a struct value. Initially an optional component is not present. It becomes present when it is assigned a value. It is an error to access a component that is not present. It is possible to test if an optional component is present or not by calling an implicit operator called

ComponentNamepresent

In the example above apresent(v) and epresent(v) can be used to test whether components a and e are present or not, in the value stored in variable v. A component that is present can be set to absent, i.e. not present, again by calling the implicit operator

ComponentNameabsent

In the example above aabsent(v) and eabsent(v) can be used to set the components to absent. Note that the absent operators are operators without result.

Components with default values also have present and absent operators in the same way as optional components. They however do not have the same semantics as for optional components. A component with default value always has a value! Present and absent instead have to do with encoding and decoding of ASN.1 values. A component that contains its default value, i.e. is absent, is in some encoding schemes not encoded.

A component with default value is initialized with the default value and has present equal to false. Present can for components with default values be seen as "is explicitly assigned some value". This means that when a component with default value is assigned a value, in an assignment for example, present will become true (even if the component is assigned the default value). The absent operator can be used to set the component back to absent. This means that the absent operator performs two things: assigns the component the default value and sets present to false.

According to Z.105, the make operator for a struct does not include components that are optional or contain a default value. Optional components always become absent and components with default values are always initialized with their default values. The struct example in the previous example only contains one component that is not optional and does not contain a default value. This means that a variable v of this type can be assigned a struct value by:

task v := (. `hello' .);

If we want to set the other components, this have to be performed in a sequence of assignments after this assignment.

To simplify assigning a complete struct value to a struct in these cases, Telelogic provide an alternative interpretation of make for a struct. You specify that you want to use this alternative interpretation of make by selecting Generate > Analyze > Details > Semantic Analysis > Include optional fields in make operator.

The alternative make always takes all components as parameters. By inserting an empty position you can specify that you want the component not present or given its default value. By giving a value you specify the value to be assigned to that component. Using the example above again it is possible to write:

task v := (. 1, `hello', , 10, .);

This means that the first, second, and fourth components are given explicit values, while the third and fifth becomes absent.

Choice

The new concept choice is introduced into SDL as a means to represent the ASN.1 concept CHOICE. This concept can also be very useful while developing pure SDL data types. The choice in SDL can be seen as a C union with an implicit tag field.

Example 9 : Choice

newtype C1 choice
a Integer;
b Charstring;
c Boolean;
endnewtype;

The example above shows a choice with three components. The interpretation is that a variable of a choice type can only contain one of the components at a time, so in the example above a value of C1 either contains an Integer value, a Charstring value, or a Boolean value.

Example 10 : Working with a choice type

DCL var C1, charstr Charstring;

TASK var := a : 5; /* assign component a */
TASK var!b := 'hello'; /* assign component b
(a becomes absent) */
TASK charstr := var!b; /* get component b */

The above example shows how to modify and extract components of a choice type. In this respect, choice types are identical to struct types, except the a:5 notation to denote choice values, whereas struct values are described using (. ... .).

Extracting a component of a choice type that is not present results in a run-time error. Therefore it is necessary to be able to determine which component is active in a particular value. For that purpose there are a number of implicit operators defined for a choice.

var!present

where var is a variable of a choice type, returns a value which is the name of the active component. This is made possible by introducing an implicit enumeration type with literals with the same names as the choice components. Note that this enumeration type is implicit and should not be inserted by you. Given the example above, it is allowed to test:

var!present = b

This is illustrated in Figure 26.

Figure 26 : Check which component of a choice is present

It is also possible to test if a certain component is active or not, by using the implicit boolean operators ComponentName present. To check if component b in the example above is present it is thus possible to write:

bpresent(v)

The information about which component that is active can be accessed using the present operators, but it is not possible to change it. This information is automatically updated when a component in a choice variable is assigned a value.

The purpose of choice is to save memory or bandwidth. As it is known that only one component at a time can contain a value, the compiler can use overlay techniques to reduce the total memory for the type. Also sending a choice value over a physical connection saves time, compared to sending a corresponding struct.

The choice construct is Telelogic-specific, and not part of recommendation Z.105, so if you want to write portable SDL, you should not use choice. Choice replaces the SDL suite #UNION code generator directive. It is recommended to replace #UNION directives by choice, as the SDL suite has better tool support for the latter.

Inherits

It is possible to create a new sort by inheriting information from another sort. It is possible to specify which operators and literals that should be inherited and it is then possible to add new operators and literals in the new type.

Note that it is not really possible to change the type in itself by using inheritance. It is, for example, not possible to add a new component to a struct when the struct is inherited.

Our experience with inheritance so far has been that it is not as useful as it might seem in the beginning, and that sometimes the use of inheritance leads to the need of qualifiers in a lot of places, as many expressions are no longer semantically valid.

Example 11 : Inherits

newtype NewInteger inherits Integer
operators all;
endnewtype;

In the example above a new type NewInteger is introduced. This type is distinct from Integer, i.e. an Integer expression or variable is not allowed where a NewInteger is expected, and a NewInteger expression or variable is not allowed where an Integer is expected. Since in the example all literals and operators are inherited, all the integer literals 0, 1, 2, ..., are also available as NewInteger literals. For operators it means that all operators having Integer as parameter or result type are copied, with the Integer parameter replaced with a NewInteger parameter. This is true for all operators, not only those defined in the Integer sort, which may give unexpected effects, which will be illustrated below.

Example 12 : Inherited operators

The following operators are some of the operators having Integer as parameter or result type:

"+" : Integer, Integer -> Integer;
"-" : Integer -> Integer;
"mod" : Integer, Integer -> Integer;
length : Charstring -> Integer;

The type NewInteger defined above will inherit these and all the others having integer as parameter or result type. Note that length is defined in the Charstring sort.

"+" : NewInteger, NewInteger -> NewInteger;
"-" : NewInteger -> NewInteger;
"mod" : NewInteger, NewInteger -> NewInteger;
length : Charstring -> NewInteger;

With this NewInteger declaration, statements like

decision length(Charstring_Var) > 5;

are no longer correct in the SDL system. It is no longer possible to determine the types in the expression above. It can either be the length returning integer that is tested against an integer literal, or the length returning a NewInteger value that is tested against a NewInteger literal.

It is possible to avoid this kind of problem by specifying explicitly the operators that should be inherited.

Example 13 : Inherits

newtype NewInteger inherits Integer
operators ("+", "-", "*", "/")
endnewtype;

Now only the enumerated operators are inherited and the problem with length that was discussed above will not occur.

Predefined Generators

Array

The predefined generator Array takes two generator parameters, an index sort and a component sort. There are no restrictions in SDL on the index and component sort.

Example 14 : Array instantiation

newtype A1 Array(Character, Integer)
endnewtype;

The example above shows an instantiation of the Array generator with Character as index sort and Integer as component sort. This means that we now have created a data structure that contains one Integer value for each possible Character value. To obtain the component value connected to a certain index value it is possible to index the array.

Example 15 : Using an array type

dcl Var_A1 A1; /* Assume sort in example above */

task Var_A1 := (. 3 .);
task Var_Integer := Var_A1('a');
task Var_A1('x') := 11;

decision Var_A1 = (. 11 .);
(true) : ...
...
enddecision;

The example above shows how to work with arrays. First we have the expression (. 3 .). This is an application of the make! operator defined in all array instantiations. The purpose is to return an array value with all components set to the value specified in make. The first task above thus assigns the value 3 to all array components. Note that this is an assignment of a complete array value.

In the second task the value of the array component at index 'a' is extracted and assigned to the integer variable Var_Integer. In the third task the value of the array component at index 'x' is modified and given the new value 11. The second and third task show applications of the operators extract! and modify! which are present in all array instantiations. Note that the operators extract!, modify!, and make! can only be used in the way shown in the example above. It is not allowed to directly use the name of these operators.

In the last statement, the decision, an equal test for two array values is performed. Equal and not equal are, as well as assignment, defined for all sorts in SDL.

The typical usage of arrays is to define a fixed number of elements of the same sort. Often a syntype of Integer is used for the index sort, as in the following example, where an array of 11 Pids is defined with indices 0 to 10.

Example 16 : Typical array definition

syntype indexsort = Integer
constants 0:10
endsyntype;

newtype PidArray Array (indexsort, Pid)
endnewtype;

Unlike most ordinary programming languages, there are no restrictions on the index sort in SDL. In most programming languages the index type must define a finite range of values possible to enumerate. In C, for example, the size of an array is specified as an integer constant, and the indices in the array range from 0 to the (size-1). In SDL, however, there are no such limits.

Example 17 : Array with infinite number of elements.

newtype RealArr Array (Real, Real)
endnewtype;

Having Real as index type means that there is an infinite number of elements in the array above. It has, however, the same properties as all other arrays discussed above. This kind of more advanced arrays sometimes can be a very powerful concept that can be used for implementing, for example, a mapping table between different entities.

Example 18 : Array to implement a mapping table

newtype CharstringToPid Array (Charstring, Pid)
endnewtype;

The above type can be used to map a Charstring representing a name to a Pid value representing the corresponding process instance.

String

The String generator takes two generator parameters, the component sort and the name of an empty string value. A value of a String type is a sequence of component sort values. There is no restriction on the length of the sequence. The predefined sort Charstring, for example, is defined as an application of the String generator.

Example 19 : String generator

newtype S1 String(Integer, empty)
endnewtype;

Above, a String with Integer components is defined. An empty string, a string with the length zero, is represented by the literal empty.

The following operators are available in instantiations of String.

mkstring : Itemsort -> String
length : String -> Integer
first : String -> Itemsort
last : String -> Itemsort
"//" : String, String -> String
substring : String, Integer, Integer -> String
append : in/out String, Itemsort;
(. .) : * Itemsort -> String

In this enumeration of operators, String should be replaced by the string newtype (S1 in the example above) and Itemsort should be replaced by the component sort parameter (Integer in the example above). The operators have the following behavior, with the examples based on type String (Integer, empty):

  • mkstring :
    This operator takes one Itemsort value and converts it to a String of length 1.
    mkstring (-3) gives a string of one integer with value -3.
  • length :
    The number of elements, i.e. Itemsort values, in the String passed as parameter.
    length (empty) = 0, length(mkstring (2)) = 1
  • first :
    The value of the first Itemsort element in the String passed as parameter. If the length of the String is 0, then it is an error to call the first operator.
    first (mkstring (8) // mkstring (2)) = 8
  • last :
    The value of the last Itemsort element in the String passed as parameter. If the length of the String is 0, then it is an error to call the last operator.
    last (mkstring (8) // mkstring (2)) = 2
  • // (concatenation) :
    The result is a String with all the elements in the first parameter, followed by all the elements in the second parameter.
    mkstring (8) // mkstring(2) gives a string of two elements: 8 followed by 2.
  • substring :
    The result is a copy of a part of the String passed as first parameter. The copy starts at the index given as second parameter (Note: first Itemsort element has index 1). The length of the copy is specified by the third parameter. It is an error to try to access elements outside of the true length of the first parameter.
    substring (mkstring (8) // mkstring(2), 2, 1)
    = mkstring(2)
  • append :
    append is a Telelogic extension and can be used to add a new component to the end of an existing String. append takes a variable as first parameter and a Itemsort value as second. The variable is then updated to include the second parameter as last component in the String. The reason for introducing this operator is that:
    task append(V, Comp);
    is much more efficient than performing the same calculation as
    task V := V // mkstring(Comp);
  • (. .):
    The (. .) expression, which is a Telelogic extension, is an application of the implicit make operator that is present in all strings. The make operator takes a sequence of Itemsort values and returns a String that contains these value in the order they are given.
    String_var := (. 1, 2, 3 .) would give a string containing 1, 2 and 3.

It is also possible to access Itemsort elements in a String by indexing a String variable. Assume that C is a String instantiation variable. Then it is possible to write:

task C(2) := C(3);

This would mean that Itemsort element number 2 is assigned the value of Itemsort element number 3 in the variable C. NOTE that the first element in a String has index 1. It is an error to index a String outside of its length.

The String generator can be used to build lists of items of the same type, although some typical list operations are computationally quite expensive, like inserting a new element in the middle of the list.

Powerset

The Powerset generator takes one generator parameter, the item sort, and implements a powerset over that sort. A Powerset value can be seen as: for each possible value of the item sort it indicates whether that value is member of the Powerset or not.

Powersets can often be used as an abstraction of other, more simple data types. A 32-bit word seen as a bit pattern can be modeled as a Powerset over a syntype of Integer with the range 0:31. If, for example, 7 is member of the powerset this means that bit number 7 is set.

Example 20 : Powerset generator

syntype SmallInteger = Integer
constants 0:31
endsyntype;

newtype P1 Powerset(SmallInteger)
endnewtype;

The only literal for a powerset sort is empty, which represents a powerset containing no elements. The following operators are available for a powerset sort (replace Powerset with the name of the newtype, P1 in the example above, and Itemsort with the Itemsort parameter, SmallInteger in the example):

"in" : Itemsort, Powerset -> Boolean
incl : Itemsort, Powerset -> Powerset
incl : Itemsort, in/out Powerset;
del : Itemsort, Powerset -> Powerset
del : Itemsort, in/out Powerset;
length : Powerset -> Integer
take : Powerset -> Itemsort
take : Powerset, Integer -> Itemsort
"<" : Powerset, Powerset -> Boolean
">" : Powerset, Powerset -> Boolean
"<=" : Powerset, Powerset -> Boolean
">=" : Powerset, Powerset -> Boolean
"and" : Powerset, Powerset -> Powerset
"or" : Powerset, Powerset -> Powerset
(. .) : * Itemsort -> Powerset

These operators have the following interpretation (the examples are based on newtype P1 of the above example, and it is supposed that variable v0_1_2 of P1 contains elements 0, 1, and 2):

  • in :
    This operator tests if a certain value is member of the powerset or not.
    3 in incl (3, empty) gives true;
    3 in v0_1_2 gives false, 0 in v0_1_2 gives true.
  • incl :
    Includes a value in the powerset. The result is a copy of the Powerset parameter with the Itemsort parameter included. To include a value that is already member of a powerset is a null-action.
    incl (3, empty) gives a set with one element, 3,
    incl (3, v0_1_2) gives a set with elements, 0, 1, 2, and 3.
  • incl (second operator) :
    This operator is a Telelogic extensions added as it is more efficient than the standard incl. This operator updates a powerset variable with a new component value.
    task incl(3, v0_1_2); means the same as
    task v0_1_2 := incl(3, v0_1_2);
  • del :
    Deletes a member in a powerset. The result is a copy of the Powerset parameter with the Itemsort parameter deleted. To delete a value that is not member of a powerset is a null-action.
    del (0, v0_1_2) gives a set with element 1 and 2;
    del (30, v0_1_2) = v0_1_2
  • del (second operator) :
    This operator is a Telelogic extensions added as it is more efficient than the standard del operator. This operator updates a powerset variable by removing a component value.
    task del(3, v0_1_2); means the same as
    task v0_1_2 := del(3, v0_1_2);
  • length :
    The number of elements in the powerset.
    length (v0_1_2) = 3, length (empty) = 0
  • take (one parameter) :
    Returns one of the elements in the powerset, but it is not specified which one.
    take (v0_1_2) gives 0, 1, or 2 (unspecified which of these three)
  • take (two parameters) :
    Elements are implicitly numbered with in the powerset from 1 to length(). The Telelogic-specific take operator returns the element with the number passed as second parameter. This operator can be used to "loop" through all elements of the set, as is illustrated in Figure 27.

Figure 27 : Computing the sum of all elements in a Powerset

  • < :
    A<B, is A a true subset of B
    incl (2, empty) < v0_1_2 = true,
    incl (30, empty) < v0_1_2 = false
  • > :
    A>B, is B a true subset of A
  • <= :
    A<=B, is A a subset of B
  • >= :
    A>=B, is B a subset of A
  • and :
    Returns the intersection of the parameters, i.e. a powerset with the element members of both parameters.
    incl (2, incl (4, empty)) and v0_1_2 gives a set with one element, visually 2.
  • or :
    Returns the union of the parameters, i.e. a powerset with the element members of any of the parameters.
    incl (2, incl (4, empty)) or v0_1_2 gives a set with elements, 0, 1, 2, and 4.
  • (. .):
    The (. .) expression, which is a Telelogic extension, is an application of the implicit make operator, that is present in all powersets. The make operator takes a sequence of Itemsort values and returns a Powerset that contains these values.
    v0_1_2 := (. 1, 2, 3 .) would give a set including 1, 2 and 3.

Powerset resembles the Bag operator, and normally it is better to use Powerset. See also the discussion in "Bag" .

Bag

The Z.105-specific generator Bag is almost the same as Powerset. The only difference is that a bag can contain the same value several times. In a Powerset a certain value is either member or not member of the set. A Bag instantiation contains the literal empty and the same operators, with the same behavior, as a Powerset instantiation. For details please see "Powerset" .

A Bag contains one additional operator:

makebag : Itemsort -> Bag

  • makebag :
    Takes an Itemsort value and returns a Bag containing this value (length = 1).

It is recommended to use Powerset instead of Bag, except in cases where the number of instances of a value is important. Powerset is defined in Z.100, and is therefore more portable. Bag is mainly part of the predefined data types in order to support the ASN.1 SET OF construct.

Ref, Own, Oref, Carray

These generators are Telelogic extensions to make it possible to work with pointers (Ref, Own, Oref) and with array with the same properties as in C.

Own and Oref is described in "Own and ORef Generators" , while Ref and Carray is part of the package ctypes described in "C Specific Package ctypes" . The package ctypes also contains SDL versions of some simple C types, which might be helpful in some cases.

Literals

Literals, i.e. named values, can be included in newtypes.

Example 21 : Literals in struct newtype

newtype Coordinates struct
x integer;
y integer;
adding
literals Origo, One;
endnewtype;

In this struct there are two named values (literals); Origo and One. The only way in SDL to specify the values these literals represent is to use axioms. Axioms can be given in a section in a newtype. This is not further discussed here. The SDL to C compilers provide other ways to insert the values of the literals. Please see the documentation in The Cadvanced/Cbasic SDL to C Compiler.

The literals can be used in SDL actions in the same way as expressions.

Example 22 : Use of literals

dcl C1 Coordinates;

task C1 := Origo;
decision C1 /= One;
...

Please note the differences in the interpretation of literals in the example above and in the description of enumeration types, see "Enumeration Sorts" . In an enumeration type each literal introduces a new distinct value and the set of literals defines the possible values for the type. In the struct example above, the type and the set of possible values for the type is defined by the struct definition. The literals here only give names on already existing values.

An alternative that might be more clear, is to use literals in the case of an enumeration type and use operators without parameters (Telelogic extension) in other cases, like the struct above.

Operators

Operators can be added to a newtype in the same way as literals.

Example 23 : Operators in struct newtype

newtype Coordinates struct
x integer;
y integer;
adding
operators
"+" : Coordinates, Coordinates -> Coordinates;
length : Coordinates -> Real;
endnewtype;

Telelogic has extended the operators with a number of new features to make them more flexible and to make it possible to have more efficient implementations. Extensions:

  • in/out parameters
  • operators without parameters
  • operators without result

Example 24 : Operators

operators
op1 : in/out Coordinates;
op2 : -> Coordinates;
op3 : ;

In the example above op1 takes one in/out parameter and has no result, op2 has no parameters and returns a value of type Coordinates, while op3 has neither parameters. nor result.

The behavior of operators can either be defined in axioms (as the literal values) or in operator diagrams. An operator diagram is almost identical to a value returning procedure (without states). An alternative to draw the operator implementation as a diagram is to define it in textual form. This might be appropriate as most operators performs calculations, and does not have anything to do with process control or process communication. In this case the algorithmic extension described in "Compound Statement" could be of great value.

Example 25 : Operator implementations

newtype Coordinates struct
x integer;
y integer;
adding
operators
"+" : Coordinates, Coordinates -> Coordinates;
operator "+" fpar a, b Coordinates
returns Coordinates
{
dcl result Coordinates;
result!x := a!x + b!x;
result!y := a!y + b!y;
return result;
}
endnewtype;

In the SDL to C Compilers there is also the possibility to include implementations in the target language. The problem with this is that it is necessary to know a lot more about the way the SDL to C Compilers translate operators into C.

Default Value

In a newtype or syntype it is possible to insert a default clause stating the default value to be given to all variables of this type.

Example 26 : Default value in struct newtype

newtype Coordinates struct
x integer;
y integer;
default (. 0, 0 .);
endnewtype;

All variables of sort Coordinates will be given the initial value
(. 0, 0 .), except if an explicit default value is given for the variable in the variable declaration.

Example 27 : Explicit default value in variable declaration

dcl
C1 Coordinates := (. 1, 1 .),
C2 Coordinates;

Here C1 has an explicit default value that is assigned at start-up. C2 will have the default value specified in the newtype.

Generators

It is possible in SDL to define generators with the same kind of properties as the pre-defined generators Array, String, Powerset, and Bag. As this is a difficult task and the support from the code generators is limited, it is not recommended for a non-specialist to try to define a generator.

The possibility to use user defined generators in the SDL to C Compilers is described in more detail in "Generators.


Using C/C++ in SDL

Introduction

To enable access to C or C++ declarations from an SDL specification, translation rules from C/C++ to SDL have been developed, that specify how C/C++ constructs may be represented in SDL. These translation rules have been implemented in the SDL suite's CPP2SDL tool. CPP2SDL supports the translation of both C and C++ declarations.

Important!

Please note that the H2SDL utility is replaced with the more flexible and improved CPP2SDL utility described in The CPP2SDL Tool.

When using CPP2SDL, it is possible to access C/C++ declarations and definitions in SDL. Figure 28 shows how CPP2SDL takes a set of C/C++ header files and, optionally, an import specification as input. Note that the import specification is only optional when CPP2SDL is executed from the command line. When using the utility from the Organizer, an import specification is created with a default configuration. An import specification holds CPP2SDL options, and may also specify which declarations in the header files are to be translated. CPP2SDL then translates the C/C++ declarations in the header files to SDL declarations. These resulting SDL declarations are saved in a generated SDL/PR file. See "Introduction for more details.

.

Figure 28 : CPP2SDL input and output.

Workflow

The typical workflow involved when using CPP2SDL will be illustrated with an example based on the AccessControl system. The example can be found in Telelogic\SDL_TTCN_Suite4.4/sdt/examples/cpp_access. Please note that the example currently runs on Windows only. However, the principles that are demonstrated are the same on all platforms.

The AccessControl system controls the access to a building. The building has a user terminal consisting of a display, a card reader and a keypad. To get access to the building, a valid card has to be inserted and a correct 4-digit code has to be typed.

In this version of the AccessControl system, information about cards and valid codes is stored in an external database. The database will be accessed through ODBC1, which is a commonly used C/C++ API for accessing data from different kinds of databases.

The purpose of the example is to show how a C/C++ API can be accessed from SDL by means of the tools in the C/C++ Access. The example covers the most important issues regarding the usage of the C/C++ Access, and may serve as a basis for more advanced experiments.

The example described below is a walk-through of how to utilize CPP2SDL from within the Organizer. The different development phases illustrated are:

  • A PR symbol is added to the Central process diagram.
  • The PR symbol is refined to be an import specification, by double-clicking it and setting the document type to C++ Import Specification.
  • A TRANSLATE section is added to the import specification, in which we list the names of all C/C++ declarations we need to access.
  • The import specification is then saved in a file, and the import specification symbol is thereby automatically connected to this file.
  • We use the CPP2SDL Options dialog to set various options for the import specification.
  • Finally, we add a header file to be translated.

Editing

The first step in accessing a C/C++ API from SDL is to insert a PR symbol at the place in the SDL specification where the C/C++ declarations of the API are to be used. The PR symbol represents the inclusion of an SDL/PR file, in general. In C/C++ Access this mechanism is used to include the SDL/PR file that is generated by CPP2SDL.

In the AccessControl example, we insert a PR symbol named ODBC in the process Central. The ODBC API is accessed from this process exclusively, thereby maintaining the narrowest possible scope.

Normally, an import specification should be placed at the highest level where declarations imported by the import specification are used. However, if C/C++ variables are imported, the import specification must be placed in a scope where external SDL variables are allowed to be declared.

Note:

External variables cannot be declared at system or block level. They can only be declared in processes, procedures, services or in operator diagrams.

Figure 29 : The PR symbol in the SDL Editor

When a PR symbol has been added in the SDL Editor it will initially appear in the Organizer as an unconnected reference, see Figure 30.

Figure 30 : The unconnected PR symbol in the Organizer

By default, the Organizer assumes that an unconnected PR symbol is to be connected to an ordinary user-defined SDL/PR file. In this case this is not what we want. By double-clicking the PR symbol, either in the SDL Editor or in the Organizer, an edit Document dialog is opened, see Figure 31. If we change the document type from SDL/PR to C++ Import Specification, we specify that the SDL/PR file is generated from a set of C++ header files.

Note:

Ordinary PR symbols are connected to user-defined SDL/PR files, while import specification symbols are connected to generated SDL/PR files.

Figure 31 : Edit the type of the PR symbol to be a C++ Import Specification

Since we want to create a new import specification, we leave the Show in editor check-box marked. If we already have an import specification to be used, there are two methods of connecting it. The first approach is to unmark all check-boxes and use the Connect command in the Organizer to connect to the existing import specification file. The second approach is to check the Copy existing file option and either browse for, or input the path to, the existing import specification. When using this method, it is necessary to view the file in the Text Editor, and then save in order to connect it.

An import specification can be edited manually by means of the Text Editor. However, an import specification can be left empty, and CPP2SDL options set from within the Organizer at a later stage. This will add a section called CPP2SDLOPTIONS where different options to CPP2SDL are stored. Often an import specification will contain a TRANSLATE section, with a list of the names of all declarations that you wish to be made accessible in SDL. For more information, refer to "Import Specification" .

In our case we add a TRANSLATE section with the names of all ODBC functions and types that we will need to access from SDL. See Figure 32.

Figure 32 The TRANSLATE section of the ODBC import specification

TRANSLATE {

SQLHENV
SQLHDBC
SQLHSTMT
SQLRETURN
SQLCHAR
SQLINTEGER
SQLSMALLINT
SQLPOINTER

SQLAllocHandle
SQLSetEnvAttr
SQLSetConnectAttr
SQLConnect
SQLBindCol
SQLExecDirect
SQLFetch
SQLCloseCursor
SQLFreeHandle
SQLDisconnect
SQLGetDiagRec

unsigned char.[6]
unsigned char.[64]
unsigned char.[256]

char.[256]

strcpy
strcat
}

When the import specification is saved to a file (called ODBC.is), the Organizer will automatically connect the import specification symbol to that file.

Figure 33 shows the connected import specification symbol.

Figure 33 : The connected import specification symbol in the Organizer

The next step is to set appropriate options for the translation of the C/C++ declarations that are specified in the import specification. This is best done by means of the CPP2SDL Options dialog (see Figure 34). This dialog is opened by right-clicking on the import specification symbol in the Organizer. For more detailed information about the CPP2SDL options, see "The CPP2SDL Tool.

Figure 34 : The CPP2SDL Options Dialog

The following options may be specified:

  • Language
    The language option specifies the input language, i.e. if C or C++ declarations shall be translated. If C is selected as input language, CPP2SDL will assume that no C++ specific constructs are encountered in the input header files.
    Note that this option determines if the import specification is a C or C++ import specification. Refer to Figure 31 where we selected which type of import specification to use.
  • Dialect
    These check-boxes make it possible to specify what C/C++ dialects that are to be supported by CPP2SDL. If no check-boxes are marked, the ANSI C/C++ dialect is supported.
    In our example we use the ODBC implementation from the Microsoft Foundation Classes, so we need support for the Microsoft dialect.

  • Run-Time Type Information
    If this check-box is set, Run-Time Type Information (RTTI) is assumed and dynamic casting is supported.
  • Allow Object Slicing
    Set this check-box if generated SDL cast operators are to support slicing of C++ objects.
  • Recognize SDL Sorts in Input
    When this check-box is set, SDL sorts will be recognized in the input.
  • Preprocessor
    The preprocessor to be used for preprocessing the input can be set here. If no preprocessor is set, CPP2SDL will use Microsoft Visual C/C++ Compiler (cl) in Windows and the standard C/C++ Preprocessor (cpp) on UNIX.

Note:

It is normally recommended to preprocess the input C/C++ headers with a compiler rather than a plain preprocessor. The reason for this is that a compiler may set several useful preprocessor defines.

  • Preprocessor Options
    The preprocessor options can be set in this field.
  • Pointer, Array, Template, Keyword, Incomplete, Underscore
    These fields specify the prefixes and suffixes that are used when C/C++ names must be modified in the SDL translation.
  • Generate SDL Representations for Fundamental Types
    Set this check-box if SDL representations for fundamental C/C++ types are to be included in the translation. These SDL representations are defined in SDL/PR files, which are described in detail in "SDL Library for Fundamental C/C++ Types.

Note:

If the SDL type representation option is set at several levels, this will cause problems. SDL representations for fundamental types should only be included at the highest level at which the types will be used. For example, if two blocks in a system have import specifications for accessing C/C++ declarations, SDL representations for fundamental C/C++ types should be included in the system, and not in the blocks. This can be done by adding an empty import specification without input headers at system level, that includes the SDL representations for the fundamental C/C++ types.

  • Only Generate Class Pointer Types when Necessary
    When this check-box is set, CPP2SDL will optimize the generation of class pointer types.

When appropriate CPP2SDL options have been set for an import specification, the next step is to add the C/C++ header files that are to be translated. This is done by selecting the import specification and, in the Edit menu, select Add Existing... Added header files will appear under the import specification symbol in the Organizer, see Figure 35.

Figure 35 : Add header files to the import specification

An arbitrary number of header files can be added to an import specification. They will all be processed using the options that are specified for the import specification. In the AccessControl example only one header file is added (includes.h).

To see the contents of a header file double-click on its symbol in the Organizer. The Text Editor will then open and display the contents of the header file. If this is done on the includes.h header, we see that it actually includes several other header files. The reason for using a wrapper header like includes.h instead of adding the interesting headers under the import specification directly, is that we would like to avoid hard-coding the path to these files. By using #include <file> statements, and preprocessing the file with the Microsoft Visual C++ compiler, the location of these files will be known at compile-time.

Let us summarize what we have done in the example so far. We have edited the SDL system by adding a PR symbol, changed the PR symbol to an import specification, added a TRANSLATE listing the needed declarations, saved the import specification connecting it to the system, configured CPP2SDL using the options dialog, and adding the header file to the system.

This concludes the editing phase. It is now time to analyze the system.

Analyzing

The SDL declarations that are generated by CPP2SDL must be analyzed as case-sensitive SDL. Before starting the Analyzer, a case-sensitivity option must therefore be set:

  • Select Tools in the Organizer and start the Preference Manager.
  • In the Preference Manager, double-click on the SDT symbol and set CaseSensitive to on (it is by default set to off).

Figure 36 : Set case-sensitive SDL in the Preference Manager

The Analyzer will perform three major steps during the analysis of an SDL system that contains C/C++ import specifications. During each step a message will be printed in the Organizer Log window to indicate the progress, see Figure 37.

Figure 37 : The Organizer Log window for the analyze phase

  1. SDL/GR to SDL/PR Conversion
    The Analyzer requests the SDL Editor to perform an SDL/GR to SDL/PR conversion. This means that all graphical SDL symbols are converted to their textual representations. In particular, every PR symbol will be represented by a #include 'filename.pr' in the SDL/PR, where filename.pr is the name of the file to which the corresponding import specification is connected.

    In our example we will thus get a #include 'ODBC.pr' in the SDL/PR representation of the process Central.
  2. C/C++ to SDL Conversion
    This step is performed once for each import specification in the system. The header files associated with an import specification are parsed and analyzed by CPP2SDL. Errors that are reported during this phase may, for example, be due to differences in language support and inappropriate preprocessor settings. If so, you can set the correct language dialect and suitable preprocessor options in the CPP2SDL Options dialog. Syntax errors and some semantic errors in the header files will also be checked for during this phase. For more information about how CPP2SDL handles errors, see "Example usage of some C/C++ functionality.
    If no errors are found, CPP2SDL will generate an SDL/PR file with the result of the translation. Finally, some warnings may be printed, for example to notify that certain declarations for some reason could not be translated.
    In our example we get a file called ODBC.pr when this step is finished.

Note:

CPP2SDL is not as good as a C/C++ compiler when it comes to error detection and error reports. It is thus strongly recommended to make sure that the header files are semantically correct by running them through a compiler, before they are translated to SDL.

  3. Syntactic and Semantic SDL Analysis
    When all SDL/PR code has been generated the SDL Analyzer will check for syntactic and semantic errors as usual. For example, it is likely that many errors will be reported if case-sensitive SDL was not set in the Preference Manager, see Figure 36. A common source for errors is that SDL representations for fundamental types were; not included at all, included at the wrong place in the SDL system, or included many times in the same SDL scope entity.

Once we have got a clean analysis of the system, it is time to proceed with code generation.

Generating

Code generation can be done either from the traditional Make dialog, or from the more powerful tool SDL Targeting Expert. To generate code for a system containing C or C++ import specifications, it is preferred to use the Targeting Expert. For example, it is much easier to link-in the object files that belong to the translated header files, using the Targeting Expert. The Make dialog will in the near future be discontinued in favor of the Targeting Expert.

A system that contains one or more C++ import specifications must be translated to C++ rather than C code. An option to the Code Generator controls whether C or C++ code is generated. This option is automatically set by the Analyzer if there are one or more C++ import specifications present in the Organizer view.

To start the Targeting Expert, select Targeting Expert... in the Generate menu in the Organizer. The Targeting Expert dialog will appear, see Figure 38. For full information about all the settings and options provided by Targeting Expert, see The Targeting Expert.

Figure 38 : The SDL Targeting Expert

When one or more C++ import specifications are present in the SDL system, the Targeting Expert will issue a warning that a C++ compiler is needed to compile the generated code (see Figure 38). Next, right-click Component, select Simulations, and then Simulation. The compiler may be set by pressing the Compiler/Linker/Make icon, and then, under the Compiler tab, locating the compiler executable. Here we may also specify compiler options and preprocessor settings.

Note:

Make sure that the settings made in the CPP2SDL Options dialog for the preprocessor and preprocessor settings match the settings made in the Targeting Expert.

In the AccessControl example, you can use the C++ Microsoft Simulation kernel, and the generated code can be compiled with the Microsoft Visual C++ compiler.

To avoid getting loads of link errors, we also have to remember to link-in several required Microsoft libraries (e.g. the Odbc32.lib library). This is done under the Linker tab as shown in Figure 39. Simply add the file to the List of files and save.

Figure 39 : Add libraries in the Targeting Expert

Now everything is ready for code generation. Press the Make or Full Make buttons and the Targeting Expert will instruct the Analyzer to analyze the SDL system (see "Analyzing" ) and then invoke the C or C++ Code Generator. Finally the generated code will be compiled and linked as specified to create a simulator executable. Figure 40 shows what the Targeting Expert may look like when this has been done.

Figure 40 : Generating a simulator from the Targeting Expert

Simulating

Naturally, it is possible to simulate and debug a system on SDL level even if it uses C or C++ declarations. The standard SDL simulator can be used for this.

A simulator will automatically start when making from Targeting Expert. At other times than making to start a simulation of a system, select SDL in the Tools menu in the Organizer or in the Targeting Expert. Then select Simulator UI and the SDL Simulator user interface will start. To load the simulator executable that was generated above, select File and Open... in the SDL Simulator UI.

For the AccessControl example, two customized buttons are available for the Simulator UI. They may be loaded by selecting Buttons and then Load...The "GUI" button starts a GUI for the AccessControl system and waits for you to single-step or go through the system by interacting with the GUI. The "GUI+MSC" button also activates the GUI, and in addition generates an MSC trace. In Figure 41 an example of an MSC trace of the AccessControl system is shown.

Figure 41 : MSC trace of the AccessControl system

The Simulator will treat C++ classes as C structs, but with the additional possibility of invoking the constructors of the class. For example, when the value of a C++ class, that is instantiated in SDL, is changed from the Simulator, the following steps are performed:

  • The Simulator pops up a dialog showing a list of available constructors. For example:
    0 /* No constructor */
    1 /* C() */
    or, for a class with a user-defined constructor,
    0 /* No constructor */
    2 /* C(int) */

    Type the number for the constructor that are to be invoked, if any.
  • If a constructor was selected, the Simulator will prompt for its actual arguments.
  • Finally, the Simulator allows public member variables to be explicitly set using either the SDL or ASN.1 syntax. For example:
    (. 1, true, 'x' .) SDL syntax
    {mv1 1, mv2 true, mv3 'x'} ASN.1 syntax
    Note that the ASN.1 syntax is more flexible since it contains the names of the member variables.

The steps for instantiating a C++ class from the Simulator (e.g. by sending a signal containing a parameter of class type) are similar to the ones shown above.

Summary of the AccessControl Example

The walk-through of the AccessControl example above has shown the typical workflow when using the C/C++ Access.

  • The SDL specification is edited by adding PR symbols to it, and they are refined to become import specifications. C/C++ header files are added under each import specification, and appropriate translation options are set by means of the CPP2SDL Options dialog. A TRANSLATE section may also be added to the import specification listing the names of the declarations to be translated.
  • The SDL specification is analyzed as case-sensitive SDL. Errors in the C/C++ headers or in the SDL specification are detected by CPP2SDL or the SDL Analyzer respectively.
  • C or C++ code is generated by using the Make dialog or, preferably, the Targeting Expert. The generated code is compiled and linked together with additional object files.
  • The SDL specification may be simulated using the Simulator UI.

Figure 42 below shows the Organizer view of how the AccessControl system may look like when it is completed.

Figure 42 : Organizer view of the AccessControl system

As can be seen in the figure, the Central process has one PR symbol that has not been refined into an import specification. Instead this symbol is connected to an ordinary SDL/PR file, macro.pr, that contains external SDL synonyms that represent C/C++ macros that are needed in the calls to the ODBC API. The sorts of these synonyms are imported by the ODBC.is import specification. An alternative technique for accessing C/C++ macros, based on the #CODE operator, is described in "Accessing C/C++ Macros from SDL" .

Import Specification

The import specification is a text file written in a simple C/C++ style syntax. You can specify exactly which declarations in the input header files to access, by using an import specification. The specified subset of the declarations is translated by CPP2SDL. The import specification also enables access to e.g. class and function templates. For more information about import specifications, see "Import Specifications.

The example below shows a simple import specification where the identifiers a_int, i_arr and func are made available in SDL.

Example 28 : A simple import specification

TRANSLATE {
a_int
i_arr
func
}

If an identifier in an import specification refers to a declaration that depends on other declarations, CPP2SDL will translate all these declarations as well.

There are some more advanced constructs that can be used in an import specification:

  • Type Declarators
  • Prototypes for Ellipsis Functions

For more information about these constructs, see "Advanced Import Specifications.

Templates

By using the CPP2SDL tool, instantiations of template declarations are supported.

To be able to instantiate a C++ template, CPP2SDL needs information about its actual template arguments. This information is given in an import specification.

The C++ template declaration is not itself translated to SDL. Instead an instantiation of the template is mapped to SDL.

Accessing C/C++ Constructs not Fully Supported by CPP2SDL

Accessing C/C++ Macros from SDL

Macros are used for conditional compilation, but can also be used for other purposes:

  • To define constants: #define PI 3.1415
  • To define types: #define BYTE char
  • To define functions: #define max(a,b) a>b?a:b

Macros are not part of the C or C++ languages and are therefore not translated to SDL. Instead, the preprocessor expands all macros before CPP2SDL perform the translation.

To be able to access macro constants from SDL, the implicit #CODE operator or SYNONYM can be used, see example below.

Example 29 : Constants defined as C++ macros

C++:

#define PI 3.1415;

SDL using #CODE:

dcl a double;

task a := #CODE('PI');

SDL using SYNONYM:

SYNONYM PI double = EXTERNAL 'C++';

dcl a double;

task a := PI;

To be able to access macro definitions for types or functions, the macro __CPP2SDL__ can be used. The __CPP2SDL__ macro is defined when CPP2SDL executes, but not otherwise, and is used in a special header file (called x.h in the examples below). This header file must then be included in the set of header files that are translated by CPP2SDL.

The following examples illustrate how the __CPP2SDL__ macro can be exploited to change C/C++ headers to make macro definitions for types and functions available in SDL.

Example 30 : Macro "types" in C++ headers

#define BYTE char

In the C++ fragment above, the macro BYTE is used as if it were a type. The preprocessor will resolve all BYTE occurrences, which result in that BYTE cannot be available in SDL. To avoid this, the definition of BYTE can be changed to the following:

x.h:
#ifndef __CPP2SDL__
#ifdef BYTE
#undef BYTE
#endif
#define BYTE char
#else
typedef char BYTE;
#endif

The macro BYTE is now available as a type in SDL, since __CPP2SDL__ will be defined during the C++ to SDL translation. In the generated C++ code, BYTE is a macro, since __CPP2SDL__ will be undefined.

Example 31 : Macro "functions" in C++ headers

#define max(a,b) a>b?a:b

By defining max as a macro, max can be used as if it were a function. The macro max can be used for any type for which > is defined. The following definition makes max available in SDL for char and int.

x.h:
#ifndef __CPP2SDL__
#ifdef max
#undef max
#endif
#define max(a,b) a>b?a:b
#else
int max(int a,int b);
char max(char a, char b);
#endif

With the above definition, max will be regarded as an operator by the SDL system, since __CPP2SDL__ has been defined. When the C++ code generated from SDL is compiled, the C++ preprocessor will resolve the "function calls" to max, since the macro __CPP2SDL__ then will be undefined.

Function Pointers

Function pointers are mapped to untyped pointers in SDL, ptr_void(void*). This allows function pointers to be represented in SDL. However, it is not possible to work with this SDL representation. For example to call a function that the pointer points at or to assign the function pointer with the address of an SDL operator, you have to do as shown in the following example:

Example 32 : Using function pointers

C++:

int func1(int i, int j);
int con_sum(int a, int b, int (*F)(int,int));

Import Specification:

TRANSLATE {
func1
con_sum
}

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
con_sum : int, int, ptr_void -> int;
func1 : int, int -> int;
ENDNEWTYPE global_namespace; EXTERNAL 'C++';

SDL using #CODE alternative 1:

dcl
sum int,
pfunc ptr_void;

task {
pfunc := #CODE('(void*) &func1');
sum := con_sum(1,4,#CODE('(int (*)(int,int)) #(pfunc)'));
};

SDL using #CODE alternative 2:

dcl
sum int;

task {
sum := con_sum(1,4,#CODE('&func1'));
};

Unsupported Overloaded Operators

In both C++ and SDL, there is a possibility to override predefined operators. In the table below, the overloaded C++ operators that CPP2SDL supports are listed.

.
C++ operator | Description | SDL operator
+ | (binary) Addition | +
- | (binary) Subtraction | -
* | (binary) Multiplication | *
* | (unary prefix) Dereference | *>
/ | (binary) Division | /
% | (binary) Modulo | rem
! | (unary prefix) Not | not
< | (binary) Less | <
> | (binary) Greater | >
<< | (binary) Left Shift | <
>> | (binary) Right Shift | >
== | (binary) Equal | =
!= | (binary) Not Equal | /=
<= | (binary) Less Equal | <=
>= | (binary) Greater Equal | >=
&& | (binary) And | and
|| | (binary) Or | or

Both shift operators and the less/greater operators in C++ are mapped to < and > in SDL. This mapping implies that overloading is supported on either < and > or << and >> in SDL. If both these operator pairs are overloaded, CPP2SDL will issue a warning, and select the former pair to be represented in SDL.

Overloaded operators, that are not supported by CPP2SDL, can be handled using the operator #CODE.

1

ODBC is a de facto standard on Windows, but it has also been implemented on other platforms.


C Specific Package ctypes

Telelogic offers a special package ctypes that contains data types and generators that match C. It is described in detail in The ADT Library. The ctypes package should be used in the following cases:

  • if you want to use pointers in SDL
  • if you need a data type that matches some specific C type (for example short int) for which there is no corresponding SDL sort.
  • if you use C headers directly in SDL In this case package ctypes must be used.

The tables below list the data types and generators in ctypes and their C counterparts.

SDL Sort
Corresponding C Type

 ShortInt

 short int

 LongInt

 long int

 UnsignedShortInt

 unsigned short int

 UnsignedInt

 unsigned int

 UnsignedLongInt

 unsigned long int

 Float

 float

 Charstar

 char *

 Voidstar

 void *

 Voidstarstar

 void **

SDL Generator
Corresponding C Declarator

 Carray

 C array, i.e. []

 Ref

 C pointer, i.e. *

The rest of this section explains how these data types and generators can be used in SDL.

Different Int Types and Float

ShortInt, LongInt, UnsignedShortInt, UnsignedInt, UnsignedLongInt are all defined as syntypes of Integer, so from an SDL point of view, these data types are really the same, and the normal Integer operators can be used on these types. The only difference is that the code that is generated for these types is different. Float is defined as a syntype of Real.

Charstar, Voidstar, Voidstarstar

Charstar represents character strings (i.e. char *) in C. Charstar is not the same as the SDL predefined type Charstring! Charstar is useful when accessing C functions and data types that use char *. In other cases it is better to use Charstring instead (see also "Charstring" ). Conversion operators between Charstar and Charstring are available (see below).

Voidstar corresponds to void * in C. This type should only be used when accessing C functions that have void * parameters, or that return void * (in which case it is advised to "cast" the result directly to another type).

Voidstarstar corresponds to void ** in C. This type is used in combination with the Free procedure described in "Using Pointers in SDL" . In rare cases this type is also needed to access C functions.

The following conversion operators in ctypes are useful:

cstar2cstring : Charstar -> CharString;
cstring2cstar : CharString -> Charstar;
cstar2vstar : Charstar -> Voidstar;
vstar2cstar : Voidstar -> Charstar;
cstar2vstarstar : Charstar -> Voidstarstar;

These operators have the following behavior:

  • cstar2cstring:
    Converts a C string to an SDL Charstring. For example if variable v of type Charstar contains the C string "hello world", then cstar2cstring(v) = 'hello world'.
  • cstring2cstar:
    Converts an SDL Charstring to a C string, i.e. the opposite of cstar2cstring.
  • cstar2vstar:
    Converts a Charstar to a Voidstar. This operator is sometimes useful when calling C functions with void * parameters.
  • vstar2cstar:
    Converts a Voidstar to a Charstar. This operator can for example be used if a C function returns void *, but the result should be "casted" to a char *.

The Carray Generator

The generator Carray in package ctypes is useful to define arrays that have the same properties as C arrays. Carray takes two generator parameters; an integer value and a component sort.

Example 33 : Carray instantiation

newtype IntArr Carray(10, Integer)
endnewtype;

The defined type IntArr is an array of 10 integers with indices 0 to 9, corresponding to the C type

typedef int IntArr[10];

Two operators are available on instantiations of Carray; modify! to change one element of the array, and extract! to get the value of one element in the array. These operators are used in the same way as in normal SDL arrays, see "Array" . There is no (. ... .) notation provided for denoting values of whole CArrays.

modify! : Carray, Integer, Itemsort -> Carray;
extract! : Carray, Integer -> Itemsort;

Example 34 : Use of Carray in SDL

DCL v IntArr, i Integer;

TASK v(0) := 3; /* modifies one element */
TASK i := v(9); /* extracts one element */

If a C array is used as parameter of an operator, it will be passed by address, just as in C. This makes it possible to write operators that change the contents of the actual parameters. In standard SDL this would not be possible.

The Ref Generator

The generator Ref in package ctypes is used to define pointer types. The following example illustrates how to use this generator.

Example 35 : Defining a pointer type

newtype ptr Ref(Integer)
endnewtype;

The sort ptr is a pointer to Integer.

Standard SDL has no pointer types. Pointers have properties that cannot be defined in normal SDL. Therefore they should be used very carefully. Before explaining how to use the Ref generator, it is worthwhile to list some of the dangers of using pointers in SDL.

Pointers Will Lead to Data Inconsistency

If more than one process can read/write to the same memory location by means of pointers, data inconsistency can and will occur! Some examples:

  • In a flight reservation system there is one seat left, and two reservation requests come in simultaneously. If pointers were used to check the availability of seats, both requests might be approved! In literature this is called the "writers-writers problem".
  • A process may update some array variable. If at the same time another process tries to read the variable by means of a pointer to the array, the reading process may get a value were some elements of the array are "new" while other elements are "old", and the total result makes no sense. This is the classic "readers/writers problem".

Even though tools such as the Simulator and Validator will be able to detect a number of errors regarding pointers, there are situations that cannot be detected with these tools! This is because the Validator and Simulator assume a scheduling atomicity of at best one SDL symbol at a time. This may not hold in target operating systems where one process can be interrupted at any time (pre-emptive scheduling). If pointers are used, data is totally unprotected, and data inconsistency may occur, even though the Validator did not discover any problems! All these problems can be avoided by using SDL constructs for accessing data, like remote procedures and signal exchange.

Caution!

For the above stated reasons, NEVER PASS POINTERS TO ANOTHER PROCESS! Not in an output, not in a remote procedure call, not in a create, and not by exported/revealed variables!

And if you do not obey this rule anyway: after passing a pointer, release immediately the "old" pointer to prevent having several pointers to the same data area. For example (for some pointer p):

OUTPUT Sig(p) TO ...;
TASK p := Null;

Pointers Are Unpredictable

If you have an SDL system that always works except during demonstrations, then you have used pointers! Bugs with pointers may be very hard to discover, as a system may (accidentally) behave correctly for a long time, but then suddenly strange things may happen. Finding such bugs may take very long time; in rare cases you might not find them at all!

Caution!

BUGS CAUSED BY POINTERS MAY BE HARD TO FIND!

Pointers Do Not Work in Real Distributed Systems

If an SDL system is "really" distributed, i.e. where processes have their own memory space, it makes no sense to send a pointer to another process, as the receiving process will not be able to do anything with it. Therefore, by communicating pointers to other processes, limitations are posed on the architecture of the target implementation.

Pointers Are Not Portable

The Ref generator and its operators are completely Telelogic-specific. It is highly unlikely that SDL systems using pointers will run on other SDL tools.

Using Pointers in SDL

If you still want to use pointers in SDL after all these warnings, this section explains how to do this. A pointer type created by the Ref generator always has a literal value Null (corresponds to NULL in C), which is also the default value. The literal Alloc is used for the dynamic creation of new memory. Examples are given later.

Note:

It is up to the user to keep track of all dynamically allocated data areas and to free them when they are no longer needed.

The following operators are available for Ref types:

"*>" : Ref, Itemsort -> Ref;
"*>" : Ref -> Itemsort;
"&" : Itemsort -> Ref;
make! : Itemsort -> Ref;
free : in/out Ref;
"+" : Ref, Integer -> Ref;
"-" : Ref, Integer -> Ref;
vstar2ref : Voidstar -> Ref;
ref2vstar : Ref -> Voidstar;
ref2vstarstar : Ref -> Voidstarstar;

Furthermore, the following procedure is defined:

procedure Free; fpar p Voidstarstar; external;

These operators can be used in the following way:

  • *> (postfix operator):
    Gets/changes the contents of a pointer. This is a postfix operator, so p*> returns the contents of pointer p. In SDL terminology this is the extract and modify operators for pointers.
  • & (prefix operator):
    Address-operator. This is a prefix operator, so &var returns a pointer to variable var.
  • make! or (. .)
    This constructor allocates new memory and assigns the parameter to make to the newly allocated memory.
  • free
    This operator takes a pointer variable, frees the memory it refers to and sets the pointer variable to Null.
  • +, -:
    used to add/subtract an offset to/from an address. This can be useful to access arrays in C. These operators are defined as in C, e.g. if p is a pointer to some struct, then p+1 points to the next struct (not to byte p+1).
  • vstar2ref:
    Converts Voidstar to another pointer type. Should only be used to "cast" the result of C functions that return a void *.
  • ref2vstar:
    Converts a pointer to Voidstar. This is useful when calling C functions that have void * parameters.
  • ref2vstarstar:
    Returns the address of the pointer as a void **. This operator is needed when calling the Free procedure.
  • Procedure Free: (NOTE: use free operator above instead)
    This procedure is used to release memory that has previously been allocated with alloc. This procedure is only provided for backward compatibility, use the free operator described above instead.

Example 36 : Use of the Ref operators

NEWTYPE ptr Ref(Integer)
ENDNEWTYPE;

DCL p ptr,
i, j Integer;

TASK p := alloc; /* creates dynamically a new
integer; p points at it */
/* here it should be checked that p != Null */
TASK p*> := 10; /* changes contents of p */
CALL free(p); /* releases the integer */
TASK p := (. 10 .); /* allocate and set to 10 */
CALL free(p); /* releases the integer again */
TASK p := &i; /* p now points to i */
TASK p*> := 5; /* changes contents of p, i.e. also
i is changed! */
TASK j := p*>; /* gets contents of p (=5) */

Using Linked Structures with Pointers

Pointers are useful when defining linked structures like lists or trees. In this section we give an example of a linked list containing integer values. Figure 43 shows an SDL fragment with data type definitions for a linked list, and part of a transition that actually builds a linked list. A list is represented by a pointer to an Item. Every Item contains a pointer next to the next item in the list. In the last item of the list, next = Null.

Figure 43 : Building a linked list

Figure 44 shows an SDL fragment where the sum of all elements in a list is computed. Note that this computation would never stop if there would be an element that points back in the list, just to illustrate how easy it is to make errors with pointers.

Figure 44 : Going through the list


Using ASN.1 in SDL

ASN.1 is a language for defining data types that is frequently used in the specification and implementation of telecommunication systems. ASN.1 is defined in ITU-T Recommendations X.680-X.683. Recommendation Z.105 defines how ASN.1 can be used together with SDL. A subset of Z.105 is implemented in the SDL suite.

This chapter explains how ASN.1 data types can be used in SDL systems. The following items will be discussed:

  • How to organize ASN.1 modules in the SDL suite
  • How to use ASN.1 data types in SDL
  • How to share ASN.1 data between SDL and TTCN

Organizing ASN.1 Modules in the SDL Suite

It is recommended to have a special chapter for ASN.1 modules (for example called ASN.1 Modules). If many ASN.1 modules are used, they may be grouped into Organizer modules (which is not the same as ASN.1 modules!), see "Module.

Figure 45 shows an example of the Organizer look of a chapter with two Organizer modules containing ASN.1 modules.

Figure 45 : Example of ASN.1 modules in the Organizer

We will show with an example how to use an ASN.1 module in an SDL system. Suppose we have an ASN.1 module MyModule in file mymodule.asn:

MyModule DEFINITIONS ::=
BEGIN

Color ::= ENUMERATED { red(0), yellow(1), blue(2) }

END

This module contains one type definition, Color, that has three values, red, yellow, and blue.

We first add a new diagram of type Text ASN.1 to the Organizer using Edit/Add New (without showing it in the Editor) and we connect it to the file mymodule.asn (using Edit/Connect). In order to use the ASN.1 module in SDL, we edit the system diagram and add use MyModule; in the package reference clause, as is illustrated in Figure 46 below.

Figure 46 : Using an ASN.1 Module in SDL

Figure 47 shows the resulting Organizer view. The symbol below the MySDLSys system symbol is a dependency link that indicates that the SDL system depends on an external ASN.1 module. Dependency links for ASN.1 modules that are used by an SDL system were previously required by the Analyzer, but now only serve as comments and are optional.

Figure 47 : Organizer View of SDL System Using ASN.1 Module

If ASN.1 modules use other ASN.1 modules, dependency links between the ASN.1 modules should be created.

Using ASN.1 Types in SDL

After the above preparations, the data types in MyModule can be used in SDL. As an example, we will make an SDL system that converts a character string to the corresponding color. This is done by two signals:

  • Signal GetColor has ASN.1 type IA5String as a parameter.
  • When this signal is sent to the SDL system, the SDL system will reply with signal ReturnColor, that has a BOOLEAN parameter indicating whether there is a color that matches the string, and a Color parameter.

The system diagram including these signal definitions is shown in Figure 48 below.

Figure 48 : SDL system diagram

The MSC below illustrates how the system is intended to be used.

Figure 49 : MSC illustrating GetColor

In order to know which values and which operators can be used on ASN.1 types, it is necessary to look in "Translation of ASN.1 to SDL.

For example, Color is defined as an ENUMERATED type. By looking at the mapping rules in "Enumerated Types, we see the list of operators that can be used on Color. These are in this case num, <, <=, >, >=, pred, succ, first, last, and also = and /=, which are always available.

Figure 50 : Using the Color type in SDL

Figure 50 shows a fragment of an SDL process that uses Color. It contains a loop over all values of Color, and illustrates how to declare variables of Color, how to use Color in new SDL sort definitions, and how to use the operators first, last, and succ. Some notes on the fragment:

  • The type ColorToString is used to convert a color to an IA5String. In the fragment we do actually the opposite. An alternative solution would be to have a StringToColor Array (IA5String, Color) because then no loop would have been needed (see also "Array" ). However, the purpose of the example was to illustrate how to loop through all elements.
  • Operator first in c := first(red) returns the element with the lowest associated number. This ensures that we really get all elements when using the Succ operator. In this case we could just as well have written c := red.
  • Note also the use of the predefined ASN.1 type IA5String, which is in fact a syntype of the predefined SDL sort Charstring.

Using Predefined ASN.1 Types in SDL

The predefined simple ASN.1 types can be used directly in SDL. In most cases, the ASN.1 type has the same name in SDL, for example ASN.1's type NumericString is also called NumericString in SDL. However, some predefined ASN.1 types contain white-space, like BIT STRING. In SDL, the white-space is replaced with an underscore, so the corresponding SDL sort is called BIT_STRING.

The operators on these predefined ASN.1 types are described in detail in section "Using SDL Data Types" .

Using ASN.1 Encoding Rules with the SDL Suite

The ASN.1 constructs defined in ITU-T Recommendation X.690 and X.691 are supported, which is explained in "ASN.1 Encoding and De-coding in the SDL Suite" on page 2731 in chapter 58, ASN.1 Encoding and De-coding in the SDL Suite, in the User's Manual.

Sharing Data between SDL and TTCN

One more advantage of ASN.1 is that TTCN is also based on this language. By specifying the parameters of signals to and from the environment of the SDL system with ASN.1 data types, this information can be re-used in the TTCN suite for the specification of test cases for the system.

Figure 51 : Sharing ASN.1 definitions between SDL and TTCN

This has the big advantage of making it easier to keep the SDL specification consistent with the TTCN test specification.

The use of external ASN.1 in TTCN is covered in more detail in the TTCN suite manual. In this section we will briefly illustrate how to share data between SDL and TTCN using TTCN Link.

Supposing we have to write a test suite for the SDL system with the Colors example, we would add a new diagram - a TTCN Test Suite, for example called ColorTest - to the Organizer. In this test suite we want to use definitions from the ASN.1 module MyModule that contains the Colors data type. For this purpose we need to set a dependency link between the ASN.1 module and the test suite. We do this by selecting the ASN.1 module in the Organizer. By using Generate/Dependencies we connect it to the TTCN test suite ColorTest.

We can also use TTCN Link to generate declarations from SDL system MySDLSys. For this purpose, it is easiest to associate the SDL system with the TTCN test suite. This is done by selecting the SDL system diagram in the Organizer and associate it with the TTCN test suite using Edit/Associate. The Organizer View for the test suite now looks as in Figure 52 below:

Figure 52 : Organizer view of a test suite that uses ASN.1

We can generate a TTCN Link executable for the SDL system by selecting the SDL system in the Organizer and using Generate/Make select standard kernel TTCN Link. Now we can start the TTCN suite by double-clicking on test suite ColorTest. By using TTCN Link/Generate Declarations, we can automatically generate the PCOs, ASP type definitions and ASN.1 type definitions. If we look at the result, we can see that Color is present as an ASN.1 Type Definition by Reference. This table is shown in below.

Figure 53 : Resulting table in the TTCN suite

Now this data type can be used in creating test cases, in constraints, etc. If at some point in time the definition of Color would be changed (for example if we would add a new color), then, in order to update the test suite accordingly, we can select the TTCN table for Color. In the Analyzer dialog, we should select both Enable Forced Analysis and Retrieve ASN.1 Definitions. Now the TTCN test suite will be updated with the new definition for Color.


3 Using SDL Extensions

This chapter describes some of the extensions to SDL that are available in the SDL suite, and that are not documented outside Telelogic.

The extensions covered here are the Own and ORef generators, and the algorithmic extensions to SDL. There are other Telelogic-specific extensions to SDL supported in the SDL suite, mainly concerning data types, generators and operators. These extensions are covered in 2 Data Types.


Own and ORef Generators

Introduction

A major problem to obtain fast applications generated from SDL is the data model, that requires copying of data in a number of places. In an interchange of a signal between two processes, the signal parameters are first copied from the sending process to the signal and then again copied from the signal to the receiver. If the two processes have access to common memory, it would be possible only to pass a reference to the data via the signal, and in that way there would be no need to perform the two copy actions.

The generator Ref can be used for this purpose (see "The Ref Generator" ), but there is a number of important problems when using the Ref generator:

  • The user has to deallocate memory when it is no longer used. If the user forgets this in any circumstance, memory will be lost.
  • It is easy to, intentionally or unintentionally, access the same memory from several process instances. This is very bad practice in real-time programming (without protection for simultaneous access to the memory) and might cause unwanted behavior. These kinds of errors are usually very difficult to find.

Basic Properties of the Own Generator

The purpose of the Own generator is to solve the situation described above, i.e. it should be possible to limit the number of copy operations that are needed, at the same time as the user should not need to worry about memory deallocation, and simultaneous access to the memory from several processes should not be possible.

The basic property of the Own generator that makes this possible is that only one Own pointer at a time can refer to the same memory. This variable (of Own type) is referred to as the owner of the memory. Ownership is passed to another variable by assignment.

Example 37 : Own variables

newtype Data struct
a, b integer;
endnewtype;

newtype Own_Data Own(Data)
endnewtype;

dcl
v1 Own_Data,
v2 Own_Data;

task v1 := v2;

This assignment is interpreted as follows:

  • If v1 refers to some memory this memory is deallocated.
  • v1 is assigned the value of v2, i.e. refers to the same memory as v2.
  • v2 is set to Null.

By this scheme the basic properties of the Own generator is preserved, i.e. all memory no longer accessible is deallocated and there is only one reference to the data.

To handle more complex cases, the order in which these operations are performed is a bit more complicated. With the same types and variables as in the example above and the procedure P, taking three Own_Data parameters:

task v1 := P(v2, v1, v2);

we get the following execution:

Evaluation of the right-hand side is performed from left to right, i.e. starts with the first actual parameter of P. The first formal parameter of P is assigned the value of v2 and takes the ownership of this memory. The variable v2 is assigned the value Null. The same thing happens for the second formal parameter and the variable v1. The third formal parameter of P get the value Null as v2 is Null at this point.
Now the procedure P is called and its return value is obtained. Before assigning this value to the variable on the left hand side, i.e. to v1, the memory currently referred to by v1 is deallocated. In this case v1 is Null at this point as the second formal parameter of P already have taken the ownership of this memory. Last the variable v1 is assigned the value returned by P.

Ownership is, as can be seen in the example above, passed not only in assignments, but in every case where the reference is assigned to some other place. This happens for example in assignments, input, output, set, reset, procedure call, and create. The only places where ownership is not passed is:

  • when the explicit copy function is used, for example
    task v1 := copy(v2);
  • in import, export, and view operations, which are interpreted as containing implicit copy operations.
  • in calls to the standard functions `=' and "/=".

Note that copy(v2) is a "deep" copy, i.e. any Own pointers in the copied data structure are also copied. Otherwise we would end up with several references to the same memory.

Definition of Own Generator

The Own generator is defined in SDL according to the following:

GENERATOR Own (TYPE Itemsort)
LITERALS
Null;
OPERATORS
"*>" : Own, ItemSort -> Own;
"*>" : Own -> ItemSort;
make! : ItemSort -> Own;
DEFAULT Null;
ENDGENERATOR Own;

Basically the Own generator is a way to introduce pointers to allocated memory. The Null value is as usual interpreted as "a reference to nothing". The operators "*>" are the Extract! and Modify! operators, i.e. the way to reference or modify the memory referred to by the pointer. Using the type and variables in the previous example the following statements are correct:

task v1*>!a := 1;
task i := v2*>!b;
/* integer assignment, i is integer variable */
task d := v2*>;
/* struct level assignment, d is of type Data */

The "*>" operator have the same properties as the `*' in C, i.e. "v1*>" has the same meaning as "*v1" in C. To make the syntax a bit easier there is a possibility to let the SDL Analyzer implicitly insert the "*>" in the expressions where it is needed. The example above would then become:

task v1!a := 1;
task i := v2!b;
/* integer assignment, i is integer variable */
task d := v2;
/* struct level assignment, d is of type Data */

which is a bit easier to read. More details about the implicit type conversions can be found in "Implicit Type Conversions" .

Before it is possible to start working with components in the data referenced by the Own pointer, the Own pointer must be initialized with a complete value (default is Null as can be seen in the definition). The Make! operator is a suitable way to initialize a variable. As usual the concrete syntax for Make! is "(. x .)", where x should be replaced by a value of the ItemSort for the current Own pointer.

Example of intializations using the data definitions in the examples above:

dcl v1 Own_Data := (. (. 1, 2 .) .);
task v1 := (. (. 5, 5 .) .);

The inner "(. .)" is for the constructing the struct value and the outer "(. .)" is for the Own make! function. It is, however, possible to avoid the double parentheses as there is an implicit type conversion from a type T to Own(T), by implicitly inserting "(. .)" around a value of type T. So the examples above could (and probably should) be written as

dcl v1 Own_Data := (. 1, 2 .);
task v1 := (. 5, 5 .);

Again, please see "Implicit Type Conversions" . The other operations available for own pointers, apart from "*>" and make!, are assignment, test for equality, and copy. The assign operator has already been described above. Test for equality (`=' and "/=") does NOT test for pointer equality as two Own pointers cannot be equal. Instead equality is "deep" equality, i.e. the values referred to by the Own pointers are compared.

An implicit copy operator has been inserted for every type. It takes a value and returns a copy of that value. For all types that are not Own pointers or contain Own pointers, this operator is meaningless as it just returns the same value. For Own pointers or for structured values containing Own pointers, the copy function, however, copies the values referenced by the Own pointers.

The ORef Generator

The ORef generator is intended to be used together with the Own generator to provide a way to temporary refer to owned data during some algorithm, without affecting the ownership of the memory. If, for example, Own pointers is used to create a linked list and we would like to write a procedure that calculates the length of the list, then we need a temporary pointer going through the list. If that pointer was a Own pointer the list would be destroyed while we traverse the list, as there may be only one Own pointer referring to the same memory.

Example 38 : Own and ORef

newtype ListElem struct
Data MyType;
Next ListOwn;
endnewtype;

newtype ListOwn Own(ListElem)
endnewtype;
newtype ListRef ORef(ListElem)
endnewtype;

procedure ListLength; fpar Head ListRef;
returns integer;
dcl
Temp ListRef,
Len Integer;
start;
task Len := 0, Temp := Head;
again :
decision Temp /= null;
(true) :
task Len := Len+1, Temp := Temp!Next;
join again;
(false) :
enddecision;
return Len;
endprocedure;

dcl
MyList ListOwn,
L integer;

task L := call ListLength(MyList);

Note the use of the ListRef type both in the formal parameter Head and in the local variable Temp. If Head would be of ListOwn type, the variable MyList would be null after the call of ListLength, which is not what we intended. If ListOwn was used as type for the variable Temp, as the statement Temp := Temp!Next would unlink the complete list.

Another example of a typical application of ORef, is to introduce backward pointer in a linked list, to make it doubly linked. If the forward pointers are Own pointers then the backward pointers cannot be Own pointers as then we would have two Own pointers on the same object.

The ORef generator is defined as:

GENERATOR ORef (TYPE Itemsort)
LITERALS
Null;
OPERATORS
"*>" : ORef, ItemSort -> ORef;
"*>" : ORef -> ItemSort;
"&" : ItemSort -> ORef;
"=" : ORef, ItemSort -> Boolean;
"=" : ItemSort, ORef -> Boolean;
"/=" : ORef, ItemSort -> Boolean;
"/=" : ItemSort, ORef -> Boolean;
DEFAULT Null;
ENDGENERATOR;

Where "*>" is used for dereferencing and `&' is an address operator.

Run-Time Errors

There are four situations, concerning Own and ORef, that can lead to a run-time error. These situations are:

  • Dereferencing of a null pointer.
  • An ORef pointer that refers to an object that has been deallocated.
  • An ORef pointer that refers to an object that is owned by another process.
  • A cycle of Own pointers is created, as this memory can never be deallocated.

These problems are all found during simulation and validation, except that if an ORef pointer refers to a data area that is first deallocated and then allocated again, the ORef pointer is no longer invalid.

Examples of run-time error situations assuming the data types in the previous section.

dcl
L1, L2 ListOwn,
R1, R2 ListRef,
I Integer;

task
L1 := null,
R1 := null,
L1!Data := 1,
/* ERROR: Dereferencing of Null pointer */
I := R1!Data;
/* ERROR: Dereferencing of Null pointer */

task
L1 := (. 1, null .),
R1 := L1,
L1 := null,
I := R1!Data;
/* ERROR: Reference to deallocated memory */

task
L1 := (. 1, null .),
R1 := L1;
output S(L1) to sender;
task
I := R1!Data;
/* ERROR: Reference to memory not owned by
this process */

task
L1 := (. 1, null .),
L1!Next := (. 2, null .),
L1!Next!Next := L1;
/* ERROR: Loop of own pointers created */

Implicit Type Conversions

Note:

Implicit type conversions are by default off in the SDL Analyzer. It can be turned on in the Analyze dialog in the Organizer. Implicit type conversions will, however, influence the time needed for semantic analysis. The more complex an expression is, the more effect on time the implicit type conversions will have, as the number of possibilities increases (often exponentially) with the length of the expression.

The purpose of the implicit type conversions is to simplify the use of the Own generator. The code that operate on data structures should be the same if you use a data structure T or if you use a own pointer to T, own(T). The only thing that a user has to think about is if ownership should be passed or if a copy should be made, when passing data to somewhere else.

The implicit conversions never change the type of, for example, an assignment. If there is an assignment:

task R1 := L1;

no implicit type conversions are applied on R1, as that would change the type of the assignment. Type conversions might be applied on L1 in the right hand side, to obtain the correct type. In an assignment:

task Q(a) := ...;

the implicit type conversions might also be applied to the index expression, i.e. to a.

In a test for equality and in similar situations, e.g. in:

L1 = R1

implicit type conversions are first applied to the left expression, i.e. to L1. If that yields a correct interpretation, that one is selected. Otherwise implicit type conversions are tried on the right expression, i.e. to R1.

Assume a type T and a two generator instantiations Own_T = Own(T) and ORef_T = ORef(T). Assume also the variables:

dcl
t1 T,
v1 Own_T,
r1 ORef_T;

Then the following implicit type conversions are possible:

1. Own_T -> T, by v1 -> v1*>
2. T -> Own_T, by t1 -> (. t1 .)
3. Own_T -> ORef_T, by v1 -> demote(v1)
4. ORef_T -> Own_T, by r1 -> (. r1*> .)
5. T -> ORef_T, by t1 -> &t1
6. ORef_T -> T, by r1 -> r1*>

Type conversions 1 and 6 make it possible to exclude "*>" in component selections. Instead of writing

a*>!b*>(10)*>!c

it is possible to write

a!b(10)!c

This possibility also exists for ordinary Ref pointers.

Type conversion 2 makes it possible to assign an Own pointer a new value of the Own pointer component type. If A is a Own pointer to a struct containing two integers, then it is possible to write:

A := (. 1, 2 .);

which means the same as

A := (. (. 1, 2 .) .);

where the inner "(. .)" is the make! function for the struct and the outer "(. .)" is the make! function for the Own pointer.

This possibility also exists for ordinary Ref pointers.

Type conversion 3 makes it possible to assign an ORef pointer to an Own pointer. This is already used in the examples above, but is not directly possible, as an ORef and an Own pointer are two distinct types. The demote operator converts a Own pointer to the corresponding ORef pointer. (Corresponding means the first ORef with the same component type in the same scope unit as the Own pointer type is defined).

Type conversion 4 makes it possible to construct a new Own value, starting from a ORef value. The conversion is performed in two steps, first going from ORef_T to T by applying conversion 6, and then from T to Own_T by applying conversion 2.

Type conversion 5 makes it possible to let a ORef_T pointer refer to a DCL variable by writing:

task r1 := t1;

which means the same thing as

task r1 := &t1;

where `&' is the address operator (as in C).


Algorithms in SDL

A former problem in SDL is the lack of support for writing algorithms. For pure calculations, not involving communication, the graphical form for SDL tends to become ordinary flow charts, which is usually not a good way to describe advanced algorithms. Such, often large, parts of an SDL diagram also hide other, from the SDL point-of-view, more important parts of the diagram, namely the state machine and the communication aspects.

The algorithmic extensions described here addresses these problems by introducing the possibility to write algorithms in textual form within a Task symbol, and also to define procedures and operators in textual form in text symbols. There are two major advantages with this approach, compared to ordinary SDL:

  • The algorithms are written in a compact form, similar to ordinary programming languages, and will therefore not hide other important aspects of an SDL diagram.
  • The language used within the algorithms contains more powerful algorithmic constructs than ordinary SDL, like if-then-else, and loop statements.

In addition, the algorithmic extensions make it possible to now define procedures and operators in textual form in text symbols in SDL/GR.

These algorithmic extensions to SDL have been approved by ITU Study Group 10 to be incorporated into the official Master List of Changes that will affect the next ITU recommendation for SDL. There are a few minor differences in the support for SDL algorithms in the SDL suite compared with the ITU definition - these are noted in the descriptions below.

The constructs that are part of the extensions are:

  • Compound Statement
  • Local Variables
  • If Statements
  • Decision Statements
  • Loop Statements
  • Label Statements
  • Jump Statements
  • Empty Statements

Compound Statement

The basic concept in the algorithmic extensions is the compound statement. A compound statement starts with a `{', which is followed by a sequence of variable declarations and a sequence of statements, and it then ends with a `}'.

A compound statement may be used in three places:

  • as the contents of a TASK,
  • as the body of a procedure or operator definition in a text symbol,
  • as a statement within an enclosing compound statement.

Note:

According to the ITU language definition the body of a procedure or operator is allowed to be a statement. In the SDL suite, however, a compound statement is required. This means that if the body consists of only one statement, the enclosing "{ }" are required anyhow.

Note also that the enclosing "{ }" should not be included in a Task symbol in the SDL Editor. These braces will be added when the SDL system is converted to SDL/PR for analysis.

Example 39

Contents in Task symbol in SDL/GR:

a := b+1;
if (a>7) b := b+1;

Corresponding code in SDL/PR:

task {
a := b+1;
if (a>7) b := b+1;
};

Example 40

A procedure in a text symbol in SDL/GR, or in SDL/PR:

procedure p fpar i integer returns integer
{
if (i>0)
i := i+1;
else
i := i-1;
return i;
}

Local Variables

Within a compound statement it is allowed to define a number of local variables. These variables will be created when the compound statement is entered and will be destroyed when the compound statement is left. The semantics of a compound statement is very much like a procedure without parameters, which is defined and called at the place of the compound statement.

A variable declaration within a compound statement looks that same as ordinary variable declarations, except that "exported" and "revealed" are not allowed. Example:

dcl
a, b integer := 0,
c boolean;

Statements

A statement within a compound statement my be of any of the following types:

  • compound statement
  • output statement
  • create statement
  • set statement
  • reset statement
  • export statement
  • return statement (only in procedures and operators)
  • procedure call statement
  • assignment statement
  • if statement
  • decision statement
  • loop statement
  • label statement
  • jump statement
  • empty statement

Note that each statement (and each variable declaration statement) ends with a `;'. The following statement types use the same syntax as in ordinary SDL/PR:

output, create, set, reset, export, return, call, assignment

Example 41 : Ordinary SDL/PR statements

output s1(7) to sender;
output s2(true, v1) via sr1;
create p2(11);
set(now+5, t);
reset(t);
export(v1);
return a+3;
call prd1(a, 10);
a := a+1;

Note:

According to the ITU language definition the keyword call in a procedure call is optional. In the SDL suite it is, however, required.

If Statements

The structure of an if statement is:

if ( <Boolean expr> )
<Statement>
else
<Statement>

where the else part is optional. The Boolean expression is first calculated. If it has the value true, the first statement is executed, otherwise the else statement, if present, is executed.

Example 42

if (a>0)
a := a+1;

if (a=0) {
a := 100;
b := b+1;
} else {
a := a+1;
b := 0;
}

If there are several possible if statements for an else path (the "dangling else" problem), the innermost if is always selected.

Example 43

if (a>0)
if (b>0)
a := a+1;
else
a := a-1;

means:

if (a>0) {
if (b>0)
a := a+1;
else
a := a-1;
}

Decision Statements

A decision statement has much in common with the ordinary decisions found in SDL, i.e. it is a multi-branch statement. The major differences between decision statements and ordinary statements is that all paths in a decision statement ends at the enddecision.

Example 44

decision (a) {
(1:10) : {call p(a); a := a-5;}
(<=0) : a := a+5;
else : a := a-5;
}

The decision question and the decision answers follows the same syntax and semantics as in ordinary decisions. Following an answer there should be a statement, which might be a compound statement.

Loop Statements

A loop statement is used to repeat the execution of a statement (or usually a compound statement), a number of times. The loop is controlled by a loop variable, which either can be locally defined in the loop or defined somewhere outside of the loop.

The loop control part contains three fields:

  • the loop variable indicator with a start value,
  • the loop test expression,
  • the new loop variable value.

Example 45

for (a := 1, a<10, a+1)
sum := sum+a;

should be interpreted as (in C-like syntax):

a = 1;
while (a<10) {
sum = sum+a;
a = a+1;
}

Note the difference between SDL and C when it comes to the variable update. In C this is a statement, in SDL it is an expression to be assigned to the variable mentioned in the loop variable indicator.

In the loop variable indicator, either a new variable can be defined or a previously defined variable can be used. Example:

for (a := 1, ...
for (dcl a integer := 1, ...

Other possibilities in loop statements:

  • One or more of the loop control part fields can be empty. If, however the loop variable indicator (first field) is empty, then the loop variable update field (third field) must also be empty. Example:
for (a := 1, , a+1) ..
for ( , , ) ...

  • A loop may contain several loop control parts. Example:
for (a := 1, a<10, a+1; b := 1, b<5, b+1)
sum := sum+a+b;
This should be interpreted as (in C like syntax):
a = 1;
b = 1;
while ( (a<10) and (b<5) ) {
sum = sum+a;
a = a+1;
b = b+1;
}

  • Break statements can be used to break out of a loop. See "Label Statements" and "Jump Statements" .
  • A loop statement may end with a "then" statement, which is executed if the loop is terminated because of the loop test expression becomes false. The "then" statement is not executed if the loop is terminated due to a break statement. Example:
ok := false;
for (a:=1, a<10, a+1) {
sum := sum+arr(a);
if (sum > limit) break;
}
then
ok := true;

Label Statements

A label statement is just a label followed by a statement. These labels are only of interest if the statement following the label is a loop statement. The label name can be used in break statements (see below) to break out of a loop statement. Example:

L:
for (i:=0, i<10, i+1)
sum := sum+a(i);

Note:

There are no "join" or "goto" statements allowed in the algorithmic extensions to SDL.

Jump Statements

Jump statements, i.e. break and continue, are used to change the execution flow within a loop.

A continue statement, which only may occur within a loop, is defined as: "skip the remaining part of the loop body and continue with updating the loop variable to its next value."

Example 46

for (a:=1, a<10, a+1) {
if (sum > limit) continue;
sum := sum+arr(a);
}

should be interpreted as (in C like syntax):

a = 1;
while (a<10) {
if (sum > limit) goto cont;
sum = sum + arr[a];
cont :
a = a+1;
}

A break statement can be used to stop the execution of the loop and directly goto the statement after the loop.

Example 47

ok := false;
for (a:=1, a<10, a+1) {
sum := sum+arr(a);
if (sum > limit) break;
}
then
ok := true;

should be interpreted as (in C like syntax):

ok = false;
a = 1;
while (a<10) {
sum = sum + arr[a];
if (sum > limit) goto brk;
a = a+1;
}
ok = true;
brk:

A break statement breaks out of the innermost loop statement. By using labeled loop statements breaks out of outer loops can be achieved.

Example 48

L: for (x:=1, x<10, x+1) {
a := 0;
for (y:=1, y<10, y+1) {
a := a+y;
if (call test(x,y)) break L;
}
}

The break statement in the inner loop breaks out from both loops as it mentions the label for the outer loop.

Empty Statements

It is allowed to have an empty statement, represented by just writing nothing. This is sometimes useful, for example as loop statement:

for (i:=1, Arr(i)/=0 and i<Limit, i+1) ;
/* This loop sets i to the index of the first zero
element in the Array Arr. */

Grammar for the Algorithmic Extensions

Meta grammar:

 `dcl', `)', `;'	 are examples of terminal symbols.
 <Stmt>, <Name>	 are examples of non-terminal symbols.
 ::=	 means defined as.
 $	 means used for empty.
 *	 means 0 or more occurencies.
 +	 means 1 or more occurencies.
 |	 means or.
Start of Grammar

<CompoundStmt> ::=
`{' <VarDefStmt>* <Stmt>* `}'

<VarDefStmt> ::=
`dcl' <Name> (`,' <Name>)* <Sort> (`:=' <Expr> | $)
( `,' <Name> (`,' <Name>)* <Sort> (`:=' <Expr> | $) )*
`;'

<Stmt> ::=
<CompoundStmt> |
<Outputx> `;' |
<CreateRequest> `;' |
<Setx> `;' |
<Resetx> `;' |
<Export> `;' |
<Return> `;' |
<ProcedureCall> `;' |
<IfStmt> |
<LabelStmt> |
<AssignmentStatement> `;' |
<DeciStmt> |
<LoopStmt> |
<JumpStmt> `;' |
<EmptyStmt> `;'

<IfStmt> ::=
`if' `(' <Expr> `)' <Stmt> (`else' <Stmt> | $)

<DecisionStmt> ::=
`decision' `(' <Expr> `)' `{'
( <Answer> <Stmt> )+
( `else' <Stmt> | $)
`}'

<Answer> ::= same as answer in ordinary decisions

<LoopStmt> ::=
`for' `(' (<LoopClause> (`;' <LoopClause>)* | $) `)'
<Stmt>
(`then' <Stmt> | $)

<LoopClause> ::=
(<LoopVarInd> | $) `,' (<Expr> | $) `,' (<Expr> | $)

<LoopVarInd> ::=
`dcl' <Name> <Sort> `:=' <Expr> |
<Identifier> (`:=' <Expr> | $)

<LabelStmt> ::=
<Label> <Stmt>

<JumpStmt> ::=
<Break> (<Name> / $) |
<Continue>

<EmptyStmt> ::=
$

End of Grammar

Algorithms in Simulator/Validator

The textual trace in the SDL Simulator and the SDL Validator for the new algorithmic extensions will be according to the table below.

Statement
Textual trace
Comment
Compound
No trace
If

 IF (true)
 IF (false)

Decision

 DECISION  Value: 7
Same trace as for ordinary decisions
Loop

 LOOP variable b := 3
 LOOP test TRUE
 LOOP test FALSE
For loop variable assignments
For loop tests
Jump

 CONTINUE
 BREAK
 BREAK LoopName

Empty
No trace

A compound statement without variables declarations is seen as just a sequence of statements, while a compound statement with variable declarations is seen as a procedure call of a procedure with no name, without parameters. However, no trace information is produced for this implicit procedure call or procedure return.

When it comes to variables, these are available in the simulator interface just in the same way as if compound statements where true procedures. That is, the commands Up and Down can be used to view variables in different scopes. Note that a variable defined in a loop variable indicator introduces a scope of its own.

There is one exception of this general treatment of variables in local scopes and that is procedures defined as a compound statement.

In this procedure:

procedure p
fpar in/out a integer
{
dcl b integer;
...
}

the parameter a and the variable b will be in the same scope, the procedure scope. For compound statements within the outermost procedure scope the general rules above apply.

Execution Performance in Applications

Cadvanced

All concepts in the algorithmic extensions have efficient C implementations, except variable declarations in local scopes (including in a loop variable indicator), as such compound statements will become SDL procedure calls.

Cmicro

All concepts in the algorithmic extensions have efficient C implementations. Compound statements containing variables are implemented using C block statements.


4 Organizing a Project

This chapter explains how diagrams and other documents that can be handled in the Organizer, may be managed in a project including several project members. The functionality of the SDL suite related to management of diagrams in a project environment is provided by the Organizer. A reference manual for the Organizer can be found in The Organizer.


Introduction

General

Software development projects are typically staffed by a large number of software engineers, each working simultaneously on different parts of the same system. This requires careful coordination and version control of the different parts of the system. Normally, stable (well-defined) versions of a system are stored in a central storage area (in this chapter named the original area) accessible for each user. The original area is typically either:

  • A directory containing different versions of the system managed by a version or revision control system, e.g. RCS, CM Synergy or ClearCase.
  • An ordered set of directories, where each directory represents one version of the system and contains the information that has changed as compared to the previous version. For example, version 1 of the system PBX may be stored in the directory PBX-1 which contains version 1 of all parts of the system PBX. Version 2 of the system PBX is then stored in the directory PBX-2 which contains only the parts of the system that has changed in comparison to PBX-1.

In addition, each project member may have his own work area where he temporarily stores the parts of the system he is currently working on. Furthermore, a project may also use a reference area which contains one or more packages of information that are shared between different projects.

This way of working is supported by the Organizer tool. It allows the members of a project to work independently, but in a coordinated and structured way. In particular, the tool supports:

  • Individual customization of the user environment.
  • Easy visualization of the SDL system's contents, in terms of SDL packages and diagrams, Message Sequence Charts and physical files.
  • Updating of versions from each individual user's work area to the shared original area.
  • Copying of SDL diagrams and Message Sequence Charts between different storage areas.

Improved Support

To facilitate the management of more complex projects, the SDL suite can be integrated to control systems that are used to manage versions and revisions. Example of such systems are RCS, CM Synergy and ClearCase. The Organizer can easily be customized in order to extend the menus commands with support for "check-in", "check-out" and "update" operations. The extensions are defined in textual files that contain the definitions of the names of the menus and commands, what operations they will call in the control system, what objects are the subject of the operation, etc.

The rest of this chapter is organized as follows:

  • "Diagram Binding" describes the principles for how diagrams and other documents are connected to files.
  • "How to Manage the Diagrams in a Project" describes how the tools can be used to manage the SDL diagrams in a project environment.


Diagram Binding

The Organizer provides the ability to manage the diagrams and other documents that build up a project, without the need for an external version or revision control system.

Important is that one diagram is represented by one file, and the mapping between diagrams and files are kept in the system file. The system file is the file that is opened when issuing the Open command in the Organizer. The system file has by default the extension .sdt.

A diagram may be bound to a physical file using the Organizer by:

  • Automatic Binding
  • Manual Binding

Automatic Binding

Diagrams may be bound automatically when the diagram is saved for the first time. The name of the physical file will by default be <diagram name>.<ext>, where <diagram name> is the name of the diagram and <ext> is a suggested extension of three letters indicating what type of diagram is contained in the file. See "Save for information on default file names and extensions.

Example 49

The block diagram with the name DemonBlock will by default be bound to the file demonblock.sbk

Manual Binding

Diagrams and files may be bound manually, on demand, via the command Connect. A file selection dialog appears and the selected diagram may be connected to an existing file. Another possibility is to look for the diagram file in a certain directory.

Figure 54 : Connecting a diagram to an existing file

When connecting a diagram, there is a possibility to automatically connect all diagrams in a possible substructure, the Expand Substructure option. The names of the files are not important when mapping files automatically, using this feature, since the diagram name is stored in the file. What is important though, is the extension of the file name which must correspond to the type of diagram stored in the file.

Source and Target Directories

Two settings in the Organizer are related to where diagrams are stored. The two settings are:

  • Source Directory
    The directory where new diagrams are stored.
  • Target Directory
    The directory where generated files are stored. Generated files do not include the source files, i.e. the files included in the Organizer Diagram Structure.

The source directory and the target directory may be changed in the Organizer by using the Set Directories command. In the Set Directories dialog there is also an option to either show the absolute path to files, or to show the path relative the Source directory. For a complete description of the functionality of this command, please see the "Set Directories.

Figure 55 : Specifying the Source and Target directories

This affects the way paths to files are stored in the system file:

  • If the option Absolute file names is chosen, then the absolute path will be stored in the system file.
  • If the option Relative file names is chosen, then only the relative path will be stored in the system file. This is important if the source directory should be moveable, in which case this option should be selected.


How to Manage the Diagrams in a Project

One way to manage the diagrams in a project is to have the original area managed by some external configuration or version control system, e.g. RCS (Revision Control System), which is available on most computer systems. In that case, every member of the project has his own work area. In each work area, there is a system file (or perhaps multiple system files, each one containing a different part of the system). All diagrams in the system file are bound to files in the users' work area. The relationship between files in the users' work area and files in the original area is managed by the external configuration or version control system.

The rest of this section describes how to use RCS as a version control system. For more information about SDL suite/RCS Integration, see Readme files in <inst dir>\examples\cm\win32\rcs\ or <inst dir>/examples/cm/unix/rcs/. How to use CM Synergy is described in "Using CM Synergy Together with an SDL System" . How to instead use ClearCase is described in "Using CM Synergy Together with an SDL System" .

The control is based on the following mechanisms:

  • The locking functionality in RCS, by using the check in and check out commands.
  • The multi user support in the Organizer, facilitated by the Control Unit File s.
  • The possibility to add own menu commands to the SDL suite, commands that in this case should connect the Organizer to RCS.

Note:

The following instructions and descriptions only addresses a UNIX system with the UNIX version of RCS.

Starting to Use RCS Together with an SDL System

When handling of files managed by RCS is to be introduced for an existing SDL system, the following approach can be used:

  1. Have all the files related to your system placed in one directory hierarchy which we call the work area.
  2. Set the Source Directory in the Organizer to the work area directory.
  3. Now we create the original area for the system as the RCS file database. The work area and the original area should have the same directory structure for a given diagram system. The original area will contain the RCS directories that hold the revision files, but these directories are empty for now. (Note that the work area does not have any RCS directories.)

Example 50 : Work and original area for the DemonGame system

The work area has three directories:

  • One for the files related to the system.
  • One for each of the two blocks (GameBlock and DemonBlock):
demonblock gameblock system

demonblock:
demon.spr demonblock.sbk

gameblock:
game.spr gameblock.sbk main.spr

system:
demongame.msc demongame.ssy systemlevel.msc

The original area for the Demon Game system (created in a different place in the file system) will then have the following structure:

RCS demonblock gameblock system

demongame/RCS:

demongame/demonblock:
RCS

demongame/demonblock/RCS:

demongame/gameblock:
RCS

demongame/gameblock/RCS:

demongame/system:
RCS

demongame/system/RCS:

  4. Define the root directory of the original area (setenv rcsroot <directoryname>) and load the RCS menu-set into the Organizer (run $telelogic/sdt/examples/RCS/sdtrcs.mnu). A new menu titled RCS appears in the Organizer menu bar.
    • The RCS menu in the Organizer is an example of how check in and check out can be done on one diagram and a hierarchy of diagrams. (The commands that are defined in the example could easily be tailored to fit specific needs).
  5. Check in the first version of each diagram file, using the Organizer commands Recursive Check In or Check In.
    • To visualize the results, make sure the file permissions are visible in the Organizer (Choose the View Options command in the View menu and select the option File access permissions.
  6. After a successful check in, the original area is now populated with the RCS files.

Example 51 : The Original Area, now populated

RCS demonblock gameblock system

RCS:

demonblock:
RCS

demonblock/RCS:
demon.spr,v demonblock.sbk,v

gameblock:
RCS

gameblock/RCS:
game.spr,v gameblock.sbk,v main.spr,v

system:
RCS

system/RCS:
demongame.msc,v demongame.ssy,v systemlevel.msc,v

Using the SDL suite and RCS in a Multi User Environment

If the system is developed by a group of developers it is useful to partition it and assign Control Unit File s, for the different partitions. For the DemonGame example, let us assume that the -DemonBlock is developed by one developer and the -GameBlock by another. The procedure here is to create:

    • a top level control unit file,
    • a control unit file for the DemonGame system,
    • a control unit file for the DemonBlock, and
    • a control unit file for the GameBlock.
  1. In order to assign a control unit file for an Organizer object we select the object and execute the Configuration > Group File command from the Edit menu.
  2. When the four control units above are assigned, we save the system from the Organizer (which also saves the control units on their respective .scu files).
  3. Now, we can check in the created .scu files. It is wise to have the control unit file located in the same directory as the corresponding object file.

Example 52 : The Original Area with Control Unit Files

The DemonGame original area with checked in control unit files:

RCS demonblock gameblock system

alfa/RCS:
demongame.scu,v

alfa/demonblock:
RCS

alfa/demonblock/RCS:
DemonBlock.scu,v demon.spr,v demonblock.sbk,v

alfa/gameblock:
RCS

alfa/gameblock/RCS:
GameBlock.scu,v game.spr,v gameblock.sbk,v main.spr,v

alfa/system:
RCS

alfa/system/RCS:
DemonGame.scu,v demongame.ssy,v
demongame.msc,v systemlevel.msc,v

Make Local Changes Global Using RCS

When a user has made changes in files that have been checked out and locked and wants to make these changes global for the complete project, the following steps should be performed.

  • Use Check In or Recursive Check In from the Organizer RCS menu, on the diagrams that have been modified. Note that Recursive check In will automatically handle control unit files as well.

Example 53 : Adding a Diagram to the Control Unit and Saving

Say that a new process diagram is added to the GameBlock:

  1. The user must therefore check out the files gameblock.sbk and GameBlock.scu.
  2. With the SDL Editor, the diagram GameBlock is updated to contain the new process reference symbol.
  3. When saving from the Organizer, GameBlock.scu will automatically be updated with the new process diagram file name. Note also that all changes will be local to the partition of the diagram system that represents the GameBlock and that no global update of the system file is needed.

Make Global Changes Local Using RCS

If a user is notified that there have been changes to the system, the following should be done in order to update the users' local system:

  • Use Check Out or Recursive Check Out to update the diagrams.
    • From Example 53 above, if the GameBlock has been modified a Recursive Check Out on the GameBlock object will bring in the newest checked in version.

Building and Populating a Work Area from RCS based Original Area

Say that we have an original area with its RCS directories containing the checked in diagrams and the control unit files. A developer that is new to the project wants to make a complete update of a system in his work area to get an up-to-date view.

  1. The developer must first create/update his work area directory tree. The environment variable rcsroot should be defined to point to the original area.
  2. In an empty Organizer: the RCS menus are loaded (use for instance the command $-telelogic/sdt/examples/RCS/sdtrcs.mnu), the Source Directory is set to the work area, and the top level control unit file is associated with the SDT symbol (using the Organizer Configuration > Group File command).
    • Note that the top level control unit file must be assigned the correct file name that is checked in. For the DemonGame example, the top level control unit file name would be DemonGame.scu in the work area top directory.
  3. To populate/update the work area, select the SDT symbol in the Organizer and perform Recursive Check Out.
  4. The new developer saves the system file to get a personal view of the diagram system.
    • When saving the system file, the Organizer tries to save the top level control unit file; this file is read-only and the Organizer will hence issue an error message which can be disregarded.

Endpoint Handling with RCS

Presently there is one global link file (the master link file) that holds the link information for a given system. A group of developers can coordinate changes to this file with the help of the RCS check out and lock facility, where only one developer can update the file at a time. A local link file is used for temporary storage of changes made to the endpoint and link information, until the user decides to make his changes global. Say we have checked in the first version of the link file into the original area. In order to modify the link file, the procedure would follow these guidelines:

  1. Issue the command Add Local Link File in the RCS menu.
  2. All changes to the endpoint and link information will now be stored in the local link file, and the master link file will be left unchanged.
  3. When it is time to update the global link information, check out the master link file by issuing the command Check Out And Lock Link File.
  4. Issue the command Merge Local Link File, which will update the master link file with the information from the local link file.
  5. Check in the master link file by issuing the command Check In Link File.

Simultaneous Editing of an SDL Diagram

There is a possibility for several users to work simultaneously on the same SDL diagram by utilizing the commands Split and Join, available in the Tools menu of the Organizer.

By the Split command, a diagram with several pages can be saved in several files, with disjoint sets of pages, thus enabling several users to edit them independently. The Join command simply merges two SDL diagrams of the same kind.


Using CM Synergy Together with an SDL System

This section describes one way of using the SDL suite and CM Synergy in an integrated way.

For more information about the SDL suite/CM Synergy Integration see the Readme file in the installation
<SDL Suite inst dir>\examples\cm\win32\cmsynergy\ or
<SDL Suite inst dir>/examples/cm/unix/cmsynergy/.

For a more general description of using a configuration or version control system, please see "How to Manage the Diagrams in a Project" .

Introducing CM Synergy with the SDL suite - Migration

When handling of files by CM Synergy is to be applied on a system being developed by the SDL suite, the following approach can be used.

  1. Make sure that all files (related to the system) are configured in one directory hierarchy outside CM Synergy.
  2. Install the CM Synergy menu into the Organizer. Add cmsynergy.ini to your org-menus.ini file.
    The SDL suite will search for the org-menus.ini first in the directory where the SDL suite was started, then in a directory pointed to by the HOME environment variable and finally in the directory in which the SDL suite was installed.
    If you do not already have a org-menus.ini file, the cmsynergy.ini can serve as one. Just copy cmsynergy.ini to either your HOME directory or to where you have the SDL suite installed and rename it to org-menus.ini. For more information on dynamic menus, see "Defining Menus in the SDL Suite" . (The CM Synergy menu that comes with the distribution of the SDL suite is an example and could be tailored by the user.)
  3. Set your path environment variable to include
    • <CM Synergy inst dir>\bin or <CM Synergy inst dir>/bin, and
    • <SDL Suite inst dir>\bin\wini386 or <SDL Suite inst dir>/bin.
      This is necessary to be able to start the tools from each other directly.
  4. Start the CM Synergy Client.
  5. Change role to ccm_admin.
  6. Display the Admin>Type Definition dialog to define an SDL file type. Enter the following values:
    Type Name: SDL
    Description: Binary file
    Super Type: binary
    Initial Status: working
    Require Task at:<none>
    Verify Comment Existence on Promote / Check In: Off
    Allow Update during Model Install: Off
    Associate with a File in the File System: On
    Can be a Product File: Off
    Icon Color / Fil: binary.bmp
    File Name Extension: .ssy
  7. Display the Type>Modify File Operations dialog, and enter the following values:
    (If necessary, replace sdt below with the command you use to start SDL Suite. If the sdt script is not in your PATH, you should specify a full path.)
    Type Name: SDL
    Description: Binary file
    Command Templates:
    Graphical User Interface:
    Edit: sdt %file1
    View: sdt %file1
    Compare: sdt -fg -grdiff %file1 %file2
    Merge: sdt -fg -grdiff %file1 %file2 -mergeto %outfile
    Command line interface:
    Edit: sdt %file1
    View: sdt %file1
    Compare: sdt -fg -grdiff %file1 %file2
    Merge: sdt -fg -grdiff %file1 %file2 -mergeto %outfile
    Print:
    Compare Attribute: source
  8. Click OK.
  9. Click Update Type.
  10. Define a project file type (*.sdt) by entering the following values:
    Type Name: SDT
    Description: SDT project file
    Super Type: ascii
    Initial Status: working
    Require Task at:<none>
    Verify Comment Existence on Promote / Check In: Off
    Allow Update during Model Install: Off
    Associate with a File in the File System: On
    Can be a Product File: Off
    Icon Color / Fil: ascii.bmp
    File Name Extension: .sdt
  11. Display the Type>Modify File Operations dialog, and enter the following values:
    (If necessary, replace sdt below with the command you use to start SDL Suite. If the sdt script is not in your PATH, you should specify a full path.)
    Type Name: SDT
    Description: SDT project file
    Command Templates:
    Graphical User Interface:
    Edit: sdt %file1
    View: sdt %file1
    Compare: %FAIL
    Merge: %FAIL
    Command line interface:
    Edit: sdt %file1
    View: sdt %file1
    Compare: %FAIL
    Merge: %FAIL
    Print:
    Compare Attribute: source
  12. Click OK.
  13. Click Update Type.
  14. Close the dialog. (File>Close).
    Now you have set up CM Synergy for SDL system diagram and SDT project files.
  15. To manage the other SDL diagram types select Tools>Migrate>Options>Set>Edit to open up the migrate rules file (migrate.rul) in a text editor.
  16. After the entry for your new type which should look something like (might differ depending on platform):
    MAP_FILE_TO_TYPE .*\xfa [Ss][Ss][Yy]$ SDL # Created automatically ...
    MAP_FILE_TO_TYPE .*\xfa [Ss][Dd][Tt]$ SDT # Created automatically ...
    add the following lines:
    MAP_FILE_TO_TYPE .*\xfa [Ss][Bb][Kk]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Pp][Rr]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Pp][Dd]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Uu][Nn]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Oo][Pp]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Ss][Tt]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Bb][Tt]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Ss][Uu]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Pp][Tt]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Vv][Tt]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Ss][Ss][Vv]$ SDL
    MAP_FILE_TO_TYPE .*\xfa [Mm][Ss][Cc]$ SDL
    and save the file. Be very careful with the syntax in this file as it is sensitive to syntax errors. Close the open dialogs.
  17. Use the Migrate facility to load the files into CM Synergy, via Tools>Migrate.
    • Put in the path to your Project directory in the From Directory field, or use the browse button to locate them.
    • In the Project field use the syntax ProjectName-Version, make sure to set the version to a meaningful value.
    • Next click on the menu item Options>Set>Set Object State To>released and click OK.
    • Windows only: To be able to change files you must set the option Make Copies Modifiable in Work Area Properties and then click OK.
    • To ensure that the correct files are being migrated it is suggested that you click Preview. If the results are what you expected go ahead and click Load.
      Now you have a project that is baselined in a released state which you can start to work from.
  18. Each developer will now need to set up their own working environment before using CM Synergy with Telelogic Tau.

Introducing CM Synergy with the SDL suite - Set up your working environment

After the build manager has migrated your SDL system into CM Synergy, each developer will need to set up their own CM Synergy work-area. This should be done using the CM Synergy client to ensure that all the correct options are selected.

  1. Select the correct project baseline for your SDL system as directed by your build manger.
  2. Check out your own personal working version of the project hierarchy using the correct options as directed by your build manager, check out the system file (this will be your own personal version).

Note:

You will normally only have to set up a working environment in this way once for each major release of your software.

  3. Load the CM Synergy menu into the Organizer <org-menus.ini>

Introducing CM Synergy with the SDL suite - Day-to-Day Working with CM Synergy

These steps assume that you will be using the (recommended) CM Synergy Task Based-CM methodology. They may be executed from the Telelogic Tau Organizer.

  1. Select your SDL system and start CM Synergy from the Organizer.
  2. Set your default task (also known as the current task), create one if required.
  3. Check out the file(s) you wish to work on.
  4. Edit and test as required.
  5. Check in your (default) task.

Note:

If you are working as part of a team you may pick up your colleagues' latest work by selecting the top level directory and using the Update command (from time to time you may need to do a full update from the CM Synergy client - ask your build manager).


Using ClearCase Together with an SDL System

This section describes one way of using the SDL suite and ClearCase in an integrated way. For more information about SDL suite/ClearCase Integration, see Readme files in <inst dir>\examples\cm\win32\clearcase\ or <inst dir>/examples/cm/unix/clearcase/.

For a more general description of using a configuration or version control system, please see "How to Manage the Diagrams in a Project" .

Introducing ClearCase with the SDL suite - Checking in Files

When handling of files by ClearCase is to be applied on a system being developed by the SDL suite, the following approach can be used.

  1. Make sure that all files (related to the system) are configured in one directory hierarchy outside ClearCase. See the work area part in Example 50.
    • Note that when working with ClearCase, the original area and work area point to the same directory - the top level directory for the diagram system.
  2. Install the ClearCase menu into the Organizer. Please add clearcase.ini to your org-menus.ini file. The SDL suite will search for the org-menus.ini first in the directory where the SDL suite was started, then in a directory pointed to by the HOME environment variable and finally in the directory in which the SDL suite was installed.If you do not already have a org-menus.ini file, the clearcase.ini can serve as one. Just copy clearcase.ini to either your HOME directory or to where you have the SDL suite installed and rename it to org-menus.ini. For more information on dynamic menus, please see "Defining Menus in the SDL Suite" . (The ClearCase menu that comes with the distribution of the SDL suite is an example and could be tailored by the user.)
  3. Set an appropriate ClearCase view. Copy the system file to the top level directory of the ClearCase file system. You may have to edit it in order to remove the line defining SourceDirectory.
  4. Open the system file to bring up the structural view of the system (the diagrams are marked as invalid in the Organizer - this is OK for now).
  5. The MkDir for Object menu command can be used to create the directory structure in a ClearCase VOB. Select an object in the Organizer and execute the MkDir for Object menu command to create the directory for the selected object in the ClearCase VOB.
  6. Now you can populate the ClearCase directory structure with the diagram files, by copying the files from the directory in step 1. above.
  7. Re-open the system file in the Organizer. All diagrams should now be connected to their files.
  8. Select the System File icon and do the Recursive MkElem menu choice to create all the objects in the ClearCase VOB.
    • Note that no ClearCase element is created for the system file.
  9. Select the System File icon and the Recursive Check In will check in all objects into the ClearCase VOB.
  10. The directories must be checked in separately. Use the command Check In Directory to do that.

The system file for the diagram system can be checked in but it is not suitable for version control since the Organizer wants to update it in situations unrelated to revision changes. The system file should be regarded as one developer's personal view of the system being developed. On the other hand, the top level control unit file should be checked in and is suitable to be put under revision control.

Introducing ClearCase with the SDL suite - Opening a System

The top level control unit file allows to load the system into the Organizer if a user starts from scratch. Say that there is a checked in diagram system in a ClearCase VOB. A developer that wants to start working on that diagram system has to do the following.

  1. Mount the ClearCase VOB containing the diagram system.
  2. Set the appropriate ClearCase view and start the SDL suite in it on a new system.
  3. Load the ClearCase menu into the Organizer $-telelogic/sdt/examples/ClearCase/sdtcc.mnu
  4. Set the Source Directory to the top level directory for the diagram system.
  5. Connect the top level control unit file with the System File icon and run the Recursive Update ClearCase menu command. This loads the system into the Organizer.
  6. Save the system file. (The Organizer will warn that the top level control unit file is read only but this can be disregarded.)


Telelogic Tau 4.4

TTCN Suite
Methodology Guidelines


Introduction

About this Manual

This volume, TTCN Suite Methodology Guidelines, contains a selection of topics that we hope will assist you in understanding how to take advantage of the TTCN language in a TTCN suite environment.

The TTCN language, concepts, and data types are described, including the use of ASN.1. The features of TTCN are introduced using a bottom-up approach with the help of a simple case study. Concurrent TTCN is also addressed.

Documentation Overview

A general description of the Telelogic Tau documentation can be found in "Telelogic Tau Documentation".

Typographic Conventions

The typographic conventions that are used in the Telelogic Tau documentation are described in "Typographic Conventions".

How to Contact Customer Support

Detailed contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".


1 The TTCN Introduction

This chapter is intended to provide an easy - but not necessarily trivial - introduction to TTCN for the beginner.


Introduction

ISO/IEC 9646 (ITU X.290 series) is a five-part standard which defines a framework and methodology for conformance testing of implementations of OSI and ITU protocols. The test notation, the Tree and Tabular Combined Notation (TTCN), is the third part of this standard, i.e. ISO/IEC 9646-3.

The use of TTCN is increasing, and as the notation has now become an ISO International Standard and a ITU Recommendation, we believe there exists a need for a guideline on TTCN.

We do not describe the TTCN in the same order that it is presented in the standard, but instead have used a bottom-up approach. We begin by introducing some basic TTCN features developed round a simple example. Additional features are introduced as required. We have tried to concentrate on aspects that have been introduced in the IS version of the notation, especially concerning the use of ASN.1. We also address the concurrent TTCN.

We hope that readers will find this approach instructive. The guidelines intends to provide:

  • an easy, but not necessarily trivial, introduction for the new-comer to TTCN;
  • an overview of the TTCN for those users of the notation who are familiar with earlier versions and who require a quick up-date on the later features; note, for example, the summary of the extensions.


Background

Among other things, parts 1 and 2 of ISO/IEC 9646 define the basic concepts and abstract methods that are the cornerstone of standardized conformance testing. It is beyond the scope of this guideline to examine these concepts in detail, but a knowledge of the terms and concepts described below is helpful to understanding the TTCN.

Black Box Implementations

One of the basic premises of the conformance standard is that the implementation of the protocol, called an implementation under test (IUT) is a black box.

Any conclusions that we may draw about the conformance of that IUT will be made by observing and controlling the events that occur at the lower and upper service interfaces of the IUT. In ISO/IEC 9646 terms these interactions occur at points of control and observation (PCO) and are expressed in terms of protocol data units (PDUs) embedded in abstract service primitives (ASPs).

An IUT is tested by a test system. In TTCN the different parts of the test system are called test components. A test component created by the main test system is referred to as a Parallel Test Component (PTC).

Lower Tester and Upper Tester

In simple terms, the test components which communicate with the IUT via the PCOs at the lower interface are collectively called the lower tester (LT). The test components which communicate with the IUT via the PCOs at the upper interface are collectively called the upper tester (UT). There must be at least one test component always present in the test system. This is called the master test component (MTC) and it is responsible for coordinating and controlling the test and for setting the final verdict of the test.

Communication between test components in the LT is achieved via coordination points (CP). Similarly, UT test components may communicate with each other via CPs.

Coordination between the LT and the UT is achieved by test coordination procedures (TCP).

Figure 1 : Generalized parallel test architecture (illustrated for a single-layer implementation)

The lower tester is the more complex of the two components as it is also responsible for the control and observation of the protocol data units (PDUs) embedded in the ASPs that it sends and receives. In fact, at any given time the LT, when executing a test case, is implementing a portion of the relevant protocol.

Test Notation

In order to test the IUT we need to specify the sequences of interactions, or test events, that we wish the test system to control and observe. A sequence of such events that specify a complete test purpose is called a test case. A set of test cases for a particular protocol is called a test suite.

The TTCN is a notation that has been developed for the specification of test cases at a level that is abstracted from the architecture of any real test system that these test cases may eventually be run on.

The abstract test cases contain all the information that is necessary to fully specify the test purpose in terms of the protocol that the IUT is supposed to implement. It does not include test system specific information. However, this does not mean to imply that the notation itself is abstract - during the last few years the definition of TTCN has become very precise, with regard to both syntax and operational semantics, and is now close to a programming language.

Forms of TTCN

The main body of ISO/IEC 9646-3 defines the graphical form of the notation (TTCN-GR), where all information is presented using tables. There is also an underlying machine processable format (TTCN-MP) specified in an extended form of BNF (Backus-Naur Form). In this guideline we shall concentrate on the TTCN-GR.

Requirements on TTCN

From Figure 1 it can be seen that, generally speaking, the ISO conformance standard requires that tests are specified in terms of (N-1)-layer ASPs, (N)-layer ASPs and (N)-layer PDUs. In order to fulfil these requirements the minimum functionality that the TTCN should provide is:

  • the ability to specify the ASPs to be sent and/or received by the test system;
  • the ability to specify the PDUs embedded in the ASPs;
  • specification of the order in which ASPs are to be sent and/or received at specific PCOs.

In order to do this the TTCN allows:

  • declaration of ASP and PDU types;
  • declaration of PCOs;
  • specification of actual ASPs and PDUs;
  • specification of instances of behaviour.

We shall examine in detail how these, and other, features are supported in TTCN to make it a powerful notation for specifying abstract test cases.


A Case Study

The Test Case

For the purposes of this guideline we shall invent a simple case study for an imaginary protocol, which we shall call the X-Protocol. The case study is based on the architecture introduced in the previous section. The IUT is an implementation of the X-protocol.

We shall assume that there is an underlying service provider that provides a network service (N), over which we shall run the test. This leads to the following:

  • the LT will be specified in terms of N-SERVICE primitives and X-PDUs,
  • N_DATArequest and CR_PDU;
  • the UT will be specified in terms of X-SERVICE primitives,
  • X_CONNECTrequest;

Description of the Case Study

Our examples will introduce the TTCN features necessary to specify the simple scenario described below:

  • The MTC initiates the test by CREATING the necessary PTCs. One lower PTC and one upper PTC for each connection.
  • The lower PTC then establishes an X-connection with the upper PTC via the IUT. For the sake of simplicity we will assume that an (N)-connection has already been set up, and that the X-protocol does not allow an X_CONNECTrequest to be refused (the example has been created to illustrate TTCN features, rather than to specify a sensible protocol).
  • The test then continues with the data phase, where the lower PTC transmits a data packet which shall be returned by the upper PTC via the IUT. The packet shall be returned within a given period of time. This process is repeated a given number of times.
  • After the data transfer the lower PTC disconnects and sends its preliminary result to the MTC which then computes the final verdict and the test terminates

Purpose of the Test Case

The case study has two test purposes, these can be stated as:

  1. The IUT shall accept and return a given number of data packets within the time limitations of the protocol over a single X-connection.
  2. The IUT shall accept and return a given number of data packets within the time limitations of the protocol over two simultaneous X-connections.

Each test purpose will be expressed as a separate test case.

Case Study Road-Map

We shall create a TTCN complete mini-test suite that contains all the TTCN necessary to specify the above test cases. The following table (this is not a TTCN table!) shows the main sections of this example in the order in which they would appear in a real test suite. The complete study can be found in "The Complete Case Study" . The right-hand column of the table tells you where these sections are described in this guideline:

Section of test suite | Described in this guideline
Overview | "Suite Overview Part"
Configurations | "The Test Configuration"
Test Suite Parameterization | "Test Case Selection"
Global Type Definitions | "TTCN Types and Values"
Global Declarations | "Constants and Variables"
PCO and CP declarations | "PCOs and CPs"
Timer Declarations | "Timer Statements"
ASP, PDU and CM Definitions | "Defining ASP, PDU and CM Types"
ASP, PDU and CM Values | "Specifying ASP, PDU and CM Values"
Behaviour Descriptions | "Dynamic Behaviour Descriptions"


The Test Configuration

Let us start by specifying the test component configurations needed in the test suite. The conformance standard defines various abstract test methods. For the purposes of this guideline we shall assume that the IUT is a single-layer implementation and that we are testing with the distributed method. Also, we are testing in a multi-party context because our second test purpose requires more than one connection.

In this case, the architecture of Figure 1 says that we need:

  • one MTC;
  • two lower PTCs
  • two upper PTCs;
  • one (N-1) service provider;
  • four PCOs (two lower L1 and L2 and two upper and U1 and U2);
  • two coordination points (CP1 and CP2) between the lower PTCs and the MTC.

This is illustrated in the following figure:

Figure 2 : Illustration of the multi-party distributed test method

In concurrent TTCN this architecture is specified using the following tables:

  • Test Component Declarations
  • Test Component Configuration Declaration (one table per definition)

Case study 1: This table lists all the test components that may be used in the test suite. They can be thought of as building-blocks that can be used to construct different configurations. A test component may have the role of main test component (MTC), or parallel test component (PTC).

Figure 3 : Test Component Declarations

Case study 2: This table shows the configuration for the single-connection test case. In any one configuration there should never be more than one MTC.

Figure 4 : Test Component Configuration Declaration (SINGLE_PARTY)

Case study 3: This table shows the configuration for the multi-connection test case.

Figure 5 : Test Component Configuration (MULTI_PARTY)


Specification of Test System Behaviour

Before we continue with the declaration of the test case let us now look at how TTCN describes the behaviour of the various test components. Many standardized service definitions and protocol specifications use state diagrams and/or state tables to describe the behaviour of the service or protocol.

Test cases are derived from these specifications. However, because conformance testing is concerned with observing and controlling sequences of interactions at service interfaces it is more appropriate that we specify test system behaviour as a tree which has branches for all the possible sequences of interactions that may occur between any two given protocol states.

Behaviour Trees

In TTCN a tree of interactions is called a behaviour tree. The tree structure is represented by using increasing levels of indentation to indicate progression into the tree with respect to time.

Figure 6 : A tree is represented in TTCN using indentation

Note that an absolute level of indentation does not necessarily mean that nodes are siblings. For example, although the nodes F and G are numerically at the same level of indentation (i.e. 3) as I and J, the nodes F and G are in one branch of the tree and the nodes I and J are in another

Behaviour Lines

A node in a behaviour tree is called a behaviour line. A behaviour line consists of the following components:

  • line number;
  • label;
  • statement line;
  • constraint reference;
  • verdict;
  • behaviour line comment.

Exactly which components of the behaviour line are used at a specific time varies. For example, line numbers and comments are always optional and constraint references and verdicts shall only be used when required.

TTCN Behaviour Description

Behaviour lines are specified in dynamic behaviour tables. There are three kinds of behaviour tables, each consisting of a header and a body.

  • Test Case Dynamic Behaviour;
  • Test Step Dynamic Behaviour;
  • Default Dynamic Behaviour.

The visual difference between these three tables is in the header. The format of the body is the same for all three. However, there is a significant difference, which will be explained later, in how these different tables are used.

Figure 7 : The body of a dynamic behavior table

The table body shows the columns for the line numbers, labels, statement lines, constraint references, verdicts and comments. The light shading indicates the extent of a single behaviour line. The dark shading indicates the extent of a single statement line.

Statement Lines

A sequence of one or more statements, together with the indentation information, in a single behaviour line is called a statement line. Statement lines appear in the behaviour description column of dynamic behaviour tables.

Statements

The behaviour of the test system, such as sending and receiving ASPs, is expressed using TTCN statements. Statements can be split into three distinct types:

  • events;
  • actions;
  • qualifiers.

Events

Some statements will be successful, i.e. match, depending on the occurrence of certain events. There are two types of event: input events and timer events. An input event is the arrival of an ASP at a named PCO or a message at a named CP. A timer event is the expiry of a protocol timer. The TTCN statements that are events are:

  • RECEIVE
  • OTHERWISE
  • TIMEOUT

Actions

Some statements will always be successful, i.e. execute. We shall call such statements actions, although this term is not used in ISO/IEC 9646-3. These are actions that are executed by the test system, and TTCN assumes that they can always be executed successfully. The TTCN statements that are actions are:

  • SEND
  • IMPLICIT_SEND
  • ASSIGNMENT_LIST
  • TIMER_OPERATION
  • GOTO

Qualifiers

Statement lines may include a qualifier statement, i.e. a boolean expression. We call such statement lines qualified statement lines. No event can match, nor can any action be executed unless the qualifier included in the statement line evaluates to TRUE. An unqualified statement line is one that does not include a qualifier.

A TTCN qualifier is simply a:

  • BOOLEAN_EXPRESSION

Combinations of Events, Actions and Qualifiers

The actual combinations of events, actions and qualifiers that are allowed are defined by the TTCN-MP. The different combinations will be described at the relevant points in this guideline.

Execution and Matching

We shall now consider how a behaviour tree is traversed and executed.

Alternatives

A set of statement lines at the same level of indentation, and in the same branch of the tree are called a set of alternative statement lines, or alternatives for short. Thus, in the Figure 6 (A,B), (C, D, E), (F, G), (I, J) and (H) are all different sets of alternatives.

Because the ordering within any given set of alternatives is significant it is important that all events and qualified statements appear before any unqualified actions.

Execution of the Behaviour Tree

Execution starts at the root of the tree. That is, the first set of alternatives is repeatedly looped with each alternative being evaluated in the order of its appearance in the set. This looping continues until a statement line is successfully executed or matched. If a statement line is successful then the next set of alternatives (if any) is entered, and the process is repeated.

Execution stops when a leaf of the tree is reached. A final verdict will also halt execution, see "Verdicts" .

In the example shown in Figure 7 execution starts by looping through the first set of alternatives (A, B). If B is successful then execution terminates. If A is successful then the next set of alternatives (C, D, E) is entered. Let's assume that the statement line E is successful: then the next set of alternatives is (I, J). If either I or J is successful then execution terminates. Note that if no statement line in any set of alternatives is ever successful then execution gets `stuck' as we repeatedly loop through those alternatives.

Figure 8 : Cycle of execution of a test case behavior tree


TTCN Types and Values

We shall now discuss TTCN data types and their values. These are used to specify the data types, including ASPs and PDUs that are used in the behaviour descriptions.

TTCN has been tailored to interface with the Abstract Syntax Notation One (ASN.1, ISO/IEC 8824:1990). There is no clear boundary between TTCN types and ASN.1 types; the distinction is an artificial one. It is there, however, to allow test suite specifiers to build the types, ASPs, PDUs, etc. they need without using ASN.1 if they do not wish to do so. This is relevant, for example, in lower-layer protocols, where ASN.1 is not normally used in the protocol specifications.

TTCN contains a number of predefined types. It also allows the user to construct his own types from the predefined types. This may be done using the following tables:

  • Simple Type Definitions
  • Structured Type Definition (one table per definition)

Predefined Types

TTCN supports a rich set of predefined (built-in) types. The predefined TTCN types, with the exception of HEXSTRING, are a subset of the ASN.1 built-in types and are compatible with their ASN.1 counterparts. The HEXSTRING type does not exist in ASN.1. The remaining ASN.1 built-in types may also be used without being explicitly defined.

Figure 9 : List of predefined types that may be used in TTCN Test Suites

Value Denotation

The value denotation for the predefined types is the same in both TTCN and ASN.1, see "ASN.1 Types and Values" .

Simple User Defined Types

The TTCN user can construct other types based on the simple predefined types, without the need to resort to ASN.1 syntax. These subtypes are defined in the Simple Type Definitions table, and they may be used anywhere in the test suite. They are constructed by restricting the predefined types (and possibly previously declared subtypes) by specifying:

  • value lists,
    which are lists whose elements may consist of literal values only;
  • ranges,
    which may be used to restrict INTEGER types only;
  • length restrictions,
    which may be used to restrict string types only.

Note:

The TTCN syntax does allow the use of ASN.1 in the Simple Type Definitions table if wished. We recommend, however, that the special tables for ASN.1 types be used instead.

Figure 10 : Some miscellaneous simple type definitions

Case study 4: Definition of a user type for test case results.

Figure 11 : Simple Type Definitions

Structured Types

TTCN has tables for the declaration of structured (i.e., complex) types. These types, like the predefined types and the simple types may be used anywhere (that is why they are defined early on in the test suite). However, their main use is to substructure ASPs and PDUs and we shall therefore discuss them in "Specifying ASP, PDU and CM Values" .


ASN.1 Types and Values

ASN.1 is used to describe data types. It is often used as a means for defining the PDU structures of many OSI protocols. In the following we shall give an overview of the ASN.1 type and value notation.

Type References, Value References and Identifiers

A type reference is the "name" of an ASN.1 type constructed by the ASN.1 user. The ASN.1 standard requires that the initial character of a type reference is always an upper case letter.

A value reference is the "name" of an ASN.1 value constructed by the ASN.1 user. The ASN.1 standard requires that the initial character of a value reference is always a lower case letter.

Note:

Many test suite specifiers ignore this convention, indeed, so does ISO/IEC 9646-3!

As you will see shortly, type references in SETs and SEQUENCEs etc. may be "labeled". Such labels are called identifiers. The ASN.1 standard requires that the initial character of an identifier is always a lower case letter. Value references and identifiers are distinguished by context.

Identifiers and Underscore

The ASN.1 standard allows the character dash (-) in identifiers. TTCN does not (otherwise there would be ambiguity in arithmetic expressions between dash and minus). TTCN uses underscore (_) instead. If ASN.1 definitions are imported, copied, borrowed etc. from external specifications (e.g. the PDU definitions for a particular protocol) then all occurrences of dash in identifiers should be changed to underscore.

ASN.1 Simple Types

BOOLEAN

BOOLEAN is a type denoted by two distinguished values: TRUE and FALSE. The TTCN has operators for values of any type whose base type is BOOLEAN.

INTEGER

INTEGER is a type denoted by the distinguished values which are the positive and negative whole numbers, including zero. TTCN has operators for any values whose base type is INTEGER.

REAL

REAL is a data type specified as a triple of three INTEGERS consisting of:

  • mantissa*baseexponent

The base is limited to 2 or 10.

  • pi REAL ::= { 314159, 10, -5 }

TTCN does not have any operators for values of REAL types. If REAL arithmetic is absolutely necessary this can be achieved by user defined operations.

BIT STRING

BIT STRING is a type whose distinguished values are the ordered sequences of zero, one, or more BITs. Individual BITs in the BIT STRING may be named.

  • ABitString ::= BIT STRING { bit1 (0), bit2 (1), bit3 (2), bit4 (3) }
  • a-value ABitString ::= `1001'B

OCTET STRING

OCTET STRING is a type whose distinguished values are the ordered sequences of zero or an even number of HEX digits, each digit corresponding to an ordered sequence of four bits. Individual OCTETSs in the OCTET STRING may be named.

  • AnOctetString ::= OCTET STRING { octet1 (0), octet2(1) }
  • a-value AnOctetString ::= `0F'H

Note:

There is an incompatibility between TTCN and ASN.1 over the value denotation of OCTET STRING. TTCN terminates OCTET STRING values with the keyword `O' rather than the keyword `H'.

CharacterString

A variety of character sets are supported. For the purposes of this guideline we shall restrict ourselves to using the ITU character set IA5String.

ENUMERATED

ENUMERATED types represent the complete set of values (domain) that an instance of a data type may take.

  • transport-classes ENUMERATED ::= { class1 (0), class2 (1), class3 (2), class4 (3), class5 (4) }

No TTCN operators can be applied to values of ENUMERATED type.

OBJECT IDENTIFIER

OBJECT IDENTIFIER denotes a named object as a sequence of non-negative INTEGERs. The naming hierarchy of specific objects is decided by the relevant authority (e.g. ISO or ITU). An OBJECT IDENTIFIER specifies a unique path in this hierarchy, i.e. all objects are uniquely named.

  • ttcn-standard OBJECT IDENTIFIER ::= { iso (1) standard (0) 9646 3 }

The OBJECT IDENTIFIER for ISO/IEC 9646-3 would be 1.0.9646.3

Objects that TTCN needs to reference in this manner might be ASN.1 modules (PDUs etc.) and PICS, PXIT documents.

OBJECT DESCRIPTOR

OBJECT DESCRIPTOR denotes a text string that references an object. The difference between an OBJECT IDENTIFIER and an OBJECT DESCRIPTOR is that the former is unique, while the latter may not be.

  • ttcn-standard OBJECT DESCRIPTOR ::= "The TTCN: ISO/IEC 9646, part 3"

ASN.1 Constructors

Complex data types can be built from the simple predefined types (excepting HEXSTRING) using ASN.1 constructors. This process is recursive, i.e. constructors can use other constructors (including themselves) to an arbitrary level of nesting. The constructor types are:

  • SEQUENCE
  • SEQUENCE OF
  • SET
  • SET OF
  • CHOICE

SEQUENCE

SEQUENCE is a data type denoting an ordered set of elements. This set may be empty. The elements of this set may be of any ASN.1 type and may be of different types. The elements in the set may be named.

  • ASequence ::= SEQUENCE {field1 INTEGER, field2 BOOLEAN}
  • a-value ASequence ::= { field1 123, field2 TRUE }

SEQUENCE OF

SEQUENCE OF is a data type denoting an ordered set of elements. This set may be empty. The elements of this set may be of any ASN.1 type but they shall all be of the same type. The elements in the set may be named.

  • ASequenceOf ::= SEQUENCE OF INTEGER { field1, field2 }

SET

SET is a data type denoting an unordered set of elements. This set may be empty. The elements of this set may be of any ASN.1 type and may be of different types. The elements in the set may be named.

  • ASet ::= SET { field1 INTEGER, field2 BOOLEAN }

SET OF

SET OF is a data type denoting an unordered set of elements. This set may be empty. The elements of this set may be of any ASN.1 type but shall all be of the same type. The elements in the set may be named.

  • ASetOf ::= SET OF INTEGER { field1, field2 }

At first glance SEQUENCE and SET may appear the same. The difference is that a SEQUENCE is ordered, a SET is not. For instance, in the previous examples when the SET is eventually encoded it can be transmitted by sending field2 before field1, if wished. In the case of SEQUENCE field1 must always precede field2. This has implications when testing, which will be discussed later.

The same applies to SEQUENCE OF and SET OF.

In short, SEQUENCE and SEQUENCE OF rely on ordering to avoid ambiguity. SET and SET OF rely on the data type and/or tag of each element to uniquely distinguish each element.

OPTIONAL

The keyword OPTIONAL in a SEQUENCE or SET indicates that the presence of that element in the SEQUENCE is not mandatory and may be included or omitted at will.

  • ASequence ::= SEQUENCE { field1 INTEGER OPTIONAL, field2 BOOLEAN }
  • a-value1 ASequence ::= { 123, TRUE }
  • a-value2 ASequence ::= { TRUE }

The same applies for SEQUENCE OF, SET and SET OF.

DEFAULT

In certain cases it is useful to be able to specify a DEFAULT value to be used (in encoding) if the element is not present in the data type.

  • ASequence ::= SEQUENCE { field1 INTEGER DEFAULT 0, field2 BOOLEAN }

CHOICE

A CHOICE type is a data type that defines the union of one or more data types. The alternatives in this union may be named. Any given instance, i.e. value, of a CHOICE shall be exactly one of the alternatives of the CHOICE. This has implications for testing which will be discussed later.

  • AllPDUs ::= CHOICE {pdu1 SEQUENCE { ..... }, pdu2 SEQUENCE { ..... }, pdu3 SEQUENCE { ..... } }
  • a_pdu AllPDUs ::= pdu2

TAGGED TYPES

Tags are used to distinguish between different occurrences of the same type. Tags are denoted by a non-negative INTEGER enclosed in square brackets. Tags are included in the encoding of the data type. There are four classes of tags:

  • UNIVERSAL
    Universal tags are globally unique and are only defined in the ASN.1 standard. These tags have a meaning world-wide.
  • PRIVATE
    Private-use tags are unique within a given enterprise, and are defined by agreement of the parties involved in the enterprise. These tags have no meaning outside the scope of the enterprise.
  • APPLICATION
    Application-wide tags are unique within a specific ASN.1 module. These tags have no meaning outside of the ASN.1 module that they are used in.
  • CONTEXT
    Context-specific tags are unique within a specific constructor type. For example, elements in a particular SET may be tagged to uniquely distinguish them. These tags have no meaning outside of the ASN.1 type that they are used in.

IMPLICIT

The keyword IMPLICIT may be used together with the definition of the tagged type. IMPLICIT is an instruction to an ASN.1 encoder that only the tag need be encoded and thus transmitted over the network. This is done to reduce the amount of transmitted data. IMPLICIT may only be used where no loss of essential information would occur. For example, it should not be used with CHOICE.

EXTERNAL

Use of the EXTERNAL type is not allowed in TTCN.


PCOs and CPs

The TTCN supports an asynchronous communication model. Communication between the test components and the IUT or service provider is achieved via points of control and observation (PCOs). Communication between the test components themselves is achieved via coordination points (CPs).

The Communication Model

We shall use the same queue model to describe both PCOs and CPs:

  • each PCO/CP has two unbounded first-in-first-out (FIFO) queues;
  • one queue for SEND, and
  • one queue for RECEIVE;
  • exactly two parties must be connected to a single PCO or CP;
  • the SEND queue for one party is the RECEIVE queue for the other, and vice versa.

Sending an ASP

The SEND action appends an ASP to the relevant PCO send queue. Even in the case of the IUT and the underlying service provider the send queue is considered to be unbounded, and that the IUT or service provider will always accept the ASPs sent by an LT or UT.

Receiving an ASP

A successful RECEIVE pops the ASP from the top of the RECEIVE queue. We shall see later that RECEIVE involves two steps:

  • receipt of the ASP;
  • checking its contents.

Figure 12 : Illustration of the PCO and CP queue model

Declaring PCO Types

All PCO types that are used in the test suite must be declared in the

  • PCO Type Declarations
    Each PCO Type requires the following information:
  • the name the PCO Type
  • the role of the PCO, which is either of the keywords LT or UT;

Case study 5: Declaration of the PCO Types N_SAP and X_SAP.

Figure 13 : PCO Type Declarations

Declaring PCOs

All PCOs that are used in the test suite must be declared in the

  • PCO Declarations
    Each PCO requires the following information:
  • the name the PCO
  • the type of the PCO;
  • the role of the PCO, which is either of the keywords LT or UT;

Case study 5: Declaration of the PCOs L and U.

Figure 14 : PCO Declarations

Using PCOs and CPs

If the test suite only uses one PCO it is allowed to omit the PCO name in the TTCN statements that use them. If there is more than one PCO used (e.g. as in the distributed method) then the PCO and CP names (if any) must appear in the TTCN statements that use PCOs or CPs.

PCO and CP Snapshots

We have already described how a behaviour tree is executed by repeatedly looping through a set of alternatives until a statement line is successful. At the beginning of each loop a snapshot is taken of each input queue in every PCO or CP. Statements are evaluated on the basis of the state of the snapshots, not on the actual state of the PCO or CP queues. This has the effect of freezing time while a set of alternatives is being processed i.e. "prevents" the occurrence of an event in between snapshots. This means that the arrival of an ASP, PDU or CM during processing of a set of alternatives is not registered until the snapshots are updated.

Declaring CPs

All CPs that are used in the test suite must be declared. This is done in the CP Declarations table. Each PCO requires the following information:

  • the name of the CP;
  • the role of the CP,
    i.e. the two test components which communicate with each other over the CP.

Case study 6: Declaration of the coordination points called CP1 and CP2.

Figure 15 : Test Component Declarations


The SEND Statement

The transmission of ASPs and/or PDUs to the IUT or messages to other test system components is one of the fundamental actions in a typical TTCN behaviour tree.

Sending an ASP

The SEND statement allows the test suite specifier to express that an ASP of a certain type is to be transmitted over a named PCO. The SEND statement is denoted by:

  • PCO_Identifier ! ASP_Identifier

The SEND statement may be qualified and it may be followed by an ASSIGNMENT_LIST and/or TIMER_OPERATION. The order in which these statements may appear in the statement line is fixed, as shown below; the square brackets indicate that the presence of the statement in the statement line is optional:

  • SEND3 [QUALIFIER]1 [ASSIGNMENT_LIST]2 [TIMER_OPERATION]4

Executing a SEND Statement

The numbers on the line above indicate the order, with respect to time, in which the statements should be executed: the QUALIFIER (if any) is evaluated first. If it evaluates to FALSE processing stops and the statement line is not successful. If it evaluates to TRUE then the ASSIGNMENT_LIST (if any) is executed. Only then can the SEND statement be executed. Finally, the TIMER_OPERATION (if any) is executed.

  • L! N_DATArequest
    means: send the Network data request service primitive to the PCO named L;
  • L! N_DATArequest [B=1]
    means: if B is equal to 1 then execute the SEND;
  • L! N_DATArequest [B=1] (X:=3)
    means: if B is equal to 1 then assign the value 3 to X and then perform the SEND.

Sending a PDU

Normally PDUs are embedded in ASPs, and will not be explicitly named in the SEND statement. However, not all protocols have a service definition (e.g. X.25) and TTCN therefore permits the SEND statement to be used explicitly with PDUs instead of ASPs. The action of sending a PDU is denoted by:

  • PCO_Identifier ! PDU_Identifier

Other statements that may be associated with sending a message, and the order in which the statement line is processed, is exactly the same as for an ordinary SEND statement line.

Sending a Coordination Message

The SEND statement is also used to send messages to coordination points. The action of sending a CM is denoted by:

  • CP_Identifier ! CM_Identifier

Other statements that may be associated with sending a message, and the order in which the statement line is processed, is exactly the same as for an ordinary SEND statement line.


The RECEIVE Statement

The receipt of ASPs and/or PDUs from the IUT or messages from other test system components is one of the fundamental events in a typical TTCN behaviour tree.

Receiving an ASP

The RECEIVE statement allows the test suite specifier to express that an ASP of a certain type is to be received over a named PCO. The RECEIVE statement is denoted by:

  • PCO_Identifier ? ASP_Identifier

The RECEIVE statement may be qualified and it may be followed by an ASSIGNMENT_LIST and/or TIMER_OPERATION. The order in which these statements appear in the statement line is fixed, as shown below; the square brackets indicate that the presence of the statement in the statement line is optional:

  • RECEIVE1 [QUALIFIER]2 (ASSIGNMENT_LIST)3 [TIMER_OPERATION]4

Executing a RECEIVE Statement

The numbers on the line above indicate the order, with respect to time, in which the statements should be executed: the RECEIVE is evaluated first, and succeeds if an ASP of the correct type is at the head of the PCO queue. If the RECEIVE fails then processing stops and the statement line is not successful. If the RECEIVE is successful then the QUALIFIER (if any) is evaluated. If the QUALIFIER evaluates to FALSE processing stops and the statement line is not successful. If it evaluates to TRUE then the ASSIGNMENT_LIST (if any) is executed. Finally, the TIMER_OPERATION (if any) is executed. For example:

  • L? N_DATArequest
    means: the statement line matches if a Network data request primitive is at the head of the PCO named L;
  • L? N_DATArequest [B=1]
    means: the statement line matches if the correct ASP is at the head of the PCO L and if B is equal to 1;
  • L? N_DATArequest [B=1] (X:=3)
    means: the statement line matches if the correct ASP is at the head of the PCO L and if B is equal to 1. Only when the match has occurred can the ASSIGNMENT_LIST be executed.

Receiving a PDU

Normally PDUs are embedded in ASPs, and will not be explicitly named in the RECEIVE statement. However, not all protocols have a service definition (e.g. X.25) and TTCN therefore permits the RECEIVE statement to be used explicitly with PDUs instead of ASPs. Receipt of a PDU is denoted by:

  • PCO_Identifier ? PDU_Identifier

Other statements that may be associated with sending a message, and the order in which the statement line is processed, is exactly the same as for an ordinary RECEIVE statement line.

Receiving a Coordination Message

The RECEIVE statement is also used to accept messages from coordination points. Receipt of a CM is denoted by:

  • CP_Identifier ? CM_Identifier

Other statements that may be associated with receiving a message, and the order in which the statement line is processed, is exactly the same as for an ordinary RECEIVE statement line.


The OTHERWISE Statement

The OTHERWISE statement allows the test suite specifier to express that an ASP or PDU of any type is to be received over a named PCO. Note that this includes objects that may not normally be recognized as proper ASPs or PDUs, due to the fact that the IUT may not be working correctly, i.e. OTHERWISE is a catch-all. The OTHERWISE statement is denoted by:

  • PCO_Identifier ? OTHERWISE

OTHERWISE should not be used at coordination points.

Note:

Always have an OTHERWISE as an alternative to a RECEIVE event.


Defining ASP, PDU and CM Types

ASPs are derived from the relevant standardized service definitions. When using the distributed method, for example, ASP definitions are needed for both the (N) and the (N-1) service. There should be one ASP definition for each ASP used in the test suite.

PDUs are derived from the relevant protocol specifications. There should be one PDU type definition for each PDU used in the test suite. If, for the purposes of testing, it is required to use non-standard PDUs then these too should also be defined in the test suite.

Coordination Messages are also defined by the test suite specifier.

TTCN has tables that allow the definition of ASPs, PDUs and CMs using either the simple TTCN tabular format or ASN.1.

Complex TTCN Types

TTCN has tables for the declaration of the following complex types:

  • ASP Type Definitions;
  • PDU Type Definitions;
  • Structured Type Definitions;
  • CM Type Definitions.

Using these complex types we can define arbitrarily structured ASPs and PDUs (structured types are substructures of ASPs and PDUs). In essence there is no real difference in TTCN between the composition of the body of an ASP, PDU or structured type. Note the following:

  • an ASP has parameters,
    where the type of each parameter may be of any type except ASP type;
  • a PDU has fields,
    where the type of each field may be of any type except ASP type;
  • a structured type has elements,
    where the type of each element may be of any type except ASP type.

Chaining

Normally, the ASP parameters, PDU fields and structure elements will be predefined or simple types (note that this includes the use of ASN.1, if wished). However, as noted above, the parameter, field or element types may also be PDUs or structures to allow the chaining of these types to build complex definitions.

Figure 16 : Structuring ASPs and PDUs

Complex ASN.1 Types

In ASN.1, constructors such as SEQUENCE and SET are used to build arbitrarily complex types. ASN.1 definitions may be used in the following tables:

  • ASN.1 Type Definitions;
  • ASN.1 ASP Type Definitions;
  • ASN.1 PDU Type Definitions;
  • ASN.1 CM Type Definitions.

It is always possible to express the TTCN tabular format in ASN.1, but not vice versa. The two formats can be used in combination, if wished. A common example is to use a tabular ASP to carry a structured PDU defined in ASN.1.

Figure 17 : Structuring ASPs and PDUs using ASN.1

Local Type Definitions

There will always be at least one type definition in an ASN.1 table. This is the main definition, and it is named in the table header. However, these ASN.1 tables may also include any number of local definitions which are only available to the type definitions defined within the table itself, i.e. the main definition and other local definitions (if any).

Note that local definitions begin with typereference ::=. This is not the case for the main definition as the type identifier already appears in the header.

Type Definitions by Reference

In order to save repeating PDU and other type definitions that are specified in another standard TTCN allows the following types to be declared by reference rather than explicitly:

  • ASN.1 ASP Definitions;
  • ASN.1 PDU Definitions;
  • ASN.1 Type Definitions.

A single table is used for all references to a particular type. The reference tables are:

  • ASN.1 ASP Definitions by Reference;
  • ASN.1 PDU Definitions by Reference;
  • ASN.1 Type Definitions by Reference.

Note that because the entries in the Type Reference column and the Module Identifier column follow ASN.1 syntax they may contain the dash character. Note also that the module identifier may be followed by an optional object identifier.

Figure 18 : Example of PDU definitions by reference

Defining ASPs

OSI service primitives are often defined in a standard as a tuple, i.e. the primitive name followed by a list of parameters. Each parameter is defined using natural language descriptions and may represent service control information or service user data. Some parameters are mandatory (i.e. must always be present) while others are optional and, under certain circumstances, may be omitted.

In TTCN service primitives are called Abstract Service Primitives (ASPs) and are declared in ASP Type Definition tables.

Case study 7: A service provider ASP type definition.

Figure 19 : ASP Type Definition (N_DATArequest)

The PDU Metatype

The above example uses the PDU metatype. This indicates that any type of PDU, and not just a particular type of PDU may be embedded in this ASP.

Defining PDUs

In most OSI standards PDUs are usually defined using either:

  • a simple tabular-like format, together with informal text; or
  • ASN.1 together with informal text.

In the first case the specification may be rather loose, and typing of PDU fields and substructuring of the PDUs is not always obvious. The test suite specifier must transpose these definitions to the more powerful and precise formats available in TTCN.

For example, a standard may describe a particular field as comprising 8-bits, implying that it shall be encoded as a BITSTRING. If none of the bits in this BITSTRING need to be referenced individually, it may be adequate for testing purposes (and easier to understand) if this field is defined as an OCTETSTRING.

In the case of ASN.1 the types and structure of PDUs and their fields is usually complete and well-defined, and may be taken directly from the protocol standard, either by copying them or by reference.

Case study 8: Type definition of an X_PDU using the TTCN format.

Figure 20 : PDU Type Definition (CR_PDU)

Figure 21 : Type definition of the same X_PDU using ASN.1

Substructuring ASPs and PDUs

TTCN structured types (which we will sometimes refer to simply as structures) are only used to substructure ASPs, PDUs, CMs and other structured types.

If ASN.1 is used then the ASN.1 type definition table may be used not only to substructure ASPs, PDUs etc. but also to define types general to the entire test suite.

Case study 9: Type definition of a PDU substructure using the TTCN format.

Figure 22 : Structure Type Definition (VARIABLE_PART)

Figure 23 : Type definition of the same substructure using ASN.1

Defining Coordination Message Types

Coordination messages are special to each test suite and are created by the test suite specifier. Either the tabular format or ASN.1 may be used.

Case study 10: Type definition of a coordination message.

Figure 24 : CM Type Definition (PTC_RESULT)

Figure 25 : Type definition of the same coordination message using ASN.1


Using ASPs and PDUs in Behaviour Trees

In this section we will expand our example a bit further and show how the sequencing of ASPs w.r.t. time is expressed in TTCN behaviour descriptions.

Figure 26 : An N_DATArequest, carrying a CR_PDU, is sent over the network

It results in the IUT generating an X_CONNECTindication, which is responded to by the UT tester sending an X_CONNECTresponse. This results in an N_DATAindication, carrying a CC_PDU, appearing at the LT.

Figure 27 : The above scenario can be expressed as two TTCN behavior trees

Note the introduction of the OTHERWISE statement.


TTCN Expressions

All values in TTCN are quite simply expressions. Note that the TTCN syntax allows the operands of expressions to be:

  • literal values;
  • constant or variable identifiers;
  • formal parameter identifiers;
  • ASP parameters;
  • PDU or CM fields;
  • structure elements;
  • predefined and user defined operations;
  • expressions, i.e. the syntax is recursive.

Exactly which variables etc. may be used in an expression depends on the context in which the expression is used. This aspect will be discussed in the relevant sections.

TTCN Operators

TTCN supports the following kinds of operators for use in expressions:

  • arithmetic;
  • relational
  • logical.

Arithmetic Operators

TTCN supports the following arithmetic operators for use only with operands of INTEGER type or derivations of INTEGER type:

  • +, -, *, /, MOD

Expressions that use these operators are called arithmetic expressions.

  • 3*(Z+9)

Equality Operator

The equal to and not equal to operators may be used on values of any type:

  • =, <>

Expressions that use these operators must always evaluate to a BOOLEAN value:

  • B_string = `01'B
  • H_string <> `FF'H

Other Relational Operators

TTCN supports the following relational operators for use only with operands of INTEGER type or derivations of INTEGER type:

  • <, >, >=, <=

Expressions that use these operators must always evaluate to a BOOLEAN value:

  • X <= 3*Y

Boolean Operators

TTCN supports the following logical operators for use only with operands of BOOLEAN type or derivations of BOOLEAN type:

  • AND, OR, NOT

Expressions that use these operators must always evaluate to a BOOLEAN value:

  • A AND NOT (B OR C)

Qualifiers

A qualifier is an expression enclosed in square brackets:

  • [ expression ]

The expression must evaluate to a BOOLEAN value.

  • [ X < 6 AND H_string <> `FF'H ]

Assignment Lists

A TTCN statement may be an ASSIGNMENT_LIST, i.e. a list of assignments, separated by commas and enclosed in parentheses:

  • ( assignment1, . . . ., assignmentn )

The left-hand side (l.h.s.) of an assignment must resolve to a variable. In the context of SEND and RECEIVE statements the l.h.s. of an assignment may resolve to an ASP parameter reference, a PDU field reference or a structure element reference. The right-hand side (r.h.s.) of the assignment is an expression, which must evaluate to a value of a type compatible with the type of the l.h.s.

  • (X := 3, A := "a string", Y := 3*(Z+9), H := `FF'H)

Note:

By type compatibility we quite simply mean that a value, a, of type A is type compatible with type B if a is a legal value of both type A and type B.

TTCN Operations

TTCN supports both a number of predefined operations and a mechanism that allows the definition of user operations. Operations may be used as operands in expressions.

Predefined Operations

TTCN now supports a number of predefined operations. More are expected to be added by the work on TTCN extensions. Currently these operations are:

  • HEX_TO_INT (data_object_reference),
    converts a HEXSTRING value to an INTEGER value;
  • BIT_TO_INT (data_object_reference),
    converts a BITSTRING value to an INTEGER value;
  • INT_TO_HEX (data_object_reference),
    converts an INTEGER value to an HEXSTRING value;
  • INT_TO_BIT (data_object_reference),
    converts an INTEGER value to an BITSTRING value;
  • LENGTH_OF (data_object_reference),
    returns the length of the data object reference, which must be of string type, in units of that string type, e.g. number of bits, number of characters etc.;
  • NUMBER_OF_ELEMENTS (data_object_reference),
    returns the number of elements in the data object reference (e.g. PDU field) which must be of type SEQUENCE OF or SET OF;
  • IS_PRESENT (data_object_reference),
    returns TRUE if an OPTIONAL or DEFAULT data object reference (e.g. PDU field) is present in a received PDU; otherwise returns FALSE;
  • IS_CHOSEN (data_object_reference),
    this operation is used to indicate that we wish to accept a particular element from a CHOICE. It returns TRUE if the data object reference (e.g. PDU field), which must be of CHOICE type, matches the received value.

User Defined Operations

TTCN allows the informal definition of user define operations. A possible approach is to use a programing language to `describe' the operation.

Note:

The TTCN amendment (PDAM 2) is currently exploring ways of how user operation descriptions can be made more `formal'.

Like the predefined operations user defined operations may be used in both behaviour trees and as `values' in constraints.

Each user defined operations is declared in a Test Suite Operations table.

Case study 11: Definition of a user defined operation.

Figure 28 : Test Suite Operation Definition

If an operator does not have any arguments it should be called with an empty actual parameter list, e.g. DATE ( ).


Specifying ASP, PDU and CM Values

The previous section showed how to define structured ASP, PDU and CM types. However, when a tester SENDs or RECEIVES an ASP, PDU or CM it is necessary to specify in detail actual values of these complex types.

Values, or instances, of complete ASPs, PDUs and CMs are called constraints. For each ASP, PDU or CM definition table there should be at least one corresponding constraint table.

The constraint declaration tables are:

  • ASP Constraint Declaration;
  • PDU Constraint Declaration;
  • Structured Type Constraint Declarations;
  • CM Constraint Declaration.

Static and Dynamic Chaining

ASPs, PDUs and structured types may be chained to allow the construction of arbitrarily complex ASPs and PDUs. Static chaining means that the actual name of a PDU constraint or structure constraint appears as the value of an ASP parameter, PDU field or structure element, i.e. the structure is hardwired by symbolic references. Dynamic chaining means that the linking occurs when the actual constraint is passed as a parameter in the constraints reference.

Figure 29 : Relation between structured ASP and PDU types and their constraints

Complex ASN.1 Values

The concept of chaining is an integral part of ASN.1, although it is not described in those terms. It is expressed by the use of type references. If a reference is made from one type definition to another then there should be a corresponding value for that reference in the relevant constraints.

ASP Constraints

Generally, for every ASP type definition, there will be at least one ASP constraint declaration. However, some service definitions include ASPs that do not have parameters. In such cases, a constraint is not necessary. The same may apply to coordination messages, but it does not apply to PDUs. A PDU without fields is a nonsense.

ASP constraints are very similar to PDU constraints, which are more fully described in the next section. The rules that apply to PDU constraints, also apply to ASP constraints.

Case study 12a: A typical ASP constraint. Note that the constraint is parameterized - more about that later.

Figure 30 : ASP Constraint Declaration (NDr)

The DefCon Utility

The DefCon utility is a TTCN Access application that traverses a test suite in .itex format and generates default constraints for all ASN.1 ASP:s found in the test suite. The output is directed to the standard terminal output in .mp format.

Case study 12b: A test suite named MyTest.itex contains some ASN.1 ASP:s. To generate default constraints for these ASP:s and to store the constraints in a file named MyTestConstraints.mp, the DefCon utility should be called like this:

c:\> defcon MyTest.itex > MyTestConstraints.mp

The generated constraints can then be merged into the .itex file with the Autolink Merge utility. See "Merging TTCN Test Suites in the TTCN Suite" for more information.

Naming generated constraints

When calling DefCon, optional arguments may be provided. These arguments specify which pre- and/or postfixes to use for naming the generated constraints.

The default naming scheme is defined like this:

If there is an ASN.1 ASP named "MyASP" in the test suite, DefCon generates a constraint named "MyASPConstraint" from it. In other words, the default prefix is empty and the default postfix is "Constraint".

The syntax for changing pre- and postfixes is:

defcon [-pre <prefix>] [-post <postfix>] <testsuite>

Note:

Pre- and postfix strings are given without quotes on the command line.

PDU Constraints

Generally, for each field in the PDU type definition, there will be a corresponding field in the constraint. The value of the constraint field must be compatible with the type definition for that field. We shall see later how fields may be omitted or replaced, and how the derivation path entry should be used. We shall also see how constraint values are matched.

Case study 13: Declaration of an X_PDU constraint using the TTCN tabular format.

Figure 31 : PDU Constraint Declaration (CR1)

Figure 32 : Declaration of the same constraint using ASN.1

Structured Type Constraints

Constraints on structured type definitions and ASN.1 type definitions are constructed in the same way as ASPs and PDUs. Just as the type definitions may be used by both ASP and/or PDU type definitions, so also may the constraints.

When the TTCN tabular format is used the structure of the constraints shall be the same as the structure of the type definitions. That is, if a PDU field is defined as being of structure type then there will be one constraint for the PDU and one for the structure.

This rule is relaxed in ASN.1. The structure must be compatible but there need not necessarily be a one-to-one correspondence between the type tables and the constraint tables.

Case study 14: Declaration of a structured type constraint using TTCN tabular format.

Figure 33 : Structured Type Constraint Declaration (variable_part_CR1)

Figure 34 : Declaration of the same substructure constraint using ASN.1

CM Constraints

Coordination message constraints are also similar to PDU constraints.

Case study 15: Declaration of a CM constraint using TTCN tabular format

Figure 35 : CM Constraint Declaration (PTC_RES)

Figure 36 : Declaration of the same CM constraint using ASN (we shall assume
that RESULT_TYPE is an ASN.1 ENUMERATED type)


Constraint References

The TTCN SEND and RECEIVE statements indicate only which ASP or PDU type is to be transmitted or received. The constraints column in dynamic behaviour tables is used to state exactly which ASP or PDU value is to be sent, or is expected to be received. In other words, each SEND or RECEIVE statement must be accompanied by a constraints reference.

Note:

This rule can be relaxed for parameterless ASPs.

Figure 37 : Using constraint references in behavior lines

Parameterized Constraints

Constraints can be parameterized. That is, a constraint name may be followed by an optional formal parameter list. The formal parameters can be used in the value column of the constraint.

Figure 38 : A parameterized constraint

The actual parameters are passed to the constraint when it is invoked from the constraints column in a behaviour description.

Figure 39 : Invocation of a parameterized constraint

The actual parameter must always resolve to a specific value. In a SEND constraint this is the value that will eventually be encoded and transmitted.

In a RECEIVE constraint the actual parameter resolves to the value that will be matched against the received value. No binding occurs, i.e. the received value is not bound to the actual parameter. If it wished to capture received values, then this should be done by explicit assignment statements in the behaviour descriptions.

Dynamic Chaining

A common use of parameterized constraints is to link ASPs, PDUs and structures dynamically rather than statically, as we have described earlier. The linking occurs when the actual constraint is passed as a parameter in the constraints reference.

Figure 40 : Dynamic chaining of a parameterized PDU in an ASP

An N_DATArequest is used to carry the DT_PDU of the previous example.

Sending and Receiving Constraints

The rules for sending a constraint are not the same as those for receiving one. We shall examine each of these aspects in turn.

Constraints and the SEND Statement

A constraint in the context of SEND specifies the values that will eventually be transmitted over the network (at this point in time we will ignore encoding issues). In TTCN this transmitted object is called the Send Object which is built from information in the relevant constraint. Note that assignments may override values derived from the constraint in the Send Object, which is why BUILD occurs before ASSIGNMENT_LIST.

  • SEND3 BUILD 2 [QUALIFIER]1 [ASSIGNMENT_LIST]3 [TIMER_OPERATION]4

Constraint Values and SEND

In the context of SEND we shall use the term received constraint value to mean the value of an ASP parameter, PDU field or CM field of the ASP, PDU or CM constraint that the test specifier wishes to transmit. The type of the constraint value is defined in the relevant ASP, PDU or CM definition.

Constraint values for Send Objects should always be fully specified at the time of transmission of the object.

Figure 41 : Execution of an alternative that contains SEND

Constraints and the RECEIVE Statement

The receipt of an ASP, PDU or CM is more complex than simply receiving an ASP, PDU or CM of the correct type. Testing often requires that the composition of the ASP, PDU or CM is checked in detail. This is achieved in TTCN by specifying a constraint that the ASP, PDU or CM is expected to match. The RECEIVE event can be considered successful only if all the conditions stipulated in the constraint are satisfied. We shall, therefore, extend our description of the RECEIVE statement line of "The RECEIVE Statement" to be:

  • RECEIVE1 MATCH 2 [QUALIFIER]3 [ASSIGNMENT_LIST]4 [TIMER_OPERATION]5

Received Object

TTCN uses the term Received Object to mean the ASP, PDU or CM that is currently at the top of the relevant incoming PCO or CP queue, and is being checked during evaluation of a RECEIVE statement.

Constraint Values and RECEIVE

In the context of RECEIVE we shall use the term received constraint value to mean the value of an ASP parameter, PDU field or CM field of the ASP, PDU or CM field that the test specifier wishes the received value to match. Sometimes the received constraint value is called the expected value. The type of the expected value, defined in the relevant ASP, PDU or CM definition, is called the expected type.

Received Value

We shall use the term received value to mean the value of received object element. A received value is always, of course, a literal value, of a type compatible with the type of the corresponding element in the ASP, PDU or CM definition.

Figure 42 : Execution of an alternative that contains RECEIVE

Constraints and the OTHERWISE Statement

Constraints are not used with the OTHERWISE statement. Remember, OTHERWISE will always match if the named PCO incoming queue is not empty. No other checking is required.

Figure 43 : Execution of an alternative that contains OTHERWISE


Matching Received Constraint Values

In this section we shall take a closer look at the RECEIVE statement and how it is used to check the received values against the specified constraint values.

Specific Values

In most cases a constraint value will be a specific value. Note that this is not necessarily always a literal value. In TTCN a specific value is an expression which evaluates to a value compatible with the corresponding element type in the relevant ASP, PDU or CM definition. The TTCN syntax allows the operands of these expressions to be:

  • literal values;
  • constant identifiers;
  • formal parameter identifiers;
  • predefined and user defined operations;
  • expressions, i.e. the syntax is recursive.

When a specific value is used as a constraint value a successful match means that the received value is exactly equal to the value to which the constraint expression evaluates. Specific values can of course, be used to specify constraint values of all types.

Note:

We will talk about matching in different contexts. For example, a received value can match a constraint value. This does not mean of course that the entire constraint matches. For that to happen all received values must match all component values specified in the constraint.

Omitting Values

In many cases it may be necessary to omit ASP parameters or PDU fields. In the tabular format all parameters or fields are considered to be optional and may be omitted. This is denoted by writing a dash (-) instead of value.

Case study 16: Omitting values.

Figure 44 : Structured Type Constraint Declaration (variable_part_CR1)

In the ASN.1 only parameters or fields that are defined as being OPTIONAL or DEFAULT may be omitted. This can be indicated either by explicitly using the OMIT keyword, or by not including the parameter or field in the constraint.

Figure 45 : Omitting values in ASN.1 constraints

Replacing Values

In ASN.1 constraints may be constructed from previously defined constraints by using the REPLACE keyword.

Figure 46 : This table indicates that the constraint variable_part_CR2 is exactly the same as variable_part_CR1, except that the value of paramB is set to FALSE

Matching Mechanisms

In many instances it is not possible, or even desirable, to specify that the field of a received PDU shall have a specific value. It may be more appropriate to say that a match occurs if the received value falls within certain boundaries or fulfils certain conditions.

TTCN supports a number of matching mechanisms: matching symbols, matching operations and attributes that allow the test specifier to express these matching conditions instead of specific values.These mechanisms include:

  • lists of values
  • complemented lists of values
  • ranges of INTEGER values
  • any value
  • any value or omit value
  • wildcards
  • if present attribute
  • length attributes

Matching Value Lists

A constraint value may be a list of one or more specific values (remember that specific values include expressions etc. so the elements in the list may be quite complex). A match occurs only if the received value is equal to any one of the values in the constraint value list, otherwise the match fails.

  • (`00'B, `11'B) will match if the received value is either `00'B or `11'B.

Complementing Value Lists

If a value list is preceded by the keyword COMPLEMENT then a match occurs only if the received value is not equal to any of the values in the constraint value list, otherwise the match fails. Complement can be used on values of any type.

  • COMPLEMENT (`00'B, `11'B) will match if the received value is either `01'B or `10'B. Note that this is the same as the list: (NOT `00'B, NOT `11B').

Matching Ranges

Ranges may only be used to match values of INTEGER compatible types. The keywords INFINITY and -INFINITY may be used to specify ranges that may be unbounded in the positive and/or negative direction.

A range matches if the received value is within the range, including the upper and lower boundary.

  • the range (8 .. INFINITY) matches any INTEGER value greater than 7.

Matching Any Value

In many cases the test suite specifier is prepared to accept any single value for a particular field, provided that the actual value is compatible with the corresponding element type.

The matching symbol AnyValue is denoted by "?". A match will occur if the received value is any value that is compatible with the expected type.

  • suppose that we have declared a BITSTRING of length exactly 2; then AnyValue would match one of `00'B, `01'B, `10'B and `11'B but nothing else;
  • suppose that we have declared a value of SEQUENCE OF INTEGER type; then AnyValue will match any SEQUENCE OF INTEGER, except an empty sequence.

Matching Any Value, or Omitting It Altogether

The AnyOrOmit matching symbol, denoted by "*", is similar to AnyValue, except that the value may be omitted altogether. If there is a value present then a match will occur if the received value is any value that is compatible with the expected type; otherwise the value must be omitted. This is only allowed with optional fields.

  • suppose that we have declared a BITSTRING of length exactly 2; then AnyOrOmit would match one of `00'B, `01'B, `10'B and `11'B, or a value could be missing altogether;
  • suppose that we have declared a value of SEQUENCE OF INTEGER type; then AnyOrOmit will match any SEQUENCE OF INTEGER, including an empty sequence.

Wildcards Within Values

There are two wildcards that may be used within values:

  • AnyOne;
  • AnyOrNone.

The AnyOne symbol, denoted by "?", is used to replace single elements within all the string types, and within SEQUENCE, SEQUENCE OF, SET and SET OF types. However, the element may not be omitted.

  • `?0'B would match either `00'B or `10'B;
  • "ab?z" will match any character string of length 4 that begins with ab and ends with z;
  • A value of SEQUENCE OF INTEGER such as: {1, 2, ?, 3} means that the third element matches any INTEGER value.

Note that the denotation is the same as for AnyValue, but the semantics of the symbol are not the same.

The AnyOrNone symbol, denoted by "*", is used to replace single elements or a consecutive number of elements within all the string types, and within SEQUENCE, SEQUENCE OF, SET and SET OF types. Also, the element may be omitted.

  • `*0'B would match any BITSTRING value that ended with a zero bit;
  • "ab*z" will match any character string that begins with ab and ends with z, including the string "abz";
  • A value of SEQUENCE OF INTEGER such as: {1, 2, *, 3} means that any SEQUENCE OF INTEGER that begins with 1, 2 and ends with 3, including {1,2,3}, will match.

The If_Present Attribute

The If_Present attribute is intended for use with OPTIONAL fields. The test suite specifier may not know beforehand whether the IUT will be including an OPTIONAL value or not in a particular PDU - the protocol allows either or. The test then has to specify that if the optional value is present it should be checked.

  • 3 IF_PRESENT means that either the INTEGER value of 3 will be accepted for that particular field or no value shall be present.

Note that in the tabular format all fields are considered to be OPTIONAL. The match will occur if the received value is any value that is allowed by the specified expected type, i.e. they need not be explicitly declared as such. In ASN.1 this is not the same case; any fields that are OPTIONAL have to be declared as such.

Length Restrictions

Length restrictions apply to the following types:

  • BITSTRING
  • HEXSTRING
  • OCTETSTRING
  • CharacterString
  • SEQUENCE OF
  • SET OF

Essentially these are the same length restrictions that may be placed on the type definitions. The restriction may state the precise length of the string:

  • HEXSTRING [8]

or it may define a range:

  • HEXSTRING [4 .. 8]

Figure 47 : Examples of matching mechanisms used in a PDU constraint


Encoding

The TTCN standard says nothing about the actual encoding of values that are to be transmitted and received over the network. This aspect is being addressed in the second TTCN amendment, WDAM 2. It will allow the TTCN user to specify encodings at several levels:

  • for all ASPs and/or PDUs;
  • for individual ASP types and/or PDU types;
  • for individual ASP parameters and/or PDU fields;
  • for individual ASP constraints and/or PDU constraints;
  • for individual ASP constraint parameters and/or PDU constraint fields.

Encoding ASPs

It is unusual for a standard to specify the types of the parameters that constitute an ASP. How ASPs are realized is an implementation issue, outside the scope of the standard. The types, therefore, that are given to TTCN ASPs should not be considered binding - they are there to give a consistent representation in the test suite, and are mainly for documentation purposes.

In other words, checking of ASP parameters should be consistent with the implementation of those ASPs in the test system, rather than the exact TTCN specification.

Encoding PDUs

In contrast to ASPs, PDU fields are typed in the relevant protocol standard and it is essential that these types are implemented correctly in the ETS. As far as encoding is concerned, TTCN currently refers to the standards that the PDUs are derived from. For example, if ASN.1 is used it is probable that the ASN.1 basic encoding rules (BER) rules apply, but not necessarily. Work needs to be done on this issue.

Manipulation of Encodings

In some cases of testing it may be necessary to manipulate the encoding of values, e.g. in testing of the presentation layer. This aspect, too, is addressed in WDAM 2.


Referencing Components of Complex Types

TTCN allows the use of individual components of complex types as operands in expressions or as the l.h.s. of an assignment. Such components include:

  • a single ASP parameter;
  • a single PDU field;
  • a single structure element;
  • a single CM field.

In the context of ASN.1 it is possible to access:

  • an individual BIT in a BITSTRING;
  • an element in a SEQUENCE or SEQUENCE OF;
  • an element in a SET or SET OF;
  • an element in a CHOICE.

These references may be made either:

  • in the context of a SEND or RECEIVE statement; or
  • by capturing an incoming ASP or PDU for later reference.

References in the Context of SEND and RECEIVE

These are references to ASP parameters, PDU fields or structure elements made from a statement line that contains a SEND or RECEIVE and, most importantly, an associated constraint. In their simplest form these references are denoted by:

  • ASP_Identifier . ParameterIdentifier
  • PDU_Identifer . FieldIdentifier
  • CM_Identifer . FieldIdentifier
  • StructuredTypeIdentifier . ElementIdentifier

Suppose that a substructured PDU is chained to an ASP. To reference the kth element in the structure from a statement line we could write:

  • ASP_Identifier . Parameteri . PDU_Identifier . fieldj . StructureIdentifier . elementk

However, because the ASP, PDU and structure identifiers are unique within the test suite, it is allowed to simply use:

  • StructureIdentifier . elementk

For example, if we wish to preserve the value of the user_data field of the incoming DT_PDU, embedded in an N_DATAindication. This could be done by writing:

  • A := N_DATAindication . user_data . DT_PDU . user_data

This is rather verbose and because the PDU identifier is unique it is enough to write:

  • A := DT_PDU . user_data

In other words the `dotted path' need only contain the identifiers that are enough to give a complete and unique reference.

Referencing ASN.1 Elements

The same mechanism can be used to reference elements in ASN.1 constraints that use SEQUENCE, SEQUENCE OF etc.

Suppose that we have defined the following PDU:

Figure 48 : A TTCN PDU Type

A constraint on that PDU may be:

Figure 49 : A TTCN PDU Constraint

Then writing:

Figure 50 : A Send Statement

means that the third field in the constraint is overridden and that the send object a_pdu is transmitted with field3 having the value FALSE.

Note:

Where possible values should be set using parameters, rather than by this mechanism.

In cases where the elements are not named, such as the elements in the SEQUENCE OF INTEGER that compose field2 in our previous examples, it is possible to reference the element by position. For example, if we wish to override the value 22 in field2 we simply write:

Figure 51 : A Send statement

Individual bits in a BIT STRING can also be accessed in a similar manner. If we wish to change the third bit in the value of field1 from 0 to 1 we write:

Figure 52 : A Send statement

This mechanism cannot be used with other string types.

Capturing Incoming ASPs and PDUs

An incoming ASP or PDU (i.e. received object) is only preserved for the duration of a RECEIVE statement, i.e. components of the received object cannot be accessed on statement lines subsequent to the RECEIVE event. It is possible, however, to declare variables of ASP, PDU or structure type. These variables are then bound to the received object. Suppose the variable temp_pdu is of type A_PDU:

Figure 53 : A Receive statement

We can now access components of a_pdu on subsequent statement lines and not just on the statement line that contains the RECEIVE statement:

Figure 54 : A Qualifier statement


Verdicts

There are two mechanisms in TTCN that provide assignment of verdicts to a test case. These mechanisms are:

  • preliminary results;
  • explicit final verdicts.

A preliminary result or explicit final verdict may be associated with any TTCN statement except for the following:

  • IMPLICIT SEND;
  • ATTACH;
  • GOTO;
  • REPEAT.

The Result Variable

TTCN has a predefined test case variable, known as the result variable, called R. This variable may be used in expressions and the verdict column of a behaviour description. It is used to store preliminary results and has the following characteristics:

  • A preliminary verdict does not terminate execution of a test case;
  • it may appear in expressions as a read-only variable, i.e. it may not be used on the l.h.s. of an assignment;
  • it may only take one of the values: pass, fail, inconc or type definition. These values are predefined identifiers, and are case sensitive;
  • changes are made to its value by entries in the verdicts column;
  • at the start of a test case R is bound to the value type definition.

Preliminary Results

The value of R is changed by recording a preliminary result in the verdicts column. A preliminary result may be one of the following:

  • (P) or (PASS), meaning that some aspect of the test purpose has been achieved;
  • (I) or (INCONC), meaning that something has occurred which makes the test case inconclusive for some aspect of the test purpose;
  • (F) or (FAIL), meaning that a protocol error has occurred or that some aspect of the test purpose has resulted in failure.

For example:

  • writing (FAIL) in the verdict column will bind R to the value fail.

Preliminary results have an order of precedence, for example:

  • if R has the value fail and a preliminary result (PASS) is encountered in the verdict column, then R cannot be changed to pass and it will remain bound to fail. On the other hand, if R has the value pass and a preliminary result (FAIL) is encountered in the verdict column, then R is bound to the value fail.

The table below shows how R may be changed according to the precedence rules:

Figure 55 : Calculation of the preliminary result variable R
 | (PASS) | (INCONC) | (FAIL)
none | pass | inconc | fail
pass | pass | inconc | fail
inconc | inconc | inconc | fail
fail | fail | fail | fail

Final Verdicts

Execution of a test case is terminated either by:

  • reaching a leaf of the test case behaviour tree; and/or
  • an explicit final verdict on the behaviour line (i.e. in the verdict column).

A final verdict may be one of the following:

  • P or PASS, meaning that a pass verdict is to be recorded;
  • I or INCONC, meaning that an inconclusive verdict is to be recorded;
  • F or FAIL, meaning that a fail verdict is to be recorded;
  • the predefined variable R, meaning that the value of R is to be taken as the final verdict, unless the value of R is none in which case a test case error is recorded instead of a final verdict.

If no explicit final verdict is reached, then the final verdict is the value of R. If R is still bound to the value none then this is a test case error.

The final verdict must be consistent with the value of R. For example:

  • if R has the value fail and an explicit final verdict PASS is encountered in the verdict column, then a final verdict of fail and not pass should be recorded. On the other hand, if R has the value pass and an explicit final verdict FAIL is encountered in the verdict column, then a final verdict of fail should be recorded.

The table below shows how the final verdict should be recorded according to the value of R:

Figure 56 : Final verdict
 | (PASS) | (INCONC) | (FAIL) | R
none | pass | inconc | fail | *error*
pass | pass | inconc | fail | pass
inconc | *error* | inconc | fail | inconc
fail | *error* | *error* | fail | fail


The GOTO Statement

In order to be able to express repetitive behaviour in a convenient way, TTCN allows statement lines to be labelled so that jumps may be made to them from later points in the tree. A GOTO is denoted either by:

  • -> LabelIdentifier

or:

  • GOTO LabelIdentifier

Infinite loops should be avoided, i.e. entering the GOTO loop should always depend on some event occurring or condition being fulfilled.

Figure 57 : Using GOTO in a behavior tree

The following rules should be followed:

  • a GOTO can only be made within a single tree in a behaviour description;
  • the label should be unique within the behaviour description;
  • line numbers may not be used as labels;
  • the label must always be associated with the first statement line in a given set of alternatives, i.e. a GOTO cannot cause a jump to the middle of a set of alternatives;
  • a result of the previous rule means that a GOTO to the first level of alternatives in a test step (i.e. the test step root) is not allowed;
  • a GOTO may only be made to an ancestor node in the behaviour tree, i.e. a jump to a part of the tree that has previously been executed;
  • no other statements may be used in conjunction with a GOTO.


Timer Statements

TTCN timers are used to test timer events in the IUT. This is usually done by timing an expected response from the IUT using the START timer operation and the TIMEOUT event. The CANCEL timer operation is used to stop and reset a running or expired timer.All timers are declared in the Timer Declarations table. The duration is the period of time that will pass from the moment a timer is started to the moment it expires. Duration is measured in one of the following units:

  • ps (i.e. picosecond);
  • ns (i.e. nanosecond);
  • us (i.e. microsecond);
  • ms (i.e. millisecond);
  • s (i.e. second);
  • min (i.e. minute).

Figure 58 : Declaration of timers

The Timeout List

TTCN maintains a timeout list. If a timer expires its name is added to the timeout list. Three things can remove the name of the timer from the timeout list:

  • a successful TIMEOUT statement;
  • a START timer operation;
  • a CANCEL timer operation.

The TIMEOUT Statement

The test suite specifier may state that a named timer be checked to see if it has timed-out. This is denoted by:

  • ?TIMEOUT TimerIdentifier

When this statement is encountered while processing a statement line the TIMEOUT will match if the named timer is in the timeout list, otherwise the TIMEOUT fails.

An alternative use of TIMEOUT is simply:

  • ?TIMEOUT

i.e. no TimerIdentifier is given. In this case the TIMEOUT statement will succeed as long as the timeout list is not empty.

The TIMEOUT statement may be qualified and it may be followed by an ASSIGNMENT_LIST and/or TIMER_OPERATION. The order in which these statements may appear in the statement line is fixed, as shown below; the square brackets indicate that the presence of the statement in the statement line is optional:

  • TIMEOUT2 [QUALIFIER]1 [ASSIGNMENT_LIST]3 [TIMER_OPERATION]4

Note:

TIMEOUT should not be used to guard against a faulty IUT not sending a required response. It is the responsibility of the test system to implement detection of such an occurrence.

Timer Snapshots

We have already mentioned that at the beginning of each cycle through a set of alternatives a snapshot is taken of the incoming PCO queues. The alternatives are then checked against this snapshot. The same thing is done for the timeout list. A snapshot is taken of this list at the start of each cycle and if a TIMEOUT alternative is encountered in the set of alternatives it is checked against the timeout snapshot rather than the actual timeout list. This means that the expiry of a timer during processing of a set of alternatives is not registered until the timer snapshot is updated.

The START Timer Operation

A named timer is started using the START timer operation. This is denoted by:

  • START TimerIdentifier

The duration for this timer is taken from the timer declaration. Alternatively, an explicit duration may be given, which overrides the declared duration:

  • START TimerIdentifier ( Duration )

If the timer is already running when the START is invoked then the timer is cancelled, reset and then started, i.e. the timer is re-started.

If the timer has expired then its name is removed from the timeout list before it is re-started.

The START_TIMER statement may be qualified and it may be followed by an ASSIGNMENT_LIST. The order in which these statements may appear in the statement line is fixed, as shown below:

  • [QUALIFIER]1 [ASSIGNMENT_LIST]2 [START_TIMER]3

Figure 59 : Using START and TIMEOUT in a behavior tree

The CANCEL Timer Operation

A named timer is cancelled using the CANCEL operation. This is denoted by:

  • CANCEL TimerIdentifier

An alternative use of CANCEL is simply:

  • CANCEL

i.e. no TimerIdentifier is given. In this case all running timers are cancelled and reset and the timeout list is cleared.

Cancelling a timer that is expired will result in the timer being reset and its identifier is removed from the timeout list.

The CANCEL_TIMER statement may be qualified and it may be followed by an ASSIGNMENT_LIST. The order in which these statements may appear in the statement line is fixed, as shown below:

  • [QUALIFIER]1 [ASSIGNMENT_LIST]2 [CANCEL_TIMER]3

Figure 60 : Execution of an alternative that contains a stand-alone timer operation


Constants and Variables

TTCN supports both constants and variables. There are two types of constants:

  • test suite parameters;
  • test suite constants;

and two types of variables:

  • test suite variables;
  • test case variables.

The tables used are:

  • Test Suite Constant Declarations
  • Test Suite Parameter Declarations
  • Test Suite Variable Declarations
  • Test Case Variable Declarations

Test Suite Constants and Test Suite Parameters

Test suite constants are declared globally and may be used anywhere in the test suite, including the constraints part. The value of the constant is specified at its point of declaration and may not be changed.

Case study 17: Declaration of test suite constants.

Figure 61 : Test suite constant declarations

Test Suite Parameters

Test suite parameters are also constants, but their actual values are not known to the abstract test suite specifier. These values will depend on which IUT is being tested, and possibly on the test system itself. In this sense the values of test suite parameters will be different from IUT to IUT, but during the testing of any given IUT they will remain constant.

Case study 18: Declaration of test suite parameters.

Figure 62 : Test suite parameter declarations

The test suite parameter values are derived from the Protocol Implementation Conformance Statement (PICS) and the Protocol Implementation eXtra Information for Testing (PIXIT). These documents are like checklists that are filled-in according to the characteristics of the IUT.

Prior to executing the tests the PICS and PIXIT are used to bind values to the test suite parameters. This process is called test suite parameterization.

Test Suite and Test Case Variables

Both test suite variables and test case variables are declared globally i.e. they may be used by test cases, test steps and defaults throughout the test suite. A default value may be specified for each variable, if wished. If no default value is specified, then the variable is said to be unbound.

Variables should be bound before use, unless they appear on the l.h.s. of an assignment.

Case study 19: Declaration of test case variables.

Figure 63 : Test case variable declaration

Resetting Default Values

The difference between the two kinds of variable is when they are reset to their default values (if no default value is specified for a variable, then resetting means that the variable becomes unbound):

  • test suite variable are reset at the end of execution of the test suite, which means that information may be retained between test case execution;
  • Test case variables are reset at the end of execution of each test case, i.e. test case variables begin each test case bound to their default values.

Variables in Concurrent TTCN

When more than one test component exists, as does with concurrent TTCN, then each test component is supplied with its own copy of each test case variable.

  • In the case study we declare the test case variable count. This variable is available to both the lower tester and the upper tester as a separate copy of count to each, i.e. if the lower tester changes the value of count it only changes its copy of count, and not the upper tester's copy.

Test suite variables behave the same way in concurrent TTCN as they do in the non-concurrent version.


Dynamic Behaviour Descriptions

There are three types of tables for specifying the behaviour descriptions:

  • Test Case Dynamic Behaviour;
  • Test Step Dynamic Behaviour;
  • Default Dynamic Behaviour.

We have already noted that the difference between the different behaviour tables is in the header, rather than in the body of the tables.

Figure 64 : Fragment of a test case behavior table, showing the header for the test case

Test case Identifiers and Test Group References

The test case identifier appears in the first field and, like most TTCN identifiers, it should be a name unique to the entire test suite. The second field contains the test case reference, which is a path name that specifies the test case's location in the test suite structure.

In the case of test steps this path specifies the test step's location in the test step library. In the case of defaults it specifies the location of the default in the default library. These references have the general format:

  • SuiteIdentifier / GroupIdentifier1 / . . . / GroupIdentifiern /

Note the terminating slash, which is the last group name in the path. The path may begin with the first GroupIdentifier, i.e. the SuiteIdentifier is optional. If the test suite has no hierarchy then the reference is empty.

Test Purpose and Objective

In the test case table the third field is used to specify the test purpose. The corresponding field in test steps and defaults is called the objective.

Configuration

The configuration entry is introduced by the concurrent TTCN to state the configuration in which this test case behaviour description is used. This field does not appear in test steps and defaults.

Default Behaviour

The default entry is used to state the default behaviour which should be used, if any.

Case study 20: Test step dynamic behaviour.

Figure 65 : Test step dynamic behaviour (LT_DATA_TRANSFER)


Using Aliases

One of the main aims of TTCN is to specify behaviour descriptions so that the human reader can easily understand the TTCN specification of the test purpose.

The conformance standard requires that behaviour be expressed in terms of (N) and (N-1) ASPs. However, a behaviour tree consisting of mostly (N-1)-data requests and indications says very little to the reader. What is important are the PDUs embedded in these service primitives. If static chaining is used the reader will have no idea, without turning to the constraints, what PDU interactions are specified in the test.

The alias mechanism allows ASPs (and if necessary PDUs) to be renamed to reflect the different PDUs that they carry. The (N-1)-data request and indication may have several aliases, depending on which (N)-PDU they are carrying.

Figure 66 : Declaring aliases

In ISO/IEC 9646-3 aliases are defined as textual expansions. However, it is probably easier to think of alias identifiers as alternatives to ASP or PDU identifiers in the SEND and RECEIVE statements. The effect is exactly the same, i.e.

  • PCO_Identifier ! AliasIdentifier
  • PCO_Identifier ? AliasIdentifier

Figure 67 : Test Step dynamic behavior using aliases


Modularization of Test Cases

Test cases can be long and complex. There exist two mechanisms that allow test cases to be modularized: test steps and defaults.

Test Steps

Behaviour trees can be modularized by splitting them into sub-trees called test steps. Test steps are either:

  • local to a behaviour description; or
  • reside in the test step library.

Test steps may be parameterized, i.e. the calling tree can pass PCOs, variables, literal values, constraints etc. to the attached test step.

Local test steps

Local test steps may only be used within the behaviour description in which they appear:

Figure 68 : Illustration of local test trees and test step library

The Test Step Library

Test steps that belong to the test step library are specified in Test Step behaviour tables. These steps may be called by any test case, test step or default.

The ATTACH Statement

The ATTACH statement is used to invoke a test step, and is denoted by:

  • + TreeIdentifier ActualParameterList
    for attachment of a local test step; or
  • + TestStepIdentifier ActualParameterList
    for attachment of a test step in the test step library.

In both cases the actual parameter list should only be used if the test step has a formal parameter list. Note that a parameter may also be a PCO or CP.

Case study 21: The following test step:

Figure 69 : Test Step Dynamic Behaviour (LTS)

Case study 22: Is the same as:

Figure 70 : Test Step Dynamic Behaviour (LT)

Tree Attachment as a Subroutine Call

TTCN defines tree attachment as the actual expansion of the called tree, i.e. the test step, into the calling tree, which may be a test case or another test step. While this is a sensible approach, adequately described in the TTCN standard, we feel that the view of treating test steps as subroutines is a valid one, and one that implements the TTCN semantics for tree attachment correctly. These semantics are easily understood by anyone with a programming background.

A test step can be considered as a subroutine when handled in the following manner:

  • when an attach statement is reached when looping through a set of alternatives, control is passed to the attached test step;
  • if no alternative in the first set of alternatives in the test step is successful during the first loop through that set of alternatives, then control returns from the test step to the calling tree, and evaluation continues with the other alternatives, if any, in the same set of alternatives as the attach statement; this has the same effect as if the test step was actually expanded into the calling tree;
  • if an alternative in the first level of the test step is successful then execution continues in the test step tree;
  • if a final verdict is reached in the test step tree then the execution of the test step (i.e. the entire test case) is halted and control is not returned to the calling tree;
  • if no final verdict is encountered, before a leaf of the test step tree is reached then control returns to the calling tree, and execution continues with the next set of alternatives (if any) subsequent to the attach statement, i.e. the next level of indentation.

Figure 71 : Execution of a test step

Default Behaviour

The conformance standard requires that a TTCN test case must be fully specified, in terms of behaviour. This means that at any point in time a tester must be prepared to accept all possible incoming ASPs or PDUs. This includes not only the ASPs or PDUs that are allowed by the protocol but also any ASP, legal or otherwise, that the IUT or service provider may issue

The easiest way to take care of this is by using the OTHERWISE statement. However, TTCN requires that the OTHERWISE statement leads to a fail verdict and this may not always be desirable. For example, it may be perfectly legal for the underlying network service to issue an N_DISCONNECTindication at any time. Certainly, an OTHERWISE would pick this up, but a verdict of FAIL in such an instance would be quite wrong. The only verdict that should be assigned in this case is INCONClusive, i.e. use with care!

Specifying all possible combinations tends to clutter up the main behaviour description, detracting from the readability of the test case. The default behaviour can be used to specify this peripheral behaviour in a precise manner. It will often comprise the set of ASPs or PDUs that are allowed by the protocol at any given time but which are not part of the test purpose, and an OTHERWISE to catch all other unspecified events. It is also common practice to include a general TIMEOUT in the default.

Case study 23: If we specify the following default behaviour.

Figure 72 : Default Dynamic Behaviour (LT_DEFAULT)

Modeling Default Behaviour

Default behaviour can be modeled as a tree attachment that is implicitly called as the last alternative in every set of alternatives.

Defaults Reference

A test case or test step references this default behaviour in the Defaults entry in its header. If this entry is empty then no default behaviour is applicable.

Figure 73 : The test step with a default

Figure 74 : Is the same as the previous test step


Parameter Lists in TTCN

The following TTCN objects may be parameterized:

  • test suite operations
  • constraints
  • test steps
  • defaults

Formal Parameter Lists

In all cases parameterization is indicated by the relevant TTCN object identifier being followed by a formal parameter list. For example:

  • an_identifier (fpar1, fpar2:INTEGER, fpar3:HEXSTRING)

Actual Parameter Lists

Parameterized objects are invoked with an actual parameter list. For example:

  • an_identifier(1, 2, FALSE)

The following rules apply:

  • the number of parameters in the actual parameter list must be the same as the number of parameters in the formal parameter list;
  • the actual values in the actual parameter list must be of a type that is compatible with the type of the corresponding formal parameters;
  • all actual parameters shall be bound at the time of invocation of the test suite operation, test step, constraint or default;
  • all actual parameters must resolve to specific values.

Call-By-Reference

The TTCN uses textual substitution to define the passing of actual parameters in test steps and defaults. An alternative, and more intuitive, way of describing parameter passing for test steps and defaults and yet retain TTCN semantics is to describe the mechanism in terms of call-by-reference, in which the called routine (test step or default) has access to the original argument, not a local copy. All operations that effect that argument have the same effect on the original.

Call-By-Value

The TTCN standard states that neither user defined operations nor constraints may change the values of any actual parameters that are passed to them, i.e. they shall have no side-effects. Thus, for user defined operations and constraints it is more suitable to describe the parameter passing mechanism in terms of call-by-value in which the called routine (user defined operations or constraint) works on a local copy of the argument. The original argument is not affected by the routine.


Test Case Selection

A test suite contains many hundreds, perhaps thousands, of test cases. In most cases of testing it will only be necessary to choose and run a selection of tests taken from the test suite. This choosing process is called test case selection. Depending on values and answers obtained from the PICS and PIXIT only a subset of the entire test suite need be executed.

Selection Expressions

TTCN allows each test case to be associate with a selection expression. These expressions are predicates that will evaluate to TRUE or FALSE depending on the answers given to the relevant PICS and PIXIT questions. If no selection predicate is given then the test will always be selected.

The predicates are defined in the Test Case Selection Expression Definitions table, and references are made to them from the Test Case Index.

Groups of test cases may be selected in a similar manner by making references to selection expressions from the Test Suite Structure table.


Structure of a TTCN Test Suite

Each TTCN object has a specific position in the hierarchy of the test suite.

Parts of a Test Suite

The different test suite components may only appear in a specific order. A TTCN test suite consists of four parts:

  • Overview
  • Declarations
  • Constraints
  • Behaviour

Each part contains a number of TTCN tables. The order in which the tables appear is shown in the following list. Each bulleted item in this list represents a TTCN table. The tables that have number subscripts are tables for single TTCN objects, e.g. PDUs and test cases. The tables that do not have a subscript are multiple TTCN object tables, e.g. simple type definitions or test suite variables.

Some tables may be displayed in a compact format. Tables printed in italic font are defined in the TTCN extensions.

Suite Overview Part

The test suite overview consists of four tables:

  • Test Suite Structure
  • Test Case Index
  • Test Step Index
  • Default Index.

Declarations Part

The declarations part is concerned both with the definition of new (i.e. not predefined) data types and operations and the declaration of all the test suite components.

  • Test Component Declarations
  • Test Component Configuration Declarations
  • Simple Type Definitions
  • Structured Type Definition1
  • :
  • ASN.1 Type Definition1
  • :
  • ASN.1 Type Definitions By Reference
  • Test Suite Operation Definition1
  • :
  • Test Suite Parameter Declarations
  • Test Case Selection Expression Definitions
  • Test Suite Constant Declarations
  • Test Suite Variable Declarations
  • Test Case Variable Declarations
  • PCO Declarations
  • CP Declarations
  • Timer Declarations
  • ASP Type Definition1
  • :
  • ASN.1 ASP Type Definition1
  • :
  • ASN.1 ASP Type Definitions By Reference
  • PDU Type Definition1
  • :
  • ASN.1 PDU Type Definition1
  • :
  • ASN.1 PDU Type Definitions By Reference
  • TTCN CM Type Definition1
  • :
  • ASN.1 CM Type Definition1
  • :
  • Alias Declarations

Constraints Part

The constraints part contains the tables for all the ASP, PDU, structure and CM constraints. Both in the tabular form and the ASN.1.

  • ASP Constraint Declaration1
  • :

Note:

ASP Constraints may displayed in a compact format if wished.

  • ASN.1 ASP Constraint Declaration1
  • :

Note:

ASN.1 ASP Constraints may displayed in a compact format if wished.

  • PDU Constraint Declaration1
  • :

Note:

PDU Constraints may displayed in a compact format if wished.

  • ASN.1 PDU Constraint Declaration1
  • :

Note:

ASN.1 PDUConstraints may displayed in a compact format if wished.

  • Structured Type Constraint Declaration1
  • :

Note:

Structured Type Constraints may displayed in a compact format if wished.

  • ASN.1 Type Constraint Declaration1
  • :

Note:

ASN.1 Type Constraints may displayed in a compact format if wished.

  • CM Constraint Declaration1
  • :
  • ASN.1 CM Constraint Declaration1
  • :

Dynamic Part

The dynamic part contains all the test cases, all the test steps in the test step library and the all the defaults in the default library.

  • Test Case Dynamic Behaviour1
  • :

Note:

Test groups, i.e. the test suite structure, are not represented here. Test cases may displayed in a compact format if wished.

  • Test Step Dynamic Behaviour1
  • :

Note:

Test step groups are not represented here.

  • Default Dynamic Behaviour1
  • :

Note:

Default groups are not represented here.


Distributed Development (UNIX)

In the TTCN suite on UNIX, the implemented version of TTCN does support modularization of a TTCN document. This support is conveniently used to concurrently produce multiple documents with some definitions in common or to cooperatively produce one large TTCN document.

The mechanism implemented assumes that each user have a private target directory and all collaborating users having the same source files.

The following figures depict how this is accomplished. In the figures TS denotes a test suite and M denotes a TTCN module. Numbers are used to distinguish separate documents.

Figure 75 : Two Modular Test Suites using a common Module

Figure 75 depicts the case where two test suites are developed in parallel by two different users with both test suites referencing objects defined in a common module.

Figure 76 : A large Modular Test Suite

Figure 76 depicts the case where a large test suite (TS) is developed in parallel by two different users, each responsible for one module of the test suite (M1 and M2), with both modules referencing objects defined in a common module (M3).

In the case where more than one user is to concurrently develop different parts of a large test suite, here is a simple way to distribute the document files in the file system.

  1. First create or select a suitable readable and writable directory accessible to all users. This directory will be used to store all files common to all users and so need to be accessible to all users with the same path.
  2. Next create a template system file in this directory containing references to all documents (all document files referenced could conveniently be present in this directory), creating empty documents for those documents that will be produced later, set the directory representation to the absolute form, save everything, and finally make this template system file unwritable to protect it from inadvertent modifications.
    At this point it may be wise to assign ownership of the documents to the users that are responsible for them and inhibit write access for others, and also to remove superfluous files (e.g. all TTCN files that have an extra hash-sign, `#', prepended to the file name).
  3. Finally inform all users that they should follow these steps when they start their work:
    • Select or create a personal target directory, preferably on a local disk for optimum speed
    • Copy the template system file to it (i.e. create a personal copy)

The user may now change the directory representation back to the relative form if so wished.


The Complete Case Study

Suite Overview Part

Figure 77 : Test suite structure

Figure 78 : Test step index

Figure 79 : Default index

Declarations Part

Figure 80 : Simple type definitions

Figure 81 : Definition of VARIABLE_PART

Figure 82 : Definition of INC operation

Figure 83 : Test suite parameter declarations

Figure 84 : Test suite constant declarations

Figure 85 : Test case variable declarations

Figure 86 : PCO type declarations

Figure 87 : PCO declarations

Figure 88 : Coordination point declarations

Figure 89 : Test component declarations

Figure 90 : Declaration of SINGLE_PARTY

Figure 91 : Declaration of MULTI_PARTY

Figure 92 : Definition of IN_DATArequest

Figure 93 : Definition of IN_DATAindication

Figure 94 : Definition of X_CONNECTindication

Figure 95 : Definition of X_CONNECTresponse

Figure 96 : Definition of X_DATArequest

Figure 97 : Definition of X_DATAindication

Figure 98 : Definition of CR_PDU

Figure 99 : Definition of CC_PDU

Figure 100 : Definition of DT_PDU

Figure 101 : Definition of PTC_RESULT

Figure 102 : Alias definitions

Constraints Part

Figure 103 : Declaration of variable_part_CR1

Figure 104 : Declaration of variable_part_CR2

Figure 105 : Declaration of NDr

Figure 106 : Declaration of NDi

Figure 107 : Declaration of CONind

Figure 108 : Declaration of CONrsp

Figure 109 : Declaration of DATreq

Figure 110 : Declaration of DATind

Figure 111 : Declaration of CR1

Figure 112 : Declaration of CC1

Figure 113 : Declaration of DT1

Figure 114 : Declaration of PTC_RES

Dynamic Part

Figure 115 : Definition of SP_DATA_TRANSFER

Figure 116 : Definition of MP_DATA_TRANSFER

Figure 117 : Definition of LTS

Figure 118 : Definition of ESTABLISH_CONNECTION

Figure 119 : Definition of LT_DATA_TRANSFER

Figure 120 : Definition of CLOSE_CONNECTION

Figure 121 : Definition of UTS

Figure 122 : Definition of ACCEPT_CONNECTION

Figure 123 : Definition of UT_DATA_TRANSFER

Figure 124 : Definition of UT_DEFAULT

Figure 125 : Definition of UT_DEFAULT

Figure 126 : Definition of T_DEFAULT


Telelogic Tau 4.4

SDL Suite Getting Started

Telelogic
http://www.telelogic.com


Introduction

About this Manual

This volume, SDL Suite Getting Started, contains a guide that will assist you in getting familiar with the SDL suite environment.

We start by giving an introduction to the SDL suite and the supported languages. Then follows a number of chapters with hands-on tutorials on how to use the tools included in the SDL suite, including a first look at object-oriented analysis and design. These tutorials use the same simple example (DemonGame), and can be followed without any previous knowledge of the SDL suite.

The remaining chapters contain a number of more advanced tutorials on how to use ASN.1 data types and Cmicro targeting in practice.

All tutorials build on the knowledge gained in the previous tutorials, so you should practice them in the order they are included.

Documentation Overview

A general description of the Telelogic Tau documentation can be found in "Telelogic Tau Documentation".

Typographic Conventions

The typographic conventions that are used in the Telelogic Tau documentation are described in "Typographic Conventions".

How to Contact Customer Support

Detailed contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".


1 Introduction to Languages and Notations

This chapter begins with a brief introduction to SDL; the language, its history, its main concepts and application areas.

Next follows an introduction to the MSC language (including High level MSC), the Object Model notation and State Chart notation, and the ASN.1 notation.

Telelogic Tau also comprises the TTCN suite. For the sake of completeness, we have included a brief introduction to the TTCN notation. More information can be found in Introduction to Languages and Notations.

After reading this chapter, you may want to deepen your -knowledge of SDL. In Object Oriented Design Using SDL, you will find information about how to take advantage of the SDL-92 language in an SDL suite environment.

Also, a list of recommended literature dealing with various language topics is enclosed at the end of this chapter; see "References" .


Benefits of a Specification Language

It is widely accepted that the key to successfully developing a system is to produce a thorough system specification and design. This task requires a suitable specification language, satisfying the following needs:

  • A well-defined set of concepts.
  • Unambiguous, clear, precise, and concise specifications.
  • A basis for verifying specifications with respect to completeness and correctness.
  • A basis for determining whether or not an implementation conforms to the specifications.
  • A basis for determining the consistency of specifications relative to each other.
  • Use of computer-based tools to create, maintain, verify, simulate and validate specifications.
  • Computer support for generating applications without the need of the traditional coding phase.

The SDL suite fulfills all the demands outlined in the list above.


General about the SDL Language

SDL (Specification and Description Language) is a standard language for specifying and describing systems1. It has been developed and standardized by ITU-T in the recommendation Z.100.

The development of SDL started in 1972 after a period of research work. The first version of the language was issued in 1976 and it has been followed by new versions every fourth year. The latest versions expanded the language considerably, and today SDL is a "complete" language in all senses.

In the SDL suite, there is full support of SDL including some of the SDL-96 concepts. For more information about the SDL support in the SDL suite, see "Application Programmers Interface.

Modularity

An SDL specification/design (a system) consists of a number of interconnected modules (blocks). A block can recursively be divided into more blocks forming a hierarchy of blocks. The channels define the communication paths through which the blocks communicate with each other or with the environment. Each channel usually contains an unbounded FIFO queue that contain the signals that are transported on the channel. The behavior of the leaf blocks is described by one or more communicating processes. The processes are described by extended finite state machines.

Object Oriented Design

SDL furthermore supports object-oriented design by a type2 concept that allows specialization and inheritance to be used for most of the SDL concepts, like blocks, processes, data types, etc. The obvious advantage is the possibility to design compact systems and to reuse components which in turn reduces the required effort to maintain a system.

Graphical and Textual Notations

SDL gives a choice of two equivalent syntactic forms; a Graphical Representation (SDL/GR) and a textual Phrasal Representation (SDL/PR). The SDL suite supports both notations.

Application Areas

Currently, SDL is mainly known within the telecommunication industry, but it also has broader areas of application and is now gaining acceptance within the real-time software industry. The application areas may be summarized as follows:

  • Type of system described by SDL: Real-time, interactive, distributed.
  • Type of information provided by SDL: Behavior and structure.
  • Level of abstraction supported by SDL: From system overview to functional detail.
1

No distinction is made in SDL between the terms "specification" and "description", although they generally have different meanings in SDL applications.

2

SDL has adopted the term type which corresponds to the term class used in many of the OO notations and programming languages.


More about SDL

Theoretical Model

The basic theoretical model of an SDL system consists of a set of extended finite state machines (FSM) that run in parallel. These machines are independent of each other and communicate with discrete signals.

An SDL system consists of the following components:

  • Structure
    • hierarchical decomposition with system, block, process, and procedure as the main building blocks
  • Communication
    • asynchronous signals with optional signal parameters
    • remote procedure calls for synchronous communication
  • Behavior
    • processes
  • Data
    • abstract data types that can be inherited, generalized and specialized
    • ASN.1 data types according to Z.105
  • Type Concept
    • describing type hierarchies with inheritance, generalization and specialization

Structure

Figure 1 shows the four main hierarchical levels in SDL: system, block, process, and procedure.

Figure 1 : The architectural view of an SDL system

In addition, there is a service concept that can be used within processes. Procedures can be used in both processes and services.

Communication

Figure 2 : Sending signals between two processes

In SDL, there is no global data. This approach requires that information between processes, or between processes and the environment, must be sent with signals and optional signal parameters. Signals are sent asynchronously, that is, the sending process continues executing without waiting for an acknowledgment from the receiving process.

Synchronous communication is possible via a shorthand, remote procedure call. This shorthand is transformed to signal sending with an extra signal for the acknowledgment.

Behavior

The dynamic behavior in an SDL system is described in the processes. The system/block hierarchy is only a static description of the system structure. Processes in SDL can be created at system start, or created and terminated dynamically at runtime. More than one instance of a process can exist. Each instance has a unique process identifier (PId). This makes it possible to send signals to individual instances of a process. The concept of processes and process instances that work autonomously and concurrently makes SDL a true real-time language.

Figure 3 : Creation of a new process instance at runtime

Data

The abstract data types concept used within SDL is very well suited to a specification language. An abstract data type is a data type with no specified data structure. Instead, it specifies a set of values, a set of operations allowed on the data type and a set of equations that the operations must fulfil. This approach makes it very simple to map an SDL data type to data types used in other high-level languages.

Alternatively, ASN.1 types can be used in SDL. This is useful when specifying or implementing telecommunication applications that make use of ASN.1. ITU-T Recommendation Z.105 defines how ASN.1 is used in combination with SDL. For more information on ASN.1, see "ASN.1 - Abstract Syntax Notation One" .

Figure 4 : Abstract Data Type example

Type Concept

The object-oriented concepts of SDL give you powerful tools for structuring and reuse. The concept is based on type definitions. All structural building blocks can be typed. Type definitions can be placed anywhere in the system, and also in packages outside the system.

One of the major benefits of using an object oriented language is the possibility to create new objects by adding new properties to existing objects, or to redefine properties of existing objects. This is what is commonly referred to as specialization.

In SDL, specialization of types can be accomplished in two ways:

  • A subtype may add properties not defined in the supertype. One may, for example, add new transitions to a process type, add new processes to a block type, etc.
  • A subtype may redefine virtual types and virtual transitions defined in the supertype. It is possible to redefine the contents of a transition in a process type, to redefine the contents/structure of a block type, etc.


The Message Sequence Chart Language

History

During the last years, ITU has made a considerable effort in standardizing a formal language which defines Message Sequence Charts (MSC). In the summer of 1992, a first version of the MSC recommendation Z.120 was published.

As defined in the recommendation Z.120, the MSC language offers a powerful complement to SDL in describing the dynamic behavior of an SDL system. Its graphical representation is well suited for presenting a complex dynamic behavior in a clear and unambiguous way which is easy to understand.

There is an extended version of the MSC standard, called MSC'96, as defined in the current Z.120. In the SDL suite, there is support for the most important MSC'96 extensions. See "Compatibility with ITU MSC for more information.

Plain MSC

An MSC describes one or more traces from one node to another node of an abstract communication tree generated from an SDL specification.

Basically, the information interchange is carried out by sending messages from one instance to another (see Figure 5). In an SDL specification, those messages would coincide with the signals which are sent from one process and consumed in another process. The instances would correspond to any part of the specification (an SDL system, a block or a process).

An MSC can reference another MSC using an MSC reference symbol. MSC references can for example be used to have one MSC describing an initialization sequence and then reference this MSC from a number of other MSCs.

The reference symbol may not only refer to an MSC but can also contain MSC reference expressions that reference more than one MSC. This construct gives a very compact MSC representation and it also provides an excellent means for reusability of certain MSCs.

By using inline operator expressions, several MSC scenarios can be composed in a single diagram. The same structures of events can be expressed as with MSC reference symbols.

Figure 5 : An example of a simple Message Sequence Chart

High-Level MSC

A high-level MSC (HMSC) provides a means to graphically define how a set of MSCs can be combined. Contrary to plain MSCs, instances and messages are not shown within an HMSC, but it focus completely on the composition aspects. HMSCs can be hierarchically structured, i.e. it is possible to refine HMSCs by other HMSCs. The power of the MSC language is considerably improved with the new concepts introduced with HMSCs. It is e.g. much easier to specify a main scenario together with all accompanying exceptions.

Figure 6 : Example of an HMSC

Graphical and Textual Notations

The MSC language supports two notations which are equivalent. Besides the graphical notation (MSC-GR), a textual notation (MSC-PR) is standardized since the autumn of 1994.

Application Areas

Among the various application areas, we have selected the following:

  • Producing documents with the purpose of defining the requirements of a system.
  • Facilitating the design phase, by identifying and documenting a multitude of dynamic cases before starting designing with SDL.
  • Presenting the execution of a simulation as a graphical output which is easy to understand and which can later on be verified against a reference. Message Sequence Charts can be verified against an SDL system using the SDL suite.
  • Presenting the execution trace of an SDL system during an interactive simulation and generation of reports.


Object Model Notation

The object model notation used in the SDL suite is an adaptation of the notations used in OMT (Object Modeling Technique) and UML (Unified Modeling Language). The OMT/UML notation is a commonly accepted graphical notation that is used for drawing diagrams that describe objects and the relations between them.

Class

The most important concept in an object model is the class definition. A class is a description of a group of similar objects that share the properties defined by the class. The properties of a class are described with attributes and operations. The object model notation for a class is exemplified in Figure 7, where the second class definition also shows how to define attributes and operations.

Figure 7 : A collapsed class symbol and a class symbol
with attributes and operations

Classes may inherit attributes and operations from other classes, known as specialization and generalization. The object model notation for this is shown in Figure 8.

Figure 8 : inheritance between classes

Relations and Multiplicity

Classes may be physically or logically related to each other. This is shown in the object model by means of associations as shown in Figure 9. An association may have a name and/or the endpoints of the association may be labeled by the role of this endpoint.

Figure 9 : Associations between classes

Aggregation is special kind of association, indicating a "consists of" relation. It has its own notation as shown in Figure 10.

Figure 10 : Aggregation

The endpoints of associations and aggregations may have a multiplicity according to the following:

  • No multiplicity (exactly one)
  • * (zero or more)
  • 0,1 (zero or one)
  • 1..* (one or more)
  • 1..3,6,10..* (several intervals: 1, 2, 3, 6, 10 or more)

Objects

Besides class definitions, object models may also contain objects (instances) and their relations. The relation that exists between objects are links, which corresponds to associations for classes. The object symbol has one field containing the object name and a reference to the class ("name:class"), and an attribute field where constant or default values can be assigned to the object attributes. See Figure 11.

Figure 11 : Objects related by links


State Chart Notation

The state chart notation used in the SDL suite is a subset of the notations used in OMT (Object Modeling Technique) and UML (Unified Modeling Language).

A state chart model is suitable to use together with class and object models. The descriptions of the behavior of a class in a class diagram is collected into a state chart which describes the dynamic view of the model by means of states and transitions between states.

State

A state symbol describes the name of the class, state variables, and internal activities. State variables highlight attributes of the class which is used or in some way affected by the behavior described in the state chart. Internal activities are taking place upon entering the state, while in the state and when exiting the state. Activities are described by specifying events and associated actions. Figure 12 shows a collapsed state and a state with state variables and events.

Figure 12 : A collapsed state symbol and a state symbol
with state variables and events

Transition

A transition symbol is an arrow which typically connects two state symbols. A transition is triggered by an event together with a condition, and a transition then executes an action; see Figure 13.

Figure 13 : The transition from state1 to state2 is triggered by the event
my_event and the condition that attr1 is less than attr2

Start and Termination Symbol

The start symbol denotes the starting point of a state machine described by a state chart and the termination symbol denotes the point of termination of a state machine. Figure 14 shows a simple state machine, describing the behavior of a door, including start and termination symbols.

Figure 14 : A simple state chart with a start symbol and a termination symbol

Substates

States may be refined into nested diagrams of sub-states, or hierarchical states. The state represents a simplification of more complex behavior expressed in the nested diagram.

Figure 15 : A state with substates


ASN.1 - Abstract Syntax Notation One

ASN.1 (ITU-T Recommendation X.680-683) is a generic notation standardized by ISO and ITU for the specification of data types and values. The general idea behind ASN.1 is to describe data type information independent of the transfer format.

The original use of ASN.1 has been the information description in high-level protocols like FTAM, CMIP, MHS, DS, VT, etc. Today it is also frequently used in numerous other telecommunication protocols and applications.

ASN.1 data types and values can be defined in modules that can be used in TTCN and in SDL. This makes it possible to use the data types of an application both in the SDL specification and in the TTCN test suite, which assures consistency between the information transferred in the system specification and the test specification.


The TTCN Notation

As the use of standards within the world of Information Technology and Telecommunications has increased tremendously during the last decade, so has the need for methods and tools that support the verification and validation of both the standards and their actual implementations.

This need has been addressed by ISO and ITU in the "Framework and Methodology for Conformance Testing of Implementations of OSI and ITU Protocols". The framework has for some time had the status of an international standard as ISO/IEC 9646 (or X.290).

The standard introduces the concept of abstract test suites (consisting of abstract test cases). This is a description of a set of tests that should be executed for a system. The tests should be described using a black-box model, i.e. only control and observation using the available interfaces.

The abstract tests are to be described using a formal language rather than using informal natural language. As part of the standard the language TTCN is defined in order to describe the abstract tests.

TTCN - Tree and Tabular Combined Notation

With TTCN a test suite is specified. This is a collection of various test cases together with all the declarations and components it needs.

Each test case is described as an event tree. In this tree behaviors like "First we send A, then either B or C will be received, if it was B we will send D..." are described. The new version of TTCN allows several event trees to be running concurrently.

TTCN is abstract in the sense of being independent of the actual test systems. This means that a test suite in TTCN for one application (protocol, system...) can be used in any test environment for that application.

The use of TTCN has increased tremendously during the last years. This has been augmented by the significant amount of TTCN test suites released by various standardization bodies. TTCN is however not only used in standardization work. The language is very suitable for all kinds of functional testing for communicating systems. This has led to a wide usage also within the industry.

The specifications of the messages being sent and received can be defined using either the built-in form of TTCN or by using ASN.1.


Tool Support

Telelogic has been a firm supporter of SDL for a long time. We co-operate with ITU in the on-going work of improving the language and with ETSI in using SDL for defining protocol standards. We initiate and participate in international research programs on how to use the language in different application areas (such as the European Community programs RACE, ESPRIT and EUREKA). Our experience and know-how in these areas is put to practice when we develop software engineering tools that support the languages.

A tool for a specification language must be able to create, maintain, and analyze a specification. It is also fundamental that the tool can simulate, validate and generate application code to other high level languages.

The SDL suite can do all of this.


References

  1. ITU Recommendation Z.100:
    Specification and Description Language (SDL)
    1994, ITU, General Secretariat - Sales Section,
    Places des Nations, CH-1211 Geneva 20
  2. Annex A, B, C1, C2 D, E, F1, F2 and F3 to Z.100, as above
  3. ITU Recommendation Z.120:
    Message Sequence Charts (MSC)
    1992, ITU General Secretariat - Sales Section
    Place des Nations, CH-1211 Geneva 20
  4. Jan Ellsberger, Dieter Hogrefe, Amardeo Sarma:
    SDL - Formal Object-oriented Language for Communicating Systems.
    Prentice Hall Europe (1997)
    ISBN 0-13-632886-5
  5. A. Olsen, O. Færgemand, B. Møller-Pedersen, R. Reed, J.R.W. Smith:
    Systems Engineering Using SDL-92.
    Elsevier (1994)
    ISBN 0-444-89872-7
  6. Ferenc Belina, Dieter Hogrefe, Amardeo Sarma:
    SDL with Applications from Protocol Specification.
    Prentice Hall International (UK) Ltd. (1991)
    ISBN 0-13-785890-6
  7. Belina, Hogrefe:
    The CCITT Specification and Description Language SDL
    Computer Networks and ISDN System.
    North-Holland, Amsterdam (1988/1989)
  8. Bræk, Gorman, Haugen, Melby, Møller-Pedersen, Sanders:
    TIMe - The Integrated Method
    SINTEF 1998
    http://www.sintef.no/time
  9. Færgemand, Marques (editors):
    SDL 89: The language at work.
    Proceedings of the Fourth SDL Forum,
    North Holland, Amsterdam (1989)
  10. Færgemand, Reed (editors):
    SDL 91: Evolving Methods.
    Proceedings of the Fifth SDL Forum,
    North-Holland, Amsterdam (1991)
  11. Færgemand, Sarma (editors):
    SDL 93: Using Objects.
    Proceedings of the Sixth SDL Forum,
    North-Holland, Amsterdam (1993)
  12. Haugen, Møller-Pedersen:
    Tutorial on object-oriented SDL.
    SISU Project Report 91002
    Norwegian Computer Center
    PO Box 114, N-0314 Oslo 3, Norway
  13. Behcet Sarikaya:
    Principles of Protocol Engineering and Conformance Testing.
    Simon & Schuster International (1992)
  14. Sarraco, Smith, Reed:
    Telecommunications system engineering using SDL.
    North-Holland, Amsterdam (1989)
  15. K.J. Turner (editor):
    Using Formal Description Techniques -
    An Introduction to Estelle, LOTOS and SDL.
    John Wiley & Sons (1992)
  16. ITU Recommendation X.680-683
    Abstract Syntax Notation One (ASN.1)
    1994, ITU, General Secretariat- Sales Section,
    Places des Nations, CH-1211 Geneva 20
  17. ITU Recommendation Z.105
    SDL Combined with ASN.1 (SDL/ASN.1)
    1995, ITU, General Secretariat- Sales Section,
    Places des Nations, CH-1211 Geneva 20


2 Introduction to the SDL Suite

This chapter contains a brief introduction to the SDL suite and to the functionality of its components.

After reading this chapter, you may want to familiarize yourself with the SDL suite: starting the tools, proceeding with a small example, or reading about what is new in this release in comparison to earlier versions. You are then recommended to study the following chapters:

  • For a beginner's tutorial on the SDL suite: 3 Tutorial: The Editors and the Analyzer, in this volume.
  • For news compared to previous versions: Release Notes.


About the SDL Suite

Telelogic

The SDL suite is developed and marketed by Telelogic. Our company has been a firm supporter of the SDL, MSC and UML languages for a long time. We cooperate with ITU and OMG in the ongoing work of improving the languages and with ETSI in defining international standards in the field of communication protocols.

We initiate and participate in international research programs on how to use the languages in different application areas (such as the European Community programs RACE, ESPRIT and EUREKA, as well as the Swedish national IT program).

Our experience and know-how in these areas is put to practice when we develop software engineering tools that support the languages. Our family of tools is known as Telelogic Tau.

The SDL Suite

Tools for design and specification languages must be able to create, maintain, and verify a specification with respect to the language syntax and semantics. It is also fundamental that the tools can simulate, validate and generate application code to other high level languages.

To be able to perform a complete development cycle, the tool should support early analysis phases, and the move from object-oriented analysis to SDL design.

The tool should be able to export and import information from other SDL tools. Major documentation standards or de-facto standards should be supported.

The tool should provide an intuitive and consistent graphical user interface which reduces learning time and makes it easy to work with the tool. Besides the graphical user interface, a batch facility should allow to process a large amount of information without user interaction.

A powerful, context-sensitive Help facility should be provided, freeing you from time-consuming browsing through user documentation in search for the topic of interest.

The SDL suite can do all of this, and much more.

Telelogic
http://www.telelogic.com


Overview of the SDL Suite

Architecture

The SDL suite is a member of the Telelogic Tau family, which also includes the TTCN suite and the UML suite.

Telelogic Tau consist of a number of separate tools that process information. The tools are integrated using a selective broadcast integration mechanism, making it possible to design a highly integrated system from separate tools. This approach also makes it possible to add new tools without creating any conflicts with the existing tools. In addition, the integration between two separate tools can be easily enhanced, and tools can communicate with each other over a network.

The interface that ties the tools in Telelogic Tau is called The PostMaster . The parts of the Postmaster interface that are of interest for the users, are documented so that you can read about how to integrate your own tools with Telelogic Tau.

Starting the SDL Suite tools

The SDL suite components are normally started by using the sdt start script in the bin directory of the Telelogic Tau installation. This script can take a number of options:

  • sdt -reuse
    If there is a running Telelogic Tau session, then the Organizer from that session is displayed. If there is no running Telelogic Tau session, then a new session is started.
  • sdt <system file>
    Starts the SDL suite components and loads the specified system file.
  • sdt <diagram file>
    Starts the SDL suite components and loads the specified diagram file in an editor.
  • sdt <archive file> [ <unpack directory> ]
    Starts the SDL suite components, unpacks the specified archive file, and loads any system file found in the archive file. The archive file is unpacked in the specified unpack directory. If no directory is specified, then the Organizer will display a dialog, asking for a directory to unpack in.
  • On UNIX,sdt -fg
  • On Windows, sdtfg
    Normally, the sdt start script immediately gives the user a new command line prompt for other commands. When sdt -fg or sdtfg is used, the start script will wait until the SDL suite is closed down before giving the user a new command line prompt.
  • sdt -noclients
    This variant starts the Postmaster without starting any clients/applications such as the Organizer. Later, Postmaster clients can be started and attached to the postmaster. To attach to an existing postmaster, start a client with -post. Read more about this in "Run-Time Considerations" .
  • sdt -grdiff [ -notmoved ] v1.ssy v2.ssy [ [ -original o.ssy ] -mergeto r.ssy ]
    Starts the SDL suite components and immediately invokes the Compare Diagrams operation (see "Compare Diagrams" , comparing the SDL diagram files v1.ssy and v2.ssy. The use of the -notmoved option corresponds to setting the option Ignore moved or resized objects to off. (Note that if you use the -n option on UNIX it will be processed by the X window system) Normally this means that moved and resized symbols will not be detected as being different. When the operation is finished, the SDL suite is closed down. If the -mergeto option is used, the Merge Diagrams operation is used instead. (See "Merge Diagrams" and the merge result diagram is saved in r.ssy. If the -original option is used as well, then the merge operation tries to auto-merge differences using the o.ssy file as a guide for deciding how to merge v1.ssy and v2.ssy. o.ssy should point out an original diagram file version that both v1.ssy and v2.ssy are derived from. When using -grdiff to start a merge operation from another tool (such as a configuration management tool), combine -grdiff with -fg to have the other tool wait with processing the merge result file until after the merge operation is finished.
  • sdt -sdtdiff v1.sdt v2.sdt [ -mergeto r.sdt ]
    Starts the SDL suite components and immediately invokes the Compare System operation (see "Compare System" , comparing the system files v1.sdt and v2.sdt. When the operation is finished, the SDL suite is closed down. If the -mergeto option is used, the user will be prompted to save the merge result when the operation is finished, and r.sdt is used as a proposed file name.

Batch Facilities

The Batch Facilities are commands that you type from the OS prompt. These facilities take advantage of the Postmaster and pass messages to the tools, ordering the individual tools to process information as required. The batch facilities support the following operations:

  • Printing (to file or to printer)
  • Analyzing (typically syntactic and semantic check of an SDL system)
  • Making (for instance building an application for target environment)
  • Comparing SDL diagrams (with a textual report)

Licensing Mechanism

The software license server controls the licensing of the tools included in Telelogic Tau. This is performed through a floating license mechanism based on a third party software, FLEXlmTM 1. The current license numbers along with a key are stored on a text file, which is distributed at installation of the software. This provides a flexible way of upgrading licences and adding new license agreements, as well as allowing you to keep track of the actual usage of the tools you have purchased.

FLEXlm supports multiple tools (even from different tool manufacturers) sharing the same license server, so Telelogic should not cause any problems when installing it into your computer environment.

For increased flexibility in the use of licenses and to prevent started but unused tools from holding licenses, an optional timeout feature can be enabled. This will automatically release licenses when a user has been idle during a selectable interval.

For more information on license mechanisms, see A Primer on Licensing.

Common Telelogic Tau Tools

The SDL suite shares a set of tools common to Telelogic Tau:

  • The Organizer features a graphical view of all diagrams and documents making up a system. This may include SDL hierarchies, Message Sequence Charts, Object Model diagrams, State Charts, High-level MSCs, TTCN documents and text documents. The view may be freely organized into chapters and modules according to your preference.
    Furthermore, the Organizer manages the other tools in Telelogic Tau, taking advantage of their respective functionality when needed and thus providing the feeling of a truly integrated tool set.
  • The Link Manager and The Entity Dictionary maintains and visualizes Implinks and Endpoints. Implinks (short for implementation links) are used to trace the implementation and design decisions for concepts and objects between different phases in the development process. The link endpoints are texts and objects created in the editors described below. The Link Manager and the Entity Dictionary can be started from all of the editors.
  • The Preference Manager allows you to set up or change the behavior of the Telelogic Tau tools by customizing the values of preference parameters. It is possible to specify whether a customized behavior should be project-wide or even company-wide, or if an individual user should be allowed to customize some behavior.
  • When you are Printing Documents and Diagrams, there are various options that allow you to customize the printouts so that they fit in your documentation environment. Except for when you print TTCN documents, it is possible to generate, PostScript, encapsulated PostScript, FrameMakerTM, InterleafTM and web files. In Windows, you can also print to any printer you have set up in Microsoft Windows.
  • The on-line help provides access to help on tools, windows, dialogs and commands. The on-line help is in HTML-format, featuring hypertext links and navigation support. The PostScript files that were used when printing this manual are also enclosed in the distribution. You are free to produce additional hard-printed copies of the manual pages that are of interest.
  • The PostMaster implements the integration mechanism that ties the tools together. The public parts of the PostMaster interface are documented, allowing you to integrate your own tools with Telelogic Tau tools and the information they manage.

The SDL Suite Graphical Tools

The SDL suite comprises the following graphical tools:

  • The diagram editors are used for creating, editing and printing Object Model, State Charts, Message Sequence Charts and High-level Message Sequence Charts diagrams.
    The OM Editor uses the full graphical notations of OMT/UML. It keeps track of all class and object definitions with the same name in a scope of OM diagrams, and supports the merging of these definitions for maintaining a combined view of a class. The SC and HMSC editors work in a similar way.
    The MSC Editor uses the graphical notation defined in the standard Z.120. Also, it can serve as a powerful graphical trace tool when you simulate and validate a system specified in SDL. MSCs can also be verified for consistency with an SDL system when you use the SDL Validator.
  • The SDL Editor is used for creating, editing and printing specifications and descriptions using the graphical SDL notation defined in the standard Z.100. The SDL Editor also performs various syntax checks at editing time.
    • Advanced functions include a context-sensitive grammar help and signal dictionary. When you edit an SDL diagram, the signal dictionary is automatically updated to contain all SDL signals that you add to a system and provides immediate access to them.
    • The SDL Editor can also display Overview Diagrams of the SDL system, where the diagrams are displayed in a nested fashion.
  • The SDL Type Viewer visualizes the impact of the inheritance and specialization mechanisms in your SDL-92 system. The Type Viewer produces a graphical tree that is of great assistance to understand and take full advantage of the SDL types2 that you have defined in an SDL system.
  • The SDL Index Viewer presents listings of definitions and cross-references in a clear and easy-to-understand graphical notation. The Index Viewer is provided with filtering and navigation functions, with a trace-back to the source SDL or MSC diagrams.
  • The SDL Coverage Viewer is a test coverage and profiling tool that displays the results of a simulation or validation as a graphical transition or symbol tree. The tool can present an overview of the system, coverage or a detailed view on a part of the system.

Other SDL Suite Tools and Back-End Facilities

The following additional tools and facilities are available:

  • The Text Editor is used for creating, editing and printing ASCII text documents. The text documents can be textual requirements, use cases and other textual documentation used in the development process. The Text Editor can also be used for writing ASN.1 or C code to be linked to the SDL system.
  • The ADT Library (library of Abstract Data Types) features a number of general ADTs that provide the basic services that are often needed when you design an SDL system. The ADT library is distributed in source code so you can tailor the ADTs to fit your specific requirements, if needed.
  • The SDL Analyzer performs several functions. It performs syntactic and semantic analysis of your SDL descriptions, generates error reports and warnings in appropriate cases, and has the ability to produce information about definitions and cross references in an SDL system. The Analyzer also converts SDL information from the Graphical Representation (SDL/GR) to the textual Phrase Representation (SDL/PR). The reverse conversion is also possible, allowing you for instance to import PR files from other tools supporting SDL.
  • The Cadvanced/Cbasic SDL to C Compiler transforms your SDL system into a number of C source files that are compiled and linked with an SDL suite run-time library. The C code can be used for a number of purposes, depending on what libraries are available in your configuration (see below). The SDL to C Compiler is available in a Cbasic (for simulation and validation purposes), and a Cadvanced (for building any kind of application) version.
  • The SDL Simulator library allows you to make an executable program, a simulator, which helps you to understand and debug the behavior of a system specification. The simulator can be controlled from a graphical user interface (SimUI).
    You can choose to focus on the external view of a system specification, where you are interested in the signal interface, or on the internal behavior of a system specification. The execution of a simulator can be traced in a graphical mode in the source SDL diagrams and can be logged graphically in terms of Message Sequence Charts. Target simulation is also supported.
  • The SDL Validator library allows you to make a validator, an advanced "self-exploring" simulator that may be used for finding errors and inconsistencies in an SDL system and for verifying that a system is consistent with a Message Sequence Chart. The validator can be controlled from a graphical user interface (ValUI).
  • The Performance Library allows you to create a performance model of your SDL system that you run on your host computer. The library is optimized with respect to performance, so that a large amount of statistical data can be produced during a reasonable execution time.
  • The Cadvanced SDL to C Compiler can be used for Building an Application for both host and target environments. Predefined Application libraries are available for specific host environments. The Master Library is the SDL suite run-time library in source code format, which can be customized to fit different needs and operating systems.
    Integration with Operating Systems supports most of the commercially available real-time operating systems. You can also build applications where the runtime library schedules the system and sets the real-time pace.
  • The Cmicro SDL to C Compiler is designed to meet the needs of small to mid-range microcomputer controlled applications. It translates an SDL system into optimized and compact C code with highly reduced memory requirements. The Cmicro SDL to C Compiler is part of the Cmicro Package which in addition consists of the Cmicro Library and the SDL Target Tester. The Cmicro Package can be ordered separately.
    • The Cmicro Library is the "virtual SDL machine" needed to build an executable from the generated Cmicro Code.
    • The SDL Target Tester allows testing and debugging of the generated SDL system while it is running on a target. A prerequisite is a communications link to a host system. The SDL Target Tester is an optional part of the Cmicro Package.
  • TTCN Test Suite Generation is provided by two features: TTCN Link and Autolink. They provide a means to check the consistency between an SDL system managed by the SDL suite and a test specification, expressed in TTCN3 managed by the TTCN suite. TTCN Link generates the declarations of the test specification automatically. In the TTCN suite, there is direct access to the SDL system specification and you can interactively build test cases. Autolink is a feature of the Validator, and can generate entire test suites from an SDL specification.
1

FLEXlm stands for Flexible License Manager.

2

The SDL term type corresponds to the term class, used in many OO notations

3

TTCN stands for Tree and Tabular Combined Notation. It is an ISO standard that is used to describe a test specification.


Information Management

In order to properly use Telelogic Tau, you need to understand the basics for how the information is organized.

SDL Diagrams

The SDL suite primarily handles SDL information in the graphical representation, SDL/GR. The major advantage that follows this approach is that you are free to apply any graphical style guide to your diagrams since the SDL suite lets you position symbols and shape lines the way you like.

Each SDL diagram consists of a number of diagram pages. An SDL diagram page may contain references to other SDL diagrams. This allows you to build a hierarchical structure which adheres to the SDL syntax rules. See Figure 16.

Figure 16 : Organization of SDL information

Each diagram stored on its own individual file. An SDL structure is built up from a number of these SDL files. These files are logically tied together by the SDL suite components, in order to constitute a coherent SDL structure. This process is managed by the Organizer. The SDL suite can manage several separate SDL structures at the same time.

You may also include SDL/PR files into an SDL/GR structure. Transformation of SDL/GR to SDL/PR and vice versa is supported.

MSC Diagrams

Message Sequence Charts are mainly handled in the graphical representation, MSC/GR.

In contrast to SDL diagrams, MSCs are not paginated and cannot build a hierarchical structure. However, an MSC diagram can reference other MSCs (or HMSCs, see below), but without implying any structure between them.

MSC diagrams may be managed as entities of their own. The Organizer also supports including MSCs in an SDL structure using the concept of associated documents.

Telelogic Tau allows reading and writing of MSCs expressed in the textual form, MSC/PR. Both the instance-oriented and event-oriented forms are supported, according to the recommendation.

High-Level MSC Diagrams

In contrast to "plain" MSCs, High-level MSCs (HMSCs) are paginated, but they cannot build a hierarchical structure visible in the Organizer. However, an HMSC diagram can reference other HMSCs or MSCs, but without implying any structure between them.

Textual SDL and MSC Formats

Telelogic Tau has the ability to read and write SDL and MSC textual files, SDL/PR and MSC/PR. The primary purpose is to enable importing and exporting of SDL and MSC information, rather than to provide an alternative storage format, since the layout and exact appearance of a diagram is lost when stored in PR format and read back again.

Telelogic Tau also use the PR formats as temporary storage formats when processing information.

SDL/GR diagrams can be converted to and from CIF (Common Interchange Format) files, by using CIF converters supplied with the SDL suite. CIF is an extension to SDL/PR that also stores the graphical layout information. However, CIF files cannot be managed directly by the SDL suite.

Object Model Diagrams

Object Model (OM) diagrams may be managed as entities of their own, or grouped together using the concept of modules in the Organizer.

OM diagrams are paginated, but does not contain any structure information. However, a scope concept is used to allow the same object class to be defined in more than one OM page or diagram. All diagrams and pages within the scope are considered when the complete definition of a class is needed. OM diagram belong to the same scope if they are managed in the same module in the Organizer.

State Chart Diagrams

State Chart (SC) diagrams are paginated, but does not contain any structure information, nor any references to other diagrams. They are always managed as entities of their own.

Text Documents

Telelogic Tau handles text documents in the form of plain ASCII files. Telelogic Tau uses the file extension of text files to determine the type of text file. Telelogic Tau recognizes text files as C header, ASN.1 or as plain text files.

Text documents are managed as entities of their own, but C header and ASN.1 specifications can be linked to the rest of the system by using the concept of dependency links. In this way, these text documents can be analyzed and translated to SDL/PR format.

A text document can also be a build script, containing commands to control the analyze and code generation process in detail.

The System File

Once Telelogic Tau is up and running, you may work on individual documents, regarding them as individual objects of their own. However, this requires that you keep track of each individual file.

When the amount of documents increases, this process tends to become rather complicated, in particular when introducing inheritance and specialization between SDL diagrams, and dependency links between different document types.

To cope with this problem and as a means to ensure the consistency of a document structure, the system file is introduced. The system file is managed by the Organizer.

Document Structure

The system file holds the information about the SDL structure and all other documents included in a system. It also keeps track of the file bindings, i.e. what file a particular document is stored on, and the dependency links between the documents. When working on your documents, the Organizer keeps track of the changes you apply and updates the system file accordingly.

A graphical approach is used, in order to display the contents of the system file in the Organizer. Documents may be freely organized into chapters and modules (within chapters) to keep related documents together.

Connections between documents in different chapters, modules and SDL structures can be made in the form of associations and dependency links.

Options

In addition to the properties mentioned above, the system file may store information about what options you have set up for the document structure that is managed by the system file. Typically, analysis and code generation options are stored in the system file.

The Link File

The Link Manager keeps track of all link endpoints and implementation links in the system. This link database is stored on a separate link file, which is referenced from the system file.

Control Unit Files

Control unit files facilitate multiuser support when you work with an SDL system. They contain structure information for a subset of a document system and are suitable for configuration management (revision control). If control unit files exist, they are referenced from the system file.

Source Management

Since Telelogic Tau operates on files, you may use any revision handling system for checking out work copies of your SDL diagram files to your work directory (this task needs to be performed outside Telelogic Tau).

Telelogic Tau may also be configured to manage multiple versions of your source documents, by binding a document to any suitable file in your file system.

Telelogic Tau provides mechanisms for an easy rebinding of documents. These file binding mechanisms allow you to keep track of multiple versions of your source documents with a minimum of effort.

Target Management

Virtually all of the output information that is produced with Telelogic Tau consists of files, most of them use a text-based format (for instance SDL/PR files and C files).

You may specify default locations for files that are generated with Telelogic Tau. Also, you may specify the level of granularity, allowing you to generate multiple files or one file only.

Furthermore, the SDL suite features an SDL-Make mechanism that minimizes the turnaround time, by computing the passes the tool must run in response to a modification of a source diagram.


PCs and Workstations

User Interface

On UNIX workstations, Telelogic Tau is implemented as X Window applications, using the Motif widget set. On PCs, Telelogic Tau is designed as Microsoft Windows applications (Windows 95, Windows 98, Windows NT 4.0 or Windows 2000). At present, some features are not available on the PC platform.

Since the SDL suite is supported on different systems, there may be slight differences in the appearance of the tools between environments. However, the functionality is identical as long as the underlying system and the OS allow it.

All Telelogic Tau graphical applications follow the same style guide, described in User Interface and Basic Operations.

Supported UNIX Systems

Full compatibility between the SDL suite on PCs and the SDL suite on UNIX workstations ensures that future upgrading of your computers towards workstations is possible, and allows heterogeneous network solutions with, for instance, PCs connected to a UNIX based file server.

On workstation environments, the following architectures and operating systems are supported:

  • Sun SPARCstation (Solaris)
  • HP 9000/700 and 800 series (HP-UX)

For more information about the supported platforms, see Platforms and Products.


3 Tutorial: The Editors and the Analyzer

The SDL suite products are used for designing and specifying systems, in particular real-time systems. The SDL suite supports the Specification and Description Language (SDL) as recommended by ITU (the Z.100 recommendation). The SDL suite also supports the definition of Message Sequence Charts (MSCs), as well as parts of the Unified Modeling Language (UML) notation. For full support of the UML language you should rather use the Telelogic Tau UML Suite.

This tutorial assumes that you are already familiar with SDL and have some brief notions about Message Sequence Charts. UML notation is described in the UML Suite documentation.

We will demonstrate, by using a simple SDL system as example, the basic editing and analysis functionality that is available. You will practice various "hands-on" exercises that will get you more familiar with the SDL Editor and the MSC Editor, as well as the SDL Analyzer.

In order to learn how to use these tools, read through this entire chapter. As you read, you should perform the exercises on your computer system as they are described.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the user interface and the essential editing functionality in the SDL suite. This tutorial is designed as a guided tour through the SDL suite, where a number of hands-on exercises should be performed on your computer as you read this chapter.

We have on purpose selected a simple example that should be easy to understand. It is assumed that you have a basic knowledge about SDL -- this chapter is not a tutorial on SDL.

This tutorial addresses primarily persons with no or little experience of the SDL suite. You may also find it useful if you have experience of earlier versions of the SDL suite and want to learn the new features and user interface concepts in Telelogic Tau 4.4.

Once you have completed the exercises in this tutorial, you may want to continue with the tutorials that are presented in:

  • 4 Tutorial: The SDL Simulator,
  • 5 Tutorial: The SDL Validator, and
  • 6 Tutorial: Applying SDL-92 to the DemonGame.

Note: Platform differences

It is possible to run the tutorials on UNIX as well as on Windows platforms. Should there be any differences between the platforms, this is indicated in the text with the markers "on UNIX", "Windows only", etc. This is also indicated in the platform-specific screen shots.
When such platform indicators are found, please pay attention only to the instructions and screen shots that are valid for your platform.


The Demon Game

The example that has been chosen in this tutorial is a simplified version of the "Demon game", which is a well known example in the SDL community, since it is, among other things, used as example in the SDL recommendation.

The SDL definition of the Demon game may be found in SDL/GR form later in this chapter (see "Appendix A: The Definition of the SDL-88 DemonGame" ). The definition of the behavior of the Demon game is probably not the simplest way of describing the game, but it has been selected since it is good for demonstrating the facilities of simulation and validation.

Behavior of the Demon Game

Seen from the environment, the behavior of the system is as follows. The system accepts four different types of signals, Newgame, Endgame, Probe, and Result, where the first two signals are used to start and end a game. Only one game at a time can be played, that is, Newgame signals will be ignored when a game is in progress and Endgame will be ignored if there is no game in progress.

The game in itself is very simple. A "demon," which in the system is represented by the process Demon, changes the status of the system every now and then between winning and losing. This is represented by the states Winning and Losing in the process Game. The user is to guess when the status is winning. If the user probes (outputs the signal Probe), when the status is winning, he wins one point. If the user probes when the status is losing he loses one point. The system responds to a Probe signal by either a Win or a Lose signal. To see the current score the user can issue a Result signal, which will be answered by a Score signal containing an integer parameter giving the current score.


Starting the SDL suite

Some Preparatory Work

This tutorial assumes that the SDL suite has been installed correctly, according to the instructions in the Installation Guide.

Note: Installation directory

On UNIX, the Telelogic Tau installation directory is pointed out by the environment variable $telelogic. If this variable is not set in your UNIX environment, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for instructions on how to set this variable correctly.
In Windows, the Telelogic Tau installation directory is assumed to be C:\Telelogic\SDL_TTCN_Suite4.4 throughout this tutorial. If you cannot find this directory on your PC, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for the correct path to the installation directory.

The directory $telelogic/sdt/examples/demongame (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame (in Windows), is created during installation and is the directory that contains the complete example, that you may look at whenever you feel insecure or want to "shortcut" an exercise.

In order not to modify these completed example files, you should create a dedicated directory for the purpose of this tutorial.

On UNIX, follow this instruction:

  1. Create a new subdirectory in your home directory:
mkdir ~/demongame
In the remainder of this tutorial, we will assume this name for your personal tutorial directory.

In Windows, follow these instructions:

  1. Create a local directory
    C:\Telelogic\SDL_TTCN_Suite4.4\work\demongame on your PC. In the remainder of this tutorial, we will assume this name for your personal tutorial directory.

Note: Do not use space characters in Windows

In Windows, Telelogic Tau does not support file or directory names that contain space characters. Make sure you do not use such names.

Starting the SDL suite

On UNIX, to start the SDL suite environment:

  1. Change directory to your demongame directory:
cd ~/demongame

  2. Now, type:
sdt

Note:

If the command sdt is not found, you first have to set up your $path variable correctly. Consult your system manager or the person that is responsible for the SDL suite environment at your site.

In Windows, to start the SDL suite in a manner suitable for this tutorial you should create and use a shortcut icon:

  1. Locate the executable SDL suite file sdt.exe (or just sdt) in C:\Telelogic\SDL_TTCN_Suite4.4\bin\wini386. (See the note "Installation directory" if you cannot find this directory.)
  2. Create a shortcut icon to this file on the Windows desktop.
  3. From the new icon's popup menu, select Properties. In the dialog, select the Shortcut tab at the top.
  4. In the Start in field, enter the path to your new directory, i.e. C:\Telelogic\SDL_TTCN_Suite4.4\work\demongame
  5. Click OK to close the dialog.
  6. Double-click the shortcut icon.

The Organizer Window

When you have started the SDL suite, the Organizer window is displayed (see Figure 17 and Figure 18). The Organizer is the main tool from which you have access to the tools in the Telelogic Tau environment.

The Organizer also displays the Welcome window, where you may read the licensing agreement for Telelogic Tau. The window is always placed on top of the Organizer window and disappears as soon as you perform any action in the Organizer (you may also click the Continue button).

You are now ready to start working.

Figure 17 : The Organizer window (on UNIX)

Figure 18 : The Organizer window (in Windows)

Note: Screen shots

As you can see, screen shots of the Organizer window are shown for each platform, UNIX and Windows. From now on, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see on your computer screen.
Only if a screen shot differs in an important aspect between the platforms will two separate screen shots be shown.


Preferences

What You Will Learn

  • To set up and save preferences
  • The basics of the graphical user interface in the SDL suite, operated from the mouse and the keyboard. You will learn to:
    • Use graphical lists
    • Use pull-down menus
    • Use pop up menus
    • Use quick buttons
    • Use the status bar
    • Use option menus
    • Use text fields
    • Use slide bars
    • Use keyboard accelerators

What Are Preferences for?

Before starting creating your first SDL diagram, you should set up some preferences to match your computer environment. These preferences affect the default behavior of the Telelogic Tau tools and should be adjusted to convenient values in order to have Telelogic Tau function properly (most options in Telelogic Tau may be set as preferences). When Telelogic Tau is installed, the factory settings are used as preference settings. Your system manager may have already prepared the environment for you; good advice is to check this anyway.

At least the following should be checked:

  • The help preferences
  • The printer preferences
  • The drawing area size
  • The platform mode.

Displaying and Changing Preferences

To view and possibly change the preferences:

  1. From the Organizer's Tools menu, select the Preference Manager command. The Preference Manager window is displayed:

Figure 19 : The Preference Manager window

Your next task will be to check and, if required, modify a few preferences.

Help Preferences

Telelogic Tau supports a context-sensitive online help facility that you may use at any moment to request help on a window, on a command, on a dialog etc.

The online help is in HTML-format and you may use Netscape Navigator or Internet Explorer as help viewer. You can change the help viewer by setting a preference.

To set up the Help preferences:

  1. Locate the icon titled Help and double-click it.
    • You can also right-click the icon and select Expand from the pop up menu.
      This will expand the list structure below and make the Help preferences visible.
  2. Locate the preference HelpViewer.
    To the right of the preference icon you can see the current value, the currently saved value and an explanatory text.
  3. Change the preference by selecting the HelpViewer icon and then selecting a new viewer in the option menu at the bottom of the window. (You may need to ask your system manager if you do not know what viewer to use). The icon will turn gray, which means that the preference has been changed and needs to be saved.
  4. Depending on your choice of viewer, you should now check that the command Telelogic Tau uses when starting the help viewer is correct, according to your computer environment:
    • Locate and select the icon titled NetscapeCommand or InternetExplorerCommand. The current value is shown to the right. If it is not correct, change the text in the text field at the bottom of the window. (You may need to ask your system manager about the correct value.)
  5. Collapse the Help icon by double-clicking it.

You have now learned how to work with graphical lists in Telelogic Tau. Graphical lists are used extensively throughout the tools; they may hold as many levels as required (the Preference Manager uses three levels of indentation, as seen on the screen).

Some tools also support a vertical tree as an alternative to a graphical list. The functionality is identical, only the presentation differs. You will acquaintance yourself with a graphical tree later in this tutorial.

Setting the Default Printer

In this tutorial, you will learn how to print diagrams. Before you start printing from Telelogic Tau, you should check and, if needed, set up your print preferences in accordance to your computer environment.

To set up the Print preferences:

  1. Locate the Print icon. Expand it.
  2. Locate the PrinterCommand preference. Adjust it to an adequate value (if required, ask your system manager). You may specify any suitable operating system command, for instance sending the resulting printouts to a printer queue (the command lpr) or previewing a PostScript file in a pre-viewer such as Ghostview1.
  3. Locate the PaperFormat preference. Telelogic Tau supports a number of predefined paper sizes on the option menu (A4, A3, US Letter and US Legal). You may also specify an arbitrary UserDefined value, in which case you also need to specify the preferences UserDefinedWidth and UserDefinedHeight; these values are expressed in millimeters.
  4. Adjust, if required, the preferences MarginUpper, MarginLower, MarginLeft and MarginRight. These preferences govern how much space in millimeters will be reserved for the margins on the printed pages; you may use this space for including headers and footers in your printouts.
    • To adjust these preferences, select them and drag the slider for a coarse adjustment. Terminate by clicking left or right of the slide bar or on the arrows to adjust in smaller steps.
  5. Adjust, if required, the preference Landscape to on or off (this preference specifies the orientation, landscape or portrait).

Setting the Drawing Area Size

When editing SDL diagrams, the pages are assigned a predefined size. You should specify the default size to match the size of the printer pages and the printer margins that you defined in the previous exercise.

  1. Locate the SDL Editor icon (at the very top), expand it and inspect the preferences PageWidth and PageHeight.
  2. If required, adjust these preferences to suitable values.

Saving the Preferences

You should now save your preference settings for future Telelogic Tau sessions.

  1. Select the Save command from the File menu.
    • Alternatively, you may click the quick button for Save. Quick buttons are located in a tool bar which may be found immediately beneath the menu bar. Quick buttons are mouse accelerators for frequent commands and are available in all Telelogic Tau tools, not only in the Preference Manager.
    • You may "preview" the functionality that a quick button provides by pointing on the quick button; the status bar (situated at the bottom of the window) displays an explanatory text. If you let the mouse pointer rest on the quick button, a short "tool tip" text is also displayed just below the button.
    • Another possibility is to type the keyboard accelerator for the Save command, by pressing <Ctrl+S>. This is indicated immediately to the right of the menu choice Save.
  2. You will receive a warning that the preferences you have changed will not take effect until the individual tools are restarted (exited and started again). Just click OK to acknowledge this.
    Your preferences are now saved on file for the current (and for future) Telelogic Tau sessions.
  3. Close the Preferences window by selecting the Exit command from the File menu.

This concludes your Preference session. You may of course at any moment go back to the Preference Manager and adjust other preferences.

1

Ghostview: A user interface for ghostscript. 1992 Timothy O. Theisen.


Creating an SDL Structure

You are now ready to create your first SDL diagrams.

What You Will Learn

  • To customize the Organizer chapters
  • To create an SDL structure
  • To add a system root node
  • To create a system diagram
  • To add a page
  • To edit a system diagram
  • To save a diagram on file
  • To save a diagram structure on a system file
  • To work with dialogs (modal and modeless)
  • To work with tree structures

Customizing the Organizer Chapters

When the SDL suite is started, the Organizer displays two icons that symbolizes the system file and the source directory for your diagrams. The system file will be explained later. The source directory is where the SDL suite components will look for existing diagrams, and save newly created diagrams. (The source directory can of course be changed.)

The source directory should already be set to the directory that you started the SDL suite from (~/demongame (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\work\demongame (in Windows)).

By default, the Organizer also shows 5 areas in its window:

  • Analysis Model
  • Used Files
  • SDL System Structure
  • TTCN Test Specification
  • Other Documents.

These areas are known as chapters. You may use the chapters to hold a number of diagrams and documents; the actual use is a matter of personal taste and the default is to be regarded as a suggestion. As you will design a rather simple system, we suggest that you start by removing the chapters Analysis Model, Used Files and TTCN Test Specification.

To remove the chapters:

  1. Select the chapter Analysis Model.
  2. Select the menu choice Remove from the Edit menu. (You may also press the <Del> button on the keyboard.)
    • A dialog opens - confirm the removal by clicking the Remove button in the dialog.

Figure 20 : Confirming to remove a chapter

  3. Repeat the steps above for the chapters Used Files and TTCN Test Specification.

You may also rename the remaining two chapters:

  1. Select the chapter SDL System Structure.
  2. Select the Edit menu choice from the Edit menu. (You may also double-click the chapter.)
  3. In the dialog that opens, make sure the option Edit chapter symbol is selected and click the Edit button.

Figure 21 : Editing the chapter symbol

  4. Change the document name in the opened Edit dialog; for instance to My first SDL system. Do not change the document type indicated by the Organizer button and the option menu value Chapter.

Figure 22 : Naming the chapter

    • On UNIX, you may note that the cursor changes to the shape of a question mark as soon as it points on the parent Organizer window. This convention has been adopted to indicate that a dialog must be closed before any other operation is allowed to take place in the tool. Dialogs that need to be answered before proceeding further are called modal dialogs.
  5. Turn off (uncheck) the option Show in editor.
  6. Terminate by clicking the OK button.
    • If you like, also rename the Other Documents chapter. This chapter will be used later in this tutorial to hold diagrams that are not part of the SDL system but that you will want to keep track of.

Creating a System Diagram

Adding a Root Node

You will now create an SDL system, working in a top-down fashion:

  1. Make sure the chapter My first SDL system is selected.
  2. Select the Add New command from the Edit menu. The Add New dialog opens, prompting you to specify the name and type of diagram to add.

Figure 23 : Adding a new diagram

  3. Specify the New document type as SDL, and specify the SDL diagram type as System, as depicted above.
    • If the SDL diagram type shows something else than System and thus needs to be changed, click the option menu to adjust it.
  4. Specify the New document name as DemonGame (the default name, Untitled, disappears).
    • You may need to point and possibly click with the cursor on the text field to set the focus on it.
  5. Make sure the Show in editor button is turned off.
  6. Click the OK button.
    • The dialog disappears and the Organizer window is updated with a root node -- system DemonGame. Note that the diagram is identified as being [unconnected], meaning that there is no connection to a physical file.

Figure 24 : The new root node

Creating the System Diagram

You have so far created an Organizer diagram structure, consisting of one reference to an SDL system diagram (the referred diagram does however not yet exist).

Your next task is to create the system diagram:

  1. Select the DemonGame SDL system diagram icon. See Figure 24.
  2. From the Edit menu, select the menu choice Edit.
    • You may also press the right mouse button while pointing on the icon -- a popup menu appears -- select the sub-menu Edit and the menu choice Edit.
    • Another way to edit the diagram is to double-click the icon with the left mouse button.
  3. The Edit dialog opens, suggesting to create a new diagram and to Show the diagram in editor. (The dialog is very similar to the Add New dialog you just used.) Accept the suggestion by clicking OK.

Figure 25 : Prompting to create a new diagram

The SDL suite responds by displaying the SDL Editor window, showing the upper left corner of page 1 of the system diagram DemonGame.

The SDL Editor is the tool you use when editing the contents of the diagrams. The SDL Editor is also used for building the diagram structure that is displayed in the Organizer window.

Figure 26 : The SDL Editor window (on UNIX)

Your next task is to fill in the contents of the diagram. Figure 27 shows the appearance of the diagram when completed and printed on paper. As you can see, the diagram consists of two block reference symbols (GameBlock and DemonBlock), a channel conveying the signals between the blocks (C3) and two channels conveying the signals to and from the environment (C1 and C2). There is also a text symbol where the signal declarations may be found.

Figure 27 : The system diagram

The next pages describe in detail how you proceed to add the symbols and texts to the diagram.

Customizing the SDL Editor Window

Before you start editing, you may want to resize the editor window. You may also hide and show various sub-windows using the command Window Options from the View menu.

Figure 28 : The window options

  • You can hide and show the editor Tool bar, Status bar, printed Page breaks and the grid points.
  • You may also hide and show the text window and the symbol menu by clicking on the provided quick buttons. You will however need these windows soon.

Placing Block Reference Symbols

  1. Start editing the diagram by inserting the two block reference symbols (GameBlock and DemonBlock).
    To place a block reference symbol:
    • Click on the block symbol in the symbol menu. On UNIX, the symbol menu is located to the extreme right of the window. In Windows, the symbol menu is a separate window always placed on top of the SDL Editor window (if the two windows overlap).

      If you are not sure what symbol to use, point to or select a symbol in the symbol menu - its type is displayed in the Status Bar at the bottom of the SDL Editor window.
    • Move the mouse into the drawing area. The symbol "floats" and follows the mouse. Click to position the symbol where you want it to be. No overlap between symbols is allowed. (In case symbols are overlapping, an alert sound is emitted and you have to repeat the operation.)

Note: Aborting and undoing

  • To abort the insertion of a symbol after you have moved the mouse into the drawing area, just press <Esc>.
  • If you happen to perform a command or operation that you wish not had taken place, you should immediately select the Undo command from the Edit menu.

  2. Once you have placed the symbol, type the name of the block: GameBlock or DemonBlock
    • You can type in text directly at the cursor's position. The cursor position can be set by clicking on the text in the symbol. However, you cannot select (highlight) text directly in the symbol.
    • Before you have started text editing, the text cursor is not flashing. Pressing <Delete> at this stage deletes the whole selected symbol. Once text editing has started, the text cursor is flashing and pressing <Delete> only deletes a character.
    • You may see a red underlining appearing in the text, if you enter a name that has incorrect syntax according to SDL. This is the general way to indicate textual syntax errors in the SDL Editor.
    • When you edit text, you may also take advantage of the text window, which allows you select text by dragging. On UNIX, the text windows is located below the drawing area. In Windows, the text windows is a separate window always placed on top of the SDL Editor window (similar to the symbol menu).
    • No matter where you enter the text, the text is always displayed both in the symbol and in the text window.
    • You may also note that the Organizer diagram structure is automatically updated to reflect the insertion of the diagram reference symbol (once the symbol is de-selected).

Moving and Resizing Symbols

To move a block:

  • Select and drag the block with the mouse to the desired location. (Remember, no overlap with other symbols is allowed).

After you place the blocks where you want them, you may resize them:

  • Point to one of the symbol's corners, and drag. You must be fairly close to the corner. If this method fails, first select the symbol with a click and then repeat the procedure while pointing to a selection square.

Drawing Channels between Blocks

To draw a channel from block DemonBlock to block GameBlock:

  1. Select the DemonBlock symbol. A "handle" appears.

Figure 29 : A block symbol's "handle"

  2. Drag the handle (i.e. press the mouse button while pointing on the handle, and start moving the mouse while keeping the mouse button pressed).
  3. As soon as mouse motion has begun the editor responds by drawing a line; from now on you may release the button while moving the mouse.
  4. Move the mouse until it points to the GameBlock symbol. Click the mouse button; the channel is connected at both ends.
    • You may move the channel's endpoints individually by dragging them. Select the channel first if the endpoint is difficult to "hit" with the mouse.
    • You will notice a tiny selection square at the middle of some lines drawn in the SDL Editor. This can be used to create "breakpoints" on the line, thus dividing the line into different line segments. You will not use this feature in this tutorial.

The SDL Editor creates two text attributes associated to the channel. These text fields are displayed as selection rectangles which you use when entering the name of the channel and the list of the signals the channel is to convey. Initially, when the text attributes are empty, a red underlining is shown to indicate that this is not allowed according to the syntax rules of SDL.

Figure 30 : The channel's text attributes with red underling

The two blocks have been aligned horizontally to more easily distinguish the two text attributes.

To fill in the name of the channel C3:

  • Type it directly, immediately after the channel has been drawn. (If the channel has become de-selected, select it again.)

To fill in the signal Bump into the signal list text field:

  1. Click on the text field surrounded with two brackets `[ ]'. (Click in the space between the brackets.)
  2. Type the name of the signal. Note that the brackets are adjusted automatically to fit the size of the text.
  3. You may move the text attributes to new locations, if desired. Simply drag them with the mouse.

Drawing Channels to the Environment

To draw a channel from a block to the environment (e.g. C2):

  1. Select the block.
  2. Start by dragging the handle, and terminate by clicking on the frame symbol (the rectangle that encloses the diagram, see Figure 32).
  3. Fill in the name and the signals.
    • Note that, as you type the signal list, the red underlining changes and shows if and where the text is not syntactically correct according to SDL. As soon as you have entered the signal names separated with commas, the red underlining disappears and shows that the text now is syntactically correct!
    • The SDL Editor allows you to leave a text containing syntax errors. However, it is not possible to build an SDL system that contains syntax errors.

Drawing a Channel from the Environment

To draw a channel from the environment to a block (e.g. C1):

  1. Start by drawing the channel from the block to the environment, as you just learned.
  2. Make sure the channel is still selected.
  3. Then, select the command Redirect from the Edit menu. Fill in the name and signals the usual way.
    • You may press <Return> to insert line breaks within the signal list, if it becomes too long.

Drawing a Text Symbol

The diagram also contains a text symbol with the required signal declarations.

  1. Pick the text symbol in the symbol menu (the top symbol), insert it into the drawing area and fill in the contents as shown in Figure 27. The built-in syntax check is even more evident in this case.
  2. When the contents of the text symbol are changed, the editor automatically resizes the text symbol to fit the text. You may resize it by dragging the lower right corner, or toggle between its minimized and maximized sizes by double-clicking the symbol. Try this.
    • The selection squares at the other three corners of the text symbol are gray. This means that the symbol cannot be resized by dragging any of these corners.

Resizing the Text Window

If the text window is too small to bring all the text in view, you may resize it. In Windows, this is done in the same way as any normal window. On UNIX, this is done by dragging the sash up or down; the sash is the small square situated to the right and above the text window menu bar; the text window is a pane of the SDL Editor window.

Figure 31 : The SDL Editor's sash (UNIX only)

Other Items in the System Diagram

Except for SDL symbols, a diagram also contains the following:

Figure 32 : Other symbols

Package Reference Symbol

The package reference is used to refer to included SDL packages. This simple example does not include any packages. Just leave it empty.

The Kernel Heading

The kernel heading is automatically assigned its contents by the editor to reflect the type and the name of the diagram being edited. The kernel heading is editable, but you are not going to alter its contents in this tutorial.

Additional Heading Symbol

The additional heading symbol is not defined further according to Z.100. In the SDL Editor, it looks like a dashed text symbol. The symbol is editable and may be resized the same way as you learned for resizing text symbols, but it cannot be moved. Its intended use in the SDL Editor is, among others, to define inheritance and specialization and to specify formal parameters. You will not use this symbol in this first tutorial.

Frame

The frame surrounds the objects that are contained in your diagram. You may want to resize the frame to create a more compact diagram: simply drag any corner to do this.

Note:

The frame is not the same as the paper border!

Page Numbering

The page numbering is updated automatically, and reflects the name of the page and the total number of pages. It is not editable.

Saving the Newly Created System Diagram

In this exercise, you will learn the commands that store SDL diagrams on files.

  1. You should now have two windows on the screen, the Organizer window and the SDL Editor window.
    • To find the Organizer window, you may at any time select the command Show Organizer from the SDL Editor's Tools menu, or click the Show Organizer quick button.
  2. Before you save anything, open the Organizer's View Options dialog from the View menu.

Figure 33 : The Organizer's View options

  3. Make sure the options are in accordance to Figure 33 and click the Apply button. This makes, among other things, the file and directory names visible in the Organizer.
    • The list in the dialog is a multiple selection list. When you click on an item in the list (in Windows while holding down the <Ctrl> key), its selected state is toggled without affecting any other item. This makes it possible to select any number of items in the list. In Windows, if you by mistake click on an item without using the <Ctrl> key, you may press Default to get back to the default settings.
    • To close the View Options dialog, click the Close button. This kind of dialog is modeless, meaning that it remains open until you decide it is longer needed and close it. You are not forced to close a modeless dialog to continue working with the tool, in opposite to modal dialogs, such as the Add New dialog which you used for creating a new system (see Figure 23).
  4. Look at the resulting Organizer view. The system diagram icon is drawn with a gray pattern, which shows that the diagram is modified and not saved. The name of the diagram (i.e. DemonGame) is shown in bold face, to indicate that the diagram is currently open in an editor. The text to the right of the icon reads [unconnected] which is a convention adopted in Telelogic Tau to show that a diagram has no current binding to a file.
    There are two other diagram icons, which are [unconnected] These represent the references to the block diagrams that you added when editing the system diagram.

Figure 34 : A modified, unconnected diagram (DemonGame)

  5. Now, go back to the SDL Editor and save the SDL diagram by selecting the Save menu choice from the File menu.
    • To locate the SDL Editor window from the Organizer, you may double-click the icon for the system diagram again, which simply raises the SDL Editor window.
  6. A file selection dialog is displayed. This is a generic dialog that Telelogic Tau opens whenever you are prompted to specify a file (to open, to save, etc.). The title of the dialog shows the nature of the operation, Save in this case.

Figure 35 : A file selection dialog (on UNIX)

On UNIX, this dialog works as follows:
  • The Filter field is preset to *.ssy, which is the default file extension for files that contain SDL system diagrams. To list other files, you have to change the contents of the Filter field and click the Filter button (but do not do this now).
  • The right list shows a list of files that match the file filter. It should be empty since you have not created any diagrams yet.
  • The left list shows the directory structure from the root node of the file system down to the current directory. You may double-click here in order to navigate in your directory structure (do not use this list now).

Figure 36 : A file selection dialog (in Windows)

In Windows, this dialog works as follows:
  • The Files of type field is preset to *.ssy, which is the default file extension for files that contain SDL system diagrams. To list other files, you have to change the contents of the File name field and click the OK button (but do not do this now).
  • The list shows a list of files that match the file filter. It should be empty since you have not created any diagrams yet.
  • The Look in list shows the directory structure from the root node of the file system down to the current directory. You may click here in order to navigate in your directory structure (do not use this list now).
  7. The SDL Editor suggests a file name to store the diagram on: DemonGame.ssy. You may change to any file name; we assume however in this tutorial that you accept the suggested file name.
    So, simply click the OK button to accept the file name. The diagram is now stored on file. If you look at the title of the SDL Editor window, you may see that the diagram has been saved on file.

Figure 37 : The SDL Editor window title

This information is also available in the Organizer structure, where the file name has changed from [unconnected] to DemonGame.ssy.

Figure 38 : The diagram structure after saving the diagram

Saving the Diagram Structure

You have, so far, saved the system diagram. You should also save the Organizer's view options and diagram structure for future sessions. If you look at the Organizer's window title, you notice an ending asterisk. This asterisk denotes that the Organizer's view or structure information has been modified and needs to be saved.

Figure 39 : The Organizer window title

The System File

The Organizer saves its view, along with a number of options, on a dedicated file called the system file1. System files are used as a means to maintain the consistency of an SDL structure and provide immediate access to the diagrams that are defined in the structure.

The system file is represented by its own icon at the top of the Organizer view, a rectangle with "SDT" in it. Even though the system file has not yet been saved, the Organizer has assigned a file name for it.

To save the system file:

  1. Select the Save command from the Organizer's File menu. The Organizer responds by issuing the Save dialog.

Figure 40 : The Organizer's Save dialog

  2. The tool suggests a file name to store the information on: demongame.sdt (system files are by default assigned the extension .sdt). Accept the suggestion by clicking the Save button.

Once a system file has been created, the diagram structure and the Organizer options are saved for future sessions. You Open an existing system file from the Organizer's File menu.

More About Saving

For the purpose of this tutorial, you have learned how to save individual diagrams and how to save the system file. There are however other handy ways to save everything with one single command. Two of these methods are listed below.

    • You may click the Save All button in the Organizer's Save dialog (see Figure 40).
    • You may click the quick button for Save on the Organizer's tool bar. This button orders a global and silent save of all diagrams (no prompting will be issued unless special cases need your attention), including the diagram structure. (The SDL Editor's quick button for Save saves the current diagram only.)
1

A system file may contain information related to any kind of SDL structure, not necessarily an SDL system. The term system file is a general term.


Printing the System Diagram

What You Will Learn

  • To print one SDL diagram
  • To adjust print options
  • To scale a printout

How to Print

You have now drawn your first SDL diagram. It may be convenient to print the diagram before proceeding with the remaining exercises. On UNIX, we assume that your computer environment includes a PostScript printer. If not, you may skip this exercise.

To print the diagram:

  1. Raise the SDL Editor window.
  2. Select the Print command from the File menu. The Print dialog is opened.
    • You may instead click the quick button for Print.

Figure 41 : The Print dialog

  3. If you have set up your preferences adequately, the dialog should be preset with the correct options. If not, you need to check and possibly modify at least the:
    • Paper format option menu
    • Destination Format: if you do not have access to a PostScript printer in Windows, you may select MSW Print.
    • Execute command (governed by the preference PrinterCommand).
  4. Once the settings look OK, order the printout by clicking the Print button. On UNIX, a PostScript file will be generated on /tmp and the file will be piped to the Execute command that you have specified. In Windows, a print file will be generated by using the Execute command that you have specified to print it, or by using the default printer driver if you have selected MSW Print format.
    If the file is sent to a printer queue, the printer should respond almost immediately. If you are not satisfied with the size of the resulting printout, you may scale it as follows:
    • Click the Setup button. The Print Setup dialog is opened.

Figure 42 : The Print Setup dialog

    • Adjust the scale to the value of your choice and click OK.
    • Order the printout once more by clicking Print.


Checking the System Diagram

What You Will Learn

  • To invoke the Analyzer
  • To set analysis options
  • To work with the Organizer Log window
  • To locate and correct syntax errors

Running the Analyzer

You should now check the syntax of the system diagram you created before proceeding further by creating the remaining diagrams. To do this, you will use the Analyzer tool, a back-end tool which is fully integrated with the Organizer.

  1. Select the SDL system diagram icon in the Organizer diagram structure. Then, from the Organizer's Generate menu, select the Analyze command.
  2. If you had (perhaps accidentally) modified any diagram, the Organizer first prompts you to save modified diagrams (by issuing the Save dialog, see Figure 40) -- in which case you should click the Save All button to make sure everything is OK.
  3. Once the Save dialog is closed, the Analyzer dialog is opened.

Figure 43 : The Analyzer Options dialog

  4. Adjust the options in accordance to Figure 43, i.e.
    • Macro expansion off
    • Syntactic analysis on
    • Semantic analysis off
    • Adjust, if required, the error limit slide bar to a reasonable value. This parameter defines how many errors and warnings the Analyzer will report before aborting the analysis.
  5. Click the Analyze button. The Analyzer now starts processing the input with the options as specified in the options dialog. When it is finished, the Organizer status bar should read something with the essence "Analyzer done", possibly appended with extra information.
  6. The Organizer is provided with a textual window where important information is logged. By default, the Organizer Log window is raised as soon as information classified as "warning" or "error" is reported. If the window does not appear automatically after the analysis is complete, open the window manually. (Use the Organizer Log command from the Organizer's Tools menu to show the window, or the provided quick button).

Looking for Analysis Errors

The diagnostics that are reported by the Analyzer are appended to the Organizer Log (together with other important messages). Look at the tail of the log for the report summary, which should look something like:

--------------------------------------------------

Number of warnings: <diagram dependent>
+ Analysis completed

(You may need to scroll down the Organizer Log window to bring the tail into view.)

The text "Number of warnings" or "Number of errors" shows how many syntactic warnings or errors that were detected in the diagram (if no warnings or errors were found, then these lines are missing altogether).

  1. For the purpose of this exercise, you may need to introduce a syntactic error into the diagram. You may for instance remove one of the separating commas in the signal list of channel C1 (but make sure there is a space separating the signals).
    • Such a syntactic error will be detected already in the SDL Editor and marked with a red underline, but we will show how the error is reported by the Analyzer.
  2. Save everything and repeat the analysis.

Correcting Analysis Errors

Your Organizer log should now report an error looking something like:

#SDTREF(SDL,/opt/home/tmi/demongame/DemonGame.ssy(1),131(25,50),3,8) (on UNIX)
#SDTREF(SDL,C:\Telelogic\SDL_TTCN_Suite4.4\work\demongame\DemonGame.ssy(1),131(25,50),3,8) (in Windows)
ERROR 312 Syntax error in rule SIGNALLIST, symbol Name found but one of the following expected:
, ; comment
Result Endgame;
?

How to Interpret the Error Message

Let us spend a few moments on explaining the contents of this error.

  • The first part (#SDTREF...) is a reference to the source diagram, page, symbol, line number and finally a position within a line of text where the error was found. All references produced by the Analyzer adhere to this format in its whole or partially; the reference may in some circumstances be less precise than in the example above, depending on the Analyzer's ability to locate the exact source of error.
  • The second part (ERROR 312...) contains the error number and an explanatory text, telling you, in this case that a comma, a semicolon or a comment was expected.
  • The last part (Result Endgame) along with the `?' character shows more specifically where the error occurred, in this case the comma should be inserted between the signals Result and Endgame.

To display the diagram and symbol where the error was found, you may use a handy facility:

  1. Select, by dragging the mouse, the lines of text containing the error message.

Figure 44 : Selecting the error message

  2. Select the command Show Error form the Tools menu.
    • Alternatively, you may click the Show error quick button.
  3. The symbol where the error was found is immediately selected in the SDL Editor. The more information the reference holds, the more precise the selection. Correct the error (insert the comma).
  4. To correct the next error, simply click the Show error button again.
  5. Save the diagram and repeat the analysis until the Analyzer does not report any errors. If you feel uncertain about how to interpret and correct the errors, look at the printout for the system diagram for a reference (see Figure 27).
    • You may clear the Organizer Log window at any time, for instance between subsequent passes to make it easier to read the contents of the log. Use the Clear Log command from the Edit menu for this, or the provided quick button.
    • For repeated analysis passes using the same options, you can use the Analyze quick button in the Organizer.

You have now designed your first SDL diagram using the SDL suite. You have also verified that the diagram is syntactically correct according to the Z.100 recommendation. Congratulations!


Creating a New Block Diagram

What You Will Learn

  • To create and draw a block diagram
  • To request signal dictionary support
  • To work with multiple diagrams using the SDL Editor
  • To open new windows on a page
  • To work with multiple SDL Editor windows
  • To perform syntax check on a block diagram

Creating a Block Diagram from the Organizer

In this exercise, you will create a block diagram, starting from the Organizer.

  1. Locate the Organizer window and double-click the icon named GameBlock. In a similar fashion as when creating the system diagram, you will get the Edit dialog (see Figure 25). Make sure the Show in editor option is on and click the OK button.
    Next, the Add Page dialog is opened. The dialog is used to specify the type of page (process or block interaction). The page name can also be specified. Decide if you want the pages to be autonumbered. (1, 2,... N). This functionality is enabled by default.

  2. Figure 45 Process Interaction Page

    Make sure the Process Interaction Page button is on and click OK.

The SDL Editor opens a window on page 1 of the newly created block diagram. The block diagram editor window is similar to the system diagram window; only the symbol menu differs.

Figure 46 shows the appearance of the finished block GameBlock when printed. As you may see, the diagram contains two process reference symbols, five signal routes, three connection points and a text symbol with a signal declaration.

Figure 46 : The block GameBlock

You should now draw the block diagram as depicted in Figure 46. You add the symbols and lines in a similar fashion as when editing the system diagram. Please spend a minute reading the three sub-sections below before starting drawing the diagram, in order to familiarize yourself with the new concepts that are introduced and how you manage them.

Process Name and Number of Instances

When you add a process reference symbol, you should specify the number of instances by appending the text directly after the name of the process reference symbol. The number of instances is the text between parentheses `( )'.

Signal Routes

Signal routes are drawn in a similar way as channels. When you select a process reference symbol, two "handles" are displayed.

Figure 47 : The two handles of a process reference symbol

  • The left handle is used for drawing signal routes, in a similar fashion as channels.
  • The right handle is used for drawing create requests. It is not used in this tutorial.

Connection Points

When you draw signal routes to / from the frame symbol, you should not only fill in the name and signal list, but also take advantage of graphical connection points to establish connections between the signal routes and the parent system diagram, i.e. connecting the signal routes to the channels. When you draw a signal route to the frame, an additional text object is created close to the frame symbol. In this text object, the name of the corresponding channel is entered. See Figure 48.

Figure 48 : Graphical connection point

The figure depicts a signal route (R1) in the block diagram and the referencing system diagram with the connected channel (C1).

To edit a connection point:

  • Simply select it and enter its textual contents.

Editing the Block Diagram

Now, draw the diagram as described in the following steps:

  1. Start by adding the process reference symbol "Main(1,1)".
    • As when drawing the system diagram, all text you enter is subject to an immediate syntax analysis. Errors are indicated by a red underlining, which disappear as soon as you have entered the complete text according to the SDL syntax.
    • Remember that before text editing has started, the text cursor is not flashing. Pressing <Delete> at this stage deletes the whole selected symbol, instead of just a typed character.
  2. Draw a signal route from the environment to the process (use the Redirect command). Enter the name of the signal route: R1.

Using the Signal Dictionary for Individual Signals

You are now to specify the name of the signals to be conveyed on the signal route R1. The SDL Editor has the ability to assist you in reusing the signals that are already defined in the SDL structure (i.e. defined in the system diagram, since you are working in a top-down fashion!), with a facility known as the signal dictionary.

  1. Select the signal list text field.
  2. Select the command Signal Dictionary from the Window menu. The Signal Dictionary window is displayed. If necessary, move it so that you can see the signal list in the Editor window.

Note:

To function properly, the Signal Dictionary utility requires that the input SDL diagrams are syntactically correct. If not, you need to go back to the previous exercise (see "Correcting Analysis Errors" ) and run the Analyzer in order to correct any errors.

Figure 49 : The Signal Dictionary window (on UNIX)

The exact appearance of the list to the left depends on the graphical capabilities available on your terminal.

  3. Look at the left list in the Signal Dictionary window. The first section starts with the separator Up. This section includes the signals that are available by looking one level up in the diagram structure (i.e. in the parent diagram, system DemonGame).

Figure 50 : The Up separator (on UNIX)

Figure 51 : The Up separator (in Windows)

  4. In this section, the first item identifies the System DemonGame, as expected:

Figure 52 : The item symbolizing the system DemonGame (on UNIX)

Figure 53 : The item symbolizing the system DemonGame (in Windows)

  5. Since you are editing a signal route from the system diagram to the block diagram, you should look for all icons/lines symbolizing channels from the parent diagram, i.e. IN channels.

Figure 54 : The icon symbolizing a channel from the parent
diagram to the current diagram (on UNIX)

Figure 55 : The line specifying a channel from the parent
diagram to the current diagram (in Windows)

    • You should find exactly one channel that matches the criteria: C1. The remaining channels are either internal (C3) or are not directed into the current diagram (C2).
  6. Beneath the channel all the signals that it conveys are listed. Click on the signal named Newgame:

Figure 56 : The Newgame signal (on UNIX)

Figure 57 : The Newgame signal (in Windows)

  7. From the Edit menu, select the command Insert. The signal list in the SDL Editor is immediately updated.
    • Alternatively, you may double-click the signal in the list.

Note: Undoing the operation

If you happen to insert the signal into the wrong text field (such as the signal route name), you may select the Undo command from the Signal Dictionary's Edit menu. (The SDL Editor's Text Window has no Undo facility).

  8. Insert the required comma and a newline in the Editor window (move the signal list if needed).
  9. Double-click the signal Endgame in the Signal Dictionary.
  10. The channel in the Signal Dictionary also gives a suggestion about how to fill in the connection point: C1. Select the connection point text field in the diagram and double-click the channel in the Signal Dictionary.

Using the Signal Dictionary for Multiple Signals

  1. In the SDL Editor window, add the process reference symbol: Game(0,1).
  2. Draw the signal route R3 from Game to the frame symbol.
    When you are to enter the signal list for R3, you do not need to enter the signals one by one as for R1, since the channel C2 is not split up into multiple signal routes, in the way that C1 becomes R1 and R2 (see your printout or Figure 27). Instead, you may insert all signals with one single operation:
  3. Select the channel C2 in the Signal Dictionary. The right list is updated to list all signals conveyed on the channel. Insert them with the Insert command (or double-click the channel C2).

Figure 58 : Selecting a channel in the Signal Dictionary
window lists all signals (on UNIX)

Figure 59 : Selecting a channel in the Signal Dictionary
window lists all signals (in Windows)

You are now somewhat familiar with the Signal Dictionary utility.

Completing the Diagram

  1. Fill in the remaining parts of the diagram using your preferred method. When done, you may close the Signal Dictionary window (use the Close command from the File menu).
  2. Once you are finished with the block GameBlock, save everything, for instance by clicking on the Organizer's Save quick button. Accept the default file name suggested by the Save dialog.

Working with Multiple Diagrams

You have now created two SDL diagrams. Both diagrams are currently opened by the SDL Editor; however only the diagram currently being edited is visible in a window.

The SDL Editor provides a menu named Diagrams where all diagrams and pages currently opened by the editor are listed.

  1. Click on the Diagrams menu. It should now list two diagrams:

Figure 60 : The Diagrams menu

Each of these menu choices correspond to a diagram and page currently opened by the SDL Editor. The file the diagram is stored on is also displayed to the right of the diagram name.
Now, bring the diagram for the system DemonGame into view:
  2. Select the menu choice
    System DemonGame/1 ...... DemonGame.ssy 1
    The system diagram is instantly displayed. (The block diagram is now hidden.)
    • The menu choices Back and Forward can also be used to switch between diagrams and pages. The SDL Editor keeps track of which pages you have edited and you can go back and forward in this list, in much the same way as for visited Web pages in a Web browser. There are also two quick buttons for this.

Working with Multiple Windows

So far, you have only worked with one single window on a page. The SDL Editor allows you to open new windows on the same diagram, which makes it possible to work on multiple views on a page. This is also called instantiating a window.

To open a new window on a page:

  1. Make sure the page whose window is to be instantiated is the page currently in view in the SDL Editor. If not, use the Diagrams menu.
  2. From the Window menu, select the command New Window. A new window showing the current page is instantly displayed (see Figure 61).
  3. You may now use any window to work on the page. Any change causes both windows to be simultaneously updated. Try this, for instance by moving a symbol!
  4. You probably need one window only for this tutorial, since the diagrams you are working on in this tutorial are small, on purpose. Close any of the two windows with the Close Window command from the Window menu.

Figure 61 : Two windows of the same page

Resulting Organizer View

Save everything. The resulting Organizer View should now look like:

Figure 62 : The resulting Organizer view

Checking the Syntax of the Block Diagram

You may now want to use the Analyzer to check the syntax of the block diagram you just created.

To analyze the block GameBlock, do as follows:

  1. Select the icon for the block GameBlock to specify the block as input to the Analyzer.
  2. Select the command Analyze and analyze the block diagram.

Figure 63 : Specifying the input to the Analyzer

    • Note that the Analyze dialog lets you select which part(s) of the system you wish to analyze. Make sure the top text in the dialog says Analyze Block GameBlock before clicking -Analyze.
  3. Proceed as for the system diagram, i.e.
    • Look for any syntax errors in the Organizer Log.
    • Correct these errors.
    • Repeat the procedure if required (see "Correcting Analysis Errors" if you do not remember how to do this).
1

The exact appearance of the menu choice depends on the directory structure you are working on.


Creating a Block Diagram From a Copy

What You Will Learn

  • To create a diagram from an existing copy
  • To save a diagram on a new file

Creating the Block DemonBlock

You created the block GameBlock from the Organizer by double-clicking the symbol. You may also do this from within the SDL Editor, by double-clicking on diagram reference symbols.

To create the block DemonBlock:

  1. Locate the block reference symbol DemonBlock in the SDL Editor. Double-click on the reference symbol. A dialog is opened.

Figure 64 : Prompting to create the block DemonBlock

You will now create the diagram by using a copy of an existing file. The Telelogic Tau installation contains a number of SDL examples, among which the diagrams that build up the DemonGame example may be found. These diagrams are by default stored in a subdirectory to the installation directory. The name of the directory should be $telelogic44/sdt/examples/demongame (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame (in Windows).
Your next task is to specify the location of the file that contains the block DemonBlock. This file is named DemonBlock.sbk

Note:

You may need to contact your system manager to find out the exact location of the directory mentioned above. If you fail in finding the directory with the DemonGame example, do not give up! You may always create the remaining diagrams with the New option, and design them with the SDL Editor in a hand-drawn fashion, as you learned in the previous exercises.

  2. Make sure the Copy existing file button is turned on.
  3. Then, either:
    • Type in the file name, including the directory path (according to above),

      or
    • Click on the folder button to the right of the text field. A file selection dialog (with the title Select File to Copy for Block DemonBlock) is displayed.
    • In the dialog, navigate in the directory structure until you have located the directory where the diagrams are stored (see the directory path above). On UNIX, you double-click the directory names in the left list and find any block diagram files in the right list. In Windows, you select directories from the Look in box or double-click directories in the list.
    • Select the file DemonBlock.sbk that appears in the list and click OK.

Note: Accessing files on other disks

In Windows, you may use so-called UNC paths to access network disks by using the syntax \\disk\directory\ when typing the path to file names.
On UNIX, the possibility to change to the [root] directory using the Telelogic Tau file selection dialog may or may not work properly, depending on your computer system and network file system. You may need to type in a leading slash (`/'), followed by a name, then click OK in order to access files that are stored on another disk than the one you are currently working on (but try first to double-click the [root] directory).

  4. Close the Edit dialog by clicking on the OK button. The SDL Editor shows the diagram in a window. The diagram when printed should look like Figure 65.

Figure 65 : The block DemonBlock

  5. Now, save the diagram from the SDL Editor (use the Save quick button). A file selection dialog is displayed, with the suggested file name -DemonBlock.sbk.
  6. Accept the suggestion by clicking the OK button. The resulting Organizer's diagram structure should be as follows:

Figure 66 : The resulting Organizer list

You may use the method described above to take a copy of an existing diagram for any diagram in the remainder of this tutorial. However, we recommend that you draw the diagrams from scratch to get yourself acquainted with all editing features of the SDL Editor. How to draw a process diagram (described next) is somewhat different from drawing a block diagram.


Creating a Process Diagram

You have now created the structural elements of your SDL system. This structure needs now to be completed with the implementation, i.e. the process flow charts that describe the behavior of the system.

In the previous exercises, you have learned how to create new diagrams, either from the Organizer or from the SDL Editor, so we will not focus on these details any more. Feel free to double-click icons in the Organizer or in the SDL Editor, or to use the Organizer Edit command, depending on your preference.

In the next exercise, you will instead learn how to use the SDL Editor for drawing process diagrams. Let us start with the process Demon, which is depicted in Figure 67.

Editing the Process Demon

Figure 67 : The process Demon

On the next pages, you will find suggestions about how to use the SDL Editor to draw the diagram.

What You Will Learn

  • To add symbols with the double-click facility
  • To work with the clipboard functions
  • To insert symbols in a flow
  • To request grammar help

Creating the Diagram

  1. Edit the Demon diagram. When you are prompted to add a page, make sure that you specify a page with the type set to Graph Page.

Figure 68 : Specifying page type to graph page

  2. When the SDL Editor responds by displaying the (empty) diagram, you notice that the appearance of the symbol menu is different; it now contains the symbols that are allowed on a flow diagram (such as state and input symbols).

Figure 69 : The SDL Editor window for flow diagrams (on UNIX)

The diagram consists of two branches of symbols (see Figure 67). When you append symbols to a branch, the editor may automatically interconnect the symbols with flow lines.

You may select to enter the text into each symbol once the symbol has been inserted, or insert all symbols and then edit the text, or a mix of both methods.

Creating the Left Branch with Grammar Help

To create the left branch:

  1. Select the start symbol in the symbol menu and place it in the drawing area at a suitable location.
    • Remember that when you point to or select a symbol in the symbol menu, its type is displayed in the Status Bar at the bottom of the SDL Editor window. Use this if you are not sure what symbol to pick.
  2. Double-click the task symbol in the symbol menu. An empty task symbol should now be appended to the start symbol.
    When you are to edit the task symbol containing the statement that sets the timer, let us assume, for the purpose of this exercise, that you do not have the grammar for the Set statement in mind.
    The SDL Editor provides a context-sensitive facility, the Grammar Help window, that assists you in entering correct SDL expressions. You will now use it in order to fill in a correct set expression.
  3. Select the command Grammar Help from the Windows menu. The SDL Editor responds by displaying the Grammar Help window.

Figure 70 : The Grammar Help window

    • The left list shows a number of "use cases", each of them identified with their name. The first one is the GRAMMAR for the selected object.
    • The top of the right list shows a number of references to the Z.100 definition.
    • Beneath the Z.100 references are listed the formal textual (SDL/PR) expressions that are legal to add to the symbol. (The formal expressions need of course to be replaced by the actual values that are used in your context).
  4. The use case you are to use is the set of a timer, so locate the item titled Set in the left list and select it.
    • The right list is updated to reflect the formal grammar for the expression: "SET(Now+Expr, TimerName)".

Figure 71 : The grammar for a Timer Set

  5. Insert the formal text into the task symbol by selecting the Insert command from the Edit menu. The task symbol is immediately updated.
    • You may also double-click the Set item in the list.
  6. Now, change the generic names Expr and TimerName to their actual values (1 and T, respectively).
    • You use the SDL Editor's text window for this. Drag for instance the mouse over the text to be changed and type in the new text to substitute it with.

Figure 72 : Edit the text in the text window (on UNIX)

You have now learned the basics about how to work with the Grammar Help.
  7. To finish the left branch, double-click a state symbol and enter the text: Generate

Creating the Right Branch

To create the right branch:

  1. Copy the newly added state symbol to the clipboard. You find the clipboard commands, e.g. Copy, on the Edit menu or on the pop up menu that is activated with the right mouse button.
  2. Paste the state symbol. Following Paste, you should specify the location of the new symbol; move the mouse until you point to a suitable location and terminate with a click with the left mouse button.
  3. Append an input symbol with a double-click. Enter the text: T
  4. Append the output of the signal Bump with a double-click and enter the text Bump.
  5. Copy the task symbol with the text "SET (Now+1, T)" to the clipboard. But, do not paste right now.
  6. Point to the output symbol Bump. Press the right mouse button and select the Insert Paste command. This pastes and connects the task symbol.
  7. Terminate the branch by double-clicking a state symbol and typing a hyphen (-).
  8. Finally, add a text symbol and type in the declaration of the timer T.
  9. If desired, resize the frame symbol.
  10. Save the diagram with the file name Demon.spr.

This concludes the editing of the process Demon.

Editing the Process Game

First, create the process diagram Game in the usual way. In this exercise, you will learn some other editing functions:

What You Will Learn

  • To edit parallel flow branches
  • To interconnect symbols

Figure 73 : The process Game

You may proceed editing the process diagram in Figure 73, as will be described below:

Editing the Start Transition

  1. Insert the start symbol, the following task symbol and the state symbol Losing.
  2. You will now insert two input symbols in parallel. To do this, first make sure the state symbol is selected. Then, press <Shift> and double-click two input symbols (<Shift> must be kept pressed while you do this).
  3. Release <Shift> and select the left input symbol.
  4. Fill in the name of the input symbol (Probe), and complete the left branch.
  5. Select the right input symbol, fill in the name (Bump) and complete the branch without bothering about the subbranch that starts with the input of the signal Probe in the state Winning.
  6. Select the Probe input symbol in the left branch. On the Edit menu, use the Select Tail command to extend the selection to the end of the branch.
  7. Copy the selection and Paste it. Move the selection (which appears as a set of symbols) to a suitable place and paste it with a click with the left mouse button. If Paste fails (because of insufficient space or overlap), an alert sound is issued -- please try again.
  8. Change the text in the input symbol from Lose to Win.
  9. Change the text in the task symbol to Count:=Count+1.
  10. To interconnect the state symbol Winning with the input symbol Probe: select the state symbol - a handle appears -

Figure 74 : The selected state and its handle

drag the handle while pressing the mouse and release the mouse when it points to the input Probe symbol. A line is drawn between the symbols:

Figure 75 : The two branches are connected

  11. Conclude the diagram by drawing the remaining parts and saving the diagram.

Figure 76 : Remaining parts to edit

Editing the Process Main

The process Main is the last diagram to create and edit. If you find this tedious, you may skip this exercise and create the diagram as a copy from the files that are enclosed in the distribution (how to do this is described in section "Creating a Block Diagram From a Copy" ). Figure 77 shows the appearance of the diagram to create.

Figure 77 : The process Main


More About the Organizer

When you are ready with the diagram, save everything. The diagram structure in the Organizer Window should now look like this:

Figure 78 : The resulting diagram structure

In this tutorial, you have only browsed through a minor part of the available functionality. You may for instance customize the Organizer to display the information using different view options.

What You Will Learn

  • To work with vertical trees
  • To expand and collapse the diagram structure
  • To rearrange diagrams in an Organizer structure
  • To display directories and pages
  • To print the entire system

Tree View

  1. Bring up the View Options dialog (see Figure 33), click on the Vertical tree radio button and click on Apply. The Organizer window changes its presentation mode:

Figure 79 : A vertical tree structure

  2. Apply the Indented list mode again.

Expand / Collapse

You may make parts of the diagram structure invisible (and visible again) with the Expand and Collapse commands from the View menu. (Expand is available on collapsed nodes only (indicated by the small triangle), while Collapse is available on expanded nodes that have a substructure).

  1. Collapse the block GameBlock. The subtree for the block -GameBlock is reduced to the node, with a small triangle added.

Figure 80 : A collapsed node

  2. Expand the subtree again (use Expand Substructure).

Rearranging Diagrams

The Organizer lets you rearrange the order of appearance of symbols.

You can either do that with arrow keys (<Up>, <Down>, <Left> and <Right>) or with the quick buttons Move up and Move down.

Say that you want to rearrange the order of appearance of the blocks -DemonBlock and GameBlock:

  1. Select the block GameBlock.
  2. Click once on the quick button Move down, alternatively press <Shift> and type the <Down> arrow key. The result becomes:

Figure 81 : Rearranged GameBlock and DemonBlock

  3. Change back to the original order of the diagrams.

Diagram Pages

  1. In the View Options dialog, turn the Page symbols item on.
  2. Apply the options - the result becomes a list where the SDL pages are made visible.

Figure 82 : Diagram pages are displayed

Printing the System

The Organizer lets you print all diagrams that are included in the system with a single command. You may also include a table of contents:

  1. De-select all diagram symbols, or select the system diagram.
  2. Click the quick button for Print. This opens the Organizer's Print dialog.
  3. Turn the Table of contents toggle button on and click on Print to order a global printout of all SDL diagrams, including a table of contents (see Figure 83).

Figure 83 : Including a table of contents

You have now created and printed your first complete SDL system using the SDL suite. Your next task is to check the complete system with respect to SDL syntax and semantics.


Analyzing the Complete System

What You Will Learn

  • To perform syntactic and semantic analysis on the whole system
  • To generate files containing definitions and cross references

Enabling Semantic Analysis

To analyze the system, you should also enable the semantic checker. To do this:

  1. Select the system diagram icon.
  2. Use the Analyze command from the Generate menu.
  3. Adjust the analyzer options according to the picture below:

Figure 84 : Including semantic analysis

    • Make sure the Analyzer generates a file with cross references, by turning the toggle button Generate a cross reference file on. You will need this file in a later exercise in this tutorial.
    • The semantic Analyzer has some other options, each one of these individually activated with a toggle button. They have no impact on this tutorial.
  4. Click the Analyze button.
  5. When the Organizer status bar reads "Analyzer done", look at the Organizer Log for any errors reported by the Analyzer.
  6. If required, correct the errors and repeat the procedure. How to locate errors in the source SDL diagrams was described in a previous exercise, see "Looking for Analysis Errors" and "Correcting Analysis Errors" .
  7. The tail of the Organizer log should contain the following output when the system is syntactically and semantically correct:
+ Analysis started
Conversion of SDL to PR started
Conversion to PR completed
Syntactic analysis started
Syntactic analysis completed
Semantic analysis started
Semantic analysis completed
+ Analysis completed

Terminate this exercise by saving everything. You may also want to print the diagrams again (see "Printing the System" for how to do this).


Managing Message Sequence Charts

Besides the SDL tools, Telelogic Tau also support the Z.120 recommendation, also known as Message Sequence Charts (MSC). You should have a basic understanding of MSC symbols to fully understand this exercise.

In this tutorial we will demonstrate some application areas of MSCs.

  • First, an MSC may be used for describing the requirements on the dynamic behavior of a system, viewed as a "black box" which receives external stimuli (corresponding to SDL signals issued from the environment) and respond by sending SDL signals to the environment.
  • MSCs may also help you to understand a problem, by offering a way of presenting, in graphical form, some use cases which have been identified, before proceeding with the design in SDL.
  • Generating MSCs as the result of a simulation of a system also provides a mean to understand the dynamic behavior and verify it against the expected behavior.
  • Finally, MSCs can be input to a Validator where you can verify that the scenario that the MSC is describing may actually occur and under what circumstances.

What You Will Learn

  • To add MSCs to the diagram structure
  • To associate SDL diagrams and MSCs
  • To create MSCs
  • To edit MSCs

Inserting an MSC into the Organizer

To create an MSC, you use the Organizer, where the MSC will be managed as an Other Document. In this exercise, we will create an MSC where you will describe the dynamic behavior of the system DemonGame. You will also use this MSC as a reference when simulating and validating the system (this is done in later exercises).

To create an MSC:

  1. Select the Organizer chapter Other Documents.
  2. From the Edit menu, select the command Add New, or click the quick button for this.
  3. The Add New dialog is opened, prompting you to specify a diagram name and type.

Figure 85 : Specifying the name and type of the diagram to add

Adjust the dialog options as in Figure 85 above:
  • Set New document type to MSC
  • Change the name to DemonGame.
  • Show in editor should be turned on
  4. Click the OK button. An MSC icon appears in the Organizer's Other Documents chapter; the lower part of your Organizer window should look like Figure 86, once the MSC Editor is started (you may have to raise the Organizer window if the MSC Editor covers it).

Figure 86 : The Organizer structure with an MSC added

The MSC you have inserted into the Organizer is intended to describe the behavior of the system and you will associate it with the system diagram. The association will be visible in the Organizer.
  5. Make sure the MSC icon is selected and select the Associate command from the Edit menu. A dialog is displayed.

Figure 87 : Associating an MSC with an SDL diagram

  6. Select the system DemonGame item in the list and click OK.
  7. Look at the resulting Organizer structure. In addition to the MSC icon in the Other Documents chapter, an MSC Link icon appears, connected to the system diagram icon. If you select it, the Organizer's status bar informs you about the link to the actual MSC.
    • If you do not see any MSC Link icon, check the Organizer's View Options, turn the option Association Symbols on and click Apply.

Figure 88 : Association between the System diagram and the associated MSC

Editing an MSC

  1. Raise the MSC Editor window for the newly added MSC symbol. The window of the MSC Editor looks similar to the SDL Editor window, but provides of course a different symbol menu and different set of commands and quick-buttons.

Figure 89 : The MSC Editor window (on UNIX)

Your next task is to use the MSC Editor to create the following diagram:

Figure 90 : The MSC for the system DemonGame

The MSC basically consists of four instances (the vertical lines starting with a rectangle), a number of messages (the horizontal lines ending with an arrow), a create process (the dashed horizontal line), a timer (the symbol starting with an hourglass and ending with an arrow) and two condition symbols (with the shape of a hexagon). You also find a text symbol, containing a textual comment in it.

How to Draw the MSC

We suggest that you draw the MSC as described below. If you are unsure what symbol in the symbol menu to use, select or point to a symbol and look at the description in the Status Bar.

  1. Start by entering the text symbol and fill in its contents. (This is done in the same way as with the SDL Editor).
  2. Then, insert the three instances with the instance name Environment, Main and Demon:
    • To insert an instance, locate the instance head symbol in the symbol menu, select it and place it into the drawing area as shown in Figure 90; as soon as you insert an instance head, the MSC Editor automatically appends an instance axis (with an infinite length).
    • Type in the text to assign the instance name (Environment, Main, Demon)
    • To assign the instance kind (process Main, process Demon), select the small rectangle located immediately above the instance head symbol and type in the text.

Figure 91 : The text attributes associated to an instance head

    • If you are not satisfied with the placement of an instance head, you may drag the symbol to a new location.
  3. Once the three instances are added, insert the message Newgame:
    • Select the message symbol in the symbol menu
    • Move the pointer into the diagram. You will notice that a circle indicates a start position outside an instance axis.
    • Click once on the instance axis Environment to define the start of the message.
    • Move the pointer towards the instance axis Main. The message arrow follows the pointer, and a filled circle now indicates an end position outside an instance axis.
    • Click a second time on the instance axis Main to specify the end of the message.
    • Type in the name of the message (Newgame).
    • If you are not satisfied with the placement of a message, you may move it up or down by dragging the mouse. You may also move only the start or end position of the message along the instance axis.
  4. The instance Game is dynamically created. To add Game, you use the create process symbol. You insert it in a similar fashion as a message:
    • Select the create process symbol in the symbol menu.
    • Click once on the instance axis Main to specify the source of the create process symbol.
    • Click a second time to specify the location of the instance head. A process create and an instance head with its axis are inserted.
    • Fill in the instance kind and instance name fields (after you have selected the instance head).
    • If desired, you may move the instance head symbol.
  5. Continue by adding the first condition symbol to the instance axis Game:
    • Select the condition symbol in the symbol menu, and move the pointer to the instance axis. Click to insert the symbol and fill in the name of the condition: Losing.
    • The condition symbol may now be moved vertically along the instance axis.
  6. Add a timer to the instance axis Demon:
    • Select the timer symbol in the symbol menu.
    • Click once on the instance axis to specify the base of the timer symbol.
    • Move the pointer downwards and click a second time on the same instance axis to locate the end of the timer (the end must reside below the source).
    • Enter the name of the timer: T
    • You may drag the start or endpoint to resize the timer symbol, if required. You may also drag the symbol to move it up or down.
  7. Insert the message Bump.
  8. Add the second condition symbol, Winning, to the instance axis Game.
  9. Add the remaining messages. The message Score also contains a parameter with the value 1. To enter the parameter value, select the lower of the two selection rectangles and type in the text 1.

Figure 92 : The text attributes associated to a message

  10. Conclude the editing of the MSC by adding a process stop symbol.
    • Select the symbol in the symbol menu.
    • Place it by a click on the instance axis Game, below the last message.
  11. Before leaving the MSC Editor, you should save the MSC. When saving the newly created diagram, the editor suggests the file name DemonGame.msc. Accept the suggested file name by clicking the OK button.


Using the Index Viewer

In this exercise, you will practice on the Index Viewer. The Index Viewer is a dedicated tool that presents a graphical view of the definitions and references to SDL entities available in an SDL system. It manages virtually all SDL information related to a system and has a number of facilities for navigating back to the source SDL diagrams.

A prerequisite to this exercise is an up-to-date cross reference file containing the definitions and references, which was generated when you last performed a semantic analysis of the system.

If you have changed any of the SDL diagrams since the last analysis of the system, you should regenerate the file. Perform a new semantic analysis and make sure the option Generate a cross reference file is on (see Figure 84).

What You Will Learn

  • To start the Index Viewer
  • To look for definitions
  • To look for references

Starting the Index Viewer

  1. You start the tool with the Index Viewer command from the Organizer's Tools menu and its sub-menu SDL. Select the sub-menu SDL and the menu choice Index Viewer.
    • As an alternative, you may click the quick button for the Index Viewer. You will then be prompted to save unsaved diagrams. The SDL system is then analyzed and a new cross reference file is generated automatically.
  2. The Index Viewer window is displayed. Start by opening the newly created file -DemonGame.xrf (unless you used the quick button, in which case the file is automatically opened).
  3. The Index Viewer reads the file, interprets the content and displays it in graphical form.

Figure 93 : The Index Viewer window

    • Some definitions are predefined in the SDL suite environment (the ones containing PACKAGE Predefined). They are not of interest for the purpose of this tutorial.

In the next exercise, you will use the Index Viewer to identify all possible situations where a certain signal may be sent or received. We will also look for the definition of the signal.

Finding a Definition

Let us look for the definition of the signal Probe. By default, the definitions in the window are sorted alphabetically, but you do not need to scroll the window manually to find a definition.

There is a Search quick button that can be used to find any text in the window. However, if you want to search for the name of a definition, there is an even faster way.

  1. Simply start keying in the name "Probe". When you start typing, a search is started on the names that are displayed in bold face. As you type each letter on the keyboard, the status bar at the bottom of the window indicates what text is being searched for, and the window scrolls to show the first matched name. After a few keystrokes, the Index Viewer window shows the signal Probe selected:

Figure 94 : Finding the signal Probe

The selected row shows the icon for a signal, the name and type of the definition ("Probe SIGNAL") and which diagram the signal is defined in ("SYSTEM DemonGame").
We now wish to see where the signal is defined.
  2. Make sure the Probe icon still is selected.
  3. From the Tools menu, select the command Show Definition.
    • You can also double-click the icon.
      An SDL Editor window is displayed on the diagram for the system DemonGame. The text symbol containing the declaration (i.e. the definition) of the signal is selected.

Finding References

Below the Probe icon in the Index Viewer, all uses (references) of the Probe signal are listed, including the icons for the SDL entities in which the signal has been referred. The information displayed in Figure 94 should be interpreted as:

  • The signal is conveyed on one channel,
  • The signal may be input in two states,
  • The signal is conveyed on one signal route.

To conclude this exercise, you will now locate the places where the signal is input.

  1. Select the input icon.
  2. The Tools menu should now contain the two menu choices Show Use 1 and Show Use 2.
  3. Select the menu choice Show Use 1- an input symbol is selected in an SDL Editor window, showing the diagram for the process Game.
  4. Select the menu choice Show Use 2 - the second input symbol is selected, also in process Game. These are the two situations where the signal may be input.
  5. Double-click the signal route icon. The signal route containing the Probe signal is selected in an SDL Editor window.
    • If you double-click an icon with more than one reference, the selection in the SDL Editor is automatically changed to the next occurrence. You may try this with the input icon.


So Far...

You should now have learned how to use the basic functions in the SDL suite - creating, managing, editing and printing SDL diagrams - and how to create Message Sequence Charts in the MSC Editor. You have also practiced on syntactic and semantic checks on your SDL diagrams. Finally, you have acquainted yourself with the Index Viewer.

Your next task will be to "animate" your first SDL system by simulating it. A number of exercises are prepared in the next tutorial, starting with "Purpose of This Tutorial" .


Appendix A: The Definition of the SDL-88 DemonGame

Telelogic
http://www.telelogic.com


Appendix B: The MSC for the DemonGame

Telelogic
http://www.telelogic.com


4 Tutorial: The SDL Simulator

The SDL Simulator is the tool that you use for testing the behavior of your SDL systems. In this tutorial, you will practice "hands-on" on the DemonGame system.

To be properly assimilated, this tutorial therefore assumes that you have gone through the exercises that are available in 3 Tutorial: The Editors and the Analyzer.

In order to learn how to use the Simulator, read through this entire chapter. As you read, you should perform the exercises on your computer system as they are described.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the essential simulation functionality in the SDL suite. Typically, simulation means executing the system under user control; stepping, setting breakpoints, examining the system, processes and variables, sending signals and tracing the execution, as you would do with a debugger, but applied on the SDL domain.

This tutorial is designed as a guided tour through the SDL suite, where a number of hands-on exercises should be performed on your computer as you read this chapter.

We have on purpose selected a simple example that should be easy to understand. It is assumed that you have a basic knowledge about SDL -- this chapter is not a tutorial on SDL.

It is assumed that you have performed the exercises in 3 Tutorial: The Editors and the Analyzer before starting with the tutorial on the simulator.

Note: C compiler

You must have a C compiler installed on your computer system in order to simulate an SDL system. Make sure you know which C compiler(s) you have access to before starting this tutorial.

Note: Platform differences

This tutorial, and the others that are possible to run on both the UNIX and Windows platform, are described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc. When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.
Normally, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see when running the SDL suite in your environment. Only if a screen shot differs in an important aspect between the platforms will two separate screen shots be shown.


Generating and Starting a Simulator

Once you have designed and analyzed a complete SDL system, it is possible to simulate the system, i.e. to interactively inspect and check its actual behavior. To be able to simulate the DemonGame system, you must first generate an executable simulator and then start the simulator with a suitable user interface.

Note:

In order to generate a simulator that behaves as stated in the exercises, you should use the SDL diagrams that are included in the Telelogic Tau distribution instead of your own diagrams. To do this:
  • On UNIX: Copy all files from the directory
    $telelogic/sdt/examples/demongame
    to your work directory ~/demongame.
  • In Windows: Copy all files from the directory
    C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame
    to your work directory
    C:\Telelogic\SDL_TTCN_Suite4.4\work\demongame.
If you generate a simulator from the diagrams that you have created yourself, the scheduling of processes (i.e. the execution order) may differ.
If you choose to copy the distribution diagrams, you must then re-open the system file demongame.sdt from the Organizer.

What You Will Learn

  • To generate an executable simulator
  • To start the simulator user interface
  • To start a simulator from the user interface

Generating the Simulator

To generate an executable simulation program, do as follows:

  1. Make sure the system diagram icon is selected in the Organizer.
  2. Select the Make command from the Generate menu. The Make dialog is opened:

Figure 95 : The Make dialog (on UNIX)

Figure 96 : The Make dialog (in Windows)

  3. Adjust the options in accordance to the figure, i.e.
    • Analyze & generate code on
    • Makefile and Generate makefile on
    • Compile & link on
    • Use standard kernel on. Make sure that a Simulation kernel is specified to the right; if not, select it from the option menu.
  4. Click the Make button.
  5. Select the Organizer log from the Tools menu. Check that no errors occurred. The Organizer's status bar should read "Analyzer done" and the Organizer Log should report no errors between the "Make started" and "Make completed" messages.
  6. If errors were reported, bring up the Make dialog again, but click the Full Make button instead. This time, no errors should be reported.
    • Another problem could be with the C compiler used on your system. If you still receive errors, try changing to a Simulation kernel reflecting your C compiler, e.g. gcc-Simulation or Microsoft Simulation, and repeat the Make process.

Starting the Simulator

The generated simulator is now stored on a file called demongame_xxx.sct (on UNIX) or demongame_xxx.exe (in Windows) in the directory from which you started the SDL suite (the _xxx suffix is platform or kernel/compiler specific). The simulator contains a monitor system that provides a set of commands which can be used to control and monitor the execution of the simulator.

It is possible for you to execute the simulator directly from an OS prompt, in which case you have to enter all commands to the monitor system textually using a simple command-line interface.

The SDL suite provides a user-friendly graphical interface to the simulator that is started from the Organizer.

  1. From the Tools menu, select the sub-menu SDL and the command Simulator UI. The Simulator UI window is opened:

Figure 97 : The main window of the Simulator UI (on Windows)

The text area to the right informs you that no simulator is running. The text area displays the textual input/output from the monitor system, such as entered commands, the results of commands, and error messages.
  2. To start a simulator, select Open from the File menu, or click the Open quick button.
  3. In the file selection dialog, the generated simulator file described above should be listed. Select it and click OK or Open.
  4. The text area of the Simulator UI greets you with a welcome message to acknowledge that the simulator has been started:
Welcome to SDL SIMULATOR. Simulating system Demongame.

When a simulator is started, the static process instances in the system are created (in this case Main and Demon), but their initial transitions are not executed. The process in turn to be executed is the Main process.

The Simulator UI is now ready to accept commands to the monitor system. Whenever it is possible to enter a command, the prompt Command: is issued in the text area.


Executing Transition by Transition

What You Will Learn

  • To enter commands textually
  • To show the next symbol to be executed
  • To interpret printed trace and graphical trace
  • To execute the next transition
  • To issue commands using buttons
  • To send signals from the environment

Executing the Start Transitions

In this exercise, you will execute the start transitions in the process instances of the system. First, however, we must set the amount of trace information that we want printed during execution. The command Set-Trace is used for setting the textual trace level.

For now, you will enter commands textually by using the text field Command: just below the text area; this field is called the input line.

  1. Click in the input line to place the cursor. Enter the command
    set-trace 6 and hit <Return>. The value 6 specifies that we want full information about the actions that are performed during the transitions. The entered command is moved to the text area and the simulator monitor confirms the trace setting; the text area should now show:
Welcome to SDL SIMULATOR. Simulating system Demongame.

Command : set-trace 6
Default trace set to 6

Command :

A graphical trace (GR trace) is also available, which means that the execution is traced in the SDL diagrams by selecting the next symbol to be executed. GR trace is by default off when you start the simulation.
  2. To enable the GR trace, enter the command set-gr-trace 1. The value 1 specifies that the next symbol to be executed will be displayed in an SDL Editor each time the monitor system is entered.
  3. To have an SDL Editor window appear now, enter the command show-next-symbol. An SDL Editor window appears, showing the diagram for the process Main with its start symbol selected (this is the next symbol in turn to be executed). This SDL Editor window will be used for graphically tracing the execution of the simulator during your simulation session.
  4. If needed, move and resize the Simulator UI and SDL Editor windows so that they both are completely visible and fit on the screen together. A few useful advice are:
    • Before resizing the SDL Editor, you may hide the symbol menu and the text window by using the quick buttons. The editor window will not be used for editing any diagrams, only viewing them.
    • Check and, if required, adjust the SDL Editor's option Always new window to off. (Use the command Editor Options on the View menu for this).
    • You may reduce the width of the Simulator UI window somewhat, which only affects the width of the text area. You may also reduce the height, but you should make sure that all buttons in the left part of the window are still visible.
    • During this simulator tutorial, you will not need to see the contents of the Organizer window. You may cover it, or minimize it by using the window system.
      To determine the transition in turn to be executed, you can look in the editor window. The start state of process Main is selected and the next state symbol is Game_Off. To execute this (empty) transition, you will use the command Next-Transition.
  5. Execute the command Next-Transition by simply entering n-t in the input line. All commands may be abbreviated as long as the abbreviation is unique among all available commands.
    The start transition of Main is now traced in two ways:
    • In the text area, the textual trace information of the transition contains the process instance, the name of the initial state, and the current value of the simulation time. It ends with the Nextstate action, giving the name of the resulting process state:
*** TRANSITION START
* PId : Main:1
* State : start state
* Now : 0.0000
*** NEXTSTATE Game_Off

    • In the SDL Editor, the GR trace selects the next symbol to be executed. Since this is the start state of the process Demon, that diagram is loaded into the editor.
      The next transition is the start transition of Demon, which contains the setting of a timer. To execute it, you can use another feature of the command interface:
  6. Place and click the pointer on the input line and press the arrow key <Up>. The command you entered previously appears (n-t). Execute it by pressing <Return>.
    • You can use the <Up> and <Down> arrow keys repeatedly on the input line to show previously entered commands. This feature is commonly known as a command history. You may also edit a command before it is executed, for instance by changing the value of a parameter.
      The start transition of Demon executes. Also, the SDL Editor sets the selection on the text symbol where the declaration of the timer T is found. This is a convention adopted in the SDL suite to show that the next event to take place in the system, if no signal is sent from the environment, is the expire of a timer.
      Note that the printed trace also contains the action of setting the timer T.

Sending Signals from the Environment

To make something of interest happen in the system you have to send signals from the environment into the system. We will start by sending the signal Newgame to the Main process. For this, you can use the command Output-Via, which takes as parameters a signal name, the parameters of the signal (none in this case), and a channel name.

In this exercise, however, you will execute commands using buttons instead of entering them textually on the input line. The command buttons are arranged into different "modules" in the left part of the Simulator UI. You can "preview" the command that is executed by a button by selecting it and move the mouse pointer away from the button before you release the mouse. The associated command is then listed in the Status Bar at the bottom of the window.

  1. Locate the button module Send Signal and click on the Send Via button.
    This button executes the Output-Via command, as is shown in the text area. A dialog is opened, asking for the value of the first parameter, the signal name. The list contains all signals possible to send from the environment:

Figure 98 : Sending the signal Newgame

  2. Select the signal Newgame and click the OK button.
  3. Another dialog is opened, asking for the channel name.

Figure 99 : Selecting the channel to send via

  4. As there is only one channel from the environment to the system, you do not have to select it explicitly. Simply click the OK button.
    The signal is now sent, which is confirmed in the text area. The GR trace shows that the next symbol to execute is the input of Newgame (in process Main).
  5. Execute the next transition by using the button Transition in the module Execute (this executes the Next-Transition command). The printed trace information shows the actions of the executed transition up until the state Game_On. Note that the start of the transition is described by the combination of a state (Game_Off) and the input of a signal (Newgame):
*** TRANSITION START
* PId : Main:1
* State : Game_Off
* Input : Newgame
* Sender : env:1
* Now : 0.0000
* CREATE Game:1
* ASSIGN GameP := Game:1
*** NEXTSTATE Game_On

Since the process Game was created in the transition, the GR trace shows that the next symbol to execute is the start state of Game. This clearly demonstrates the difference between printed trace and GR trace:
  • The printed trace describes what happened in the previously executed transition, including the initial state and the reached state of the process.
  • The GR trace shows what will happen next, if the system is left on its own. The start symbol of the next transition is selected, which may be in a different process diagram.
  6. Execute the start transition of Game with the Transition button. The Game process reaches the state Losing, and the GR trace changes back to the Demon process. The SDL Editor selection shows again the text symbol with the declaration of the timer T.
  7. Execute the next transition, in order to have the timer expire. This transition is a timer output, i.e., a timer that sends its signal to the process which earlier executed the Set action. A timer output is also considered to be a transition. Note that the simulation time has now been updated to 1:
*** TIMER signal was sent
* Timer : T
* Receiver : Demon:1
*** Now : 1.0000

  8. Execute another transition. The start of this transition is described by the combination of the Generate state and the input of the timer T. The signal Bump is now sent to the Game process:
*** TRANSITION START
* PId : Demon:1
* State : Generate
* Input : T
* Sender : Demon:1
* Now : 1.0000
* OUTPUT of Bump to Game:1
* SET on timer T at 2.0000
*** NEXTSTATE Generate

The GR trace shows the next symbol to be the input of Bump in Game. In the process diagram, note that after the input of Bump, the Game process will be in the state Winning awaiting either the input of another Bump or the input of a Probe signal.
  9. Execute the next transition to put the process Game in the state Winning. The GR trace switches back to the Demon process and indicates the next default behavior which is the expire of the timer T. However, you will instead send the signal Probe from the environment:
  10. Send the Probe signal by using the Send Via button as before. The GR trace switches back to the Game process.
  11. Execute the next transition. The Probe signal is consumed and the signal Win is output to the environment. The process returns to the state Winning and awaits a new Bump (or Probe) signal.
*** TRANSITION START
* PId : Game:1
* State : Winning
* Input : Probe
* Sender : env:1
* Now : 1.0000
* OUTPUT of Win to env:1
* ASSIGN Count := 1
*** NEXTSTATE Winning

We have now shown how you can use the commands Next-Transition and Output-Via to reach a certain point or state in the simulation.


Viewing the Internal Status

In this exercise we will introduce some of the available commands for viewing the internal status of the system. With the graphical user interface, it is also possible to continuously view the internal status without having to execute commands manually.

In the previous exercise, you learned how to interpret the available traces. We will not focus on these details anymore, unless we need to point out some important aspect.

What You Will Learn

  • To restart the simulator without leaving the Simulator UI
  • To use the Command and Watch windows
  • To view and interpret the process ready queue
  • To view the signal input port of a process
  • To view variable values
  • To examine process instances
  • To view active timers

Restarting the Simulator

Before continuing, you need to restart the simulation from the beginning and set the trace level:

  1. Select the Restart command from the File menu.
  2. A dialog informs you that the current simulation will terminate. Confirm this by clicking OK. The text area is cleared and the simulator is now reset.
  3. Set the trace level to 6 and the GR trace level to 1, as before. The easiest way to do this is to use the up arrow key on the input line to find the previous Set-Trace 6 and Set-GR-Trace 1 commands and then hit <Return>.
    • The Simulator UI remembers all previous commands entered on the input line in the same session, even if you have started a new simulator.

Viewing Process and Signal Queues

To view the internal status continuously, the Command window is used. This window shows, if your preferences are set up adequately, the process ready queue and a list of all processes.

This information is displayed in separate "modules" in the Command window by executing suitable monitor commands (List-Ready-Queue and List-Process). These modules are similar to the button modules in the main window.

  1. Select Command Window from the View menu to open the Command window. Resize the window so that both command modules become visible (see Figure 100). Move the window so that you can still see the SDL Editor window and use the main window.

Figure 100 : The Command window

Note:

Whether the Command window shows any commands or not is preference dependent. If the window does not show these command modules at start-up, you may add the commands using the Add Command menu choice from the Command menu and specify each of the commands to add. See Figure 101.

Figure 101 : Specifying a command to add

The command modules show the following information:
  • The List-Ready-Queue command displays the process ready queue, i.e., an ordered list of all processes that are ready to execute a transition. The list contains an entry number (the position in the queue), the process instance, its current state, the number of signals in its input port, and the name of the signal that will cause the next transition. At this stage, both processes (Main and Demon) are to execute their start transition, so no signals are listed.
  • The List-Process command displays a list of all active processes in the system. It shows the same information as the List-Ready-Queue command above (with the exception of the additional "env" process, which represents the environment). At this stage, the two lists are identical.
  2. Execute the next transition and note the changes in the Command window. The Main process is removed from the ready queue since it needs a signal input (Newgame) to execute the next transition, but this signal has not yet been sent. The process list shows the new state of Main (Game_Off).
  3. Execute the next transition. The ready queue is now empty since the Demon process needs an input of the timer signal T, but this timer has not yet expired.
  4. Send the signal Newgame from the environment. The Command window shows that Newgame has entered the signal input port of Main, thus adding Main to the ready queue.
  5. You may also print a list of all signals in the input port of the process in turn to execute. The command for this is not available through a command button. Instead, locate the menu Examine in the menu bar and select the Input Port command. For each signal an entry number (the position in the signal queue), the signal name, and the sender of the signal is printed. The asterisk before the entry number of Newgame indicates that this signal will be consumed by the process in the next transition.

Viewing Variables and Process Instances

Apart from the Command window, you can also continuously monitor variable values by using the Watch window. We will now monitor the variable GameP in process Main to see how its value changes as the process Game is started and later stopped.

  1. Open the Watch window by selecting Watch Window from the View menu. If needed, move it so that you can also see the contents of the Command window.
  2. In the Watch window, select Add from the Watch menu to add a variable to the list of variables to display.
  3. In the dialog, you have to specify both the process (within parenthesis) and the variable name. Enter (Main) GameP and click OK.

Figure 102 : Adding a variable to watch

  4. The value null should now be displayed in the Watch window:

Figure 103 : Adding GameP to the Watch window

If necessary, resize the window so that the value becomes visible.
  5. Execute the next transition and check that the value of GameP in the Watch window changes to the value Game:1 as the process Game is created. Game is also added to the lists printed in the Command window.
  6. You can examine the newly created Game process. The information is printed by giving the command Examine-PId (enter ex-pid on the input line) and contains the current values of Parent, Offspring, and Sender. Parent is Main:1, as expected.
  7. Send the signal Endgame from the environment. Notice that Main is added to the ready queue, but after Game.
  8. Execute the next transition, which is the start transition of Game.
  9. You can now examine the Main process, since it is the next to execute. Give the command Examine-PId again and compare the values printed with those from the Game process.
  10. Execute the two next transitions to stop the Game process. Notice that the value of GameP is reset to null and that Game no more is listed in the Command window.

Other Viewing Options

There are a number of other viewing commands available in the Examine menu. You can list the active timers in the system, check the parameters of signal and timer instances, etc. We will conclude this exercise by showing that the system is not idle, even though the ready queue is now empty.

  1. Check that the timer T is still active by choosing Timer List in the Examine menu. The timer's name, corresponding process instance, and expiration time is printed.
  2. Execute the next transition. Try to examine the timer instance by giving the command Examine-Timer-Instance (enter ex-tim-ins on the input line). You are informed that the timer queue is empty, i.e. the timer T is no longer active.


Dynamic Errors

What You Will Learn

  • To recognize and interpret a dynamic error
  • To find the SDL symbol last executed
  • To continue an interrupted transition

Finding a Dynamic Error

In this exercise, a dynamic error in the Demongame system will be detected. The error is found by simply executing the first four transitions of the system:

  1. Select the Restart command from the File menu.
  2. Set the trace level to 6.
  3. We will not use graphical trace in this exercise. So, exit the currently open SDL Editor from its File menu.
  4. As you will not need the Command and Watch windows, close them by selecting Close All from the View menu.
  5. Execute the four next transitions until a warning message is printed in the text area:
********************* WARNING ********************
Warning in SDL Output of signal Bump
Signal sent to NULL, signal discarded
Sender: Demon:1
TRANSITION
Process : Demon:1
State : Generate
Input : T
Symbol : #SDTREF(SDL,c:\Telelogic\SDL_TTCN_Suite4.4\work\...
TRACE BACK
Process : Demon
Block : DemonBlock
System : Demongame
**************************************************

The message indicates that there was no receiver for the Bump signal sent from the Demon process. This is quite true, as no process instance of type Game has been created. The definition of the Demon game is thus not correct, as it is actually requires that the user always has a game running, when Bump signals are sent. A better (and correct) solution would be to direct the Bump signals from Demon to Main, which then retransmits the signal to the instance of the Game process, if it exists.
  6. When no GR trace is in effect, you can still see where the error occurred. Choose Prev Symbol in the Show menu. This opens an SDL Editor and selects the last symbol that was executed. In this case, the output of Bump in the Demon process.
    After a dynamic error has occurred it is, of course, possible to continue the simulation, both to execute more transitions and to examine the status of the system. Note that the execution was stopped directly after the symbol in which the dynamic error occurred, i.e. the transition was interrupted.
  7. To execute the interrupted transition to its end, issue a Next-Transition command as usual. In the printed trace you can see that no signal was sent in the erroneous output statement.


Using Different Trace Values

The amount of trace information printed during transitions is set by the command Set-Trace. So far, you have used this command to set the trace value to 6. The higher the trace value you set, the more information is printed.

You can also define trace values for different parts of the system. In this way, blocks, process types, process instances, etc. can have different trace values. If a process does not have a trace value defined, the value for the enclosing block is used. If the block does not have a defined value, the value for the next enclosing structure is used, etc. The system always have a trace value defined, which initially is 4.

In this exercise, you will use these facilities to run the demon game and only print trace information for transitions executed by the processes Main and Game. The process Demon will not be traced. This is accomplished by setting the trace value for the system to 0 and the value for the block GameBlock to 6.

The GR trace value will be set to 1 throughout this exercise.

What You Will Learn

  • To set trace values for different parts of a system
  • To list the current trace values
  • To execute the next SDL symbol only
  • To execute a sequence of transitions until trace is printed

Setting Trace Values

The command Set-Trace actually takes two parameters, the name of a unit and a trace value, and assigns the trace value to the unit. To easily specify the unit, you will now execute Set-Trace by using a menu, instead of entering it on the input line.

  1. First, restart the simulator. If needed, resize and move the SDL Editor window that is open.
  2. Locate the Trace menu and select the Text Level : Set entry. In the first dialog, select the unit System Demongame and click OK. In the second dialog, select the trace value 0. Note that all possible trace values (0-6) have a short explanation.

Figure 104 : Setting the trace 0 for System DemonGame

  3. In a similar way, set the trace value for the block GameBlock to 6.
  4. The menu choice SDL Level : Set can be used to set the GR trace value in the same way. Use it to set the trace value for the system DemonGame to 1.
  5. Check that you have set the correct trace values by using the menu choices Text Level : Show and then SDL Level : Show. The following information should be printed:
Default 4 = All SDL actions
System Demongame : 0 = No trace
Block GameBlock : 6 = All SDL actions + Result + Parameters

Default 0 = GR trace off
System Demongame 1 = Show next symbol when entering monitor

Executing Symbol by Symbol

To clearly see that the Demon process is not traced in the text area, we will follow the execution in smaller steps than complete transitions. The smallest execution step possible is one SDL symbol at a time. The command Step-Symbol is used for this.

  1. First, send the Newgame signal from the environment.
  2. Execute the start symbol of Main by clicking the button Symbol (in the Execute module). Note that the printed trace does not include information about the next state (Game_Off) since that symbol has not yet been executed (it is selected to be executed next):
*** TRANSITION START
* PId : Main:1
* State : start state
* Now : 0.0000

  3. Execute the next symbol with the Symbol button. Now, the printed trace gives information about the Game_Off state being reached:
*** NEXTSTATE Game_Off

  4. The execution now continues in the Demon process. Execute the three symbols in the start transition of Demon. Note that no trace is printed in the text area, since Demon is not part of the block GameBlock.
  5. Continue executing the symbols in the Main and Game processes until the Demon process is entered again (you will need to press the Symbol button a number of times; watch the SDL Editor window for monitoring the execution). Note that trace is printed for each symbol.
  6. When the Demon process is entered, you can continue to execute symbol by symbol, or you may execute the complete transition by using the Transition button as usual. No trace is printed.
  7. Stop executing when you are back in the Game process.

Hiding Uninteresting Transitions

If you would continue to execute transition by transition at this point, trace would only be printed while executing the Game process. But, you would still have to manually execute the "silent" transitions in the Demon process. To avoid this, you can use another command,
Next-Visible-Transition. This command executes a sequence of transitions; it stops after it has reached a process with a trace value greater than 0, i.e., when the first "visible" transition is executed. In this way, transitions by uninteresting parts of the system are hidden.

  1. Execute the command by choosing Until Trace in the Execute menu. The execution does not stop until the Game process is entered again and the state Winning (or Losing) is reached. Trace is then printed for the last executed transition.
  2. Repeat the command a number of times. The printed trace shows that you are now switching between the states Losing and Winning in the Game process. The execution in the Demon process is hidden in the printed trace.
    You should note, however, that the GR trace only shows the Demon process. Remember that the GR trace selects the next symbol to be executed, which is always in the Demon process when the Game process has reached the state Winning or Losing. If you want to check where in the Game process you are, do as follows:
  3. Choose Prev Symbol in the Show menu to select the last executed symbol. This should be a state symbol, Winning or Losing, in the Game process.


Looking at the External Behavior

What You Will Learn

  • To use the signal log facility
  • To add command buttons to the Simulator UI
  • To execute transitions up to a certain time value

Setting Trace and Signal Logging

During this exercise, you will look at the external behavior of the system, which is the same as actually playing the Demon game. To achieve this, we will set the system trace to 1. This means that you will see only signals sent to the environment and none of the actions performed during transitions. In order to log the external behavior on a file, you will also use the signal log facility.

  1. As usual, restart the simulator.
  2. Set the trace value for the system to 1.
  3. To log the signals sent to and from the environment, enter the command signal-log in the input line and hit <Return>. (This command has no associated button or menu choice.)
    The Signal-Log command takes two parameters, which are now asked for in dialogs. The first parameter is a unit name. All signals sent to, from or through the specified unit will be logged to file.
  4. Instead of selecting one of the units in the list, enter the unit name env in the dialog's text field and click OK. This is the way to specify the environment of the system.

Figure 105 : Specifying the environment

The second parameter is a the name of a file name to which information about the signals will be written. A file selection dialog is opened.
  5. In the File field, enter the file name signal.log and click OK.

Adding Buttons for Common Commands

When you are playing the Demon game, you are sending signals to the system from the environment. You will start by sending the signal Newgame. Since this is an action often performed in the simulation of this system, we will first define a new button that executes the proper command. In this way, you only need to click the button to send the signal.

  1. In the Send Signal module, select Add from the Group menu to the far right:

Figure 106 : Adding a new button to a module

  2. In the dialog, enter Newgame as the button label, but do not hit <Return>. Enter output-via newgame - as the command definition.

Figure 107 : Adding a button

    • The `-' as the last parameter to Output-Via indicates the default value, in this case for the channel parameter. Specifying `-' as a parameter is the same as just clicking OK in the corresponding parameter dialog.
  3. Click Apply. The new button appears in the module, and the dialog is ready for another button definition.
  4. Since sending the Probe signal also is a common action, add a button Probe in the same way as above.
  5. If you wish, add buttons for the signals Result and Endgame in the same way. Finally, close the dialog with the OK button.
    (If the Error message "Button label must not be empty" occur, just ignore the message.)

Playing the Game

You are now ready to start playing the game. You will use the new buttons to send signals to the game, and the command Proceed-Until to execute transitions up to the next point in time when you want to send a signal.

  1. Send the signal Newgame with a click on the Newgame button.
  2. Execute transitions until the time is 5.5 by selecting Until Time (in the Execute menu). Enter the value 5.5 in the dialog. This executes the command Proceed-Until 5.5. This will execute all transitions up to the point in time when the simulation time first becomes equal to the specified time value.
  3. Send a Probe signal.
  4. Execute transitions until the time is 10.3. Note the output of the signal Win or Lose to the environment.
  5. Send a Probe signal again. Then, send another Probe signal. The two signals will enter the input port of the Game process. Check this by selecting Input Port in the Examine menu:
Input port of Game:1
Entry Signal name Sender
*1 Probe env:1
2 Probe env:1

  6. Send the signal Result. Use the button if you have defined one; otherwise, use the Send Via button or enter the command on the input line.
  7. Execute transitions until the time is 13.5. Note the output of the signals Lose or Win (one for each Probe) and Score to the environment.

Examining the Signal Log File

  1. Exit the simulation by choosing Stop Sim in the Execute menu. This is needed to finish the signal logging. The Simulator UI itself is not closed by this command.
  2. Examine the file signal.log from outside the simulator. The file contains a specification of all signals sent to and from the environment. It should look like this:
Signal log for system Demongame with unit Process env on file ...
0.0000 Newgame from env:1 to Main:1
5.5000 Probe from env:1 to Game:1
5.5000 Win from Game:1 to env:1
10.3000 Probe from env:1 to Game:1
10.3000 Probe from env:1 to Game:1
10.3000 Result from env:1 to Game:1
10.3000 Lose from Game:1 to env:1
10.3000 Lose from Game:1 to env:1
10.3000 Score from Game:1 to env:1
Parameter(s) : -1


Using Breakpoints

The facility of a simulator demonstrated in this exercise is the breakpoint. A breakpoint can be used to stop the execution and activate the monitor system at a certain point of interest. There are four kinds of breakpoints; symbol, transition, output and variable. The first two kinds will be explained in the following.

What You Will Learn

  • To set a breakpoint on an SDL symbol
  • To set a breakpoint on a transition
  • To list all defined breakpoints
  • To graphically trace each executed SDL symbol
  • To get a textual SDT reference to an SDL symbol
  • To continuously execute the system

Setting Up the System

To see where a breakpoint is reached, you will start the execution of the system with the Go command. This command continuously executes transitions until an error occurs, a breakpoint is reached, or the system is completely idle. You should first set up the system in a way suitable for continuous execution:

  1. Restart the simulator.
  2. Set the trace value for the system to 0 to avoid trace information being printed during execution (you may use the Text level : Set entry from the Trace menu to do this) .
  3. Set the GR trace value for the system to 2. Each SDL symbol will then be selected in the SDL Editor as it is executed, allowing you to follow the execution even though no trace is printed.

Setting a Symbol Breakpoint

A symbol breakpoint is set at a specific SDL symbol in the process diagrams. Symbol breakpoints are checked before symbols are executed, i.e. the symbol is not executed when the breakpoint is reached. We will now show how to set a breakpoint on the first task symbol in the Game process, i.e. the initializing of the variable Count to 0.

  1. First, send the signal Newgame (using the new button). This is very important, as otherwise the Game process will not be created and the breakpoint will never be reached!
  2. In the SDL Editor, bring up the Game process diagram from the Diagrams menu.
    • If, for some reason, this diagram is not included in the menu, you have to open it explicitly. Either click the Open quick button and select the file Game.spr, or double-click the Game diagram icon in the Organizer window.
  3. In the Simulator UI, choose Connect sdle in the Breakpoint menu (you may have to resize the window to see the menu). This establishes a connection between the Simulator and the SDL Editor. As a consequence, a new menu Breakpoints appears in the SDL Editor's menu bar (you may have to resize the window to see the menu).
  4. Go back to the SDL diagram and select the task symbol "Count:=0". Then, select the second command Set Breakpoint from the new Breakpoints menu in the editor (the one without trailing dots). The symbol breakpoint is now defined.
    A red "stop" sign is added to the task symbol to indicate the breakpoint. Back in the Simulator UI, the definition of the symbol breakpoint is printed.
  5. Start executing the system by pressing the Go button in the Execute module. Note how the SDL symbols are selected in rapid succession as they are executed. Finally, the breakpoint is reached and the execution stops. The symbol where the breakpoint was set is next to be executed.

Setting a Transition Breakpoint

A transition breakpoint is set at a specific transition in the system. Transition breakpoints are checked before transitions are executed, i.e. the transition is not executed when the breakpoint is reached. We will set a breakpoint in the Demon process, when it is in the state Generate and receives the timer T.

  1. To define the breakpoint, choose Transition in the Breakpoint menu of the Simulator UI. This command takes a number of parameters. In the dialogs that appear:
  2. Select the Demon process and click OK:

Figure 108 : Specifying the process

  3. Leave the instance number empty and click OK:

Figure 109 : Leave the instance number empty

  4. Do not specify a service name; simply click OK:

Figure 110 : Do not specify a service name

  5. Select the Generate state and click OK:

Figure 111 : Specifying the state Generate

  6. Select the timer T and click OK:

Figure 112 : Specifying the timer T

  7. Simply click OK in the remaining dialogs:

Figure 113 : Leaving the remaining dialogs empty

To omit selecting a parameter value is interpreted so that any value, name or number, will match this parameter. In this case, any instance of Demon and any sender will match the breakpoint.
  8. To see how the new breakpoint was defined, list all breakpoints with the Show entry in the Breakpoint menu:
1
Process name : Demon
Instance : any
Service name : any
State : Generate
Input : T
Sender name : any
Sender instance : any
Stop each time

  9. Resume execution of transitions by clicking the Go button. When the breakpoint is reached, you can see that the current state of the system matches the breakpoint definition:
Breakpoint matched by transition
PId : Demon:1
State : Generate
Input : T
Sender : Demon:1
Now : 1.0000


Changing the System

There are a number of commands in the simulator monitor that change the behavior of the system. These commands should be used with care, since it is no longer the original system that is simulated after such a command has been issued. These commands are still useful, especially in debugging situations, for making minor changes so that it is possible to continue the simulation after an error has been detected. They can also be used to force the system into certain situations, that otherwise would require a large number of transitions to be attained.

What You Will Learn

  • To change and add commands in the Command window
  • To create a process manually
  • To change the process scope
  • To change the value of a process variable
  • To change the state of a process
  • To set and reset a timer manually

Some Preparations

In the following two exercises, you will be changing processes and timers. Before continuing, you will set up the simulation and the Simulator UI in a suitable way.

  1. Restart the simulator.
  2. Open the Command window through the View menu. You will now change the commands executed in the Command window. The List-Process command is to be replaced by Examine-PId, and a new command, List-Timer, will be added.
  3. In the List-Process command module, select Edit from the Command menu to the far right. (This menu works in the same way as the Group menu in the button modules.)
  4. In the dialog, change the command to examine-pid and click OK.
  5. Go to the Command window's menu bar and select Add Command from the Command menu. In the dialog, enter the command list-timer and click OK.
  6. A new command module is added to the window. Resize the window so that all three modules are visible.
    • You may also reduce the number of text lines displayed in a module by selecting Size from the module's Command menu. In a dialog, you can set the number of lines with a slider.

Figure 114 : Adjusting the number of lines

  7. Set the system trace value to 6 to get full trace.
  8. Execute the two first transitions so the processes Main and Demon are started.
  9. If the GR trace in the SDL Editor window makes it difficult to see the output in the Command window, set the system GR trace to 0.

Creating a Process

In this exercise, we will put the system in the state it would be in after the reception of a Newgame signal. This will be accomplished without actually sending the signal. Instead, we will manually create an instance of process type Game, using the Create command.

  1. Create the Game process by selecting the Create Process entry (in the Change menu). Select the process Game, and click OK.
  2. In the next dialog, select the parent process Main and click OK. This sets up the Parent-Offspring link between the process instances.

Figure 115 : Creating the process Game from process Main

To complete the actions taken when a Newgame signal is received, you must also set the GameP variable in Main, and put Main in the state Game_On. This is done with the commands Assign-Value and Nextstate. However, these commands operate on the process next to execute, which at this stage is Game, as can be seen in the ready queue printed in the Command window.

Figure 116 : The Ready Queue

Next process to execute is Game.

Therefore, you first have to change the current process, also known as the process scope.
  3. Change the scope by selecting Set Scope in the Examine menu. Select the process Main in the dialog and click OK.
    The Examine-PId command in the Command window shows that Main is the current process. The variable GameP must be set to the value of Offspring in Main. In the Command window, check that this value is Game:1.

Figure 117 : Process Main is the current process

The Offspring of the current process is Game:1.

  4. Assign the GameP variable by selecting Variable in the Change menu. In the dialogs that follow, select the variable GameP, and enter the PId value Game:1.
  5. To put the Main process in the correct state, use the State entry in the Change menu. Select the state Game_On and click OK.
    The system is now in exactly the state it would be in after the reception of a Newgame signal. Even though you have changed the process scope, the next transition to be executed is still the start transition of Game. (You can check this by viewing the process ready queue. See Figure 116.)
  6. Execute the next transition and check that the Game process is started.

Changing the State of Timers

In this exercise, we will execute Set and Reset actions on timers directly in the monitor system. At this stage, the timer T is active, as it has been set by the Demon process. You can check this by looking at the List-Timer module in the Command window.

Figure 118 : The timer T is active

  1. Reset the timer by choosing Reset Timer in the Change menu. Select the timer T and click OK.
  2. Try to execute the next transition and note the message printed:
No process instance scheduled for a transition

The system is now completely idle, i.e., there are no transitions in the system that can be executed. The Command window shows that both the ready queue and the timer queue is empty. To restart the system you must perform a set operation on timer T in process Demon.
  3. Choose Set Timer in the Change menu, select the timer T and enter a time value of 10.
  4. Execute the next transition and check that the timer was set at time 10 (look at the trace in the main window).
*** TIMER signal was sent
* Timer : T
* Receiver : Demon:1
*** Now : 10.0000


Generating Message Sequence Charts

In this exercise, we will demonstrate the power of Message Sequence Charts as a method of illustrating, in a graphical way, the dynamic behavior of the system. This can easily be done when simulating the system by using MSC trace. MSC trace transforms some of the SDL events that take place into MSC events; typically sending of signals and dynamic creation of processes. The trace can then be graphically logged in an MSC Editor during the execution.

Earlier in this tutorial, you drew a Message Sequence Chart which illustrated a simple sequence of messages. We will now run the simulator and generate the MSC trace of the events which actually take place.

What You Will Learn

  • To start and stop logging of MSC events
  • To trace back from an MSC to an SDL diagram

Initializing the MSC Trace

  1. Restart the simulation.
  2. Make sure the GR trace is disabled to avoid having the SDL Editor window being updated and raised (select the SDL Level : Show entry in the Trace menu and verify that system GR trace is 0).
    By default, the MSC trace is enabled for the entire system. You must, however, explicitly start the interactive logging of MSC events:
  3. Choose MSC Trace : Start in the Trace menu. A dialog is issued, where you are prompted to specify the amount of symbols to include in the MSC trace. You will include states in the MSC trace, so select 1 and click OK.

Figure 119 : Specifying to include states in the MSC trace

  4. An MSC Editor is opened, displaying an MSC diagram named "SimulatorTrace." If needed, move and resize the window to make it fit on the screen together with the Simulator UI.
    • Before resizing the MSC Editor, you may hide the symbol menu and the text window by using the quick buttons. You should not edit the generated MSC, so there is no need for these windows.
      Initially, the system has three active instances, the processes Main_1_1 and Demon_1_2, as well as env_0 which has been introduced in order to represent the environment to the system:

Figure 120 : The initial appearance of the MSC

Tracing the Execution in the MSC

  1. Send the signal Newgame from the environment. This is now displayed in the MSC Editor as a message sent from the instance env_0.
    At this stage, the message is connected to the instance Main_1_1, since it has not yet been consumed. Instead, the message is temporarily drawn as a "lost" message, indicated by the filled circle. You may also see the text "Main_1_1" associated with the circle, indicating the intended receiver of the message.

Figure 121 : The sent Newgame signal

  2. Execute the next transition. A condition symbol with the text Game_Off appears on the instance axis for the process Main. This symbol shows that the process has started executing and has reached the corresponding SDL state, Game_Off.

Figure 122 : The Condition symbol

  3. Execute the next transition. The timer T is set in the Demon process. The vertical coordinate is incremented downwards in the MSC, enhancing the impression of an absolute order of events. Also, a condition symbol with the text Generate is drawn on the instance axis.
  4. Execute the next symbol only (use the Symbol button). The Main process consumes the Newgame message; the filled circle disappears. Note that the start point and the end point of the message have different vertical positions, since the timer T was set after the message was sent.
  5. Execute the next symbol. An instance of the Game process is created, thus adding a new instance head and instance axis. The MSC should now look like this:

Figure 123 : The MSC after creating the Game process

  6. Execute the next transition by clicking the Transition button twice. The second transition causes the Game process to enter the state Losing.
  7. Execute the next three transitions. The timer signal T is consumed and the signal Bump is sent and consumed. The Game process is now in the state Winning. Note how the signal interchange is shown in the MSC.
  8. Next we illustrate a message which is consumed immediately. Send the signal Probe from the environment and execute the next transition. First, the message Probe is displayed (marked with filled circle), then it is redrawn, keeping its horizontal alignment.
  9. The system responds with the signal Win.
  10. Send the signal Result and execute the next transition. In the MSC, you can see that the message Score has the parameter 1.
  11. End the game by sending the Endgame signal and execute the next two transitions. The Game process is stopped.

The MSC should now look like in the figures below. (You may note a dotted horizontal line in the MSC diagram on screen. This indicates where a page break will occur if you would print out the diagram.)

Compare this diagram with the one in Figure 90. You will notice differences between the hand-drawn and the generated diagram. These discrepancies are quite natural, since it is impossible to predict the dynamic behavior of a system just by looking at the SDL diagrams.

Figure 124 : The finished MSC 1(2)

Figure 125 : The finished MSC 2(2)

Trace-Back to SDL Diagrams

From the generated MSC diagram, you may obtain a trace back to the SDL source diagrams.

  1. From the MSC Editor's Window menu, select Info Window. A window is opened, containing information about the graphical object which is currently selected. (The amount and type of information depends on what sort of object you have selected.)

Figure 126 : The Info window

The window shows information related to the message Bump.

  2. Select a few different objects in the MSC Editor and note how the information in the Info window changes.
  3. Select the message Bump and click on the button Show SDL Symbol in the Info window. An SDL Editor is opened, in which the symbol corresponding to the actions of sending or consuming the SDL signal Bump is selected:
    • If you have selected the message Bump by clicking on a point which is closer to the start point of the message than to the end point, the corresponding SDL output symbol will be selected.
    • Otherwise, the corresponding SDL input symbol will be selected.

Ending the MSC Trace

  1. Stop the logging of MSC events by selecting the MSC Trace : Stop entry in the Trace menu.
  2. In the MSC Editor, save the generated MSC diagram under the file name SimulatorTrace.msc.
  3. Exit the MSC Editor.


The Coverage Viewer

In this final exercise of the SDL Simulator, you will learn to use the Coverage Viewer. The Coverage Viewer is a graphical tool that shows how much of a system has been covered during a simulation in the terms of executed transitions or symbols. By checking the system coverage, you can for instance see what parts of the system that have not been executed in the simulation so far.

What You Will Learn

  • To create a coverage file
  • To start the Coverage Viewer
  • To interpret and change the coverage tree information
  • To open a more detailed coverage chart
  • To exit the Simulator UI

Starting the Coverage Viewer

  1. Restart the simulator.
  2. Send the signal Newgame. Execute seven (7) transitions until the printed trace shows that the Game process is in the state Winning.
  3. Send the signal Probe and execute the next transition.
    Let us see how much of the system we have executed so far. By simply starting the Coverage Viewer from the Simulator UI, the current coverage information is displayed.
  4. Select Coverage from the Show menu. The main window of the Coverage Viewer is opened.

Using the Coverage Viewer

  1. If a symbol coverage tree is displayed, switch to a transition coverage tree by clicking on the Tree Mode quick button.
  2. To see all of the transition coverage tree, click on the All Nodes quick button.

Figure 127 : A transition coverage tree

Only a part of the tree is depicted.

    • Since the coverage tree is quite large, you may maximize the window (by using the window manager) while working with the Coverage Viewer. When returning to the Simulator UI, you can simply restore the size of the window to its original size.
    • Alternatively, you may also zoom out the window contents with a number of clicks on the quick button.
      The coverage tree shows the diagram structure of the Demongame system. Beneath each process diagram (Main, Game, Demon), you see all possible transitions in that process, defined by a state and the possible signal inputs from that state. The start transitions are represented by an SDL start symbol.
      The number below each symbol in the tree is the number of times the symbol has been executed so far. In addition, each symbol is filled with a gray pattern to indicate to what extent it has been executed. Parts of the system that never have been executed have a zero value and "empty" symbols. Parts that have been completely traversed by the execution so far have a non-zero value and completely filled symbols.
      From the displayed tree, you can find out the following information:
    • In the states Losing and Winning, one out of four transitions have been executed. Thus, these state symbols are filled to 1/4.
    • In the Main process, two out of three transitions have been executed. Thus, the process symbol is filled to 2/3.
    • In the Demon process and the block DemonBlock, all transitions have been executed at least once. Thus, these symbols are completely filled.
    • In the system as a whole, a little more than half of all possible transitions have been executed.
  3. To only see those transitions that never have been executed, click on the Least quick button. You can now see which signals must be sent in which states to execute the rest of the system
    • The Least quick button actually shows those symbols that have been executed the least number of times. The symbols that are dashed are present only to make the structure complete.
  4. In the same way, to only see those transitions that have been executed at least once, click on the Most quick button. You can now see which signals have been sent so far in the system.
    • The Most quick button actually shows those symbols that have been executed the most number of times. In this case, no transition has been executed more than once.
  5. To see the whole tree again, click on the All Nodes quick button. If you want to see a transition in the SDL Editor, just double-click on one of the signal input symbols or start state symbols. Try this!
    The Coverage Viewer can also show a symbol coverage tree, i.e. how many times each SDL symbol in the process diagrams have been executed:
  6. Switch to a symbol coverage tree by clicking on the Tree Mode quick button. Beneath each process diagram, you will now see a small icon for each SDL symbol. To see which SDL symbol an icon represents, double-click the small icon.
  7. Switch back to a transition coverage tree and go back to the Simulator UI.

Augmenting the Coverage

  1. Execute three more transitions to put the Game process in the state Losing again.
  2. Send the signal Result. Execute four more transitions to return to state Winning.
  3. Send the signal Endgame. Execute two more transitions to stop the Game process.
  4. Check the current system coverage in the Coverage Viewer by selecting Coverage from the Show menu.
  5. Change to a transition coverage tree and show All Nodes. As you can see, the Main process has now been completely executed. The Losing and Winning states are also more filled.
  6. To see what transitions have still not been executed, you can click the Least quick button. If, however, you click the Most quick button you will only see the most executed transition (and other symbols), i.e. the input of timer T, not all transitions that have been executed.
  7. To see more of the tree, select Increase Tree from the Tree menu. The input of Bump should now be added. Select the command again and all remaining executed transitions should be added.

Looking at Coverage Details

  1. Select the system diagram in the Coverage Viewer. From the Tools menu, select Show Details, or click the quick button for this. The Coverage Details window is opened.
    The displayed coverage chart shows how many transitions that have been executed a certain number of times. The chart should contain four bars:

Figure 128 : The Coverage Details window

  2. Select the bars one at a time and look at the text in the Status Bar at the bottom of the window. You will now see how many transitions that have been executed 0, 1, 2 and 3 times. To see which transitions that have not been executed at all, do as follows:
  3. Select the "zero bar" furthest to the left. Click the Show Editor quick button. The SDL Editor is opened, showing the three transitions in the Game process that remain to be executed.
    • If the transitions can be found in more than one diagram, a confirmation dialog is issued between each diagram that is opened. Simply click OK to see the transitions in the next diagram.
  4. Select another symbol in the coverage tree in the main window. The Coverage Details window is now updated to show the coverage chart for that symbol.
  5. "Play around" in the Coverage Viewer as much as you like. You should note, however, that the Demongame system is a bit too simple to give full justice to the power of the Coverage Viewer.

Exiting the Simulator UI

You will now close down the Simulator UI.

  1. First, exit the Coverage Viewer from the File menu.
  2. Then, exit the Simulator UI from the File menu. You will be asked whether to save the changes to the sets of variables in the Watch window, commands in the Command window, and buttons in the button area. If you choose to save them (with the suggested file names), they will become the default the next time you start the Simulator UI from the same directory.


So Far...

You have now learned how to "animate" an SDL system by generating, executing and tracing a simulator.

If your configuration includes the Validator tool, we suggest that you proceed with the exercises on the Validator. These exercises start in 5 Tutorial: The SDL Validator.

In all cases, the example you have been practising on, the system DemonGame, is rather simple. To deepen your knowledge of the SDL suite, you may practise on a number of exercises that illustrate the advantages of SDL-92 when adopting an object-oriented design methodology. These exercises are described in 6 Tutorial: Applying SDL-92 to the DemonGame.


5 Tutorial: The SDL Validator

The SDL Validator is the tool that you use for validating the behavior of your SDL systems, using state space exploration techniques. In this chapter, you will practice "hands-on" on the DemonGame system.

To be properly assimilated, this tutorial therefore assumes that you have gone through the exercises that are available in 3 Tutorial: The Editors and the Analyzer as well as 4 Tutorial: The SDL Simulator.

In order to learn how to use the Validator, read through this entire chapter. As you read, you should perform the exercises on your computer system as they are described.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the essential validation functionality in the SDL suite. With validation we mean exploring the state space of an SDL system with powerful methods and tools that will find virtually any kind of possible run-time errors that may be difficult to find with regular simulation and debugging techniques.

This tutorial is designed as a guided tour through the SDL suite, where a number of hands-on exercises should be performed on your computer as you read this chapter.

We have on purpose selected a simple example that should be easy to understand. It is assumed that you have a basic knowledge about SDL -- this chapter is not a tutorial on SDL.

It is assumed that you have performed the exercises in 3 Tutorial: The Editors and the Analyzer as well as 4 Tutorial: The SDL Simulator before starting with the tutorial on the Validator.

Note: C compiler

You must have a C compiler installed on your computer system in order to validate an SDL system. Make sure you know what C compiler(s) you have access to before starting this tutorial.

Note: Platform differences

This tutorial, and all tutorials that are possible to run on both the UNIX and Windows platform, are described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc. When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.
Normally, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see when running the SDL suite in your environment. Only if a screen shot differs in an important aspect between the platforms will two separate screen shots be shown.


Generating and Starting a Validator

In addition to simulating a system, it is also possible to validate the system using the SDL Validator. A validator can be used to automatically find errors and inconsistencies in a system, or to verify the system against requirements.

In the same way as for a simulator, you must generate an executable validator and start it with a suitable user interface.

Note:

In order to generate a validator that behaves as stated in the exercises, you should use the SDL diagrams that are included in the Telelogic Tau distribution instead of your own diagrams. To do this:
  • On UNIX: Copy all files from the directory
    $telelogic/sdt/examples/demongame
    to your work directory ~/demongame.
  • In Windows: Copy all files from the directory
    C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame
    to your work directory
    C:\Telelogic\SDL_TTCN_Suite4.4\work\demongame    .
If you generate a validator from the diagrams that you have created yourself, the scheduling of processes (i.e. the execution order) may differ.
If you choose to copy the distribution diagrams, you must then re-open the system file demongame.sdt from the Organizer.

What You Will Learn

  • To quickly generate and start an executable validator

Quick Start of a Validator

A validator can be generated and started in the same way as described earlier for the simulator, i.e., by using the Make dialog and the Tools menu in the Organizer. However, we will now show a quicker way.

  1. Make sure the system diagram icon is selected in the Organizer.
  2. Click the Validate quick button. The following things will now happen, in rapid succession:
    • An executable validator is generated. Messages similar to when generating a simulator are displayed in the Status Bar, ending with "Analyzer done." This is the same action as manually using the Make dialog and selecting a validator kernel. If you like, you can verify that a validator kernel has been used by looking at the tail of the Organizer log.
    • A graphical user interface to the validator is started. The status bar of the Organizer will read "Validator UI started." This is the same action as manually selecting Validator UI from the Tools menu.
    • The generated validator is started. The Validator UI shows the message "Welcome to SDL VALIDATOR." This is the same action as manually using the Open quick button and selecting the executable validator (named demongame_xxx.val (on UNIX), or demongame_xxx.exe (in Windows), where the _xxx suffix is platform or kernel/compiler specific).

Note:

If you receive errors from the Make process (in the Organizer Log window) or if no Validator is started, do as follows:
  • Open the Make dialog and change to a Validation kernel reflecting the C compiler used on your computer system, e.g.
    gcc-Validation or Microsoft Validation.
  • Click the Full Make button and check that no errors where reported.
  • Click the Validate quick button again. A Validator should now be started as described above.

The Validator UI looks like this:

Figure 129 : The main window of the Validator UI

As you can see, the graphical user interface of a validator is very similar to a simulator GUI, which you have learned to use in the previous exercises. However, the button modules to the left are different and a few extra menus are available.

A validator contains the same type of monitor system as a simulator. The only difference is the set of available commands.

When a validator is started, the static process instances in the system are created (in this case Main and Demon), but their initial transitions are not executed. The process in turn to be executed is the Main process. You can check this by viewing the process ready queue:

  1. Locate the button module View in the left part of the window, and click the Ready Q button. The first entry in the ready queue is Main, waiting to execute its start transition.
    • If the View module appears to be empty, you have to click the toggle button to the left of the module's name. The button module is then expanded. You may collapse and expand any button module by using these toggle buttons:

Figure 130 : A collapsed button module

    • The buttons in the View module execute the same type of commands as those in the Simulator UI.
  2. If required, resize the Validator UI window so that all button modules are visible. You may also reduce the width of the text area. In the exercises to come, you will have a number of windows open at the same time.

Basics of a Validator

Before you start working with the validator exercises, you should have an understanding about the basic concepts of the SDL Validator.

  • When examining an SDL system using the validator, the SDL system is represented by a structure called a behavior tree. In this tree structure, a node represents a state of the complete SDL system. The collection of all such system states is known as the state space of the system.
  • By moving around in the behavior tree, you can explore the behavior of the SDL system and examine each system state that is encountered. This is called state space exploration, and it can be performed either manually or automatically.
  • The size and structure of the behavior tree is determined by a number of state space options in the validator. These options affect the number of system states generated for a transition in an SDL process graph, and the number of possible branches from a state in the behavior tree.


Navigating in a Behavior Tree

In this first exercise, we will explore the state space of the Demongame system by manually navigating in the behavior tree. The validator will then behave in a way similar to when running a simulator. However, there are also important differences, which will be pointed out.

By default, the validator is set up in a way that results in a state space as small as possible. In this set-up, a transition between two states in the behavior tree always corresponds to a complete transition in the SDL process graphs. Also, the number of possible branches from a state is limited to a minimum.

What You Will Learn

  • To use the Navigator tool
  • To get printed trace and GR trace

Setting Up the Exploration

When interactively exploring the behavior tree, a validator tool called the Navigator is used.

  1. Start the Navigator by clicking the Navigator button in the Explore module. The Navigator window is opened:

Figure 131 : The Navigator tool

The Navigator shows part of the behavior tree around the current system state. In general, the upper box represents the behavior tree transition leading to the current state, i.e., the transition that just has been executed. The boxes below represent the possible tree transitions from the current state. They are labelled Next 1, Next 2, etc. and have not yet been executed.
Since the system now is in its start state, there is no up node. The only next node is the start transition of Main.
  2. To be able to see the printed trace familiar from simulation, open the Command window from the View menu. (The trace is not printed in the main window of the validator.)
  3. To switch on GR trace of SDL symbols, select Toggle SDL Trace from the Commands menu in the Validator window; SDL trace is now enabled. However, an SDL Editor will not be opened until the first transition is executed.

Using the Navigator

  1. In the Navigator, execute the next transition by double-clicking on the Next 1 node. The following happens, in order:
    • In the Navigator, the Up 1 node shows the just executed transition, while the Next 1 node shows the next possible transition, the start transition of Demon. You have now moved down to a system state in the next level of the behavior tree.

Figure 132 : The last and next transition

    • An SDL Editor is opened and the symbols that were just executed becomes selected. Note the difference compared to the simulator, where the SDL Editor instead selects the next symbol to be executed.
    • The Command window shows the printed trace for the executed transition, the start transition of Main (you may have to scroll or resize the window to see the trace):

Figure 133 : The printed trace for the executed transition

  2. If needed, move and resize all opened windows to make them completely visible and still fit on the screen together.
  3. Double-click the Next 1 node to execute the next transition. The start transition of Demon is traced in the Command window and in the SDL Editor.
    At this stage, neither of the two active processes can continue without signal input: Main awaits the signal Newgame from the environment, and Demon awaits the sending of the timer signal T. These are the two transitions from the current state now shown in the Navigator as Next 1 and Next 2. As you can see, the transitions in the boxes are described by the same type of information as in a printed trace.

Figure 134 : Transition descriptions in the Navigator

This means that the validator gives information of all possible transitions from the current system state, even though they have not been executed yet. (This information cannot easily be obtained when running a simulator.)
  4. Send the timer signal by double-clicking the Next 2 node. The Command window tells us that the timer signal is sent and the Navigator shows that the next transition is the input of the timer T.
  5. Execute the next transition by double-clicking the Next 1 node. This is where the dynamic error in the Demongame system occurs, as explained in the simulator tutorial earlier (see "Dynamic Errors" ). Instead of showing the next transition, the Navigator displays the error message in the next box.

Figure 135 : The dynamic error

    • The error message can also be found in the tail of the Command window, if you scroll the Print-Trace module.

Figure 136 : The tail of the Print-Trace module

We cannot go further down this branch of the behavior tree, since a reported error by default truncates the tree at the current state. Instead, we will back up to the state where we could select the output of Newgame.
  6. Double-click the Up 1 node to go back to the previous state. Repeat this action again to go to the state we were in after step 3 above. This way of backing up in the execution is not possible when running a simulator, as you may have noticed when running the Simulator tutorial.
    You should also note that the Next 2 node is marked with three asterisks "***." This is used to indicate that this is the transition we have been backing up through:

Figure 137 : Marking a transition that has been backed through

  7. Execute the Next 1 transition instead. The printed trace shows that the signal Newgame was sent from the environment. The Main process is ready to receive the signal. Note that you do not have to send the signal yourself; this is taken care of automatically by the validator.
  8. Execute the next transition. The printed trace and the SDL trace show that Main now is in the state Game_On. The Navigator displays the start transition of the newly created Game process.
  9. Execute the start transition of Game. The Navigator will now show the different signal inputs that are required to continue execution: Endgame, Probe, Result, and the timer T.

Figure 138 : Signal inputs required for continued execution

If the number of transitions from a state is large, it may be difficult to see them all in the Navigator when a tree structure is used. To overcome this problem, you can change the display to a list structure.
  10. Click the Toggle Tree quick-button to see how the list structure looks like. Now it is easier to see the possible signals.

Figure 139 : The list structure

  11. Change back to the tree structure.
    We will not continue further down in the behavior tree in this exercise. Figure 140 shows the part of the behavior tree we have explored so far. The nodes in the figure represent states of the complete SDL system. Each node lists the active process instances that have changed since the previous system state, what process state they are in and the content of their input queues. The arrows between the nodes represent the possible tree transitions. They are tagged with a number and the SDL action that causes the transition. The arrow numbers are the same numbers as printed in the Next nodes in the Navigator.
    Note that this is a somewhat different view of the behavior tree compared to the Navigator. In the Navigator, the nodes represent the tree transitions and the process states are not shown.

Figure 140 : A Demongame behavior tree


More Tracing and Viewing Possibilities

In this exercise, we will take a look at some of the additional tracing and viewing possibilities of the validator.

What You Will Learn

  • To print a complete trace from the start state
  • To use the view commands
  • To use the MSC trace facility
  • To go to a state by using the path commands

Using the View Commands

  1. Make sure you are still in the same state as after the last step in the previous exercise.
    To see a complete printed trace from the start state to the current state, you can use the Print-Trace command. As parameter, it takes the number of levels back to print the trace from.
  2. On the input line of the Validator UI, enter the command pr-tr 9 (you can use any large number). The trace is printed in the text area of the main window. This trace gives an overview of what has happened in the SDL system so far.
  3. The SDL Validator supports the same viewing possibilities as the SDL Simulator. Click the Timer List button in the View module to list the active timer set by the Demon process.
  4. Examine the GameP variable in the Main process by first setting the scope to the Main process (click the Set Scope button and select the Main process), and then clicking the Variable button and selecting the GameP variable.
    • You may also use the Watch window in the validator to continuously monitor the values of variables.

Using MSC Trace

In addition to textual and graphical traces, the validator can also perform an MSC trace.

  1. First, turn off SDL trace by selecting Toggle SDL Trace from the Commands menu. Then, turn on MSC trace from the same menu. An MSC Editor is opened, showing a Message Sequence Chart for the trace from the start state to the current state.
    • You may also close down the SDL Editor to avoid having too many windows on-screen.

Figure 141 : The current MSC trace

  2. When the MSC appears, execute, with a double-click, one of the signal transitions in the Navigator, e.g. Probe. The message is appended to the MSC (but it is not yet consumed).
  3. Go up a few levels in the Navigator.
    Note how the selection in the MSC Editor changes to reflect the MSC event corresponding to the current state!
  4. Go down again, but select a different path than before, i.e., send one of the other signals.
    Note how the MSC diagram is redrawn to show the new behavior of the system!
  5. Toggle MSC trace off in the Commands menu. Unless other MSC diagrams were opened, the MSC Editor is closed.

Going to a State Using Path Commands

You can use the commands Print-Path and Goto-Path to return to a state where you have been before.

  1. Execute the command Print-Path from the input line. The output represents the path taken in the behavior tree from the start state to the current state.
Command : print-path
1 1 1 1 1 3 0
    • The numbers in the path are the same as the transition numbers in the Navigator, and the arrow numbers shown in Figure 140.
  2. Go up a few levels in the Navigator.
  3. In the text area, locate the path printed by the Print-Path command above (you may have to scroll the text area). On UNIX, select the numbers in the path with the mouse by dragging the mouse to the end of the line. Make sure you select the final zero.
  4. In the input line, enter goto-path and the path printed by the Print-Path command. On UNIX, paste in the path numbers by positioning the mouse pointer at the end of the entered text and clicking the middle mouse button.
  5. Hit <Return> to execute the command. You now end up in the previous state.
    • If you make an error while entering the path numbers, you can clear the input line by using the <Down> arrow key and try again.


Validating an SDL System

In the previous exercises, we have navigated manually in the behavior tree. We have also found an error situation by studying the Navigator and the printed trace in the Command window.

In this exercise, we will show how to find errors and possible problems by automatically exploring the state space of the Demongame system. This is referred to as validating an SDL system.

What You Will Learn

  • To perform an automatic state space exploration
  • To examine reported errors using the Report Viewer
  • To change state space and exploration options
  • To restrict the state space without affecting the behavior
  • To check the system coverage of an exploration
  • To use user-defined rules
  • To perform a random walk exploration

Performing a Bit State Exploration

Automatic state space exploration can be performed using different algorithms. The algorithm called bit state exploration can be used to efficiently validate reasonably large SDL systems. It uses a data structure called a hash table to represent the system states that are generated during the exploration.

An automatic state space exploration always starts from the current system state. Since we want to explore the complete Demongame system, we must first go back to the start state of the behavior tree.

  1. Go to the top of the tree by clicking the Top button in the Explore module.
  2. Start a bit state exploration by clicking the Bit-State button. After a few seconds, a tool called the Report Viewer is opened. We will soon describe this window; in the meantime, just move it away from the main window.
  3. For a small system such as Demongame, the exploration is finished almost immediately and some statistics are printed in the text area. They should look something like:
** Starting bit state exploration **
Search depth : 100
Hash table size : 1000000 bytes

** Bit state exploration statistics **
No of reports: 1.
Generated states: 2569.
Truncated paths: 156.
Unique system states: 1887.
Size of hash table: 8000000 (1000000 bytes)
No of bits set in hash table: 3642
Collision risk: 0 %
Max depth: 100
Current depth: -1
Min state size: 68
Max state size: 124
Symbol coverage : 100.00

Of the printed information, you should note the following:
  • Search depth : 100
    The search depth limits the exploration; it is the maximum depth, or level, of the behavior tree. If this level is reached during the exploration, the current path in the tree is truncated and the exploration continues in another branch of the tree. It is possible to change the search depth by setting an option in the Validator UI.
  • No of reports: 1.
    The exploration found one error situation. This error will be examined in the next exercise.
  • Truncated paths: 156.
    The maximum depth was reached 156 times, i.e., there are parts of the behavior tree that were not explored. This is a normal situation for SDL systems with infinite state spaces. Demongame is such a system, since the game can go on forever.
  • Collision risk: 0 %
    The risk for collisions was very small in the hash table that is used to represent the generated system states. If this value is greater than zero, the size of the hash table may have to be increased by setting an option; otherwise, some paths may be truncated by mistake. This situation will not occur in this tutorial.
  • Symbol coverage : 100.00
    All SDL symbols in the system were executed during the exploration. If the symbol coverage is not 100%, the validation cannot be considered finished. This situation will occur in a later exercise.

Examining Reports

The error situations reported from a state space exploration can be examined in the Report Viewer. The Report Viewer window displays the reports in the form of boxes in a tree structure.

Figure 142 : The Report Viewer

  • The top box shows how many reports there are (in this case only one).
  • On the next level in the report tree, there is one box for each type of report, stating the number of reports of that type.
  • On the next level, it is possible to see the actual reports. However, this level of the tree is by default collapsed, indicated by the small triangle icon below the report type boxes.
  • To expand the report, double-click on the report type box Output. You will now see a box reporting the error we have found manually earlier. In addition, the tree depth of the error situation is shown.

Figure 143 : An expanded report

If you look in the Navigator and Command windows, you can see that the validator is still in the start state of the system, even though a state space exploration has been performed. We will now go to the state where the error has occurred.
  2. Double-click the report box in the Report Viewer. The following things will now happen:
    • The printed trace of the error situation is displayed in the text area of the Validator UI and in the Command window.
    • The Navigator moves to the error state and displays the error.
    • An MSC Editor is opened, showing the MSC trace to the current state. You can see that the signal Bump was not received by any process, since the Game process has not yet been created. You should move the MSC Editor window so that it does not cover the other windows.
      Once you have used the Report Viewer to go to a reported situation, you can easily move up and down the path to this state. Simply use the Up and Down buttons in the Explore module, instead of double-clicking a node in the Navigator:
  3. Move up two steps by using the Up button. Of the two transitions possible from this state, the one that is part of the path leading to the error is indicated by three asterisks "***" (see Figure 137). This is the transition chosen when using the Down button.
  4. Move up to the top of the tree (click the Top button in the Explore module). Move down again to the error by using the Down button repeatedly.
    Note that you do not have to chose which way to go when the tree branches. The path to the error is remembered by the validator until you manually chose another transition.

Exploring a Larger State Space

We will now run a more advanced bit state exploration, with a different setting of the state space options. This will make the state space much larger, so that more error situations can be found.

  1. Go back to the top of the behavior tree (use the Top button).
  2. In the Options1 menu, select Advanced. This sets a number of the available state space options in one step, as you can see by the commands executed in the text area:
Command : def-sched all

Command : def-prio 1 1 1 1 1

Command : def-max-input-port 2
Max input port length is set to 2.

Command : def-rep-log maxq off
No log for MaxQueueLength reports

Note that the Navigator now shows two possible transitions from the start state; this is an immediate effect of the larger state space.
  3. In addition, we will increase the search depth of the exploration from 100 (the default) to 300. From the Options2 menu, select Bit-State: Depth. In the dialog, enter 300 and click OK.

Figure 144 : Specifying Depth = 300

Since the behavior tree becomes much larger with these option settings, the exploration will take longer to finish. We will therefore show how to stop the exploration manually.
  4. Start a new bit state exploration. In the text area, a status message is printed every 20,000 transitions that are executed. Stop the exploration after one of the first status messages by pushing the Break button in the Explore module. The text area should now display something like this:
*** Break at user input ***

** Bit state exploration statistics **
No of reports: 2.
Generated states: 50000.
Truncated paths: 1250.
Unique system states: 21435.
Size of hash table: 8000000 (1000000 bytes)
No of bits set in hash table: 41557
Collision risk: 0 %
Max depth: 300
Current depth: 235
Min state size: 68
Max state size: 168
Symbol coverage : 100.00

Note:

If the exploration finishes by itself before you have had a chance to stop it manually, redo this exercise from step 1. but increase the search depth even more, e.g. 400 or 500.

Note the following differences in the printed information compared to the previous exploration:
  • No of reports: 2.
    The exploration found an additional error situation. This is an effect of more transitions being able to execute from each state in the behavior tree.
  • Max depth: 300
    Current depth:     <number>
    The exploration was at the printed depth in the behavior tree at the moment it was stopped. However, since the exploration uses a depth-first algorithm, the maximum depth of 300 was reached at an earlier stage. The exploration may be continued from the current depth if you wish to explore the remaining parts of the behavior tree.
  5. In the Report Viewer, open the two report type boxes to see both reports with a double-click on each. The Report Viewer window should now look something like:

Figure 145 : The two reports as displayed in the window

  6. For now, just note on which depth each of the reported situations occurred; do not double-click any of the reports. (The depths may be different from the ones shown in the figure.)
  7. Continue the exploration by clicking the Bit-State button again. A dialog is opened, asking if you would like to continue the interrupted exploration or restart it from the beginning.

Figure 146 : Continuing the exploration

  8. In the dialog, select Continue and click OK. Wait for the exploration to finish by itself.
  9. In the Report Viewer, open the two reports again. Note that the depth values have changed. This is because only one occurrence of each report is printed; the one found at the lowest depth so far.
  10. Go to the state where an unsuccessful create of the Game process was reported (double-click the Create report).

Figure 147 : The report about an unsuccessful process create

  11. To see what caused the unsuccessful create, look at the MSC trace.
    At the receipt of the last Newgame signal, the Main process attempts to create a Game process. However, the already active Game process has not yet consumed the previous GameOver signal, and has therefore not been terminated. Since you cannot have more than one instance of the Game process in the Demongame system, the process create could not be executed!

Restricting the State Space

The Validator makes it possible to limit the state space in several different ways. We will now explore one of these methods that in many cases is very efficient. This is done by using the Define-Variable-Mode command.

This command is used to instruct the Validator to ignore certain variables when matching states during the state space exploration. The mode can for each variable be set to either "Skip" or "Compare". The implication of setting the mode to "Skip" is that the search may be pruned even if a new state is encountered during the search. This happens if the only difference between the new state and a previously visited state is that the values of some of the skipped variables are different.

We will now apply this to our DemonGame system. The variable Count in the Game process keeps track of the current score for the game, and the value of this variable does not have any real impact on the behavior of the system. So, we will now instruct the validator to ignore this variable when performing a search.

  1. Go to the top of the tree by clicking on the Top button.
  2. Enter the command define-variable-mode in the command line in the Validator UI, select the Game process in the first dialog, the Count variable in the second dialog and Skip in the last dialog. You have now instructed the Validator to ignore the Count variable.
  3. Start a bit state exploration by clicking on the Bit-State button. (Select to Restart the exploration if a dialog is opened.)
  4. When the search stops compare it with the previous exploration. The only difference between the two explorations is that the second one ignores the Count variable. However, while the first exploration took a long time to finish, the second one only took a few seconds! The printed statistics show very small numbers in comparison.

The lesson to learn from this is that it in many cases it is possible to drastically reduce the time needed for explorations by checking the variables in the system. Look for variables that do not have any impact on the behavior (i.e. that does not influence decision statements or the expression used in an "output to" statement). Also look for variables that do not change their value during the exploration. This can for example be arrays that are initialized at system start up but then never changes (or at least not changed in the intended exploration). The mode for these types of variables should be set to "Skip".

Checking the Validation Coverage

If the symbol coverage after an automatic state space exploration is less than 100%, the Coverage Viewer can be used to check what parts of the system that have not been executed. To attain a symbol coverage less than 100% for the Demongame system, we will set up the exploration in a special way.

  1. Go to the top of the tree.
  2. First, we need to restore the smaller, default state space. Select Default from the Options1 menu. Note that the Navigator changes back to display only a single possible transition from the top node.
  3. To avoid reaching all system states, we will reduce the search depth of the exploration from 100 to just 10. Use the Bit-State: Depth menu choice from the Options2 menu and specify a maximum depth of 10.
  4. Start a bit state exploration. The printed statistics should now inform you that the symbol coverage is about 82%.
    • If the symbol coverage still is 100%, select Reset from the Options1 menu and repeat steps 3 and 4 above.
  5. To find out which parts of the Demongame system that have not been reached, open the Coverage Viewer from the Commands menu.
    A symbol coverage tree is displayed, showing all symbols which have not been executed yet.
  6. Change to a transition coverage tree by clicking the Tree Mode quick-button.

Figure 148 : The transition coverage tree

You can now see that none of the transitions from the state Winning in the Game process has been executed. To explore this part of the system in the validator, you can go to the state Winning and start a new exploration from there. How to do this is explained in the following exercises.

Going to a State Using User-Defined Rules

To go to a particular system state, you could use the Navigator to manually find the state by studying the transition descriptions and the printed trace in the Command window. This can be both tedious and difficult, especially for larger systems than Demongame. Instead, we will show an easier way: by using a user-defined rule.

When performing state space exploration, the validator checks a number of predefined rules in each system state that is reached. It is when such a rule is satisfied that a report is generated.

In this exercise, we will show how to define a new rule to be checked during state space exploration. The rule will be used to find the state Winning in the Game process.

  1. Make sure you still are at the top of the behavior tree.
  2. Define a new rule by selecting Define Rule from the Commands menu. In the dialog that appears, enter the rule definition
    state(Game:1)=Winning

Figure 149 : Specifying a new rule

This very simple rule says that the state of the process instance Game:1 must be equal to Winning. By defining the rule, a report will be generated when a state space exploration reaches a state that satisfies the rule.
  3. Start a bit state exploration. Since we have not changed any of the options since the last exploration the same statistics will be printed, with the exception that an additional report is generated.
  4. From the Report Viewer, go to the reported situation where the user-defined rule was satisfied. You have now reached the first place in the behavior tree where the Game process is in the state Winning.
  5. We now instruct the validator to use this state as the root of the behavior tree. To do this, enter the command define-root on the input line and select Current in the dialog.

We can now change options, define a new rule or load an MSC. These new settings will then be used in all explorations based on the new root. Also all list/goto-path commands will use the path from the new root and the MSC trace will give the trace from the new root.

  6. Before continuing, do not forget to clear the user-defined rule. To do this, enter the command clear-rule on the input line.

In our case we will only clear the rule and start another type of state space exploration from this state; a random walk.

Performing a Random Walk

Apart from bit state exploration, there is another exploration method known as random walk. A random walk simply explores the behavior tree by repeatedly choosing a random path down the tree. This is mainly useful for SDL systems where the state space can be very large. But also for a small system like Demongame, it can be as effective as other exploration methods.

  1. Start a random walk exploration from the current state by clicking the Random Walk button. From the printed statistics, you can see that the symbol coverage now has become 100%.
  2. Load the Coverage Viewer with the new coverage information by selecting Show Coverage Viewer from the Commands menu. Change to transition coverage and display the whole tree. Note that all transitions have executed a large number of times. When the exploration selects a random path down the tree, there is no mechanism to avoid that already explored paths are explored once more. Therefore, the same transition may be executed any number of times
  3. Exit the Coverage Viewer from the File menu.
  4. Reset the system by selecting Reset from the Options1 menu. You are now back at the top of the tree, and the root of the tree is reset to the original root, the start state of the system.


Verifying a Message Sequence Chart

Another main area of use for a validator is to verify a Message Sequence Chart. To verify an MSC is to check if there is a possible execution path for the SDL system that satisfies the MSC. This is done by loading the MSC and performing a state space exploration set up in a way suitable for verifying MSCs.

What You Will Learn

  • To verify an MSC

Verifying a System Level MSC

In this exercise, we will verify one MSC made on the system level, i.e., an MSC that only defines signals to and from the environment. The name of the MSC file is SystemLevel.msc and is located in the same directory as the remaining files for the DemonGame example. The MSC is shown in the figure below.

Figure 150 : A system level MSC

  1. Reset the system. This time do it by choosing Restart in the File menu. Choose "No" if you are asked to save options. The Restart command will actually terminate the running Validator and start it again.
  2. Start an MSC verification by clicking the Verify MSC button. A file selection dialog is opened, in which you select the MSC to verify.
  3. Select SystemLevel.msc and click OK. A state space exploration is now started, which is guided by the loaded MSC.
    In the printed statistics, note that the exploration is completed without any truncated paths. This is because the loaded MSC restricts the size of the behavior tree; only the parts dealing with the events in the MSC are executed. The maximum depth of it is not more than 20.
    Note the line that tells if the MSC was verified or violated:
** MSC SystemLevel verified **

In this case the MSC was verified, i.e., the behavior described in the MSC was indeed possible. In the Report Viewer, however, one (or two) of the reports is a violation of the loaded MSC, while the other one is a verification of the MSC. The exploration may very well find states that violate the MSC; it is the existence of states that verify the MSC that determines the result of the verification.

Figure 151 : Violations and verifications of the MSC

  4. Go to the state where the MSC was verified. The printed trace in the Command window shows that the Main process has received the Endgame signal, and sent the GameOver signal to the Game process:
* OUTPUT of GameOver. Receiver: Game:1
* Signal GameOver received by Game:1

  5. Take a look at the MSC trace and compare it with the loaded MSC in Figure 150. Note that the loaded MSC only defines signals to and from the environment and therefore is less detailed than the MSC trace. An MSC trace in the validator is always made on the process level.

Figure 152 : The MSC trace

The trace in the figure does not show the condition symbols that indicates the state of the processes.

Exiting the Validator UI

The first part of the validator tutorial is now finished. Close the validator windows in the following way:

  1. To close the Navigator and the Report Viewer, click the Close quick button in these windows.
  2. To close the Command window, select Close from the File menu.
  3. Exit the Validator UI from the File menu. You may be asked in a dialog whether to save changes to the Validator options.

Figure 153 : Saving changed options

  4. If you select Yes and click OK, the option settings are saved in a file called .valinit (on UNIX), or valinit.com (in Windows). This file is read each time the Validator UI is started from the same directory, or when the validator is restarted or reset from the Validator UI. You should select No and click OK.


Using Test Values

In this final exercise we will explore the test value feature in the Validator. This feature is used to control the way the environment interacts with the system during state space exploration. In practise, the test values define what signals will be sent from the environment to the system, including the exact values of their parameters.

In this part of the Validator tutorial we will use another SDL system, the Inres system.

  1. Copy the Inres system from the installation to a working directory of your own. Copy all files from the directory $telelogic/sdt/examples/inres (on UNIX), or
    C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\inres     (in Windows).

What You Will Learn

  • To examine and use the automatically generated test values
  • To manually change the test values

Using the Automatic Test Value Generation

When the Validator is started, test values for a number of SDL sorts are automatically generated. For example, all integer parameters will have the test values -55, 0 or 55. We will now take a look at the automatically generated test values for the Inres system.

  1. Open the Inres system file from the Organizer's File menu. If any part of the existing DemonGame system needs saving, you are first prompted to do so before the Open file dialog appears. Locate the file inres.sdt that you have copied and open it.
  2. Generate and start a Validator for the system by clicking on the Validate quick button; see "Quick Start of a Validator" for more information. If you are asked in a dialog whether to start a new Validator UI or use an existing one, select the existing validator in the list and click OK.
  3. Expand the Test Values button module in the Validator UI and make the window bigger so you can see all the buttons.
    The button module contains four rows of buttons. The top three buttons List Value, Def Value And Clear Value make it possible to define test values for each sort (data type) in the SDL system. The middle row with the buttons List Par, Def Par and Clear Par handles test values for specific signal parameters. The bottom rows handles test values for entire signals.
  4. Click on the List Value button to see what default test values have been generated. The following values should be listed:
Sort integer:
0
-55
55

Sort Sequencenumber:
zero
one

Sort IPDUType:
CR
CC
DR
DT
AK

As you can see, there were test values defined for the predefined sort integer and for two system specific enumerated sorts Sequencenumber and IPDUType. For enumerated types, all the values will by default be used as test values if there are 10 or less values. Note that only sorts that appear on parameters to signals to or from the environment are listed.
  5. Click on the List Signal button to see what signals will be sent to the system based on the test values for the sorts.
    You should now see a list of signals similar to the following. Note that there might be differences in the parameters to the MDATreq signal since this is computed using a random function that is depending on the compiler used.
ICONreq
IDATreq(0)
IDATreq(-55)
IDATreq(55)
IDISreq
MDATreq((. CR, zero, -55 .))
MDATreq((. CR, zero, -55 .))
MDATreq((. CC, one, 55 .))
MDATreq((. AK, one, 55 .))
MDATreq((. CR, one, 55 .))
MDATreq((. DT, one, -55 .))
MDATreq((. CC, one, 0 .))
MDATreq((. CC, one, -55 .))
MDATreq((. AK, one, 55 .))
MDATreq((. DR, one, 0 .))

The signals ICONreq and IDISreq have no parameters so there will only be one signal definition for each of these signals. The IDATreq signal has one integer parameter, and as you can see there will be three test values for this signal, one for each of the test values for the integer sort.
The MDATreq signal takes a parameter that is a structure with three fields: one IPDUType, one Sequencenumber and one integer. Whenever the Validator finds a structure, it tries to generate test values for the sort based on all combination of test values for each field. However, if the number of test values is larger than a maximum value, a randomly chosen subset is used instead. The maximum number is by default 10, but can be changed with the Define-Max-Test-Values command.
The consequence of this is that for the MDATreq signal, 10 different randomly chosen parameter values are generated.
Now, let us check how the test values influence the behavior of the system during state space exploration.
  6. Start the Navigator by clicking on the Navigator button in the Explore button module.
  7. Double-click on the down node 4 times (until there is more than one alternative down node).
    You should now have a choice between 11 different down nodes that each one represents an input from the environment to the SDL system. If you check the inputs more carefully, you will see that these 11 inputs correspond to the test values defined for the signals ICONreq and MDATreq.
    This is the way the test values have an impact on the state space exploration. Whenever a signal can be sent from the environment to the system, the Validator uses the test values defined for the signal to determine what parameters to use when sending the signal.

Changing the Test Values Manually

Now, we will use the other commands in the Test Values button module to manually change the test values.

  1. Click on the Top button in the Explore module to return to the start state in the state space.
    First we will change the test values for integer to only test the values 1 and 99.
  2. Click on the Clear Value button, select the integer type in the dialog and give the value `-' (a dash) in the value dialog. Dash indicates that we would like to remove all test values currently defined for the sort.
    Note that the Validator tries to recompute test values for various sorts and signals when you have changed the test values for integer. Since integer is used in a number of other sorts and signals, the Validator is now unable to compute test values for these sorts and signals.
  3. Check the signal definitions that now is used by clicking on the List Signal button. The current signal definitions should now be:
ICONreq
IDISreq
Since there are no test values for integer, only the signals that does not contain integer parameters are listed. In this case this means that only ICONreq and IDISreq would have been sent to the system from the environment if you would start an exploration.
  4. Click on the Def Value button, select integer in the sort dialog and give the value 1 in the value dialog.
  5. Click on the Def Value button once more. Select integer in the sort dialog again, but this time give the value 99 in the value dialog.
  6. Click on the List Signal button to check the signal definitions and make sure that the signals with integer parameters are once again on the list. This time with the test values 1 and 99.
ICONreq
IDATreq(1)
IDATreq(99)
IDISreq
MDATreq((. AK, zero, 1 .))
MDATreq((. DR, zero, 99 .))
MDATreq((. AK, one, 1 .))
MDATreq((. DR, one, 1 .))
MDATreq((. DR, zero, 99 .))
MDATreq((. AK, zero, 1 .))
MDATreq((. AK, one, 99 .))
MDATreq((. AK, zero, 99 .))
MDATreq((. AK, one, 1 .))
MDATreq((. CR, one, 1 .))

You have now explored some on the most frequently used test value features in the Validator. There are also possibilities to set test values for specific parameters and to enumerate all signal definitions manually. You can find more information about this in the section "Defining Signals from the Environment.

Exiting the Validator

To exit the Validator follow the same steps as before:

  1. Select Exit from the File menu.
  2. Choose Yes when asked whether you want to save the new options or not. To select Yes in this dialog implies that commands that recreates your new test value definitions will be saved in the file .valinit (on UNIX) or valinit.com (in Windows).


So Far...

By practicing this and the previous tutorials, you have learned the basics of the SDL suite and we hope you have enjoyed the "tour". The examples you have been practising on, the DemonGame and Inres systems, are however rather simple. To deepen your knowledge about the SDL suite components, you may practise on a number of exercises that illustrate the advantages of SDL-92 when adopting an object-oriented design methodology. These exercises are described in 6 Tutorial: Applying SDL-92 to the DemonGame.


6 Tutorial: Applying SDL-92 to the DemonGame

This tutorial will teach you how to take advantage of the object-oriented extensions that have been added to SDL, also known as SDL-92. The example that has been selected for this purpose is the well known DemonGame, which you should have already practiced on, in the previous tutorials presented in 3 Tutorial: The Editors and the Analyzer and 4 Tutorial: The SDL Simulator.

In order to learn how to take advantage of the object oriented extensions in SDL, read through this entire chapter. As you read, you should perform the exercises on your computer system as they are described.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the essential object-oriented SDL functionality in the SDL suite tools. This tutorial is designed as a guided tour through the SDL suite, where a number of hands-on exercises should be performed on your computer as you read this chapter.

We have on purpose selected a simple example that should be easy to understand. It is assumed that you have a basic knowledge about SDL -- this chapter is not a tutorial on SDL.

The example is DemonGame, which was used in the earlier tutorials in this volume. It is assumed that you have performed the exercises in 3 Tutorial: The Editors and the Analyzer as well as 4 Tutorial: The SDL Simulator before starting with this tutorial.

Note: Platform differences

This tutorial, and the others that are possible to run on both the UNIX and Windows platform, are described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc. When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.
Normally, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see when running the SDL suite in your environment. Only if a screen shot differ in an important aspect between the platforms will two separate screen shots be shown.


Applying SDL-92 to the DemonGame

In the previous tutorials, you have practiced using some of the basic language elements in SDL; all of these elements were already defined in the non-object-oriented version of SDL, known as SDL-88.

To introduce SDL-92 to you, we have prepared a number of exercises in which you will add features to the DemonGame. You will do this by redefining and adding properties to the process Game in an object-oriented fashion.

We will introduce the following SDL-92 language constructs:

  • Process types
    • Inheriting process types and adding properties
    • Virtual and redefined process types
    • Virtual and redefined transitions
  • Packages
    • Using packages
    • Reusing packages
  • Block types
    • Inheriting block types and adding properties.

Note:

In this chapter, the term SDL-92 denotes the object-oriented SDL that was introduced in the 1992 version of the language. These object-oriented features remain unchanged in SDL-96.


Some Preparatory Work

Instead of continue working on the original DemonGame system, we suggest you to continue from a version that is better designed for introducing SDL-92. The changes that have been made are the following:

  • All signals from the environment (Newgame, Endgame, Probe, -Result) are now directed to the administrating process Main, that will send them further to the Game process, if there is such a process.
  • The Bump signal is also sent to the process Main, which in turn transfers it to the Game process. This eliminates the annoying behavior when a signal is sent to a nonexisting receiver.
  • Signal routes and signal lists have been updated to reflect the new routing of signals.
  • The internal signal GameOver is really not necessary and is therefore replaced by the signal EndGame.

From the user's point of view, the system will show the same functionality as before, but is more robust.

The new versions of the block GameBlock and the process Main are depicted below, in Figure 154 and Figure 155.

To use the new version:

  1. Make a new empty directory sdl92 of your own (under ~/demongame on UNIX, and under
    C:\Telelogic\SDL_TTCN_Suite4.4\work     in Windows).
  2. Copy all files in the directory $telelogic/sdt/examples/demongame/sdl92/process_type (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame\sdl92\process_type (in Windows), to this new directory.

Note: Installation directory

On UNIX, the Telelogic Tau installation directory is pointed out by the environment variable $telelogic. If this variable is not set in your UNIX environment, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for instructions on how to set this variable correctly.
In Windows, the Telelogic Tau installation directory is assumed to be C:\Telelogic\SDL_TTCN_Suite4.4 throughout this tutorial. If you cannot find this directory on your PC, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for the correct path to the installation directory.

  3. Start the SDL suite and open the system file -demongame.sdt in this new directory with the Organizer. (You will find copies of the diagrams building up the complete system).

You should recognize the system DemonGame, with the modifications as described above.

Nearly all versions of the diagrams shown in the following exercises are available in the directory you created above. You can either draw a diagram to learn how to use SDL-92 in the SDL Editor, or copy (or connect to) the pre-made version of the diagram if you do not wish to do this.

Figure 154 : The block GameBlock, redesigned

The exact layout of your diagrams may differ slightly from the above.

Figure 155 : The process Main, redesigned

The exact layout of your diagrams may differ slightly from the above.


Creating a Process Type from a Process

What You Will Learn

  • To change a process diagram to a process type
  • To refer to and instantiate a process type
  • To interconnect the process type with a block and other processes (types), using gates
  • To define transitions as virtual

Changing into a Process Type

To facilitate the introduction of new features, we will start by generalizing the process Game, by changing it to a process type, that you later on will be in a position to specialize or redefine.

  1. Open the process Game and change the diagram type from process to process type, simply by selecting the diagram heading symbol and editing the text in it to say "Process Type Game".

Figure 156 : Changing the diagram type

  2. From the SDL Editor's File menu, save the diagram Process Type Game on a new file, e.g. new_game.spt using the Save As command. Edit the file name in the file selection dialog and click OK. (The existing *.spt files are copies of the complete system that comes with the examples in the SDL suite.)
  3. Raise the Organizer window.

Figure 157 : Invalid reference as shown in the Organizer

You may notice that the reference symbol has been changed to -Process Type Game, and marked as having no reference in the parent diagram. Also, the old process Game is marked as unconnected. Do not bother about that for the moment - it will be replaced by an instantiation symbol, which will be explained later.
  4. Open the diagram block GameBlock. Change it so that the process reference Game is changed to an instantiation of the process type Game. The syntax is: "Game(0,1):Game" (You are allowed to add newlines to have the text fit into the symbol.)
    • Before you have started text editing, the text cursor is not flashing. Pressing <Delete> at this stage deletes the whole selected symbol. Once text editing has started, the text cursor is flashing and pressing <Delete> only deletes a character.
  5. As soon as you deselect the symbol, one text rectangle appears for each connection point to the signal routes. Name the connections points for instance G2 and G5:

Figure 158 : Naming the connection points

  6. Also add a process type reference symbol with the name Game. The block diagram should now look like this:

Figure 159 : The resulting block

  7. Save the block diagram on a new file, e.g. new_gameblock.sbk (use Save As as before).

Inserting Gates and Virtual Transitions

You will now finish the process type Game. You are recommended to do this by following the editing instructions described below. If you prefer, you can instead connect to the finished version of the diagram (see "Connecting to the Finished Diagram" ), but you should in any case read through the text below.

Editing the Process Type Diagram

  1. Go back to the process type Game in the SDL Editor. The connection to the signal routes must be defined using gate symbols, named in accordance to the connection points you just defined.
  2. Gate symbols are to be connected to the frame symbol. If you want to connect gates to the left or top of the frame, you must first select the frame and drag it down and/or right.

Figure 160 : Adjusting the frame symbol

  3. For each of the gates G2 and G5, add a gate symbol and fill in the name and the signal list.
    • The gate symbol is the one who looks like an arrow. Remember that the Status Bar displays the type of a symbol when you point to or select it in the symbol menu.
    • To direct a gate to the frame, you must add a gate, then -Redirect it. (Gates can also be made bidirectional.)
    • You may use the New Window command to bring both the -Process Type Game and the Block GameBlock into view at the same time, then Copy and Paste the text between the diagrams.
    • You may also take advantage of the Signal Dictionary window, and Insert the signals from the block GameBlock (Up).
  4. Also make the start transition as well as the input of the signals Probe and Bump virtual by adding the text "VIRTUAL" before the name of the signal.
    • By doing this, you will later on be able to change the properties of the game in a smooth way.

The changes to the resulting diagram should now look something like this:

Figure 161 : The resulting process type Game

Connecting to the Finished Diagram

The finished Game process type diagram is also available as the file game.spt. If you instead of drawing the diagram wish to use this file, do as follows:

  1. In the SDL Editor, close the Game process type diagram.
  2. In the Organizer, select the diagram Process Type Game, and then select Connect from the Edit menu.
  3. Select the option To an existing file. Change the filename to game.spt, or select this file by using the folder button.
  4. Click Connect and check the new file connection in the Organizer.

The Organizer Structure

  1. Save everything. The resulting Organizer list should now resemble:

Figure 162 : Resulting Organizer view

Note the presence of an instantiation symbol, looking like a normal symbol, but with the generic "X:Y" (meaning -instance:type) notation in it. The instantiation symbol denotes that the type is actually instantiated somewhere in the diagram.
Instantiation symbols in the Organizer cannot be used for navigating into the system hierarchy with a double click, since they do not refer to diagrams. (You can use them from within the SDL Editor with the support from the Type Viewer tool, which you will practice on later in this tutorial).
  2. Terminate by analyzing the system. Correct any syntactic or semantic errors that are reported.


Redefining the Properties of a Process Type

What You Will Learn

  • To have a process type inherit properties from another process type
  • To redefine transitions in a process type

The Process Type JackpotGame

So far, you have redesigned the original functionality of the system -DemonGame, using a slightly different design. Next step will be to add a feature that allows you to win the "jackpot", with a probability of 10%. The jackpot is arbitrarily set to increase the score by 10. A simple implementation of this could be to create a pseudo random number generator that returns a sequence of numbers from 0 to 9, and to check the random number upon the reception of the signal Probe.

It should also be possible to specify what kind of game to start at run-time, meaning that we need an additional input signal from the environment, NewJackpotGame, that will start the JackpotGame; that new signal requires additions to the process Main and the system diagram.

The JackpotGame is implemented as a process type that inherits the properties of the process type Game, and adds the random number feature by redefining the transitions that handle the signal Bump. The pseudo random generator is activated upon each reception of the signal Bump. See below.

Figure 163 : The process type JackpotGame

  • Create the diagram above and save it on a new file (new_jackpotgame.spt for instance). Then close the diagram in the SDL Editor (Close Diagram from the File menu).
    • This diagram is also available as the file jackpotgame.spt, if you wish to make a copy (or use it as is) instead of drawing the diagram.

Changes to the Block GameBlock

To make the process type JackpotGame available from the parent block, you simply add a process reference symbol and a process instantiation symbol, as you did before with the process type Game. You also add a signal NewJackpotGame to the signal list to the process Main.

Figure 164 : The block GameBlock

  • Update the existing diagram GameBlock according to above and save it on file.
    • This version of the diagram is also available as the file gameblock2.sbk. To use it instead of drawing the diagram, close the GameBlock diagram in the SDL Editor, and connect the GameBlock diagram in the Organizer to the new file. (Use Connect in the Edit menu and the option To an existing file.)

Changes to Process Main and System DemonGame

The process Main and the system DemonGame need to be extended with the declaration of the signal NewJackpotGame and the code to receive the signal and create an instance of the game JackpotGame:

Figure 165 : The extensions to process Main and system DemonGame

  1. Update the diagrams Main and DemonGame according to the figure above and save them on file. You may want to save the diagrams on new files, e.g. new_demongame.ssy and new_main.spr.
    • This version of the Main diagram is also available as the file main2.spr, if you wish use it instead of editing the diagram. In the Organizer, connect the diagram to the new file (from the Edit menu).
    • The DemonGame diagram has to be edited manually - do not re-connect it to an existing file.
  2. In the Organizer, make sure that the process type diagram JackpotGame is connected to the file new_jackpotgame.spt that you created earlier. (If not, use Connect in the Edit menu and the option To an existing file.)

The resulting Organizer list should now look like this:

Figure 166 : JackpotGame added to Organizer list

Simulating the JackpotGame

To understand the resulting system, you may want to spend a few minutes simulating it.

  1. First analyze the system and generate a simulator, as you learned from the tutorial on the simulator. Then open the generated simulator in the Simulator UI.
  2. We suggest that you check the following features:
    • It should be possible to start one instance of Game or of -JackpotGame at run-time using the NewGame/NewJackpotGame signals, but not to have two games running at the same time. (Use the command output-via to send the signals NewJackpotGame, Newgame and EndGame via C1, in order to start and stop the game).
    • Even if we do not have any game started, the signal Bump no longer causes any dynamic error, since there is always a receiver (Main).
    • Turn the graphical MSC trace on, to visualize how the signalling is done. Also turn the graphical SDL trace on. Verify that the execution takes place in the graphs for both the process types Game and JackpotGame, even if you have started a JackpotGame! (You may have to execute at symbol level to catch this.)
  3. Play the game in a realistic way.
    • First, create a button in the Simulator UI with the name Probe, that sends the signals Probe and then Result, then resumes the execution with the command Go. Each time you click this button, the Score is returned. (The button definition should contain output-to Probe Main; output-to Result Main; go)

Figure 167 : Defining the button Probe

    • Then, set the trace for the system to 1, meaning that only signals to/from the environment are traced. If required, turn all graphical traces off, in order to speed up the execution: -
      set-gr-trace 0; stop-msc-log
    • Send the signal NewJackpotGame and run the simulator:
      output-to NewJackpotGame Main; go
    • Click repeatedly the Probe button and watch the trace. You should win 10 points every now and then.
  4. Stop the execution with the Break button.


Adding Properties to a Process Type

What You Will Learn

  • To inherit a process type and add properties
  • To use dashed gates.

The Process Type DoubleGame

Even with a "jackpot" feature, winning "a lot" with the DemonGame takes some time... Suppose now that you would like to add a function that doubles the "stake" of the game, whenever you want, so that you have the possibility to win more.

A way to do this is to:

  1. Create a process type DoubleGame, that inherits the properties of the process type Game, with the following additions:
    • Declaration of a variable Stake of type integer.
    • Initialization of Stake to 1, by redefining the start transition.
    • Reception of a signal DoubleStake that doubles the value of Stake.
    • Redefinition of the transitions Winning and Losing to add/deduct the current Stake from the score Count.
  2. The resulting graph is depicted below. Create it in the same way as you have learned from the previous exercises, and save it on the file new_doublegame.spt. Then close the diagram in the SDL Editor (Close Diagram from the File menu).
    • This diagram is also available as the file double.spt, if you wish to make a copy (or use it as is) instead of drawing the diagram.

Note:

The diagram contains a dashed gate symbol G5, where the signal DoubleStake is conveyed. You use dashed gates to refer to gates that are already defined in the supertype (the type that you inherit from), to distinguish from situations where you have to add a new gate.
To dash a gate:
  • Make sure the gate is selected.
  • Select the Dash command from the Edit menu of the SDL Editor (this command toggles between Dash/Undash).

Figure 168 : The process type DoubleGame

  3. Add a process type reference symbol DoubleGame, and a process instantiation symbol with the text "DoubleGame (0,1):DoubleGame" to the block diagram GameBlock; see below.
    • This version of the diagram is also available as the file gameblock3.sbk. To use it instead of drawing the diagram, close the GameBlock diagram in the SDL Editor, and connect the GameBlock diagram in the Organizer to the new file.
  4. Also add the signals NewDoubleGame and DoubleStake to the signal list on the signal route R1, and DoubleStake to the signal list to the process -DoubleGame; see below.

Figure 169 : The resulting block GameBlock

  5. Add the new signals NewDoubleGame and DoubleStake at the system level (in the DemonGame diagram), both in the signal declaration, and in the signal list on the channel C1.
    • You have to make these changes yourself.
  6. Extend the process Main with the code to receive the signal -DoubleStake, and the code to receive the signal NewDoubleGame and create an instance of the game DoubleGame; see below.
    • This version of the Main diagram is also available as the file main3.spr, if you wish use it instead of editing the diagram. In the Organizer, connect the diagram to this file.

Figure 170 : New code in process Main

  7. If needed in the Organizer, connect the process type diagram DoubleGame to the file new_doublegame.spt that you created earlier.

Simulating the DoubleGame

You may simulate the DoubleGame in a similar way as the -JackpotGame (the DoubleGame is started with the signal -NewDoubleGame).

  1. To play the game in a realistic way, also add a button Double to the Simulator UI, with the text "Double" and the command
    Output-to DoubleStake Main; go
  2. Try for instance the following tactic: whenever your score is negative, double the stake.


Combining the Properties of Two Process Types

What You Will Learn

  • To work with the Type Viewer (the "class browser" in the SDL suite)
  • To inherit process types in more than one level

So far, you have created a basic version of the game (the supertype process type Game), and extended it as two subtypes (the process types JackpotGame and -DoubleGame). To assist you in understanding the inheritance and instantiation of types, the SDL suite is provided with a "class browser", the Type Viewer.

Working with the Type Viewer

  1. Open the Type Viewer with the command Type Viewer from the Organizer's Tools > SDL menu.
    The Type Viewer is started and displays two windows: the main window, where all types are listed, and the Type Trees, where the inheritance and instantiation of the types is visualized.

Figure 171 : The two windows of the Type Viewer

The main window displays a list of all types and instances that exist in your current system. When selecting an object in the main window, the Type Trees window is updated to show the inheritance tree for that type.

Figure 172 : The inheritance tree for the process type Game

Figure 172 shows an inheritance tree for the process types Game, -JackpotGame and DoubleGame. We have one level of inheritance, as depicted above. You can also note that the Type Viewer keeps track about the types that have been instantiated somewhere in the SDL system.

    • You may go to the source SDL graphs and find the declarations and instantiations of the types by double clicking the symbols in the Type Viewer.

How to Work-Around the Lack for Multiple Inheritance

Say that you would like to design a new game where both the "jackpot" and the "double" features are supported. As SDL-92 does not support multiple inheritance, we cannot simply create a SuperGame that inherits JackpotGame and DoubleGame. Instead, we will have to inherit from, i.e. reuse, the JackpotGame or the DoubleGame, and then redefine/add some of the properties. (The idea is to rewrite as little code as possible).

Which one should we reuse as is? The code for the DoubleGame seems to be still valid for the SuperGame. So, let us inherit that process type, and redefine some of the properties in accordance to the JackpotGame.

To create the SuperGame:

  1. Open the process type JackpotGame in the SDL Editor, and Save As on a new file, e.g. -new_supergame.spt
    • This diagram is also available as the file supergame.spt, if you wish to make a copy (or use it as is) instead of drawing the diagram. In that case, continue with step 6. below.
  2. Rename the diagram to process type SuperGame.
  3. Change the inheritance from "INHERITS Game" to "INHERITS -DoubleGame".
  4. Update the contents of the graph, in order to:
    • Change the branch Winning/Probe so that you add Stake instead of 1 to Count when winning, and reward you with 10 times the value of Stake when winning the jackpot.
    • Redefine the transition Losing/Probe so that you deduct Stake instead of 1 from Count.

Figure 173 : The changes to the process type SuperGame

  5. If the Process Type JackpotGame has become unconnected in the Organizer, re-connect it to the file used earlier (new_jackpotgame.spt).
  6. Also add a process type reference symbol with the name -SuperGame in the diagram GameBlock. In the Organizer, then connect the newly added process type diagram SuperGame to the file new_supergame.spt that you created earlier.
  7. You may check the impact of the changes above in the Type Viewer. Save everything and the select Update from the Type Viewer's File menu (since the Type Viewer does not automatically update its content when you make changes to a diagram). Your inheritance tree should now look like this:

Figure 174 : The process type SuperGame, added

  8. If you want to be able to play the SuperGame, you must also add a process instantiation symbol "SuperGame(0,1):SuperGame" in the GameBlock, and add a signal NewSuperGame that starts the game (in a similar fashion as you did in the JackpotGame and the DoubleGame). Do not forget to update the system diagram.
    • These versions of the diagrams are also available as the files gameblock.sbk and demongame.ssy, if you wish use them instead of editing the diagrams. In the Organizer, connect the diagrams to the new files. A complete and final system file, demongame_sdl92.sdt, is also available, with connections to the final SDL diagrams.


Using Packages and Block Types

What You Will Learn

  • To create a package diagram
  • To use a package in a system
  • To refer to and instantiate a block type
  • To define a process type as virtual

Package - a Reusable Component

Packages are used to make type definitions available in different systems, and to make components reusable. You will take advantage of the package concept by developing two versions of the DemonGame, one that has only the basic "Probe" feature, and one that also includes the "Jackpot" and "DoubleStake" features.

The idea here is to develop a package "BasicFeatures" that is used in the basic version and that is reusable to 100% in the advanced version.

Using packages to their full extent in this example requires not only the process Game to be transformed to a process type (as you have done in the previous exercises, when creating the JackpotGame, DoubleGame and SuperGame), but also to transform the process Main and the block GameBlock to reusable process type and block type, respectively.

You have probably noticed that the process type Main also requires to be extended for each feature that we add ("jackpot", "double", etc.), so it would be a good idea to make a reusable type of it. This has already been prepared for you, so your task will be to add the required "glue" to build the two packages.

  1. Start by copying the files gameblock.sbt and main.spt from the directory $-telelogic/sdt/examples/demongame/sdl92/packages (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame\sdl92\packages (in Windows) to the same directory you created earlier for this tutorial.
    • All diagrams in the remaining exercises are available in the above directory. You may choose to copy them if you do not want to draw all diagrams, and then connect the created diagram symbols in the Organizer to the corresponding files.

Creating a Package

To create a package:

  1. Select the Add New command from the Organizer's Edit menu. In the Add New dialog, specify document type as SDL Package, and document name as BasicFeatures.

Figure 175 : Adding a new package Basic Features

As you click OK, a new diagram structure is created in the Organizer with the package diagram as root diagram. (The Organizer supports managing multiple structures in the same system file.)
The newly created package should contain the generic properties for the DemonGame; namely:
  • The declaration of the signal interface between the "basic" -DemonGame and the environment, as well as a process type Main that supports the signal interface.
  • The definition of the process type Game with the basic functionality.
  • A block type that contains the process types.
  2. With the SDL Editor, move the declaration of the signals from the system diagram to the package diagram. Also add the process type reference symbol Game and the block type reference symbol -BasicGameBlock to the package diagram. See below.

Figure 176 : The package BasicFeatures

  3. Save the package diagram on a file, e.g. basicfeatures.sun
  4. With the Organizer, connect the block type BasicGameBlock to the recently copied file gameblock.sbt (the diagram is depicted in Figure 177).
    • Note that the process type Main is declared as VIRTUAL. This is essential since we are going to add properties to Main, and need to address signals from the environment to Main, without changing its name to e.g. "SuperMain" (compare to how you did for the process type Game that was specialized into -JackpotGame, etc.). By defining a process type as VIRTUAL, we can later add properties without changing its name, using the keyword REDEFINED (you will practice that in a few moments, in "Redefined Process Type Main" ).

Figure 177 : The block type BasicGameBlock

  5. You should also connect the process type Main to the copied file main.spt (This may already have been done if you had Expand Substructure turned on in the Connect dialog in the previous step.)

Using a Package

To use a package, you add a USE statement to the package reference symbol (looking like a text symbol immediately outside the frame symbol).

  1. To create a version of the DemonGame that has the basic features, add a USE statement to the system diagram. Also remember to instantiate the block type -BasicGameBlock (which is contained in the package). See below.

Figure 178 : USE of packages

    • You may want to save the system diagram on a new file, e.g. -basicdemongame.ssy
  2. In the Organizer, Disconnect the old GameBlock from the system structure. The resulting Organizer view should now be something like this (the order of appearance of symbols may differ):

Figure 179 : System BasicDemonGame using package BasicFeatures

  3. Terminate the exercise by analyzing the resulting system.

Note:

You may analyze the package (by selecting the package symbol in the Organizer as input to the Analyzer before ordering the Analyze command), in which case a partial semantic analysis will be done on the package. (The Analyzer will not check the consistency between the package and the system that uses it.)
A complete semantic analysis requires the system diagram to be selected before ordering Analyze.


Reusing Packages

When developing the version of the DemonGame that has all features, you create a package AdvancedFeatures that contains the additional features and that will reuse the package BasicFeatures.

What You will Learn

  • To reuse a package in another package
  • To inherit a block type
  • To redefine a process type

The Package AdvancedFeatures

  1. Create the package AdvancedFeatures in a similar fashion as the package BasicFeatures (see Figure 175).
    • You should now have two package structures in the Organizer, BasicFeatures and AdvancedFeatures.

The package AdvancedFeatures must do the following:

  2. Use the package BasicFeatures.
  3. Add the declarations of the new signals.
  4. Add references to the process types JackpotGame, etc.
  5. Add a reference to a block type AdvancedGameBlock (which inherits the block type BasicGameBlock and in turn refers to a redefined process type Main).
  6. Save the package diagram on the file advancedfeatures.sun

Figure 180 : The package AdvancedFeatures

Block Type AdvancedGameBlock

The diagram contains a reference to a REDEFINED process type Main, and a dashed instantiation symbol Main.

Figure 181 : Block type AdvancedGameBlock

  • The block type AdvancedGameBlock is already provided on the file -advancedgameblock.sbt. Copy that file from the directory $-telelogic/sdt/examples/demongame/sdl92/packages (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame\sdl92\packages (in Windows), and use the Organizer to connect the diagram to the file.

Redefined Process Type Main

The REDEFINED process type Main inherits implicitly from the -VIRTUAL process type Main in the package BasicFeatures, and adds the code to receive the signals that command the new features.

Figure 182 : The redefined process type Main

  • The REDEFINED process type Main is also provided on the file advancedmain.spt in the directory
    $-telelogic/sdt/examples/demongame/sdl92/packages (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame\sdl92\packages (in Windows). Copy the file and use the Organizer to connect the diagram to the file.

Creating the System AdvancedDemonGame

Creating the system is now fairly simple.

  1. Add a New SDL system in the Organizer. Say you name the system AdvancedDemonGame and save it as demongameadvanced.ssy
  2. With the SDL Editor, Copy the contents of the system -BasicDemonGame and Paste them into the new system.
  3. Have the system USE AdvancedFeatures in addition to -BasicFeatures.
  4. Change the reference from the block type BasicGameBlock to -AdvancedGameBlock.
  5. Update the signal list C1 with the new signals JackpotGame, etc. The system is now complete. Analyze it and simulate it if you find it meaningful.

Figure 183 : The system AdvancedDemonGame


Conclusion

The SDL-92 session of this tutorial has shown how to design a (small) SDL system so that the result becomes reusable components, which in turn reduces the effort needed to maintain and extend the functionality.

The tutorial also illustrates the need to design the system properly in order to introduce the OO paradigm in a smooth way.

To verify that you have assimilated the SDL-92 tutorial, you should now be ready to add new features on your own, without having to rewrite the whole system.


More Exercises...

As a "menu" of new features that can be introduced, we suggest that you try to extend the AdvancedDemonGame with the following:

  1. Memorization of "highest score ever" since system start (there should be only one highest score, common for all types of games).
  2. A "hall of fame" that memorizes the name of the player that reaches the "highest score ever". (The name is assumed to be provided by the environment).
  3. A "gameover" function that checks if the current score is less than an arbitrary value of, say -100, and disables the game so that the player needs to restart it entirely.

Good luck!

Note:

A suggestion for a solution for the exercises above can be found in the directory: $-telelogic/sdt/examples/demongame/sdl92/exercises (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongame\sdl92\exercises (in Windows)


Appendix: Diagrams for the DemonGame Using Packages

Figure 184 : Hierarchical structure

Figure 185 : Inheritance tree for the block type and process type Main

(The inheritance tree for the process type Game is displayed in Figure 172.)


7 Cmicro Targeting Tutorial

This tutorial takes you through the first steps of targeting. Currently this tutorial is designed for using a Borland C or a Microsoft Visual C compiler in Windows, and gcc or cc on UNIX.


Prerequisites / Abbreviations Used

Before you run this tutorial, you should be familiar with the SDL Suite tools, especially the Organizer, the SDL Analyzer and the SDL Simulator. If you have not already done so, you are recommended to go through the previous tutorials in this volume.

The following notations and directories concern the rest of this tutorial:

  • <TAUinstallation> denotes the Telelogic Tau installation directory, which is called
    <systemdrive>:\Telelogic\SDL_TTCN_Suite4.4     in Windows and $telelogic on UNIX.
  • In this tutorial there is a mixed use of the path separation characters `/' and `\', as several steps in Windows and on UNIX only differ in these.
  • Although "directories" are sometimes called "folders" in Windows, this tutorial always uses the expression "directory".
    You will find this tutorial placed in the directories:
<TAUinstallation>\sdt\examples\cmicrotutorial\wini386
<TAUinstallation>/sdt/examples/cmicrotutorial/sunos5
<TAUinstallation>/sdt/examples/cmicrotutorial/hppa
  • The Cmicro Library can be found in the directories:
<TAUinstallation>\sdt\sdtdir\wini386\cmicro
<TAUinstallation>/sdt/sdtdir/sunos5sdtdir/cmicro
<TAUinstallation>/sdt/sdtdir/hppasdtdir/cmicro
For a description of the Cmicro Library please view The Cmicro Library.


Introduction

General

This tutorial is divided into three sections. In the first section you will take a small SDL system and generate it with the SDL Analyzer. You will learn about configuration possibilities using the Targeting Expert and how to create environment functions. Finally, you will build the target application.

In the second section you will test it and learn something about how to use the SDL Target Tester.

In the third section you will learn how to remove the Target Tester source from the target application.

Integrations

Targeting may be implemented using the following methods:

  • Bare integration:
    The SDL system is running on a bare target, scheduled by the Cmicro Kernel without any other operating system (OS).
  • Light integration:
    The SDL system (scheduled by the Cmicro Kernel) is running as one task in an OS, possibly using functions of the OS.
  • Tight integration:
    All the SDL process instance sets (and other tasks) are scheduled by the OS of the target.

In this tutorial you will be doing a light integration as the target application is executed as an independent OS task, where the SDL processes are scheduled by the Cmicro Kernel.

Target Tester Communication

The communication between the Target Tester and the target application is done using sockets (localhost, port 9000 as default) in this tutorial.


Prerequisites to the Example

The Pager System

The SDL system that will be used for this tutorial is a pager system. A pager is a small hand-held device used for contacting people. It contains a radio receiver which is capable of receiving signals on a certain frequency consisting of short messages and telephone numbers.

The pager has also a sort of databank with a limited capacity for storing messages as well as a keypad and a display which serve as the interface to the user. The user has the option of scrolling through, reading and deleting the messages that are displayed on the small screen.

The keypad consists of three buttons; one for scrolling to the right, one for scrolling to the left and one for deleting. The pager emits a sound when a new message has arrived and also when the user makes an error or tries to do something which is not allowed. For example, trying to delete a message when the databank is empty or scrolling too far in a certain direction would be instances of illegal actions. Naturally, the pager can only hold a certain amount of messages and therefore at some point eventually fills up.

When the pager has reached its capacity a warning message is given for 2 seconds before the received message is displayed.

The SDL Overview shows the pager system divided into blocks and processes.

Figure 186 : An overview of the system Pager

Process
Description

 Database
The process Database manages the array of messages that makes up the pager's memory. It can store messages, retrieve them and delete them while maintaining order in the databank.

 PagerCtrl
PagerCtrl basically handles all the input and output of the system. It receives input from the user via the keypad, messages from the radio receiver and information from the database regarding the status of saving and deleting.

 Keypad
The process Keypad converts the input from the user into a signal and sends it to PagerCtrl.

Delivered Files

The files needed for this tutorial can be found in the directory:

<TAUinstallation>/sdt/examples/cmicrotutorial/<platform>/pager

The project directory pager includes a sub directory called system. The directory system contains the SDL/GR files of the Pager system.

Furthermore, there is a directory prepared in parallel to the system directory. Here you can find an environment file env.c which can be used if you are not interested in programming the environment on your own.


Targeting

Preparations - File Structure

  1. Create a new empty directory <cmicrotutorial> in your home directory or on your local hard disk. This directory will be denoted by <MyTutorial> in the following.
  2. Copy the directory <TAUinstallation>/sdt/examples/cmicrotutorial/pager (including all files and subdirectories) to your new <MyTutorial> directory and remove all write protections.
  3. In the Organizer, open the Pager system (Pager.sdt) found in <MyTutorial>/pager/system.

Using the Targeting Expert

  1. Select the system symbol in the Organizer view.
  2. Start the Targeting Expert from the Generate menu. The Targeting Expert will generate a default partitioning diagram model (see "Partitioning Diagram Model File" ) and will check the directory structure.
  3. As the target directory specified in the Organizer does not exist yet, you will be prompted if it should be created. Press the Yes button.

A sub-directory structure is added in the target directory afterwards by the Targeting Expert. For further information see "Target Sub-Directory Structure" .

Note:

If the Targeting Expert is started the very first time a welcome window is displayed. Just press the Close button and proceed. The welcome window will be shown any time you start the Targeting Expert again until you select the "Do not show again at startup" check box.

The work flow of the Targeting Expert is divided into four steps.

  • Step 1: Select the Desired Component
  • Step 2: Select the Type of Integration
  • Step 3: Configure the Build Process
  • Step 4: Make the Component

The very first time you are using the Targeting Expert, an assistant is automatically started showing you how to proceed. When you have closed the assistant, you can always re-start it by choosing the menu option Help > Assistant.

The Help Viewer will be displayed and show the appropriate manual page if you click on one of the numbered boxes.

Step 1: Select the Desired Component

  • Click on the component in the partition diagram model.
    The complete SDL system is (per default) generated into the component "component".

Hint:

The component can be given any name you like if the system is deployed using the Deployment Editor. For more detailed information on how to deploy a system, see The Deployment Editor.

Figure 187 : The Targeting Expert's main window

Background Information

  • More details about partitioning diagram models can be found in "Partitioning Diagram Model File" .
  • For further information concerning the selectable entries in the partitioning diagram model, please see "Targeting Work Flow" .

Step 2: Select the Type of Integration

  1. Press the left most combo box in the integration tool bar of the main window (or click the component entry in the partitioning diagram model using the right mouse button). This is shown in Figure 188.

Figure 188 : Popup menu in the Targeting Expert

  2. A tree structure containing all the pre-defined integrations is shown in the popup menu displayed. Select Light Integrations > Application TEST.
  3. As there is no automatic configuration of the pager system available so far, you are prompted to start the automatic configuration. Press the Yes button in the dialog. The Targeting Expert then automatically starts the Cmicro SDL to C compiler to generate the file sdl_cfg.h.

The SDL system is now checked for correctness and the automatic configuration is done.

Hint:

Although only the file sdl_cfg.h is needed the SDL to C compiler generates the files: component.c, component.ifc,
component.sym and sdl_cfg.h. This is done because only the SDL to C compiler knows all the used and unused features (OO concept).

After the SDL to C compiler has finished, the Targeting Expert:

  • generates the file env.c and lists all the SDL signals from and to the environment (see event log). A manual adaptation is needed for each signal before the generated files and the library files can be compiled. This is necessary as the Targeting Expert only generates a skeleton with the used signals.
    How to edit the env.c, is described in "Edit the Environment File" .
  • generates default Target Tester options (file sdtmt.opt)
  • generates a default manual configuration (file ml_mcf.h)

Hint:

After the integration has been selected the Targeting Expert automatically sets the default compiler. The default compiler's name is taken from the Telelogic Tau Preferences.
If a different compiler is required than the one set as default in the preferences, it is possible to change this in the integration tool bar's combo box.

Background Information

If you want to do an integration not given in the Tau distribution, please select the entry <user defined> in the integration popup menu. Then you are able to do all settings needed for the used hardware. You are also able to set up your own integration accessible in the integration popup menu.

The contents of the files:

  • component.c
    Describes the SDL system's behavior in C functions.
  • component.ifc
    The header file for the environment functions. E.g. it provides PIDs and type definitions for signals.
  • component.sym
    Provides information on SDL symbols. Necessary for tracing the SDL system with the SDL Target Tester.
  • sdl_cfg.h
    The automatic configuration file for the Cmicro Kernel. For instance, if you use a timer, the file contains a define, which turns the timer implementation on.

Edit the Environment File

In this section you will learn how to fill in the environment functions in the file env.c.

Hint:

There is also a prepared env.c. You can copy it from directory:
<MyTutorial>/pager/prepared into
<MyTutorial>/pager/target/pager._0/Application_TEST.
Do not forget to remove the write protection!
Note the differences between the prepared and generated file.

Note:

In the following the Targeting Expert starts a text editor. Per default the built-in editor is used. This can be changed in the Tools > Customize menu.

  1. Select the menu Edit > Edit Environment File to open the file env.c

Caution!

In the file env.c, you should only edit code between the lines:

/* BEGIN User Code ... */
/* END User Code ... */

The reason is:

If the Targeting Expert needs to generate the file a second time, the code in these sections will be read in and copied to the new file. Only the code between the mentioned lines will be unchanged.

Do NOT edit lines with the text:

/* BEGIN User Code ... */
/* END User Code ... */

  2. Find the lines from the global section:
/* BEGIN User Code (global section)*/
/* It is possible to define some global variables here */
/* or to include other header files. */

This tutorial describes a console application. It will use the screen and the keyboard to communicate with the user. It is necessary to include the used header file(s).
For a better style some defines are used. Further some global variables and functions have to be implemented. The functions are called, if there should be something simulated in the environment, like a display. After the line
/* or to include other header files. */
 the following code needs to be inserted:
#if defined(BORLAND_C) || defined(MICROSOFT_C)
#include <conio.h>
#else
#include <stdio.h>
#endif

#define key_was_pressed 1
#define key_not_pressed 0

int KeySignalPresent = 0;
char LastKeyPressed;

xInitEnv()

  3. We like to have a welcome message displayed when the system is started. This can be done like this in the function xInitEnv()
printf("-------- Welcome to Pager system--------\n\n");
printf("get message : 0 to 4\n");
printf("scroll right: r\n");
printf("scroll left : l\n");
printf("delete : d\n\n");

The code must be inserted between

/* BEGIN User Code (init section) */

and

/* END User Code (init section) */

xInEnv()

  4. Now you have to handle the data from the environment. In this tutorial it means you have to handle the input from the keyboard!

Caution!

Do not use blocking functions in the environment file.

The environment is polled with every cycle of the Cmicro Kernel. That is the reason why it is not allowed to use blocking functions like getchar(). These kind of functions stop the kernel and so it cannot process the SDL system.

The possible handling of the data:
If a key has been pressed the digits 0-4 are recognized as a message and the letters 'r', 'l' and 'd' are the commands for scrolling and deleting.
Please go to the code position of the function xInEnv() with the following lines:
/* BEGIN User Code (variable section)*/
/* It is possible to define some variables here */
/* or to insert a functionality which must be polled */
Below these lines insert the following code:
char my_inkey;

KeySignalPresent = key_not_pressed;

#if defined(XMK_UNIX)
my_inkey = 0;
if((my_inkey = getchar_unlocked()) != 0)
{
KeySignalPresent=key_was_pressed;
}
#elif defined(BORLAND_C) || defined(MICROSOFT_C)
if (kbhit())
{
my_inkey=_getch();
KeySignalPresent=key_was_pressed;
}
#endif

if (KeySignalPresent==key_was_pressed)
{
if ((my_inkey == 'r') ||
(my_inkey == 'l') ||
(my_inkey == 'd') ||
((my_inkey>='0')&&(my_inkey<='4')))
LastKeyPressed = my_inkey;
else
LastKeyPressed=0;
}
else
LastKeyPressed = 0;

  5. Find the following lines of code in the function xInEnv()
/* BEGIN User Code <ScrollRight>_1 */
if (i_have_to_send_signal_ScrollRight)
/* END User Code <ScrollRight>_1 */
In step 2 we implemented the variable LastKeyPressed. In step 4 we assigned it the value of my_inkey which has the value of the last key pressed. Modify the if() statement into:
if (LastKeyPressed == 'r')
  6. Find the following line of code in the function xInEnv()
GLOBALPID(Who_should_receive_signal_ScrollRight,0));
The process type ID which should receive the signal ScrollRight needs to be inserted. To get an overview of the process type IDs look at the dialog window that has pop-ed up by the Targeting Expert. All the used process type IDs are given here.

Figure 189 : Process type ID dialog

Select the XPTID_Keypad entry in this dialog to copy it into the clipboard. Then paste it into the env.c as shown below.
GLOBALPID(XPTID_Keypad,0));
The function returns, and the signal is treated.
  7. Find the following lines in the function xInEnv()
/* BEGIN User Code <ScrollLeft>_1 */
if (i_have_to_send_signal_ScrollLeft)
/* END User Code <ScrollLeft>_1 */
Modify the if() statement to:
if (LastKeyPressed == 'l')
  8. Find the following line of code in the function xInEnv()
GLOBALPID(Who_should_receive_signal_ScrollLeft,0));
Copy the XPTID_keypad as described in step 6.
GLOBALPID(XPTID_Keypad,0));
  9. Find the following lines of code in the function xInEnv()
/* BEGIN User Code <Delete>_1 */
if (i_have_to_send_signal_Delete)
/* END User Code <Delete>_1 */
Modify the if() statement to:
if (LastKeyPressed == 'd')
  10. Find the following line of code in the function xInEnv()
GLOBALPID(Who_should_receive_signal_Delete,0));
Copy the XPTID_keypad as described in step 6.
GLOBALPID(XPTID_Keypad,0));
  11. Because we do not use a real target hardware, but simulate the Pager system, we have to predefine some messages.
    Find the following lines of code in the function xInEnv()
/* BEGIN User Code <ReceivedMsg>_1 */
if (i_have_to_send_signal_ReceivedMsg)
/* END User Code <ReceivedMsg>_1 */
Modify the if() statement to:
if ((LastKeyPressed>='0')&&(LastKeyPressed<='4'))
This if-statement checks whether the key hit on the keyboard was one of the defined keys or not.
  12. Go to the next empty "User Code" section and insert following lines:
char *p;
xmk_var.Param1.MyText = (SDL_Charstring)NULL;

switch(LastKeyPressed)
{
case '0':
p = " Hello user";
xmk_var.Param1.TelNumber = 12345;
break;
case '1':
p = " How do you feel doing targeting?";
xmk_var.Param1.TelNumber = 555555;
break;
case '2':
p = " Targeting is all so easy!";
xmk_var.Param1.TelNumber = 987654;
break;
case '3':
p = " I only wanted to check if it works.";
xmk_var.Param1.TelNumber = 45454;
break;
case '4':
p = " ... and it works very fine!";
xmk_var.Param1.TelNumber = 911911;
break;
default :
break;
}
xAss_SDL_Charstring(&(xmk_var.Param1.MyText), p, XASS_AC_ASS_FR);
In this part the messages to the equivalent numbers 0-4 are stored. With the switch statement it is decided which one is handed over to the environment.

Note:

This way of "receiving" messages is of course just a helper function because we do not use a real interface here!

The line xmk_var.Param1.MyText = (SDL_Charstring)NULL;
means that the element MyText of the parameter message which is a parameter of the signal ReceivedMsg is set to null.
The Signal ReceivedMsg and the parameter message are declared in the SDL system.
The line xAss_SDL_Charstring(&(xmk_var.Param1.MyText), p, XASS_AC_ASS_FR); allocates memory for the pointer p.

Note:

If an SDL charstring is mapped to an array of char in C, the first character in this array (index 0) is for internal use only, i.e. the text message should start at index 1. This is done by having a space in front of the text in the implementation shown above.

  13. Find the following line of code in the function xInEnv()
GLOBALPID(Who_should_receive_signal_ReceivedMsg,0));
Modify the statement as showed below.
GLOBALPID(XPTID_PagerCtrl,0));

xOutEnv()

Caution!

The function xOutEnv() provides a pointer named: xmk_TmpDataPtr. The data referenced by this pointer is valid only as long as the function xOutEnv() is processed.

If you need to treat the data after leaving the function, copy it to variables defined by you.

  14. Find the following code section:
case CurrentMsg :
{
/* BEGIN User Code <CurrentMsg>_1 */
/* Use (yPDP_CurrentMsg)xmk_TmpDataPtr to access the signal's parameters */
/* ATTENTION: the data needs to be copied. Otherwise it */
/* will be lost when leaving xOutEnv */
/* END User Code <CurrentMsg>_1 */

/* BEGIN User Code <CurrentMsg>_2 */
/* Do your environment actions here. */
xmk_result = XMK_TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code <CurrentMsg>_2 */
}
This code fragment handles the signal CurrentMsg. The chosen message is displayed on the screen (telnumber, message, current message position and the total number of messages). Insert the following code after: /* Do your environment actions here. */
printf("\r ");
printf( "\rCurrentMessage: %6d %s (%d/%d)",
((yPDP_CurrentMsg)xmk_TmpDataPtr)->Param3.TelNumber,
((yPDP_CurrentMsg)xmk_TmpDataPtr)->Param3.MyText+1,
((yPDP_CurrentMsg)xmk_TmpDataPtr)->Param1,
((yPDP_CurrentMsg)xmk_TmpDataPtr)->Param2);
xFree(&(((yPDP_CurrentMsg)xmk_TmpDataPtr)->Param3.MyText));
The line
xFree(&(((yPDP_CurrentMsg)xmk_TmpDataPtr)->Param3.MyText)); frees the memory allocated in the kernel when sending the signal.
  15. Find the following code in the function xOutEnv():
case ServiceMsg :
{
/* BEGIN User Code <ServiceMsg>_1 */
/* Use (yPDef_Close*)xmk_TmpDataPtr to access
the signal's parameters */
/* ATTENTION: the data needs to be copied.
Otherwise it */
/* will be lost when leaving xOutEnv */
/* END User Code <ServiceMsg>_1 */

/* BEGIN User Code <ServiceMsg>_2 */
/* Do your environment actions here. */

xmk_result = TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code <ServiceMsg>_2 */
}
The code fragment handles the signal ServiceMsg. The handling of the data is same as in the step before. So insert the following code after: /* Do your environment actions here. */
printf("\r ");
printf( "\rServiveMessage: %s",
((yPDP_ServiceMsg)xmk_TmpDataPtr)->Param1+1);
xFree(&(((yPDP_ServiceMsg)xmk_TmpDataPtr)->Param1));

  16. Find the following code section in the function xOutEnv():
case ShortBeep :
{
/* BEGIN User Code <ShortBeep>_1 */
/* END User Code <ShortBeep>_1 */

/* BEGIN User Code <ShortBeep>_2 */
/* Do your environment actions here. */
xmk_result = XMK_TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code <ShortBeep>_2 */
}
break ;
The code fragment handles the signal ShortBeep. A beep sounds when the pager receives a message or you do something which is not allowed. After the code /* BEGIN User Code <ShortBeep>_1 */ insert
putchar(07);
  17. Find the following code section in the function xOutEnv():
case LongBeep :
{
/* BEGIN User Code <LongBeep>_1 */
/* END User Code <LongBeep>_1 */

/* BEGIN User Code <LongBeep>_2*/
/* Do your environment actions here. */
xmk_result = XMK_TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code <LongBeep>_2*/
}
break ;
Insert the following code after
/* BEGIN User Code <LongBeep>_1 */
putchar(07);
putchar(07);

Closing the Environment

In this tutorial there is no need to close the environment. In other cases, e.g. microprocessor hardware, it is probably necessary to do so.

Have a look in the file env.c, find code like this in the function xCloseEnv():

/* BEGIN User Code (close section) */
/* Do the actions here to close your environment */
/* END User Code (close section) */

Insert any code you need to have here.

Step 3: Configure the Build Process

  1. Press the items below the Application TEST in the partitioning diagram. If it is necessary to add or remove settings for your job, you can edit the settings.
  2. Click Save to close the dialog.

For this section of the tutorial there it is not necessary to modify anything, though we will do some modifications later in section "Run Target EXE without Tester" .

Background Information

Short description of the different areas:

  • Compiler / Linker / Make
    In this area it is possible to configure all the settings used for the Compiler, Linker and Make tools.
    Something special regarding Additional Compiler. For example, you have to use an ANSI C- compiler to compile the generated files, and it is necessary to link the objects with the object from one file, which needs to be compiled with a C++ compiler. In this instance you could enter the regarding file and the used compiler in the section Additional Compiler.
    For more information see: "Configure Compiler, Linker and Make" .
  • Target Library
    In this area it is possible to set defines and values to scale the target library. For more information see "Configure and Scale the Target Library" .
    All settings will be stored in the file ml_mcf.h.
  • Target Tester
    In this area it is possible to set defines and values to scale the functionality of the tester. For more information see "Configure the SDL Target Tester (Cmicro only)" .
    All settings will be stored in the file ml_mcf.h.
  • Host Connection
    In this area it is possible to set the parameter of the connection to the host. For example, it contains the description of the message coding and the name of the executable, etc. The configuration of the Host Connection is always stored in the file sdtmt.opt. This file is mandatory for the SDL Target Tester. For more information see: "Configure the Host (Cmicro only)" .

Step 4: Make the Component

  1. In the dialog which is displayed by default (when the Application TEST is selected) you have to select two check boxes. Analyze / Generate Code and Environment functions.
  2. Click on the button Full Make to start the code generation and make.

After the SDL to C compiler has finished the code generation, the Targeting Expert will re-generate the env.c (and keep your modifications). Afterwards it generates a makefile with the given settings and the code will be compiled and linked.

The Targeting Expert then starts the SDL Target Tester.


Use of the SDL Target Tester

Differences between SDL Simulator and SDL Target Tester

The difference compared to the SDL Simulator is that the generated SDL system is running on a target hardware and is sending messages to the host system on which the SDL Target Tester's host part is running.

In this Cmicro tutorial, the SDL Target Tester's host part is running on the host as well as the generated SDL system (target).

Figure 190 : Communication links between the processes

Restrictions

In this Tutorial

It is possible to use all the features supported by Cmicro (e.g. signal priorities, error checks, tester) except the preemptive Cmicro Kernel. This is due to the concept behind Cmicro which is designed for small targets on a stand-alone hardware (bare integration).

Background Information

  • To get information on how it works with a real target hardware, see The Cmicro Library.
  • If you want to edit the makefile, or have a look into it, please use the menu Edit > Makefile in the Targeting Expert. For more information please view The Targeting Expert.

Testing the Pager System

Running the SDL Target Tester

The SDL Target Tester could be started automatically from the Targeting Expert or by:

  • selecting Tools > SDL > SDL Target Tester in the menu of the Targeting Expert.
  • pressing the quick button in the quick button bar.

After it has been started the following steps have to be done (in the given order)

  1. Start the communication with the executable by pushing the button StartGateway in the Communication group or with the menu Execute > StartGateway.
  2. Go back to the Targeting Expert and select the menu entry
    Tutorial > Start target (Windows) or respectively
    Tutorial > Start target (UNIX)

Hint:

The menu Tutorial is a configurable menu not available if working on other SDL systems. Please refer to "Configurable Menus for more information on how to create your own menu entries.

Note:

In Windows the target application is started in a separate command prompt window.
On UNIX the target application is started in a separate xterm.

  3. Now the communication between SDL Target Tester and target is established. The SDL Target Tester displays the message Start with "Go Forever". The corresponding button is located in the Execute group. Press the button.

    All messages of the target application are displayed in the UNIX shell or DOS command prompt where it was started. The pager will display its start-up message which was implemented in "xInitEnv()" .
  4. You can "receive" messages by pressing the keys 0, 1, 2, 3, 4 and scroll with the keys r and l. To delete a message press d.
    See "xInEnv()" on how the environment was implemented.
  5. The pager displays the last received message, the number of the current message and the total number of received messages. Now you can scroll, delete and receive new messages. If you receive a new message while the maximum amount of messages(3) is reached, the pager saves the message temporary and displays the warning:
    Memory full, please free memory to get new messages
    for about 2 seconds.
  6. Press the d key on your keyboard, the last message is then deleted and the received message is displayed.

Note:

To exit the target application press CTRL+C on the keyboard.

SDL Target Tester Commands

The SDL Target Tester has button groups. Each button represents a Tester command. You can use the buttons or the command line at the bottom of the Tester to enter a command. If you enter help in the command line you will see a list of SDL Target Tester commands.

In the following some Tester commands are explained briefly. For more information, see 67 The SDL Target Tester.

Tracing the SDL System -> MSC Editor

Similar to the SDL Simulator GUI it is possible to generate MSC traces while testing the system with the SDL Target Tester.

  • In the Trace group you can select the Start MSC button, for example, to start the MSC trace.
  • Now you can select between output via display or output to a file.

Tracing the SDL System -> SDL Editor

It is possible to trace the target system with the SDL Editor.

  • You can start the trace with the command line of the SDL Target Tester by typing start-sdle, or by using the button Start SDLE.

The MSC trace and SDL trace functions are powerful tools for understanding the system.

Target Information

To get more information about target configuration, you must open the Configuration Group in the button area of the SDL Target Tester and press Target to get the current target configuration.

To get information about the kernel, you have to open the Examine Group. If you press Queue you will get information about the current state of the internal queue of your system. You will see the peak hold and the amount of signals of your current system. By pressing the other buttons in the Examine Group, you will get more information of the running system.

Memory

With the ?memory command you can see how the current memory state is.

  1. Start the Pager system as described in "Running the SDL Target Tester" .
  2. Type ?memory (the short command ?m can also be used) on the command line. You can check the memory pool size, the current memory fill and so on.

Now we will see how the memory is handled in the Pager system. Notice that the current amount of blocks in pool is four and the peak hold is five.

  3. Switch to the target application and press a key (1-4) to get a message.
  4. Go back to the Target Tester and execute the ?m command again. This time you can see that two more blocks are allocated. If you delete the last message the memory should be freed again and show four blocks.

Breakpoints and Queues

To debug the system you can use the Breakpoints button group. You can set a breakpoint on a signal input or a process state. If a breakpoint was reached you can continue the system with the button Continue.

  1. Restart the target as described in "Running the SDL Target Tester" .
  2. Expand the Breakpoints group and select Break input.
  3. Now you can choose a process ID. In this example we take the Keypad ID.
  4. A signal ID list is shown afterwards, select the delete signal.
  5. Breakpoint on input is set is shown in the text area now, switch to the target application window and insert some messages first, then press d. Nothing happens.
  6. Switch to the Tester again. Now you can use the ?memory command or look how the Queue looks like (?queue).
  7. Press Continue after you have examined the system state.

As the system will be halted every time the signal delete is to be consumed in process Keypad, it is probably useful to delete the breakpoint(s) by entering the command BA.


Run Target EXE without Tester

It is also possible to run the target executable without starting the Target Tester. Following has to be done first:

  1. Exit the target application and the Target Tester if not already done.
  2. Switch back to the Targeting Expert.

In the following there is a description what has to be done to remove the Target Tester source code form the target application.

  1. Press the entry Target Tester below Application TEST in the Partitioning Diagram Model. As you can see all the selected Target Tester flags are disabled, i.e. it is not possible to switch them off because the pre-defined integration selected prevents doing so.
    To get access to these flags, the Targeting Expert provides a so called "Advanced Mode". (For details see "Advanced Mode.
  2. Select the menu entry Tools > Customize and a dialog pops up. Select the check box Advanced Mode and press the dialog's OK button.

Caution!

The Advanced Mode is now switched on each time you enter the Targeting Expert again. Make sure you switch off the Advanced Mode to take advantage of the restrictions given with all the other pre-defined integration settings.

  3. In the dialog displayed when the Application TEST entry is selected in the Partitioning Diagram Model, you have to select the Execution tab. Press the None radio button in the Test application group box.
    This is done to disable the execution of the Target Tester after the target application has been successfully build.
  4. Select Target Tester in the Partitioning Diagram Model and deselect the Use the Target Tester check box. Press OK in all following windows. (Depending flags are switched off). After the last dialog has been executed, all check boxes on the Tester tab should be un-selected now.
  5. Press the Save button below the dialog.

Hint:

A new manual configuration file ml_mcf.h is generated with all the Target Tester flags undefined.

  6. Now press the Make button. (All the files are compiled again because the ml_mcf.h has been modified.)

When compile and link is completed, the target can be started via the menu Tutorial > Start target and can be used now without SDL Target Tester.


8 Tutorial: Using ASN.1 Data Types

This tutorial describes how to use ASN.1 types and values in the SDL suite. You will learn how to import and use ASN.1 modules in your SDL diagrams, how to generate code and how to encode and decode your ASN.1 types using BER or PER encoding.

The tutorial contains all steps from creating ASN.1 data types to the implementation of the ASN.1 data types in your source code.

To illustrate the functionality and the work flow, small examples are presented throughout the tutorial. The SNMP protocol is used as a base to illustrate how ASN.1 could be applied on a typical SNMP stack.

In order for you to fully take advantage of this tutorial, you should be familiar with the SDL suite and the basics of ASN.1.

Additional information regarding ASN.1 types and its usage together with the SDL suite can be obtained in:

  • Data Types
  • The ASN.1 Utilities
  • Building an Application
  • ASN.1 Encoding and De-coding in the SDL Suite


Introduction

The Abstract Syntax Notation One (ASN.1) is a notation language that is used for describing structured information that is intended to be transferred across some type of interface or communication medium. It is especially used for defining communication protocols.

As ASN.1 is widely popular, the SDL suite allows you to translate ASN.1 data types to SDL and to encode/decode ASN.1 data types.

By using ASN.1 data types in the implementation of your application, you will optimize your development process. The following list displays some of the advantages of ASN.1:

  • ASN.1 is a standardized, vendor-, platform- and language independent notation.
  • A vast number of telecommunication protocols and services are defined using ASN.1. This means that pre-defined ASN.1 packages and modules are available and can be obtained from standardization organizations, RFCs, etc. For instance, the ASN.1 data types defining SNMP are available in RFC 1157.
  • When ASN.1 data types are transmitted over computer networks, their values must be represented in bit-patterns. Encoding and decoding rules determining the bit-patterns are already defined for ASN.1. The SDL suite supports BER and PER encoding.
  • ASN.1 enables extensibility. This means that it simplifies compatibility of systems that have been designed and implemented large time frames apart.
  • The SDL suite and the TTCN suite can share common data types by specifying these in a separate ASN.1 module.

Implementation of ASN.1

When importing ASN.1 data types to your SDL system, you need to translate the ASN.1 definitions to SDL. The SDL suite does this for you using a tool called ASN.1 Utilities. This tool is automatically invoked when you analyze your SDL system.

However, having the ASN.1 data types translated to SDL is not enough to include them in your application. If you are going to transfer application-generated information on computer networks, the values of the data types must be encoded. When transferring signals in or out of your SDL system, you must also create the interface between the environment and the system.

Thus, the process of implementing ASN.1 data types can be divided into three separate steps:

  1. Creating the abstract syntax
  2. Creating the transfer syntax
  3. Compiling the application

The definitions of the abstract syntax and the transfer syntax is presented below.

Abstract Syntax

The basic idea is to transport some type of information between two nodes using protocol messages. The abstract syntax is defined as the set of all possible messages that can be transported. To create the abstract syntax you must:

  • design some form of data structure defined in a high-level programming language, for instance ASN.1.
  • define the possible set of values that the data structure can take.

Transfer Syntax

The transfer syntax is the set of bit patterns that represents the abstract syntax messages with each bit pattern representing just one value. The rules determining the bit-patterns are called the encoding rules.


Creating the Abstract Syntax

When creating the abstract syntax you must perform the following tasks:

  • Adding ASN.1 modules to your project
  • Importing the ASN.1 modules in your SDL diagrams.
  • Assigning values to the data types.

Adding ASN.1 Modules to your Project

An ASN.1 module is a file containing the ASN.1 data type definitions. If you are implementing a standard communication protocol, it is very likely that pre-defined ASN.1 modules have been created. The modules can be obtained from standardization organizations, RFCs, etc. In Example 10, the ASN.1 module that defines the SNMP protocol is presented. This module is available in the RFC 1157.

However, should a pre-defined module not be available for your type of application, you must create your own module. Please see adequate ASN.1 literature for instructions and guidelines on creating ASN.1 modules.

Regardless how you obtain the ASN.1 modules, you must add the module to your project before the SDL suite can include the data types.

Follow the instructions below to add the ASN.1 module to your project.

  1. Save your ASN.1 module in a subdirectory to your project. Make sure that you append the .asn file extension to the saved module.
  2. Open the Organizer and select the chapter where you want to include the module. This is done by clicking the chapter marker, for instance the Other Documents marker, see Figure 191.

Figure 191 : Selection of chapter marker

  3. From the Edit menu, select the Add Existing... command. The Add Existing window opens.

Figure 192 : The Add Existing window

  4. Click the folder image button in order to find your ASN.1 module. The Select file to add window opens.
  5. Select the directory you want to search and change the search filter, by typing *.asn in the Filter field. Click the Filter button. The available ASN.1 modules are now displayed in the Files window. Select module and click the OK button. The Select file to add window closes.
  6. The selected module is now displayed in the Add Existing window. Just click the OK button to add the module to your system. The module should now be visible in the Organizer in your selected chapter.

The ASN.1 modules are now added to your project.

Example 1 : Adding ASN.1 modules to SDL project

In the SNMP example, the three modules RFC1155_SMI, RFC1157_SNMP and USE_SNMP have been added to the project.

Figure 193 : View of added ASN.1 modules

Importing ASN.1 Modules

After the modules have been added to the project, they must be made available to the SDL system. This is done by importing the modules to the SDL system file. When the modules have been imported, the ASN.1 data types can be used as regular SDL types.

Follow the instructions below to import the modules in the SDL diagrams:

  1. From the Organizer, open the system file, <system_name>.ssy.
  2. Enter the name of the added modules in the package reference frame, which is located outside the system frame. (See Figure 194).
  3. Save the diagram.

Example 2 : Importing ASN.1 modules

In the SNMP example, the three modules RFC1155_SMI, RFC1157_SNMP and USE_SNMP are imported.

Figure 194 : View of the imported ASN.1 modules

Assigning Values to the Data Types

When the modules are imported to the SDL system, you are free to declare signal parameters and variables of ASN.1 data types. The parameters and variables are treated as regular SDL parameters and variables, and you assign values to them in the same manner as you normally do.

When declaring signals that are transporting information defined using ASN.1, it is recommended that you define a top-level type of a ASN.1 module as the signal parameter.

When your variables have been assigned values, you have created the abstract syntax.

Example 3 : Assigning values to variables

In this example the variable Reply has been declared as the type Message. This type is a top-level type that is defined in the ASN.1 module SNMP1157.asn, see Example 10.

Figure 195 : Declaration of the reply variable

When the variable reply has been declared, you can use it in the SDL diagram as a regular SDL variable. Figure 196 shows how reply is used as the argument of a signal that has been received by the SDL system.

Figure 196 : Usage of the reply variable

Example 4 : Declaring signals

The signal snmp_reply in the previous example must be declared before it can be used. As mentioned before, the argument of the signal is a top-level type of the ASN.1 module.

Figure 197 : Signal Declarations


Creating the Transfer Syntax

The SDL suite offers several way to create the transfer syntax. The available coding access interfaces are:

  • Basic SDL interface
  • Extended SDL interface
  • C code interface

In this tutorial, only the C code interface will be covered. For a complete description of ASN.1 encoding and decoding, please see ASN.1 Encoding and De-coding in the SDL Suite.

Using the C code interface, the transfer syntax can be created either using the Organizer's make dialog or using the Targeting Expert. Both methods are presented in this tutorial. When using the Targeting Expert, you can select to use the Cadvanced SDL to C Compiler or the Cmicro SDL to C Compiler when creating the transfer syntax. Both methods will be covered as well.

This section starts with a short introduction and the actual instructions are presented in:

  • "Generating Template Files - the Organizer"
  • "Generating Template Files - Targeting Expert"

Introduction

To be able to transfer the abstract syntax between two nodes in network, you must first create the transfer syntax. The transfer syntax representation is then transmitted in a protocol buffer.

When creating the transfer syntax you must perform the following tasks:

  • Generating template files
  • Editing the generated template files

The template files must be generated in order for you to include the ASN.1 data types in the compilation and code generation processes. The template files extract information from your SDL system and create a skeleton. Often these template files do not contain sufficient information to meet the demands of the application and therefore you must edit the templates. The template files that are generated cover the following areas:

  • the environment functions
  • the make process

However, the SDL suite needs additional information in order to create the environment file. Before the generation you must determine which encoding/decoding schemes to use and you must create type nodes files.

Note: Environment File

There are several ways to create the environment file. This tutorial shows how to auto-generate the file. However, you can also make your own file from scratch. This procedure is more advanced and is only partially covered.

Note: Type Nodes

The type nodes are auto-created by ASN.1 Utilities and must not be edited.

Note: The Make process

The template makefile is only created if you are using the Make dialog. The default makefile of the Targeting Expert handles all necessary make functionality.

Environment Functions

The environment is defined as all devices or functions that are needed by the application but not specified within the SDL system. By sending signals to the environment, the SDL system wants certain tasks to be performed. This could be for instance:

  • reading or writing information to a file
  • sending or receiving messages across the network
  • reading or writing information on hardware ports or sockets

However, the SDL system only controls events that occur within the system. It does not specify how signals leaving the system are handled by the environment. This is why you must provide an interface between the SDL system and the environment. This interface is made up by the environment functions.

Figure 198 : The environment functions

The SDL suite is rather helpful and can generate a template environment file that includes a skeleton of the environment functions. The environment file is written in C code and by editing this file you can specify the behavior of signals from the SDL system and of signals going in to the SDL system.

An environment header file or system interface header file can also be created. This file contains all type definitions and other external definitions that are necessary in order to implement the environment functions.

Note: Environment files

There are several ways to create the environment file. You can:
  • auto-create the file. This procedure is covered in this tutorial.
  • make your own file from scratch. This is a more advanced procedure and is only partially covered in this tutorial.

Encoding/Decoding

When creating the transfer syntax, the messages that will be transferred must be encoded and the incoming messages must be decoded. The type of encoding rules to apply is specified in the environment file. This means that the encoding/decoding function calls must be included in the environment file.

The SDL suite supports the standard BER and PER encoding/decoding schemes, but it also allows you to use a user specified encoding scheme. ASCII encoding is available in the SDL suite as well, but it does not support encoding of ASN.1 types.

Type Nodes

To include the ASN.1 data types in your application, they must be translated into a form that the SDL suite understands. Within the SDL suite, this translation is handled by the ASN.1 Utilities.

The ASN.1 Utilities tool is invoked automatically when the SDL system is analyzed and it allows you to:

  • perform syntactic and semantic analysis of your ASN.1 modules
  • generate SDL code from the ASN.1 modules
  • generate type information for encoding and decoding using BER or PER

This means that when you are using the ASN.1 utilities, you create type nodes. A type node is a static variable that describes the properties and characteristics of an ASN.1 data type, including tag information needed by BER/PER encoders and decoders. The variable is named yASN1_<type_name>.

All nodes are generated in files named <asn1module_name>_asn1coder.c and declarations to access them in files named <asn1module_name>_asn1coder.h.

Note:

The type nodes are auto-created by ASN.1 Utilities and must not be edited.

Make Process

Note: Make dialog only

This section is only valid if you build and analyze your project using the Organizer's make dialog.

The default makefile in the SDL suite, determines the relationship between source files, header files, object files and libraries in your project.

However, the default makefile does not include the generated files in the make process. To include the environment files and the type node files in the make process, you must generate a template makefile that will be appended to the default makefile, see Figure 199. The template makefile can be generated by the SDL suite.

Figure 199 : The make process

Generating Template Files - the Organizer

Follow the instructions below to generate environment files, type node files and the template makefile using the Organizer's Make dialog:

  1. Click the SDL system symbol in the Organizer.
  2. From the Generate menu, select the Make... command. The SDL Make window opens.
  3. Specify your options in the make dialog according to the following list:
    • Select Analyze & generate code
    • From the Code generator drop-down list, select Cadvanced
    • Select Generate environment header file
    • Select Generate environment functions
    • Select Generate ASN.1 coder, to invoke ASN.1 Utilities.
    • From the Use standard kernel drop-down list, select Application

Note:

Make sure that you de-select the Compile & link option as you only want to generate the template files.

  4. Specify your target directory where the generated files will be stored.
    Figure 200 shows the Make dialog with the selected options.

Figure 200 : The Make dialog - generating template files

  5. Press the Full Make button.

Note:

Encode and decode calls are only generated if the Generate ASN.1 coder option is enabled in the make dialog.

In your target directory, you will now find the generated files including:

  • <system_name>_env.c
    This is the environment skeleton file.
  • <system_name>.ifc
    This is the environment header file.
  • <system_name>_env.tpm
    This is the template makefile.
  • <asn1module_name>_asn1coder.c
    <asn1module_name>_asn1coder.h
    These files are the type nodes created by the ASN.1 utilities.

Editing the Generated Files - the Organizer

As the generated files only consist of skeleton functions, you must edit the files to suit the functionality of your application.

Note:

Make a habit of making a copy of the environment file and the template makefile after they have been edited. Otherwise the edits will be overwritten, if the files are re-generated from the Make dialog by mistake.

  1. Edit the environment file <system_name>_env.c file using any text editor. In the skeleton file, macros are included but they are not defined. To define the macros, create a <system_name>_env.h file and enter the code manually. Example 5 shows the unedited SNMP environment file.
  2. Save the environment file.
  3. Edit the template makefile <system_name>_env.tpm if necessary.
  4. Save the template makefile.
  5. Make copies of the edited files and save the copies in a different folder.

Notes:

  • In order to transfer the information on the network, you must add socket commands to an appropriate header file.
  • If you want to use more than one encoding scheme, for instance BER and PER, you must enter the appropriate encoding function calls in the environment file

Example 5 : Environment Functions

The following code is part of the environment file skeleton and displays the function that handles the out signals.
XENV_OUT_START

/* Signals going to the env via the channel Signal_env */

/* Signal snmp_request */
IF_OUT_SIGNAL(snmp_request,"snmp_request")
OUT_SIGNAL1(snmp_request,"snmp_request")
XENV_BUF(BufInitWriteMode(Buf));
XENV_ENC(BER_ENCODE(Buf, (tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDef_snmp_request *)(*SignalOut))->Param1));
OUT_SIGNAL2(snmp_request,"snmp_request")
XENV_BUF(BufCloseWriteMode(Buf));
RELEASE_SIGNAL
END_IF_OUT_SIGNAL(snmp_request,"snmp_request")

/* Signal Init */
IF_OUT_SIGNAL(Init,"Init")
OUT_SIGNAL1(Init,"Init")
XENV_BUF(BufInitWriteMode(Buf));
OUT_SIGNAL2(Init,"Init")
XENV_BUF(BufCloseWriteMode(Buf));
RELEASE_SIGNAL
END_IF_OUT_SIGNAL(Init,"Init")

/* Signal Close */
IF_OUT_SIGNAL(Close,"Close")
OUT_SIGNAL1(Close,"Close")
XENV_BUF(BufInitWriteMode(Buf));
OUT_SIGNAL2(Close,"Close")
XENV_BUF(BufCloseWriteMode(Buf));
RELEASE_SIGNAL
END_IF_OUT_SIGNAL(Close,"Close")
}

Encoder and Decoder function calls

As stated earlier, it is not necessary to auto-create the environment file. By copying another environment file or by writing it from scratch, you can customize the environment file for your needs. If you do so you must use the correct syntax of the encoding and decoding functions.

The syntax of the BER function calls is:

BER_ENCODE (
Buffer,
&Typenode,
&Signalparameter)

BER_DECODE (
   Buffer,
   &Typenode,
   &Signalparameter)

The syntax of the PER function calls is:

PER_ENCODE (
Buffer,
&Typenode,
&Signalparameter)

PER_DECODE (
   Buffer,
   &Typenode,
   &Signalparameter)

Example 6 : Encoding and Decoding function calls

The following function calls are being used in the SNMP example:
BER_ENCODE(Buf, (tASN1TypeInfo *)&yASN1_Message,
   (void *)&((yPDef_snmp_request *)(*SignalOut))->Param1));

BER_DECODE(Buf, (tASN1TypeInfo *)&yASN1_Message,
   (void *)&((yPDef_snmp_reply *)SignalIn)->Param1))

Decoding incoming signals

Before the SDL system can use the information that is encapsulated in the incoming signals, a number of tasks must be performed. Most of them are automatically performed by the SDL suite, but some must be handled manually.

The following list defines the steps involved in the decoding process. You must perform steps 1 and 2 manually, while steps 3 through 5 are generated by the SDL suite:

  1. In order to auto-generate a correct environment file, declare incoming and outgoing signals in the SDL system. If signal parameters are declared as ASN.1 types, a top-level node in the ASN.1 module should be used, see Example 4. It is recommended that you use the same top-level type when decoding as you do when encoding.
  2. Extract the encoded information from the protocol-specific packet and transfer it to a data buffer. This should be implemented in C code in the environment file. Instructions and further information is available in Building an Application

The functions and function calls of the following functionality are auto-generated in the environment file.

  3. Memory for the signal structure is allocated.
  4. The BER_DECODE function is called. The function is defined in the decoding library and handles the actual decoding process.
  5. The decoded signal is sent to the SDL system. This is performed by the SDL_Output function.

Generating Template Files - Targeting Expert

Follow the instructions below to generate environment files, type node files and the template makefile using the Targeting Expert.

  1. From the Generate menu, select the Targeting Expert command. The SDL Targeting Expert window opens.
  2. From the drop-down menu located above the Partitioning Diagram Model frame, select Light Integrations and the desired SDL to C Compiler. It is possible to used either Cadvanced or Cmicro. The pre-defined alternative specifies the type of compiler needed for the generation.
  3. Select the SDL to C Compiler tab.
  4. In the General box, select Analyze/generate code.
  5. In the Environment box, select:
    • Environment functions
    • Environment header file
  6. Select the Communication tab. In the Coders box, select the Generate ASN.1 coder functions check box.
  7. Press the Full Make button. This generates the environment file.

Note:

Encode and decode calls are only generated if the Coder functions... option is enabled.

In your target directory, you will now find the generated files including:

  • <system_name>_env.c (Cadvanced)
    env.c (Cmicro)
    This is the environment skeleton file.
  • <system_name>.ifc
    This is the environment header file.
  • <asn1module_name>_asn1coder.c
    <asn1module_name>_asn1coder.h
    These files are the type nodes created by the ASN.1 utilities.

Editing the Generated Files - Targeting Expert

As the generated files only consist of skeleton functions, you must edit the files to suit the functionality of your application.

Note:

Make a habit of making a copy of the environment file after it has been edited. Otherwise the edits will be overwritten, if the file is re-generated by mistake.

  1. Rename the environment file.
  2. Edit the environment file <system_name>_env.c file according to your needs. In the skeleton file, macros are included but they are not defined. To define the macros, create a <system_name>_env.h file and enter the code manually. Example 7 shows the unedited SNMP environment file.
  3. Save the environment file.

Notes:

  • In order to transfer the information on the network, you must add socket commands to an appropriate header file.
  • If you want to use more than one encoding scheme, for instance BER and PER, you must enter the appropriate encoding function calls in the environment file

Example 7 : Environment Functions - Cadvanced

The following code is part of the environment file skeleton and displays the function that handles of the out signals.
XENV_OUT_START

/* Signals going to the env via the channel Signal_env */

/* Signal snmp_request */
IF_OUT_SIGNAL(snmp_request,"snmp_request")
OUT_SIGNAL1(snmp_request,"snmp_request")
XENV_BUF(BufInitWriteMode(Buf));
XENV_ENC(BER_ENCODE(Buf, (tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDef_snmp_request *)(*SignalOut))->Param1));
OUT_SIGNAL2(snmp_request,"snmp_request")
XENV_BUF(BufCloseWriteMode(Buf));
RELEASE_SIGNAL
END_IF_OUT_SIGNAL(snmp_request,"snmp_request")

/* Signal Init */
IF_OUT_SIGNAL(Init,"Init")
OUT_SIGNAL1(Init,"Init")
XENV_BUF(BufInitWriteMode(Buf));
OUT_SIGNAL2(Init,"Init")
XENV_BUF(BufCloseWriteMode(Buf));
RELEASE_SIGNAL
END_IF_OUT_SIGNAL(Init,"Init")

/* Signal Close */
IF_OUT_SIGNAL(Close,"Close")
OUT_SIGNAL1(Close,"Close")
XENV_BUF(BufInitWriteMode(Buf));
OUT_SIGNAL2(Close,"Close")
XENV_BUF(BufCloseWriteMode(Buf));
RELEASE_SIGNAL
END_IF_OUT_SIGNAL(Close,"Close")
}

Example 8 : Environment functions - Cmicro

The following code is part of the environment file skeleton and displays the function that handles of the out signals.

switch (xmk_TmpSignalID)
{
case snmp_request :
{
/* BEGIN User Code */
/* Use (yPDP_snmp_request)xmk_TmpDataPtr to access the signal's parameters */
/* ATTENTION: the data needs to be copied. Otherwise it */
/* will be lost when leaving xOutEnv */
/* This section can be used to encode outgoing data with the selected coder functions.
** Please remove the comments and send the data with your communications interface!
** (<SendViaCommunicationsInterface( data, datalen )> must be replaced)
char* data;
int datalen;

BufInitWriteMode( Buf );
XENV_ENC( PER_ENCODE( Buf, (tASN1TypeInfo *) &yASN1_z_RFC1157_SNMP_0_Message,
(void *) &((yPDef_snmp_request *)xmk_TmpDataPtr)->Param1));
BufCloseWriteMode( Buf );
BufInitReadMode( Buf );
datalen = BufGetDataLen(Buf);
data = BufGetSeg( Buf, datalen );
<SendViaCommunicationsInterface( data, datalen )>;
BufCloseReadMode( Buf );
*/
/* Do your environment actions here. */
xmk_result = XMK_TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code */
}
break ;

case Init :
{
/* BEGIN User Code */
/* Do your environment actions here. */
xmk_result = XMK_TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code */
}
break ;

case Close :
{
/* BEGIN User Code */
/* Do your environment actions here. */
xmk_result = XMK_TRUE; /* to tell the caller that */
/* signal is consumed */
/* END User Code */
}
break ;

default :
xmk_result = XMK_FALSE;/* to tell the caller that */
/* signal is NOT consumed */
/* and to be handled by */
/* the Cmicro Kernel ... */
break ;
}

Encoder and Decoder function calls

As stated earlier, it is not necessary to auto-create the environment file. By copying another environment file or by writing it from scratch, you can customize the environment file for your needs. If you do so you must use the correct syntax of the encoding and decoding functions.

The syntax of the BER function calls is:

BER_ENCODE (
Buffer,
&Typenode,
&Signalparameter)

BER_DECODE (
   Buffer,
   &Typenode,
   &Signalparameter)

The syntax of the PER function calls is:

PER_ENCODE (
   Buffer,
&Typenode,
&Signalparameter)

PER_DECODE (
   Buffer,
   &Typenode,
   &Signalparameter)

Example 9 : Encoding and Decoding function calls

The following function calls are being used in the SNMP example:
BER_ENCODE(Buf, (tASN1TypeInfo *)&yASN1_Message,
   (void *)&((yPDef_snmp_request *)(*SignalOut))->Param1));

BER_DECODE(Buf, (tASN1TypeInfo *)&yASN1_Message,
   (void *)&((yPDef_snmp_reply *)SignalIn)->Param1))

Decoding incoming signals

Before the SDL system can use the information that is encapsulated in the incoming signals, a number of tasks must be performed. Most of them are automatically performed by the SDL suite, but some must be handled manually.

The following list defines the steps involved in the decoding process. You must perform steps 1 and 2 manually, while steps 3 through 5 are generated by the SDL suite:

  1. In order to auto-generate a correct environment file, declare incoming and outgoing signals in the SDL system. If signal parameters are declared as ASN.1 types, a top-level type in the ASN.1 module should be used, see Example 4. It is recommended that you use the same top-level type when decoding as you do when encoding.
  2. Extract the encoded information from the protocol-specific packet and transfer it to a data buffer. This should be implemented in C code in the environment file. Instructions and further information is available in Building an Application.

The functions and function calls of the following functionality are auto-generated in the environment file.

  3. Memory for the signal structure is allocated.
  4. The BER_DECODE function is called. The function is defined in the decoding library and handles the actual decoding process.
  5. The decoded signal is sent to the SDL system. This is performed by the SDL_Output function.


Compiling Your Application

After you have created the transfer syntax, you are ready to compile and build your application, including the edited environment file and the template makefile. Follow the appropriate instructions as presented in:

  • "Using the edited files - Organizer"
  • "Using the edited files - Targeting Expert"

Using the edited files - Organizer

Please follow the instructions below:

  1. Click the SDL system symbol in the Organizer
  2. From the Generate menu, select the Make... command. The SDL Make window opens.
  3. Change your options in the make dialog according to 0 following list:
    • Select Analyze & generate code
    • From the Code generator drop-down list, select Cadvanced
    • De-select Generate environment header file
    • De-select Generate environment functions
    • De-select Generate ASN.1 coder
    • Select the Makefile button
    • Select Generate makefile and use template and enter the generated template makefile .... /<new_name>_env.tmp in the text field.
    • Select Compile & link
    • From the Use standard kernel drop-down list, select Application.
      Figure 201 shows the Make dialog with the selected options.

Figure 201 : The Make dialog - Compiling

  4. Specify your target directory where the generated files will be stored.
  5. Press the Full Make button.

Using the edited files - Targeting Expert

Please follow the instructions below:

  1. Select the SDL to C Compiler tab.
  2. In the Environment box, de-select the Environment functions option and the Environment header file option.
  3. Press the Full Make button.


Appendix A

Example 10 : The RFC1157 ASN.1 Module

RFC1157-SNMP DEFINITIONS ::= BEGIN

IMPORTS
ObjectName, ObjectSyntax, NetworkAddress, IpAddress, TimeTicks
FROM RFC1155-SMI;

-- top-level message

Message ::=
SEQUENCE {
version -- version-1 for this RFC
INTEGER {
version-1(0)
},

community -- community name
OCTET STRING,

data -- e.g., PDUs if trivial
PDUs --ANY-- -- authentication is being used
}

-- protocol data units

PDUs ::=
CHOICE {
get-request
GetRequest-PDU,

get-next-request
GetNextRequest-PDU,

get-response
GetResponse-PDU,

set-request
SetRequest-PDU,

trap
Trap-PDU
}

GetRequest-PDU ::=
[0]
IMPLICIT SEQUENCE {
request-id
RequestID,

error-status -- always 0
ErrorStatus,

error-index -- always 0
ErrorIndex,

variable-bindings
VarBindList
}
GetNextRequest-PDU ::=
[1]
IMPLICIT SEQUENCE {
request-id
RequestID,
error-status -- always 0
ErrorStatus,

error-index -- always 0
ErrorIndex,

variable-bindings
VarBindList
}
GetResponse-PDU ::=
[2]
IMPLICIT SEQUENCE {
request-id
RequestID,
error-status
ErrorStatus,

error-index
ErrorIndex,

variable-bindings
VarBindList
}
SetRequest-PDU ::=
[3]
IMPLICIT SEQUENCE {
request-id
RequestID,

error-status -- always 0
ErrorStatus,

error-index -- always 0
ErrorIndex,

variable-bindings
VarBindList
}

Trap-PDU ::=
[4]

IMPLICIT SEQUENCE {
enterprise -- type of object generating
-- trap, see sysObjectID in [5]
OBJECT IDENTIFIER,

agent-addr -- address of object generating
NetworkAddress, -- trap

generic-trap -- generic trap type
INTEGER {
coldStart(0),
warmStart(1),
linkDown(2),
linkUp(3),
authenticationFailure(4),
egpNeighborLoss(5),
enterpriseSpecific(6)
},

specific-trap -- specific code, present even
INTEGER, -- if generic-trap is not
-- enterpriseSpecific

time-stamp -- time elapsed between the last
TimeTicks, -- (re)initialization of the network
-- entity and the generation of the trap

variable-bindings -- "interesting" information
VarBindList
}

-- request/response information
RequestID ::=
INTEGER

ErrorStatus ::=
INTEGER {
noError(0),
tooBig(1),
noSuchName(2),
badValue(3),
readOnly(4),
genErr(5)
}

ErrorIndex ::=
INTEGER

-- variable bindings

VarBind ::=
SEQUENCE {
name
ObjectName,

value
ObjectSyntax
}

VarBindList ::=
SEQUENCE OF
VarBind

END


9 Tutorial: Using SDL-2000 features

This tutorial describes how to use the SDL-2000 features in Telelogic Tau.

In order for you to fully take advantage of this tutorial, you should be familiar with the SDL suite and the SDL Editor functionality.

This tutorial is independent from the Demon game example presented in the tutorial on the editors and the Analyzer.

You can find additional information on how to use the SDL-2000 features in "Working with Classes.


Purpose of this Tutorial

The purpose of this tutorial is to make you familiar with the SDL-2000 support in Telelogic Tau SDL Suite.


Introduction

Support in the SDL Suite

The Telelogic Tau SDL Suite supports the following SDL-2000 related features:

  • Graphical design of data types (using class symbols)
  • Textual algorithms
  • Case sensitivity
  • Operators without parameters
  • Operators without return results.

Why SDL-2000?

The useful features in UML are included in SDL to facilitate the transport from UML to SDL.


Graphical Design of Data Types

Telelogic Tau SDL Suite offers the following graphical data type design features:

  • Class Symbols
  • Association Lines
  • Aggregation Lines
  • The Browse & Edit Class dialog, see Editing a Diagram.
  • The Class Information dialog, see Viewing a Class.

Class Symbols

With class symbols you can graphically design data types. The SDL editor handles class symbols much the same way as other SDL symbols.

Figure 202 Class symbol

A class symbol has three separate text fields:

  • name field (1)
  • attribute field (2)
  • operator field (3)

The properties of a class symbol can be set in the preference manager in the same way as for other SDL symbols, except for case sensitivity, see "Case Sensitivity" . The size of the class symbol is adjusted to the size of the text, and you cannot change them manually. Class symbols cannot be collapsed or expanded.

Association and Aggregation Lines

There are two types of lines:

  • Association lines
  • Aggregation lines

Figure 203

Association Lines

An association links two types using UML notation. The types are:

  • Block types
  • Process types
  • Data types
  • Interfaces

Association lines can be both redirected and bidirected. Single association lines (unidirectional associations) have a name and a role name. Double association lines (bidirectional associations) have a name and two role names.

Figure 204 : Example of an association line

Aggregation Lines

Aggregations use the same format as associations.

Aggregations are used to indicate that a class is a subset of another class or a part-of relationship, e.g. a steering wheel is a subset of or a part of a car. Aggregations can only be single directed.

Figure 205 : Example of an aggregation line.


Creating an SDL Structure

In this section you will create a small example and perform a number of actions to learn what possibilities and limitations there are in the SDL-2000 support in the SDL Suite.

Figure 206 :SDL diagram with class symbols

Working with Class Symbols

  1. Start the SDL Editor.
  2. Place a class symbol in the diagram.
    You place symbols the same way as other SDL symbols, see "Placing Block Reference Symbols" . You can move symbols but not resize them.
  3. Name the class symbol Person.
    All class symbols with the same class name are treated as a single, merged class. See "Limitations" for more information on naming issues.
  4. Fill out the attribute and operator fields.
  5. Place two more class symbols in the diagram and name them Company and Xid.
  6. Fill out the attribute and operator fields.

Working with Lines

  1. Click the class symbol Person. Two handles appears.
  2. Select the square association handle and drag it to the class symbol Company. The editor draws a line while you are dragging. You drag lines the same way as lines in other SDL diagrams, see "Drawing Channels between Blocks" .

Figure 207

  3. Click the mouse button when you have reached the class symbol Company. The line is connected at both ends.
  4. Name the association line and the role.

The name of an association is often a verb phrase and the role often has a noun as a name.

Figure 208

  5. Bidirect the line by selecting Bidirect from the Edit menu.
  6. Give the second role a name.
  7. Select the diamond shaped aggregation handle and drag it to the class symbol Xid.
  8. Name the aggregation line and the role.

Moving Symbols and Lines

You move symbols and lines the same way as in other SDL diagrams, see "Moving and Resizing Symbols" .

Saving the Diagram

  1. Save the diagram by the menu choice Save, by clicking the Save button or by <Ctrl> s.
    The file is saved with the extension .ssy.


Editing a Diagram

The Browse & Edit Class dialog lets you view and edit the complete definition of a class to ensure consistency between the attributes and operators.

The dialog consists of two parts. The above part is where you browse classes and all occurrences of each class. In the below part you can edit the name, attributes and operators of a class.

All symbols that belong to the class you select in the Browse & Edit Class dialog will be affected by the changes you make in the dialog. If you want to edit the content in only one class symbol, you have to select the single symbol and edit the content in that symbol. For detailed information on how to edit class information, see"Browse & Edit Class Dialog" .

Figure 209 : The Browse & Edit Class dialog

Case Sensitivity

Case sensitivity applies to class symbols and it cannot be turned off in the Preference Manager, though case sensitivity for other symbols in the SDL editor can be switched off.

Class sensitivity applies to both the name field and the attribute field as well as the operator field.

If two classes have the same name but different cases (for example Person and person), they will be treated as two separate classes in the Browse & Edit Class dialog and will not be merged into a single class when generating code.

For a detailed description, see "Set-Case-Sensitive" .

Limitations

You can edit a class in this dialog when you have selected a single class symbol, but the dialog is not available if you select more than one class symbol.

If the class name contains incorrect syntax the dialog will not be displayed.

You cannot add syntax errors to your classes as the values you enter are syntactically checked.

Incorrect text in a symbol is not displayed in the dialog.

Edit the Diagram

  1. Double-click the class Xid or select the class Xid and then select Class.. on the Edit menu.
    The Browse & Edit Class dialog is displayed with the class name and its attributes or operators filled in.
    If there are more than one class with the same name, attributes or operators for all classes with the same name will be shown in the dialog.
  2. Select class Person from the Classes drop down menu. The content of the attributes and operators fields changes to that of the class Person.
  3. Change the name of the class Person to Employed in the Class Name field and click OK.
    The class name has changed to Employed in the diagram.
  4. Open the Browse & Edit Class dialog again and select either of the radio buttons Attributes or Operators to edit or view the attributes or operators of the class Employed.
    The list of the attributes or operators is displayed in the field below the radio buttons.
  5. You can now edit the information in the Name, Parameters, Sort and Body Code fields.
    The Parameters and Body Code fields are for operators only.
  6. Click OK.
    The dialog is closed and all appropriate class symbols in the current SDL diagram are updated.


Viewing a Class

The Class Information dialog lets you view the complete textual (PR) definition of a class in read-only format. If you want to edit the diagram, see "Editing a Diagram" .

For detailed information on how to view class information, see "Class Information" .

Figure 210 : The Class Information dialog

Limitations

The dialog is not available if you select more than one class symbol.

View the Definition

  1. Rename two or more classes with identical names (for testing of the Class information dialog).
  2. Select one of the classes and then select Class Information on the Window menu.
    The Class Information dialog, with the PR code for all classes with the same name, is displayed.
  3. Select the Show Next Symbol button.
    The next symbol, which is described by the line on which the cursor is placed, is displayed.
    The number in brackets shows the number of symbols that are described by this line in the current diagram. You can browse through all symbols, one by one, with the Show Next Symbol button.
  4. If you decide that you want to edit the class, select the Edit Class button and the Browse & Edit Class dialog for that class is displayed.


Textual Algorithms

Textual Algorithms

Telelogic Tau SDL Suite supports textual descriptions of algorithms. Algorithms can be expressed within a Task symbol, e.g. if-then-else, loops and decisions. For a detailed description of this feature, see "Algorithms in SDL" .


Operators without Parameters and Operators without Return Results

Telelogic Tau SDL Suite supports operators with no parameters or no return value. For example, an alternative to an assignment statement could be that an operator application statement invokes a non value returning operator.

For a detailed description of operators and parameters, see "Operators" .


Limitations

The following limitations are worth noticing:

  • Inheritance lines are not supported.
  • Comments added to a class symbol will not appear in the generated PR code.
  • CIF code generation for class symbols is not supported.
  • If the same association has been drawn in several places, all instances have to be edited to change the association.
  • Navigating from a class symbol is possible only by using Tools>Navigate, since double-clicking a class symbol will open the Browse & Edit Class dialog.


An Example of Using Class Symbols

Figure 211 Graphical representation of a data structure

The operator definition must be added in the Body Code part of the Browse & Edit Class dialog. It might look like this:

operator retired returns Boolean { /*start of user defined body code*/
return age > 64;
/* End of user defined body code */}

The above graph will then generate the following PR code.

newtype Person struct
employer Own_Company;
a_Company Ref_Company;
id Ref_XId;
age Integer;
name CharString;
operators
retired: -> Boolean;
operator retired returns Boolean {/*start of user defined body code*/
return age > 64
/* End of user defined body code */}
endnewtype;
newtype Ref_Person Ref(Person); endnewtype;
newtype Own_Person Own(Person); endnewtype;
newtype Oref_Person Oref(Person); endnewtype;
newtype XId struct
idName CharString;
idNo Integer;
endnewtype;
newtype Ref_XId ref(XId); endnewtype;
newtype Own_XId own(XId); endnewtype;
newtype Oref_XId oref(XId); endnewtype;
newtype Company struct
employee Oref_Person;
a_Person Ref_Person;
name CharString;
endnewtype;
newtype Ref_Company Ref(Company); endnewtype;
newtype Own_Company Own(Company); endnewtype;
newtype Oref_Company Oref(Company); endnewtype;


10 Tutorial: Threaded Integration

The Threaded Integration model provides a powerful template for integrating generated C code with an operating system. In this tutorial, you will practice building applications using this model. You will get hands-on experience by building the SDL system "Mobile", which is an implementation of a small GSM system.

This tutorial requires basic knowledge of the SDL suite editors, the Organizer and the Targeting Expert. Brief knowledge of SDL and integration with operating systems will also help your understanding. Before working with this tutorial, it is recommended that you read through 64 Integration with Operating Systems.

To get the most out of this tutorial, read the entire chapter. As you progress, perform the exercises on your computer as described.


Introduction

The purpose of this tutorial is to make you familiar with the Threaded Integration model. After reading the tutorial, you should have a basic understanding of how to build a "threaded" executable and how to integrate it with external code.

This tutorial is designed as a guided tour through the build tools in the SDL suite. You will get acquainted with the Deployment Editor and the Targeting Expert.

Note: Platform differences

This tutorial, and the others that are possible to run on both the Solaris and Windows platforms, are described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on Solaris", "Windows only", etc. When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.
Normally, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see when running the SDL suite in your environment. Only if a screen shot differs in an important aspect between the platforms will two separate screen shots be shown.

Prerequisites

Windows

  • C compiler
  • Resource compiler

Solaris

  • C compiler
  • Motif (Library for GUI widgets) version 1.2 or later


Description of Example System

The SDL System

Functional Description

The example system is a model of a GSM system. The implementation is restricted to the high-level layers of the GSM standard. The following functionality is implemented:

  • User PIN code verification (PIN code is one digit only)
  • Tracking of mobile phones through VLR and HLR databases
  • Freedom of movement for mobile phones by base station switching
  • Control of the IMEI code of a mobile phone
  • Billing service to keep track of elapsed time and cost for phone calls

Implementation Description

The system is implemented in a modular way. Each functional entity is implemented as a block type. The block types are organized in a package, called "GSM".

The SDL system uses the GSM package and instantiates its block types. The "Mobile" system has four MobileStation block instances, four BaseTransceiverStation block instances and two MobileSwitchingCenter block instances. The MobileStation instances are named as mobile phone owners. The names are Marie, John, ParisPizza and LyonPizza. The BaseTransceiverStation instances are named Lyon11, Lyon12, Paris11 and Paris12, indicating their location.

The Target Application

Deployment

The Mobile system is partitioned into five executable files. Each MobileStation block instance is built as an executable and the remaining block instances (Proxy, BaseTranscieverStation, BaseStationController, MobileSwitchingCenter and Database) execute together in one executable.

The Graphical User Interface

A graphical user interface (GUI) is provided for the MobileStation block. It is delivered as C source code to be compiled and linked when building each of the four mobile phone executable files. The interface resembles that of a typical mobile phone. A simple menu system, containing a phone book and a billing report, is provided. The user can switch base station from the option menu in the bottom of the window. The GUI is shown in Figure 212.

Figure 212 : The Mobile Phone GUI

TCP/IP Communication

The executable files of the target application communicate by sending signals via TCP/IP. The communication is handled by the SDL suite TCP/IP communication module, which is delivered as C source code. It is compiled and linked into each of the executables.

To be able to locate the receiver of a signal, the TCP/IP module needs the host name and TCP port number of the receiving executable. This information must be supplied through a routing function, which is manually implemented in C.

The mobile system is delivered with default routing functions. This will enable you to run all executables on your computer without giving any routing information manually.

Figure 213 shows a UML component diagram of the executable files in the deployed mobile system. Each executable file sets up a TCP/IP server, listening on a specific TCP port number. This number is used by remote executables for addressing SDL signals. The TCP/IP server is illustrated by the interface on each component. The dashed arrows indicate a flow of signals from one component to another.

Figure 213 : A Component Diagram Showing the Deployed Mobile System


Preparations

Copy the Example System

In order to allow experimentation, you should copy the example system from the SDL suite installation into a working directory of your preference:

UNIX

Copy all files from the directory
$telelogic/sdt/examples/mobile
to a working directory, e.g. ~/mobile.

Windows

Copy all files from the directory
C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\mobile
to a working directory, e.g.
C:\Telelogic\SDL_TTCN_Suite4.4\work\mobile.

Open the System

Open the system file Mobile.sdt from the Organizer.


Drawing a Deployment Diagram

In order to build a threaded executable, you must supply information about the threads of the application. For each thread, you must specify which SDL instance sets that should run inside it. Finally, you may want to partition your SDL system into several executable files.

This information is modeled using Deployment Diagrams. These are edited using the Deployment Editor. The Deployment Diagram provides a way to model deployment of SDL systems independently of the target platform.

What You Will Learn

  • To start the Deployment Editor
  • To deploy an SDL system onto executable files and threads

Starting the Deployment Editor

  • Double-click the deployment symbol "network_depl" in the Organizer. The Deployment Editor is launched with the selected diagram.

Deploying an SDL System

The Deployment Diagram features:

  • Partitioning of SDL systems
  • Organization of SDL instance sets within executable files
  • Organization of SDL instance sets within threads (Threaded Integration only)

A deployment diagram has five symbols: the node, the component, the thread, the object and the comment symbols. Each symbol is described in Table 1.

Table 1
Symbol | Name | Description
 | Node | A computational resource, i.e. a computer
 | Component | An executable file which contains SDL instance sets
 | Thread | A point of execution. The symbol is used for threaded integrations only
 | Object | An SDL instance set, i.e. a system, block or process instance set
Deployment Diagram Symbols

The symbols are connected using compositions. When a symbol is selected in a diagram, a handle is shown at its bottom. Click the handle to create a composition link. Click the symbol you wish to connect to.

The name of each symbol can be edited from the diagram area. Some of the symbols contain additional information, which is edited from the Symbol Details dialog box.

The network_depl deployment diagram is shown in Figure 214.

Figure 214 : The network_depl Deployment Diagram

The diagram shows five components, each representing an executable file. All components are attached to one node. Each component has one or many threads. Each thread has one or many objects attached to it, reflecting the SDL instance sets that execute inside it.

For instance, the "JohnMS" component contains one thread, "T". The thread has one object attached to it, called "JohnMS". The object reflects an SDL instance set in the network SDL system. Look at the Organizer window and compare the block instance sets shown in the system with the objects in the deployment diagram.

The Symbol Details Dialog Box

The dialog box is opened in one of the following ways:

  • Double-click a diagram symbol
  • Right-click a diagram symbol. Select Symbol Details... in the pop-up menu.

Component

Double-click the component named "John". The symbol details dialog box will appear. The dialog box is shown in Figure 215.

Figure 215 : The Symbol Details dialog box for Component "John"

The integration model can be selected from a drop-down list in the dialog box. The selected integration model controls the code generation parameters for the executable file that is generated from the component. Three integration models can be selected: Light, Threaded and Tight.

For the "John" component, the selected integration model is "Threaded". The information filled in the other text boxes is not used for code generation.

Thread

Click the thread symbol "T". The dialog box will change its content to reflect that of the thread. The new appearance of the dialog box is shown in Figure 216.

Figure 216 : The Symbol Details Dialog Box for Thread "T"

For a thread, four parameters can be set for performance-tuning of the generated executable:

  • Stack Size
  • Thread Priority
  • Queue Size
  • Max Signal Size

The values of these parameters are specific to the target operating system. If no values are given, default values are used. All threads in the network_depl deployment diagram use default values.

Object

Click the object symbol "JohnMS". The dialog box will change its content to reflect that of the object. The new appearance of the dialog box is shown in Figure 217.

Figure 217 : The Symbol Details Dialog Box for Object "JohnMS"

For an object, two parameters are mandatory to fill in:

  • Stereotype
  • Qualifier

The stereotype is the type of SDL instance set. The possible values are "system", "block" and "process". "JohnMS" is a block, which is reflected in the stereotype text box.

The qualifier is used to identify the SDL instance set. Locate the "JohnMS" block in the Organizer window. The block instance set is located directly under the "network" system. This renders the qualifier "network/johnMS".

The network_depl diagram is complete. The next step is to build executable files from the diagram.

More information on the Deployment Editor is available in The Deployment Editor.


Using the Targeting Expert

What You Will Learn

  • To start the Targeting Expert
  • To build executable files from a deployment description
  • To configure C code generation from the Targeting Expert GUI
  • To configure your compiler and linker from the Targeting Expert GUI

Starting the Targeting Expert

The deployment diagram should be used as input to the Targeting Expert.

Right-click the network_depl diagram symbol in the Organizer and select Targeting Expert from the pop-up menu.

The deployment diagram will be analyzed. If any errors are found, the Organizer Log pops up and shows an error message. You can locate the error in the deployment diagram by clicking on the "Show error" button in the Organizer Log toolbar.

The Targeting Expert is launched.

Selecting Target Platform

The initial appearance of the Targeting Expert window is shown in Figure 218.

Figure 218 : The Targeting Expert When First Opened

The left part of the window, called Partitioning Diagram Model, shows a filtered view of the deployment diagram. The nodes and components are represented.

For each component, do the following:

  1. Select the component in the Partitioning Diagram Model window.
  2. Click the drop-down list containing "SELECT INTEGRATION". A menu with available integrations is opened. As the component has "Threaded" as integration (selected in the Deployment diagram), this is the only available selection.
  3. Select the platform in the sub-menu.
    • Windows: Select Win32 Threaded (CAdvanced)
    • Solaris: Select Solaris Threaded (CAdvanced)
  4. A dialog-box will pop up, asking if the SDL system should be automatically generated. Click Yes.

The Targeting Expert window now looks as in Figure 219.

Figure 219 : Components with Selected Integration Models

Configuring C Code Generation

The Targeting Expert GUI for C code generation has four tabs. These are SDL to C Compiler, Communication, Environment Header File and Execution. All these tabs contain widgets for configuring the code generation for an executable.

Each of the executable files that will be built have communication through external code. All executables use the TCP/IP communication module and the mobile phone executables (John, Marie, ParisPizza and LyonPizza) use a GUI. The external code is connected to the SDL system through environment functions. The generation of environment functions must be configured manually.

The Targeting Expert features a wizard for easy configuration of the TCP/IP module. When activating the wizard, all the necessary environment functions will be generated by default.

The TCP/IP wizard dialog box is shown in Figure 220.

Figure 220 : The TCP/IP Wizard

The TCP/IP module needs routing information to send signals to the correct recipient. A C header file with the routing function declaration must be included. The routing function definition must be given in a C source file. The TCP port number for incoming signals must also be given. This number is used by routing functions in remote executables sending signals to this executable.

For each of the components, do the following:

  1. Click the name of the integration in the left sub-window.
    • Windows: Click Win32 Threaded
    • Solaris: Click Solaris Threaded
  2. Select the Communication tab.
  3. Click in the TCP/IP check box in the Signal Sending group. The TCP/IP Wizard is opened.
  4. Click in the check box Include routing header file.
  5. Click the file button to the right of the header file text box. A file selection dialog box is opened.
  6. Select the routing header file in your working directory.
    • If you build the John, Marie, ParisPizza or LyonPizza executable, select router.h.
    • If you build the Switch executable, select switchrouter.h.
  7. Click Open.
  8. Click the file button to the right of the source file text box. A file selection dialog box is opened.
  9. Select the routing source file in your working directory.
    • If you build the John, Marie, ParisPizza or LyonPizza executable, select router.c.
    • If you build the Switch executable, select switchrouter.c.
  10. Click Open.
  11. Enter the server port number of the executable you are building. Enter a port number according to Table 2.
Table 2 TCP Server Port Numbers for the Executables
Executable | TCP Port Number
Marie | 4949
John | 5959
ParisPizza | 7979
LyonPizza | 8989
Switch | 6969
  12. Click OK in the TCP/IP wizard dialog box.

The code generation configuration is now finished.

Compiling and Linking

The Targeting Expert Compiler/Linker/Make section contains six tabs: Compiler, Source Files, Additional Compiler, Linker, Library Manager and Make. The section is shown in Figure 221.

Figure 221 : The Targeting Expert Compiler/Linker/Make Section

Compiling and Linking the Switch Executable

To configure the compilation and linking of the Switch executable, do the following:

  1. Click Compiler/Linker/Make for Switch in the Partitioning diagram Model window.
  2. In the Include text box, add -I../../../../../ After the addition, the text box will look as shown in Figure 222.

    Figure 222 : The Include Text Box with an Additional -I flag

  3. Click the Save button.
  4. Click Target Library for Switch in the Partitioning diagram Model window.
  5. In the Kernel tab, click in the following check boxes:
    • Show errors on stdout. Setting this option renders log messages if errors are encountered during execution.
    • Text trace. Setting this option renders textual traces on stdout during execution.
  6. Click the Save button.
  7. Click the Full Make button. The SDL system is analyzed, code is generated and a makefile is generated and executed.

You will now have an executable file named switch. The file extension will be .exe on Windows and .sct on Solaris.

Compiling and Linking the MobileStations

To configure the compilation and linking of the MobileStation executables, do the following:

  1. Click Compiler/Linker/Make for MobileStation in the Partitioning Diagram Model window.
  2. In the Include text box, add -I<your working directory>, e.g. -I/home/mobile . After the addition, the text box will look as shown in Figure 222.
  3. Add the following flags in the Library Flag text box:
    • -DXMAIN_NAME=SDL_Main
    • -DXEXTENV_INC="<gui.h>"
    • -DMARIE, -DJOHN, -DPARISPIZZA or -DLYONPIZZA, depending on which executable you are configuring

The XMAIN_NAME flag is used to rename the main function in the generated SDL system. A main function is provided in the GUI source code. The SDL main function, renamed SDL_Main, will be started in a thread from the new main function.

XEXTENV_INC is a flag for using environment code together with the TCP/IP module. The gui.h file contains definitions of some macros in the generated environment file.

  4. Click the Source Files tab. A list of the external files to compile is shown.
  5. Click the Add button. A dialog box is shown.
  6. Select gui.c in the working directory. Click Open. The file is added to the file list.
  7. Windows only: The GUI must be compiled using a resource compiler.
    • Click the Additional Compiler tab.
    • Enter rc in the Compiler Name text box.
    • Enter -l 0x41d %I -fo %o %s in the Options text box.
    • Add the file gui.rc to the list of files to compile by clicking the Add button and select gui.rc from your working directory.
    • Enter .res in the Object Extension text box.
    • Click on the Make tab.
    • Change from Microsoft nmake (using temporary response file) to Microsoft nmake in the Make tool drop down list.
  8. Click the Linker tab.
  9. Enter the following in the Options text box:
    • Windows: Change -subsystem:console to -subsystem:windows
    • Solaris: Add -lXm -lXt -lX11 between -lpthread and -L/usr/lib.
  10. Click the Save button.
  11. Click the Full Make button. The SDL system is analyzed, code is generated and a makefile is generated and executed.

You will now have an executable file. The file extension will be .exe on Windows and .sct on Solaris.

The Target System

The generated executable files are located in a directory structure created by the Targeting Expert. The Targeting Expert uses the target directory given in the Organizer as root.

In the mobile system, target is given as target directory. The generated target directory structure is shown in Figure 223.

Figure 223 : The Generated Target Directory Structure

The executable files are located in the platform-specific directories (Win32_threaded and Solaris_threaded, respectively). The object files are located in subdirectories of the platform directories.


Running the System

What You Will Learn

  • To run the executable files generated from Targeting Expert
  • Use the mobile system

An Overview of the System

Figure 224 shows the run-time architecture of a MobileStation executable.

Figure 224 : Run-time architecture of a MobileStation Executable

The SDL system interacts with the outside world through its environment. The GUI message loop is run in a thread of execution of its own. The TCP/IP server thread executes the same way. The environment threads interact with the SDL system by inserting signals. This is done by calling the SDL kernel function SDL_Output.

When a signal is sent from the SDL system to the environment, it is interpreted either as GUI feedback or is sent to an external receiver via TCP/IP.

Using the System

Start the mobile system in the following order:

  1. Start the Marie, John, ParisPizza and LyonPizza executables. A GUI will pop up for each of them.
  2. Start the Switch executable. Switch will initialize the MobileStation executables by sending signals. You will see that the On buttons on the mobile phone windows become enabled.

To make a call, do the following:

  1. Click the On button on the MobileStations. You will be prompted to enter a PIN code. The correct PIN codes are shown in Table 3.
Table 3 MobileStation PIN Codes
Executable | PIN Code
Marie | 1
John | 2
ParisPizza | 3
LyonPizza | 4
  2. Click OK. "PIN OK" will be displayed. You are now ready to make a call.
  3. Click OK. The menu system of the GUI is activated. Select "Phone Book" by pressing the "<" and ">" buttons and click OK.
  4. Select a name from the list and click OK. If the receiving MobileStation is on, its display will show "Incoming Call".
  5. Click OK on the receiving MobileStation. A call is established.
  6. Click OK on the calling party and the receiving party when you wish to finish the conversation.

The system has more features not described in this manual. Experiment to discover its secrets!

The tutorial is finished. To get more detailed information about the Threaded integration and the TCP/IP module, please read Integration with Operating Systems.


Telelogic Tau 4.4

TTCN Suite Getting Started

Telelogic
http://www.telelogic.com


Introduction

About this Manual

This volume, TTCN Suite Getting Started, contains a guide that will assist you in getting familiar with the TTCN suite environment.

We start by giving an introduction to the TTCN suite and the supported languages. Then follows a number of chapters with hands-on tutorials on how to use the tools included in the TTCN suite, including different ways to build TTCN test suites from an SDL specification. These tutorials can be followed without any previous knowledge of the TTCN suite.

The basic tutorials have separate chapters for the UNIX and Windows version of the TTCN suite. The reason for this is the differences - in how to use the TTCN suite and the TTCN suite user interface - between the two versions.

All tutorials build on the knowledge gained in the previous tutorials, so you should practice them in the order they are included.

Documentation Overview

A general description of the Telelogic Tau documentation can be found in "Telelogic Tau Documentation".

Typographic Conventions

The typographic conventions that are used in the Telelogic Tau documentation are described in "Typographic Conventions".

How to Contact Customer Support

Detailed contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".


1 Introduction to Languages and Notations

This chapter describes the benefits of formal methods. It also gives a brief introduction to the TTCN, the ASN.1 and the MSC language.

Note that this chapter is not a tutorial on TTCN, ASN.1 or MSC. In TTCN Suite Methodology Guidelines you can find more information about TTCN and how to use it.

If you want to know more about the languages supported in the SDL suite, you should read Introduction to Languages and Notations.


Standardized Formal Methods

It is getting increasingly accepted within a steadily growing range of industrial segments that the only true way for software engineering to achieve higher quality, deliver on time and decrease development costs, is to use formal methods. Furthermore, as the international market grows, equipment from different manufacturers must be able to communicate with each other. Therefore it is obvious that the formal method to be used should be internationally standardized.

There are a number of different formal standardized languages and methods available today. The one you select, however, should fulfill a few more important requirements.

One is the availability of professional development tools. Another is clarity. The notation should be understood by a general audience, from experts to end users. Ideally it should have a graphical syntax.

Formal standardized graphical languages ...

  • ... enforce precision during specification, since ambiguities and unclear statements are impossible to make.
  • ... allow tool support. Tools can help to perform all kind of analyses like syntax/semantics check, simulation, test generation, code generation, etc.
  • ... attract more than one tool-builder. The second-source possibility creates vendor independence with all its advantages.
  • ... are more often the subject for courses, seminars, and text-books.
  • ... are more likely to be maintained. As with natural languages, formal languages need to evolve to stay modern.
  • ... promotes efficient verbal and written communication within development teams, between manufactures and between suppliers and customers, due to the conceptually formalized means of communication.
  • ... have a graphical syntax that makes it simple and efficient to exchange information between different players within an organization.

The Test Suite Framework Standard

As the use of standards within the world of Information Technology and Telecommunications has increased tremendously during the last decade, so has the need for methods and tools that support the verification and validation of both the standards and their implementations.

This need has been addressed by ISO and CCITT (ITU-T) in the "Framework and Methodology for Conformance Testing of Implementations of OSI and CCITT Protocols". The framework has now reached the status of an International Standard as ISO/IEC 9646 (or X.290).

  • The standard introduces the concept of Abstract Test Suites (consisting of Abstract Test Cases), a description of a set of tests that should be executed for a system. The tests should be described using a black-box model, i.e. only control and observe using the available external interfaces.
  • The abstract tests are to be described using a formal language rather than using informal natural language. As part of the standard, the language TTCN is defined in order to describe the abstract tests.
  • The possibility to copy the ASN.1 definitions from the protocol specification into the test suite in TTCN assures consistency between the information transferred in system specification and the test specification.

Conformance Testing

Conformance testing is the process of verifying that an implementation performs in accordance with a particular standard/specification/environment.

Conformance testing is exclusively concerned with the external behavior of an implementation. Service and functional behavior is tested in order to find logical errors and prerequisites for interoperability. Conformance testing is not intended to be exhaustive and a successfully passed test suite does not imply a 100% guarantee. But it does ensure, with a reasonable degree of confidence, that the implementation is consistent with its specifications, and it does increase the probability that implementations will interwork.

System Testing

  • Conformance testing verifies whether an implementation performs according to the stated standard/specification/environment.
  • Interoperability testing checks the ability of different implementations to interact in a prescribed manner, achieving predictable results.
  • Regression testing is performed after functional improvements or corrections, to confirm that nothing unintentional has been introduced.


The TTCN Language

TTCN (Tree and Tabular Combined Notation, ISO/IEC 9646-3) is a language standardized by ISO for the specification of tests for real-time and communicating systems. TTCN has been developed within the framework of standardized conformance testing (ISO/ IEC 9646).

With TTCN a test suite is specified. A test suite is a collection of various test cases together with all the declarations and components it needs. Each test case is described as an event tree. In this tree, behaviors such as "First, we send A, then either B or C is received; if it was B we will send D..." are described. Concurrent TTCN allows several event trees to run concurrently.

TTCN is abstract in the sense of being test system independent. This means that a test suite in TTCN for one application (e.g. protocol, system, etc.) can be used in any test environment for that application.

The use of TTCN has increased tremendously during the last few years. This has been augmented by the significant amount of test suites released by various standardization bodies. TTCN is not only used in standardization work. The language is very suitable for all kinds of functional testing for real-time and communicating systems. This has led to a wide usage throughout the industry.

The specifications of the messages being sent and received can be defined using either the native form of TTCN or by using ASN.1 (Abstract Syntax Notation One).

Theoretical Model

A TTCN specification describes an abstract test suite (ATS) that is independent of test system, hardware and software. The ATS defines the test of the implementation under test (IUT), which is treated in a black box model, i.e. only its exterior interface is of concern. The IUT is stimulated by sequences of test events and its response is inspected.

A TTCN abstract test suite can be transformed into an executable test suite (ETS) using the TTCN suite. This ETS is downloaded into the test system (the system performing the test).

The test system performs the test by executing the ETS against the system under test (SUT) which contains the implementation under test. During execution the ETS will report any errors and log events for on-line or post-test evaluation.

Figure 1 : Test System with Executable Test Suite (ETS)
connected to the system under test (SUT)

TTCN Specification Structure

A TTCN specification is similar to a Pascal or C program. (Being cleaner and more comprehensive, TTCN is easier to learn.) Just like Pascal and C, TTCN requires type and data declarations and it uses concepts like modules and subroutines. Since TTCN is designed for testing, it contains test specific concepts such as:

  • Powerful pattern matching constructs for complex data structures using both TTCN and ASN.1.
  • Verdicts and preliminary verdicts to define the outcome of test cases.
  • Possibilities to handle alternative outcomes in a test case.
  • Pre-ambles and post-ambles to show how to compose test cases.
  • The "modules" concept supporting multi-user test development.
  • The "modules" concept supporting the re-use of test components and data structures.
  • Constructs for parallel test component execution including synchronization primitives.

A TTCN specification has a standardized layout that produces comprehensive and unambiguous paper printouts. This greatly improves clarity and readability. A test suite is divided into the following four major parts:

  • The overview part, containing a table of contents and a description of the test suite. Its purpose is mainly to document the test suite to increase clarity and readability.
  • The declarations part, declaring all messages, variables, timers, data structures and black box interface towards the Implementation Under Test.
  • The constraints part, assigning values and creating constraints for inspection of responses from the implementation under test.
  • The dynamic part, containing all test cases, test steps and default tables with test events and verdicts, i.e. it describes the actual execution behavior of the test suite.

Figure 2 : The basic structure of a TTCN Test Suite

Test Suite Dynamic Structure

The dynamic part of a TTCN abstract test suite is created in a hierarchical and nested manner. The building blocks are test groups, test cases, test steps and test events. There are no limitations as to how many test groups may be contained in a test suite, how many test events may be contained in a test step, etc.

Test component explanation:

  • Test event: The smallest, indivisible unit of a test suite. Typically, it corresponds to a signal, interrupt, message, data or timer expiration.
  • Test step: A grouping of test events, similar to a subroutine or procedure in other programming languages.
  • Test case: The main fundamental building block in a test suite. A test case tests a particular feature or function in the implementation under test (IUT). A test case has an identified test purpose and it assigns a verdict that depends on the outcome of the test case.
  • Test group: A grouping of test cases. It might for example be convenient to group all test cases concerning connection establishment, and to put all test cases concerning transport into a separate test group.
  • Test suite dynamic part: The highest level, encompassing all test components and serving as the root of the tree. A test suite can range from a large number of test groups and test cases to a single test event contained in a test case.

Figure 3 : The TTCN dynamic part structure

Communication Mechanisms

TTCN uses the concepts of points of control and observation (PCOs), abstract service primitives (ASPs) and protocol data units (PDUs) in order to create an abstract interface towards the implementation under test (IUT). A PCO is a point in the abstract interface where the IUT can be stimulated and its responses can be inspected. An ASP or a PDU is either a stimuli or a response that carries information, i.e. parameters and data.

Each PCO has two first in first out queues for temporary storage of ASPs and PDUs: One queue for send and one queue for receive. These queues are infinite, i.e. they can store any number of ASPs and PDUs.

Figure 4 : PCOs together with ASPs and PDUs create an
abstract interface towards the IUT

Event Trees, Constraints and Verdicts

TTCN uses event trees with test events to express the behavior of test steps and test cases.

All the leaves in the event tree are assigned a verdict that can be PASS, FAIL or INCONCLUSIVE. PASS means that the test case completed without detecting any error. FAIL means that an error was detected, that is, the behavior of the IUT did not conform with the pre-defined specification. INCONCLUSIVE means that there was insufficient evidence for a conclusive verdict to be assigned, but that the behavior of the IUT was valid.

Figure 5 : An event tree and the corresponding execution order

A verdict can be either preliminary or final, allowing for flexibility in the specification. A final verdict will terminate the active test case and return its verdict. A preliminary verdict will not terminate test case execution but it will flag either PASS, FAIL or INCONCLUSIVE. This preliminary verdict can be inspected during test execution, like any variable.

TTCN uses the comprehensive format shown in Figure 6. The indentation level of statements in the Behaviour Description column indicates where in the event tree an event belongs. The leaves of the tree hold verdicts that define test case outcome.

Figure 6 : The TTCN test case corresponding to the event tree in Figure 5

Data and Value Model

The TTCN data and value model is somewhat different from the one in traditional programming languages. It allows for the creation of complex data structures and types, and has the concept of constraints to do value assignments. Constraints are more powerful than values in that they also allow the use of patterns. A pattern can contain wild cards and define allowable value ranges for complex data structures. This is very useful when inspecting responses from the implementation under test.

TTCN has two alternative data and constraint representation formats: the TTCN native tabular form and ASN.1 (Abstract Syntax Notation One). ASN.1, which is a purely textual notation, provides a more flexible platform for describing complex data structures. ASN.1 also allows data descriptions to be shared between an SDL (Z.105) specification and a TTCN test suite.

Modular TTCN

With modular TTCN, it is possible to define test suite components for re-use. This facilitates test component re-use, and provides a language platform for multi-user test development projects. See also "Distributed Development (UNIX).

Concurrent TTCN

Concurrent TTCN introduces a parallel architecture for simultaneous execution of several test components, allowing many interfaces to be tested concurrently. There are several benefits:

  • Test components become more cohesive/modular since they focus on the test of a specific interface of the IUT. Each interface is isolated in specific test components.
  • Module and integration testing is easier and it facilitates test component re-use.
  • Test suite maintenance becomes easier since test components are less monolithic. If one interface of the IUT changes, it will not influence any test components but the ones specifically dedicated to this interface.
  • Each test component becomes smaller and simpler since it deals with fewer alternatives.

In concurrent TTCN, each test case consists of several parallel test components (PTCs) that execute autonomously, performing concurrent tests. A master test component (MTC) starts the execution of the PTCs and controls the final verdict. The PTCs can only set preliminary verdicts and the test case is completed and its verdict is decided when all the PTCs are finished. The PTCs are synchronized through co-ordination points (CPs) and co-ordination messages (CMs).

Graphical and Textual Notations

The TTCN language supports two notations that are equivalent. The graphical notation (TTCN-GR) and a textual notation (TTCN-MP).

Application Areas

Currently, TTCN is mainly known within the telecommunications industry. However, it has broader areas of application, which can be summarized as follows:

  • Any protocol conformance testing.
  • Any communicating systems testing, e.g. interactive, message-driven, real-time or distributed.
  • Any system with a well defined interface that can be stimulated and observed.


The ASN.1 Language

Abstract Syntax Notation One is a language specifically designed for describing structured information that is conveyed across some inter-face or communication medium. ASN.1 is standardized internationally (ISO/IEC 8824) and it is a key ingredient of Open Systems Interconnection (OSI).

In the presentation layer of the OSI hierarchy, data values of quite complex types, such as character strings, intricate structures or arrays of values, need to be determined in a unique way without saying anything about the representation. ASN.1 is developed to fill this need.

ASN.1 is a generic notation for the specification of data types and values. The basic principle is to define a small number of simple types by defining their possible values, and give rules for combining these into increasingly complicated types. The original use of ASN.1 was in the information description of high-level protocols (FTAM, CMIP, MHS etc.), but today it is widely used in the telecommunications industry for protocols and applications.

Figure 7 : A sample ASN.1 type definition

ASN.1 Encoding and Transfer Syntax

ASN.1 requires a transfer syntax in order to pass data between two entities. Basic encoding rules (BER, ISO 8825) is a standardized transfer syntax of OSI. Others exist as well: canonical encoding rules (CER) for security applications, distinguished encoding rules (DER) for digital signatures, traditional C/C++, etc. Any transfer syntax can be used for ASN.1 descriptions.

ASN.1, SDL and TTCN - a Powerful Combination

TTCN includes ASN.1, i.e. ASN.1 is used for creating data descriptions and constraints in test suite specifications. Through the new standard of Z.105, ASN.1 is merged with SDL (Specification and Description Language) to create an extremely powerful language environment for specification of real-time, interactive and distributed systems.

Data descriptions made in ASN.1 can be used for both SDL and TTCN specifications, thus making a tight integration between implementation and test, and promoting re-use.

Figure 8 : ASN.1 specifications can be shared between
SDL and TTCN specifications


The Message Sequence Chart Language

History

During the last years, ITU has made a considerable effort in standardizing a formal language that defines message sequence charts (MSCs). A first version of the MSC recommendation was published in the summer of 1992.

As defined in the recommendation Z.120, the MSC language offers a powerful complement to SDL in describing the dynamic behavior of an SDL system. Its graphical representation is well suited for presenting a complex dynamic behavior in a clear and unambiguous way that is easy to understand.

Theoretical Model

An MSC describes one or more traces from one node to another node of an abstract communication tree generated from an SDL specification. Basically, the information interchange is carried out by sending messages from one instance to another. In an SDL specification, those messages would coincide with the signals that are sent from one process and consumed in another process. The instances would correspond to any part of the specification (an SDL system, a block or a process).

Graphical and Textual Notations

The MSC language supports two notations that are equivalent. Beside the graphical notation (MSC/GR), a textual notation (MSC/PR) is standardized.

Application Areas

Among several application areas, we have selected the following:

  • Producing documents with the purpose of defining the requirements on a system.
  • Facilitating the design phase, by identifying and documenting a multitude of dynamic cases before starting designing with SDL.
  • Presenting the execution of a simulation as a graphical output. This output is easy to follow and can later be verified against a reference. MSCs can be verified against an SDL system using the SDL suite.
  • Presenting the execution trace of an SDL system during an interactive simulation and generation of reports.
  • A convenient way to define test purposes, particularly in conjunction with the Autolink test generation features.


2 Introduction to the TTCN Suite (in Windows)

This chapter gives an introduction to the TTCN suite and its functionality. It also includes a list of file types supported by the TTCN suite.

When you have read this chapter and want to get more familiar with the TTCN suite, you should read and practice 4 Tutorial: TTCN Suite Basics (in Windows).

If you want to know more about what is new in this release of the TTCN suite, you should read Release Notes.

Note: Windows version

This is the Windows version of the chapter. The UNIX version is 3 Introduction to the TTCN Suite (on UNIX).


Introduction to the TTCN Suite

The TTCN suite is a family of tools for the development, specification and compilation of executable tests for the TTCN language. You can find more information about the TTCN suite tools in "The TTCN Suite Toolset" .

With the TTCN suite and TTCN, tests are specified in a way that is independent of implementation software and hardware, that is, the tests are only based on the system to be tested and not on the system performing the test. This has encouraged standards organizations to use the technology. Test suites for various standards, supplied by standardization authorities such as ETSI, can therefore be used by all manufacturers and users of that standard. The test suites are created in a graphical editor environment and checked for syntactic and semantic errors by means of a TTCN analyzer.

One of the TTCN suite tools is TTCN Access. It is a general tool for developing translators, code generators for different languages, automatic encoders and decoders, interpreters, reporters and analysis tools for TTCN test specifications.

The TTCN to C compiler produces code for both concurrent and non-concurrent TTCN as well as a limited subset of ASN.1 (see "TTCN ASN.1 BER Encoding/Decoding for further details on the restrictions that apply). To complete the production of an ETS, the generated code must be adapted to the specific target environment.

The generated C code forms an ETS together with the Generic Compiler Interpreter (GCI) Interface. The GCI Interface standardizes the communication between a TTCN component supplied by a vendor and other test system components supplied by the customer, thus forming a Means Of Testing (MOT). GCI is a minimal interface for the adaptation of the generated code to a specific target environment. It makes ETS adaptation easy.


The TTCN Suite Toolset

Telelogic Tau consists of the UML suite. the SDL suite, and the TTCN suite. The TTCN suite is an integrated set of tools used for creating, editing and maintaining TTCN documents. The TTCN suite will be described below. For more information about the SDL suite, see Introduction to the SDL Suite.

The Organizer - Co-Ordination of Telelogic Tau

You start the TTCN suite by adding and opening TTCN documents in the Organizer. The Organizer is the main window in Telelogic Tau. It integrates and co-ordinates the individual tools as required. Several tools may be used simultaneously through the Organizer. For instance, one part of a design may be analyzed at the same time as another is edited.

The Organizer features a graphical view of all the diagrams and documents you are working with, making them an integrated part of the development process. This may include TTCN documents, SDL hierarchies, Messages Sequence Charts, Object Model diagrams, State Charts, Highlevel MSCs and text documents. The view may be freely organized according to your preference.

Different Views of the Test Suite

You can view and edit the contents of a TTCN test suite in the Browser, the Table Editor and the Finder. The Browser gives information about the overall structure while the Table Editor is used for viewing and editing the contents of the TTCN tables. The Finder is used for displaying parts of the test suite, based on different search criteria. Some operations in the TTCN suite produce logs and they are displayed in the Log Manager.

The Browser

The Browser presents the view of the overall structure of a test suite. You can manipulate the test suite by adding and deleting items. It is also possible to control the amount of information displayed in the Browser by collapsing and expanding the test suite.

Several Browsers, displaying different test suites, can be opened at the same time. You may also find it useful to create a sub Browser, in which you can select to display only a part of the test suite.

The Table Editor

When you double-click a table that is included in a test suite, it will be opened in the Table Editor. In the Table Editor you can edit the standardized TTCN-GR tables, including the concurrent TTCN tables.

The Finder

By using the Finder, you can display the TTCN tables in a list, without any ordering restrictions. You can sort out the amount of tables included in the list by different criteria, for example name, type, modification time and analysis status. The tables can also be opened and analyzed from the Finder.

The Log Manager

The Log Manager presents information about different operations in the TTCN suite. For example, log information will be generated when you analyze, simulate or export a file.

Building a Test Suite

You can edit the declarations, constraints and dynamic tables manually in the Table Editor, but there are also other ways for editing which reduce the manual work and the risk of typing-errors:

Data Dictionary

An alternative to manually writing behaviour lines is to use the Data Dictionary. By using the Data Dictionary, you can select system components - for example PCOs, types, constraints and timers - that are already declared. You can then use these to build behavior statements.

SDL to TTCN Link

SDL to TTCN Link is similar in use and appearance to the Data Dictionary. The difference is that with SDL to TTCN Link, you generate TTCN declarations and interactively build behaviour tables based on an SDL specification.

Autolink

Autolink supports the automatic generation of declarations, constraints and dynamic behaviour tables in a TTCN test suite. The test generation is based on an SDL specification and a number of MSC diagrams. You may create these MSCs manually in the MSC Editor or automatically in the SDL Simulator or the SDL Validator. The output from Autolink is a test suite in MP file format which can be opened in the TTCN suite and refined subsequently.

In general, it is easier to describe test cases by MSCs than to specify them in TTCN directly. Moreover, Autolink provides a number of facilities to control the format and enhance the readability of a generated test suite.

Generation of the Test Suite Overview

The test suite overview tables includes the test suite structure, test case index and default index tables. These tables only need to be generated once, for example when the test suite is to be printed or exported. After that, the overview will be updated automatically as soon as you edit the test suite.

Analyzing, Verifying and Executing a Test

The Analyzer

The Analyzer performs a complete syntax check on TTCN and ASN.1 (as used in TTCN), as well as a number of static semantic checks, focusing on the existence and uniqueness of identifiers and the way they are being used.

It is possible to analyze the entire Browser structure or selected parts of it, as well as an entire modular TTCN system. If any tables are found to be erroneous after analysis, the names of those tables will be displayed in the Log Manager. An easy way to find and open an erroneous table, is to left-click the table name in the log and then <Ctrl>-right-click the table name again.

The TTCN to C Compiler

The TTCN to C compiler translates TTCN to ANSI-C. The TTCN to C compiler reduces the time for code generation as well as the volume of the generated code. Automatically generated code is also free from the potential errors of manual coding. The generated code is independent of the target operative system and protocol. In order to be executable, the generated C code must be linked to a library containing the pertinent OS functions.

The Generic Compiler Interpreter Interface

The Generic Compiler Interpreter interface (GCI) is an interface for the adaptation of the generated code to a specific target environment. The GCI interface focuses on what an abstract test suite needs in order to execute in terms of functionality, and on what is needed to integrate TTCN with a larger system.

The TTCN-SDL Co-Simulator

The TTCN-SDL Co-simulator allows execution of a TTCN test suite in a host environment. The system under test consists of a simulated SDL system. When the TTCN-SDL Co-simulator is connected with the SDL Simulator, the combined system is simulated. The test cases are executed one by one or in batch. After the execution, the test coverage information can be visualized by the SDL Coverage Viewer.

TTCN Access

TTCN Access makes the internal data structures representing the test suite, available for application programs. It can be seen as a platform for writing applications related to an abstract test suite, for example code generators, interpreters, report tools and analysis tools.

Access provides a default mechanism for accessing the information, but gives you total freedom to override this for one better fitted to your needs.

Input and Output Formats

The TTCN language supports two notations that are equivalent: TTCN-GR - the graphical notation - and TTCN-MP - the textual notation.

TTCN-GR

TTCN-GR is the format used when you edit a test suite in the TTCN suite. The TTCN suite also prints a TTCN document in the TTCN-GR format according to ISO/IEC 9646-3. You may select to print an entire test suite or just parts of it. A preview feature allows you to see what the printed material will look like before printing. The document may be printed as a hard copy or a PostScript file.

TTCN-MP

It is possible to export TTCN documents to TTCN-MP format. Selected items in the Browser - a single table or sets of tables - may also be exported to TTCN-MP format. The test suite that is to be exported, does not necessarily have to be correct, analyzed or complete.

It is also possible to open a document in TTCN-MP format. There is a high tolerance for errors in the MP file and you can use the Analyzer for finding the errors and then correct them in the TTCN suite rather than in the original MP file.


Files in the TTCN Suite

File Types

The TTCN suite supports a number of different file types with various suffixes:

Filename | Explanation
filename.itex | TTCN document main data base file
filename.itex#0 | TTCN document revert file
filenJAAa002l89,s | TTCN document working structure file
filenJAAa002l89,t | TTCN document working table file
filename.itex-lock | TTCN document lock file
filename.mp | TTCN-MP file
filename.log | TTCN suite log file
filename.c | ANSI-C file generated by the TTCN to C compiler
filename.h | Header file generated by the TTCN to C compiler

The working structure and table files are the internal TTCN suite files and will be created temporarily in the temporary directory.The TTCN suite checkpoints automatically to these files during editing but the main data base files are updated only on save.

The revert file is created in the session directory (which is the same as the target directory unless the ITEX_SESSION_DIR environment variable is set). It has a name consisting of the name of the main data base file (including extension), a hash sign (#) and a sequence number. The revert file is always stored in the TTCN-GR format even if it has a name like filename.mp#0.

Locking of TTCN Documents

When a TTCN document is saved, a lock file for it (which has the additional suffix -lock) is automatically created. This means that no other user can access it during the save operation. The lock files are created in the same directory as where the document is saved.

Transferring TTCN Suite TTCN Documents

The entire TTCN suite data bases may be transferred between storage areas. This is useful in order to preserve information that is lost in the TTCN-MP format. Use the usual file commands to achieve this.


3 Introduction to the TTCN Suite (on UNIX)

This chapter gives an introduction to the TTCN suite and its functionality. It also includes a list of file types supported by the TTCN suite.

When you have read this chapter and want to get more familiar with the TTCN suite, you should read and practice 5 Tutorial: TTCN Suite Basics (on UNIX).

If you want to know more about what is new in this release of the TTCN suite, you should read Release Notes.

Note: UNIX version

This is the UNIX version of the chapter. The Windows version is 2 Introduction to the TTCN Suite (in Windows).


The TTCN Suite Toolset

Telelogic Tau consists of the UML suite, the SDL suite and the TTCN suite. The TTCN suite is an integrated set of tools used for creating, editing and maintaining TTCN documents. The tools and functionality of the TTCN suite will be described below. For more information about the SDL suite, see Introduction to the SDL Suite.

The Organizer - Co-Ordination of Telelogic Tau

You start the TTCN suite by adding and opening TTCN documents in the Organizer. The Organizer is the main window in Telelogic Tau. It integrates and co-ordinates the individual tools as required. Several tools may be used simultaneously through the Organizer. For instance, one part of a design may be analyzed at the same time as another is edited.

The Organizer features a graphical view of all the diagrams and documents you are working with, making them an integrated part of the development process. This may include TTCN documents, SDL hierarchies, Messages Sequence Charts, Object Model diagrams, State Charts, Highlevel MSCs and text documents. The view may be freely organized according to your preference.

Different Views of the Test Suite

You can view and edit the contents of a TTCN test suite in the Browser and the Table Editor. The Browser gives information about the overall structure while the Table Editor is used for editing the contents of the TTCN tables.

The Browser

The Browser presents the view of the overall structure of a test suite. You can manipulate the test suite by adding and deleting items. It is also possible to control the amount of information displayed in the Browser by collapsing and expanding the test suite.

Several Browsers, displaying different test suites, can be opened at the same time. You may also find it useful to create a sub Browser, in which you can select to display only a part of the test suite.

The Table Editor

When you double-click a table that is included in a test suite, it will be opened in the Table Editor. In the Table Editor you can edit the standardized TTCN-GR tables, including the concurrent TTCN tables.

Building a Test Suite

You can edit the declarations, constraints and dynamic tables manually in the Table Editor, and the menu choice Replace allows searching for and replacing of test strings. There are also other ways for editing which reduces the manual work and the risk of typing-errors: you can use the Data Dictionary, the SDL to TTCN Link and the Autolink.

The test suite overview tables can be generated by the menu choice Generate SO.

Data Dictionary

An alternative to manually writing behaviour lines is to use the Data Dictionary. The Data Dictionary is included in the Table Editor, and by using it you can select system components - for example PCOs, types, constraints and timers - that are already declared, to build behaviour statements.

SDL to TTCN Link

SDL to TTCN Link is similar in use and appearance to the Data Dictionary. The difference is that with SDL to TTCN Link, you generate TTCN declarations and interactively build behaviour tables based on an SDL specification. This ensures consistency between the test suite and the specification.

Autolink

Autolink supports the automatic generation of declarations, constraints and dynamic behaviour tables in a TTCN test suite. The test generation is based on an SDL specification and a number of MSC diagrams. You may create these MSCs manually in the MSC Editor or automatically in the SDL Simulator or SDL Validator. The output from Autolink is a test suite in MP file format which can be imported into the TTCN suite and refined subsequently.

In general, it is easier to describe test cases by MSCs than to specify them in TTCN directly. Moreover, Autolink provides a number of facilities to control the format and enhance the readability of a generated test suite.

Generate Overview

To complete the test suite, you have to generate the test suite overview tables, that is, the test suite structure, test case index and default index tables. The page numbers of the tables referenced in the index tables will also be calculated. No selection is required when you generate the overview and you can do it both from the Browser and the Table Editor.

Other Test Suite Operations

The following operations can be performed on the entire test suite or selected parts of it:

Select

You can create a selection in the Browser by specifying various predicates. They could be name or content patterns, cross reference predicates, type information or analysis results. The selections may later be used for presenting status information on the items selected. It is also possible to create sub Browsers from selections.

Report

It is possible to produce a configurable textual report - status information as analysis status or modification date - on a test suite. The output may also be used for further processing in an awk script or Microsoft Excel.

Compare

You may compare two TTCN documents. This is often useful when you want to resolve conflicts before merging one of the documents into the other. When you want to compare two documents, you make selections in one test suite. These are then compared with the other test suite - the destination test suite. Any similarities found will be logged and reported.

Merge

You can merge an entire TTCN document or selected parts of it into another TTCN document. This only works if there is no conflict, that is, no object in the source test suite has the same name as an object in the destination test suite.

It is also possible to merge the contents of an MP file into a TTCN document.

Search

You may search for occurrences of a specified pattern, which can be either a literal string, wildcard or regular expression. If you want to, you can also replace the matches by another pattern. It is possible to search both from the Browser and the Table Editor and to select, for example, the scope and direction for the search.

Find Tables

You can search for and display named tables. No selection is required and you can to it both from the Browser and the Table Editor.

Analyzing, Verifying and Executing a Test

The Analyzer

The Analyzer performs a complete syntax check on TTCN and ASN.1 (as used in TTCN), as well as a number of static semantic checks, focusing on the existence and uniqueness of identifiers and the way they are being used.

When the Analyzer is started from a Browser, it will analyze selected items in the test suite. When the Analyzer is started from a Table Editor it will only analyze that table.

If any tables are found to be erroneous after analysis, the names of those tables will be displayed in the log. An easy way to find and open an erroneous table is to select the name of the table in the log and then select Find Table from the Tools menu in the Browser or the Table Editor.

The TTCN to C Compiler

The TTCN to C compiler translates TTCN to ANSI-C. The TTCN to C compiler reduces the time for code generation as well as the volume of the generated code. Automatically generated code is also free from the potential errors of manual coding. The generated code is independent of the target operative system and protocol. In order to be executable, the generated C code must be linked to a library containing the pertinent OS functions.

The Generic Compiler Interpreter Interface

The Generic Compiler Interpreter interface (GCI) is an interface for the adaptation of the generated code to a specific target environment. The GCI interface focuses on what an abstract test suite needs in order to execute in terms of functionality, and on what is needed to integrate TTCN with a larger system.

The TTCN-SDL Co-Simulator

The TTCN-SDL Co-simulator allows execution of a TTCN test suite in a host environment. The system under test consists of a simulated SDL system. When the TTCN-SDL Co-simulator is connected with the SDL Simulator, the combined system is simulated. The test cases are executed one by one or in batch. After the execution, the test coverage information can be visualized by the SDL Coverage Viewer.

TTCN Access

TTCN Access makes the internal data structures representing the test suite, available for application programs. It can be seen as a platform for writing applications related to an abstract test suite, for example code generators, interpreters, report tools and analysis tools.

Access provides a default mechanism for accessing the information, but gives you total freedom to override this for one better fitted to your needs.

Input and Output Formats

The TTCN language supports two notations that are equivalent: TTCN-GR - the graphical notation - and TTCN-MP - the textual notation.

TTCN-GR

TTCN-GR is the format used when you edit a test suite in the TTCN suite. The TTCN suite prints a TTCN document in the TTCN-GR format according to ISO/IEC 9646-3.

When you print, configurable headers and footers, double or single sided printing and partial prints are supported. The output format is PostScript, which also makes it possible to print the test suite to a file.

TTCN-MP

It is possible to export TTCN documents to TTCN-MP format. Selected items in the Browser - a single table or sets of tables - may also be exported to TTCN-MP format. The test suite that is to be exported, does not necessarily have to be correct, analyzed or complete.

It is also possible to import a document in TTCN-MP format. There is a high tolerance for errors in the MP file and you can use the Analyzer for finding the errors and then correct them in the TTCN suite rather than in the original MP file.

In addition, you can simply open MP files and work with them as with TTCN-GR files without having to convert them first. It is also possible to use Save As for changing the format.


Files in the TTCN Suite

File Types

The TTCN suite supports a number of different file types with various suffixes:

Filename | Explanation
filename.itex | TTCN document main data base file
filename.itex#0 | TTCN document revert file
filenJAAa002l89,s | TTCN document working structure file
filenJAAa002l89,t | TTCN document working table file
filename.itex-lock | TTCN document lock file
filename.mp | TTCN-MP file
filename.log | TTCN suite log file
filename.rpt | TTCN suite reporter file
filename.c | ANSI-C file generated by the TTCN to C compiler
filename.h | Header file generated by the TTCN to C compiler

The working structure and table files are the internal TTCN suite files and will be created temporarily in the temporary directory. The TTCN suite checkpoints automatically to these files during editing but the main data base files are updated only on save.

The revert file is created in the session directory (which is the same as the target directory unless the ITEX_SESSION_DIR environment variable is set). It has a name consisting of the name of the main data base file (including extension), a hash sigh (#) and a sequence number. The revert file is always stored in the TTCN-GR format even if it has a name like filename.mp#0.You can specify the compression of the revert files by using the resource revertFileCompressionMethod.

UNIX commands such as mv, cp, rm etc. can be used on these files (but use with caution!).

Locking of TTCN Documents

When a TTCN document is saved, a lock file for it (which has the additional suffix -lock) is automatically created. This means that no other user can access this file during the save operation. The lock files are created in the same directory as where the document is saved.

Transferring TTCN Suite TTCN Documents

The entire TTCN suite data bases may be transferred between storage areas. This is useful in order to preserve information that is lost in the TTCN-MP format. Use the usual UNIX commands to achieve this.


4 Tutorial: TTCN Suite Basics (in Windows)

This tutorial is intended as an easy introduction to the TTCN suite for the newcomer. It is assumed that you have some basic knowledge about Windows. In addition, to find the TTCN suite meaningful to use, you have to understand TTCN.

Note: Windows version

This is the Windows version of the tutorial. The UNIX version can be found in 5 Tutorial: TTCN Suite Basics (on UNIX).

Note:

This document is a TTCN Suite primer and is not intended to provide a tutorial on TTCN. The volume TTCN Suite Methodology Guidelines introduces some basic TTCN features presented with the aid of a simple example.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the basic functions of the TTCN Suite. You will start by creating a test suite and you will learn various ways of editing tables.

It is assumed that you know how to use Windows but that you have no or little previous knowledge about the TTCN Suite. However, to understand the full use of the TTCN suite, you must have knowledge of TTCN. TTCN Suite Methodology Guidelines introduces some essential TTCN features, presented with the aid of a simple example.


Starting the TTCN Suite

It is assumed that the TTCN Suite (or Telelogic Tau) has been installed correctly and that the installation directory is:
C:\Telelogic\SDL_TTCN_Suite4.4

To start Telelogic Tau:

  • Select the Telelogic Tau icon from the Start menu.
    • You can also double-click the executable file sdt.exe, which should be located in:
      C:\Telelogic\SDL_TTCN_Suite4.4\bin\wini386      .

After a few seconds, the Organizer is started. The Organizer is the main window from which you have access to the tools in the Telelogic Tau environment.

A welcome window, where you may read the license agreement for Telelogic Tau, will also be displayed. The window disappears as soon as you click the Continue button or perform any action in the Organizer.

Figure 9 : The Organizer main window

The Organizer consists of a main window and a log window. In the main window, five areas - known as chapters - are displayed by default:

  • Analysis Model
  • Used Files
  • SDL System Structure
  • TTCN Test Specifications
  • Other Documents

You may freely use these chapters to hold a number of documents and chapters may also be renamed, deleted and created - the actual use is a matter of personal taste.

More information about customizing the chapters can be found in "Customizing the Organizer Chapters.


Creating a TTCN Test Suite Document

What You Will learn

  • To set the source and target directory
  • To create a TTCN test suite

Setting the Source and Target Directory

You will begin by setting the source and target directory in the Organizer. The source directory is where your new documents will be saved by default. The target directory is where generated files are put. Both of these directories must already exist - you cannot create them in the Organizer.

  1. Double-click the source directory icon in the Organizer window.
    • You may also select the source directory icon and then select Edit from the Edit menu in the Organizer or you may select Set Directories from the File menu.

The Set Directories dialog is opened, and you may change the source and target directories.

Figure 10 : The Set Directories dialog

  2. Select the source directory by writing the path in the text field or by browsing in the dialog that is opened when you click the folder button. Make sure that you have write access to the directory.
  3. In the same way, you can change the target directory.
  4. Click OK in the Set Directories dialog.

Creating a New Test Suite

When you have set the source and target directories, you should create a new TTCN document.

  1. Select the chapter TTCN Test Specification in the Organizer.
  2. Select Add New from the Edit menu in the Organizer.
    The Add New dialog is opened. In the dialog you should set the document type and name.

Figure 11 : Add New dialog

  3. Select TTCN and Test Suite or Modular Test Suite in the New document type list.
  4. Type Tutorial in the New document name field.
  5. Make sure that the option Show in editor is selected.
  6. Click OK.
    A new TTCN document is created in the source directory. At the same time, a TTCN icon is created in the Organizer. After that, the TTCN suite is started. The TTCN Browser will show the new test suite in collapsed format.

Figure 12 : The TTCN suite is started and the Browser displays the test suite


Using the Browser

What You Will Learn

  • To expand and collapse nodes
  • To build a test suite

Expanding and Collapsing Nodes

The Browser displays the test suite in a collapsed format, which is indicated by plus signs in front of the nodes. You expand and collapse the nodes the same way that you expand and collapse directory levels in the Windows Explorer.

Figure 13 : The Dynamic Part has been expanded

Some nodes are not marked with plus or minus signs. Those node are tree nodes without children. The node Test Cases in Figure 13 is an example of this. Such nodes represent the static (structural) parts of the test suite that cannot be opened or edited.

Building a Test Suite

You are now going to add a TTCN table to your test suite.

To add a PCO type:

  1. Expand the Declarations Part.
    To be able to see the entire test suite, you may also have to enlarge the Browser window.
  2. Select the PCO Type Declarations node.
  3. Select Add in from the Edit menu.
    A PCO Type with the temporary name NoName is added in the PCO Type Declarations list. The table icon looks like a small graphical table, which means that it can be opened and edited.
  4. Rename the PCO type NoName by clicking on it when it is selected, that is, it becomes highlighted. Name the PCO type LOWER_PCO.

Figure 14 : The test suite when a PCO Type has been added

Note that the new table is marked with a question mark to indicate that it has not yet been analyzed.
  5. You should also add the following items:
    • A TTCN PCO called L
      (Declarations Part > PCO Declarations)
    • A TTCN PDU called SEND
      (Declarations Part > PDU Type Definitions > TTCN PDU Type Definitions)
    • A TTCN PDU called RECEIVE
      (Declarations Part > PDU Type Definitions > TTCN PDU Type Definitions)
      You can also copy and paste SEND and change the name to RECEIVE.
    • A TTCN PDU constraint on the SEND PDU called S1
      (Constraints Part > PDU Constraint Declarations > TTCN PDU Constraint Declarations)
    • A TTCN PDU constraint on the RECEIVE PDU called R1
      (Constraints Part > PDU Constraint Declarations > TTCN PDU Constraint Declarations)
      You can also copy and paste S1 and change the name to R1.
    • A test case called TEST_CASE_1
      (Dynamic Part > Test Cases)
    • A test step called TEST_STEP_1
      Dynamic Part > Test Step Library)

Figure 15 : The test suite when the tables have been added

The next step is to edit the tables that you just added.


Using the Table Editor

What You Will Learn

  • To open the Table Editor
  • To resize the window parts
  • To edit the contents of a table

Opening the Table Editor

The Table Editor is opened when you double-click a table icon in the Browser:

  • Double-click the test case table TEST_CASE_1.
    The test case table is opened in the Table Editor.

Figure 16 : The test case TEST_CASE_1 which has not yet been edited

Resizing the Table

As you can see, the Table Editor window is divided into three parts: the header, the body and the footer. These parts can be resized and hidden.

  • Drag the horizontal bars that separates the table parts to change the relative size.
  • Drag a row separator in the left most column to change the height of a row.
  • Drag a column separator in a header of the body part of the table to change the column width.

Editing the Test Case Table

As you can see, TEST_CASE_1, or any other table, consists of fields where text may be inserted and edited. This is what you are going to do now:

  1. Click in the Purpose field and type some text, for example:
    This is an example test case for the TTCN suite tutorial.
  2. Type some text in the Description field: Example test case.
    • Instead of clicking the mouse to set the input focus, you can press <down arrow> until the cursor has reached the Description field.
      It is also possible to type text in the other fields but you do not have to do that in this tutorial. Note that the Group field is not editable. The contents of this field is always kept updated from the Browser structure.
  3. Select Insert New Row After from the Edit menu.
    • You can also press <Ins> or <Insert>.
      A new empty line is added to the body of the table. Note that the line is automatically numbered.
  4. Type L! SENT in the Behaviour description field of the new line.

Note:

The misspelling of "SEND" is intentional!

  5. Type S1 in the Constraints Ref field.
  6. Press <Ins> or <Insert> to add another new line.
  7. Type +TEST_STEP_1 in the Behaviour Description field of row 2
    Note that the text is automatically indented.

Figure 17 : The test case TEST_CASE_1 when it has been edited.

The misspelling of "SEND" is intentional.

When you have edited TEST_CASE_1, you should close the table.

Completing the Test Suite

You should now edit the other tables that you have already added to the test suite. Use the tables in the following figures as models.

  1. Edit the tables in the Declarations Part of the test suite, that is the PCO type LOWER_PCO, the PCO called L and the PDUs called SEND and RECEIVE:

Figure 18 : The PCO type LOWER_PCO

Figure 19 : The PCO L

Figure 20 : The PDU SEND

Since the contents of SEND and RECEIVE are identical, you can copy the text and rows from SEND and paste them in RECEIVE:
  • Select text in the usual way with the mouse.
  • Select an entire row in the body of a table by clicking the left most field.
    When you are going to paste, note the following:
  • Text can only be pasted in text edit mode, that is, when a field contains a text pointer.
  • A body row can only be pasted when a body row is selected or when a body field is highlighted.

Note:

This means that there are two paste buffers: one for plain text and one for body rows.

Figure 21 : The PDU RECEIVE

  2. Edit the tables in the Constraints Part, that is the PDU constraints called S1 and R1:

Figure 22 : The PDU constraint S1

Figure 23 : The PDU constraint R1

  3. Edit the test step called TEST_STEP_1 in the Dynamic Part:

Figure 24 : The test step TEST_STEP_1

When you add row 2 it is automatically indented, however, in this case it should not be. To decrease the indention, put the cursor in row 2 and then either:
  • Press <Alt+-> (<Alt> and the minus key).
  • Click the minus indention quick-button.
  • Select Edit > Decrease Indention Level.
  4. Close all tables when you have finished editing.
  5. Save the test suite by selecting Save in the File menu.


Analyzing the Test Suite

What You Will Learn

  • To analyze a test suite
  • To find errors

Analyzing the Test Suite

You are now going to analyze the test suite:

  1. Select Analyze Suite from the Build menu.
    • You can also select the top node in the Browser and then select Analyze. Analyze only works on selected parts of a test suite (including sub-trees) so in this case it will have the same effect as Analyze Suite.)
      The Analyzer/TTCN to C Compiler Settings dialog is opened. You do not have to change the settings in this tutorial.

Figure 25 : The Analyzer/TTCN to C Compiler Settings dialog

Note that if you analyze the test suite again by using a quick-button or a shortcut, the same options will be used but the dialog will not be displayed.
  2. Click OK.
    If you have edited the test suite as described, the TTCN suite Log Manager is opened with a textual log that should show a single error message:

Figure 26 : The TTCN suite Log Manager window showing one error

The log text means that there is an error in line 1 of the behaviour description of the test case dynamic behaviour table called TEST_CASE_1.
Also note that the parent nodes to the erroneous table are marked with a red arrow and the table is marked with a red cross in the Browser.

Finding and Correcting the Error

To find the erroneous table, you use the popup menu:

  1. In the Log Manager, click the table identifier, that is, the name of the table: TEST_CASE_1.
  2. <Ctrl>-right-click the name of the table again.
    A popup menu is opened.
  3. Select the top command in the popup menu: Test Case Name: TEST_CASE_1.

Figure 27 : Finding a table by using the popup menu in the Log Manager

The Table Editor window is opened, displaying the TEST_CASE_1 table. Note that the error is marked in red, in this case L! SENT in the Behaviour Description column.

You should now correct the error and analyze again:

  1. Correct the error, i.e. change SENT to SEND.
  2. Analyze the test suite again. You can do this while having the Table Editor window still opened since the Analyzer works on any level of the test suite.
    You will now have a small test suite that is syntactically correct. This means that the red markings will disappear.


Creating TTCN Tables in Other Ways

The methods described below make it faster and more efficient to create TTCN tables. They also avoid annoying spelling errors and reduces the amount of text that needs to be typed.

What You Will Learn

  • To create a table by copying and pasting.
  • To create a table by using the Data Dictionary.
  • To delete a table.

Copying and Pasting

You are now going to practice another way of creating a TTCN table, namely by copying and pasting it.

  1. Copy the PDU called SEND in the Browser.
  2. Select S1 and then paste the table you have copied.
    The SEND table is pasted before S1.

Editing the New Table

  1. Open the new SEND table.
    The Table Editor window is opened displaying the table. As you can see, the PDU Type field and the Field names are filled in. Now you just have to change the name and insert values in Field_1 and Field_2.
  2. Type a new name in the Constraint Name field: S2.
  3. Give Field_1 the value 3 and Field_2 the value TRUE in the Field Value column.
  4. Analyze the entire test suite as described in "Analyzing the Test Suite" .

Using the Data Dictionary

You can use the Data Dictionary to interactively build behaviour lines in behaviour tables. In the Data Dictionary dialog, you can compose sends, receives, timeouts and attachments, and at the same time see how it turns out in the dialog.

In this simple example, you will use the Data Dictionary to create a new test case with the same contents as TEST_CASE_1, and as a comparison you may have that table opened too:

  1. Create a new test case and open it.
  2. Name the test case TEST_CASE_2.
  3. Open the Data Dictionary from the View menu.

Figure 28 : The Data Dictionary dialog

  4. In the Send/Receive tab in the dialog, make the following settings:
    • Select the PCO L.
    • Select the ! (exclamation mark) radio button, which means that you will add a send statement.
    • Select the type SEND.
    • Select the constraint S1.
    • No verdict should be selected.
      The Behaviour Line, the Constraint and the Verdict fields show the contents of the behaviour line that is inserted in the table.
  5. Click Apply.
    The behaviour line you have composed is inserted in the table.
  6. In the Attachment tab, select TEST_STEP_1.
    The Behavior Line will read +TEST_STEP_1.
  7. Click the Apply button.
    The behaviour line is inserted and TEST_CASE_2 should now be identical to TEST_CASE_1.
  8. Close the Data Dictionary dialog.

Deleting the Tables

You will not need the newly created tables in the rest of this tutorial. You should therefore delete them:

  1. Select S2 and TEST_CASE_2 in the Browser.
  2. Select Delete from the Edit menu or press the <Delete> key.
    The tables are deleted.


Exporting a Test Suite

What You Will Learn

  • To save the test suite as TTCN-MP
  • To generate the test suite overview
  • To save the test suite as HTML

Saving a Test Suite to MP Format and Generating the Overview

You should now convert the test suite to TTCN-MP format. However, before the actual conversion, the test suite overview has to be generated. How to do this will also be described below.

  1. Select the top node of the test suite in the Browser.
  2. Select Save As from the File menu.
    Since the test suite overview has not been generated before, it has to be done now. A dialog is opened where you can confirm this operation.
  3. Click Yes in the confirmation dialog.
    Since the test suite you have created is small, the generation will not take long. Also, once it has been generated, it will be updated automatically.
    A file dialog is opened.
  4. Specify where the file is to be saved, ensure that you save as type TTCN-MP and give the file a name (example).
    The test suite will now be renamed to example.mp.

Hint:

Optionally, you can use the Export to MP button for exporting the .itex file to MP, while keeping the .itex file open.

A TTCN-MP file can be opened like an ordinary .itex file.

Saving a Test Suite as HTML

To save the entire test suite, or selected parts of it, as HTML, you proceed as described in "Saving a Test Suite to MP Format and Generating the Overview" . But instead of TTCN-MP, select HTML as the file type.

It is also possible to only export an opened table. To do this:

  1. Open a table.
  2. Select Generate HTML from the pop-up menu in the table.
  3. Select a name of the file and where it should be saved.

An HTML document cannot be opened in the TTCN suite again, but you can view it in an HTML browser.


Printing the Test Suite

You should by now have a test suite that is syntactically correct.

If you have saved the test suite as MP, as described earlier, the test suite overview should also have been generated and it does not have to be done again. The overview will be automatically updated as soon as you make any changes in the test suite after the generation.

If you did not save the test suite as MP, you will have to confirm the updating of the overview before printing is possible.

You can print a test suite both from the TTCN suite and the Organizer. The main differences are that in the TTCN suite there is a print preview, and in the Organizer, you can print several test suites at the same time.

Printing from the TTCN Suite

To print from the TTCN suite:

  1. Ensure that the Browser window is active.
  2. Select Print from the File menu.
    The Print dialog is opened.
  3. If necessary, change some settings.
  4. Click OK.
    The test suite is printed.

Printing from the Organizer

To print from the Organizer:

  1. Select the TTCN document icon in the Organizer.
  2. Select Print from the File menu.
    The Print TTCN dialog is opened.
  3. If necessary, change some settings.
  4. Click Print.
    The test suite is printed.


So Far...

You should now have learned how to create a test suite and how to edit it in the Browser. You have also learned how to create and edit tables and how to work with the Table Editor. Other things you should have learned is how to analyze the test suite, how to find errors and how to save as MP and HTML.

By practicing this tutorial you have probably not achieved any knowledge about TTCN. If you want to know more about the basics of TTCN you may read the TTCN Suite Methodology Guidelines. That volume is, however, not a tutorial on TTCN.

The following tutorial is 6 Tutorial: TTCN-SDL Co-Simulator (Windows). Before you start practising that, you should know how to use the SDL Simulator. A tutorial on that can be found in Tutorial: The SDL Simulator.


5 Tutorial: TTCN Suite Basics (on UNIX)

This tutorial is intended as an easy introduction to the TTCN suite for the newcomer. It is also assumed that you have some basic knowledge about UNIX. In addition, to find the TTCN suite meaningful to use, you have to understand TTCN.

Note: UNIX version

This is the UNIX version of the tutorial. The Windows version can be found in 4 Tutorial: TTCN Suite Basics (in Windows).

Note:

This document is a TTCN suite primer and is not intended to provide a tutorial on TTCN. The volume TTCN Suite Methodology Guidelines introduces some basic TTCN features presented with the aid of a simple example.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the basic functions of the TTCN suite. The sections in this chapter are to be read sequentially. You will start by setting up the TTCN suite environment. Then you will create a TTCN test suite, edit the tables in the test suite and apply some basic the TTCN suite tools.

It is assumed that you know how to use UNIX but that you have no or little previous knowledge about the TTCN suite. However, to understand the full use of the TTCN suite, you should have knowledge of TTCN. The volume TTCN Suite Methodology Guidelines introduces some essential TTCN features, presented with the aid of a simple example.


Setting Up the TTCN Suite Environment

It is assumed that the TTCN suite (or Telelogic Tau) has been installed correctly, according to the instructions in the Installation Guide. The Telelogic Tau installation directory is pointed out by the environment variable $telelogic. This variable has to be set correctly in your UNIX environment.

  1. The TTCN suite commands are made available if you add the Telelogic Tau bin directory to the environment variable PATH:
setenv PATH ${PATH}:$telelogic/bin

  2. Also set the environment variable MANPATH to include the TTCN suite and the X11 man directories, to make the manual pages available:
setenv MANPATH \ ${MANPATH}:$telelogic/itex/man:$telelogic/X11/man

If you type man itex, the UNIX manual entry for the TTCN suite will be displayed. It describes the switches that may be used to set the default settings of the dialog options.

To be able to use the on-line help, you need an HTML viewer, either Netscape or Internet Explorer. To select the HTML viewer to use, see "Customizing the On-Line Help.


Starting the TTCN Suite

Once the TTCN suite software has been installed, you can start it from a UNIX shell tool (e.g. an X-term) by the command itex:

  • Type itex to start the TTCN suite.

After a few seconds, the Organizer window is displayed. The Organizer is the main window from which you have access to the tools in the Telelogic Tau environment.

Figure 29 : The Organizer main window

A welcome window, where you may read the licensing agreement for Telelogic Tau, will also be displayed. The window disappears as soon as you click the Continue button or perform any action in the Organizer.

The Organizer consists of a main window and a log window. In the main window, five areas - known as chapters - are displayed by default:

  • Analysis Model
  • Used Files
  • SDL System Structure
  • TTCN Test Specifications
  • Other Documents

You may freely use these chapters to hold a number of documents and chapters may also be renamed, deleted and created - the actual use is a matter of personal taste.

More information about customizing the chapters can be found in "Customizing the Organizer Chapters.


Creating a TTCN Test Suite Document

What You Will Learn

  • To set the source and target directory
  • To create a new test suite

Setting the Source and Target Directory

You will begin by setting the source and target directory in the Organizer. The source directory is where your new documents will be saved by default. The target directory is where generated files are put. Both of these directories must already exist - they cannot be created in the Organizer.

  1. Double-click the source directory icon in the Organizer window.
    • You may also select the source directory icon and then select Edit from the Edit menu in the Organizer or select Set Directories from the File menu.

The Set Directories dialog is opened, and you may change the source and target directories.

Figure 30 : The Set Directories dialog

  2. Select the source directory by writing the path in the text field or by browsing in the dialog that is opened when you click the folder button. Make sure that you have write access to the directory.
  3. In the same way, you can change the target directory.
  4. Click OK in the Set Directories dialog.

Creating a New Test Suite

When you have set the source and target directories, you should create a new TTCN document of type test suite or modular test suite:

  1. Select the chapter TTCN Test Specification in the Organizer.
  2. Select Add New from the Edit menu in the Organizer.
    The Add New dialog is opened. In the dialog you should set the document type and name.

Figure 31 : Add New dialog

  3. Select TTCN and Test Suite or Modular Test Suite in the New document type list.
  4. Type Example_A in the New document name field.
  5. Make sure that the option Show in editor is selected.
  6. Click the OK button.
    A new TTCN document of type test suite or modular test suite is created. At the same time, a TTCN icon is created in the Organizer. After that, the TTCN Browser window is opened. The Browser will show the new test suite in a collapsed format.

Figure 32 : The Browser window with a collapsed test suite


Using the Browser

What You Will Learn

  • To expand and collapse the test suite
  • To add TTCN tables to the test suite

Expanding and Collapsing the Test Suite

The Browser displays the test suite in a collapsed format, which is indicated by the three dots after the items in the test suite.

To expand the entire test suite:

  1. Select the top node in the Browser, that is Example_A.
  2. Select Expand Tree from the View menu.
    • It is also possible to open the pop-up menu on Example_A and select Expand Tree from it.
      All the collapsed items in the Browser are expanded.

Shortcut:

· <Shift+e> (Expand Tree)

Figure 33 : The Browser window with the expanded
modular test suite and no selected items

You may also want to deselect the test suite:
  3. Deselect the test suite by selecting Deselect All from the pop-up menu.

Shortcut:

· <Ctrl+\> (Deselect All)

To collapse the test suite:

  • Open the pop-up menu on Example_A and select Collapse from it.

Shortcut:

· c (Collapse)

· e (Expand - does not have the same effect as Expand Tree)

· <Shift+e> (Expand Tree)

Note that Expand and Collapse only work on a single selection. If more than one item or if no item is selected, the Collapse, Expand and Expand Tree commands are dimmed. In the following, it is assumed that the test suite is completely expanded in the Browser.

You should also note that items in bold font represent the static (structural) parts of the test suite that cannot be opened or edited. The items in normal, plain font represent TTCN tables, which of course can be opened and edited.

Building a Test Suite

You are now going to add a simple TTCN table to your test suite.

To add a PCO Type to Example_A in the Browser:

  1. Select PCO Type Declarations in the Declarations Part.
  2. Select Add from the Browser Edit menu.
    Note that Add only works when a single item is selected.

Shortcut:

· <Ctrl+Shift+Ins> (Add)

A PCO type with the temporary name NoName is added in the PCO Type Declarations list.
  3. Rename the PCO type NoName by opening the pop-up menu on NoName and selecting Rename from it.

Shortcut:

· First click on NoName, then press r (Rename).

It is now possible to type the new name. In this example we will call the PCO type LOWER_PCO.
  4. In a similar manner as described above, you should also add the following items:
    • A TTCN PCO called L
      (Declarations Part > PCO Declarations)
    • A TTCN PDU called SEND
      (Declarations Part > PDU Type Definitions > TTCN PDU Type Definitions)
    • A TTCN PDU called RECEIVE
      (Declarations Part > PDU Type Definitions > TTCN PDU Type Definitions)
    • A TTCN PDU constraint on the SEND PDU called S1
      (Constraints Part > PDU Constraint Declarations > TTCN PDU Constraint Declarations)
    • A TTCN PDU constraint on the RECEIVE PDU called R1
      (Constraints Part > PDU Constraint Declarations > TTCN PDU Constraint Declarations)
    • A test case called TEST_CASE_1
      (Dynamic Part > Test Cases)
    • A test step called TEST_STEP_1
      Dynamic Part > Test Step Library)

Figure 34 : The Browser window showing some of the newly added items

The next step is to edit the tables that you just added.


Using the Table Editor

What You Will Learn

  • To open the Table Editor
  • To edit the contents of a table

Opening the Table Editor

The Table Editor window is opened when you double-click on a table in the Browser window.

  • Double-click the test case TEST_CASE_1.
    The test case table is opened in the Table Editor window.

Figure 35 : The test case TEST_CASE_1 which has not yet been edited

Editing the Test Case Table

As you can see, the TEST_CASE_1 table, or any other table, consists of fields where text may be inserted and edited. You are now going to edit the contents of TEST_CASE_1:

  1. Click in the Purpose field and type some text, for example:
    This is an example test case for the TTCN tutorial    .
  2. Type some text in the Description field, e.g. Example test case.
    • Instead of clicking the mouse to set the input focus in the Description field, you may also press <Ctrl+Down arrow> until the cursor has reached the Description field.
      It is also possible to type text in the other fields but you do not have to do that in this tutorial. Note that the Group field is not editable. The contents of this field is always kept updated by the TTCN suite from the Browser structure.
  3. Press <Ins> or <Insert>.
    A new, automatically numbered, empty line is added to the body of the table.
  4. Type L! SENT in the Behaviour description field of the new line.

Note:

The misspelling of SEND is intentional!

  5. Type S1 in the Constraints Ref field.
  6. Press <Ins> or <Insert> to add another new line.
  7. Type +TEST_STEP_1 in the Behaviour Description field of row 2.
    Note that the text is automatically indented.

Figure 36 : The test case TEST_CASE_1 when it has been edited.
The misspelling of "SEND" is intentional.

Copying and Pasting Text and Table Rows

Before you close the editor you may want to try to copy and paste text and rows in the table:

  • If you only want to copy text, you simply select and copy it, either by a menu choice or shortcut. To paste the text, you can either use a menu choice or shortcut.
  • If you want to copy an entire row in the body of a table, you select it by pressing <Ctrl> while at the same clicking in the row. (A row in a dynamic behaviour table is selected if you click in the Nr column). When the row has been selected you can press <Ctrl+c> to copy it. You paste it with <Ctrl+Meta+v> (to paste after selected row) or <Ctrl+Shift+v> (to paste last in the body of the table).

Shortcut:

· <Ctrl+x> (Cut a row)

· <Ctrl+c> (Copy a row)

· <Ctrl+v> (Paste a row)

· <Ctrl+Meta+v> (Paste After)

· <Ctrl+Shift+v> (Paste Last)

· <Ctrl+Right arrow> (moves the input focus right)

· <Ctrl+Left arrow> (moves the input focus left)

· <Ctrl+Down arrow> (moves the input focus down)

· <Ctrl+Up arrow> (moves the input focus up)

Note:

There are two paste buffers: one for plain text and one for table rows.

When you have finished copying and pasting, make sure that the contents of the table are exactly as in Figure 36.

Closing the Table Editor

  • When you have edited TEST_CASE_1, close the table from the File menu.

Completing the Test Suite

Now you should edit the other tables that you have already added to the test suite. Do this in a similar manner as described above, by using the tables in the following figures as models.

  1. Edit the tables in the Declarations Part of the test suite, that is the PCO type LOWER_PCO, the PCO called L and the PDUs called SEND and RECEIVE:

Figure 37 : The PCO type LOWER_PCO

Figure 38 : The PCO L

Figure 39 : The PDU SEND

Figure 40 : The PDU RECEIVE

  2. Edit the tables in the Constraints Part of the test suite, that is the PDU constraints called S1 and R1:

Figure 41 : The PDU constraint S1

Figure 42 : The PDU constraint R1

  3. Edit the test step called TEST_STEP_1 in the Dynamic Part of the test suite:

    Figure 43 : The test step TEST_STEP_1

    §When you add row 2 it is automatically indented, however, in this case it should not be. To decrease the indention:
    • Select the entire line by clicking in the Nr column. Then select Decrease Indent from the Edit menu.
      (The shortcuts are <-> and <+> on the right-hand keypad.)
  4. Close all Table Editors when you have finished editing.
  5. Save the test suite by selecting Save in the File menu. A Save As dialog is displayed.
  6. Click OK.


Analyzing the Test Suite

What You Will Learn

  • To analyze a test suite
  • To find errors

Analyzing the Test Suite

You are now going to analyze the test suite:

  1. Select Analyze from the Browser Tools menu.
    The Analyzer dialog is opened. You do not have to change the settings in this tutorial.

Figure 44 : The Analyzer dialog

  2. Click Analyze.
    The log window is opened. If you have edited the test suite as described above, the log should show a single error message:

Figure 45 : The TTCN suite log window showing one error

The log text means that there is an error in line 1 of the Behaviour Description of the test case dynamic behaviour table called TEST_CASE_1.

Finding and Correcting the Error

To find the erroneous table:

  1. Select the test case name in the log.

Figure 46 : Selecting text in the TTCN suite log

  2. Select Find Table from the Browser Tools menu.
    The table will be found and displayed. In the first behaviour line you can see that you have written SENT instead of SEND.
    Note that the error line is marked in red. In the Browser, the erroneous table is also marked with a red bar.
  3. Correct the error, i.e. change SENT to SEND.
  4. Analyze the table by selecting Analyze from the Table Editor Tools menu.
    You will now have a small test suite that is syntactically correct. This means that the red markings will disappear.
    You may now close the table editor and log windows.


Saving a TTCN Test Suite Document

What You Will Learn

  • To save a TTCN document
  • To change its file name and/or its format

Save As Document

When you want to save a newly created document into a file, you must make a number of choices in the Save As operation:

  1. Select Save As from the File menu in the Browser.
  2. Select Binary (TTCN-GR) or Text (TTCN-MP).

Figure 47

.

  3. If you chose Binary, you need to select None, Gzip or Compress.1
  4. Select a file name.
  5. Press Save As.
    At the same time, the TTCN icon in the Organizer is associated with the specified file name.

Save Document

To save a document you can use either the Save Document item in the File menu of the Browser, or use the left most button in the toolbar of the Browser. The Save Document operation saves the document on disk with the same file name and format as before. If you try to save a document which has no file name assigned yet, the Save As operation will be initiated instead.

1

For maximum compatibility, the None selection should be used. The Gzip selection is preferred over Compress, both for portability and performance.


Creating TTCN Tables in Other Ways

The methods described below make it faster and more efficient to create TTCN tables. They also avoid annoying spelling errors and reduces the amount of text that needs to be typed.

What You Will Learn

  • To create a table by copying and pasting
  • To create a table by using the Data Dictionary menu
  • To delete a table

Copying and Pasting

You shall now practice another way of creating a TTCN table, namely by copying and pasting it.

  1. Find the PDU called SEND in the Browser.
  2. Copy the SEND PDU by using the popup menu.
  3. Find the PDU Constraint called S1.
  4. Open the pop-up menu on S1 and select Paste Before from it.
    The SEND copy is pasted before S1.

Editing the New Table

  1. Open the new SEND table.
    The Table Editor window is opened displaying the table. As you can see, the PDU Type field and the Field names are filled in. Now you just have to change the name and insert values in Field_1 and Field_2.
  2. Type a new name in the Constraint Name field, e.g. S2.
  3. Give Field_A the value 3 and Field_B the value TRUE in the Field Value column.
  4. Analyze the entire test suite as described in "Analyzing the Test Suite" .

Using the Data Dictionary

This section contains an example of an efficient way of creating test cases. Start by creating a new test case:

  1. Create a new test case.
  2. Name the test case, for example TEST_CASE_2.
  3. Open the test case.
  4. Select Add Send Statement from the Table Editor Data Dictionary menu. The Add Send dialog is opened.

Figure 48 : Add Send dialog

  5. Click on S2 in the Constraints list.
  6. Click OK.
    A send statement has now been automatically generated.
  7. Select the generated line in the Table Editor by clicking in the Nr column.
  8. Select Add Attach Statement from the Table Editor Data Dictionary menu. The Add Attach dialog is opened.

Figure 49 : Add Attach dialog

There is only one test step available (i.e. TEST_STEP_1) so this will be automatically selected.
  9. Click OK.
    A new line has been added to the table.

Deleting the Tables

For the remainder of the tutorial you will not need the two tables that you have just created. You should therefore delete them.

  1. Select Deselect All from the pop-up menu in the Browser.
  2. Select TEST_CASE_2.
  3. Select the PDU Constraint S2, while at the same time pressing <Ctrl>.
  4. Select Delete from the Edit menu. The items are deleted.


Selecting Browser Items

The Selector is a tool that you may use when you want to make selections of Browser items. Before you apply the Selector, the Browser must already contain a selection.Then you can specify, with the Selector, if you want to increase, decrease or replace the existing selection.

Based on the selections in the Browser, you can make sub Browsers. A sub Browser works as the normal TTCN Browser, but it does not contain the entire test suite - only selected parts.

What You Will Learn

  • To use the Selector tool
  • To create a sub Browser

Selection 1

Suppose that you wish to select all the tables in the test suite that reference the PDU called SEND:

  1. Deselect the entire test suite.
  2. Select the single PDU called SEND.
  3. Select Selector from the Browser Tools menu.
    The Selector dialog is opened:

Figure 50 : The Selector dialog

  4. Select the Extend option in Select Mode.
  5. Choose the Referenced by option in the Relations box.
    You do not have to change any other options.
  6. Click the Select button.
    Now take a look at the Browser. You should see that not only is the SEND PDU selected but also the constraint S1 and the test case TEST_CASE_1. Only these objects reference the SEND PDU. (You may have to scroll the Browser to see them all.)

Selection 2

As another example, suppose that you wish to find all behaviour tables that have the character 1 included in their identifier and have a PASS verdict in the table:

  1. Select the entire test suite.
  2. Select Selector from the Browser Tools menu.
    The Selector dialog is opened.
  3. Type 1 in the Name restriction field.
    This means that the names of the tables that you want to select should include the character 1.
  4. Select Test Case Dynamic Behaviour, Test Step Dynamic Behaviour and Default Dynamic Behaviour in the Type Restriction box.
  5. Type PASS in the Content restriction field.
    This means that there must be at least one occurrence of the word PASS in the selected tables.
  6. Select Restrict in the Select mode box.
    In other words, the intention is to select all behaviour tables that have a 1 in their names and that have a PASS substring in the contents of the table.
    The Analyze status and Relations options should not be set.
  7. Click the Select button.
    Only TEST_STEP_1 is selected in the Browser window.

Selection 3

Compare the result of the selection above with the following:

  1. Select the entire test suite.
  2. Apply the Selector with almost the same options as described above.
    • The difference is that you should remove PASS from the Content restriction field, i.e. the field should be empty.
  3. Click the Selector button.
    This time, both TEST_CASE_1 and TEST_STEP_1 are selected, because a PASS substring does not appear in the test case.

Creating a Sub Browser

It might be suitable at this point to create a sub Browser of the selection that you have just created (i.e. just the items TEST_CASE_1 and TEST_STEP_1):

  • Select Browser from the Browser Tools menu.
    A sub Browser containing the selected objects is created, together with the necessary minimal static structure to glue them together.

    Figure 51 : A sub Browser containing TEST_CASE_1 and TEST_STEP_1.

    You will not need this sub Browser in this tutorial so you may close it if you wish.


Generating Overview Tables

To complete the test suite, you also have to generate the Test Suite Overview tables - that is the Test Suite Structure, the Test Case Index, the Test Step Index and the Default Index tables - and the TTCN Module Overview - that is the TTCN Module Structure and the Index tables.

None of these tables are editable. Instead, you have to make the changes in the corresponding tables. The reason for this is that the overview tables should be consistent with the TTCN document.

To generate the overview:

  1. Select Generate Overview from the Browser Tools menu.
    The Generate Document Overview dialog is opened.
    The TTCN suite also generates the page numbers. You can set the start page number in this dialog, but you do not have to do that in this tutorial.
  2. Click the Generate button in the dialog.
  3. Open the Test Case Index table.
    You will see that the Description field has been generated from the additional Description field in the header of the test case. To make changes, you have to edit the tables from which the overview was generated and then generate the overview again.
  4. Close the Test Case Index table.


Printing the Test Suite

You should by now have a test suite that is syntactically correct and which includes an up to date overview. If you want to, you can print it.

Printing the Entire Test Suite

To print the whole test suite:

  1. Select the entire test suite.
  2. Select Print from the Browser's File menu.
    The Print Document dialog is opened.
  3. Make sure that Output Device names a printer that is recognized by your system.
    You do not have to change any other settings in this tutorial.
  4. Click the Print button if you want to print the entire test suite.

Printing Parts of the Test Suite

It is also possible to print parts of the test suite.

To print, say, just the Constraint tables:

  1. Select only S1 and R1.
  2. Select Print from the Browser File menu.
    The Print Document dialog is opened.
  3. Make sure that Output Device names a printer that is recognized by your system.
    You do not have to change any other settings in this tutorial.
  4. Click the Print button if you want to print the Constraint tables.


Creating Reports

The Reporter tool is used for presenting status information on selected items in the Browser. The information may for example be analysis status and modification date.

To make a list of the full amount of information:

  1. Select the entire test suite.
  2. Select Reporter from the Browser Tools menu.
    The Reporter dialog is opened.

Figure 52 : The Reporter dialog

  3. Set the options as shown in Figure 52, that is select all options in the list of actions, normal verbosity and the formatting nl + tab. The latter means that each list entry will be printed on a new line and the components in the list entry will be separated by tabs.
  4. Click the Reporter button.
    The options set in the dialog will produce the full amount of information available, a portion of which is illustrated below:

Figure 53 : Test suite information

Note that, as with all the TTCN suite log files, this file can be saved. This may be useful if you wish to print the file or process it with non-TTCN suite tools.
If you want to, you can apply the Reporter again and experiment with other settings.

You may also find it practical to apply the Find Table tool to text that is marked in the log window:

  1. Mark the name of a table in the log window
  2. Select Find Table from the Browser Tools menu.
    The table is found and opened.


Exporting and Importing

In the following examples, you will use the menu choices Convert to MP in the Browser and Convert to GR in the Organizer for exporting and importing TTCN-MP documents from and to the TTCN suite. However, you can also use Save As in the TTCN suite for changing the document format. In addition, TTCN-MP documents may be opened directly in the TTCN suite.

What You Will Learn

  • To export a test suite to TTCN-MP format
  • To import a test suite from TTCN-MP format

Exporting a Test Suite to MP Format

You shall now convert the test suite to TTCN-MP format:

  1. Select the entire test suite in the Browser window.
  2. Select Convert to MP from the File menu.
    The Convert to MP dialog is opened, in which you may specify the name of the new document and where it is to be saved.

Figure 54 : The Convert to MP dialog

  3. Select the directory path in the Directories box.
  4. Type the file name that you wish the exported file to be called. In this example the file name is Example_suite.mp.
    Note the suffix .mp (used by convention). You are now ready to convert the file.
  5. Click Convert to export the test suite.
    The TTCN-MP file for the test suite can now be found in the file Example_suite.mp. You can check it if you like.

Importing a Test Suite from MP Format

Your next task is to import the TTCN-MP file that you have just exported. Do not close the existing open test suite - you need that later.

  1. Select Convert to GR from the Generate menu in the Organizer. The Convert to GR dialog is opened:

Figure 55 : The Convert to GR dialog

  2. Select Convert TTCN MP to TTCN GR.
  3. Click the folder icon of the Source MP file name field. The Select Source MP file dialog is opened.
  4. Click the file that you want to convert, when you have found it in the Files list. In this case the file is Example_suite.mp.
  5. Click OK.
  6. Click the folder icon of the Destination directory for generated TTCN GR field. The Select Destination Directory dialog is opened.
  7. Select the destination directory, i.e. where you want the converted document to be saved.
  8. Click OK.
  9. Click the Convert button in the Convert to GR dialog.
    The file is converted and is stored in a file with a generated file name in the given directory. The generated file name is the MP file name with the extension .itex. This is shown in the Organizer log.

Note:

You can open and work with MP-files just as you do with GR-files. All conversions to and from MP will then be done transparently.

Now perform the following:

  1. Select the TTCN Test Specification chapter in the Organizer.
  2. Select Add Existing in the Edit menu in the Organizer. The Add Existing dialog is opened.
  3. Select the file that you just converted (Example_suite.itex) and click OK.
    Either type the filename and the path or click the folder button to select the file.
  4. Make sure that the Show in editor option is selected.
  5. Click Add.
    The test suite is now added in the TTCN Test Specification chapter and it is opened in the Browser.
  6. In the Browser, rename this test suite as Example_B.
  7. Expand the entire test suite.
  8. Analyze the entire test suite.
  9. Do not close Example_B, you will need it in the following exercise.


Replacing, Comparing and Merging

In this exercise you are going to merge the two test suites, the Example_A and the Example_B that you have just created. First you should change some names in one test suite though - to make it different - and then compare it with the other.

What You Will Learn

  • To start search for a specified pattern and to replace matches
  • To compare two TTCN documents
  • To merge two TTCN documents

Searching and Replacing

The first thing you should do is to change some text in Example_B. The reason for this is that there would be no use comparing the documents - which you are soon going to do - if they both are the same.

You can start the search from both the Browser and the Table Editor, and in this case you will do it from the Browser:

  1. In the Browser displaying Example_B, click the Search button.
    The Table Editor will be opened, and as you can see it is empty.

  2. Type 1 in the Look for field
  3. Click the Search button.
    The first table of the test suite containing 1 is opened and 1 is highlighted.
  4. Type 2 in the Change to field.

  5. Click the Replace button.
    1 will be changed to 2 and it is no longer highlighted.

  6. Click the Search button again.
    This will find another occurrence of 1.

  7. Click the Proceed button.
    This is the same as first clicking Search and then Replace. Another occurrence of 1 will be found.

  8. Click the Replace all button.
    This will change all occurrences of 1 to 2. The Table Editor will display the table in which the final replacement was made and the status bar will show the total number of replacements.

Comparing Two Documents

When you have changed some text in Example_B, you can compare it to Example_A to see if any similarities exist:

  1. Ensure that the test suites Example_A and Example_B are opened.
  2. Select the entire test suite Example_B
  3. Select Compare from the Browser Tools menu.
    The Compare Documents dialog is opened:

Figure 56 : The Compare dialog

  4. Make the dialog settings as depicted in Figure 56.
    This will compare the test suite Example_A with the selection that you made in Example_B, in this case the entire test suite.
    Also make sure that Example_A is selected in the Documents field in the dialog.
  5. Click the Compare button.
    The comparison will deselect all items in the Browser for Example_B that do not match with items in Example_A. What remains are the items that are the same in both test suites, namely the lower PCO L and the PDUs SEND and RECEIVE. These tables will also be presented in the TTCN suite log.
  6. Delete the selected items from Example_B.
    The only items left now are the ones that differ between the two test suites. You are now ready to try a merge.

Merging Two Documents

The Merge tool is used for merging one TTCN document (complete or partial) into another. This only works on condition that the documents do not conflict, that is, if an item in one document has the same name as another item in the other document. This will not be a problem now, as you have already compared the documents and deleted the similarities.

The final exercise in this tutorial is that you should merge what is left of Example_B into Example_A:

  1. Select the entire suite Example_B.
  2. Select Merge from the Browser Tools menu.
    The Merge Documents dialog is opened:

Figure 57 : The Merge Documents dialog

  3. Select Example_A in the Documents chapter. That is the suite that you are going to merge Example_B into
  4. Click the Merge button.
    If you look at the Example_A Browser, you should see that the suites have been merged into one. This is also depicted in Figure 58.

Figure 58 : The Example_B has been merged into Example_A


So Far...

You should now have learned how to create a test suite and what the test suite looks like in the Browser. You have also learned to create and edit tables and how to work with the Table Editor. Other things you should have learned is how to analyze the test suite and how to find errors.

Some other TTCN suite functionality that you have used are selecting, generating the overview, printing, making reports, converting to MP and back to GR, replacing, comparing and merging.

By practicing this tutorial you have probably not achieved any knowledge about TTCN. If you want to know more about the basics of TTCN you may read the TTCN Suite Methodology Guidelines. That volume is, however, not a hands-on tutorial on TTCN.

The following tutorial is 7 Tutorial: TTCN-SDL Co-Simulator (on UNIX). Before you start practising that, you should know how to use the SDL Simulator. A tutorial on that can be found in Tutorial: The SDL Simulator.


6 Tutorial: TTCN-SDL Co-Simulator (Windows)

This is an introductory tutorial to the TTCN-SDL Co-simulator in Windows and an example of a complete test session with Cbasic. The tutorial is divided into sections that describes steps that are performed during a typical test session.

Note: Windows version

This is the Windows version of the tutorial. The UNIX version is 7 Tutorial: TTCN-SDL Co-Simulator (on UNIX).


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the TTCN-SDL Co-simulator. When you have read and practised this tutorial you will know the actions required to execute a simulated test.

It is assumed that you know how to use the SDL Simulator. More information can be found in Tutorial: The SDL Simulator and in The SDL Simulator.


The Steps in a Test Session

When a TTCN test suite and an SDL suite system already exists, this is what you do in a typical test session:

  1. Generate and start the TTCN-SDL Co-simulator.
  2. Generate and start the SDL Simulator.
  3. Switch to simulation mode in the TTCN suite.
  4. Set up the communication between the TTCN-SDL Co-simulator and SDL Simulator.
  5. Start the simulation.
  6. Start the TTCN-SDL simulation.
  7. Perform the simulation.


The Test System

This section describes the system that is going to be tested and what roles the TTCN-SDL Co-simulator and SDL Simulator play in the test.

An SDL system called ABP will be used in this tutorial. The ABP system implements a small OSI stack containing a network layer, a data-link layer and a physical layer. The network component on one side is handled by the TTCN suite and on the other side by an SDL process.

The data-link layer implements a very simple protocol known as the Alternating Bit Protocol (ABP).

The network protocol is very simple protocol, where all messages are echoed back as an acknowledgment that they have been received.

This setup gives us the ability to send messages from the TTCN suite to the network peer simulated by the SDL suite, and to receive acknowledgments in return. If the answer is identical to the message, we have managed to communicate successfully.

What we want to test is the ability of the Data-Link layer's protocol to deliver, even when messages are lost on the way. To enable this, we have introduced an extra channel between the TTCN-SDL Co-simulator and the SDL simulator, on which commands can be sent to make the physical layer lose messages.

The ABP system is stored in the Telelogic Tau installation, in the sub-directory examples\bitprotocol. If you have a default installation, the complete path is C:\Telelogic\SDL_TTCN_Suite4.4\examples\bitprotocol.


Setting Up a Simulation

What You Will Learn

  • To set up the TTCN-SDL Co-simulator and SDL simulator
  • To generate and build simulator executables
  • To initialize the communication between the simulators
  • To start the simulators

When you are finished with this section, the simulators should be ready to run a TTCN suite test on a simulated SDL system.

Generating and Starting the TTCN-SDL Co-Simulator

The first thing you should do is to generate and start the TTCN-SDL Co-simulator:

  1. Start Telelogic Tau.
  2. In the Organizer, load the system ABP from the file abp.sdt.
    You can find this file in C:\Telelogic\SDL_TTCN_Suite4.4\examples\bitprotocol (where C:\Telelogic\SDL_TTCN_Suite4.4 is the default installation directory).
    You may also find it useful to copy the bitprotocol directory and the files included, to another directory. In any case, you have to make sure the bitprotocol directories and files are not read-only.
  3. Double-click the abp icon in the TTCN Test Specification chapter.
    This will start the TTCN suite with the abp.itex test suite opened in the Browser.
  4. Select the node named abp in the Browser.
  5. Select Generate Code from the Build menu.
    The Analyzer/TTCN to C Compiler Settings dialog is opened:

Figure 59 : The TTCN to C compiler options

  6. In the TTCN to C Compiler Options, make sure that Co-simulator is selected and that Ignore bodies of test suite operations is checked.
  7. Select an output directory that has sufficient space and where you have write permission.
  8. In the Build Options, ensure that the Run Make option is selected.
  9. You may also have to change the Makefile Type.
  10. Click OK to start the generation and compilation of the TTCN-SDL Co-simulator executable.
    The TTCN suite will now generate and build the TTCN-SDL Co-simulator executable. In the Log Manager window, you can see the what is happening.

  11. Click the Start Simulator button in the TTCN suite tool bar.
    This is a toggle button, which means that if it is depressed, the simulator is in simulation mode. If the button is released, simulation is ended.
    The Simulator Toolbar is available whenever this button is depressed.
.

    • You can also select Invoke Simulator from the Simulate menu.
      A file selection dialog is opened.
  12. Select abp.exe in the dialog.
    The TTCN suite simulation executable has the same name as the test suite that you are simulating.
    This step will put the TTCN suite in simulation mode, and it is now ready to simulate.

Generating and Starting the SDL Simulator

Now you have to set up the SDL simulator as well.

  1. In the Organizer, select the system diagram ABP from the SDL System Structure chapter.
  2. Click the Simulate button in the tool bar.
    • You may also want to check the settings in the Make dialog (opened from the Generate menu) before you generate and compile the simulator. If you select Make or Full Make in that dialog, you will have to open the Simulator UI and load the simulator after that.
      The SDL simulator generates and builds a simulator executable. The simulator window is displayed with the simulator started. You are now ready to simulate.

Getting the Simulators to Communicate

The next step you should perform is to initialize the communication between the simulators:

  • Enter the command start-itex in the SDL simulator window.
    This instructs the SDL simulator to communicate with the TTCN-SDL Co-simulator.


Performing the Simulation

What You Will Learn

  • To single step a test case
  • To run a test case at full speed
  • To run a test batch
  • To set and delete breakpoints
  • To abort a simulation

Single Stepping Test Cases

  1. In the TTCN Browser, select the test case TC_01.

Figure 60 : The test case TC_01 is selected in the Browser

This is the test case that you are going to execute.

  2. Click the Step Simulation button.
    Each time you click this button, the TTCN-SDL Co-simulator executes one step of TTCN code.

A Table Editor is opened. In the first line of TTCN code, there is a colored bar.

Note:

This bar indicates which line will be executed the next time you click the Step Simulation button.

  3. Enter the command go-forever in the SDL simulator window.
    The SDL simulator is now executing and it is possible to perform a simulation.
  4. Click the Step Simulation button repeatedly until you reach the end of the test case.

When you have reached the end of the test case, the bar that indicates the current line will change color. The color indicates the result of the execution of the test case. The colors are as follows:

Color | Verdict
Green | PASS
Yellow | INCONC
Red | FAIL

At this point the SDL Simulator is running at full speed. This is normal and you can safely ignore it. The cause of this is a timer in the simulated system that fires repeatedly while waiting for input from the TTCN-SDL Co-simulator.

Running Test Cases at Full Speed

  1. In the TTCN Browser, select the test case TC_01 again.
    This time, you are going to execute the test case at full speed.

  2. Click the Run Simulation button.
    The Table Editor is opened. The lines of TTCN code in the table will execute without pausing until the end of the test case is reached.

    • It is possible to stop the execution by clicking the Pause Simulation button

Running Test Batches

It is also possible to execute more than one test case or test group.

  1. In the TTCN Browser, select the test case TC_01 and TC_02.

Figure 61 : Selecting multiple test cases

  2. Press the Run Simulation button.
    This will cause the TTCN-SDL Co-simulator to execute all the selected test cases in turn without pausing anywhere.

Note:

This requires an SDL suite system that always ends in a state from where you can execute a new test case. The SDL suite system may not require any manual resetting between test cases.

Toggling Breakpoints

  1. Set the cursor on line 3 in the test case TC_01.

  2. Press the Toggle Breakpoint button.
    This will set a breakpoint on line 3.
    The button will toggle the breakpoint status on the line that the cursor is placed on. If there is a breakpoint set on the line, it will be removed. If there is not a breakpoint there, one will be set.

  3. Select test case TC_01 in the Browser.
  4. Press the Run Simulation button.
    The TTCN-SDL Co-simulator will run without pausing between lines of TTCN code. When it reaches the line where the breakpoint was set, it will stop.
  5. Set the cursor on line 3 in the test case TC_01.
  6. Press the Toggle Breakpoint button.
    This will remove the breakpoint from line 3.
  7. Press the Run Simulation button.
    The simulator now continues to run until it reaches the end of the test case.

Ending a Simulation

It is possible to end a simulation in the middle of an execution:

  1. Select test case TC_01 in the browser.
  2. Click the Step Simulation button twice.
    This will place the current line on line 2 in the test case.
    You now realize that the execution was a mistake and you want to abort it.
  3. Click the Abort Simulation button.
    This aborts the execution of the test case for the TTCN-SDL Co-simulator.
  4. In the SDL simulator window, select Restart in the File menu.
    This restarts the SDL simulator. This step is necessary because otherwise the SDL Simulator and the TTCN-SDL Co-simulator would be out of sync.
    To continue co-simulation, you will need to enter the command start-itex in the SDL simulator, start running the test in the TTCN-SDL co-simulator, and then enter the command go-forever in the SDL simulator.


Taking a Look at the Log Window

Every execution of the TTCN-SDL Co-simulator produces a log. This log is output in the Log Manager. Every line in the test case that is executed will be present in the log.

This makes it possible to examine a trace of the execution after it has finished. This is valuable when running the test cases in a batch.

The log contains the test component, table name, line within the table, behaviour, constraint and verdict.

Figure 62 : An execution log

Every test case also produces a conformance log. This log contains detailed information about the tests performed. It is very useful when determining why a test case failed or succeeded.

Figure 63 : A conformance log


7 Tutorial: TTCN-SDL Co-Simulator (on UNIX)

This is an introductory tutorial to the TTCN-SDL Co-simulator on UNIX and an example of a complete test session with Cbasic. The tutorial is divided into sections that describes steps that are performed during a typical test session.

Note: UNIX version

This is the UNIX version of the tutorial. The Windows version is 6 Tutorial: TTCN-SDL Co-Simulator (Windows).


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the TTCN-SDL Co-simulator. When you have read and practised this tutorial you will know the actions required to execute a simulated test.

In this tutorial it is assumed that you know how to use the SDL Simulator. More information can be found in Tutorial: The SDL Simulator and in The SDL Simulator.


The Steps in a Test Session

When a TTCN test suite and an SDL suite system already exists, this is what you do in a typical test session:

  1. Generate and start the TTCN-SDL Co-simulator.
  2. Generate and start the SDL simulator.
  3. Set up the communication between the TTCN-SDL Co-simulator and SDL simulator.
  4. Start the simulation.
  5. Start the TTCN-SDL simulation.
  6. Perform the simulation.


The Test System

This section describes the system that is going to be tested and what roles the TTCN-SDL Co-simulator and SDL simulator play in the test.

An SDL system called ABP will be used in this tutorial. The ABP system implements a small OSI stack containing a network layer, a data-link layer and a physical layer. The network component on one side is handled by the TTCN suite and on the other side by an SDL process.

The data-link layer implements a very simple protocol known as the Alternating Bit Protocol (ABP).

The network protocol is very simple protocol, where all messages are echoed back as an acknowledgment that they have been received.

This setup gives us the ability to send messages from the TTCN suite to the network peer simulated by the SDL suite, and to receive acknowledgments in return. If the answer is identical to the message, we have managed to communicate successfully.

What we want to test is the ability of the Data-Link layer's protocol to deliver, even when messages are lost on the way. To enable this, we have introduced an extra channel between the TTCN-SDL Co-simulator and the SDL simulator, on which commands can be sent to make the physical layer lose messages.

The ABP system is stored in the Telelogic Tau installation, in the sub-directory examples/bitprotocol. If you have set up the $telelogic environment variable, the complete path is $telelogic/examples/bitprotocol.


Setting Up a Simulation

What You Will Learn

  • To set up the TTCN-SDL Co-simulator and SDL simulator
  • To generate and build simulator executables
  • To initialize the communication between the simulators
  • To start the simulators

When you have finished with this section, the simulators should be ready to run a TTCN suite test on a simulated SDL system.

Generating and Starting the TTCN-SDL Co-Simulator

The first thing you should do is to generate and start the TTCN-SDL Co-simulator:

  1. Start Telelogic Tau.
  2. In the Organizer, load the system ABP from the file abp.sdt.
    You can find this file in $telelogic/examples/bitprotocol (where $telelogic points to the installation directory).
  3. Double-click the abp icon in the TTCN Test Specification chapter.
    This will start the TTCN suite with the abp.itex test suite opened.
  4. Select the node named abp in the TTCN Browser.
  5. Select Make from the Tools menu.
    The TTCN Make dialog is opened.
  6. Make sure that the Use standard kernel option is checked and that the Simulation command is selected.

Note:

The dialog will show up the first time you build your simulator. In later builds it will remember the settings.

  7. Select the Directory for generated files to point to a location where you have write permission and sufficient space for the generated files.
  8. Click the Full Make button to start the generation and compilation of the TTCN-SDL Co-simulator executable.
    The TTCN suite will now generate and build the TTCN-SDL Co-simulator executable.

  9. Click the Start Simulator button on the TTCN suite tool bar.
    This will start the TTCN-SDL Co-simulator and open the simulator window. The TTCN suite is now ready to simulate.
.

Generating and Starting the SDL Simulator

Now you have to set up the SDL simulator as well:

  1. In the Organizer, select the system diagram ABP from the SDL System Structure chapter.
  2. Click the Simulate button in the tool bar.
    • You may also want to check the settings in the Make dialog (opened from the Generate menu) before you generate and compile the simulator. If you select Make or Full Make in that dialog, you will have to open the Simulator UI and load the simulator after that.
      The SDL simulator generates and builds a simulator executable. The SDL simulator window is displayed with the simulator started. You are now ready to simulate.

Getting the Simulators to Communicate

The next step you should perform is to initialize the communication between the simulators.

  • Enter the command start-itex in the SDL simulator window.
    This instructs the SDL simulator to communicate with the TTCN-SDL Co-simulator.


Performing the Simulation

What You Will Learn

  • To single step a test case
  • To run a test case at full speed
  • To run a test batch
  • To set and delete breakpoints
  • To abort a simulation

Single Stepping Test Cases

  1. In the TTCN-SDL Co-simulator window, select the test case TC_01 and then click the right arrow that appears.
    This selects the test case that we will execute by adding it to the Selected box:

Figure 64 : Selecting a test case to execute

  2. Click the Step Simulation button
    Each time you click this button, the TTCN-SDL Co-simulator executes one step of TTCN code.

A Table Editor is opened. In the first line of TTCN code, there is a colored bar.

Note:

This bar indicates which line will be executed the next time you click the Step Simulation button.

  3. Enter the command go-forever in the SDL simulator window.
    The SDL simulator is now executing and it is possible to perform a simulation.
  4. Click the Step Simulation button repeatedly until you reach the end of the test case.

Running Test Cases at Full Speed

  1. In the TTCN-SDL Co-simulator window, make sure that the test case TC_01 is still in the Selected box. If it is not, select the test case again and click the right arrow.

Note:

If the test case already is in the Selected box, you do not have to select it again. If you select it again, you are actually telling the TTCN-SDL Co-simulator that you want to execute the test case twice.

  2. Click the Run Simulation button.
    The simulator now starts executing lines of TTCN code without pausing. This will continue until the end of the test case is reached or until you click the Pause Simulation button.
    As you can see, the colored bar in the Table Editor will change rapidly.

At this point the SDL simulator is running at full speed. This is normal and you can safely ignore the SDL simulator. The cause of this is a timer in the simulated SDL system that fires repeatedly while waiting for input from the TTCN-SDL Co-simulator.

Running Test Batches

It is also possible to execute more than one test case or test group.

  1. In the TTCN-SDL Co-simulator window, deselect the test case TC_01 in the Available box. You do this by clicking on the test case.
  2. Select the test case TC_02 and click the right arrow. The test case is added to the Selected box after TC_01.
    You can perform this operation with as many test cases as you wish. You can add them in any order. The Selected box tells you in what order the test cases will be executed.
  3. Press the Run Simulation button.
    This will cause the TTCN-SDL Co-simulator to execute all the selected test cases in turn without pausing anywhere. Another Table Editor is opened for the second test case.

Note:

This requires an SDL suite system that always ends in a state from where you can execute a new test case. The SDL suite system may not require any manual resetting between test cases.

Toggling Breakpoints

  1. Make sure that the TTCN-SDL Co-simulator window is active and press <Ctrl+B>.
    This will open the Breakpoints window. In this window you can add and delete breakpoints.
  2. Select Add from the Edit menu.
    This adds an empty breakpoint definition to the breakpoint editor.
  3. Click in the edit field at the bottom of the Breakpoints window and type in TC_01 3 followed by <Return>.

Figure 65 : A breakpoint in the Breakpoints window

  4. Select Save from the File menu.
  5. Type in a filename with the extension .ttb and select OK.
    This will set a breakpoint on line 3.
  6. In the simulator window, make sure that only the test case TC_01 is selected.
  7. Press the Run Simulation button.
    The TTCN-SDL Co-simulator will run without pausing between lines of TTCN code. When it reaches the line where the breakpoint was set, it will stop, as you can see in the Table Editor.
  8. Select the breakpoint line we just added in the Breakpoints window.
  9. Select Delete from the Edit menu.
    This will remove the breakpoint from line 3.
  10. Select Save from the File menu.
  11. Select Close from the File menu.
  12. Click the Run Simulation button.
    The simulator now continues to run until it reaches the end of the test case.

Ending a Simulation

It is possible to end a simulation in the middle of an execution

  1. Click the Step Simulation button twice.
    This will place the current line on line 2 in the test case.
    You now realize that the execution was a mistake and you want to abort it.

  2. Click the Abort Simulation button.
    This aborts the execution of the test case for the TTCN-SDL Co-simulator.

  3. In the SDL simulator window, select Restart in the File menu.
    This restarts the SDL simulator. This step is necessary because otherwise the SDL Simulator and the TTCN-SDL Co-simulator would be out of sync.
    To continue co-simulation, you will need to enter the command start-itex in the SDL simulator, start running the test in the TTCN-SDL co-simulator, and then enter the command go-forever in the SDL simulator.


The Execution Trace

Every execution of the TTCN-SDL Co-simulator produces a trace. This trace is output in the trace window. Every line in the test case that is executed will be present in the trace window.

This makes it possible to examine a trace of the execution after it has finished. This is valuable when running the test cases in a batch.

  • To see the execution trace, select Execution Trace in the Window menu of the TTCN-SDL Co-simulator.

The trace contains the test component, table name, line within the table, behaviour, constraint and verdict.

Figure 66 : An execution trace


The Conformance Log

Every test case produces a conformance log. This log contains detailed information about the tests performed. It is very useful when determining why a test case failed or succeeded.

  • To see the conformance log, select Conformance Log in the Window menu of the TTCN-SDL Co-simulator.

Figure 67 : A conformance log


8 Tutorial: The TTCN Link

This is a tutorial for TTCN Link. It is intended to give a guided tour through some of the facilities provided.

To be able to follow this tutorial, you need some experience of both SDL and TTCN as well as the SDL suite and TTCN suite.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the TTCN Link function and understand its usability. You are supposed to read this tutorial sequentially and practice the exercises.

Note: Platform differences

This tutorial is possible to run on both the UNIX and Windows platform, and is described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc.
When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.


More about TTCN Link

TTCN Link is a CATG (Computer Aided Test Generation) tool that enables efficient development of TTCN test suites based on SDL specifications. By using TTCN Link, you can automatically generate the declarations from the SDL specification and interactively build test cases. This ensures consistency between the test suite and the specification. TTCN Link also provides you with an integrated SDL/TTCN environment with access to the specification directly from the test case.

Using TTCN Link

The inputs needed to use TTCN Link for test case development, are an SDL specification and a test suite structure with test purposes. TTCN Link supports test suite development in three different ways:

  • Keeping the test suite consistent with the SDL specification.
  • Supporting the test suite developer with information about the SDL specification, making the actual TTCN coding easier.
  • Providing access to the SDL specification directly from the test case.

Three distinct phases can be distinguished when TTCN Link is used:

  • Preparation of the SDL specification to be used in the test case development.
  • Generation of the TTCN declarations.
  • Development of the TTCN test cases and constraints.


Taking a Look at the SDL System

In this tutorial, you will use the example SDL system called inres (short for Initiator-Responder). This system is an example of a simplified communication protocol intended to give a secure transfer of information over an unsafe communication medium. It provides a one-way, connection-oriented communication service that uses sequence numbers and retransmission to ensure that messages sent to the initiator side, are correctly received at the responder side.

Start this tutorial by taking a look at the inres SDL system:

  1. Copy the inres directory from $telelogic/sdt/examples/ (on UNIX) or \Telelogic\SDL_TTCN_Suite4.4\sdt\examples\ (in Windows) to your working directory and make sure that you have write permission.
  2. Start Telelogic Tau.
  3. Open the example SDL system called inres.sdt located in the inres directory.
  4. Select SDL Overview in the Generate menu in the Organizer, to generate an overview of the SDL system.
    The Generate SDL Overview dialog is opened. You do not have to change any settings in this dialog.
  5. Click the Generate button in the Generate SDL Overview dialog.
    The SDL Editor is opened and displays the overview.
    The block Station_Ini in System inres is the protocol that you are going to create a test for. However, due to the test architecture that is to be used, the tester can not access the lower service access point of the protocol. Since TTCN Link assumes that the channels to/from the environment are accessible for the tester (and will correspond to PCOs in the test suite), the block Medium, that models the underlying service provider, is included in the SDL system.


Generating a TTCN Link Executable

To create a test suite based on an SDL system, it is necessary to begin by creating an executable program that will be used during the test suite development. Such programs, which are created by the SDL to C Compilers, are called Link Executables. Sometimes they will also be referred to as state space generators, since the purpose of these programs is to generate the combined state space of the SDL system and the TTCN test case.

  1. Select Make in the Generate menu in the Organizer, to create a Link Executable for the SDL system.
    • Since you probably have not saved the system since you generated the overview, you will be prompted to do so before the SDL Make dialog can be opened.
  2. Make sure that the following options are set in the SDL Make dialog:
    • Code generator: Cbasic
    • Prefix: Full
    • Separation: No
    • Capitalization: Lower case
  3. Make also sure that the following options are turned on:
    • Analyze & generate code
    • Makefile
    • Compile and link
  4. Select Generate Makefile.
  5. Select a TTCN Link kernel for a suitable compiler in the Use standard kernel option.
  6. Click the Full Make button.
    A TTCN Link executable will now be generated from the SDL specification. You can open the Organizer log to see the result of the make process.

Now the preparations are completed and you can start developing a new test suite.


Creating a Test Suite

What You Will Learn

  • To specify the state space generators to use, in two different ways
  • To generate the TTCN declarations

Creating a New Test Suite

Start by creating a new test suite:

  • Add a new test suite, for example called inres, to the TTCN Test Specification chapter. In the Add New dialog, make sure that the option Show in editor is on.
    The TTCN suite is started and the Browser will display the new test suite.

The first step when you have created the new test suite, is to use TTCN Link to generate the declarations. Before you can do this, you have to tell the TTCN suite what state space generator to use.

Specifying the Link Executable

Before you can generate the declarations, you have to tell the TTCN suite which link executable to use. You can do this in two ways:

One way is to associate the test suite with the SDL system:

  1. In the Organizer, select the top icon in System inres.
  2. Select Associate from the Edit menu.
    The Associate dialog is opened.
  3. Select the test suite that you have created.
  4. Click the OK button.
    The association is illustrated by a new icon placed under the test suite icon.

Another way is to explicitly specify the state space generator to use:

  1. In the TTCN suite, select Select Link Executable from the SDT Link menu. (On UNIX, it is the menu in the Browser.)
    The Select Link Executable dialog is opened.
  2. Select inres_stx.exe.
    All generators will by default be given the name <sdl system name>_st<x>.exe , where <x> is depending on which compiler was used when the executable was created.
  3. Click OK.

Note:

In case a link executable has been selected both in the Organizer and in the TTCN suite, the one selected in the TTCN suite is the link executable that will be used.

Generating the TTCN Declarations

Since the SDL specification contains all information about the interfaces, this information is available to you when using TTCN Link. When you generate the TTCN declarations, the interface information is extracted from the SDL specification and included in the TTCN test suite as PCO, ASP and data type tables.

To generate the TTCN declarations:

  1. In the TTCN suite, select Generate Declarations from the SDT Link menu. (On UNIX, it is the menu in the Browser.)
  2. Expand the declarations part of the test suite and have a look at the generated declarations.
    Objects of the following types have been generated:
    • ASN.1 type definitions
    • PCO type declarations
    • PCO declarations
    • ASN.1 ASP type definitions
      The PCO declarations, and the PCO type declarations, are generated from the channels to/from environment in the SDL system.
      The ASP definitions are generated from the SDL signals that can be transported on the channels to/from the environment.
      The ASN.1 type definitions are generated from the types of the parameters of the above mentioned signals.
      Generated declarations will be analyzed automatically.
  3. Expand the dynamic part of the test suite.
    A defaults library is generated. It contains the table OtherwiseFail with an otherwise statement for each PCO, and in addition a timeout statement that match any timeout event.


Creating a Simple Test Case

It is now time to create the first test case. The one you will develop is the test case intended to test the successful connection establishment of the protocol.

How to create constraints and test cases with TTCN Link differs between Windows and UNIX. On UNIX, it is possible to create constraints directly from the Send dialog. In Windows, you have to create the constraints first, before they will be visible in the Link dialog.

What You Will Learn

  • To synchronize a test case (UNIX only)
  • To create constraints
  • To add send statements
  • To add receive statements

Creating a Test Case and Constraints
(in Windows)

Before you start creating the test case, you have to create a constraint for the ASP ICONreq:

  1. Copy the table ICONreq from ASN.1 ASP Type Definitions.
  2. Paste the table in the constraints part, below ASN.1 ASP Constraint Declarations.
  3. Open this table and change the name to, for example, ICONreq_1.
  4. Analyze the table.
  5. Close the table.

Creating a Test Case and Adding Statements

You are now going to create a test case and add send and receive statements by using the Link dialog. When you use the Link dialog, the test case is synchronized with the SDL specification and you cannot edit the behavior lines directly in the table.

  1. Create a new test case, for example called test_case_1.
  2. Open the test case in the Table Editor.
  3. Select Link from the SDT Link menu.
    The Link dialog is opened. The first thing you will add is a send statement for the ICONreq service primitive.

Figure 68 : The Link dialog

  4. In the dialog, select the following:
    • The PCO ISAP1
    • The type ICONreq
    • The constraint ICONreq_1
      The contents of the Behavior line and Constraint fields will be updated in accordance with your selection.
  5. Click Apply.
    The following behaviour line, a send statement, is added to the test case:

Behaviour Description
Constraints Ref

 ISAP1 ! ICONreq

 ICONreq_1

  6. Click Generate Receives.
    This will add a second behavior line, a receive statement, to the test case:

Behaviour Description
Constraints Ref

 ISAP1 ! ICONreq

 ICONreq_1

   MSAP2 ? MDATind

 MDATind500

A corresponding constraint will also be created.
If needed, just move the Link dialog to see the test case. Do not close the dialog.
The table MDATind500 (that was just created) is made visible in the Browser.
  7. Analyze the test suite by selecting Analyze Suite from the Build menu.

Creating Another Constraint

Before you can complete the connection establishment, by adding send and receive statements for the MDATreq ASP, you have to create a new constraint:

  1. In the Browser, create a copy of the constraint that was just created, MDATind500.
  2. Open the copy of MDATind500 and make the following changes:
    • The name should be MDATreq_1
    • The ASP type should be MDATreq
    • The "id" part of the parameter should be CC instead of CR, which means that the constraint value should be:

{ mSDUType1 {id CC,
num zero,
data 0}}

  3. Analyze the table.
  4. Close the table.

Adding Statements to Complete the Connection

  1. In the Link dialog, select Clear.
    This will refresh the dialog.
  2. Select the following:
    • The PCO MSAP2
    • The type MDATreq
    • The constraint MDATreq_1
  3. Click Apply.
    This will add a third behaviour line to the test case.
  4. Click Generate Receives.
    The test case should now contain 4 behavior lines.

Figure 69 : The complete test case

  5. Close the Link dialog.

Creating a Test Case and Constraints
(on UNIX)

  1. Create a new test case, for example called test_case_1.
  2. Open the test case in the Table Editor.
    As you can see, the Table Editor contains the extra menu SDT Link.
  3. Select Resynchronize from the SDT Link menu.
    The test case will now be synchronized with the SDL specification. This means that the behaviour lines will be modified from the SDT Link menu. However, if you edit a field in the test case manually - except for comment fields - the editor will not be synchronized anymore.
    What happens behind the scene is that the state space generator is started and an initial part of the state space is explored. However, you do not have to think of that now.

Adding Statements

The first thing you will add, is a send statement for the ICONreq service primitive:

  1. Select Send in the SDT Link menu. The Send dialog is displayed:

Figure 70 : The Send dialog

  2. Select ISAP1 in the PCOs list.
    The unselected PCO is moved to the lower part of the list.
  3. Select ICONreq in the Types list.
    The unselected types are moved to the lower part of the list.
  4. Click the New button to create a constraint for this ASP.
    A Table Editor, displaying the new constraint is opened.
  5. Change the name of the constraint to, for example, ICONReq_1.
  6. Analyze the table.
  7. Close the table.
  8. Click the Refresh button in the Send dialog to make the new constraint, ICONReq_1, visible in the Constraints list.
    Since this is the only constraint of the selected type, it will automatically be selected.
  9. Click OK.
    The following behaviour line, a send statement, is added to the test case:

Behaviour Description
Constraints Ref

 ISAP1 ! ICONreq

 ICONreq_1

  10. Select Receive from the SDT Link menu.
    This adds second behavior line, a receive statement, to the test case:

Behaviour Description
Constraints Ref

 ISAP1 ! ICONreq

 ICONreq_1

      MSAP2 ? MDATind

 MDATind500

The corresponding constraint is created and analyzed.

Adding Statements to Complete the Connection

To complete the connection establishment, you should now add send and receive statements for the MDATreq ASP:

  1. Select row 2 in the Behaviour Description column - the field containing MSAP2 ? MDATind.
  2. Select Send from the SDT Link menu.
    The Send dialog will once again be opened. Now you will create a new constraint by copying an old constraint and modify it.
  3. Select MDATind500 in the Constraints list.
  4. Click Copy.
    The Table Editor will appear, displaying a copy of the MDATind500 constraint.
  5. Change the name to MDATreq_1.
  6. Change the ASP type to MDATreq.
  7. Change the "id" part of the parameter to CC instead of CR, which means that the constraint value should be:
{ MSDUType1 {id CC,
num zero,
data 0}}
  8. Analyze the table and then close it to get back to the Send dialog.
  9. Click Refresh in the Send dialog.
  10. Select the new constraint, MDATreq_1.
  11. Select the PCO MSAP2.
  12. Click the OK button.
    The new send statement is inserted in the test case table.
  13. Select Receive from the SDT Link menu once more to complete the connection establishment test case.


Taking a Look at the SDL System (Again)

What You Will Learn

  • To display an SDL diagram
  • To display an MSC diagram

Displaying an SDL Diagram

It is possible to display the SDL system directly from the test case:

  1. Select a behaviour line in the test case.
  2. Select Show SDL from the SDT Link menu.
    The SDL Editor is started, displaying all symbols in the SDL process graphs that where executed in the SDL system as a response to the currently selected row in the test case.

Displaying an MSC Diagram

It is also possible to display an MSC diagram, to illustrate and document the test case:

  1. Select a behaviour line in the test case.
  2. Select Show MSC from the SDT Link menu.
    The MSC Editor is started, displaying the execution of the SDL system state up to the currently selected row in the test case. This may be useful as a means to understand how unexpected receive statements are possible.


So Far...

You should now have learned how to create a link executable and how to tell the TTCN suite which link executable to use. You should also know how to generate TTCN declarations from SDL specifications and how to create a test case that is synchronized with SDL specifications. Finally, you should have tried to generate SDL and MSC diagrams from the test case.

If you know how to use the SDL Validator and have access to it, you are now ready to read and practise 9 Tutorial: The Autolink Tool.


9 Tutorial: The Autolink Tool

This tutorial is intended to guide you through some of the features of Autolink. There are some aspects of Autolink which are not covered by this tutorial. For a complete description of all Autolink facilities, please see "Using Autolink.

To be able to follow the tutorial, some experience of the SDL Validator is needed. Therefore you should have read and practised Tutorial: The SDL Validator. You also need to have basic knowledge of the TTCN suite.

The example protocol used in this tutorial is the inres system, the same as the one used in the TTCN Link tutorial.


Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with Autolink. The tutorial is split into three parts. You are strongly recommended to read the tutorial sequentially as each exercise is founded on the previous one.

In the first exercise, you will start by creating a simple MSC. Based on this MSC, you will generate a TTCN test case and save it in a test suite. You will also learn how to manipulate constraints.

In the second session, you will develop a structured MSC. Once again a TTCN test case is generated, but this time by a direct MSC into TTCN translation. Additionally, so-called translation rules are introduced as a simple example for an Autolink configuration.

In the third part, you will use the Tree Walk algorithm to create a large number of MSC test cases automatically. You will also learn how to save and load generated test cases in Autolink. This facility will allow you to compute test cases separately and distribute test generation over several computers (provided that you have more than one license).

It is assumed that you know how to generate an SDL Validator. In addition, you should be familiar with the basic functionality of the SDL Validator, the MSC Editor and the TTCN suite. You may also find it useful to have knowledge of MSC diagrams.

Note: Platform differences

This tutorial is possible to run on both the UNIX and Windows platform, and is described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc.
When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.


Basics of Autolink

Autolink assists you in the automatic generation of TTCN test suites based on an SDL specification. In a simple approach, a TTCN test suite is generated in three steps:

  1. One or more system level Message Sequence Charts have to be defined. System level MSCs contain the externally visible events of a path. These events describe the correct test sequences of a TTCN test case.
  2. The MSCs defined in step 1 are used to generate internal test case representations.
  3. All internal test case representations are saved as a test suite in a file in TTCN-MP format.

Constraints can be added, modified and deleted between any of the above steps.


Getting Ready to Use Autolink

In order to use Autolink, an SDL Validator application has to be generated and started. In this exercise, you will use the inres system, which is found in $telelogic/sdt/examples/inres.

"Inres" is short for Initiator-Responder. The inres system is an example of a simplified communication protocol intended to give a secure transfer of information over an unsafe communication medium. It provides a one-way, connection-oriented communication service that uses sequence numbers and retransmission to ensure that messages sent from the initiator side are correctly received at the responder side.

Note:

In order to generate a validator application that behaves as stated in the exercises, you should copy all files of the inres protocol from the release to your working directory.

You also have to create two directories where MSC test steps and test cases will be stored.

  1. In your current working directory, create two subdirectories called TC (used for test cases) and TS (used for test steps).
  2. Start Telelogic Tau and open the inres system in the Organizer.
  3. Generate an inres validator and open it in the Validator UI.


Exercise 1: Basic Concepts

What You Will Learn

  • To set up value definitions
  • To create an MSC test case definition
  • To generate a test case
  • To work with constraints

Preparations

First, you should define the location of the test cases and test steps directories which you have created prior to opening the validator:

  1. Select Autolink: Test Cases Directory in the Options2 menu.
    The Directory name dialog is displayed.
  2. Double-click the TC directory.
  3. Click the OK button.
  4. Select Autolink: Test Steps Directory in the Options2 menu.
    Once again, the Directory name dialog is displayed.
  5. Choose the TS directory by first clicking the Current button and then double-clicking the TS directory.
  6. Click the OK button.

Note:

The directory settings can be saved when you leave the validator.

You should also set up proper test value definitions for the inres system:

  1. Open the TEST VALUES module by clicking on the box beside.
    A number of new command buttons appear.
  2. Click the Clear Value button in the TEST VALUES module to clear all integer test values.
    A Select dialog is displayed.
  3. Choose integer.
  4. Click the OK button.
    A Prompt dialog is displayed.
  5. Click the OK button, without typing anything in the text field.
  6. Click the Def Value button in the TEST VALUES group to define a new test value for integers.
    Another Select dialog is displayed.
  7. Choose integer.
  8. Click the OK button.
    A Prompt dialog is displayed.
  9. Type 55 as the new test value in the Value field.
  10. Click the OK button.

Creating an MSC Test Case

The first step in the test case generation process is the choice of a path. A path describes a trace through the SDL system. This trace consists of internal and external events. External events are signals sent to or from the environment.

Autolink uses system level MSCs to abstract from a path by only considering the external events. System level MSCs consist of exactly one instance axis for the SDL system and one or more instance axes for the system environment. Figure 71 shows the MSC which you are going to create in this exercise.

  1. Click the Navigator button in the EXPLORE module to start the Navigator.
    The Navigator window is displayed.
  2. Navigate through the system by double-clicking in turn on the following nodes:
    1, 1, 1, 1, 1, 1, 1, 1 (i.e. 8 times transition #1),
    3,
    1, 1, 1, 1, 1, 1, 1 (i.e. 7 times transition #1),
    10,
    1, 1, 1 (i.e. 3 times transition #1),
    2,
    1, 1, 1 (i.e. 3 times transition #1)
  3. Select MSC: Save Test Case in the Autolink1 menu to save the current path as a system level MSC.
    A Prompt dialog is displayed.
  4. Type Example1 in the Test case name field.
    The test case name is identical to the name of the generated MSC.
  5. Click the OK button.
    Autolink saves a file called Example1.mpr in the MSC test cases directory.

You have now created your first MSC test case (see Figure 71). You may start the MSC Editor and take a look at it.

Note:

You can create as many MSC test cases as you like, provided that they share the same root node.

Figure 71 : MSC Example1

It is possible to get a list of all MSC test cases (and test steps) which are currently defined:

  • Select MSC: List in the Autolink1 menu.
    A message similar to the one below should be given in the text area.
MSC test cases:
Example1.mpr

No MSC test steps found in directory '/home/tutorial/inres/TS/'.

Generating the Test Case

In the next step, an internal test case representation has to be created which is based on the MSC test case defined above.

  1. Select Test Case: Generate in the Autolink1 menu.
    A Select dialog is displayed.
  2. Select Example1.mpr.
  3. Click the OK button.
    Autolink performs a bit state exploration, which produces the following output in the text area of the Validator UI:
Autolink state space options are set.

Define-Scheduling All
Define-Transition Symbol-Sequence
Define-Symbol-Time Zero
Define-Priorities 2 1 3 2 2
Define-Channel-Queue ISAP1 On
Define-Channel-Queue MSAP2 On
Define-Max-Input-Port-Length 10

Current state is reset to root.

MSC 'Example1' loaded.

** Test case generation statistics **
No of reports: 2.
Deadlock : 1 report
MSCVerification : 1 report
Generated states: 2089.
Truncated paths: 0.
Unique system states: 790.
Size of hash table: 8000000 (1000000 bytes)
No of bits set in hash table: 1411
Collision risk: 0 %
Max depth: 49
Current depth: -1
Min state size: 388
Max state size: 524
Exploration started at: Sat Jan 29 13:39:14 2000
Exploration ended at: Sat Jan 29 13:39:15 2000
Exploration time: 000 h, 00 m, 01 s

Constraints are checked for naming conflicts...

Constraint 'cExample1' is renamed to 'cExample1_001'.
Constraint 'cExample1' is renamed to 'cExample1_002'.
Constraint 'cExample1' is renamed to and merged with 'cExample1_002'.
Constraint 'cExample1' is renamed to and merged with 'cExample1_001'.
Constraint 'cExample1' is renamed to 'cExample1_003'.
Constraint 'cExample1' is renamed to 'cExample1_004'.
Constraint 'cExample1' is renamed to 'cExample1_005'.
Constraint 'cExample1' is renamed to 'cExample1_006'.
Constraint 'cExample1' is renamed to 'cExample1_007'.
Constraint 'cExample1' is renamed to 'cExample1_008'.
Constraint 'cExample1' is renamed to 'cExample1_009'.
Constraint 'cExample1' is renamed to 'cExample1_010'.

Constraints with identical signal definitions are merged automatically...

... done.

State space options are restored.

You have now generated your first test case. This test case is kept in memory. You will save it in a TTCN test suite soon.

It is possible to get a list of all test cases which have been generated so far.

  • Select Test Case: List in the Autolink1 menu.
    The output will simply be:
Example1

You might also want to take a look at the internal test case representation before you create the TTCN test suite.

  1. Select Test Case: Print in the Autolink1 menu.
    A Select dialog is displayed.
  2. Choose Example1.
  3. Click the OK button.
    The resulting output is:
Example1

  0 ISAP1 ! ICONreq - cExample1_010
1 MSAP2 ? MDATind - cExample1_009
2 MSAP2 ! MDATreq - cExample1_008
3 ISAP1 ? ICONconf - cExample1_007
4 ISAP1 ! IDATreq - cExample1_006
5 ISAP1 ! IDISreq - cExample1_005
6 MSAP2 ? MDATind - cExample1_004
7 MSAP2 ! MDATreq - cExample1_003
8 ISAP1 ? IDISind - cExample1_001
9 P MSAP2 ? MDATind - cExample1_002
8 MSAP2 ? MDATind - cExample1_002
9 P ISAP1 ? IDISind - cExample1_001

Modifying the Constraints

During test case generation, a number of constraints have been created. These constraints are also stored in memory and can be manipulated in several ways.

Listing the Constraints

First of all, it is possible to print the list of all constraints:

  • Select Constraint: List in the Autolink2 menu.
    This should be the output in the text area:
cExample1_001 :
IDISind { }
cExample1_002 :
MDATind { mSDUType1 { id DR, num one, data 55 } }
cExample1_003 :
MDATreq { mSDUType1 { id AK, num one, data 55 } }
cExample1_004 :
MDATind { mSDUType1 { id DT, num one, data 55 } }

cExample1_005 :
IDISreq { }
cExample1_006 :
IDATreq { iSDUType1 55 }
cExample1_007 :
ICONconf { }
cExample1_008 :
MDATreq { mSDUType1 { id CC, num zero, data 55 } }
cExample1_009 :
MDATind { mSDUType1 { id CR, num zero, data 0 } }
cExample1_010 :
ICONreq { }

As you can see, 10 constraints have been created during test generation.

Adding a Constraint

Next, you can add a new constraint:

  1. Select Constraint: Define in the Autolink2 menu.
    A Prompt dialog is displayed.
  2. Type RequestCon in the Constraint name field.
  3. Click the OK button.
    A Select dialog is displayed, listing all signals in the system.
  4. Select ICONreq.
  5. Click the OK button.
    In the text area of the Validator user interface, the following message appears:
Constraints are checked for naming conflicts...

Of course, there is no naming conflict, since there does not exist another constraint with the same name.

Renaming a Constraint

You might want to assign a more reasonable name to constraint cExample1_007 containing the signal ICONconf:

  1. Select Constraint: Rename in the Autolink2 menu.
    A Select dialog is displayed, listing all constraints currently defined.
  2. Choose cExample1_007.
  3. Click the OK button.
    A Prompt dialog is displayed.
  4. Enter ConfirmCon in the New constraint name field.
  5. Click the OK button.

Parameterize a Constraint

Constraint cExample1_006 contains a signal parameter (value 55). You can define this signal parameter to be a parameter of the constraint.

  1. Select Constraint: Parameterize in the Autolink2 menu.
    A Select dialog is displayed.
  2. Select cExample1_006.
  3. Click the OK button.
    A Select dialog is displayed.
  4. Select 1 for the first signal parameter.
  5. Click the OK button.
    A Prompt dialog is displayed.
  6. Enter Data in the Formal parameter field.
  7. Click the OK button.
    The Select dialog is displayed again.
  8. This time, select 0 in order to finish parameterization.
  9. Click the OK button.

Merging Constraints

The constraints cExample1_002 and cExample1_004 only differ in the first signal parameter (which is a struct). Therefore, you might want to merge them.

  1. Select Constraint: Merge in the Autolink2 menu.
    A Select dialog is displayed, listing all currently defined constraints.
  2. Choose cExample1_002 as the first constraint.
  3. Click the OK button.
    Another Select dialog is displayed.
  4. Choose cExample1_004 as the second constraint.
    A Prompt dialog is displayed.
  5. Enter ProtDataUnit in the Formal parameter name field.
  6. Click the OK button.

Listing the Constraints - A Second Time

To see the effect of all your operations, you can list the constraints again:

  1. Select Constraint: List in the Autolink2 menu.
    This time, the following output should be displayed in the text area:
ConfirmCon :
ICONconf { }
RequestCon :
ICONreq { }
cExample1_001 :
IDISind { }
cExample1_003 :
MDATreq { mSDUType1 { id AK, num one, data 55 } }
cExample1_004(ProtDataUnit) :
MDATind { mSDUType1 ProtDataUnit }
cExample1_005 :
IDISreq { }
cExample1_006(Data) :
IDATreq { iSDUType1 Data }
cExample1_008 :
MDATreq { mSDUType1 { id CC, num zero, data 55 } }
cExample1_009 :
MDATind { mSDUType1 { id CR, num zero, data 0 } }
cExample1_010 :
ICONreq { }

In the test case, all references to the constraints have been updated appropriately:

  2. Select Test Case: Print in the Autolink1 menu.
    A Select dialog is displayed.
  3. Select Example1.
  4. Click the OK button.
    The output is:
Example1

  0 ISAP1 ! ICONreq - cExample1_010
1 MSAP2 ? MDATind - cExample1_009
2 MSAP2 ! MDATreq - cExample1_008
3 ISAP1 ? ICONconf - ConfirmCon
4 ISAP1 ! IDATreq - cExample1_006(55)
5 ISAP1 ! IDISreq - cExample1_005
6 MSAP2 ? MDATind - cExample1_004
                  ({ id DT, num one, data 55 })
7 MSAP2 ! MDATreq - cExample1_003
8 ISAP1 ? IDISind - cExample1_001
9 P MSAP2 ? MDATind - cExample1_004
                    ({ id DR, num one, data 55 })
8 MSAP2 ? MDATind - cExample1_004
                    ({ id DR, num one, data 55 })
9 P ISAP1 ? IDISind - cExample1_001

Saving the Constraints

Since all constraints are deleted if they are no longer referred to by any generated test case or if you leave the Validator, they can be saved in a file:

  1. Select Constraint: Save in the Autolink2 menu.
    A Select dialog is displayed.
  2. Click the OK button without entering any text before.
    By this you indicate that you want to store all constraints.
    The File name dialog is displayed.
  3. Type Example1.con in the File field.
  4. Click the OK button.
    The constraint definitions are saved. They can be restored by the Constraint: Load command in the Autolink2 menu but you should not do that at the moment.

Removing a Constraint

A constraint can be removed:

  1. Select Constraint: Clear in the Autolink2 menu.
    A Select dialog is displayed.
  2. Select cExample1_003.
  3. Click the OK button.
    Since this constraint is currently used in a test case, an error message is displayed in the text area:
    Error clearing constraint 'cExample1_003'.
    The constraint is currently used in a test case.
  4. Once again, select Constraint: Clear in the Autolink2 menu.
    The same Select dialog as above is displayed.
  5. Select RequestCon.
  6. Click the OK button.
    This time the specified constraint is removed, since it is not referred to in any test case.

Saving the TTCN Test Suite

In a final step, all generated test cases can be saved in a TTCN test suite. In this tutorial there is only one test case, but it is also possible to put several test cases into one test suite.

  1. Select Test Suite: Save in the Autolink1 menu.
    A Prompt dialog is displayed.
  2. Type inres in the Test suite name field.
  3. Click the OK button.
    A File name dialog is displayed.
  4. Type inres.mp in the File field.
  5. Click the OK button.
    Autolink saves the test suite in file inres.mp.
    During saving, Autolink performs a few checks to ensure the consistent use of various test suite elements. You can ignore the message about test steps, since your test case does not have any test steps at all.

You can exit the Validator now:

  1. Select Exit in the File menu.
    A Select dialog is displayed.
  2. Select Yes.
  3. Click the OK button.
    The current options are saved. You will need them in the next exercise.

Viewing the TTCN Test Suite

Up to now, you have created a TTCN test suite. This test suite is stored in MP format (machine processable) which is somewhat hard to read. Therefore you should add it to the Organizer and open it in the TTCN suite.

  1. In the Organizer, select the TTCN Test Specification chapter.
  2. Select Add Existing in the Edit menu.
    A corresponding dialog is displayed.
  3. Change the filter from "*.txt" to "*.mp" and click the Filter button.
    Provided that you are in the right directory, the file inres.mp is shown in the Files box.
  4. Select the file inres.mp in the Files section.
  5. Click the OK button.
    The file is added to the Organizer and the TTCN suite is opened with the test suite.

Completing the Test Suite

The TTCN test suite you have created so far contains information in three parts: the declarations part, the constraints part and the dynamic part.

In Windows, the test suite overview part will be generated automatically for example when you open one of the overview tables or before you print the test suite. After that, it will be kept updated.

On UNIX, you have to generate and update the overview explicitly:

  1. Select Generate Overview in the Tools menu in the Browser.
    A dialog windows appears.
  2. Click the Generate button.
    The test case index is generated.


Exercise 2: Advanced Concepts

What You Will Learn

  • To create a structured MSC test case
  • To define a simple Autolink configuration
  • To generate a structured TTCN test case by a direct translation
  • To merge new test cases with an existing test suite

Preparations

If you have closed the SDL suite or the Validator UI temporarily, perform the following steps:

  1. Open the inres system in the Organizer.
  2. Start the Validator UI.
  3. Open the inres validator again.

If you have not quit the inres validator, bring the application to its initial state now:

  • Select Reset in the Options1 menu.

Creating a Structured MSC Test Case

For a better understanding, a test case can be structured into different test steps. Typically, a test case consists of three parts:

  • The preamble comprises a sequence of test events that drives the system from the stable start state to the initial state from which the test body starts.
  • The test body comprises a sequence of test events that achieve the test purpose.
  • The postamble comprises a sequence of test events that drives the system from the state reached by the test body to a stable end state.

In this section, you will create a test case with a preamble, a test body and a postamble. This test case will be identical to the one developed in "Exercise 1: Basic Concepts" except for its structural information.

Creating the Preamble

You can define structured MSC test cases in a similar way as you did in "Exercise 1: Basic Concepts" .

  1. Click the Navigator button in the EXPLORE module to start the Navigator.
    The Navigator window is displayed.
  2. Navigate through the system by double-clicking in turn on the following nodes:
    1, 1, 1, 1, 1, 1, 1, 1 (i.e. 8 times transition #1),
    3,
    1, 1, 1 (i.e. 3 times transition #1)
    Do not close the Navigator yet.
  3. Select MSC: Save Test Step in the Autolink1 menu to save the current path as an MSC test step.
    A prompt dialog is displayed.
  4. Type Preamble in the Test step name field.
  5. Click the OK button.
    Autolink saves a file called Preamble.mpr in the MSC test steps directory.

The preamble which you have just created is shown in Figure 73.

Creating the Test Body

You should also create the body of the MSC test case:

  1. Type define-root current in the input line to set the current root.
    The following message appears in the text area:
    Root of behaviour tree set to current system state
  2. Double-click the following transitions in the Navigator window:
    1, 1, 1, 1 (i.e. 4 times transition #1),
    10,
    1, 1, 1 (i.e. 3 times transition #1).
    Again, do not close the Navigator.
  3. Select MSC: Save Test Case in the Autolink1 menu to save the path as an MSC test case.
    Make sure that you save the path as a test case, not as test step!
    A Prompt dialog is displayed.
  4. Type Example2 in the Test case name field.
  5. Click the OK button.
    Autolink saves a file called Example2.mpr in the MSC test cases directory.

Now you have defined the body of the test case. See Figure 72.

Figure 72 : The MSC Example2 - test body

Creating the Postamble

Finally, you create the postamble of the MSC.

  1. Again, type define-root current in the input line to set the root.
    The following message appears in the text area:
Root of behaviour tree set to current system state

  2. Navigate through the system by double-clicking in turn on the following nodes:
    2,
    1, 1, 1.
  3. Select MSC: Save Test Step in the Autolink1 menu.
    A Prompt dialog is displayed.
  4. Type Postamble in the Test step name field.
  5. Click the OK button.
    Autolink saves a file called Postamble.mpr in the MSC test steps directory.

You have now created the postamble of the test case, see Figure 73.

Figure 73 : Preamble and Postamble MSCs

Inserting MSC References

Before you can use MSC Example2 to generate a TTCN test case, you have to insert two global MSC references for the preamble and the postamble. To do this:

  1. Select Toggle MSC Trace in the Commands menu.
    The MSC Editor will start, showing a complete Validator Trace.
  2. Open MSC Example2.mpr stored in directory TC.
  3. Make the MSC look like Figure 74, that is:
    • Insert two global MSC references, one above the first message and one after the last message.
    • Type Preamble and Postamble (without the file extension .mpr) as reference names.

Figure 74 : Example2

  4. Save the MSC diagram as Example2.msc.
    You have now created a complete structured MSC test case with a pre- and a postamble and you are ready to generate a TTCN test case from it.

In the previous steps, you have changed the root of the behavior tree to the beginning of the postamble. Even though it is not necessary for a direct translation, you should better reset it before continuing.

  1. Switch back to the Validator UI window.
  2. Type Define-Root Original at the command line.
    The MSC Editor is started, but you do not have to bother about that. Select Toggle MSC Trace in the Commands menu to quit it.

You can list all MSC test cases and test steps currently stored on disk:

  3. Select MSC: List in the Autolink1 menu.
    The following output should appear in the text area:
MSC test cases:
Example1.mpr Example2.mpr Example2.msc

MSC test steps:
Postamble.mpr Preamble.mpr

It is also possible to remove test cases and test steps from disk. Since you do not need the temporary MSC Example2.mpr any more, you can delete it:

  1. Select MSC: Clear Test Case in the Autolink1 menu.
    A Select dialog is displayed.
  2. Select Example2.mpr.
  3. Click the OK button.
    Another Select dialog is displayed, asking you whether you really want to delete this MSC.
  4. Choose Yes.
  5. Click the OK button.

Defining an Autolink Configuration

Autolink allows to define a configuration which guides the naming and parameterization of constraints, the introduction of test suite parameters and constants and the grouping of test cases and test steps into a hierarchy of test groups. An Autolink configuration consists of a set of rules which have to be written by the user.

In this tutorial you will not learn how to write configuration rules. Instead you will use a pre-defined configuration that covers some aspects of an Autolink configuration. For a detailed descriptions of configuration rules and corresponding examples see "Translation Rules" and "Test Suite Structure Rules.

In a first step you have to create a new command file which contains the Autolink configuration:

  1. Open a text editor.
    The choice of text editor depends on the operating system of your computer.
    Create a new file called config.com.
  2. Type in the following text:
# -------------------------------
# Autolink configuration file
# for the inres protocol
# -------------------------------

Define-Autolink-Configuration

TRANSLATE "ICONreq"
CONSTRAINT NAME "Connection_Request"
END

TRANSLATE "ICONconf"
CONSTRAINT NAME "Connection_Confirmation"
END

TRANSLATE "IDATreq"
CONSTRAINT NAME "Data_Request"
PARS $1="Data"
  TESTSUITE  PARS   $1="DataValue"
END

TRANSLATE "IDISreq"
CONSTRAINT NAME "Disconnection_Request"
END

TRANSLATE "IDISind"
CONSTRAINT NAME "Disconnection_Indication"
END

TRANSLATE "MDATind" | "MDATreq"
  IF $1 == "{ id CC, *, * }" THEN
CONSTRAINT NAME "Medium_Connection_Confirmation"
END
IF $1 == "{ id AK, *, * }" THEN
CONSTRAINT NAME "Medium_Acknowledge"
END
  CONSTRAINT NAME   "c_" + $0
END

End

  3. Save the file in your current working directory.

Next, you have to load this configuration into the Validator:

  1. Select Configuration: Load in the Autolink2 menu.
    A File name dialog is displayed.
  2. Select config.com in the Files section.
  3. Click the OK button.

If an error message is displayed, you have probably made a spelling mistake in the command file. In this case, correct your file and try to reload the configuration.

Translating the MSC into TTCN

In "Generating the Test Case" , you have learned how to generate an internal test case representation based on an MSC. For that purpose, a state space exploration has been started.

However, in some cases it is not possible to simulate an MSC, e.g. if the internal processes of the SDL system are not fully specified. In these cases, you have to translate an MSC test case directly into an internal test case representation (without performing a state space exploration).

Even though it should be possible to simulate the MSC Example2.msc, you will apply a direct translation in this exercise:

  1. Select Test Case: Translate in the Autolink1 menu.
    A Select dialog is displayed.
  2. Select Example2.msc.
  3. Click the OK button.
    Autolink analyses the preamble, the test body and the postamble and generates a complete, structured test case. The following output should appear in the text area:
Current state is reset to root.

MSC 'Example2' loaded.

Constraints are checked for naming conflicts...

Constraint 'c_MDATind' is renamed to 'c_MDATind_001'.
Constraint 'c_MDATind' is renamed to 'c_MDATind_002'.
Constraint 'c_MDATind' is renamed to 'c_MDATind_003'.

Constraints with identical signal definitions are merged automatically...

... done.

Take a look at the internal test case representation to see the difference with respect to test case Example1:

  1. Select Test Case: Print in the Autolink1 menu.
    A Select dialog is displayed.
  2. Choose Example2.
  3. Click the OK button.
  4. The output is:
Example2

  0 IN Preamble
1 ISAP1 ! ICONreq - Connection_Request
2 MSAP2 ? MDATind - c_MDATind_003
3 MSAP2 ! MDATreq -
              Medium_Connection_Confirmation
4 ISAP1 ? ICONconf -
               Connection_Confirmation
5 OUT Preamble
6 ISAP1 ! IDATreq -                  Data_Request(DataValue)
7 (P) MSAP2 ? MDATind - c_MDATind_002
8 MSAP2 ! MDATreq - Medium_Acknowledge
9 IN Postamble
10 ISAP1 ! IDISreq -
                     Disconnection_Request
11 ISAP1 ? IDISind -
                      Disconnection_Indication
12 P MSAP2 ? MDATind - c_MDATind_001
13 OUT Postamble
11 MSAP2 ? MDATind - c_MDATind_001
12 P ISAP1 ? IDISind -
                       Disconnection_Indication
13 OUT Postamble

Also take a look at the constraints to see what the translation rules in your configuration file have affected:
  5. Select Constraint: List in the Autolink2 menu.
    The following output will appear in the text area:
Connection_Confirmation :
ICONconf { }
Connection_Request :
ICONreq { }
Data_Request(Data) :
IDATreq { iSDUType1 Data }
Disconnection_Indication :
IDISind { }
Disconnection_Request :
IDISreq { }
Medium_Acknowledge :
MDATreq { mSDUType1 { id AK, num one, data 55 } }
Medium_Connection_Confirmation :
MDATreq { mSDUType1 { id CC, num zero, data 55 } }
c_MDATind_001 :
MDATind { mSDUType1 { id DR, num one, data 55 } }
c_MDATind_002 :
MDATind { mSDUType1 { id DT, num one, data 55 } }
c_MDATind_003 :
MDATind { mSDUType1 { id CR, num zero, data 0 } }

Saving the TTCN Test Suite

When a TTCN test suite is created, test steps can be stored in different formats. By default, test steps are put into the test step library. However, you might want to save them locally, i.e. attached to their test cases:

  1. Select Autolink: Test Steps Format in the Options2 menu.
    A Select dialog is displayed.
  2. Select Local.
  3. Click the OK button.

Now, you are ready to save the test suite:

  1. Select Test Suite: Save in the Autolink1 menu.
    A Prompt dialog is displayed.
  2. Type inres2_local in the Test suite name field.
  3. Click the OK button.
    A File name dialog is displayed.
  4. Type inres2_local.mp in the File field.
  5. Click the OK button.
    Autolink saves the test suite in file inres2_local.mp.

You may want to save the test suite in different formats. To do this:

  1. Select Autolink: Test Steps Format in the Options2 menu.
    A Select dialog is displayed.
  2. Select Global or Inline.
  3. Click the OK button.
  4. Save the test suite as above. You can save the current test suite as often as you like.

Merging With the Old Test Suite

It is possible to merge the new TTCN test case (with its constraints) with an existing test suite.

  1. Make sure that the inres test suite you created in the first part of this tutorial is opened in the TTCN suite. This test suite contains test case Example1.
  2. On UNIX, select Autolink Merge from the SDT Link menu in the Browser.
    In Windows, select Autolink Merge from the File menu.
  3. In the dialog that is opened, select inres2_local.mp.
  4. Click Merge (UNIX) or OK (Windows).
    The test case and the constraints from the inres2_local.mp file will now be merged into the old test suite.

There are more possibilities to merge test cases: Autolink also provides commands to combine separately generated test cases within the Validator. For a detailed description see "Computing Test Cases.


Exercise 3: Test Generation with Tree Walk

What You Will Learn

  • To create a large number of MSC test cases automatically
  • To save and load generated test cases in Autolink
  • To distribute test case generation

Preparations

If you have closed the SDL suite or the Validator UI temporarily, perform the following steps:

  1. Open the inres system in the Organizer.
  2. Start the Validator UI.
  3. Open the inres validator again.

If you have not quit the inres validator, bring the application to its initial state now:

  4. Select Reset in the Options1 menu.

Creating MSC Test Cases Automatically

In the previous exercises, you had to specify your MSC test cases manually. Creating test cases by hand gives you full control over what is tested.

However, you might not be interested in defining tests for particular aspects of your SDL system. Instead, you only wish to create a large number of test cases randomly which cover most symbols of the SDL system.

In this case, you can use the Tree Walk algorithm provided by Autolink to generate test cases automatically.

In the first step, a number of TreeWalk reports have to be computed:

  1. Click the Tree Walk button in the EXPLORE module.
    A Prompt dialog is displayed.
  2. Enter the value 10.
    This is the maximum number of minutes given to Autolink for computing reports. In fact, the state space exploration is much faster for simple protocols such as Inres.
    Another Prompt dialog is displayed.
  3. Enter the value 100.
    This is the percentage of symbol coverage that you want to reach when executing your test cases.
    A message similar to the one below will appear in the text area:
Tree Walk will stop after 10 minutes or after reaching 100% symbol coverage.
Reports and symbol coverage table cleared.
States: 2109. Reports: 3. Tree walk reports: 0 (+31). Coverage: 100.00%. Time: 000:00:01

Target symbol coverage is reached.
Tree Walk is stopped.
Test report #1 of length 7 added.
Test report #2 of length 8 added.
Test report #3 of length 12 added.
Test report #4 of length 16 added.
Test report #5 of length 16 added.
Test report #6 of length 20 added.
Test report #7 of length 22 added.
Test report #8 of length 30 added.
Test report #9 of length 32 added.

The output above states that nine reports have been generated. When traversing their corresponding paths, a total symbol coverage of 100 percent is reached. The Tree Walk command stops immediately when it reaches the targeted symbol coverage.

Since Autolink requires MSC test cases as input, you have to convert the TreeWalk reports into MSCs:

  1. Select MSC: Save Reports in the Autolink1 menu.
    A Select dialog is displayed.
  2. Select TreeWalk in order to save all TreeWalk reports.
  3. Click the OK button.
    A Prompt dialog is displayed.
  4. Enter Tutorial as test case name prefix.
    Autolink saves all TreeWalk reports as system level MSCs in distinct files in the test cases directory:
MSC test case is saved in file '/home/tutorial/inres/TC/Tutorial_Tree_00001.mpr'.
MSC test case is saved in file '/home/tutorial/inres/TC/Tutorial_Tree_00002.mpr'.
MSC test case is saved in file
...
MSC test case is saved in file
'/home/tutorial/inres/TC/Tutorial_Tree_00009.mpr'.

Generating the Test Cases

In the previous exercises you have learned how to generate internal test case representations from MSCs. If you want more than one test case, you can either compute all test cases in the test cases directory at once - by a single command - or compute one test case after another.

For large SDL systems, test generation may take some time. In this case, it is advantageous not to compute all test cases in a single validator session. Instead, each test case (or a small number of test cases) should be computed separately, preferably in parallel on different machines.

To enable distributed test generation, Autolink allows to store internal test case representations on disk. After all test cases have been computed, their internal representations can be reloaded from disk and saved in a single test suite. While loading the test cases, Autolink checks them for consistency and merges identical constraints.

Generating and Saving a Single Test Case

  1. Select Reset in the Options1 menu.
    All options are reset and all generated test cases and reports are cleared.
  2. Select Test case: Generate in the Autolink1 menu.
  3. A Select dialog is displayed.
  4. Select Tutorial_Tree_00007.mpr.
  5. Click the OK button.
  6. Select Test case: Save in the Autolink1 menu.
    A Select dialog is displayed.
  7. Select Tutorial_Tree_00007.
  8. Click the OK button.
    A File name dialog is displayed.
  9. Select the TC directory by double-clicking.
  10. Type Tutorial_Tree_00007.gen in the File field.
  11. Click the OK button.
    The generated test case is stored on disk.

Repeat steps 1 to 11 for other TreeWalk test cases.

Saving the Test Suite

Once you have created all test cases and saved them in files, you can combine them and create a test suite.

  1. Select Reset in the Options1 menu.
  2. Select Test case: Load in the Autolink1 menu.
    A File name dialog is displayed.
  3. Select file Tutorial_Tree_00007.gen in the Files section.
  4. Click the OK button.
    The generated test case is loaded and identical constraints are merged (if there are identical constraints).
  5. Repeat steps 2 to 4 for all other test cases.
  6. Select Test suite: Save in the Autolink1 menu.
    A Prompt dialog is displayed.
  7. Type TreeWalk in the Test suite name field.
  8. Click the OK button.
    A File name dialog is displayed.
  9. Type TreeWalk.mp the File field.
  10. Click the OK button.
    Autolink saves the test suite file TreeWalk.mp.
    Now you may exit the Validator:
  11. Select Exit in the File menu.

In order to take a look at the TTCN test suite, add the test suite to the Organizer just like you did in the first and second example above.


So Far...

You should have learned how to create structured system level MSCs, and how to generate TTCN test cases from those MSCs. Especially you have become acquainted with two ways of producing TTCN test cases: Test generation by state space search and test generation by a direct translation. While doing this, you have discovered many of the commands in the Autolink menus of the Validator. In addition, you should also know how to view the test suite in the TTCN suite, how to generate the test suite overview and how to merge new test cases and constraints into an existing test suite in the TTCN suite.


Telelogic Tau 4.4

User's Manual

Telelogic
http://www.telelogic.com


1 User Interface and Basic Operations

This chapter describes the general graphical concepts that are used throughout the user interfaces of the Telelogic Tau tools. It also describes some common menu choices. This information will not be repeated in other chapters of the User's Manual.

You should have a basic understanding of the Telelogic Tau tools concepts and tool family before you read this chapter. Such information can be found in:

  • Introduction to the SDL Suite
  • Introduction to the TTCN Suite (on UNIX)
  • Introduction to the TTCN Suite (in Windows)


Graphical Environments and Style Guides

The Telelogic Tau tools family is designed to be available on workstations running UNIX and on PCs running Windows. Since the majority of the Telelogic Tau tools are graphical, it is assumed that the computer you are to run the Telelogic Tau tools on has the required graphical support.

Telelogic supports the following graphical environments:

  • On UNIX workstations, the X Windows system, managed by the Motif window manager. The versions currently supported are X11 R5 and Motif 1.2.
  • On PCs, the Microsoft Windows system. Telelogic Tau supports Windows 95, Windows 98, Windows NT 4.0 and Windows 2000.

Throughout the Telelogic Tau manuals, it is assumed that you are familiar with the graphical environment that is currently used. Otherwise, we recommend you to read the literature that describes that graphical environment. See for instance "References" .

The SDL suite for Windows is fully compatible with the SDL suite on UNIX workstations, with respect to functionality and storage formats. However, since they are implemented on different graphical environments, there may be slight differences in the appearance of each tool. Also, we have tried to adopt the respective style guide for each environment as long as feasible, but have been forced to compromise in order to provide a uniform user interface between the UNIX workstation and PC environments.


Constraints

The constraints that are imposed on the Telelogic Tau tools by the graphical environment are identified in "Microsoft Windows System Factors" , "X Window System Factors (UNIX only)" and "OSF/Motif Factors (UNIX only).


Application Windows

All the Telelogic Tau tools have a main window with a common general appearance. The tools may also have sub windows that depend on the main window. Apart from these, there are also dialog windows, see "Dialog Windows" .

In the TTCN suite in Windows, the windows will be displayed in the working area of the TTCN suite desktop.

Main Windows

A general main window of a Telelogic Tau tool in Windows and on UNIX, as well as the TTCN suite desktop in Windows, is depicted and explained below:

Figure 1 : A Telelogic Tau main window (in Windows)

Figure 2 : A Telelogic Tau tool main window (on UNIX)

Figure 3 : The TTCN suite desktop (in Windows)

Title Bar

The title bar may identify the tool family, the tool and the opened document. In some tools, an asterisk signifies that the document is not saved since the last change.

Menu Bar

The menu bar contains pull-down menus. The menu choices operate either on the whole document or file that is opened in the tool, or on any selected object(s). More information on menus and menu choices can be found in "General Menus" and "General Menu Choices" .

You can "preview" the functionality of a menu choice by pointing to it. In the SDL suite on UNIX you also have to press the mouse button. An explanation will appear in the status bar.

If a menu or menu choice is dimmed, it is not appropriate or meaningful in the current situation, or the associated tool license is temporarily lost.

If a menu or menu choice is hidden, you do not have a license for the associated tool, or the tool has a long/short menu concept which allows hiding of menu choices.

Tool Bar

Most operations that the quick-buttons in the tool bar provide, have an exactly corresponding menu choice, but some quick-buttons have a slightly different functionality compared to their corresponding menu choice. See also "General Quick-Buttons" .

You can "preview" the functionality of a quick button by pointing to it. In the TTCN suite on UNIX you also have to press the mouse button. An explanation will appear in the status bar, and as a tool tip just below the button (not available in the TTCN suite on UNIX).

In the TTCN suite in Windows, the tool bars are dockable on all sides of the desktop.

Drawing Area

The information a tool handles is displayed and may possibly be edited in the drawing area. The drawing area may also give access to popup menus. See also "The Drawing Area" .

Working Area (only in the TTCN suite in Windows)

The working area of the desktop will display the TTCN suite windows that you open. For example, when you open a TTCN document, the Browser window will be displayed in the working area.

Tool Frame (only in the SDL suite on UNIX)

A tool frame, with a unique color for each tool, surrounds the drawing areas in the SDL suite. This makes it easier for you to identify a tool, without the need to see the whole drawing area or the title bar.

Status Bar

The status bar displays information about menu choices and quick-buttons, the progress or result of an invoked operation, and the name of a selected object or additional information about an object.

Sub Windows

A sub window of a Telelogic Tau tool is a window that depends on the main window of the tool. A sub window is opened either automatically when the main window is opened or as a result of user interaction with the main window. All sub windows are automatically closed when the main window exits. However, to close a sub window does not affect the main window.

The TTCN Suite Logs

Some TTCN suite tools, for example the Analyzer, produce logs.

On UNIX, the relevant tool dialog allows the log device to be set to Screen, File or None. If set to Screen, the log will be displayed in its own log window. If set to File, a directory dialog will be displayed where you can specify a file to save the log in.

In Windows, the Log Manager will display the logs, and tabs are used for viewing different logs. The contents of the window can be copied and saved. For more information, see "Viewing Log Information" .

Zooming a Window

You can change the scale of the drawing area of an SDL suite window by selecting Set Scale in the View menu or by using quick buttons for zooming in and out. The scale is normally between 20% and 800%.


General Menus

The following menus are generally available in a menu bar:

  • The File menu contains menu choices related to files, documents and the whole drawing area, as well as the tool/window itself. Examples: New, Open, Save, Print and Exit.
  • The Edit menu contains menu choices concerning editing of the current document. It may also contain menu choices for changing objects. Examples: Undo, Cut, Copy, Paste, Add and Edit.
  • The View menu contains menu choices that changes the appearance of the window and the information in the drawing area. Examples: Expand, Collapse, Window Options and Set Scale.
  • The Tools menu contains menu choices for starting tools and utilities, and opening or raising other windows. Examples: Search, Show Organizer and Show <window name>.
  • The Help menu contains menu choices for supporting you with help and other useful information.


General Menu Choices

Some common menu choices in Telelogic Tau are described below and the descriptions will not be repeated elsewhere.

File Menu

The most common menu choices in the File menu of the Telelogic Tau tools are only described in this section. If a tool provides additional menu choices in the File menu, they will be described in the corresponding chapter. If a common menu choice has a different functionality, it will also be described in its corresponding chapter but minor differences will be mentioned below.

New

When you select this menu choice, a new document, diagram or file will be created and displayed. In some tools, it will be given a default file name which you later may change, and in some tools you have to specify the name and the type of document/diagram in a dialog before it will be displayed.

  • For information on adding new pages to SDL diagrams, see "Add" .
  • In the Text Editor, you have to select in a dialog whether to create a new file, copy an existing file, or to copy a template file. The directory for template files is defined by the preference TE*TextTemplateDirectory. For more information, see "Text Editor Preferences" .
  • When you create a new link file in the Link Manager, the current endpoint and link information will be deleted. You will be warned if a link file is already opened.

Open

When you select this menu choice, a file selection dialog will be issued, in which you select what file to open. For more information, see "File Selection Dialog" .

A default file filter, which depends on the tool, will be used. It corresponds to the default file name extensions applied when a document or diagram is saved (see "Save" ). The tools and the filters are listed in the table below.

  • When you open a new SDL simulator, a currently running simulator will be stopped after user confirmation. The Watch window will be updated and the text area will be cleared from previously executed commands.
  • When you open a new link file in the Link Manager, a currently opened and modified file has to be saved first.

Tool
Default File Filter
SDL Target Tester

 *.sym
SDL Coverage Viewer

 *.cov
HMSC Editor

 *.mrm
Index Viewer

 *.xrf
The TTCN suite in Windows

 *.itex
Link Manager

 *.sli
MSC Editor

 *.m??
OM Editor

 *.som
Organizer Log

 *.log
SDL Editor

 *.s??
SDL Simulator
*_sm*.exe (in Windows)
*.sct (on UNIX)
SDL Validator
*_vl*.exe (in Windows)
*.val (on UNIX)
State Chart Editor

 *.ssc
Text Editor

 *.txt

Note:

No specific file name extension on diagrams are imposed. If other file name extensions than the ones suggested have been used when saving diagrams, a different filter than the given must be applied.

Note: The MSC Editor and instance oriented MSC/PR

The MSC Editor supports reading MSC/GR (default file name extension is .msc) and MSC/PR (default file name extension is .mpr). However, the MSC Editor cannot read MSC/PR expressed in instance-oriented form. Only the event-oriented form can be read by the tool. See the Z.120 recommendation for more information on these two alternative formats.

Note: Opening *.cif files in SDL editor

If a *.cif file is opened in an SDL editor, then the information from the SDL/CIF file is presented in a new, dirty and unsaved diagram buffer.

Save

When you select this menu choice, the current information in the document/diagram/window will be saved in a file.

When you save a document/diagram for the first time, a file selection dialog is opened. A default file name and file name extension is suggested. You have to specify where the file is to be saved and you may also change the file name and extension. If you try to overwrite an existing file, you will be warned.

Note:

If you keep the file name extensions for different documents/diagrams listed below, it will be easier to locate the files. It is also impossible to add an existing file to the Organizer unless it has the default extension.

Document/Diagram Type or Storage Format
Default File or Extension
Command definitions (SDL Simulator UI)
.cmds
Coverage
.cov
HMSC
.mrm
Link file
.sli
MSC

 .msc
Object Model
.som
Organizer Log
.log
SDL System

 .ssy
SDL Block

 .sbk
SDL Substructure

 .ssu
SDL Service

 .ssv
SDL Process

 .spr
SDL Procedure

 .spd
SDL System Type

 .sst
SDL Block Type

 .sbt
SDL Service Type

 .svt
SDL Process Type

 .spt
SDL Macro Definition

 .smc
SDL Operator

 .sop
SDL Package

 .sun
SDL Overview

 .sov
State Chart
.ssc
State Overview
.ins
Text
.txt
TTCN test suite (in Windows)
.itex
.mp
.imp
Variable definitions (SDL Simulator UI)
.vars

Save Document

The Save Document menu choice only exists in the TTCN Browser and Table Editor on UNIX. When you select it, the TTCN document will be saved. See also "Save" .

Save As

Select this menu choice to save the current document/diagram in a new file. A default file name and file name extension will be suggested, see "Save" . If you change the file name and extension and try to overwrite an existing file, you will be warned.

If the document/diagram was already connected in the Organizer, it will be reconnected to the newly created file. This does not happen in the following cases:

  • Save As Text. By specifying *.txt as the file name extension for graphical diagrams, the diagram text will be saved in the specified file.
  • Save As CIF. By specifying *.cif as the file name extension for SDL diagrams, the diagram will be saved in SDL/CIF format, a standardized textual format that includes layout information. When this extension is used in the SDL editor and the Save As dialog is closed, you will be asked to select diagram pages to include in the generated file. As default, all pages are selected. A *.cif file can be opened in the SDL editor. When doing so, the information from the *.cif file is presented as a new, dirty and unsaved diagram buffer.

Note:

If you keep the file name extensions for different documents/diagrams listed above, it will be easier to locate the files. It is also impossible to add an existing file to the Organizer unless it has the default extension. In the TTCN suite in Windows, you can only open test suites that have the extension .itex, .mp or .imp.

  • In the TTCN suite on UNIX, there are three alternatives for compression when you save as TTCN-GR: None, Gzip and Compress. None gives maximum compatibility. Gzip is preferred over Compress, both for portability and performance.

Save a Copy As

This menu choice is available in the SDL suite editors. It saves a copy of the current document/diagram in a new file.

Note:

The window will hold the original file, not the newly saved copy. The document/diagram remains connected to the old file and the Organizer's structure is left unaffected by the operation.

The name of the new file is to be specified in a file selection dialog and a default file name and extension will be suggested; see "Save" . If you try to overwrite an existing file, you will be warned.

Save All

This menu choice is available in the SDL suite editors. It saves all modified documents/diagrams that are opened. Except for that, it works as described in "Save" .

Print

The different Print dialogs and how to print is described in 5 Printing Documents and Diagrams.

Close

When you select this menu choice, the current document/diagram (or in some cases the window) will be closed. In most documents, you will not have to confirm the closing.

  • In the TTCN suite, when you close the last open Browser on a document, you will be asked for confirmation if it has not been saved.
  • When you close the Link Manager window, the Link Manager will still be active in the background but the user interface will not be available.
  • In the TTCN-SDL Co-simulator Editor on UNIX, the window is closed, but current document is not closed until the associated setup is closed.
  • In the SimUI's Command window, the commands currently displayed will be saved and shown again when the window is opened again. This is also valid for the variables in the Watch window.

Close Diagram

This menu choice is available in the SDL suite editors. When you select it, the current diagram will be closed. If changes in the diagram have not been saved, a dialog will be issued where you can select to save or not before closing.

If the closed diagram was the last open diagram, the editor will exit. If there are more editor windows open, the window will be closed. If there is only one editor window, but more diagrams open, another diagram will be displayed in the window.

Revert Diagram

This menu choice is available in the SDL suite editors. When you select it, the current diagram will be re-loaded from the file system. This operation is useful if the file has changed in any way in the file system.

Exit

When you select this menu choice, the current tool will exit. If a document/diagram has been changed since last save, a dialog will be issued where you may select to save it, not save it or - where applicable - save all opened documents/diagrams or quit without saving anything.

  • In the SDL Simulator, you will be asked to save unsaved changes to the SimUI's definition files. See "Definition Files" .

Tools Menu

A Tools menu is available in most Telelogic Tau tools. It contains various menu choices, but the following is included in almost all Tools menus:

Show Organizer

This menu choice raises the parent Organizer main window, that is from where the tool was started.

Help Menu

A Help menu is available in most main and sub windows of the Telelogic Tau tools. However, the menu choices in this menu are not the same in each tool or on each platform, but they work in the same way: When you select a menu choice in the Help menu, a help viewer will be opened with the corresponding help topic.

The following Help menu choices, that may need an explanation, are described below:

  • About <Tool>
  • Help Desk
  • Index
  • Latest News
  • License Information
  • License Info
  • New Features
  • On Field
  • On Shortcuts
  • On Window
  • Search
  • Telelogic Home Page

About <Tool>

Opens the About message box for the tool that the menu choice was invoked from, which gives information on the current tool version, copyright, etc.

Help Desk

Opens the Web browser with a page on the World Wide Web from Telelogic's Help Desk (http://www.telelogic.com/usersupp/usersupp.asp). This menu choice is only available in the Organizer.

Index

Opens the help viewer with an index of all entries in the Telelogic Tau documentation. This menu choice is only available in the Organizer.

Latest News

Opens the help viewer with a "readme" file, containing late information about the release.

License Information

Opens a dialog with license information for all tools in Telelogic Tau. For more information on this dialog, see "License Information" . This menu choice is available in the Organizer.

License Info

On UNIX, this menu choice opens a dialog with additional license information on the TTCN suite tools. For more information, see "License Info" . In Windows, the dialog lists the Telelogic Tau licenses currently in use as well as the number of licenses available for each tool.

New Features

Opens the help viewer with information about new and changed functionality.

On Field

This menu choice is available in the TTCN Table Editor on UNIX. It displays the TTCN BNF syntax applicable for the relevant field.

On Shortcuts

Opens the help viewer with information about various user interface shortcuts that can be used within the Organizer tool.

On Window

Opens a text describing the TTCN suite tool that the menu choice was invoked from. This menu choice is only available in the TTCN suite on UNIX.

Search

Starts a textual search across all help files. This menu choice is available in the Organizer and all the SDL suite tools.

Telelogic Home Page

Opens the web browser with Telelogic's home page on the World Wide Web (http://www.telelogic.com). This menu choice is only available in the Organizer.


Defining Menus in the SDL Suite

The graphical the SDL suite tools allow you to define additional menus and menu items that execute external commands or send PostMaster messages. Separate user-defined menus can be defined and added to each graphical tool. However, the pre-defined menus in each tool can not be removed or changed.

User-defined menus are described by menu definition files that are read by the tools when they start up.

It is sometimes more useful to add user-defined menus to the tools after they have been started; this can be accomplished if you use the Telelogic Public Interface. For more information see "Menu Manipulation Services" .

Note:

The fact that a set of menus have been defined in a menu definition file, does not prevent using the public interface services to add additional menus, or even to modify the menus that were defined by the menu definition file.

Tools and Menu Definition File Names

Menu definition files must have fixed names that indicate which tool the menus are intended for.

The following tools allow addition of user-defined menus, and also offer the possibility of letting the menu commands access the internal state information of the tool. This is accomplished if you use format codes that are documented separately for each tool in the Public Interface.

Tool
Menu definition file name
Organizer

 org-menus.ini
MSC Editor

 msce-menus.ini
SDL Editor

 sdle-menus.ini
OM/SC/HMSC Editor

 ome-menus.ini
Text Editor

 te-menus.ini

The following tools allow addition of user-defined menus, but do not offer the possibility of accessing the internal state of the tool.

Tool
Menu definition file name
Preference Manager

 pref-menus.ini
Type Viewer

 typ-menus.ini
Coverage Viewer

 cover-menus.ini
Index Viewer

 xref-menus.ini
Tree Viewer

 tree-menus.ini
Simulator/Validator UI 1

 simui-menus.ini
1

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

Menu Definition File Location

On start-up, each tool that supports menu-definition files will search for a menu definition file with the given pre-defined name in up to three locations:

  1. First, the directory from where the SDL suite was started is searched. If a file with the expected name is found, the tool will attempt to read it and install the menus described therein.
  2. Second, the directory named in the HOME environment variable will be searched. If a file with the expected name is found, it will be used.
  3. Last, the directory where the SDL suite is installed will be searched (on UNIX, $telelogic/, and in Windows the top installation directory, by default C:\Telelogic\SDL_TTCN_Suite4.4).

If no file is found, no user-defined menus will be added on start-up.

Format of Menu Definition Files

A menu definition file is a line-oriented text file separated into sections by lines containing special section markers. Each section contains lines formatted in the same way, containing an option/value pair. Each section describes either a menu or a menu item.

The first line of a menu definition file is a format tag that identifies the file as menu definition file:

SDT-DYNAMICMENUS-3.6

Each section is started by adding a line with a section name between brackets "[ ]". Valid sections in a menu definition file are:

[MENU]
[MENUITEM]
[MENUEND]

[MENU] Section

The menu section starts a new menu. Subsequent [MENUITEM] sections will add a menu item to this menu until a [MENUEND] section is encountered. A [MENU] section should be the first line after the initial tag or follow directly after a [MENUEND] section.

After the [MENU] section tag follows the option below, using the syntax:

Name=NameOfMenu

Option
Explanation/Value

 Name
A string that contains the name of the menu. The name is presented in the tool's menu bar. The ampersand `&' character may be placed just in front of a letter to indicate that this letter will be underlined in the menu name and thus function as a keyboard shortcut for menu traversal. Make sure that the letter is not used as a shortcut in any other menu in the menu bar, or it may not be possible to open the menu with the keyboard.

[MENUITEM] Section

A [MENUITEM] section must occur between a [MENU] and a [MENUEND] section.

Following the [MENUITEM] section tag is a number of options and their values, using the syntax:

Option=Value

This section 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 exact interpretation of two of these options (ProprietaryKey and AttributeKey, described below) will depend on which tool the menu will be installed in. In particular, the ProprietaryKey option will only have significance in the Organizer and the graphical editors. The AttributeKey option will only have significance in the graphical editors. If not used these options should be set to 0.

For tools supporting access to internal state information, format codes can be used in the command string or as message parameter, providing additional context-sensitive information.

For more information on options and format codes, see "Add Item to Menu" .

Option
Explanation/Value

 ItemName
A string that contains the menu item text that appears in the menu item. Ampersand syntax is supported, as for menu names. Make sure that different letters are selected for each menu item in the menu; otherwise keyboard activation of the menu item may not work.

 Separator
A boolean value (0 or 1) that indicates whether a separator (a thin line) should precede the menu item in the menu.

 StatusbarText
A string that should be displayed in the tool's status bar while the menu item is selected to hint you about the function of the menu choice.

 ProprietaryKey
An integer whose interpretation depends on the tool; the Organizer interprets this parameter as lastAction, and the graphical editors interpret it as ProprietaryKey. For more information, see "lastAction" and "ProprietaryKey" .
For the Organizer, you can use either an integer or a symbolic string as the value.
If not used, simply set to 0.

 AttributeKey
An integer whose interpretation depends on the tool; the graphical editors interpret this parameter as AttributeKey. For more information, see "AttributeKey" .
If not used, simply set to 0.

 Scope
An enumerated value that indicates when the menu item should be dimmed. For the valid values, see "scope" . You can use either an integer or a symbolic string as the value.
If not used, simply set to 0.

 ConfirmText
A text string that contains a dialog box text. If not empty, this will issue a two button dialog with OK and Cancel buttons and an editable text field containing the command to be performed. You can alter the command text before pressing OK.

 ActionInterpretation
An integer value indicating the desired action when a menu item is activated:
PM_MESSAGE (0) - send PostMaster message
OS_COMMAND (1) - execute OS command

 BlockCommand
Only significant if Action is set to 1:
A boolean value (0 or 1) indicating whether the Organizer should wait for the execution of the command to complete (1), or allow you to perform other operations while the command executes (0).

 FormattedCommand
Only significant if Action is set to 1:
The OS command to perform. Some tools evaluate specific context sensitive format codes.

 MessageNumber
Only significant if Action is set to 0:
Indicates the number of the PostMaster message to send.

 FormattedMessage
Only significant if Action is set to 0:
The parameters to the PostMaster message. Some tools evaluate specific context sensitive format codes.

[MENUEND] Section

The [MENUEND] section indicates that a menu definition has come to an end and that no more [MENUITEM] sections should appear until a new [MENU] section is encountered. This section has no options.

Example of a Menu Definition File

An example of a typical menu-definition file could be:

SDT-DYNAMICMENUS-3.6
[MENU]
Name=&RCS
[MENUITEM]
ItemName=Check &Out
Separator=0
StatusbarText=Check out the selected object
ProprietaryKey=1
AttributeKey=0
Scope=SELECTED_OBJECT_NOT_IN_EDITOR
ConfirmText=
ActionInterpretation=OS_COMMAND
BlockCommand=1
FormattedCommand=co %f
[MENUEND]


General Quick-Buttons

If you hear a beep when you click a quick-button, then the operation is currently not available.

The following quick-buttons can be considered as standard buttons that are available in many Telelogic Tau tools:

Back
The same as Back in the Diagrams menu.

Forward
The same as Forward in the Diagrams menu.

Open
The same as Open in the File menu.

Save
The same as Save in the File menu.

Print
The same as Print in the File menu.

Search
The same as Search in the Tools menu.

Search Again
The same as Search Again in the Tools menu.

Show Organizer
Raises the parent Organizer window, from where the tool was started.
In a sub window to a tool, this button raises the main window of the tool.

Decrease Scale
Decrease the scale of the drawing area by 20%.

Increase Scale
Increase the scale of the drawing area by 20%.

Help
The same as On <Tool> in the Help menu.


The Drawing Area

Popup Menus

You invoke a popup menu with the right mouse button. A menu choice in a popup menu generally have the same name and work in the same way as a corresponding menu choice in the menu bar.

There are two types of popup menus: context sensitive popup menus and the background popup menu.

Context Sensitive Popup Menus

Objects visible in the drawing area may have associated popup menus, whose contents may vary with the type of the object.

In the SDL suite, a context sensitive popup menu can be displayed in two slightly different ways:

  • By a right-click directly on a visible object.
    The current selection also changes with this operation, i.e. the object pointed at becomes selected and replaces any previous selection.
  • By a right-click on the background, outside any object, when there exists a current selection.
    In this case, the popup menu applies to the selected object(s) and the selection does not change.

In the TTCN suite, the popup menu always applies to the object the mouse pointer is placed on, but the current selection does not change. If you right-click on the background of the drawing area, outside of any visible object, the background popup menu is displayed, regardless of any current selection.

The Background Popup Menu

In the SDL suite, the background popup menu is displayed if you right-click on the drawing area background, and there is no current selection in the drawing area. This popup menu contains some of the most important and/or commonly performed menu choices from the menu bar. The popup menu choices operate on the whole file, document or drawing area, in the same way as the corresponding menu choices from the menu bar do.

In the TTCN suite, the background popup menu is always displayed if you right-click on the drawing area background, regardless of any selected objects.

List and Tree Structures

Many Telelogic Tau tools can present a hierarchical structure in two ways; as a list structure and as a tree structure. The example below is from the Organizer.

Figure 4 : List and tree structures

It is possible to switch between the two structures if you select an Option menu choice on the View menu. It is also possible to collapse and expand nodes in a hierarchical structure with the Expand and Collapse commands in the View menu. A collapsed node is indicated by a small triangle below the node:

Figure 5 : Collapsed nodes in list structure

Selections and Input Focus in the TTCN Suite (on UNIX)

In the TTCN suite on UNIX there is a difference between selection and input focus. Selection is a marked item or text string. You select items with the left mouse button. The input focus is set when you point to an item and click with the middle mouse button. The input focus is indicated by a rectangular border surrounding the relevant item.

Figure 6 : Selection and input focus in the TTCN suite on UNIX


Dialog Windows

There are two types of dialogs, modeless and modal. A modeless dialog does not prevent you from using other parts of the application while the dialog is visible. A modal dialog does prevent this, that is, the dialog must be dealt with before any work can continue.

Modeless Dialogs

A modeless dialog can be considered as an extension to the main window. It contains an Apply button which executes the functionality of the dialog but does not close it. The button is often renamed to indicate the functionality, for example Search. The Close button closes the dialog but does not apply any functionality.

Note:

There is no button with the functionality of an OK button, i.e. execute the functionality and close down the dialog.

Modal Dialogs

A modal dialog is used for operations that must be confirmed or that affect the view or the information used in the tool. A typical example is an Open dialog. The OK button in a modal dialog both executes the functionality and closes the dialog. The Cancel button closes the dialog but the settings you may have changed in the dialog are ignored.

File Name Completion

Wherever you are supposed to input a file or directory name as text in a text field in a dialog, you can take advantage of file name completion. To do this, you type the beginning of an absolute file name or a directory and then press <Space>. This will add characters at the end of the text field. If there are several matches, the initial characters of the matching names will be added. Then you have to press <Space> again to get the alternatives one by one. And after the final alternative, you will get a space character.

File name completion is not provided in the TTCN suite.

Example 1 : File name completion

Suppose you have the files /home/lat/hello.txt and /home/lat/henderson.txt.

  1. Type /home/l, and then press <Space>.
    The result will be /home/lat/.
  2. Then type an additional h, and then press <Space> again.
    The result will be /home/lat/he.
  3. Press <Space> again.
    The result will be /home/lat/hello.txt.
  4. Press <Space> again.
    The result will be /home/lat/henderson.txt.
  5. Press <Space> again.
    The result will be /home/lat/he (with a space character at the end).

Folder Button

When the name of a file or directory is to be specified in a dialog, a combination of a text field and a folder button is often used. You can type the name directly in the text field, or press the folder button to open a file or directory selection dialog (see the following subsections).

Figure 7 : Folder buttons for selecting files and directories (Windows and UNIX)

File Selection Dialog

When you are going to save or open (or something similar) a file, a file selection dialog will be issued. The dialog will also be opened if you click on the folder button associated with a file name field in a dialog.

In Windows, the file selection dialog looks and behaves exactly like the normal file selection dialog used in Microsoft Windows.

In the SDL suite on UNIX, the file selection dialog behaves like described below. The the TTCN suite version on UNIX is described in "The TTCN Suite File and Directory Dialog (on UNIX)" .

  • The text in the Filter field determines which files are shown in the Files list. The field is initially set to match the file type that the invoking tool or dialog operates on but you may change it.
  • If you click the Filter button, the file matching pattern in the Filter text field is applied to the current directory in the Directories list and the Files list is updated. This is the same as pressing <Return> or clicking the default button when no file name is present in the File text field.
  • If you click the Current button, the directory will be changed to the source or target directory, depending on which kind of operation you have initiated. For more information, see "Set Directories" . The Files list will be updated accordingly.
  • The Directories list shows the absolute path to the currently chosen directory, as well as the names of any subdirectories in that directory. The directories in the path are shown within brackets, slightly indented for each directory level. The last directory in the list is the name of the currently chosen directory. To change to another directory, double-click on any directory in the list. Both the Directories list and the Files list are then updated to show the contents of the new directory.
  • The Files list shows the files in the currently chosen directory that match the pattern in the Filter text field. You can select the file to operate on from this list, in which case the File text field is updated to contain the name of the file. To double-click on a file name is the same as selecting it and then pressing the default button.
  • The File text field contains the name of the file selected in the Files list. This field may initially contain a default file name, suggested by the invoking tool or dialog. You can enter any file name in this field, including a relative or absolute path. You may also specify paths to home directories with the "tilde" syntax (~/ or ~user/).
    When <Return> or the default button is pressed, it is the file in this text field that is operated on. If the field is empty and no file is selected in the Files list, this is the same as pressing the Filter button.

Directory Selection Dialog

A directory selection dialog is opened when you select menu choices dealing with directories. The dialog will also be opened if you click on the folder button associated with a directory name field in a dialog.

In Windows, the directory selection dialog looks and behaves exactly like the normal directory selection dialog used in Microsoft Windows.

In the SDL suite on UNIX, the directory selection dialog behaves like described below. The TTCN suite version on UNIX is described in "The TTCN Suite File and Directory Dialog (on UNIX)" .

  • The Directories list works in the same way as in the file selection dialog. It is the last directory in the indented list of directories that is chosen when the OK button is pressed, unless the text field is specified. This means that it is not enough to select a directory in the list; it has to be double-clicked to become the chosen directory.
  • The Text Field may be used to enter any directory name, including a relative or absolute path. When <Return> or the OK button is pressed, it is the directory in this text field that is chosen, if it is specified.
  • The Current button works in the same way as in the file selection dialog. For more information, see "File Selection Dialog" .

The TTCN Suite File and Directory Dialog (on UNIX)

Many TTCN suite dialogs on UNIX require the specification of directory paths and file names. A special dialog is used for this purpose.

The example used in the description of the dialog below is taken from a Log file dialog, but the principle is the same for all file/directory oriented dialogs.

Figure 8 : The TTCN suite file and directory dialog (on UNIX)

  • The Filter field enables you to specify a name pattern which will cause only those file names which match the pattern to be displayed in the Files list. Note that the name pattern must be preceded by the complete directory path. This path is set by the TTCN suite to the currently selected directory (by selecting a directory path in the directories list), but you may edit it directly.
  • The Directories list shows the directories in the current directory. This list will contain at least two entries, the current directory (a path ending in /.) and the parent directory (a path ending in /..). To change to another directory in the dialog, select the required directory path and double-click (see also the Filter command).
  • The Files list shows the files that are in the selected directory which match the name pattern. If no files match the pattern or the directory is empty, this is indicated by "[ ]".
  • The Selection field displays the currently selected file. This input field also enables you to directly type in a file name.
  • The Filter button updates the Files list depending on the filter pattern (including the file path). Select a directory in the Directories list, then choose the Filter button to open the directory and display the files in that directory (if any) in the Files list.
  • The Select button terminates the dialog with the selection indicated in the Selection input field (in other dialogs this button may have another name, e.g. Open, Export, etc. but the effect is the same). If there is already a file name chosen before invoking this dialog (i.e. from import dialog when selecting a database name) and no name is specified in the Selection input field in this dialog, only the directory path will be modified.

Filename Error Dialogs (UNIX only)

For compatibility reasons, file names on UNIX platforms must not contain colon characters. For an overview on file compatibility issues, see "Windows and UNIX File Compatibility" .

In the SDL suite, this restriction is checked whenever the you change a file or directory specification that is stored in the system file (see "System File" for more information). If they are not followed, an error dialog is shown and you are returned to the dialog where the file was specified.

If you use the TTCN suite, this restriction affects you only when you choose a name for the system file in the Organizer.

The Busy Dialog

In some special circumstances, a message dialog may be opened, stating that a tool is "busy." This is not an indication of a system error. The dialog is opened when a tool is busy performing an operation that you have not finished. A typical example is when you select Show Organizer from another tool, and you have not closed a modal dialog in the Organizer, for example the Print dialog.

The remedy for a situation like this is to close the message dialog and finish the operation that caused the busy message.

The Timeout Warning

When a Telelogic Tau tool is started on a heavily loaded computer system, it may fail to start and respond within a certain time limit. When this happens, a timeout warning dialog is opened.

The time limit is specified, in seconds, by the environment variable STARTTIMEOUT. The default time limit is 60 seconds. If timeout problems occur, this variable should be adjusted to a higher value to match the typical response times for the computer system where the Telelogic Tau tool is running. For the changed time limit to take effect, the Telelogic Tau tools must be restarted.


Keyboard Operations

It is possible to reach and invoke all commands, menu choices and selections by using the keyboard. This section describes the general keyboard operations available.

Menu Traversal

The name of each menu in the menu bar contains an underlined character, as in the menu name File. To display, or pull down, the menu, press <Meta> (on UNIX) or <Alt> (in Windows) and the corresponding key, for example <Meta+F> or <Alt+F>.

One character in each menu choice is also underlined. To invoke a menu choice when the menu is displayed, simply press the corresponding key.

The arrow keys can also be used to move between the menu choices and the adjacent pull-down menus.

To invoke a selected menu choice, press <Return> or <Space>. To cancel the menu traversal and bring down the menu, press <Esc>.

Keyboard Accelerators

You can invoke most common menu choices by using an accelerator. An accelerator is a key combination of the form Ctrl+X. An accelerator is always case insensitive.

An accelerator always invokes the same kind of command in all SDL suite tools where it is available. The standard accelerators are:

Accelerator | Functionality or menu command
Ctrl+F | Find, Search (in the Tools menu)
Ctrl+H | Help (On <tool> in the Help menu)
Ctrl+N | New (in the File menu)
Ctrl+O | Open (in the File menu)
Ctrl+P | Print (in the File menu)
Ctrl+Q | Quit, Exit (in the File menu)
Ctrl+S | Save (in the File menu)
Ctrl+X | Cut (in the Edit menu)
Ctrl+C | Copy (in the Edit menu)
Ctrl+V | Paste (in the Edit menu)
Ctrl+Z | Undo (in the Edit menu)
Ctrl+D | Scroll one page down
Ctrl+U | Scroll one page up

Key Bindings

By using some special keys, you may perform an operation without holding down any modifier key at the same time.

Note:

All keys are not present on all keyboards.

Key
Operation
Arrow keys
Moves the selection in tree structures, list structures and ordinary lists to the closest object in the indicated direction.
Return
(Enter)
  • In a drawing area: the same action as a double-click on the selected object.
  • In a dialog: the same action as pressing the default button.
Delete
(Remove)
For texts, clears the character after the insertion point. (May be changed with a preference.)
Backspace
For texts, clears the character before the insertion point.
F1 / Help
Opens the help viewer with help on the current window.
F2
Raises the popup menu.
Page Up
(PgUp, Prev)
Moves the visible part of the drawing area a screen upwards.
Page Down (PgDn, Next)
Moves the visible part of the drawing area a screen downwards.
Home
Moves the visible part of the drawing area to show the top of the drawing area.
End
Moves the visible part of the drawing area to show the bottom of the drawing area.
Open
As the menu choice Open.
Find
As the menu choice Search.
Again
As the menu choice Search Again.
Undo
As the menu choice Undo.
Copy
As the menu choice Copy.
Paste
As the menu choice Paste.
Cut
As the menu choice Cut.

Key Bindings in the TTCN Suite

More information on keyboard accelerators and key bindings in the TTCN suite can be found in:

  • "Shortcuts"
  • "Key and Button Bindings"
  • "Key and Button Bindings"
  • "Customizing the TTCN Suite (on UNIX)"


References

  1. Valerie Quercia and Tim O'Reilly:
    The Definitive Guides to the X Window System
    Volume 3: X Window System User's Guide
    OSF/Motif Edition
    O'Reilly & Associates, Inc. 1991
    ISBN 0-937175-61-7
  2. Open Software Foundation:
    OSF/Motif Style Guide Revision 1.2
    Prentice Hall, Englewood Cliffs, New Jersey 1992
    ISBN 0-13-640616-5
  3. Microsoft Corporation:
    Introducing Microsoft Windows 95
    ISBN: 1-55615-860-2
  4. Microsoft Corporation:
    Microsoft Windows NT Workstation: Start Here, Basics and Installation


2 The Organizer

The Organizer is the main tool in Telelogic Tau. When you invoke a Telelogic Tau tool, the Organizer is started and displayed on the screen.

This chapter contains a reference manual for the Organizer; the functionality it provides, its menus, windows and symbols.


Overview

Terminology

The following basic terminology is used throughout this chapter:

  • Document
    A document is a file containing information that can be edited in an editor available through the use Telelogic Tau. Examples of documents in the Organizer are SDL diagrams, MSC diagrams, TTCN documents, and text documents.
  • Generic Document
    Files containing document types that the Organizer does not normally handle can be included in the Organizer by using a generic document symbol and connecting that symbol to the file. The Organizer uses the file extension and the preference variable Organizer*GenericCommand to determine a command to perform when the user tries to edit a generic document.
  • Diagram
    A diagram is a graphical document that only can be edited in a graphical editor. Diagrams are either SDL diagrams, MSC diagrams, HMSC diagrams, Object Model (OM) diagrams, or State Chart (SC) diagrams.
  • TTCN Document
    A TTCN Document signifies a document of type Test Suite, Modular Test Suite, TTCN Module, or TTCN Package.
  • SDL System
    An SDL system in Telelogic Tau signifies the topmost SDL diagram with all its sub diagrams, and all used SDL packages with their sub diagrams. In the normal case, the topmost diagram is an SDL system diagram, but the Organizer allows all types of SDL diagrams to be the topmost diagram, as long as the standard hierarchical rules of SDL diagrams are respected.
  • TTCN System
    A TTCN system in Telelogic Tau signifies the topmost TTCN document with all its sub TTCN documents.
  • System
    Not to confuse with an SDL or TTCN system, a system in Telelogic Tau is a set of documents that, according to your view, are related and thus managed by the Organizer. You decide which documents make up a system and how they are related and grouped together in the Organizer.
    A system can contain documents for analysis, design and testing of one or more SDL and/or TTCN systems. The documents can be textual requirements, analysis and design diagrams, test specifications, source code in different forms, and other types of related documentation.
    In the normal case, one system in the SDL suite contains one SDL system. But for special purposes it is possible to have more than one SDL system in the system context. Such a purpose could be when working with communicating simulators on UNIX where the source diagrams of each system are required to show and trace the graphical source symbols.
  • Root Document
    The topmost document in a document structure, or a stand-alone document, or a top-level document in a module. For an SDL system, the topmost diagram in the system, usually an SDL system diagram.
    SDL package diagrams and macro diagrams are special in the sense that they are used by an SDL system diagram. Therefore, they are also placed at the root level and are considered root diagrams.
  • Association
    An association is a link between two documents. Any document can be associated with any other document; a typical example is to associate an MSC diagram with a related SDL diagram. In the document structure, an association symbol is included to the associated document. This symbol is handled like a document, even though it simply represents a document residing somewhere else.
  • Chapter
    The drawing area of the Organizer is divided into several chapters. You may freely add, remove, and rename chapters, as well as rearrange the order of the chapters. Each chapter has an associated chapter level. It is possible to set the start chapter number.
  • Module
    A concept specific to the Organizer, used for freely grouping root documents together into a document structure. The user can use modules as a kind of scope unit. Modules have no corresponding concept in SDL, MSC or TTCN terminology. Note, however, that a TTCN Module is not the same concept as a module in the Organizer.
  • Logical Diagram Name
    The Organizer can identify diagrams in the system by their logical diagram names. The logical diagram name may contain the entire qualified name of the diagram in a specific format. The connection between logical diagram names and physical file names is explicit and under user control.
  • System File
    A file containing information about the structure and state information of a system as seen by one Telelogic Tau user. Organizer user settings and viewing options are also stored in this file. The system file is described further in "System File" .
  • Control Unit File
    A file that contains a control unit, i.e. structure information for a part of a system, common to all users that work with the system. The purpose is to provide workgroup support and a means to put a system under revision control. The user has full control of what parts of a system should be managed as control units. The control unit file is described further in "Control Unit File" .
  • Link File
    A file that contains the endpoint and link information, which is managed by the Link Manager. The link file is described further in "The Link File" .
  • Source Directory
  • Target Directory
    The source directory in Telelogic Tau specifies where new documents that you have created, are saved by default, and where to read from when opening and converting documents. On UNIX, the source directory is also the directory normally shown when you click Current in a standard file selection dialog or a standard directory selection dialog. For more information, see "File Selection Dialog" and "Directory Selection Dialog" .
    The target directory specifies where to put generated files.
    These directories are set in the Organizer, see "Set Directories" . They are also saved in the system file.
  • Footer File
  • Header File
    Footer and header files are used to define how footers and headers should look like when pages are printed. The footer and header file symbols makes it easy to edit the appearance of the footer or header using a text editor. The footer and header file format is described in "Footer and Header Files" .


Organizer User Interface

The Organizer consists of two windows: a main window and a log window. For a general description of the user interface, see 1 User Interface and Basic Operations.

The main window of the Organizer is also the main window of the Telelogic Tau environment. It manages the current system structure and is responsible for invocation and termination of other tools in Telelogic Tau.

Figure 9 : The Organizer main window

The main window exists in one instance only. If more than one Organizer is required, another Telelogic Tau tool must be started. For special purposes, the Organizer can handle more than one TTCN or SDL system simultaneously.

The log window is a text window used for displaying output during analysis and code generation and for displaying general logs. The window is described in "Organizer Log Window" .


Drawing Area

In the Organizer's drawing area, the files in the system and their structure are presented graphically using icons.

Presentation Modes

The Organizer can present the system information in two different ways graphically:

  • As an indented list, i.e. a compact, line-oriented list of icons using indentation to suggest the structure (see Figure 10).
  • As a vertical tree, which is depth- or level-oriented and requires a larger amount of space (see Figure 11).

The user can change the amount of information and the way it is presented in the drawing area with the menu choice View Options in the View menu. See "View Options" for more information.

Figure 10 : Indented list mode

Figure 11 : Vertical tree mode

Chapters

The chapter concept can be used to define a collection of documents. There are no restrictions on what kind of documents that may be placed in a certain chapter, or on the order of documents in a chapter; this is for the user to decide. Chapters can further be used to structure a print-out of the system included in the Organizer view. More information about this can be found in "Advanced Print Facilities" .

A chapter has a name, and possibly a number. A chapter is shown as a thick horizontal line in the drawing area, together with its number and name. A chapter symbol can be placed inside a Module, as well as inside an SDL diagram structure and a TTCN Module structure.

In addition to the line icon, it is possible to have the Organizer show the text "Chapter" ahead of the number and name; see "Icon Names and Types" .

Chapter Levels

A chapter has an associated chapter level, ranging from 0 to 4, which is reflected in the numbering of the chapter:

  • Level 0: a chapter without a number (only a name)
  • Level 1: a chapter with a single number: 1, 2, 3, etc.
  • Level 2: a chapter with two numbers: 1.1, 1.2, 1.3, etc.
  • Level 3: a chapter with three numbers: 1.1.1, 1.1.2, 1.1.3, etc.
  • Level 4: a chapter with four numbers: 1.1.1.1, 1.1.1.2, 1.1.1.3, etc.

Numbered chapters are auto-numbered by the Organizer. The initial number for the first chapter in the drawing area can be specified. The initial level of a chapter is specified when the chapter is created, but can later be changed.

Chapter Introduction Text

A chapter can be associated with a text, which can be regarded as an introduction text to the chapter. When the chapter is included in a print-out, this text will be inserted on a separate page corresponding to the position of the chapter symbol.

The text is saved in a text file, which the chapter symbol is connected to.

Default Chapters

There is a default set of unnumbered chapters, known as the basic Organizer view, intended for different kinds of documents. This view appears when creating a new system file and contains the following chapters:

  • Chapter Analysis Model
  • Chapter Used Files
  • Chapter SDL System Structure
  • Chapter TTCN Test Specification
  • Chapter Other Documents.

The intended use of these default chapters is described below. The default set of chapters can be changed by editing the preference Organizer*Areas.

Chapter Analysis Model

The Analysis Model chapter is intended for documents used in a system's analysis, such as Object Model and State Chart diagrams, text requirement documents, MSC, HMSC and SDL requirement diagrams, etc.

Chapter Used Files

The Used Files chapter is intended for documents that are not generated by Telelogic Tau and that are used, included, or imported by other documents in other chapters. Such documents may be C/C++ header files, etc.

Chapter SDL System Structure

The SDL System Structure chapter is intended for the SDL diagram structure that normally is the primary information managed by the Organizer. The diagram structure contains a strictly hierarchical view of one or more root diagrams and their substructures. Most often only one diagram structure is used (a system) with one or more package or macro structures present as separate roots in the system. A characteristic of these diagrams is that they are directly involved in the analysis/code generation process. Multiple system roots are allowed, mainly to support the possibility of running communicating simulators with graphical trace.

Chapter TTCN Test Specification

The TTCN Test Specification chapter is intended for TTCN documents used for test specifications.

Chapter Other Documents

The Other Documents chapter is intended for documents that do not fit into any of the other chapters. It may contain SDL, MSC, and HMSC diagrams, text documents, etc. that are not directly part of an SDL system and that are not related to the other document structures in the Organizer.

Structure Icons

A few special icons in the Organizer are used for showing how document icons are structured, and for specifying where they are stored in the file system by default.

In addition to the icon, it is possible to have the Organizer show the type of the structure icon textually; see "Icon Names and Types" .

Different operations are applicable to different types of icons. Double-clicking an icon is described in "Double Clicks" , and associated popup menus are described in "Pop-Up Menus" .

System File
The name of the system file. This system file could be managed as a control unit (CM group) to allow revision control of the system file in a multiuser environment.

Link File
The name of the link file.

Control Unit File
This icon designates a control unit whose contents have not yet been resolved.

Source Directory
The name of the source directory.

Target Directory
The name of the target directory.

Header File
The name of the header definition file. Note that it is possible to connect a text file to this symbol, i.e. the symbol can act as a plain text symbol.

Footer File
The name of the footer definition file. Note that it is possible to connect a text file to this symbol, i.e. the symbol can act as a plain text symbol.

Chapter
A chapter in the drawing area. A chapter can have a number and a name and may be connected to a text file.

Module
Another way to define a collection of documents, within a chapter. A module has a name but no associated file name.

More
Indicates that a number of documents are hidden in the document structure (see "Hide" ). The text associated with the icon indicates the number of hidden (additional) documents, e.g. "5 More".

Bookmark
Quick access to a place in an SDL Suite diagram or document via an SDT reference or to a place on the Web via a URL.

Document Icons

To visualize the different types of documents that are present in the user's system, a large number of graphical icons are used. A unique icon is provided for every document type that is commonly used in a system. In particular, each SDL diagram type (except packages, systems, macro definitions and operators) already have a given icon (the reference symbol specified in the Z.100 recommendation).

In addition to the icon, it is possible to have the Organizer show the type of the document textually; see "Icon Names and Types" .

Different operations are applicable to different types of icons. Double clicking an icon is described in "Double Clicks" , and associated popup menus are described in "Pop-Up Menus" .

Icon Types

The list below shows the icons that may be part of a system display in the Organizer:

Object Model Diagram icons

Object Model

State Chart

SDL Diagram icons

Package

System

Block

Substructure

Process

Service

Procedure

Macro

System type

Block type

Process type

Service type

Operator

SDL Overview

MSC Diagram icons

MSC

HMSC

Text Document icons

ASN.1 Text

Build Script (see "Build Scripts" )

C Header

C Import Specification

C++ Import Specification

Plain Text. Note that connecting a plain text symbol to an external synonym file (*.syn) has a special meaning. See "Update Visibility" , "Include Expression" and "Supplying Values of External Synonyms" .

Test Script. Used by Organizer>Tools>Simulator Test to execute test cases (in the form of input history scripts *.cui) in the simulator.

SDL PR

Word Text

TTCN Document icons

Modular Test Suite

Module

Package

Test Suite

Flat View

SDL Instance icons

System instance

Block instance

Process instance

Service instance

SDL Dashed icons

Block

Process

Service

Other icons

The icon for an association or a dependency is a dashed version of the icon of the referenced document. The example to the left shows an association referencing an MSC icon.

Generic Document

Index icon, representing a generated cross reference file that can be viewed in the Index Viewer.

Page (used for SDL, HMSC, State Chart, and OM diagrams)

Diagram and Document Icon States

The diagram and document icons can have different background colors indicating the state of the information entity associated with the icon. If the icon state is anything else than normal, additional information about the corresponding file is provided in the Status Bar when the icon is selected.

Normal
The normal state of the icon. Information is not modified.
All diagram and document icon types can be normal. This is also the background color used by all non-diagram/document icons.

Invalid
The connected file does not exist or is not a diagram file of the correct type. This state is only possible when connected to a file.
All diagram and document icons can be invalid.
For more information on invalid icons, see "Open" and "The Drives Section" .

Mismatch
The SDL diagram is not referenced in the diagram file where this diagram is referenced in the Organizer, i.e. there is a SDL diagram structure mismatch between the system file and the diagram files.
This state is only possible when connected to a file. Mismatched diagrams that are unconnected are removed from the diagram structure in the Organizer.
SDL diagram icons that are not root diagrams can be mismatched.
The reason for a mismatch is that the reference symbol in the parent diagram states a diagram name different than the kernel heading in the mismatched SDL diagram.
For more information on mismatches, see "Open" and "No Save" .

Dirty
The associated information entity is modified, but not yet saved. This state is only possible when connected to a file.
All diagram and document icons can be dirty.

Ordering

The order of root documents in a chapter is not fixed and can be changed by the user; see "Move Down" and "Move Up" . Moving documents in the Organizer is also used for two other purposes:

  • Grouping root documents in a module. Trying to move a root document "over" a non-collapsed module, will result in that the root document becomes a child symbol to the module. A document is also moved out of a module by moving the document up (or down) one or several times.
  • Grouping TTCN documents to form a TTCN system. Trying to move a root TTCN document with no children over another (non-collapsed) root TTCN document (possibly with children), will result in that the moved TTCN document will become a child symbol below the other root TTCN document. A non-root TTCN document is moved out of a TTCN system by moving the TTCN document up (or down) one or several times.

However, the order in which "child" icon types to a "parent" icon appear is fixed according to the following:

  1. Page icons
  2. Association icons
  3. Dependency icons
  4. SDL Instance icons
  5. SDL Dashed icons
  6. Child diagram and document icons

The ordering of page icons is specified in the appropriate editor for the diagram/document type (see "SDL Page Order" , or "Diagrams and Pages" ). The ordering of association icons, dependency icons, SDL instance icons and SDL dashed icons is fixed and cannot be changed by the user. The ordering of child diagram and document icons can also be changed.

Icon Names and Types

The names of chapters, modules and documents in the Organizer are always shown to the right of the icon.

It is possible to show the type of each icon, i.e. a text of the form "System file", "Chapter", "Module", "Object Model", "Block", etc., directly to the right of the icon (ahead of the name). For SDL diagrams, it is also possible to show the virtuality of the diagram. Both these options are available from the menu choice View Options in the View menu. See "View Options" for more information.

If the document is not opened in an editor, the icon text is presented in a normal, plain type face. If the document is opened in an editor, the text is presented in bold face.

Double Clicks

To double click on an icon invokes a default action on the information type that the icon represents.

The menu choices and operations corresponding to the double clicks are:

Type of icon | Menu choice / operation
Diagram and document icons | Edit on the selected diagram/document itself
Page icons | Edit on the selected page in the associated diagram/document
Association and Dependency icons | Edit on the diagram the link points to
SDL Instance icons and SDL Dashed icons | SDL > Type Viewer The corresponding symbol becomes selected in the Type Viewer. A double-click on the symbol in the type viewer shows and selects the symbol in the parent SDL diagram.
Source Directory and Target Directory icons | Set Directories
System File icon | Configuration > Group File
Link File icon | Link > Link Manager
Header File and Footer File icons | Edit on the connected text file
Chapter icon | Edit on the chapter, i.e. brings up the Edit Chapter dialog for that symbol
Module icon | Edit on the module, i.e. brings up the Edit dialog for that symbol
More icon | Show Sub Symbols
Bookmark icon | Edit on the bookmark, i.e. navigate to the place specified by the associated SDT reference or URL.


Menu Bar

This section describes the menu bar of the Organizer Main window and all the available menu choices.

The menu bar contains the following menus:

  • File Menu
  • Edit Menu
  • View Menu
  • Generate Menu
  • Tools Menu
  • Bookmarks Menu
  • Help Menu.

Available Menu Choices

The following concepts affect the menu choices that are available in the menu bar.

Long and Short Menus

The user can choose between long and short menus with the menu choice View Options in the View menu. Menu choices only available in long menu mode are presented with the menu choice name within parenthesis in the textual enumeration of menu choices for a menu in the following sections.

License Dependent Menu Choices

The following menu choices are only available if the corresponding tool is available according to the license configuration:

License | Affected menu choices
Code Generator | Make
Simulator | SDL > Simulator UI
Validator | SDL > Validator UI

Configurable Menus

In the SDL suite, some menu choices may be available through the concept of user-defined menus. For more information, see "Defining Menus in the SDL Suite" .

File Menu

The File menu contains the following menu choices. (Menu choices within parenthesis are not available in short menu mode.)

  • New
  • Open
  • Save
  • Save As
  • Pack Archive
  • Unpack Archive
  • Print > All
  • Print > Selected
  • Print > Selected and Colored
  • (Set Directories)
  • PC Drives
  • (Compare System)
  • (Merge System)
  • (Import SDL)
  • Recently used system files
  • Exit

New

This menu choice displays a dialog, with the following possibilities:

  • Start with a new and empty system, containing the basic Organizer view (see "Chapters" ).
  • Start with a standard template system, saved as an archive file (*.tgz) in the SDL Suite installation. The archive files for the standard template systems are and should be saved in directory <install dir>/sdt/include/template/.
  • Start with any template system, saved as an archive file (*.tgz) anywhere in the file system.

If you want to start with a template system, you will have to specify the directory to unpack the archive file in, in "Unpack Archive" that follows.

If a system file already is open in the Organizer, the behavior is determined by the status of the existing system. If modified information exists, the user first gets the possibility to save it; see "The Save Before Dialog" .

The new system is then created in memory. Source Directory and Target Directory are left unchanged, i.e. set to the values they had before the New operation.

Note:

The actual value of a directory in the Set Directories dialog may change if the directory is set to System file directory. Since there is no system file associated with a new system, the Telelogic Tau start-up directory is used until the file is saved.

You have to save the system to create a system file on disk.

The old contents of the drawing area is replaced with the basic Organizer view. If any of the documents in the old system managed by the Organizer were opened in an editor, these editor windows are closed.

Open

This menu choice is usually used to open an existing system file. It can also be used to open a single diagram or document file, as well as to open and resolve a *.scu file.

Opening a System File

If a system file is already open in the Organizer, the behavior is determined by the status of the existing system. If the information is not modified, the Open dialog is issued (see below). If modified information exists, the user first gets the possibility to save it; see "The Save Before Dialog" .

The Open dialog is a standard file selection dialog, with the file filter set to *.sdt. The Open button in the dialog opens the specified system file. The old contents of the drawing area is replaced with the new system. If a system window state file is found, see "System Window State File" , the window position and size is restored to the position and state it had when the system file was saved. If any of the documents managed by the Organizer were opened in an editor, the editor windows are closed.

If the system file does not specify the Source Directory and/or the Target Directory explicitly, these directories are set to the directory where the system file was found.

The following information consistency checks are performed when opening a system:

  • That the opened file is a valid system file. The case when an SDT-2 diagram file is opened is discussed above. If a system file created with an earlier version of SDT-3 is opened, you will be warned that the file will be saved in the current format
  • All file bindings in the system file are verified. For each file, a check is made to see that the file exists and that the file is of the correct type. The file access permissions are also determined. If something is not correct, it is reported in the Organizer Log.
    If a document is marked Invalid, the user must later correct the file binding. The user could either reconnect the document to a valid file, or perform a disconnection in which case the document disappears.
  • The SDL diagram structures in the system file and in the SDL diagram files are also compared, in terms of existing SDL reference symbols. If connected SDL diagrams in the system file are not present in the corresponding SDL diagram files, the diagram icons are marked Mismatch and the status is logged in the Organizer Log window. Unconnected SDL diagrams are removed from the system file and the Organizer's diagram structure. New reference symbols found in the SDL diagram files are added as unconnected diagrams in the system file and the Organizer's diagram structure.
    If an SDL diagram is marked mismatched, the user must later correct the diagram structures. The user could either perform a disconnection in which case the diagram disappears, or change the appropriate diagram in an editor to include the mismatched reference symbol.
  • File protection of the system file and the working directory. If either of them is write protected, a warning message appears.

Opening a Diagram or Document File

If you are only interested in examining the contents of a single diagram or document file, you can specify the filename of that diagram or document in the open dialog. (It might be helpful to change the filter in the open dialog first, to be able to view the existing files of the type that you are interested in.)

If you specify the filename of a single diagram or document in the open dialog, then a new system file will be created, only containing the specified diagram or document. The diagram or document will also be loaded and shown in an appropriate editor. Note that no sub(structure) diagram files will be visible in the Organizer view.

Opening a *.scu File

Software control unit files *.scu are used to allow several people to work in parallel on the same SDL diagram structure. When you update your *.scu files, for instance by using the Configuration > Update menu choice, the SDL diagram structure might change, if someone else has changed the structure and checked in an updated *.scu file.

You can have a top *.scu file associated with the system file symbol in the Organizer drawing area. This *.scu file will take control of the diagram and document structure in the Organizer, leaving the *.sdt file with only control over the user settings (print, view...) and a little system state information (when was the SDL system analyzed without errors last?)

Opening an *.scu file is the same as creating a new system by attaching a *.scu file to the system file symbol in the Organizer and using Configuration > Update to update the diagram and document structure according to the contents of the *.scu file.

Opening an Archive File

Opening an archive file (*.tgz) invokes the unpack archive file operation. Read more about this in "Unpack Archive" .

Save

This menu choice saves all modified documents and control unit files known to the Organizer, the link file, and finally the system file used by the Organizer. You can still perform a save even if the Organizer contains a completely new system, or if the system has not been changed since the last save operation. The menu choice has the text Save (not needed) in this situation.

Whenever the system file is saved, the system window state file is saved as well. See "System Window State File" .

If the system file is modified and needs saving, an asterisk `*' is appended to the name of the system file in the Organizer's title bar.

When the first document that is modified is encountered in the Organizer's view of files, the Save dialog below appears. If not Save All, Quit All or Cancel is selected, the dialog will remain on the screen and all modified documents will be handled by the dialog subsequently.

Whether the document is connected to a file or not will affect the layout and behavior of the Save dialog. For any unsaved and unconnected documents found, the user must provide a filename to connect to.

If the system has been saved before, the system file is saved (without a dialog) after all diagrams and documents have been saved. If the system never has been saved, the Organizer presents a dialog and proposes a name for the system file; the prefix is the name of the first document in the structure, the extension is .sdt.

The fields and buttons in the Save dialog are:

  • Save in file
    If the document is connected, the name of the connected file is shown. If the system file is to be saved for the first time, a proposed name for the system file is shown. The filename can be edited by the user.
    If the document is not connected, the Organizer proposes a filename based on the document name and a file extension corresponding to the document type, making the file name unique in the file system (see "Save" for more information). The filename can be edited by the user.
    The Organizer will not accept a file name that would overwrite another document or a diagram file that is loaded in an editor.
    The user is prompted to confirm the file name if it is already used by a document included in the document structure.
    If the file exists in the file system when the Save button is pressed, the user is warned in a message box that the existing file will be overwritten.
    If a valid filename is provided, Save or Save All below also connects the diagram to the supplied file.
  • Save
    Saves the document file. Then the next file which needs to be saved is shown.
  • No Save
    Ignores the file without saving it. Then the next file which needs to be saved is shown. If, during the save process, the user saves some SDL diagram files but not others, there is a risk of SDL diagram structure mismatches between the system file and the diagram files. Therefore, a warning dialog with the following alternatives is opened:
    • Clicking OK does not save the file and continues with the next file.
    • Clicking Cancel returns to the original Save dialog, making it possible to save the file.
  • Save All
    Saves all files (diagram and document files, control unit files, the link file, and the system file) without a confirmation by the user, with the exception of unconnected files, which causes the dialog to appear again.
  • Quit All
    Quits all files (document files, control unit files, the link file, and the system file) without saving. If, during the save process, the user saves some SDL diagram files but not others, there is a risk of SDL diagram structure mismatches between the system file and the diagram files. Therefore, a warning dialog with the following alternatives is opened:
    • Clicking OK as a response to an Exit operation, completes the exit process without saving any more documents / files.
    • Clicking Cancel aborts the save process (possibly the exit process) completely.

Save As

This menu choice works as the Save menu choice with the following differences:

  • Save As is always selectable.
  • There is always a Save dialog for the system file.
  • The Save As menu choice is used to save the system file under a new name. If the system file is saved under the old system file name, the user has to confirm this in a dialog.

The Save Before Dialog

Some operations in the Organizer need to save information before the actual operation can be performed. The saving is only performed if modified information exists in the system. In these cases a Save Before dialog is opened, which is very similar to a normal Save dialog. The dialog title is Save before <command> and some buttons may behave differently (see Figure 12). If not Save All, Quit All or Cancel is selected, the dialog will remain on the screen and all modified files will be handled by the dialog subsequently.

The Save Before dialog is opened for the following menu choices:

  • File menu: New, Open and Exit
    The save process handles modified documents in all chapters. In the case of Exit, unsaved diagrams in editors that are not yet in the document structure of the Organizer are also handled.
    If an SDL diagram is modified, has a diagram substructure and some of these SDL diagrams are either opened in an editor or connected to a file, special care must be taken. If the user chooses not to save such an SDL diagram, inconsistencies between the system file and the diagram files may result. The user is warned in a dialog and may choose to continue, i.e. not to save, or to return to the Save Before dialog. (See "No Save" and "Quit All" .)
  • File menu: Compare System and Import SDL
    The save process handles modified documents in all chapters. However, if any modified documents are opened in an editor, only the system file may be saved, not any of the documents.
  • Generate menu: Analyze, Make and SDL Overview
    The save process handles modified SDL diagrams in all chapters. The buttons No Save and Quit All are dimmed.
  • Generate menu: Convert to PR/MP
    The save process handles modified SDL diagrams in all chapters. The buttons No Save and Quit All are dimmed. If the user clicks Cancel, the Convert to PR/MP dialog is opened with the GR source diagram toggle dimmed.

Auto Saving

When selecting any of the Generate commands Analyze, Make, Convert to PR/MP or SDL Overview, the Save Before dialog does not appear if the preference AutoSaveBefore is set. However, unconnected and modified documents still require user interaction. If such documents exist, the dialog appears.

Pack Archive

Pack files related to the system loaded in the Organizer into an archive file (*.tgz).

The archive file has the extension *.tgz and is packed using tar and gzip. This means that the archive file can also be unpacked without using the SDL Suite, from the command line, using g(un)zip and tar.

Note:

Packing and unpacking archive files will only work if the SDL Suite can access the external tar and gzip programs, using the preferences mentioned below. tar and gzip usually exist on a UNIX system. For Windows (MSDOS), gnu versions of tar.exe and gzip.exe have been included with the installation. The external tools can be pointed out with the preferences "TarCommand" and "GzipCommand" .

The first Pack Archive Dialog

To use the pack operation, have the files you want to create an archive file for in the Organizer and invoke the operation. The first pack archive dialog will appear, where you can do the following things:

  • Pack all diagrams into archive. This text field is used to specify where the archive file should be saved, and under what name. As default, the archive file is saved in the target directory, with a name based on the SDL system diagram name, and with a *.tgz extension.
  • Diagram files are relative to. This text field is used to specify a source directory for files put into the archive. As default, the source directory specified in the Organizer is used. Note that files outside this directory, that should be included in the archive file, are put in a separate directory named external.
  • Include top directory in archive. To avoid mixing files from an archive with other files when unpacking, it is possible to create a top directory for all files in the archive when packing. As default, a top directory is created, with the same name as the SDL system diagram that is packed.
  • Save system file for archive in. With this option, it is possible to create a new system file for the archive, only referencing files that really are packed with file references updated for the archive. Use this option (instead of packing the original system file) to get a portable archive file. As default, an archive system file is created, in the archive top directory, with a name based on the SDL system diagram that is packed.

The second Pack Archive Dialog

When pressing the Next button in the first pack archive dialog, the second pack archive dialog appears, where file types to include can be decided. The following file types are included as default:

  • Archive System File
  • SDL Package Diagrams
  • Other SDL Diagrams
  • MSCs
  • UML Diagrams
  • Chapter Files
  • Other Text Files
  • Index Files
  • Header and Footer Files

The following file types are not included as default:

  • Original System File
  • Generic Files
  • Simulator Script Files
  • *.scu files

The second pack archive dialog also makes it possible to include files from the source or target directories with specific extensions. These extensions should be specified in the Also include files with the following extensions text field (a comma separated list of extension names). As default, *.lst files from the source or target directory are included in this way, with the text field text set to lst.

The third Pack Archive Dialog

Pressing the Next button in the second pack archive dialog displays the third pack archive dialog, where all files that will be included in the archive are listed. A file in the list is usually presented in the following way:

<file system file name> (-> <archive file name> )

In the dialog, it is possible to include or exclude individual files.

  • To include a file, press the Add button and specify the file in the file selection dialog that appears.
  • To exclude a file, select it in the list, and press the Remove button.

When you are satisfied with the list of files that will be packed, press the Pack button to start the pack operation. Information from the pack operation can be found in the Organizer Log.

Unpack Archive

This operation unpacks files in an archive file (*.tgz), and places them in a directory in the file system.

An archive file is created and unpacked with the external tools tar and gzip, that both must be available for the operation to work. The external tools can be pointed out with the preferences "TarCommand" and "GzipCommand" .

An archive file can be unpacked in one of the following ways:

  • By invoking the unpack archive operation in SDL Suite:
    • Select the Organizer > File > Unpack Archive menu choice.
    • Specify a *.tgz file in the Organizer > File > Open dialog.
    • Start SDL Suite with a *.tgz file as a parameter.
  • From the command line, using gzip and tar directly. (For more information about this alternative, see the documentation for these tools.

The Unpack Archive Dialog

Whenever SDL Suite is used to unpack, and the unpack directory has not been specified, the Unpack Archive dialog appears. The dialog has three things that should be considered:

  • Unpack archive file. In this text field, the archive file to unpack should be specified.
  • In directory. In this text field, the directory to unpack the files in should be specified.
  • Open unpacked system file in Organizer. If this option is on, the Organizer will after the unpack operation search for a system file (*.sdt) among the unpacked files, and if there is a system file, it will be opened in the Organizer.

Print > All

Similar to Print > Selected. The difference is that for Print All, the selection is not considered, all diagrams and documents are always printed, if the set of diagrams and documents to print is not further refined in the print dialog.

Print > Selected

Prints all or some of the diagrams in the Organizer. See 5 Printing Documents and Diagrams, for more information about the dialog and some examples of how to print. The Organizer selection decides the set of diagrams and documents to print, if the set is not further refined in the print dialog.

Print > Selected and Colored

Similar to Print > Selected. The difference is that for Print Selected and Colored, only pages (when pages are shown in the Organizer drawing area) or diagrams (when pages are not shown in the Organizer drawing area) with at least one colored symbol are printed. A symbol is colored when the symbol has a border color other than black or a fill color other than white.

Print > Selection File

A file selection dialog appears, where a print selection file should be specified (*.sel). The print selection file is read, and the Organizer print dialog is displayed, updated to reflect the state that the print dialog had when the print selection file was saved from the print dialog. The print selection file is capable of remembering:

  • Selected diagrams/documents/pages.
  • Print options (scale, paper format...)
  • Index Viewer filter options (filter types, uses and diagrams)
  • State Matrix Viewer filter options (in Text Editor) (filter processes)

Note that print selection files can also be used by having a print selection symbol in the Organizer. In that case, you can use the print selection file and invoke the print dialog by double-clicking on the print selection symbol.

Set Directories

This menu choice sets the source and target directories. For more information on these directories, see "Source Directory" and "Target Directory" .

This menu choice is only available if the system file can be changed.

If the source directory is changed while a Save dialog is active in an editor, the directory where the editor saves the diagram is undefined. An ongoing analysis is not affected by changing the target directory.

Figure 12 : The Set Directories dialog

  • Source Directory
  • Target Directory
    Source and target directory settings are saved in the system file. Both these directories can be specified in three ways:
    • SDL suite start-up directory: Source or target directory is set to the directory where the Telelogic Tau tool was started from (in Windows the directory of the executable file or the specified start directory for a shortcut icon). This setting means that relative file bindings in the system will be evaluated starting from the start-up directory the next time the system file is loaded into the Organizer.
    • System file directory: This is the default value for both source and target directory. Source or target directory is set to the directory where the system file resides. For a new system that has not been saved yet, the start-up directory is used until the system is saved. This setting means that relative file bindings in the system will be evaluated starting from the system file directory the next time the system file is loaded into the Organizer. This setting also makes it possible to move a system file and all related diagram and document files to a new directory without having to update the system file, provided that the positions of all diagram and document files relative to the system file are preserved.
    • A specific directory. The directory specified in the text field will be used. Note that the target directory can here be specified using a relative file name. If this is done, the source directory is used as a base to dynamically calculate an absolute target directory. This is useful when you want to have a target directory as a sub directory to the source directory and you want to be able to move all your Telelogic Tau files in or between file systems without great effort.
  • Absolute file names
    If this option is set, the Organizer shows and stores document files with full (absolute) path.
  • Relative file names
    If this option is set (the default), the Organizer stores document files with paths relative to the source directory. There are two variants regarding showing document files in the Organizer drawing area:
    • Short form on (the default). The file connection is shown exactly as it is stored in the system file.
    • Short form off. The directory part of a file connection is shown in italics for a file connection that exactly matches the Source Directory path. All other file connections are shown as absolute file names, even if they are not necessarily stored with absolute file paths in the system file.
  • Change document directory
    This operation is used to change the directory part of one or more file connections in one operation. A symbol that has a file connection including the directory that should be changed has to be selected before invoking the dialog. This operation will be dimmed if there is no selection or if the selected file has no file connection.
    In the To text field, the directory which the selected directory should be changed into should be specified. When pressing OK with Change document directory on, all file connections matching the From directory will be changed to the To directory.

PC Drives

This menu choice displays the drive table of the currently opened system, i.e. the mapping between drive names in Windows and the beginning of corresponding directory paths on UNIX. For more information, see "Windows and UNIX File Compatibility" .

This menu choice is only available if the system file can be changed.

The following dialog is opened:

Figure 13 : The PC Drives dialog

The text area displays the drive table currently used in the system. The table can be edited directly in the text area. When the system file later is saved, the table is stored in the The Drives Section.

When clicking OK, a basic syntax check is performed on the entered drive table. Each line should consist of two items only:

  • A Windows path, either a drive letter followed by a colon, e.g. H:, or a full path (e.g. C:\TEMP). UNC paths can be used (e.g. \\<host>\file). If you include a trailing backslash (optional) you must also include a trailing slash in the corresponding UNIX path.
  • A UNIX directory path starting with a slash `/'. If you include a trailing slash (optional) you must also include a trailing backslash in the corresponding Windows path.

Paths containing spaces must be put within double quotes. Note that within double quotes, each backslash must be entered as two backslashes, i.e. a UNC path \\host\dir name (containing spaces) must be entered as "\\\host\\dir name".

If any errors are found, the user is notified and the dialog is not closed. If the table was changed and found to be syntactically correct, the system file is marked as modified.

Note:

Changes made in the PC Drives dialog only take effect when the system file is reloaded.

Compare System

Works as Merge System, except that there is no possibility to merge the differences found during the compare operation.

Merge System

This menu choice compares the contents of the Organizer Main window with the contents of a system file (.sdt file). The compare operation is performed on a diagram/document level.

This menu choice is only available if the system file can be changed.

The two systems are compared and possible differences are reported to the user, with the option to merge them, by specifying which documents to add and which to remove in the Organizer system.

The information is processed according to the following scheme:

  1. The user is asked to exit any editors, if any is found running. This means that modified documents must be saved before the comparison can be started.
  2. If the system file is modified, the user is prompted to save it in a The Save Before Dialog.
  3. A standard file selection dialog is issued, where the system file to compare the Organizer system with may be selected. Choosing a system file in this dialog starts the compare operation.
  4. If there are differences between the options set in the Organizer and the options saved in the system file to compare with, these are reported first, as a text in a separate dialog. The text might look like this:
Comparing system in Organizer
with /home/develop/lat/target/DemonGame.sdt.

Options saved in system file differs:

SemanticControl differs: False True
Kernel differs: SCTVALIDATOR SCTADEBCOM

If you want to remove these differences, you have to do it manually by changing different settings in the Organizer. For instance, to remove the SemanticControl difference by updating the Organizer settings, bring up the Analyzer dialog and select Semantic analysis. (SemanticControl is the word used in the system file, Semantic analysis are the words used in the graphical user interface for the same thing.)
  5. The Compare System dialog is issued, where the diagram and document differences are reported (if the Organizer system and the contents of a system file are found identical, this is reported in a message box and the operation is terminated).

Figure 14 : The Compare System dialog

  6. The user decides if and how to merge the two views, by selecting or deselecting the items to include or exclude from the resulting system. OK updates the system in accordance with the settings.

The Merge System Dialog

  • The lists are sorted according to the order of appearance of the items in the Organizer Main window and the order of appearance in the system file.
  • Each item in a list identifies a chapter, module or document that was found in only one of the two systems (i.e. in the Organizer or in the system file) or were found in both systems, but differ from each other (see "How Systems Are Compared" for more information about how structures and documents are compared).
    A document is listed with its type, name and the file it is stored on. A module is listed with its type and name. A chapter is listed with its name.
    • A chapter, module or document that was found in one system but missing in the other, is present in one list only and is identified in the other list with a non-selectable `-' (hyphen).
    • Documents that were found in both systems and that are considered equal are not listed. See "equal" for more information.
    • Documents that were found in both systems and that are considered almost equal are presented in both lists. See "almost equal" for more information.
  • Association and dependency links are not included in the lists, but are preserved as far as possible. See "Associations and Dependencies" for more details.
  • The items in the two lists that are selected will be included in the resulting (merged) Organizer view.

The items in the Organizer diagrams list are the icons that were found in the Organizer's chapters.

By default, all items that originate from the Organizer are selected, meaning that they will be included in the merged view.

Figure 15 : A diagram originating from two sources

The MSC DemonGame has been found both in the current Organizer view (where the diagram is connected to a file) and in the system file (where it is connected to another file). The dialog suggests by default to include the diagram originating from the Organizer (the left list) and to exclude the diagram originating from the system file. The user may however change the selection to merge the systems in a different way.

The <system file> list indicates the directory and name of the selected system file. The items in this list are the items that were found in the system file.

By default, given two documents that are considered almost equal, the dialog will select the document originating from the Organizer, not the document originating from the system file. See example in Figure 15, above.

How Systems Are Compared

Some rules that govern how systems are compared:

  • Relative file names:
    Relative file names are managed as if they were relative to the Source Directory as currently specified in the Organizer.
  • Handling of SDL diagrams (including packages, excluding macro diagrams):
    SDL diagrams in a tree structure are examined starting from the top and down. When two diagrams are found to differ, their diagram subtree is not examined further, the subtrees being considered as a part of the diagrams that differed.
    This means that if the user chooses to include a diagram that has a subtree, the complete subtree will also be included. Similarly, if the user chooses to exclude a diagram that has a subtree, the complete subtree will be excluded.
    The level of indentation used when listing SDL diagrams in the dialog indicates the structural level at which a diagram is found.
  • Handling of Object Model diagrams, State Chart Diagrams, HMSC diagrams, MSC diagrams, SDL macro diagrams, and SDL overview diagrams:
    Since these diagrams cannot be part of a subtree, adding or removing any of these does not affect the remaining parts of the structure.
  • Rules for equality of diagrams:
    Two diagrams/documents with the same type and name can be equal or almost equal.
    • equal
      They are considered equal if the file names are equal (equal diagrams/documents are not listed in the dialog).
    • almost equal
      They are almost equal if the file names are not equal. Two documents that are almost equal are presented on one line in the dialog. For root documents it is possible to select both diagrams on one line in the dialog. For non-root documents it is only possible to select one of the diagrams.

Note:

Compare System and Merge System do only compare the structural system information saved in the system file. Compare System and Merge System do not compare the document contents, such as page names.

Associations and Dependencies

The Compare System function preserves, as far as possible, the association and dependency links that exist between documents:

  1. When an association link is found in a system file, the file names of the two documents are saved.
  2. If a document with an association link is selected by the user to be included in the Organizer, a new link is generated if a document with the previously saved file name can be found in the Organizer structure. If such a document cannot be found, the association link is removed from the included document.

Import SDL

Imports an SDL diagram or a number of SDL diagrams in SDT-2 or SDT-3 format, and extracts the diagram structure with the possibility to save it in a system file. The command may, on demand, convert the imported diagrams into SDT-3 format without the need to involve the user for each diagram to convert. It is not possible to import an SDT-3 system file.

This menu choice is only available if the system file can be changed.

To avoid potential name conflicts when saving an imported diagram structure, the menu choice will not perform any action, and causes a message box to be displayed, in the case any files are opened in an editor.

Basically, the involved diagrams and their corresponding files are bound and presented in the Organizer. A number of information entities can be extracted from the diagrams.

If a system file already is open in the Organizer, the behavior is determined by the status of the existing system structure. The user is first asked to exit any editors, if any is found running. This means that modified documents must be saved before the import is started. If a modified system file exists, the user first gets the possibility to save it; see "The Save Before Dialog" .

The following dialog is then opened:

Figure 16 : The Import SDL dialog

The root diagram to import and convert can either be named logically with type and name, or physically with a file name. The specified diagram will become a new root diagram, placed last in the Organizer.

  • Type
    The type of the diagram is selected with this option menu. Used when naming a diagram logically.
  • Name
    The name of the diagram. Used when naming a diagram logically.
  • File
    The name of a diagram file. Used when naming a diagram physically.
  • For unspecified diagrams/files, search in directory
    Specifies that search for diagram files should be done in the specified directory.
  • Import
    Starts the import operation. Both a root diagram and a search method must be specified in order to start the conversion. If this is not done, an error message is shown. The Organizer log window informs about the progress and result of the conversion.
  • Details
    Issues this dialog:

Figure 17 : The Import SDL Details dialog

    • Close the current system first
      If this option is set (the default), the current system in the Organizer will be closed and the SDL diagrams will be imported in a new system. If this option is not set, the SDL diagrams will be imported and added to the current system.
    • Expand Substructure
      If this option is set (the default), the conversion will be done recursively in the diagram substructure from the specified root diagram. If not set, files corresponding to referenced diagrams are not imported.
    • Extract MSC Diagrams from SDT2 SDL diagrams
      If this option is set (the default), references to MSC diagrams found in SDL diagrams saved in SDT-2 format will be extracted and placed after the SDL diagram structure, together with a file binding. An association link to the MSC diagram is also inserted in the SDL diagram structure where the MSC diagram was extracted.
    • Extract SDL Overviews from SDT2 SDL diagrams
      If this option is set (the default), existing overview diagrams stored in SDL diagrams saved in SDT-2 format will be extracted and stored in a separate file. The overview diagram is placed after the SDL diagram structure. An association link to the overview diagram is inserted in the SDL diagram structure where the overview diagram was extracted.
    • Extract code generator directives
      If this option is set, the diagrams will be searched for a number of directives to be included in the system file. The option is not set as default. The directives #SEPARATE and #WITH are handled
      #SEPARATE: a separator is set in the system structure on each diagram containing the directive (see "Separator symbols" ).
      #WITH: a warning is issued in the Organizer log and a template makefile is generated with the object files found.
      For more information on directives, see "Directives to the Cadvanced/Cbasic SDL to C Compiler" .
    • Save imported diagrams in SDT 3.X format
      If this option is set, parts of the diagrams which are obsolete in SDT-3 are removed from the diagram files to convert them to SDT-3 format. The parts removed are the ones controlled by the options Extract SDL Overviews from SDT2 SDL diagrams and Extract MSC Diagrams from SDT2 SDL diagrams, described above. If these options are not set, some information may be lost when importing SDT-2 diagrams. In this case, the user will be warned in a dialog when pressing the Import button:

Figure 18 : Import diagrams warning

    • Import SDT-2 Analyzer options file
      If this option is set and a file is specified, the Analyze and Make options found in an SDT-2 Analyzer file (typically <system>.san) will be used.

Recently used system files

Just above the Exit menu choice, there can be up to four menu choices representing recently opened system files. To open one of them again, select the appropriate menu choice. The information about recently used system files is saved in a file called .sdtfiles, in your home directory (see "Environment Variables).

Exit

This menu choice exits the Organizer.

The exit operation consists of four phases:

  1. Handling of modified files managed in the Organizer structure.
    If modified information exists in the current system structure, the user gets the possibility to save it; see "The Save Before Dialog" . The dialog is opened for the first file (document/system file) that is modified in the Organizer's view of files. The user can then choose how to continue. If the user does not select Save All, Quit All or Cancel, the dialog will remain on the screen and all modified files will be handled by the dialog subsequently.
    The link file and the system file are saved last, if necessary. If the Exit process at a later stage is cancelled, all documents in the editors are still available, since they are not closed until all modified documents are handled.
  2. Confirmation of Exit.
    If no analyze, make, simulation or validation jobs are active, the Organizer exits without user confirmation. If there are such active jobs, or a simulator/validator UI is executing, the user has the possibility to force an exit of these jobs:

Figure 19 : Exit confirmation with active jobs

  3. Removing of documents in editors.
  4. Shutdown of tools.
    All Telelogic Tau tools are terminated, possibly issuing a Save before exit dialog. Finally, the Organizer itself is terminated.

Edit Menu

A general mechanism to edit the document structure(s) in the Organizer does not exist. Some of the menu choices in the Edit menu are used for basic operations on root documents and file connections. However, most changes to the document structure are a result of operations made in the diagram editors; see "Reference Symbols" .

The Edit menu features the following menu choices (menu choices within parenthesis are not available in short menu mode):

  • Edit
  • Add New
  • Add Existing
  • Remove
  • (Connect)
  • (Disconnect)
  • (Configuration > Group File)
  • (Configuration > Update)
  • (Configuration > Full Update)
  • (Color > Set Default Colors)
  • (Color > Set Black and White)
  • (Associate)
  • (Paste As)
  • (Go To Source)
  • (Update Headings)
  • (Update Visibility)
  • (Properties)

Edit

This menu choice edits the selected symbol or document. A document is edited by starting the corresponding editor. A document which is opened in an editor has its name shown in bold face in the Organizer.

The menu choice is dimmed if the selected icon is invalid, or if an instance or dashed SDL diagram icon is selected.

The operation performed depends on the type of symbol or document selected, according to the following:

Type of symbol or document
Operation performed
System file
The CM Group dialog is opened (see "Configuration > Group File" ).
Link file
The Link Manager is opened.
Directory symbol
The Set Directories dialog is opened (see "Set Directories" ).
Chapter
The Edit Chapter dialog is opened. This dialog contains three choices:
  • Edit chapter symbol: the Edit dialog is opened (see below) to allow editing the symbol type, the chapter name, or the connected text file.
  • Edit chapter options: the Chapter Options dialog is opened (see "Chapter Options" ).
  • Edit first page after chapter: the first connected SDL diagram or page after the chapter symbol is edited (see below).
Module
The Edit dialog is opened (see below) to allow editing the module name.
Connected document or header/footer file
The document/file is opened in an editor. For a diagram, the first page in the diagram is shown, or if the user has specified a page to open first in the editor (see "The Open This Page First Option" ), this page is shown instead.
Association or dependency link
The corresponding referenced document is edited as if it was the selected document.
Page symbol
The page is opened in an editor.
Unconnected document or header/footer file
The Edit dialog is opened (see below).

The Edit dialog looks like this:

Figure 20 : The Edit dialog

  • The Document type and Document name fields can be used to change the type and name of a root document. If a non-root document is selected, these fields are dimmed. If the type is changed, the new document icon will replace the old one. However, the type of a module that contains documents cannot be changed.
    The wanted document type is specified by selecting the correct radio button and selecting the document type in the option menu. It is also possible to select a document in an option menu without selecting the associated radio button first; the radio button will be auto-selected in this case.
  • The Document name text field contains the current name of the document, chapter or module. The name must conform to the naming rules for the document type; otherwise an error dialog is issued. The name of a module must conform to the naming rules for SDL diagrams, but the name of a chapter may contain any printable characters except quotation marks.
  • The Show in editor option opens the document in an editor. This option is by default on for document types that can be shown in an editor. Deselecting this option automatically deselects the Copy existing file option.
  • The Copy existing file option copies the specified file and uses it as a starting point/template for the document. If no file is specified, or the file does not exist, no file is copied. Selecting this option automatically selects the Show in editor option.

Add New

This menu choice adds a new document to the system. Normally, the added document is placed as a root document below the current selection. If there is no selection, the document is placed as the first root document in the Organizer. Adding a diagram also involves an update of a control unit if there is one that is associated with the diagram substructure affected by the Add New command.

There are two exceptions to this:

  • If the selection is a module, the new document is instead added at the top level in the module. If the selection is a document in a module, the new document is added in the module at the top level after the selection. To move diagram and documents in and out of modules when they are already in the Organizer, the Move Down and Move Up quick buttons should be used.
  • If the selection is a root TTCN document and the user adds a TTCN document, the added document will be placed as a child document below the selected document. If the selection is a child TTCN document, the added document will be placed below the selected document in the same TTCN system. This menu choice is therefore, together with the Move Down and Move Up quick buttons, used to build TTCN systems.

This menu choice is only available if the system file can be changed.

To add SDL diagrams other than root SDL diagrams, the SDL Editor is used (see "Adding a Diagram Reference Symbol" ).

The same dialog is opened as for Edit on an unconnected document (see Figure 20). By default, the Show in editor button is on.

If there is a selection, Document type and Document name in the dialog will be set to the selected symbol's type and name. If there is no selection, the dialog will show the settings from the previous invocation. If it is the first time this dialog is used, the default type Module and the default name "Untitled" will be used.

Multiple root diagrams with the same name are allowed.

If an SDL diagram was selected and an MSC diagram is added, an association link to the MSC diagram is automatically added to the SDL diagram.

Add Existing

This menu choice adds an existing document file to the system. (It is also possible to add several documents by specifying a directory) The existing document is added at the same place as described for the Add New menu choice. Adding a diagram also involves an update of a control unit if there is one that is associated with the diagram substructure affected by the Add Existing command.

This menu choice is only available if the system file can be changed.

A dialog will be opened, that allows you to specify the file to add, either via a text field or via a standard file selection dialog.

There are also three options in the dialog:

  • One to specify if the substructure of the added SDL diagram should be expanded.
  • One to specify if the added diagram or document should be shown in an editor.
  • One to specify if files existing in sub directories to the specified directory (or the directory where the specified file resides) should be added.

If the standard file selection dialog is used, the file filter is set to reflect the currently selected document type. If a module is selected, the file filter is the same as in the previous invocation. If no document is selected, the file filter is set to .s??.

The document type and logical name of the existing document is determined in different ways for different document types. The type and name is determined by:

  • Reading the specified file for SDL, MSC, HMSC, OM, SC, and TTCN documents.
  • Looking at the file name and extension for text files and generic documents.

Note:

It is not possible to add a document that does not have a default file extension. For information about default file extensions, see "Save" .

If an SDL diagram was selected and an MSC or Overview diagram is added, an association link to the MSC or Overview diagram is automatically added to the SDL diagram.

The existing document is by default opened in an editor. This behavior can be changed by the preference Organizer*ShowAddExisting.

Remove

This menu choice removes a selected root document and its document substructure, if any, from the system structure. Modules, chapters and top-level documents in modules can also be removed.

This menu choice is only available if the system file can be changed.

Removing a root document may also involve the update of one control unit file if there is any containing the diagram substructure that has been removed. The menu choice is dimmed if no such document, module or chapter is selected, or if the document is modified.

Removing a chapter symbol does not remove the documents in that chapter; only the chapter symbol itself is removed.

The following dialog is opened:

Figure 21 : The Remove dialog

  • Keep sub documents as new roots
    If the selected document contains a substructure, this option moves all documents in the substructure to become new root documents (but with their substructures kept intact). It also keeps all bindings to diagrams loaded in an editor. The new root documents are placed directly after the selected root document. If the selected document is a top-level document in a module, the new root documents are placed as top-level documents in the module.
    If this option is not set, the document substructure is removed together with the selected document, but documents being edited are still kept as buffers in editors. This is the default setting, except when a module is selected.
    The option is dimmed if the document contains no substructure, if no substructure document is connected, or if a chapter symbol is selected.
  • Delete file <file> at the same time
    This option also deletes the connected file from the file system. It is dimmed if the document is not connected or is opened in an editor, or if a chapter or module is selected.

Connect

This menu choice connects a selected document to a file. It is possible to reconnect an already connected document. The menu choice is hazed if a directory, page, instance diagram, dashed diagram, chapter, or module symbol is selected. The menu choice is also hazed if the loaded system file (*.sdt) or any associated configuration group file (*.scu) file is read-only.

The following dialog appears:

Figure 22 : The Connect dialog

  • To an existing file
    This option connects the document to an existing file. If the document already is connected, the name of the connected file is shown. If the document is unconnected, the field is filled in with the directory component of the file used the last time a document was connected. The filter in the associated file selection dialog corresponds to the file extension for the document type.
    It is possible to use an environment variable to specify the first part of the file path. This can be useful if you want the system to "update its file references" when the environment variable value has changed. For instance, there is an environment variable called "telelogic" that points out the top installation directory for SDL Suite when SDL Suite is run. You can use this environment variable to point out one of the SDL diagram files in the installation:
    $telelogic/sdt/examples/demongame/Main.spr
    (Please consider using relative file names first, because that is often a better solution. See "Set Directories" .)
    When the connection is to be made, the selected file is inspected. For instance, for an SDL diagram, if the file is not an SDL suite object file, an error message box is issued:

Figure 23 : The Connect error message

If the file contains a document of the correct type but with an incorrect name, the symbol in the Organizer is renamed.
If the file contains a document which has an incorrect type or name, the user is warned in a dialog:

Figure 24 : The Connect warning dialog

If the document already is connected and only the directory part of the existing file connection is changed, the following dialog is opened:

Figure 25 : The Connect change directory dialog

  • Search in directory
    This option searches the specified directory for a document file of a type and name matching the selected document. If such a file is found, the document is connected to the file. If no such file is found, an information box is opened. Pressing OK in the dialog returns to the Connect dialog.
    The directory field is filled in with the Source Directory the first time the dialog is used. After that, the directory from the previous usage of the dialog is remembered.
  • Expand substructure
    This option is only available for SDL diagram symbols. This option recursively expands and connects SDL diagrams to files until no more reference symbols are found. If an SDL diagram has a USE clause, i.e. it references a package diagram, this option also tries to expand the package and put it as a root diagram in the system. The diagram substructure of the package is expanded. Package references are expanded recursively.
    After the expansion is completed, the Organizer display is updated.
  • Show in editor
    This option opens the document in an editor after the connection has been established.

Error Notification

If an error occurs, the user is informed in a message box and control is returned to the Connect dialog.

Reconnect Connected SDL Diagram

When performing a reconnect to an already connected SDL diagram, the current SDL child diagram references are matched against those found in the connected file. If mismatches are found, icons are marked as such but the structure is kept intact, if possible.

Connect Open Documents

When connecting an unconnected document that is opened and unsaved in an editor, the file name binding is not conveyed to the editor, i.e., the editor binding is lost.

Disconnect

This menu choice disconnects the connected file from the selected diagram. The menu choice is hazed if the selected symbol has no file connection. The menu choice is also hazed if the loaded system file (*.sdt) or any associated configuration group file (*.scu) file is read-only.

The following dialog is opened:

Figure 26 : The Disconnect Diagram dialog

  • Keep <file> as a new root
    This option keeps the connected document in the Organizer structure by making it a new root document. The disconnected document remains in the same place in the Organizer structure.
  • Delete file <file> at the same time
    This option also deletes the connected file from the file system.

If the document is currently loaded in an editor and is modified, the document reference in the Organizer gets the same status as if a new document is edited, i.e. new and unconnected. The editor binding is then lost.

Configuration > Group File

This command operates on the currently selected diagram, and is used to create or remove a Configuration Management Group for the diagram structure. The menu choice is hazed if the loaded system file (*.sdt) or any associated configuration group file (*.scu) file is read-only. When invoked, a dialog appears:

Figure 27 : The Group File dialog

  • No group file
    No group file should be associated with this document; any existing group file for this document group will be removed.
  • Group file
    Associates a group file with this document, i.e. a Control Unit file (*.scu) will be created to hold the structural information about the document and its document substructure. In the text field, the name of the Control Unit file is specified. See "Control Unit File" for more information.
    A check is made that the name of the control unit file given by the user is unique within the system. If not, a warning dialogue is issued, making it possible to cancel the operation and to provide a new file name.
    The group file will be shown in the Organizer view like this:

Figure 28 : A group file in the Organizer view

The name of the group file is presented directly below the document name, in italics. The asterisk `*' indicates that the control unit file is dirty and needs saving. After saving, the asterisk will be removed.
The name of the control unit file is presented directly below the document's file name.

Configuration > Update

A faster version of Configuration > Full Update. The *.scu files are only read if they have changed since the last save.

Configuration > Full Update

Updates configuration groups recursively below the selection in the Organizer. Use this menu choice to update the Organizer contents if you have a system with configuration groups loaded in the Organizer and the configuration groups have changed outside the control of the Organizer, for instance by a software configuration management system operation.

Color > Set Default Colors

Invoking this menu choice will make sure that all SDL diagram symbols are colored according to preference values (such as Editor*StateSymbolColor) instead of individual colors set with SDLE > Edit > Symbol Border Color and SDLE > Edit > Symbol Fill Color. Note that this menu choice only operates on the diagrams selected in the Organizer.

Color > Set Black and White

Same as Organizer > Edit > Color > Set Default Colors, but instead of preference values, black and white is used for all symbols.

Associate

This menu choice associates or disassociates a selected document with another document. An association symbol indicates that two document symbols are connected. (A related symbol is the dependency symbol, see "Dependencies" .)

The menu choice is hazed if the loaded system file (*.sdt) or any associated configuration group file (*.scu) file is read-only.

If an association icon is selected, this menu choice operates on the associated document, not the icon itself. Any document may be associated with any other document, and a document may have more than one associated document.

The following dialog is opened:

Figure 29 : The Associate dialog

  • Associate <document> with
    The multiple selection list displays the type and name of all documents in the Organizer structure. When the dialog is opened, all documents that the current document is associated with are selected, i.e. the list shows all its associated documents.
    By selecting a new document in the list, an association link to the current document will be created in the selected document's structure. By deselecting a document in the list, the corresponding association link will be removed from the selected document's structure.

Paste As

This menu choice is used to paste copied objects as new diagrams in the Organizer. This menu choice is only available if the system file can be changed. A root diagram is created and opened in an editor. The following transformations are possible via Paste As in the Organizer:

  • An Object Model class symbol can be pasted as an SDL system diagram.
  • An Object Model object symbol can be pasted as an SDL system diagram.
  • A text fragment can be pasted as an MSC diagram.

For more information about the Paste As dialog, see "The Paste As Command" .

Go To Source

This menu choice is used to open an editor with a document according to an SDT reference. The SDT reference is specified in a dialog, see Figure 30. If the SDT reference includes information about an object in the document, that object will be selected. SDT references can be obtained by using the menu choice Show GR Reference in an editor.

For information about SDT references, see 19 SDT References.

The following dialog is opened:

Figure 30 : The Go To Source dialog

  • SDT Reference
    The textual SDT reference is specified in the input field.
  • Go To
    Shows the symbol in an editor.

An error message appears if the format of the SDT reference is incorrect or if the requested SDT reference cannot be found.

Update Headings

This menu choice checks the headings of SDL, HMSC, OM, and SC diagrams for correctness with respect to what is defined in the Organizer structure.

It operates on the selected diagram and its substructure. If no diagram is selected, all SDL, HMSC, Object Model, and State Chart diagrams in the Organizer are checked. For SDL diagrams, the kernel headings are checked.

Before the headings are checked, a check is made to see if any file is connected to more than one diagram. Such files are reported in the Organizer log, and a warning box is issued to the user. These files may be modified for each appearance and will cause all but the last update to be incorrect.

The heading check is made silently until the first incorrect heading is found. The diagram checked is then shown in the dialog below. If an incorrect qualifier is found, the user is prompted in the dialog whether to update the header or not. The user also has the possibility to silently update all incorrect headings. That is, they are loaded in an editor and are then corrected without confirmation by the user.

After the operation, all updated headings are in an unsaved mode in the editor.

This operation should be done regularly in order to avoid peculiar and hard-to-find analysis error caused by incorrect diagram headings.

In SDL diagrams, qualifiers can be placed in other symbols than the heading in the system, such as qualifying data types in a text symbol. Such qualifiers are not found by the Update Headings menu choice.

The following dialog is opened:

Figure 31 : The Update Headings dialog

  • Current kernel heading
    A read-only text field that shows the contents of the heading as defined in the SDL, HMSC, Object Model, or State Chart diagram, i.e. what is displayed in the editor. (The Kernel Heading in SDL diagrams.)
  • Correct kernel heading
    A text field with the correct heading according to the structural location of the diagram. This field may be edited by the user.
  • Update
    Updates the heading in the editor according to the text in the Correct kernel heading text field. Continues to search for the next incorrect heading and keeps the dialog open. When the updating is completed, a message appears in the status bar.
  • No Update
    Does not update the diagram's heading. Continues to search for the next incorrect heading and keeps the dialog open.
  • Update All
    Updates all headings without a confirmation by the user and closes the dialog. When the updating is completed, a confirmation message is shown in the status bar.

Update Visibility

Update SDL symbol visibility according to include expressions and external synonym values.

The SDL symbol visibility can also be set manually, see "Symbol Visibility > Hide" and "Symbol Visibility > Show" .

For more information about include expressions, see "Include Expression" .

External synonyms are saved in a plain text file with the extension *.syn in the Organizer. To specify that the boolean external synonym variable DEBUG should have the value of true, and the boolean external synonym variable VERSIONTWO should have the value of false, the *.syn file should have the following contents:

DEBUG 1
VERSIONTWO 0

By using these variable names as include expressions on selected symbols, and by having a reference to the *.syn file in the Organizer, it is possible to hide or show groups of symbols by setting up the correct values in the external synonym file and applying this command. Note that the symbol visibility can not be updated in read-only diagrams.

Properties

Edit bookmark properties for a selected bookmark symbol. Location should be set to a valid SDT reference or URL. Name is any name that makes it easy to remember the place the bookmark represents. You can get valid SDT references from SDL Suite editors, by selecting a symbol and using <editor>>Tools>Show GR Reference. The easiest way to create a new bookmark with a valid SDT reference is to use <editor>>Tools>Create Bookmark.

This menu choice is only available if the system file can be changed.

View Menu

The View menu includes the following menu choices (menu choices within parenthesis are not available in short menu mode):

  • Expand
  • Expand Substructure
  • Collapse
  • (Show Sub Symbols)
  • (Hide)
  • View Options
  • Chapter Options
  • (Set Scale)

Expand

This menu choice expands the symbol structure tree one level down for the selected document. If any symbols one level down are hidden, they are still hidden after this operation. (Use the menu choice Show Sub Symbols to show hidden symbols.)

The menu choice is dimmed if:

  • No document is selected
  • The selected icon is a leaf (no child icons)
  • The selected diagram is not connected
  • The selected icon is marked invalid
  • The selected icon is already expanded

Expand Substructure

This menu choice expands the symbol structure tree the whole way down for the selected document. This also expands sub symbols that are hidden, but those sub symbols are still hidden after this operation. (Use the menu choice Show Sub Symbols to show hidden symbols.)

The menu choice is dimmed if:

  • The selected icon is a leaf (no child icons)
  • The selected diagram is not connected
  • The selected icon is marked invalid
  • The selected icon is already expanded

If no document is selected, all icons will be expanded.

Collapse

This menu choice collapses the selected document, i.e. the sub symbols are not shown after this operation. A collapsed document has a small triangle drawn below the icon to indicate that it is collapsed.

The menu choice is dimmed if:

  • The selected icon is a leaf (no children icons)
  • The selected document is not connected
  • The selected icon is marked invalid
  • The selected icon is already collapsed

If no document is selected, all icons will be collapsed. A collapsed document does not affect a corresponding document file opened in an editor, i.e. it does not have to be closed or saved.

Show Sub Symbols

This menu choice is used to specify which sub symbols of the selected document that should be shown or hidden. The sub symbols can be documents, instance diagrams, pages, or associations. If a More symbol is selected, the operation applies to the parent document, which becomes selected instead.

Only the sub symbols one level down from the selected document is affected, not the complete symbol substructure. The menu choice is dimmed if there is no selection or the selected symbol has no sub symbols.

Note:

This menu choice does not expand or collapse the document.

The following dialog is opened:

Figure 32 : The Show Sub Symbols dialog

  • Show all sub symbols for <document>
    This option shows all sub symbols for the selected document. It is a shortcut for selecting all sub symbols in the list below.
  • Show these
    This option shows the sub symbols that are selected in the list, and hides the sub symbols that are unselected. Already shown sub symbols are pre-selected when the dialog is opened. The list is a multiple selection list that toggles the state of the selected item.

Hide

This menu choice hides the selected non-root document and its substructure. The document and its substructure is replaced by a More symbol, which is always placed last of the symbols on that level. If such a symbol already existed in the parent document, the document is hidden under the same More symbol. The symbol's count of hidden documents is updated.

The menu choice is dimmed if there is no selection, or the selected document is a root document.

By double-clicking on the More symbol, the Show Sub Symbols dialog is opened.

View Options

This menu choice sets options for controlling the appearance of the Organizer window, as well as options for which icon attributes to show.

The options are set in a modeless dialog, i.e. the Organizer can continue working without waiting for the dialog to be closed. The options are saved in the system file.

The following dialog is opened:

Figure 33 : The View Options dialog

The figure above shows the default settings. The settings made in the dialog are preserved as default values the next time the dialog is invoked.

Tree mode

The Tree mode section contains options for the two different tree presentation modes available in the chapters (see "Presentation Modes" ).

  • Indented list
  • Vertical tree

Menu bar

The Menu bar section contains options for which menu choices that are available (see "Long and Short Menus" ).

  • Long
  • Short

Show

The Show section contains options for which window parts, documents and file attributes to show. The options are available as items in a multiple selection list, which can be selected or deselected. Options already turned on are pre-selected when the dialog is opened.

  • Association symbols
    Show/hide association symbols (links to associated documents).
  • CM Groups
    This option governs whether CM Groups should be displayed or not. By default, CM Groups are visible. However, note that they are not shown in vertical tree mode (see "Presentation Modes" ).
  • Dashed diagrams
    Show/hide dashed diagrams.
  • Dependency symbols
    Show/hide dependency symbols (links to documents which a document is depending on).
  • File access permissions
    Add/remove the file access permissions for connected files. An access permission can have one of the following values:
    rw Readable and writable
    r- Only readable
    -w Only writable
    -- Neither readable nor writable
    In list mode, the permissions are added in front of the file names, if they are shown. In tree mode, the permissions are added on a separate line under each node in the document structure tree, just above the file names if they are shown.
  • File directories
    Complements the File names option below. Add/remove the directory path of the connected files, in the same location as File names. If the File names option is set, the directory path is added in front of the file name. The path added is determined by the Source Directory option; see "Set Directories" .
  • File names
    In list mode: Add/remove a column of connected file names to the documents.
    In tree mode: Add/remove a line of text with the connected filename under each node in the document structure tree. The texts do not overlap; document symbols are separated to make space for the full text.
    If a document is not connected to a file, [unconnected] is shown.
  • Footer file
    Show/hide the Footer File icon.
  • Header file
    Show/hide the Header File icon.
  • Instance diagrams
    Show/hide instance diagrams.
  • Link file
    This option sets the visibility of the Link File icon. The link file icon is hidden by default.
  • Page symbols
    Show/hide page symbols below SDL, HMSC, OM, and SC diagrams.
  • Separator symbols
    Show/hide separators between diagrams. Separator symbols show how the generated code will be separated into different files. The lines between diagrams are broken by two vertical or horizontal bars where the separations occur.

Figure 34 : Separators between SDL diagrams

  • Source directory
    Show/hide the Source Directory.
  • Status bar
    Show/hide the status bar of the Organizer Main window.
  • System file
    This option sets the visibility of the System File icon. The system file icon is visible by default.
  • Target directory
    Show/hide the Target Directory.
  • Tool bar
    Show/hide the tool bar of the Organizer Main window.
  • Type names
    Show/hide the type of all icons and documents in textual form, e.g. Object Model, Module, Block, System file, Chapter, etc. The text is placed to the left of the name of the icon.
  • Virtuality
    Show/hide the virtuality of SDL type diagrams in textual form.

Chapter Options

This menu choice is used to set chapter properties.

The following dialog appears:

Figure 35 : The Chapter Options dialog

The first chapter number is defined in the text field. This number defines the chapter number to use for the first chapter symbol of type Chapter 1, Chapter 1.1, Chapter 1.1.1 or Chapter 1.1.1.1 in the Organizer View area. For example, if the first chapter number is specified as "3.2", then an initial chapter symbol of type Chapter 1 will get chapter number 3. If the initial chapter symbol instead is of type Chapter 1.1.1.1, it will get a chapter number of 3.2.1.1.

The maximum TOC chapter level decides which chapter symbols that will be visible in the table of contents when a print is done from the Organizer. A maximum TOC chapter level of zero will only show chapter symbols of type Chapter, while a chapter level of 4 will show all chapter symbol types in the table of contents.

Set Scale

Sets the scale (20%-800%) used in the Organizer window. The setting is saved in the system file.

Generate Menu

The Generate menu contains the following menu choices (menu choices within parenthesis are not available in short menu mode):

  • Analyze
  • (Make)
  • Stop Analyze/Make (UNIX only)
  • Targeting Expert
  • SDL Overview
  • State Overview
  • (CPP2SDL Options)
  • (Convert to PR/MP)
  • (Convert to GR)
  • (Convert GR to CIF)
  • (Convert CIF to GR)
  • (Convert State Chart to SDL)
  • (Edit Separation)
  • (Dependencies)
  • (Merge ASN.1)

Analyze

This menu choice analyzes the selected SDL or TTCN system. If there is no SDL or TTCN system selected, the Organizer operates on the first SDL system found in the Organizer. The menu choice is dimmed if:

  • A job using the Analyzer is already running.
  • No SDL diagram is present in the Organizer and no TTCN system is selected.
  • The selected SDL diagram or TTCN document is not connected.
  • The selected icon is marked invalid.

The Analyze SDL variant of this menu choice is described below, followed by the Analyze TTCN variant.

Analyze SDL

This menu choice starts the Analyzer for one or several related SDL diagrams. If modified information exists in the current system structure, the user should first save it. See "The Save Before Dialog" for more information.

Any SDL diagram can be selected for analysis, but in practice at least the parent block diagram will be the source of the analysis. If no SDL diagram is selected, the first SDL diagram found in the Organizer view will be used. The diagram will be analyzed in its context and together with its substructure.

Options for the Analyzer are specified in the modal dialog below. The settings are saved in the system file and persist until the next time the dialog is invoked for the same system.

Figure 36 : The Analyze dialog

The Analyze SDL Settings

Note: Normal versus full analyze (make)

In the Analyze and the Make dialog, the user can choose between the normal Analyze/Make and the Full Analyze/Make buttons. The last used button (normal or full) will be the default when any of these two dialogs is used the next time. The last used button will also determine if normal or full analyze/make will be used when invoking operations via the quick buttons Analyze, Make, Simulate and Validate. It is possible to toggle between normal or full analyze/make by pressing <Ctrl+T>.

  • Select other(s)
    When the Analyze dialog is opened, the selection in the Organizer decides the SDL diagrams that will be analyzed. The part that will be considered for analysis is the diagram itself, all diagrams below the diagram and all parent diagrams. A used package is considered to be a parent diagram. All diagrams below a used package will be analyzed.
    This button opens a sub dialog, with the possibility to analyze SDL diagrams other than the one selected in the Organizer. For instance, it is possible to analyze two out of many blocks from the same level in one SDL system. In the sub dialog, just select the diagrams that you want analyzed. Note that you only have to select the top diagram you want analyzed, all sub diagrams will be included in the analysis. The initial label in the Analyze dialog (Analyze <diagram type> <diagram name>) will change to reflect the new selections you have made.
  • Include hidden symbols
    Decides if hidden SDL symbols should be included in SDL/PR or not. Read more about hidden SDL symbols in Symbol Visibility > Hide and Symbol Visibility > Show.
    If hidden symbols are excluded, then lines to and from hidden symbols will also be excluded. One exception to this is that flow lines going to a symbol that will be excluded, are reconnected to the first following symbol that will be included, if there is one and only one such symbol.
    To use include expressions is another way to decide if SDL/GR symbols should be included in SDL/PR or not. Read more about include expressions in Include Expression.
  • Macro expansion
    Run the Macro Expander before the analysis. (See "The Macro Expander" for more information.)
  • Case sensitive SDL
    Use case sensitive SDL names. If this option is selected, keywords must be all upper or lower case.
  • Syntactic analysis
    Perform a syntax check.
  • Semantic analysis
    Perform a semantic check. This option automatically sets the option Syntactic analysis.
    Pressing the Details button pops up the Semantic Analysis - Details dialog. These options are only used if a semantic analysis is done. They are also not used if a system or package was not the target for the analysis. For more information on these options, see "Performing Semantic Check" .
    • Check output semantics
    • Check unused definitions
    • Check optional parameters
    • Check trailing parameters
    • Check references
    • Check missing else answers
    • Check missing answer values
    • Allow implicit type conversion
    • Include optional fields in make operator
    • Generate a cross reference file
      Generate a cross reference file when performing the analysis. In the text field, a file name is proposed with the diagram to be analyzed as prefix and .xrf as extension. The file is by default generated in the Target Directory.
    • Generate an instance information file
      Generate an instance information file when performing the analysis. In the text field, a file name is proposed with the diagram to be analyzed as prefix and .ins as extension. The file is by default generated in the Target Directory.
  • ASN.1 encode/decode parameter
    This option decides if the ASN.1 encode/decode buffer can be accessed from SDL. If the option is on, it is also possible to specify how the ASN.1 encode/decode buffer should be represented in SDL. For more information, see "SDL Encoding and Decoding Interfaces" .
  • ASN.1 keyword substitution file
    Change keywords in files output by asn1util according to file. If no file is specified, the keywords in the file asn1util_kwd.txt in the SDL Suite installation are used. For more information, see "Keywords substitution" .
  • Error limit
    The error limit before aborting the analysis (0-1000). A limit of 0 (zero) means that there is no error limit.
  • Log expressions deeper than
    The performance of the Analyzer depends to a large extent on the depth of the SDL expressions to be resolved. This option is used to emit warnings when the depth of an expression exceeds a certain value (0-100). A limit of 0 (zero) means that no warnings will be issued.
  • Filter command
    If used, this option allows preprocessing of files before the different analyzer phases. An executable (script), possibly with parameters, should be specified in the text field. The executable will be called before the analyzer processes any file in any phase. The executable will be called with two parameters:
    • The first parameter is the file that is going to be processed.
    • The second parameter identifies the analyzer phase that is going to be executed. Three different phases are distinguished: import (before conversion to PR), macro (before macro expansion) and parse (before syntax analysis).
  • Echo Analyzer commands
    Print (echo) all Analyzer commands in the Organizer Log as they are executed.
  • Terminate Analyzer when done
    Terminate the Analyzer process after analysis is done. By default, the Analyzer process is left running in the background after completed analysis.

The options above are forwarded to the Analyzer when the analysis process starts.

The Analyze SDL Buttons

  • Analyze
    Starts the Analyzer in the background and closes the dialog. Status information from the ongoing analysis is shown in the Organizer Log window. Among those diagrams that are considered for analysis according to the top of the dialog (Select other(s)), only the following diagrams are really analyzed:
    • Diagrams that had errors the last time the system was analyzed.
    • Changed diagrams.
    • Diagrams that any diagram mentioned above are depending on.
  • Full Analyze
    Has the same effect as the Analyze button, except that it forces all diagrams that are considered for analysis to be analyzed.
  • Set
    Saves the Analyzer option settings and closes the dialog, but does not perform an analysis.

Analyze TTCN

This menu choice is used to analyze a TTCN system and/or to generate a Flat View for a TTCN system.

Options for the Analyze process are specified in the modal dialog below. A selectable Generate Flat View phase is executed in the analyze process. The settings are saved in the system file and persist until the next time this dialog is invoked for the same TTCN system.

Figure 37 : The Analyze TTCN dialog

The Analyze TTCN Settings

  • Analyze
    Selecting this radio button means that the complete TTCN document will be considered for analysis. This radio button is set as default when the dialog is invoked.
  • Generate Flat View
    Selecting this radio button means that a Flat View will be generated for the selected TTCN system. For a detailed description of this operation, see "Generating a Flat View" .
  • Generate and analyze Flat View
    Selecting this radio button means that a Flat View will be generated for the selected TTCN system and it will be considered for analysis.
  • Enable forced analysis
    This option is described in "Enable Forced Analysis" .
  • Verbose report
    This option is described in "Verbosity" .
  • Error limit
    The error limit before aborting the analysis (0-1000). A limit of 0 (zero) means that there is no error limit.

The Analyze TTCN Buttons

  • Analyze
    Starts the Analyzer and closes the dialog. Status information from the ongoing analysis is shown in the ITEX log. For more information, see "The TTCN Suite Logs" .
  • Set
    Saves the Analyzer option settings and closes the dialog, but does not perform an analysis.

For more information about this dialog, see "The TTCN Analyzer" .

See also 32 Analyzing TTCN Documents (in Windows).

Make

This menu choice makes the selected SDL or TTCN system, or the selected SDL block or process diagram. If a Build Script containing commands to the SDL to C Compiler is selected, that file will be used as input to the SDL to C Compiler, without opening the Make dialog (see "Build Scripts" .

If no document or file of the above mentioned type is selected, the Organizer operates on the first SDL system found in the Organizer. The menu choice is dimmed if:

  • A job using the Analyzer is already running
  • There is no SDL system diagram in the chapters and no TTCN system is selected
  • The selected diagram is not connected
  • The selected icon is marked invalid

If modified information exists in the current system structure, the user should first save it; see "The Save Before Dialog" .

The SDL Make variant of this menu choice is described below, followed by the TTCN Make variant.

SDL Make

Options for the Make process are specified in the modal dialog below. An analysis phase is executed as part of the Make process. The existing Analyzer options as set in the Analyze dialog are used.

Figure 38 : The Make dialog

Code Generation Options

  • Select other(s)
    When the Make dialog is opened, the selection in the Organizer decides the diagrams that will be used when code is created. This button opens a sub dialog, with the possibility to generate code for diagrams other than those selected in the Organizer. For instance, it is possible to generate code for two out of many blocks on the same level in one SDL system. In the sub dialog, select the diagrams that you want to include in the code generation process. Note that you only have to select top diagrams, sub diagrams will be automatically included. The initial label in the Make dialog (Make <diagram type> <diagram name>) will change to reflect the new selections you have made.
  • Analyze & generate code
    This option generates code, and performs an analysis if necessary. If not set, the settings below do not affect the Make process.
  • Code generator
    The code generator is selected with this option menu. The following code generators are supported to date:
    • Cbasic (see 56 The Cadvanced/Cbasic SDL to C Compiler)
    • Cadvanced (see 56 The Cadvanced/Cbasic SDL to C Compiler and 61 The Master Library)
    • X1 (UNIX only)
  • Prefix
    The type of prefix for variables is selected with this option menu: Full (default), Entity Class, No or Special. For more information, see "Prefixes" .
  • Separation
    The type of modularity is selected with this option menu: No (default), Full or User Defined. For more information, see "Selecting File Structure for Generated Code - Directive #SEPARATE" .
  • Capitalization
    The type of capitalization is selected with this option menu: Lower Case or As Defined (default). For more information, see "Case Sensitivity" .
  • Generate environment header file
    If this option is set, a header file is generated containing the definitions of the SDL system's interface to the environment. For more information, see "System Interface Header File" .
  • Generate environment functions
    If this option is set, environment functions are generated. For more information, see "The Environment Functions" .
  • Generate signal number file
    If this option is set, a file with signal numbers will be generated. For more information, see "Generation of Support Files" .
  • Generate ASN.1 coder
    If this option is set, encoders and decoders from ASN.1 modules will be generated. This option is only available through a special license.
  • Generate SDL coder
    If this option is set, encoders and decoders from SDL will be generated, see "Type description nodes for SDL types" . This option is only available through a special license.

Makefile Options

  • Makefile
    This option controls makefile creation/usage. If not set, a makefile will not be created/used.
  • Generate makefile
    Generate a makefile (default). Choose the file by adding a .m extension to the separation name of the selected unit and the file is created in the directory specified as target directory. See "Target Directory" for more information.
  • Generate makefile and use template
    Generates a makefile and appends the specified, user defined, template at the end of the makefile. Two "hooks" are provided in the generated part of the makefile: USERTARGET and USERLIBRARIES. This enables the user to define his own targets as well as adding properties in the make file. The recommended file name extension for a template file is .tpm.
    In the template file, USERTARGET is used to add additional object files to the link script in the generated make file, by defining this name as a list of object files.
    In the template file, USERLIBRARIES is used to add library modules, for example -lm or -lsocket, to the link script in the generated make file, by defining this name as a list of libraries.
    The template file can also contain the compilation scripts for the object files specified as USERTARGET.

Example 2 : Contents of a UNIX Make Template File

USERTARGET = sctenv$(sctOEXTENSION)
USERLIBRARIES = -lm -lsocket

# Dependencies and actions
sctenv$(sctOEXTENSION): sctenv.c
$(sctCC) $(sctCPPFLAGS) $(sctCCFLAGS) \
$(TARGETDIRECTORY) sctenv.c \
$(sctIFDEF) -o sctenv$(sctOEXTENSION)

  • Use makefile
    Specifies an existing makefile to use.

Compile & Link Options

  • Compile & link
    This option controls if compilation and linking should take place. If set, compilation or linking will be done according to the settings below.
  • Standard kernel
    Use one of the available standard kernels. The kernel is selected from this option menu. The available kernels depend on the license configuration.
    Each kernel is available in versions for different compilers. You should use a kernel corresponding to a compiler you have access to on your system.
    On UNIX, the following kernels are available. There are versions for standard ANSI C compilers (e.g. cc) and for the GNU C compiler (gcc).
    • Simulation
    • gcc-Simulation
    • RealTimeSimulation
    • gcc-RealTimeSimulation
    • PerformanceSimulation
    • gcc-PerformanceSimulation
    • Application
    • gcc-Application
    • ApplicationDebug
    • gcc-ApplicationDebug
    • Validation
    • gcc-Validation
    • TTCN-Link
    • gcc-TTCN-Link
      In Windows, the following kernels are available. There are versions for the Borland C++ compiler (bcc32) and the Microsoft Visual C++ compiler (cl).
    • Borland Simulation
    • Microsoft Simulation
    • Borland RealTimeSimulation
    • Microsoft RealTimeSimulation
    • Borland PerformanceSimulation
    • Microsoft PerformanceSimulation
    • Borland Application
    • Microsoft Application
    • Borland ApplicationDebug
    • Microsoft ApplicationDebug
    • Borland Validation
      Information about the kernels can be found in "Compilation Switches" and "Libraries" 2. A list of the available kernels can also be found in the file sdtsct.knl (see "File sdtsct.knl" ).
  • Use kernel in directory
    Specifies a non-standard kernel to use. The user should specify the directory where the actual kernel is stored.
  • Preprocess C file
    This option informs the SDL to C Compilers if the SDL C Compiler Driver (SCCD) should be invoked. See 60 SDL C Compiler Driver (SCCD) for more information.

Miscellaneous Options

  • Target directory
    This option is by default set to Target Directory. This option determines where the generated files will be put in the file system.
  • File name prefix
    The names of the generated files will be prefixed by the text put in this field.

Dialog Buttons

Note:

For information about how Make/Full Make relates to Analyze/Full Analyze and quick buttons, see "Normal versus full analyze (make)" .

  • Make
    Starts the code generation in the background and closes the dialog. Status from the ongoing Make process is shown in the Organizer Log window. First the time stamps of the SDL files, e.g *.sbk, *.spr, *.spd, etc, are compared with all their dependent generated c-file counterparts. Only those diagrams that have a newer timestamp are converted from SDL GR to PR, analyzed, and code is generated. After any needed code is generated the make function corresponding to the specified compiler is called to compile and/or link the system. Situations where a make will prove useful are when the following circumstances exist:
    • Diagrams had errors the last time the system was analyzed.
    • Diagrams were changed.
    • Diagrams for which the target files have been removed.
    • Diagrams that any diagram mentioned above are depending on.
  • Full Make
    Has the same effect as the Make button, except that it forces the entire system to be regenerated, even if only certain parts needs to be regenerated. After any needed code is generated the make function corresponding to the specified compiler is called to compile and/or link the system.
  • Set
    Saves the Make option settings and closes the dialog, but does not perform a make.
  • Analyze Options
    Opens the Analyze dialog to set the analyze options. The Set button returns to the Make dialog.

TTCN Make

This menu choice is used to make (generate code, compile and link) a TTCN system.

For more information about this operation, see 28 The TTCN to C Compiler (on UNIX) or 33 The TTCN to C Compiler (in Windows).

Stop Analyze/Make (UNIX only)

This menu choice stops an ongoing analyze/make operation. The Analyzer tool is also stopped. (The Analyzer tool normally remains resident in memory for the rest of the SDL suite session once the first analyze/make is performed, and this menu choice is then renamed to Stop Analyzer. Using this menu choice is one way to free memory if needed.) Several commands, such as Analyze, Make, Convert to PR/MP and Convert to GR, are not available when the Analyzer is processing data. Stopping the Analyzer enables these commands again.

A message with the essence "Analyzer could not be stopped" may be issued as a response to this command; in this case, repeat the menu choice until the message "Analyze/make stopped" is issued in the message area.

Targeting Expert

This menu choice starts the Targeting Expert tool. See 59 The Targeting Expert for more information.

SDL Overview

This menu choice generates an SDL overview diagram for the selected SDL diagram as the top diagram. The menu choice is dimmed if:

  • No SDL diagram is present in the Organizer.
  • The selected SDL diagram is not connected.
  • The selected icon is marked invalid.
  • The system file is read-only.

If modified information exists in the current system structure, the user should first save it; see "The Save Before Dialog" .

Any SDL diagram can be selected for generation. If no SDL diagram is selected, the first SDL diagram found in the Organizer view will be used.

Figure 39 : The Generate SDL Overview dialog

  • Name of Generated SDL Overview
    Specifies the name of the generated Overview diagram. The Organizer proposes a name based on the SDL diagram which the Overview should be generated from.
  • Use Expanded Diagrams Only
    Controls whether the resulting SDL Overview should comprise all diagrams that are included in the SDL diagram substructure, or only include the diagrams which are expanded (i.e. visible in the Organizer).
  • Include Procedures & Operators
    Governs if SDL procedure and operator diagrams should be included in the SDL Overview.
  • Include States
    Controls whether state symbols should be added to the SDL Overview or not.
  • Include Lines
    Governs whether lines (such as channels and signal routes) should be added to the SDL Overview or not.
  • Minimum Symbol Width
  • Minimum Symbol Height
    These slide bars control the minimum size the tool will apply on symbols. (Symbols will be shrunk, if possible, to make the SDL Overview smaller.)
  • Margin
    This slide bar specifies the distance (in any direction) between symbols at one SDL level and the enclosing frame (the boundaries of the enclosing SDL symbol).
  • Distance between Lines
  • Distance between Symbols
    These slide bars define what distance will be inserted between lines that otherwise will overlap each other in the generated SDL Overview diagram.
  • Generate
    Causes the generation of the overview diagram to start. The user is informed about the progress of the generation in the Organizer Log window. The generated SDL Overview is added as a root document directly after the SDL structure for which the Overview diagram is generated. An SDL Editor opens and presents the Overview diagram.

State Overview

This menu choice is used to generate a state overview information file from an SDL system or a group of state charts. The state overview can be viewed either as state matrices in the Text Editor or as state charts in the State Chart Editor.

Before selecting this menu choice, make sure that the information source (an SDL system or one or more state charts) is selected directly or indirectly. For instance, you can select a group of state charts by selecting the chapter symbol that contains the state charts.

When you select this menu choice, a dialog is displayed where you can:

  • Decide if the information source should be SDL or state charts.
  • Change SDL system, if several SDL systems were selected in the Organizer. Use the first change button for this.
  • Pick out individual state charts, among the state charts that were selected in the Organizer. Use the second change button for this.
  • Decide name and directory for the generated state overview information file.
  • Decide if an Organizer symbol should be created.
  • Decide if the Text Editor should show the state overview information as state matrices.
  • Decide if the State Chart Editor should show the state overview information as state charts.

CPP2SDL Options

This menu choice is available if a C or C++ Import Specification is selected. For more information, see "The CPP2SDL Tool" .

Convert to PR/MP

This menu choice converts the selected diagram/document to textual form. SDL/GR is converted to SDL/PR and TTCN-GR is converted to TTCN-MP. If no diagram/document is selected, the Organizer operates on the first SDL system found in the Organizer. The menu choice is dimmed if a job using the Analyzer is already running.

The Convert to PR (SDL) variant of the menu choice is described below, followed by the Convert to MP (TTCN) variant.

Convert to PR (SDL)

The SDL variant of the Convert to PR/MP menu choice generates a formatted (pretty printed) SDL/PR file. Input is either an SDL/PR file or an SDL/GR diagram structure.

If modified information exists in the current system structure, the user should first save it; see "The Save Before Dialog" .

Figure 40 : The Convert to PR dialog

  • Source:
    <type> <name>
    Converts an SDL/GR diagram structure to PR. The top of the diagram structure appears in the name of the button.
    If an SDL diagram is selected, that diagram will be converted. Otherwise, the first SDL diagram structure found in the Organizer will be converted. If no SDL diagrams are found, this option is dimmed, in which case the name of the button is "<No SDL/GR diagram selected>". This will also be the case if the SDL diagram is not connected, or if its icon is marked invalid.
    If the SDL diagram to be converted has an expanded diagram substructure visible in the Organizer, this substructure is also converted. All PR code is put in the destination PR file.
  • PR file
    Generates a pretty printed PR file from an existing PR file, which is specified in the input field. By default, this file is read from the Source Directory.
  • Write reserved words in
    Specifies whether reserved words in SDL are to be written in lower case or upper case.
  • Expand included PR files
    Expands SDL/PR include files found in /*#INCLUDE...*/ comments.
  • Destination PR file name
    Specifies the pretty printed PR file to generate. The default name uses the selected diagram name as prefix and .sdl as extension. By default, this file is stored in the Target Directory.
    If no file name is provided, the user is warned and no conversion is performed.
    An Overwrite confirmation dialog is issued if the user changes the suggested file name and specifies a file that already exists.
  • Convert
    Generates the pretty printed PR file and closes the dialog. Status from the ongoing conversion process is shown in the Organizer Log window.
  • Analyze Options
    Opens the Analyze dialog to set the analyze options. The Set button returns to the Convert to PR/MP dialog.

Convert to MP (TTCN)

This TTCN variant of the Convert to PR/MP menu choice converts a TTCN-GR document to a TTCN-MP text file.

For more information about Convert to MP, see "Exporting a TTCN Document to TTCN-MP" or "Converting to TTCN-MP"

Convert to GR

This menu choice converts a textual file to one or more graphical diagrams. A TTCN-MP file is converted to TTCN-GR diagrams, and an SDL/PR file is converted to SDL/GR diagrams. The menu choice is dimmed if a job using the Analyzer is already running.

The Convert to GR (SDL) variant is described below, followed by the Convert to GR (TTCN) variant.

Convert to GR (SDL)

The Convert to GR dialog is in SDL mode when the radio button Convert SDL/PR to SDL/GR is on (see Figure 41).

Figure 41 : The Convert to GR dialog in SDL mode

  • Source PR file name
    Specifies the PR file to convert.
  • Write reserved words in
    Specifies whether reserved words in SDL are to be written in lower case or upper case.
  • Expand included PR files
    Expands SDL/PR include files found in /*#INCLUDE...*/ comments.
  • Destination directory for generated SDL/GR
    Specifies the directory where to put the generated SDL diagrams. By default, the Source Directory will be used (see "Set Directories" ).
  • Convert
    Generates the SDL/GR diagrams. The SDL/GR files are named in the same way as when saving unconnected documents in the Organizer, i.e. files are named so that no files are overwritten. Status from the ongoing conversion process is shown in the Organizer Log window.
  • Analyze Options
    Opens the Analyze dialog to set the analyze options. The Set button returns to the Convert to GR dialog.

Convert to GR (TTCN)

The Convert to GR dialog is in TTCN mode when the radio button Convert TTCN-MP to TTCN-GR is on (see Figure 41).

For more information about the Convert to GR dialog in TTCN mode, see "Importing a TTCN-MP Document" or "Converting to TTCN-MP" .

Convert GR to CIF

This menu choice converts SDL/GR diagrams to the Common Interchange Format (CIF).

On UNIX, the Convert GR to CIF dialog is opened. For more information, see "Convert GR to CIF Dialog (UNIX only)" .

In Windows, the SDT2CIF converter tool is started. For more information, see "Graphical User Interface (Windows only)" .

Convert CIF to GR

This menu choice converts diagrams in Common Interchange Format (CIF) to SDL/GR diagrams.

On UNIX, the Convert CIF to GR dialog is opened. For more information, see "Convert CIF to GR Dialog (UNIX only)" .

In Windows, the CIF2SDT converter tool is started. For more information, see "Graphical User Interface (Windows only)" .

Convert State Chart to SDL

This menu choice transforms the selected State Chart to an SDL process diagram. For more information, see "Converting State Charts to SDL" .

Edit Separation

This menu choice inserts or edits a separation on the selected SDL diagram. It is dimmed if the selected diagram type is not one of system, system type, block, block type, process, process type, procedure, and package. This menu choice is only available if the system file can be changed.

Diagram separation symbols are used during code generation and controls both the splitting of the target into separate modules and the naming of these modules. For more information, see "Selecting File Structure for Generated Code - Directive #SEPARATE" . Separations can be shown in the diagram structure of the Organizer; see "Separator symbols" . Information about separations are stored in the system file.

Figure 42 : The Edit Separation dialog

  • No separate file
    No separation is to be used on this diagram; any existing separation is cleared. This option is disabled on system and package diagrams.
  • Separate file
    Inserts a separation on this diagram, i.e. the diagram and its substructure is generated separately. In the text field, the name of the separation is specified, i.e. the prefix of the files generated for this separation.

Dependencies

This menu choice introduces or removes dependencies between a selected document and other documents. A dependency symbol below a document indicates that the document is depending on another document. For instance, if an SDL system is depending on an ASN.1 document, then the SDL system must be re-analyzed each time the ASN.1 document is updated. A related symbol is the association symbol, see "Associate" .

This menu choice is only available if the system file can be changed.

Note:

Dependency links between SDL systems and C header files or ASN.1 documents are not required, but serve mainly as comments. The SDL Analyzer will re-analyze the SDL system automatically for such dependencies.

If a dependency icon is selected, this menu choice operates on the document the dependency icon is referring to, not the icon itself. Any document may depend on any other document, and a document may have be depending on more than one document.

The following dialog is opened:

Figure 43 : The Dependencies dialog

  • Select documents depending on <document>
    The multiple selection list displays the type and name of all documents in the Organizer structure. When the dialog is opened, all documents that the current document is depending on are selected, i.e. the list shows all dependencies for the document.
    By selecting a new document in the list, a dependency for the current document will be created. By deselecting a document in the list, the corresponding dependency link will be removed from the selected document's structure.

Merge ASN.1

This menu choice controls whether the ASN.1 files in an Organizer module should be merged (joined) into a single SDL package or not. For more information, see "Using the ASN.1 Utilities" .

Figure 44 : The Merge ASN.1 dialog

  • No ASN.1 merge
    The ASN.1 files in this Organizer module should not be merged; a separate SDL package is generated for each of the ASN.1 files.
  • Merge ASN.1, separate name
    The ASN.1 files in this Organizer module should be merged; one SDL package will be generated, containing all ASN.1 modules from the ASN.1 files. The name of the SDL package will be the same as the name of the Organizer module, and the separate name will be used for the code generation in a similar way as for ordinary ASN.1 files.

Tools Menu

The Tools menu contains the following menu choices:

  • Organizer Log
  • Link > Create Endpoint
  • Link > Traverse
  • Link > Link Manager
  • Link > Clear Endpoint
  • Search
  • Spelling > Comments
  • Spelling > All Text
  • Change Bars
  • Compare SDL Diagrams
  • Merge SDL Diagrams
  • Split
  • Join
  • Compare State Machines
  • Simulator Test > New Simulator
  • Simulator Test > Existing Simulator
  • Editors > Deployment Editor
  • Editors > HMSC Editor
  • Editors > MSC Editor
  • Editors > OM Editor
  • Editors > SDL Editor
  • Editors > State Chart Editor
  • Editors > Text Editor
  • Editors > TTCN Browser
  • SDL > Type Viewer
  • SDL > Coverage Viewer
  • SDL > Index Viewer
  • SDL > Simulator UI
  • SDL > Validator UI
  • SDL > Target Tester UI
  • TTCN > Find Table
  • TTCN > Access
  • TTCN > Simulator UI
  • UML Suite
  • Preference Manager

Organizer Log

This menu choice raises the Organizer Log window. The Organizer Log window can be raised automatically when the user performs an analysis or other forms of generation. There is only one Organizer Log window.

The Organizer Log window is described in "Organizer Log Window" .

Link > Create Endpoint

This menu choice creates an endpoint for the selected document. A document with an endpoint is recognized by a small triangle in the upper left corner of the document symbol. See "Link > Create Endpoint" .

This menu choice is only available if the system file can be changed.

Link > Traverse

This menu choice traverses a link for the selected document. A document with at least one link is recognized by a small black triangle in the upper left corner of the document symbol. See "Link > Traverse" .

Link > Link Manager

This menu choice opens the Link Manager's main window. For more information about the Link Manager, see "The Link Manager" .

Link > Clear Endpoint

This menu choice removes an existing endpoint for the selected document. See "Link > Clear Endpoint" .

This menu choice is only available if the system file can be changed.

Search

This menu choice searches for text in SDL, MSC, HMSC, Object Model, and State Chart diagrams. Textual documents (C Header, Text ASN.1, and Text Plain) are also searched if the Text Editor is used. (The Text Editor is used if the preference variable SDT*TextEditor is set to "SDT.") It is not possible to search in TTCN, Word or Generic documents with this menu choice. To search in TTCN documents, use TTCN > Find Table.

The document scope of the search depends on the selection:

  • If a module is selected, all searchable documents in that module will be searched.
  • If a chapter is selected, all searchable documents in that chapter will be searched.
  • If a root document is selected, all searchable documents in that document's substructure will be searched.
  • If there is no selection, all searchable documents in the Organizer will be searched.

The menu choice is dimmed if the selected document is not a root document, not connected, or marked invalid.

The search will only take place in diagrams that are connected and do not have an invalid status. The search will start in the selected diagram and continue in top-down order for the rest of the diagrams (the order is left-right in a tree view).

The search function will go through the list of diagrams and stop each time the search criteria, as set in the dialog below, matches. If a search/replace string or any option is changed when the search is stopped (a match is found or the user pressed Abort), these values become the basis when the search is continued.

The search process will open an editor window, if necessary, and select the matched search text.

The searching is based on ASCII character matching. All text fragments in symbols are searched, with a few restrictions (see below).

When all diagrams have been searched, a beep is issued and the message Search completed appears.

Dialog Fields and Options

The Search dialog contains the following fields and options.

  • Search for
    The text to search for. To the left of the text field, there is an option menu containing old search strings. To search again for a string that has already been searched for, select the search text in the option menu.
  • Replace with
    The text which is to replace the text searched for. Does not have to be specified.
  • Search in
    Two option menus where it is possible to restrict the search to a selected diagram or symbol type. For instance, you can find all SDL input symbols by not specifying any search text, and specifying "SDL" as a diagram type and "Input" as a symbol type.
  • Consider case
    If this option is set, search is case sensitive.
  • Wildcard search
    Specifies whether a wildcard matching will be used. In wildcard search the asterisk (`*') matches a sequence of zero or more characters of any kind, e.g. whether the search text dist*ution will find the text distribution or not.
  • Search substructure
    If this option is set, not only the selected diagram but also its diagram substructure will be searched.

Note:

Only the textual elements that are visible in an MSC will be searched. See "Diagram Options" .

Dialog Buttons

When the dialog is first opened, all buttons except Replace&Search and Replace All are enabled. When Search, Replace&Search or Replace All is pressed all fields and buttons are disabled except the Close button. (The Close button changes name during the search to Abort.) If a search string is found in an editor, it is selected and all buttons and fields are enabled.

When the first search or replace operation has been applied and control returns to the Search dialog, it is possible to perform a new search on the same diagram(s).

  • Search
    Searches for the search string. An editor is opened when the search string is found. If no text is supplied in the Search for field, a warning message appears. Confirming the message box will return control to the Search dialog.
  • Replace&Search
    Replaces the current match with the replace string and searches for the next match. An editor is opened when the search string is found.
  • Replace All
    Replaces all occurrences of the search string with the replace string. No editors are opened. However, diagrams with replaced text are loaded in the editor and gets a "dirty" state in the Organizer.
    Text in reference symbols and in kernel headings are not replaced.
  • Close/Abort
    The Close button closes the Search dialog. The Close button is temporarily renamed to Abort during search in diagrams. If Abort is pressed, the current search is stopped as soon as possible (when a new file is to be searched). After an Abort, the dialog remains on screen, ready for new input.

Search Restrictions

All data in the editors that affects the diagram structure maintained by the Organizer (primarily reference symbols and kernel headings in the SDL Editor) is regarded as read only during the search operation. That is, they are not affected by the search.

Externally editing (i.e. through means other than using replace) of a diagram during a search operation completely resets the search, i.e. the next search starts from the first diagram.

The search may fail if dialogs are opened in the editor during the search. In this case the editor blocks the continuation of the search process. To continue the search process, the editor dialog must be closed.

The Organizer's data is locked during the search process. This is normally not noticed since the Search dialog is modal, but the SDL Editor needs to access that data to perform operations affecting the diagram structure. The Organizer will deny the editor's requests to modify the data structure. The duration of the search process is the period of time during which the Search dialog is visible in the Organizer.

Fast Search

Fast search is invoked by pressing ctrl+F on the keyboard.

Fast search behaves like normal search, except that:

  • No dialog is used.
  • The replace functionality can not be used.
  • Consider case is always off.
  • Wildcard search is always off.
  • Search substructure is always on.

When Fast search is invoked, the message area displays the text that will be searched for. Initially, the text is Search for:. When you type on the keyboard with the mouse pointer over the drawing area, the characters will turn up in the message area. When you have typed the text pattern to search for, press enter or return to start the search operation.

The same search operation as for normal Search is used. If the search operation finds a match, you can search for another match by pressing enter or return once more in the Organizer window.

To finish the Fast search operation, click in the drawing area or select another operation.

The next time Fast search is invoked with ctrl+F, the search text that was used the last time is proposed as a search text once more. To use it, press enter or return. To use another search text, press ctrl+F once more or the delete key several times, to erase the search text.

Spelling > Comments

Check the spelling of comments in selected diagrams. Comments can be either comment symbols or /* C-style comments */

.

Note:

This command only works if the spelling checker ispell has been installed on your computer, and the preference SDT*ISpellCommand correctly identifies the ispell executable. ispell can be found on the internet and uses the same kind of license as the emacs text editor.

For spelling errors, the Spelling dialog appears, with the following possibilities:

  • Word replacement text field. Initially, the word from the diagram is presented here. One way to correct the spelling mistake is to correct the spelling in this text field and press the change button.
  • List of suggestions. For most words, the spelling checker will present possible corrections here. Click on a word in this list to update the word replacement text field. Double-click on a word to update the diagram.
  • Add button. Add the word currently in the word replacement text field to your personal dictionary.
  • Change button. Update the diagram with the word from the word replacement text field and find the next spelling error.
  • Ignore button. Ignore the current spelling error and find the next spelling error.
  • Ignore All button. Ignore all occurrences of the current spelling error during this session and find the next spelling error. For more "permanent ignorance", use the Add button.

Spelling > All Text

Works in the same way as Spelling > Comments, but all text is checked instead of just comment texts.

Change Bars

This menu choice is used to control the usage of change bars in SDL diagrams. A dialog with two options is opened:

  • Reset change bars for selected SDL diagrams
    This option is used to reset change bars in SDL diagrams that fall under the selection in the Organizer. Note that removing a change bar makes the diagram dirty, i.e. change bars cannot be removed from diagram files where you do not have write access. If this option is on, a second dialog will be opened telling you about the diagrams that the operation will be applied upon.
  • Create change bars when SDL changes occur
    This option is used to decide if change bars should be created when an SDL diagram is edited. This option is saved in the system file and is valid for all SDL diagrams in the system. The preference ChangeBars is used as default for new SDL systems. See "ChangeBars" .

Compare SDL Diagrams

This menu choice compares the contents of SDL diagram file pairs. A diagram file pair is constructed by matching an SDL diagram file loaded into the Organizer with an SDL diagram file with the same name, but in a different directory.

Note:

There is a similar operation in the SDL Editor for comparing one SDL diagram pair at a time. See "Compare Diagrams" .

The menu choice is dimmed if there are no SDL diagrams in the Organizer.

In the same way as for the Search menu choice, the compare operation is limited by the selection in the Organizer. Only SDL diagrams within the scope of the selection will be considered for the compare operation.

When the Compare SDL Diagrams menu choice is invoked, the compare SDL diagrams setup dialog appears.

Figure 45 : The Compare SDL Diagrams Setup dialog

In the compare SDL diagrams setup dialog, the following input parameters to the compare operation can be specified:

  • Compare source directory
    The directory specified here is used instead of the normal source directory to find SDL diagrams to compare the SDL diagrams in the Organizer with.
    • For SDL diagrams in the Organizer that are relative to the normal source directory, the relative part of the file path is kept, but the part of the file path that matches the normal source directory is replaced with a part of a path constructed from the diff source directory instead.
      For example, if the source directory is /home/lat (E:\home\lat in Windows) and the diff source directory is /opt/home/gn (E:\opt\home\gn), then the Organizer file /home/lat/demo/x.ssy (E:\home\lat\demo\x.ssy)
      will be compared with /opt/home/gn/demo/x.ssy (E:\opt\home\gn\demo\x.ssy), if that file exists.
    • For SDL diagrams in the Organizer that are not relative to the normal source directory, the directory part of the file path is replaced with diff source directory.
      For example, if the source directory is /home/lat (E:\home\lat in Windows) and the diff source directory is /opt/home/gn (E:\opt\home\gn), then the Organizer file /usr/local/lat/y.ssy (E:\usr\local\lat\y.ssy)
      will be compared with /opt/home/gn/y.ssy (E:\opt\home\gn\y.ssy), if that file exists.
  • Textual difference report: Summary
    When this option is chosen, a summary of found differences is printed for each diagram pair that is compared. If more than one diagram pair is compared, a summary for all compared diagram pairs is also printed. The textual difference report is printed in the Organizer Log window.
  • Textual difference report: Details
    When this option is chosen, detailed information about every found difference is printed as a textual report in the Organizer Log window.
  • Graphical difference report
    When this option is chosen, differences are shown in the SDL Editor, one difference group at a time.
  • Ignore moved or resized objects
    When this option is chosen, the compare operation tries to ignore reporting differences only caused by moved or resized symbols by using symbol ids. This option should only be used when comparing two versions of the same original diagram file: moved symbols cannot be accurately detected by using symbol ids when comparing two versions of a diagram that are both built from scratch.
  • Select and print differences
    When this option is chosen, pages from the compared diagram versions are printed, but only those pages that contain differences.

When the OK button in the dialog is pressed, the Organizer checks if a matching diagram can be found for all SDL diagrams in the operation. If that is not the case, a dialog appears to inform about this fact.

Figure 46 : The Compare SDL Diagram missing files dialog

Finally, the real compare operation starts in the SDL Editor. Read more about this in "Compare Diagrams" .

Merge SDL Diagrams

This menu choice compares the contents of SDL diagram file pairs in the same way as "Compare SDL Diagrams" does. The main difference is that this menu choice gives the possibility to merge differences: For each diagram pair, a new merge result diagram is created. Read more about how the actual merge is performed in "Merge Diagrams" .

Split

This menu choice is used to split one SDL diagram into two SDL diagrams. This menu choice can be applied several times to split one SDL diagram into several parts. This menu choice is, together with the menu choice Join, useful in situations where several people have to work simultaneously on one SDL diagram. The SDL diagram file is partitioned into several SDL diagram files and each person is given one part to work on.

To split an SDL diagram consisting of several pages, select the diagram symbol in the Organizer and select the Split menu choice. (It is also possible to select a page symbol associated with the diagram that should be split.)

A dialog appears with a list of all pages but the first one in the diagram, see Figure 47. Select a page to define how the SDL diagram should be split. All pages before the selected page will end up in the first SDL diagram part. The selected page and all pages after the selected page will end up in the second SDL diagram part.

Figure 47 : The first Split dialog

The Split button in the first Split dialog closes the dialog and brings up the second Split dialog, as shown in Figure 48. The second Split dialog is used to specify the files that the two resulting SDL diagram parts should be saved in.

Figure 48 : The second Split dialog

When the second Split dialog is closed with the Save button, the split operation is performed: The SDL Editor is loaded with the SDL diagram that should be split. Two new smaller SDL diagrams are created in the SDL Editor and saved under the file names specified in the second Split dialog.

The visible result of the Split operation is that the SDL Editor contains at least the diagram that was split and the resulting SDL diagram parts. Note that no additional symbols are created in the Organizer. The SDL diagram parts are accessed by opening the SDL diagram part files in the SDL Editor with the Open menu choice. It is of course possible to manually add symbols for the SDL diagram parts in the Organizer with for instance the Add Existing menu choice.

Join

This menu choice is used to join two SDL diagrams of the same type into one SDL diagram. This menu choice is, together with the Split menu choice, useful when several people have to work on the same SDL diagram at the same time.

Note that it is not necessary to do a Split before doing a Join. One way to work in parallel on the same diagram is to let one designer work on the existing SDL diagram, while another designer creates new pages destined for the same SDL diagram, in a new SDL diagram with the same type as the existing SDL diagram. A join operation when the parallel work is finished puts the new SDL pages in the correct SDL diagram.

The resulting SDL diagram is produced by copying the complete first diagram part and merging/joining pages from the second diagram part by copy and paste. This means that information that is common for all pages in an SDL diagram is taken from the first diagram part. This includes:

  • The diagram name and any other information in the header.
  • The information in the extended heading symbol.
  • The information in the use text symbol.

Another consequence of this way of working is that duplicate page names and reference symbol names emerging from the second diagram part are changed by the join operation to make them unique. Auto-numbered pages from the second diagram part will also have their names changed.

When the Join menu choice is invoked, the Join dialog appears, see Figure 49.

Figure 49 : The Join dialog

In the dialog, specify the names of the two SDL diagram files that should be merged. Pressing the Join button will close the dialog and start the Join operation.

The result of the Join operation is that three diagrams will be loaded in the SDL Editor; the two SDL diagram parts that act as input to the Join operation and a new and unsaved SDL diagram that contains all the pages from both the input diagrams. The first thing that you will normally do after a Join operation is to save the new SDL diagram in a file. After that, it might be appropriate to check the new SDL diagram in the context of the SDL system with the Analyzer.

Compare State Machines

This menu choice is used to compare state machines with other state machines. This menu choice makes it possible to keep state machines expressed as a group of state charts consistent with state machines expressed as processes in an SDL system.

Before selecting this menu choice, make sure that the information sources (SDL systems and/or state charts) are selected directly or indirectly. For instance, to compare the only SDL system in the Organizer with all state charts in the Organizer, make sure that there is no selection in the Organizer by clicking in the background. The Organizer will interpret this as "everything is selected".

When you select this menu choice, a dialog is displayed where you can:

  • Specify the two groups of state machines that should be compared. A group of state machines is either the state machines in an SDL system or a group of state charts. It is only possible to choose among the state machines that were selected in the Organizer. Use the Select buttons to select individual SDL systems or state charts.
  • Specify the two state overview information files that will be generated and compared.
  • Specify if SDL procedure calls and/or state chart call actions should be compared.
  • Specify if SDL outsignals and/or state chart send events should be compared.

When the dialog is closed, two state overview information files are generated. A state overview describes a state machine in a normalized form:

  • For an SDL system, diagram type inheritance and diagram type instantiation have been removed.
  • For a state chart, state hierarchies (states in states) have been removed. The same rules as when converting a state chart to SDL are used, for more information, see "Converting State Charts to SDL" .

The compare operation compares the two generated state overview information files in the following way:

  • State machines are matched by their names. For instance, SDL process A is matching state chart A.
  • States are matched by their names.
  • Transitions are matched by a combination of from-state name, insignal name and to-state name

.

Note:

The compare operation does not compare all the details for a transition. For instance, the conditional expression in an SDL decision symbol is not compared with the guard condition in a state chart transition.

If the compare operation finds anything that does not match, this is reported in the Organizer Log. You use the Organizer Log quick button Show Error to navigate to the SDL diagram or state chart with an entity that did not match anything in the other group of state machines.

Simulator Test > New Simulator

This menu choice is used to execute test cases in the simulator for an SDL system. Test cases can be described either as MSCs or as simulator UI input scripts (*.cui). A description of how to express MSCs in this context can be found in Using MSCs as test cases.

When this menu choice is invoked, a dialog appears with a list of all MSCs and input scripts. In the dialog, it is possible to select test cases that should be executed. The selection in the Organizer decides:

  • primarily the SDL system to be used,
  • but also the default test case selection in the dialog.

When the dialog is closed, an SDL simulator is generated and each selected test case is run. When all test cases have been executed, the Organizer Log will contain a one-line summary for each test case, with information about if the test case passed or failed. For test case failures, the MSC editor will pop up, showing the symbol in the MSC that failed (this happens only if the test case was expressed as an MSC). To be able to examine test case failures in detail, run each test case that fails separately, because then the MSC editor will show the place of the MSC test case failure and the textual output from the simulator will contain information about the test case failure.

Using MSCs as test cases

MSC test cases are MSCs written in a special way. MSC test cases are high-level test cases that are auto-converted to low-level simulator UI input script test cases before they are executed.

When MSCs are used as test cases, you can:

  • send in a signal to the system and check that the expected signal is received as a response from the system.
  • check that a process instance is in a certain state.
  • check that a process instance variable has a certain value.
  • check if a process instance exists.
  • ...

Figure 50 illustrates MSC test case building blocks that are described in the text below.

Figure 50 MSC test case building blocks

MSC instance symbols are used in the following way in MSC test cases:

  • Use an MSC instance symbol called environment or env_1 or something similar as an instance to send and receive signals to and from the SDL system.
  • Use one or several MSC instance symbols to represent the SDL system. If you use one instance, give it the same name as the SDL system (for instance accesscontrol). If you use several instances, give each the name of an SDL process instance that you want to send and receive signals to and from (for instance panel or panel:1).

To send a signal into the system, draw an MSC signal from the environment instance to one of the instances representing the SDL system. Specify the signal name and any parameters that you know about.

To check that a signal is sent out from the system, draw an MSC signal from an instance representing the SDL system to the environment instance. Also here, you should specify the signal name and any parameters. The check is done by matching a text string created from the MSC with the actual textual output from the simulator. You can use the * character (matching any characters) if you for instance do not want to specify all parameters in the MSC.

There are several overlapping ways of specifying the process instance a signal should be sent to or from. Two of them involves a mapping table in an MSC text symbol. The text should look something like this (one line with a `=' for each mapping rule):

process id mappings:
instance accesscontrol = panel
signal display = panel
  • First of all, the SDL suite finds out if there is a comment symbol connected to the signal. If there is, and the text is something like to panel or from panel, the SDL suite uses panel as the process instance name (with :1 added because no : with a number was specified).
  • Second, the SDL suite finds out if there is a signal mapping rule matching the current signal name. If there is, the process instance name in that rule is taken.
  • Third, the SDL suite finds out if there is an instance mapping rule matching the instance name of the instance representing the SDL system that is attached to the current signal. If there is, the process instance name in that rule is taken.
  • If no process instance name has been found yet, then the MSC instance name of the instance representing the SDL system is taken as the SDL process instance name.

It is possible to include any simulator command in an MSC test script by attaching an MSC action symbol to the environment instance, and typing the simulator commands in it. One line for each command.

This can for instance be used to declare macros representing parameter values. If you have done add-macro myMacroName 5 in an action symbol, you can type $myMacroName instead of 5 as the value of a parameter. Macros can be defined in a separate MSC and used in normal MSC test cases. Just make sure that the macro MSC is executed before the normal MSC test cases when you do a simulator test.

There are three textual shortcuts that can be used in an action symbol:

  • To check that an SDL process instance is in a certain state:
check state (panel) = IDLE
  • To check the value of a variable in an SDL process instance:
check variable (panel) DoorNo = 1
  • To check if an SDL process instance exists or not:
check exists (panel) = false

The MSC reference symbol can be attached to the environment instance. Type in a name of a sub MSC test script that should be executed. This is a way to avoid repeating the same information in many places. It can for instance be used in the beginning of a test script to perform common initialization of the system.

Simulator Test > Existing Simulator

Same as "Simulator Test > New Simulator" , except that an already created simulator is used. Before the normal simulator test dialog (used to specify test cases to execute), a file selection dialog appears, where a simulator executable can be specified.

Editors > Deployment Editor

Adds a Deployment diagram symbol to the Organizer view, and starts the Deployment Editor. The symbol is added at the same place as when using the Add New command.

Editors > HMSC Editor

Adds a HMSC diagram symbol to the Organizer view, and starts the HMSC Editor. The symbol is added at the same place as when using the Add New command.

Editors > MSC Editor

Adds an MSC diagram symbol to the Organizer view, and starts the MSC Editor. The symbol is added at the same place as when using the Add New command.

Editors > OM Editor

Adds an Object Model diagram symbol to the Organizer view, and starts the OM Editor. The symbol is added at the same place as when using the Add New command.

Editors > SDL Editor

Adds an SDL System diagram symbol to the Organizer view, and starts the SDL Editor. The symbol is added at the same place as when using the Add New command.

Editors > State Chart Editor

Adds a State Chart diagram symbol to the Organizer view, and starts the State Chart Editor. The symbol is added at the same place as when using the Add New command.

Editors > Text Editor

Adds a Plain Text document symbol to the Organizer view, and starts the Text Editor. The symbol is added at the same place as when using the Add New command.

Editors > TTCN Browser

Adds a TTCN module symbol to the Organizer view, and starts the TTCN Browser. The symbol is added at the same place as when using the Add New command.

SDL > Type Viewer

This menu choice starts the Type Viewer. It is dimmed if there is no SDL diagram in the Organizer, or if the preference SDT*StartInformationServer is set to false. Only one instance of the Type Viewer exists. If the Type Viewer has already been started, its window is raised.

If a Referenced Diagram Type icon, an Instance Diagram icon or a Dashed diagram icon is selected in the Organizer, the Type Viewer selects the corresponding symbol when this menu choice is used.

The Type Viewer is described in 46 The SDL Type Viewer.

SDL > Coverage Viewer

This menu choice starts a Coverage Viewer. A new instance of the Coverage Viewer is started each time this command is selected.

The Coverage Viewer is described in 48 The SDL Coverage Viewer.

SDL > Index Viewer

This menu choice starts an Index Viewer. A new instance of the Index Viewer is started each time this command is selected.

The Index Viewer is described in 47 The SDL Index Viewer.

SDL > Simulator UI

This menu choice starts a new, empty Simulator UI. Several Simulator UI's may exist at the same time.

The Simulator UI is described in "Graphical User Interface" .

SDL > Validator UI

This menu choice starts a new, empty Validator UI. Several Validator UI's may exist at the same time.

The Validator UI is described in "Graphical User Interface" .

SDL > Target Tester UI

This menu choice starts a new, empty SDL Target Tester UI. The SDL Target Tester UI is described in "Graphical User Interface" .

TTCN > Find Table

This menu choice invokes the find table operation on a selected TTCN system. In Windows, this functionality is not available and the menu choice is dimmed.

For more information about the find table operation on UNIX, see "Finding Tables" . For more information about finding tables in Windows, see "Finding and Sorting Tables" .

TTCN > Access

This menu choice starts a TTCN Access application for a selected TTCN document/system.

Note:

This operation is only available on UNIX.

For more information, see 22 TTCN Access.

TTCN > Simulator UI

This menu choice starts a TTCN simulator UI.

For more information about this, see 29 The TTCN-SDL Co-Simulator (on UNIX) or 34 The TTCN-SDL Co-Simulator (in Windows).

UML Suite

This menu choice starts the Telelogic Tau UML Suite. This menu choice is dimmed if the UML Suite is not installed on your system.

Preference Manager

This menu choice starts the Preference Manager. Only one instance of the Preference Manager exists. If the Preference Manager has already been started, its window is raised.

The Preference Manager is described in 3 The Preference Manager.

Bookmarks Menu

The Bookmarks menu contains the following menu choices:

  • Add Bookmark
  • Edit Bookmarks
  • More Bookmarks

Add Bookmark

This menu choice opens a dialog where a new bookmark can be created. The information needed is the location (a URL or a SDTREF), and a name for the bookmark. If desired, a systemfile can be specified that will be loaded together with the SDTREF.

Edit Bookmarks

Edit Bookmarks will open a dialog with a list with all bookmarks. After selecting a bookmark the buttons will have the following effect:

  • OK - all changes made will be saved and the dialog will close.
  • Open - the selected bookmark will be opened
  • Edit - provides a dialog with the information form the selected bookmark, where the information can be edited.
  • Remove - removes the selected bookmark from the list.
  • Cancel - all alteration made will be disregarded and the dialog will be closed.

More Bookmarks

This choice will appear if more than 25 bookmarks are present. The dialog appearing is the same as in the Edit Bookmark menu choice. Selecting the desired bookmark and clicking on the Open button will open the bookmark.

Help Menu

For more information about Help menus in Telelogic Tau, see "Help Menu" . Two of the Organizer Help menu choices are described in more detail below.

About All

This menu choice starts an operation that presents version information about the individual tools in your SDL Suite configuration. The information is presented in the Organizer Log window. The produced information might look like this:

About All. Version information:
Help Tool Version 4.4.0
Link Manager Version 4.4.0
MSC Editor Version 4.4.0
OM InfoServer Version 4.4.0
OM/SC/HMSC/DP Editor Version 4.4.0
Organizer Version 4.4.0
Preference Manager Version 4.4.0
SDL Coverage Viewer Version 4.4.0
SDL Editor Version 4.4.0
SDL Index Viewer Version 4.4.0
SDL Type Viewer Version 4.4.0
SDT Welcome Window Version 4.4.0
Text Editor Version 4.4.0

About All. Additional version and kernel information:
Information Server version 4.4.0
SDT Analyzer
SDT Analyzer 4.4.0
SDT CPP2SDL 4.4.0
ASN.1 Analyzer 4.4.0
SDL Targeting Expert: Version 4.4.0

Simulation kernel:
2 lrwxrwxrwx 1 lat develop 66 May 5 16:05 sctworld.o
RealTimeSimulation kernel:
2 lrwxrwxrwx 1 lat develop 68 May 5 16:05 sctworld.o
...

License Information

Opens a dialog with license information for all tools in Telelogic Tau.

Figure 51 : The License Information dialog

The dialog contains the following:

  • The names of the tools that are included in Telelogic Tau and that are separately licensed.
    Each name consists of the prefix SDT or ITEX, followed by a hyphen and an abbreviated name for the tool. See the table below for a reference to these abbreviations.

Abbreviation | Telelogic Tau Tool(s)
Telelogic | Organizer
SDT-Base | SDL Editor, SDL Analyzer and SDL Viewers.
SDT-OME | Object Model Editor and State Chart Editor
SDT-MSCE | Message Sequence Chart Editor and High-Level Message Sequence Chart Editor
SDT-Cbasic | Cbasic SDL to C Compiler
SDT-Cadvanced | Cadvanced SDL to C Compiler
SDT-Cmicro | Cmicro SDL to C Compiler
SDT-Cmicro-Bodybuilder | Cmicro BodyBuilder
SDT-Cmicro-Tester | SDL Target Tester UI
SDT-X1 (UNIX only) | <Configuration dependent>
SDT-Validator | Validator Library
SDT-Simulator | Simulator Library
SDT-Application | Application Library
SDT-Performance | Performance Simulation Library
SDT-TTCN-Link | Interactive link to ITEX
ITEX-Base | TTCN Browser, TTCN Table Editor and TTCN Analyzer
ITEX-Access | ITEX Access API Library
ITEX-Simulator | ITEX Simulator
ITEX-C-Code-Generator | ITEX C Code Generator
1

The SDT-X is a generic name that allows to introduce new code generators that are under development. In "normal" installations, it has no meaning.

  • On UNIX, beneath each tool, the following information is displayed:
    • Current licenses, along with the name of the host computer, the user identity and the time the license was checked out
    • Remaining available licenses
    • Total available licenses
    • If a license has expired, the information would be replaced by:
      SDT-<ToolName>
      Expired: <Date>
  • A Give Up License button which allows you to release the interactive licenses in your current SDL suite session.
    This will disable licensed tools without closing them, making the licenses available to other users. You can reclaim these licenses at a later time, if there are corresponding licenses available, by using the Get License button, allowing you to continue working in the licensed applications.
  • A Get License button which allows you to reclaim licenses released by either the use of the Give Up License button or the automatic release of licenses.
    Licenses will be automatically released if the idle time limit, set in the preference LicenseTimeout, is exceeded. For more information, see "LicenseTimeout" .
    The reclamation of licenses is limited in the sense that it will only attempt to reclaim lost licenses once, implying that you will have to save your work in and restart the tools for which licenses could not be obtained.
1

X is reserved for future extensions in the SDL suite applied to code generation.

2

The TTCN-Link kernel is described in the ITEX manuals.


Shortcuts

There are several ways to invoke an operation in the Organizer. An operation is usually available in the menu bar and in at least one pop-up menu. Menus can be operated via the keyboard (keyboard navigation). Several operations are also available in the tool bar or via keyboard accelerators. For instance, the Print operation can be invoked by:

  • Choosing the menu choice in the File menu in the menu bar with the mouse.
  • Choosing the menu choice in the File menu in the menu bar with keyboard navigation. (<Alt+F> P)
  • Using the keyboard accelerator <Ctrl+P>.
  • Pressing the Print quick button.
  • Choosing the menu choice in the File sub menu of the background pop-up menu. (The Print menu choice is also available in several other pop-up menus.)

The sections below are "Pop-Up Menus" , "Keyboard Accelerators" and "Quick Buttons" .


Pop-Up Menus

This section describes pop-up menus for different types of icons. The operations available depend on the type of file that icon represents.

The following tables lists the menu choices in the pop-up menus and a reference to the corresponding menu choice in the menu bar.

On SDL Diagrams (but not SDL Overview Diagrams)

Print Selected | "Print > Selected"
Set Directories | "Set Directories"
Edit > Edit | "Edit"
Edit > Remove | "Remove"
Edit > Connect | "Connect"
Edit > Disconnect | "Disconnect"
Edit > CM Group | "Configuration > Group File"
Edit > CM Update | "Configuration > Update"
Edit > Associate | "Associate"
Edit > Update Headings | "Update Headings"
View > Expand | "Expand"
View > Expand Substructure | "Expand Substructure"
View > Collapse | "Collapse"
View > Show Sub Symbols | "Show Sub Symbols"
View > Hide | "Hide"
Generate > Analyze | "Analyze"
Generate > Make | "Make"
Generate > Stop Analyze/Make | "Stop Analyze/Make (UNIX only)"
Generate > Generate SDL Overview | "SDL Overview"
Generate > Convert to PR | "Convert to PR/MP"
Generate > Convert to GR | "Convert to GR"
Generate > Edit Separation | "Edit Separation"
Generate > Dependencies | "Dependencies"
Search | "Search"
Change Bars | "Change Bars"
Compare SDL Diagrams | "Compare SDL Diagrams"
Merge SDL Diagrams | "Merge SDL Diagrams"
Create Endpoint | "Link > Create Endpoint"
Traverse Link | "Link > Traverse"
Clear Endpoint | "Link > Clear Endpoint"
Type Viewer | (On SDL type diagrams only) "SDL > Type Viewer" . Opens the Type Viewer with the type diagram selected.

On MSC and SDL Overview Diagrams

Print Selected | "Print > Selected"
Set Directories | "Set Directories"
Edit > Edit | "Edit"
Edit > Remove | "Remove"
Edit > Connect | "Connect"
Edit > Disconnect | "Disconnect"
Edit > CM Group | "Configuration > Group File"
Edit > CM Update | "Configuration > Update"
Edit > Associate | "Associate"
Hide | "Hide"
Dependencies | "Dependencies"
Search | "Search"
Change Bars | "Change Bars"
Create Endpoint | "Link > Create Endpoint"
Traverse Link | "Link > Traverse"
Clear Endpoint | "Link > Clear Endpoint"

On Instance and Dashed Diagrams

Edit | "Edit" .
Type Viewer | "SDL > Type Viewer" . Opens the Type Viewer with the diagram selected.
Hide | "Hide"

On Pages

Print Selected | "Print > Selected"
Edit | "Edit" .
Hide | "Hide"

On Associations

Associations have the same pop-up menu as the associated document. All menu choices operate on the associated document, except Hide and Remove that operate on the association symbol itself.

On HMSC, Object Model and State Chart Diagrams

Print Selected | "Print > Selected"
Set Directories | "Set Directories"
Edit > Edit | "Edit"
Edit > Remove | "Remove"
Edit > Connect | "Connect"
Edit > Disconnect | "Disconnect"
Edit > CM Group | "Configuration > Group File"
Edit > CM Update | "Configuration > Update"
Edit > Associate | "Associate"
Edit > Update Headings | "Update Headings"
View > Expand | "Expand"
View > Expand Substructure | "Expand Substructure"
View > Collapse | "Collapse"
View > Show Sub Symbols | "Show Sub Symbols"
View > Hide | "Hide"
Dependencies | "Dependencies"
Search | "Search"
Change Bars | "Change Bars"
Create Endpoint | "Link > Create Endpoint"
Traverse Link | "Link > Traverse"
Clear Endpoint | "Link > Clear Endpoint"

On Modules

Print Selected | "Print > Selected"
Edit | "Edit"
Remove | "Remove"
CM Group | "Configuration > Group File"
CM Update | "Configuration > Update"
View > Expand | "Expand"
View > Expand Substructure | "Expand Substructure"
View > Collapse | "Collapse"
View > Show Sub Symbols | "Show Sub Symbols"
Merge ASN.1 | "Merge ASN.1"
Search | "Search"
Change Bars | "Change Bars"
Compare SDL Diagrams | "Compare SDL Diagrams"
Merge SDL Diagrams | "Merge SDL Diagrams"

On Chapters

Print Selected | "Print > Selected"
Edit | "Edit"
Remove | "Remove"
CM Group | "Configuration > Group File"
Search | "Search"
Compare SDL Diagrams | "Compare SDL Diagrams"

On More Symbols

Show Sub Symbols
"Show Sub Symbols"

On System File

CM Group | "Configuration > Group File"
CM Update | "Configuration > Update"

On Link File

Link Manager
"Link > Link Manager"

On Source and Target Directories

Set Directories
"Set Directories"

On the Background

Expand Substructure | "Expand Substructure"
Collapse | "Collapse"
View Options | "View Options"
Set Scale | "Set Scale"
File > New | "New"
File > Open | "Open"
File > Save | "Save"
File > Save As | "Save As"
File > Print All | "Print > All"
File > Set Directories | "Set Directories"
File > PC Drives | "PC Drives"
File > Compare System | "Compare System"
File > Merge System | "Merge System"
File > Import SDL | "Import SDL"
File > Exit | "Exit"
Edit > Add New | "Add New"
Edit > Add Existing | "Add Existing"
Edit > Paste As | "Paste As"
Edit > Go to Source | "Go To Source"
Convert to GR | "Convert to GR"
Tools > Organizer Log | "Organizer Log"
Tools > Link Manager | "Link > Link Manager"
Tools > Search | "Search"
Tools > Change Bars | "Change Bars"
Tools > Compare SDL Diagrams | "Compare SDL Diagrams"
Tools > Merge SDL Diagrams | "Merge SDL Diagrams"
Tools > Type Viewer | "SDL > Type Viewer"
Tools > Coverage Viewer | "SDL > Coverage Viewer"
Tools > Index Viewer | "SDL > Index Viewer"
Tools > Simulator UI | "SDL > Simulator UI"
Tools > Validator UI | "SDL > Validator UI"
Tools > Target Tester UI | "SDL > Target Tester UI"
Tools > UML Suite | "UML Suite"
Tools > Preference Manager | "Preference Manager"
Editors > Deployment Editor | "Editors > Deployment Editor"
Editors > HMSC Editor | "Editors > HMSC Editor"
Editors > MSC Editor | "Editors > MSC Editor"
Editors > OM Editor | "Editors > OM Editor"
Editors > SDL Editor | "Editors > SDL Editor"
Editors > State Chart Editor | "Editors > State Chart Editor"
Editors > Text Editor | "Editors > Text Editor"
Editors > TTCN Browser | "Editors > TTCN Browser"
Help > Contents Help > On Organizer Help > On Shortcuts Help > New Features Help > Latest News Help > Index Help > Search Help > Telelogic Home Page Help > Help Desk Help > About Organizer | For more information about Help menu choices, see "Help Menu" .
Help > License Information | "License Information"


Keyboard Accelerators

Apart from the general keyboard accelerators, as described in "Keyboard Accelerators" , the following accelerators can be used in the Organizer:

Accelerator
Reference to corresponding command or quick button
Ctrl+A
"Add New"
Ctrl+B
"Connect"
Ctrl+E
"Edit"
Ctrl+I
"Import SDL"
Ctrl+K
"Stop Analyze/Make (UNIX only)"
Ctrl+M
"Make"
Ctrl+R
"Disconnect"
Ctrl+T
Toggles between Analyze/Make (default) and Full Analyze/Full Make. A text is presented in the message area to confirm that <Ctrl+T> has been pressed: Either "Organizer will now use full analyze/make" or "Organizer will now use normal analyze/make". For more information, see "Normal versus full analyze (make)" .
Ctrl+0 (zero)
"Set Directories"
Ctrl+1
"Organizer Log"
Ctrl+2
"Add Existing"
Ctrl+3
"Associate"
Ctrl+4
"Analyze"
Ctrl+5
"SDL Overview"
Ctrl+6
"SDL > Type Viewer"
Ctrl+7
"SDL > Coverage Viewer"
Ctrl+8
"SDL > Index Viewer"
Ctrl+9
"Preference Manager"
Del
"Remove" . For documents that can not be removed (non-root SDL diagrams), see "Disconnect" .
arrow up
Select the symbol one step up (move the selection)
Shift+arrow down
"Move Up" .
Ctrl+Shift+
arrow up
Place the selected symbol first in the Organizer structure.
arrow down
Select the symbol one step down (move the selection)
Shift+arrow down
"Move Down"
Ctrl+Shift+
arrow down
Place the selected symbol last in the Organizer structure.


Quick Buttons

The following quick buttons are special to the Organizer's Main window. The general quick buttons are described in "General Quick-Buttons" . Each quick button in the Organizer has a preference parameter that specifies if the button is shown or hidden; see "Organizer Preferences" . As default, all quick buttons except New and Add Existing are shown.

New
Creates a new system; see "New" .

Save
Performs a silent Save All of all diagrams including the system file. Does not bring up the Save dialog, except if diagrams are modified and unconnected, or no system file exists. Corresponds to the Save All button in the Save dialog; see "Save" .

Print
Brings up the Print dialog, see 5 Printing Documents and Diagrams.

Analyze
Analyzes the part of the system defined by the selected diagram or the whole system. Brings up a Save Before dialog if any diagram is modified and not saved. Does not bring up the Analyze dialog. Corresponds to the Analyze button in the Analyze dialog. The current Analyze options are used. The same restrictions and checks apply as described in "Analyze" .

Make
Makes the part of the system defined by the selected diagram or the whole system, i.e. generates code, compiles and links it. Does not bring up the Make dialog. Corresponds to the Make button in the Make dialog. The current Analyze and Make options are used. The same restrictions and checks apply as described in "Make" .

Generate SDL Overview
Generates an SDL overview diagram for the selected diagram or the whole system. Does not bring up the SDL Overview dialog. Corresponds to the Generate button in the Generate SDL Overview dialog. The current Generate SDL Overview options are used. The same restrictions and checks apply as described in "SDL Overview" .

Simulate
Generates a simulator for the part of the system defined by the selected diagram or the whole system, and starts a Simulator UI (see "Simulator/Validator UI Started from Quick Buttons" ). Does not bring up the Make dialog if the simulator needs to be regenerated. If a simulation kernel has not been selected in this dialog, the default simulation kernel is used. The default simulation kernel is determined by the preference Organizer*DefaultSimulator. The default value is "SCTADEBCOM" which is the same as using the standard kernel Simulation in the Make dialog. The same restrictions and checks apply as described in "Make" .

Validate
Generates a validator for the part of the system defined by the selected diagram or the whole system, and starts a Validator UI (see "Simulator/Validator UI Started from Quick Buttons" ). Does not bring up the Make dialog if the validator needs to be regenerated. If a validation kernel has not been selected in this dialog, the default validation kernel is used. The default validation kernel is determined by the preference Organizer*DefaultValidator. The default value is "SCTAVALIDATOR" which is the same as using the standard kernel Validation in the Make dialog. The same restrictions and checks apply as described in "Make" .

Generate Cross References
Generates a cross reference file for the current system and presents the information in the Index Viewer. An index symbol is added in the Organizer view. Does not bring up the Analyze dialog. Corresponds to setting the Generate a cross reference file option in this dialog. The same restrictions and checks apply as described in "Analyze" and "Semantic analysis" .

Add New
Adds a new document as root; see "Add New" .

Add Existing
Adds an existing document as root; see "Add Existing" .

Move Down
Moves the selected symbol one step down in the Organizer structure. For more information about moving symbols, see "Ordering" .

Move Up
Moves the selected symbol one step up in the Organizer structure. For more information about moving symbols, see "Ordering" .

Toggle Pages
Shows or hides page symbols below diagram symbols in the Organizer structure.

Organizer Log
Opens the Organizer Log window; see "Organizer Log" .

Simulator/Validator UI Started from Quick Buttons

When the Simulate quick button is used and if the generated simulator already was loaded in a Simulator UI, the same Simulator UI will be reused for the newly generated simulator. If no Simulator UI is active, a new Simulator UI will be started. However, if there already are other started Simulator UI's, the user has the choice of selecting one of these to load the generated simulator in.

The following dialog is opened:

Figure 52 : The Simulator/Validator dialog

  • Start new UI
    Starts a new Simulator UI and loads the simulator.
  • Use existing UI
    From the list box, one of the active Simulator UI's can be selected to load the simulator in. If a simulator already was running in the selected Simulator UI, that simulator will be terminated.

The same applies also for a validator and the Validator UI.


Organizer Log Window

The Organizer log window is a sub window to the main window. It works as a console for the Telelogic Tau tools. The window can be visible (raised or iconified) or not visible on the screen. All log information is output to this window independently of whether the window is visible or not.

The window is used in the following situations:

  • To log information from the Analyze and Make process.
  • To log the activities when an SDL system is imported.
  • When files are checked during the Open command. Inconsistent files are reported.
  • To show status information from the Generate tools.
  • Other tools, such as ITEX and tools started with dynamic menus, may also use the window to output textual information.

The window is opened or raised when the menu choice Organizer Log is selected from the Tools menu, or when something is written to the log. The preference ShowLogLevel controls which output to the window should cause a raise of the window (see 3 The Preference Manager).

There is only one Organizer Log window. The Organizer main window is not locked for user input when the Organizer Log window is visible.

Figure 53 : The Organizer Log window

Quick Buttons

The following quick buttons are special to the Organizer Log window. The general quick buttons are described in "General Quick-Buttons" . Each quick button in the Organizer Log window has a preference parameter that specifies if the button is shown or hidden; see "Organizer Preferences" . All quick buttons in the Organizer Log are shown by default.

Close
Exactly the same as Close in the File menu.

Clear Log
Exactly the same as Clear Log in the Edit menu; see "Clear Log" .

Navigate Down
Move to the next error visible in the Organizer Log. See "Log Options" for details.

Navigate Up
Move to the previous error visible in the Organizer Log. See "Log Options" for details.

Show Error
Exactly the same as Show Error in the View menu; see "Show Error" .

Help on Error
Exactly the same as Help on Error in the View menu; see "Help on Error" .

Analyze
Exactly the same as the Analyze quick button in the Organizer Main window; see "Analyze" .

Show Organizer
Exactly the same as Show Organizer in the Tools menu; see "Show Organizer" .

File Menu

See "File Menu" .

Edit Menu

The following menu choices are available in the Organizer log window Edit menu:

Copy

This menu choice copies the selected text to the clipboard buffer.

Select All

This menu choice selects all text in the Organizer Log window.

Clear Log

This menu choice clears all text in the Organizer Log window.

Log Options

This menu choice lets you decide how error, warning and information messages from the Analyzer should be handled in the Organizer Log:

  • The Filter text field can be used to specify warning messages that should not be shown.
  • The navigation level decides if the navigate up and down quick buttons should navigate through:
    • Error messages
    • Error and warning messages
    • All messages

The default value for the filter is taken from the preference Organizer*LogFilter. The default value for the navigation level is taken from the preference Organzier*LogNavigationLevel.

Tools Menu

The following menu choices are available in the Tools menu of the Organizer log window:

Show Organizer

This menu choice raises the Organizer's Main window.

Show Error

This menu choice opens an editor and shows an object/text that corresponds to a selected error/warning. If no text in the log is selected, the menu choice operates on the first error/warning in the log, which becomes selected. If this menu choice is invoked several times without changing the selection manually, the selection is updated automatically to point to the next error/warning before opening the editor and selecting the corresponding object/text.

Help on Error

This menu choice activates the Help tool on the selected error/warning or the next found error/warning. The selection is not updated automatically when selecting this command repeated times (as opposed to Show Error, above).


System File

The Organizer maintains a system file that contains a description of all files that are included in the system, together with all settings the user has made to this particular system. The default file name extension for a system file is .sdt.

In addition, a system window state file contains information about window positions and sizes, and it uses the extension .sdt.state.

Contents of the System File

The contents of the system file summarizes the information that the Organizer manages:

  • Source Directory and Target Directory.
  • Link file reference (used by the Link Manager) and information about endpoints in the Organizer view.
  • All document names are listed, both with logical names and file names. The fact that document names are present means that the Organizer will have a robust recovery when files are manipulated outside the Organizer.
  • Associations and dependencies are stored as indexes to other documents for a document.
  • The names of all chapters and modules are listed.
  • The names of all Control Unit files.

The system file may contain a mapping of directory paths on Windows and UNIX to allow the system to be accessed on both platforms. See "Windows and UNIX File Compatibility" for more information.

A number of options are also stored in the system file, but only if they differ from the values in the preference file or if the preference Organizer*AllPreferences is on. The options are:

  • Window options as set in the View Options and Set Scale dialogs
  • Analyze options as set in the Analyze dialog
  • Make options as set in the Make dialog
  • Print options as set in the Print > Selected dialog

In addition, information about collapsed, hidden and selected documents are saved to enable the Organizer to open with the same appearance as when the system file was saved. However, simply changing which documents are collapsed, hidden and selected will not mark the system file as "dirty" in the Organizer.

Format of the System File

The system file is a line-oriented, human-readable text file. The system file is divided into sections. Each section contains lines formatted in the same way. Any lines before the first section are ignored, but saved for the next system file save. This means that it is possible to have user defined comments in the beginning of the file.

Caution!

The sections that describe the diagram and document structure should not be modified by the user unless absolutely necessary. Modifying these sections in a way that errors or inconsistencies are introduced may corrupt the system file.

The file has the following format:

<file> ::= <comments> SDT-SYSTEM-4.4 (<drives> | $)
(<dir> | $) (<links> | $)
(<diagram> | $) (<view> | $) (<analys> | $)
(<make> | $) (print | $)

<comments> ::= <comment>*
<comment> ::= Any line of ASCII characters not beginning with "SDT-SYSTEM-".

<drives> ::= [DRIVES] <drive>*
<drive> ::= <Windows dir> <UNIX dir>

<dir> ::= [SOURCE-TARGET-DIRECTORY] <option>*
<links> ::= [LINKS] <option>*

<diagram> ::= [DIAGRAMS] <dia>*
<dia> ::= <indent> <type> <name>
(<path> | <fileName> | %unconnected%)
<viewState> <timeStamp> <separateName>
<associations> <dependencies>

<view> ::= [VIEWOPTIONS] <option>*
<analys> ::= [ANALYSEROPTIONS] <option>*
<make> ::= [MAKEOPTIONS] <option>*
<print> ::= [PRINTOPTIONS] <option>*

<Windows dir> ::= <string>
An Windows path. This is either a drive letter and a colon (e.g. C:) or a full path (e.g. C:\SDL). UNC paths can be used (e.g. \\MYHOST\SDL). If you include a trailing backslash you must also include a trailing slash in the corresponding <UNIX dir>.
<UNIX dir> ::= <string>
A UNIX directory path corresponding to the <Windows dir>. If you include a trailing slash you must also include a trailing backslash in the corresponding <Windows dir>.

<indent> ::= <int>
The indentation level. 0 is root, -1 is used for chapters.
<type> ::= <int>
Type of document, module or chapter. If the diagram has some kind of virtuality, the value is factored with a number with the base 100. The value corresponds to the kind of virtuality. These numbers correspond to an enumerated value found in the file sdt.h. If the diagram is an instance, a value of 1000 will be added to the type.
<name> ::= <string>
Logical name of diagram or document.
<path> ::= <string>
File path including a directory.
<fileName> ::= <string>
File name.
<viewState> ::= <integer>
Viewing state, consisting of four weighted booleans for separation, expanded, shown and selected states:
Separation + 2*NotExpanded + 4*NotShown + 8*Selected.
<timeStamp> ::= <integer>
Last time the file was modified, and that the Organizer was aware of. When the Organizer reads the system file, only files with modification dates later than the time stamp are checked for correctness.
<separateName> ::= <string>
Name of separation. Only applicable for units that are separately analyzed.

<associations> ::= <string>
A string of space separated values referencing associated documents, e.g. "1 4 5". The values index documents in the DIAGRAMS section.
<dependencies> ::= <string>
A string of space separated values referencing documents that this document is depending on, e.g. "1 4 5". The values index documents in the DIAGRAMS section.

<option> ::= (<option-name> = <option-value>)
<option-name> ::= <string>
Any option found in the named dialogs.
<option-value> ::= <string>
Any valid value bound to an option.

If a section is missing entirely from the system file, a warning will be logged. If no recognizable sections could be found, the file is not a valid system file.

When loading system files, warnings will be registered in the Organizer Log window if any non-recognized option is encountered, but not if an option never was initialized.

The Drives Section

The purpose of the DRIVES section in the system file is to achieve file compatibility between UNIX and Windows systems. It specifies the drive table; a mapping between Windows and UNIX directory paths. See "Windows and UNIX File Compatibility" for more information.

The path format of the current platform is used for directory paths stored in the system file: UNIX path names on UNIX systems (i.e. starting with a slash `/' and directories separated by slashes), and Windows path names on Windows systems (i.e. starting with a drive letter "x:" and directories separated by backslashes `\', or using the UNC format "\\<host>\file").

Diagrams with file specifications in an incorrect format are marked as Invalid in the Organizer.

When reading the system file on Windows systems, file specifications in UNIX format are converted to Windows format using the mapping in the DRIVES section, if possible, including converting slashes to backslashes. When the system file is saved, the file specifications are saved in Windows format, i.e. they are not converted back to UNIX format.

On UNIX systems, file specifications in Windows format are converted to UNIX format using the mapping in the DRIVES section, if possible, including converting backslashes to slashes. When the system file is saved, the file specifications are saved in UNIX format, i.e. they are not converted back to Windows format.

Example 3

The DRIVES section of the system file looks like this:

[DRIVES]
C:\TEMP /tmp
\\MYHOST\STORAGE /home/user

The file specification /tmp/a.ssy in the system file is converted to C:\TEMP\a.ssy.

The file specification /home/user/mydir/a.ssy is converted to
\\MYHOST\STORAGE\mydir\a.ssy.

The file specification /usr/local/dir/a.ssy is converted to \usr\local\dir\a.ssy. Since no drive or host name could be matched, the file will not be found and the diagram will be marked as Invalid in the Organizer.

Options in the System File

A number of sections contain options for the Organizer, representing values that can be set in the Organizer dialogs. If an option in the file is not recognized by the Organizer, it will be ignored, and if an option is not included in the file, a default preference value will be used. A few of the options have no corresponding preference parameters.

The following tables list the Organizer options that are saved in the system file. The user should not normally need to know or change these options in the system file. However, when running the SDL suite in batch mode on UNIX, it may be useful to change some options by editing a system file to be submitted as input to sdtbatch. See "Batch Facilities" for more information.

The options must appear in the correct section of the system file, but the ordering of options within a section is not important. The options are stored in the system file according to the format:

NameOfOption=Value

The option names and option values are case insensitive.

Possible and allowed values are not specified; the user should run the Preference Manager in order to obtain a reference to the permitted values.

SOURCE-TARGET-DIRECTORY Section

Option | Default | Corresponding Preference
AbsolutePath | false | Organizer*AbsolutePath
SourceDirectory | "" | Organizer* SourceDirectory
TargetDirectory | "" | Organizer* TargetDirectory

VIEWOPTIONS Section

Option | Default | Corresponding Preference
Scale | 100 | SDT* Scale
ShowDashed | true | Organizer* ShowDashed
ShowDependencies | true | Organizer*ShowDependencies
ShowDirectories | true | Organizer* ShowDirectories
ShowFileNames | true | Organizer* ShowFileName
ShowGroups | true | Organizer* ShowGroups
ShowInstances | true | Organizer* ShowInstances
ShowLinkFile | false | Organizer* ShowLinkFile
ShowLinks | true | Organizer* ShowLinks
ShowLongMenus | true | Organizer* ShowLongMenus
ShowPages | false | Organizer* ShowPages
ShowPermissions | true | Organizer* ShowPermissions
ShowSeparators | true | Organizer* ShowSeparators
ShowStatusBar | true | Organizer* Statusbar
ShowSystemFile | true | Organizer* ShowSystemFile
ShowToolBar | true | Organizer* Toolbar
ShowTypeName | false | Organizer* ShowTypeName
ShowVirtuality | true | Organizer* ShowVirtuality
TreeRepresentation | List | Organizer* TreeRepresentation

ANALYSEROPTIONS Section

Option | Default | Corresponding Preference
AllowImplicitTypeConv | false | Organizer* AllowImplicitTypeConv
ASN1KeywordFile | false | Not available
ASN1KeywordFileName | "" | Organizer*ASN1KeywordFileName
ASN1Parameter | false | Not available
CaseSensitiveSDL | false | SDT*CaseSensitive
CoderBufferInSDL |  | Organizer*CoderBufferInSDL
EchoAnalyzerCommands | false | Organizer* EchoAnalyzerCommands
ErrorLimit | 30 | Organizer* ErrorLimit
ExpandPR | false | Organizer* ExpandPR
ExpressionLimit | 0 | Organizer* ExpressionLimit
Filter | false | Organizer*FilterCommand
FilterCommand | "" | Organizer*FilterCommand
IgnoreHidden | true | Not available
IncludeOptionalFields | false | Organizer* IncludeOptionalFields
InstanceFile | false | Not available
MacroExpansion | false | Organizer* MacroExpansion
MissingAnswerValuesControl | true | Organizer* MissingAnswerValuesControl
MissingElseControl | true | Organizer* MissingElseControl
OptionalParamControl | true | Organizer* OptionalParamControl
OutputControl | true | Organizer* OutputControl
ReferenceControl | true | Organizer* ReferenceControl
SemanticControl | true | Organizer* SemanticControl
SyntaxControl | true | Organizer* SyntaxControl
TerminateAnalyzer | false | Organizer* TerminateAnalyzer
TrailingParamControl | true | Organizer* TrailingParamControl
UpperCase | false | Organizer* UpperCase
UsageControl | true | Organizer* UsageControl
XRef | true | Organizer* XRef

MAKEOPTIONS Section

Option | Default | Corresponding Preference
Capitalization | AsDefined | Organizer* Capitalisation
CCompilerDriver | false | Not available
CompileAndLink | true | Organizer* CompileAndLink
FileNamePrefix | "" | Organizer* FileNamePrefix
GenerateASN1Coder | false | Organizer* GenerateASN1Coder
GenerateCode | true | Organizer* GenerateCode
GenerateEnvFunctions | false | Organizer* GenerateEnvFunctions
GenerateEnvHeader | false | Organizer* GenerateEnvHeader
GenerateSDLCoder | false | Organizer* GenerateSDLCoder
GenerateSignalNumbers | false | Organizer* GenerateSignalNumbers
Kernel | "SCTADEBCOM" | Organizer* Kernel
MakefileMode | Generate | Organizer* MakefileMode
PrefixType | Full | Organizer* PrefixType
Separation | No | Organizer* Separation
StandardKernel | true | Organizer* StandardKernel
TargetLanguage | Cbasic | Organizer* TargetLanguage
UserKernel | "" | Organizer* UserKernel
UserMakefile | "" | Organizer* UserMakefile
UserTemplate | "" | Organizer* UserTemplate
XCodeGenerator | X | Organizer* XCodeGenerator

PRINTOPTIONS Section

Option | Default | Corresponding Preference
DestinationFormat | PSFile | Print* DestinationFormat
FirstPageNo | 1 | Not available
FrameMakerCommand | "imaker" | Print* FrameMakerCommand
MarginLeft | 100 | Print*MarginLeft
MarginLower | 250 | Print*MarginLower
MarginRight | 100 | Print*MarginRight
MarginUpper | 420 | Print*MarginUpper
PageMarkers | false | Print* PageMarkers
PaperFormat | A4 | Print* PaperFormat
PrinterCommand | "lpr -h -r" | Print* PrinterCommand
PrinterFile | "" | Not available
PrintFrom |  | Not available
PrintTo |  | Not available
PrintToFile | true | Not available

System Window State File

When the system file is saved, a second file is saved as well; the system window state file. This file contains information about window positions and sizes. If an editor window is not open when the system file is saved, the last known position and size of that window is saved instead. While the system file uses the .sdt extension, the system window state file uses the .sdt.state extension.

If the Organizer finds a system window state file when opening a system file, the positions and sizes of the Organizer and editor windows are restored to the positions they had when the system file was saved. Note that the editor windows are not restored until they are opened from the Organizer.


Control Unit File

In addition to the System file (see "System File" ), the Organizer also manages Control Unit files, .scu files. These control units are introduced to facilitate the workgroup (multiuser) support when working with an SDL system managed by Telelogic Tau, and merging the individual results to a common system file.

General

The multiuser support in Telelogic Tau is based on, from a revision control point of view, letting the user split the system file into several files. Information that is updated often should be split and stored in control unit files.

When and where to split the SDL structure is an active action taken by the user.

The multiuser mode is effective when control unit files are used. The use of the control unit files is optional, whereas the system file is mandatory. The Organizer thus always requires a system file and can manage multiple control unit files. By not taking advantage of control units simply means using the Organizer and system files as was done before, i.e. in previous versions of Telelogic Tau (3.0X/3.1X/3.2).

Definitions

A definition for a system file (.sdt file) from a revision control point of view: a file that contains structure and state information for a document system as seen by one Telelogic Tau user. This file is normally not considered as an essential part of the system and is not suitable for revision control as it is private to one user.

  • The diagram structure information is common to all developers of the system in a multiuser environment.
  • The state information is specific for one user.

A similar definition for a control unit file (.scu file): a file that contains structure information for a subset of a document system and which is common to all users that work with the document system. Control unit files are part of the document system and are suitable for revision control.

The control unit files can be inserted and made visible in the Organizer's file structure view. The control unit files contain information that is specific to the Organizer file structure for diagrams, modules and chapters.

Splitting the System File

The users control what parts of the file structure managed by the Organizer need a separate control unit file. When several users work on a system, the management of the system file may be difficult to synchronize. This problem is solved if every user or group have control over their own part of the system file.

The Organizer structure information is hence split into several files - control unit files. The decision of where and how many control unit files are needed is left to the users; the idea being to partition the diagram system according to the user's work responsibilities and assign control unit files to these partitions. An example can be a large SDL diagram system where there are several blocks on the system level developed in parallel by different developers. Each block could then be associated with a control unit file. Now, the blocks can be updated independently and the changes are shaping the local control unit files. There is no need to manually merge changes into the system file when the work is done - the management of control unit files performed by the Organizer also includes the merge.

The user decides how control unit files and the system file cooperate to produce the Organizer view of the document system. Two scenarios are possible here. In one scenario the user decides that the system file is valid and the diagram structure is read from it. This is done when the user opens the system file and loads the document system into the Organizer. In the other scenario the control unit files are used to load the Organizer view and automatically update it accordingly to a specific revision for the document system - the system file is used only to fill in document state information (if any is available). This is done with a menu command when control unit files are used to explicitly update the document system or some part of it.

An Example

To illustrate the use and contents of control unit files and facilitate the understanding, let us discuss the topic with a simple example as input.

Example 4

Say we have the following system managed by the Organizer:

Figure 54 : A simple system, managed by the Organizer

Let us say that we create control units (using the Configuration > Group File command) for the following items:

  • One control unit that holds the entire system file together
  • One control unit for the whole diagram structure
  • One control unit for the system DemonGame
  • One control unit for the block GameBlock.

We would now have a system that looks like this:

Figure 55 : The same system, now with control units

The control units are depicted in bold face.

The [DIAGRAMS] section of the demongame.sdt file will contain:

[DIAGRAMS]
-2 102 system system.scu 0 0 - ""
-1 102 diagrams diagrams.scu 0 0 - ""
-1 23 "Diagram Structure" %unconnected% 0
0 102 demongame demongame.scu 0 0 - ""
0 1 DemonGame demongame.ssy 0 0 demongame ""
1 102 gameblock gameblock.scu 0 0 - ""
1 2 GameBlock gameblock.sbk 0 0 gameblock ""
2 5 Main main.spr 0 0 main ""
2 5 Game game.spr 0 0 game ""
1 2 DemonBlock demonblock.sbk 0 0 demonblock ""
2 5 Demon demon.spr 0 0 demon ""
0 33 1 1.txt 0 0 - ""
-1 23 "Associated Documents" %unconnected% 0
0 16 DemonGame1 %unconnected% 0 0 - ""
0 16 SystemLevel systemlevel.msc 0 0 - ""

The files system.scu, diagrams.scu, demongame.scu and gameblock.scu will contain the following information:

system.scu:
-1 102 diagrams diagrams.scu 0 0 - ""
-1 23 "Associated Documents" %unconnected% 0
0 16 DemonGame1 %unconnected% 0 0 - ""
0 16 SystemLevel systemlevel.msc 0 0 - ""

diagrams.scu:
-1 23 "Diagram Structure" %unconnected% 0
0 102 demongame demongame.scu 0 0 - ""
0 33 1 1.txt 0 0 - ""

demongame.scu:
0 1 DemonGame demongame.ssy 0 0 demongame ""
1 102 gameblock gameblock.scu 0 0 - ""
1 2 DemonBlock demonblock.sbk 0 0 demonblock ""
2 5 Demon demon.spr 0 0 demon ""

gameblock.scu:
0 2 GameBlock gameblock.sbk 0 0 gameblock ""
1 5 Main main.spr 0 0 main ""
1 5 Game game.spr 0 0 game ""

Format and Structure of the Control Unit File

Format

The format of the control unit file complies with the syntax of the [-DIAGRAMS] section in the system file (see "Format of the System File" ). There are however some exceptions:

The first line of the scu file indicates the source directory to use for relative files mentioned in the scu file. This information is saved in the same way as the same information is saved in the system file. By having this information in the scu file, it is possible to re-use/reference the same scu file from different system files with different source directories.

<viewState>
This field is only used for the separation value - the value is therefore either 0 or 1.

<timeStamp>
This field is not used - the value is always 0.

<associations> ::= " <qualifiernameList> "
A list of quoted qualifier names, each name denoting a document. See Example 5, below.

<dependencies> ::= " <qualifiernameList> "
A list of quoted qualifier names, each name denoting a document.

<qualifiernameList> ::= $ | (<qualifierName>
(, ($ | \NL) <qualifierName>)*)

<qualifierName> ::= ` <qualifierTuple>
(/<qualifierTuple>)* `

<qualifierTuple> ::= <integer> <string>
<string> is the name of the system file, chapter, module or diagram.

Example 5

" `23 Diagrams Area/1 DemonGame/2 DemonBlock', \
`23 Diagrams Area/1 DemonGame/2 GameBlock' "

Structure

Associations between Control Units and Document Structures

A control unit file is associated with a document structure in the Organizer. The control unit file holds information about the top node of the structure and information about lower level documents under the top node and/or other lower level control unit files.

Levels (Indents)

Document nodes in a control unit file have a relative level (i.e. <-indent>) starting from 0. (Exceptions: a chapter node and an control unit file node associated with a chapter have always level -1). This gives the flexibility that the control unit file can be associated with a node on different levels in the system structure of documents. To get the actual level for a document node from an control unit, the control unit file node level should be added to the document's relative node level.

Example 6 : For the control unit level 1 from Example 4

0 2 GameBlock gameblock.sbk 0 0 gameblock ""
1 5 Main main.spr 0 0 main ""
1 5 Game game.spr 0 0 game ""

Hierarchy

The control unit files are hierarchical. The top control unit file is for the whole system of documents in the Organizer. We give this control unit file level (-2). If this file has an information line in the system file this means that the top of the whole system structure is found in that file. Other structure information about diagrams mentioned in the system file is then only a mirror of the structure information found in the control unit hierarchy.

Example 7 :

-2 102 system system.scu 0 0 - ""

Modularity

The user can choose to use a control unit file only for a specific chapter, module or diagram structure (without a top level control unit system file). This means that not all information in the system file is a mirror for structure information from control unit files. Some of the information can be actual structure information that is not controlled by control unit files. When the Organizer expands structure information from control unit files it tries to match that information against the contents in the system file. This matching is necessary because only the system file holds state information about documents. The structure information from control unit files takes precedence over structure information found in the system file. If there is an inconsistency between the control unit file structure information and the system file, the control unit information takes precedence and the SDL suite contents are treated as an error situation. Say, for instance, that according to a control unit file there are three blocks in an SDL system but there are four blocks in the system file. The extra block is probably old information.

Example 8 : A control unit file for a chapter

-1 102 diagrams diagrams.scu 0 0 - ""

Order of Appearance

A control unit information line in the system file is followed by a mirror information line of the top node that the control unit file is associated with. If the Organizer cannot open the control unit hierarchy the mirror information will function as a back-up document structure information.

Example 9

-1 102 diagrams diagrams.scu 0 0 - ""
-1 23 "Diagram Structure" %unconnected% 0


Batch Facilities

the SDL suite supports operations in batch mode, such as printing the documentation, analyzing an SDL structure and generating code. These operations are managed by the Organizer in a batch, windowless mode.

Batch Syntax

The syntax for a batch command is:

sdtbatch <systemfile> <options>

Where <systemfile> and <options> are described in "Batch Options" .

When the sdtbatch command is issued, the Organizer interprets the command line arguments, performs the requested operation and then terminates. Error logging is performed by the Organizer.

Information concerning the batch job is directed the standard output device.

Note:

When executing a Batch command, external service management via the PostMaster interface is disabled.

Print Multiple Files

Syntax:

sdtbatch -p[rint] systemfile \
[-s[elect] documentfile] \
[-o[ption] optionfile]

Prints the contents in the system file. Corresponds to clicking the Print quick button.

Print One File

Syntax:

sdtbatch -p[rint] \
-s[elect] documentfile \
[-o[ption] optionfile]

Prints one file.

Compare Two SDL Diagram Files

Note:

This sdtbatch command produces a textual difference report. To get a graphical difference report, consider using the -grdiff option with the sdt startup command. Read more about this in 2 Introduction to the SDL Suite.

Syntax:

sdtbatch -d[iff] [ -b ] [ -n ] \
documentfile1 documentfile2

Compares two SDL diagram files. By default, a summary of how many differences that were found is printed. When using the -b option (verbose), information about every differing object is presented, including an SDT reference to the object in question. The use of the -n option corresponds to setting the option Ignore moved or resized objects to off. Normally this means that moved and resized symbols will not be detected as being different.

Analyze

Syntax:

sdtbatch -a[nalyse] systemfile \
[-s[elect] diagramfile] \
[-o[ption] optionfile]

Analyzes the contents in the system file. Corresponds to the Analyze quick button.

Make

Syntax:

sdtbatch -m[ake] systemfile \
[-s[elect] diagramfile] \
[-o[ption] optionfile]

Makes a target as specified by the system file. Corresponds to the Make quick button.

Extract Text

Syntax:

sdtbatch -extract [ -comment ] \
[ -keyword <keyword> ] <diagram file>

Extracts text from the diagram file. As default, all text in the diagram is shown. By using the -comment option, only text in comment symbols and /* C-style comments */ in other symbols is shown. The -keyword option limits the shown text to text from symbols containing the <keyword>. The <keyword> itself is not shown. For instance, if you have a comment symbol with the following text:

diagramversion 1.44

Then...

sdtbatch -extract -comment \
-keyword diagramversion a.ssy

...will produce the following output:

1.44

Show License Information

Syntax:

sdtbatch -licenseinfo

Show information about license holders and number of available licenses, as textual output in the console window where the command was entered.

List Files

Syntax:

sdtbatch -files systemfile

Lists all files referenced from the system file, as textual output in the console window where the command was entered.

Pack Files

Syntax:

sdtbatch -pack systemfile [ archivefile ]

Create an archive file (*.tgz) for a system, using default pack settings. If the archive file name is not given, then an archive file will be created in target directory, with a default name.

Change Case

Syntax:

sdtbatch -changecase cross-reference-file

Change the case for all words found in all referenced files in the cross reference file to the case used in the declaration.

The command will also change the case for all keywords. These should be located in a special keyword file found in the same directory, with the same name as the name of the given cross reference file but with the extension ".key".

The command does only work with the standard SDL text editor.

To generate a more extensive cross reference file and a file containing keywords, run the sdtbatch -analyze command with the options

SDLKeywordFile=True

SetPredefinedXRef=True

added to the option file. The analyzer will then generate more information in the cross reference file, casesensitive.xrf, and furthermore a keyword file, casesensitive.key, in the target directory of the system.

Configuration Update

Syntax:

sdtbatch -r[ecursive] systemfile [-u[pdate]]

Does a recursive update of the structure in the Organizer according to the Control Unit files in the system file. Corresponds to the Configuration > Update menu choice.

Checking diagrams for duplicated object IDs

Syntax:

sdtbatch -checkdiagrams systemfile
sdtbatch -checkandfixdiagrams systemfile

Normally each object in an SDL diagram have a unique ID within the diagram. This ID can be shown for example when using the SDL editor command Show GR Reference. For some existing SDL diagrams, especially diagrams that have been created using the Merge or Add Differences functions, the same ID has been used by more than one object. This will result in unpredictable behaviour when using GR References, e.g. when transforming the system to case-sensitive SDL or when an analysis error should be shown, the wrong symbol might appear. Also if the two objects having the same ID are on the same SDL Page, the lines can be connected to symbols in a way that is different from the way you expect by looking at the geometrical layout of the lines. This can give strange errors when generating SDL/PR, giving strange analysis errors. This problem have been fixed in versions 4.2.7, 4.3.3 and 4.4, therefore diagrams that are saved with these or later versions will not have this problem.

To test the diagrams for duplicated IDs you can run the batch command -checkdiagrams. The command will produce a report on duplicates for all the SDL diagrams.

Whenever there are problems with duplicates you can run -checkandfixdiagrams. This will fix all duplicates and save the diagrams such that all diagrams are free from duplicated IDs.

Batch Options

  • <systemfile>
    <systemfile> is an Organizer System File. A valid system file should be supplied.
  • -select <file>
    <file>, which should be included in the document structure, (associated documents are also included if the -print option specified) becomes the selected object upon which the command is applied. This option corresponds to a manual selection of the document in the Organizer drawing area.
    A full file path for the file must be supplied.
  • -o[ption] <optionfile>
    <optionfile> is a file with the same syntax as a System File, containing options which supersede the options found in the system file. An arbitrary number of options may supplied, but options in the file must be preceded with an option section field as found in the system file.

Note:

Note that if the options contains a filename in quotes all backslashes must be escaped with one more backslash. Example of correct filename uses:
PrinterFile=d:\tmp\printfile.ps
or
PrinterFile="d:\\tmp\\printfile.ps"

  • -u[pdate]
    If this option is supplied, the system file will be saved after the batch operation has finished.


Windows and UNIX File Compatibility

Systems can be created with Telelogic Tau on both the UNIX and Windows platforms. To allow systems to be accessed on both platforms, Telelogic Tau provides a file compatibility concept.

The drive table contains a mapping between Windows and UNIX directory paths. This mapping is included in the system file to allow file specifications in the system file to be translated to the correct format on both platforms. See "The Drives Section" for more information.

The menu choice PC Drives is available in the Organizer's File menu, and allows editing the drive table that is stored in the system file. See "PC Drives" for more information.

The drive table takes care of translating absolute paths between the two different file name formats (UNIX and Windows). On a UNIX system, some restrictions apply to file names to be compatible with Windows. These restrictions are checked whenever the user changes a file specification that is stored in the system file; if they are not followed, an error dialog is shown and the user is returned to the dialog where the file was specified. See "Filename Error Dialogs (UNIX only)" for more information.

File specifications are always stored in the correct format according to the current platform.

In general, diagrams with file specifications that are of incorrect format or that cannot be translated to the correct format, are marked as Invalid in the Organizer.


3 The Preference Manager

The Preference Manager is used for setting up the default behavior of the SDL suite tools, and the common Telelogic Tau tools.

This chapter is a reference to the Preference Manager; the functionality it provides, its menus, windows and symbols and a description of the preference parameters.

For a guide to how to use the Preference Manager to customize the behavior of the Telelogic Tau tools, see 4 Managing Preferences.


Preferences Manager User Interface

Figure 56 : The Preference Manager window

The items that build up the Preferences Manager window are:

  • The Tree Area
  • The The Interface Area
  • The Menu Bar

Tree Area

The tree area displays the tools that obey to the preference mechanism in the Telelogic Tau tools and their respective preference parameters. The notation uses a graphical approach featuring a tree with icons symbolizing the various items that are managed by the tool.

Figure 57 : Node in the tree area

Node Syntax

Each node in the tree represents either a:

  • root node
    The root node is identified by the name Preference Manager, followed by a version number.
  • tool node
    A tool node is identified by the name of an Telelogic Tau tool.

Note:

The Preference Manager only supports the SDL suite tools, and the common Telelogic Tau tools. See 30 Customizing the TTCN Suite (on UNIX), for information about how to customize the TTCN suite on UNIX.

  • parameter node
    Each parameter node in the tree is identified with an icon showing:
    • the name of the parameter
    • the current value for the parameter
    • the saved value and the default value within one or two parentheses: (( ))
    • the Preference Source within brackets, [], i.e. whether it is a company or project or user-defined setting
    • a descriptive text providing additional information about the preference parameter.

Example 10 : A Line in the Preferences Window

Given the following line in the Preferences window, with all View Options turned "on":

Figure 58 : A line in the Preferences window

The information on the line in Figure 58 should be interpreted as:

Item
Interpretation

The icon informing that the preference parameter is a boolean parameter (0/1, false/true or off/on parameter.

 Editor*SymbolMenu
The name of the preference parameter, consisting of
  • the name of the tool it affects, Editor
  • the name of the parameter, SymbolMenu
Separated with an asterisk

 off
The current value for the parameter.

 (off)
The saved value for the parameter.

 ((on))
The default value for the parameter.

 [User]
The parameter's source, in this case the parameter is defined by the user.

 Show the symbol
menu
The parameter's description, i.e. what tool property the parameter affects.

The tree is a visualization of the merged preference parameters, supplied from different sources (see "Search Order When Reading Preference Parameters" ), as the Telelogic Tau tools will perceive them. Furthermore, each node in the tree can be collapsed or expanded (see "Collapse" ) in order to reduce or extend the amount of information that is visible, thus facilitating the work with the tool. It is also possible to filter the information that is displayed with respect to various view options (see "View Options" ).

Dirty Notification

When a preference parameter is modified but not saved, this is indicated by the icon appearance changing from a light color to a gray pattern. The parent tool node and the root node are also marked as dirty when any parameter is changed.

Figure 59 : Nodes marked as dirty

The Interface Area

The interface section located under the tree view is where values are edited in an Edit Area. The type of Edit Area varies with the type of value selected.

There are different types of preference parameters:

  • Textual Preference
  • Option Menu Preference
  • Option Menu Textual Preference
  • Font Preference (Windows only)
  • Boolean Preference
  • Ranged Integer Preference
  • File Preference
  • Directory Preference
  • Color Menu Preference

Icon
Edit Area

Textual Preference
    • The preference parameter is edited as a text string.

Option Menu Preference
    • The preference parameter may be selected from a number of predefined values in the option menu.1

Option Menu Textual Preference
    • The preference parameter may be selected from a number of predefined values in the option menu.a An alternative is to type in the value into the text field, which grants access to not predefined values.

Font Preference (Windows only)
    • The font must be selected by clicking the folder button, which opens a Microsoft Windows Font dialog. It is not possible to edit the text field to the left of the folder button.
    • In the dialog, all fonts in the system are listed. It is also possible to select font style and size, but these values have no effect; only the specified font name is used.
    • Any font name can be entered by editing the Font text field in the font dialog. This possibility is useful when setting a font for printing that is not available in the system, but exists on the printer.
    • The three font names "Times", "Helvetica" and "Courier" are recognized. These are translated into the TrueType fonts Times New Roman, Arial and Courier New, respectively.
    • When using other fonts than the three mentioned above for printing, the preference Print*DestinationFormat should be set to MSWPrint to get the best result for symbols that are adjusted to the text size.

Boolean Preference
    • The value is changed by clicking the corresponding radio button.

Ranged Integer Preference
    • The preference parameter may be assigned any integer value within the range supported by the slide bar.

File Preference
    • The preference parameter may be assigned any file name, entered as a text string into the text field or selected in a dialog issued by the folder button.
Directory Preference
    • The preference parameter may be assigned any directory name, entered as a text string into the text field or selected in a dialog issued by the folder button.

Color Menu Preference
    • The preference parameter may be selected from a number of predefined values in the option menu.
1

When the mouse pointer is moved over a value in the option menu, a short description of the value is printed in the status bar. Values whose description starts with "(UNIX only)" or "(Windows only)" should only be selected on a UNIX system or a Windows system, respectively.

Selecting a parameter and editing its value with the provided UI device changes its value. The parameter's icon is set as dirty (see "Dirty Notification" ).


Menu Bar

The menu bar contains the following menus:

  • File Menu
  • Edit Menu
  • View Menu
  • Tools Menu
  • Help Menu

File Menu

The File menu contains the following menu choices:

  • Save
  • Revert
  • Print
    (see "The Print Dialogs in the SDL Suite and in the Organizer" )
  • Info
  • Exit
    (see "Exit" )

Save

This menu choice saves the parameters that have been modified in the User's Preference File, on UNIX in $HOME/.sdtpref, and in Windows in %HOME%\sdt.ini

But, before saving the preference settings, the user will be warned if there are modified preferences that are defined as company or project preferences:

Figure 60 : Attempting to save a modified project or organization parameter

  • Clicking Save saves all modified preference parameters on the User's Preference File, which may implicate a violation of the rules set up in the project!

Caution!

Consider the implications before you click Save.

When the save has been performed the user will be warned that changes will not be in effect before the tools have been restarted.

Revert

The menu choice reverts all preference parameters to the currently saved values, as they were defined when starting the Preference Manager. The Revert command requires to be confirmed, in case any preference parameters are modified and have not been saved:

Figure 61 : The Confirm to Revert dialog

Info

This menu choice issues a message with information about the preference source for the preference parameters.

Figure 62 : Information about preference sources

The message shows four items:

  • [Locale] - <file specifier>
    The location of the locale preference file
  • [Company] - <file specifier>
    The location of the company / organization preference file
  • [Project] - <file specifier>
    The location of the project preference file
  • [User] - <file specifier>
    The location of the user's preference file.

See "Preference Files" for more information on preference files and search order.

Edit Menu

The Edit menu contains the following menu choices:

  • Set Saved Value
  • Set Default Value
  • Unsave

Set Saved Value

This command restores the selected parameter to its currently saved value. The menu choice is also available from the pop-up menu.

Set Default Value

This command restores the selected parameter to its default value (i.e. factory setting). The menu choice is also available from the pop-up menu.

Unsave

This command allows to remove a preference parameter from the User's Preference File when saving the file, i.e. Unsave it. The command is available on user-defined parameters only; user-defined parameters are shown with their Value Sources set to [User].

A dialog is displayed following invocation of the command:

Figure 63 : The Unsave dialog

  • Clicking OK, the parameter's source changes to [User (No Save)]. The preference parameter will be removed from the user's preference after the next Save command, changing its source to [Project] or [Company].

View Menu

The View menu contains the following menu choices:

  • Expand
  • Expand All
  • Collapse
  • Collapse All
  • View Options
  • Set Scale

Expand

This menu choice is available only if the currently selected object is a tool node. The command expands the subtree starting from the selected tool, making all parameters for that tool visible.

The operation is also available from the pop-up menu and with a double-click.

Expand All

This command expands the entire tree, thus making all parameter nodes visible.

The operation is also available from the pop-up menu.

Collapse

This menu choice is available only if the currently selected object is a tool node. The command collapses the parameter nodes belonging to the current tool, leaving only the tool node visible in the subtree.

The operation is also available from the pop-up menu and with a double-click.

Collapse All

This menu choice collapses all tool node s and hides the parameter node s. Only the root node and the tool nodes are left visible.

The operation is also available from the pop-up menu

View Options

This menu choice issues a modeless dialog, the View Options dialog:

Figure 64 : The View Options dialog

The dialog contains the following toggle buttons:

  • A Tool Bar button
  • A Status Bar button
  • A Filter Field and Filter Button
  • A Tool Names button
  • A Saved Values button
  • A Default Values button
  • A Value Sources button
  • A Descriptions button

Tool Bar

This button controls the presence of the quick buttons.

The tool bar is visible by default.

Status Bar

This option determines whether the Status Bar should be visible or not.

The status bar is by default visible.

Filter Field and Filter Button

If the Filter Button is on, the Tree Area will only show the preference parameters which name contain the text string that is entered in the Filter Field.

Note:

The name of a preference parameter consists of a combination of a tool name and of the parameter itself (see "Syntax of Preference Files" ).
The filter option compares the text strings without respect to upper or lower case characters.

By default, no filtering is applied.

Tool Names

This option controls whether the prefix in preference parameters (consisting of the tool name and of an asterisk) should be displayed or not (see "Syntax of Preference Files" ).

Tool names are not displayed by default.

Saved Values

This option determines whether the saved values should be made visible or not. The saved values are the values that are currently stored on the preference files.

Saved values are displayed within one level of parentheses (saved value). See Example 10.

Saved values are displayed by default.

Default Values

This option determines whether the default values (i.e. factory settings) should be made visible or not.

Default values are displayed within two levels of parentheses ((default value)). See Example 10.

Default values are not displayed by default.

Value Sources

This option determines whether the Preference Source for the parameters should be displayed or not. A preference parameter may be retrieved from any of the following sources:

  • The company settings
  • The project settings
  • The user's own settings

Source values are displayed within brackets [] and are not visible by default.

Descriptions

This option determines whether an informative text should be displayed or not. The text is purely informational and provides an additional description of the function of the preference parameter. See Example 10.

Parameter descriptions are not displayed by default.

Set Scale

This menu choice opens a dialog where you may set the scale used in the preferences window. The scale may be set between 20% and 800%. 100% is the default.

Tools Menu

The Tools menu contains one menu choice:

  • Show Organizer
    (see "Show Organizer" )


Popup Menu

The contents of the popup menu depends on which node you click on.

On the Root Node

Collapse All | See "Collapse All" .
Expand All | See "Expand All" .

On a Tool Node

Collapse | See "Collapse" .
Expand | See "Expand" .

On a Value Node

Set Saved Value | See "Set Saved Value" .
Set Default Value | See "Set Default Value" .
Help | Request on-line help for the preference parameter in question.


Keyboard Accelerators

Apart from the general keyboard accelerators, as described in "Keyboard Accelerators" , the following accelerators can be used in the References window:

Accelerator | Operation
Arrow Up | Move selection up among the expanded nodes
Arrow Down | Move selection down among the expanded nodes
Page Up | Scroll up
Page Down | Scroll down
Home | Scroll left
End | Scroll right
Ctrl+Home | Display first line
Ctrl+End | Display last line
Space or Return | Expand or collapse a node. Traverse through option menu. Toggle parameters on/off.
F2 | Raise the pop-up menu.


Preference Files

All of the preference parameters along with their values (exception made for the default settings which are programmed into the Telelogic Tau tools) are stored on dedicated files, the preference files. The preference files may be edited with any text editor since the information is stored in textual form.

The Preference Manager manages these files and provides the graphical user support for customizing the Telelogic Tau tools in an easy way.

Note:

The TTCN suite cannot be customized by preferences. Instead, see 30 Customizing the TTCN Suite (on UNIX).

Preference Source

The following files build up the preference environment:

  • The Locale Preference File
  • The User's Preference File
  • The Project Preference File
  • The Company Preference File

The following items constitute the various sources for preference parameters. The source identifier may be made visible with the Value Sources options in the View Options dialog.

Source Identifier
Source Description

 [User]
The User's Preference File

 [User (No Save)]
The User's Preference File, will be removed from the user's preference file next time the parameters are saved

 [Project]
The Project Preference File

 [Company]
The Company Preference File

 [Locale]
The Locale Preference File

 [Default]
The default Factory Settings.

User's Preference File

This file stores the preferences parameters that a user has modified. The file is created / updated as a result of the Save command.

The user's preference file is identified on UNIX by:

$HOME/.sdtpref

and in Windows by:

%HOME%\sdt.ini

Note: $HOME and %HOME%

On UNIX, $HOME is assumed always to be defined in the computer environment.
In Windows, if %HOME% is not set, the user's preferences will be stored in the directory from which Telelogic Tau is started.

Project Preference File

This file stores the preferences values that are to be applied to a specific instance of a project where the Telelogic Tau tools are used.

The project preference file is identified on UNIX by:

$SDTPREF/.sdtpref

and in Windows by:

%SDTPREF%\sdt.ini

Note: $SDTPREF and %SDTPREF%

If $SDTPREF (on UNIX) or %SDTPREF% (in Windows) is not set, the project preference file feature will be disabled. In a multi-user environment, it is strongly recommended to use a directory resident on a network drive for the project preferences. All project members should have read access to this directory.

Company Preference File

This file stores the preference values that are common for an entire company or organization and therefore should be applied to all projects and users of the Telelogic Tau tools.

The company preference file is identified on UNIX by:

$telelogic/.sdtpref

and in Windows by:

<Installation directory>\sdt.ini

Note:

On UNIX, $telelogic is assumed always to be set in a Telelogic Tau environment.
In Windows, to function properly (in the sense of being unique) in a multi-user environment, the company preference file should be stored on a directory on a network drive, e.g. if Telelogic Tau is installed on a network. Also, all users should have read access to the company preference file.

Locale Preference File

This file stores the preference values that are locale dependent and should therefore be applied to all projects and users of the Telelogic Tau tools.

Factory Settings

These are the settings that are defined by default in the Telelogic Tau tools. The factory settings will be used whenever a preference parameter could not be found in the Preference Files.

Syntax of Preference Files

A line in the preference file contains two items:

  1. The first item specifies a tool and a parameter, separated by an asterisk.
  2. The second item specifies the current value that is to be assigned to that parameter when starting up the tool.

The syntax is:

tool*parameter: value

Example 11 : A Line in Preferences File

An example line in a preferences file could look like this:
Print*Scale:100
Meaning that the scale when printing is 100%.

The order of appearance of the parameters in a file is of no significance.

Search Order When Reading Preference Parameters

This section discusses how the Telelogic Tau tools read the preference parameters.

When a tool starts, it will automatically (i.e. no user-interaction is required) retrieve the preference values in an incremental way, following the order of search described below and illustrated in Figure 65 and Figure 66:

  1. First, fallback values (default factory settings) are loaded, followed by the locale settings.
  2. Then, if the environment variable SDTPREF is set:
    • If $SDTPREF/.sdtpref (on UNIX), or %SDTPREF%\sdt.ini (in Windows) exists, that file is read incrementally1 as the project preference file.
    • Otherwise, the Telelogic Tau tools will look for organization preferences in the Telelogic Tau tools installation directory, in the file designated by $telelogic/.sdtpref (on UNIX) or <Installation directory>\sdt.ini (in Windows).
  3. Finally, if the HOME environment variable is set, and $HOME/.sdtpref (on UNIX) or %HOME%\sdt.ini (in Windows) exists, that file is read incrementally as the user's preference file.
    • Otherwise, if HOME is not set, the preference file in the directory from which Telelogic Tau was started is read incrementally as the user's preference file.

The method above allows to configure an Telelogic Tau tool environment by defining some preferences as company-wide or project-wide, while allowing users to customize other preferences.

Figure 65 :How the Telelogic Tau tool searches for
preference parameters (on UNIX)

Figure 66 : How the Telelogic Tau tool searches for
preference parameters (in Windows)

Save of Preference Values

When a preference parameter is saved, it is always stored as a user-defined preference parameter in the user's preference file, i.e. -$HOME/.sdtpref (on UNIX), or %HOME%\sdt.ini (in Windows), if HOME is set. If HOME is not set, the preference parameters are stored in a preference file in the directory from which Telelogic Tau was started.

The above implies that modifying a parameter that was originally defined as a project or organization parameter, the parameter will from now on be considered as a user-defined parameter. The user is however notified about this (see Figure 60).

1

Incrementally in the sense that only parameters that are stored in the project preference file will override previous settings.


Preference Parameters

The following sections are a reference to the preference parameters in the Telelogic Tau tools with their default values and a description of what the parameter affects.

Note:

All preference parameters for the Telelogic Tau tools that are available on UNIX and in Windows are listed and described. This is to ensure compatible interchange of preferences between UNIX and Windows platforms, even if the preference parameter has no impact on one of the platforms. When this is the case, it is clearly noted.

For clarity reasons, the prefix that identifies the tool that the parameter applies to is specified once only, at the beginning of each tool section.

Preference parameters are grouped tool-wise. Within each tool section, parameters are listed in alphabetic order.

Where the parameter is specified with a numeric default value, the sort is specified within parentheses "()". Parameters whose value is specified as a text and which do not have any default value are identified as "". Possible values are not specified; the user should run the Preference Manager in order to obtain a reference to the permitted values.

The following preference groups exist:

  • Generic Preferences
  • Organizer Preferences
  • Help Viewer Preferences
  • Preference Manager Preferences
  • Print Preferences
  • Text Editor Preferences
  • SDL Editor Preferences
  • OM/SC/HMSC/MSC/DP Editor Preferences
  • Index Viewer Preferences
  • Type Viewer Preferences
  • Coverage Viewer Preferences
  • SDL Overview Generator Preferences
  • Simulator GUI Preferences
  • Validator GUI Preferences

The TTCN suite tools cannot be customized by preferences. Instead, see 30 Customizing the TTCN Suite (on UNIX).


Common Telelogic Tau Preferences

These preferences apply to tools that are available in all Telelogic Tau tools.

Generic Preferences

Prefix: SDT*

Generic preferences may be used by tools that have not defined any specialization for these preferences.

Preference Parameter
Default
Affects
AllowSpaceInFileNames
off
Whether Telelogic Tau allows the user to add files with names containing spaces. The default setting of not allowing file names with spaces is set to ensure maximum compatibility with other tools that may be connected to Telelogic Tau. Unless you are using Telelogic Tau stand-alone, you should carefully consider if your environment can correctly support spaces in file names before enabling this feature.
CaseSensitive
off
Whether the SDL language should be case sensitive or not. It will effect the syntax check in the SDL Editor and the work of the Analyzer. The default setting is as SDL96, i.e. the language is not case sensitive. Also used as the default value for the Analyzer option Case sensitive SDL in the Organizer.
CMIntegration
No integration
Specifies if Telelogic Tau is used together with an external configuration management tool. When set to ClearCase, the name of the view is shown in the Organizer window title.
Drives
""
The default contents of the The Drives Section in the system file for a newly created system.
EmacsCommand
"emacs"
The command used to start the Emacs text editor.
UNIX only, see Note:.
FileNameCompletion
on
Whether file name completion is invoked by a completion character.
FileNameCompletionChar
""
The character that invokes file name completion.
FunctionFrequencyLogFile
""
File to save tool usage statistics on; see FunctionFrequencyLogging. In addition, tool usage statistics is also saved to a file sdtfreq.log in the installation directory.
FunctionFrequencyLogging
on
Whether to collect statistics on the usage of menu commands, quick buttons and accelerators. The tools that support collecting statistics are:
  • the Organizer
  • the SDL Editor
  • the OM Editor
LicenseTimeout
0
The time interval (in hours) an interactive SDL suite user is allowed to remain idle before licenses are automatically released.
Setting this value to 0 disables the automatic release of licenses.
PrintFontFamily
"Times"
The font face to use when printing text.
RelativeSDTREF
off
If file names in SDT references should be expressed as relative to source directory or not.
Scale
100 (%)
The scale to use when displaying on screen.
ScreenFontFamily
"Helvetica"
The font face to use when displaying text on screen.
SearchUnderscoreAware
on
Decides if the search operation should find "a_ b" when searching for "ab" in SDL diagrams and MSCs.
Sound
on
The emission of an alert sound (beep) when performing an illegal operation.
StartInformationServer
on
If an Information Server should be allowed to start or not.
TextEditor
Telelogic
The text editor to use when editing text documents.
UseLowerCaseInFileNames
off
If turned on, saved diagram names are converted to lower case to provide UNIX/DOS file name compatibility. Activating this preference can lead to problems when accessing existing files with names containing non-lowercase letters.
WordCommand
"Winword.exe"
The command used to start Microsoft Word.
Windows only, see Note:.
TextWindowFontFamily
Courier New
The font used in text windows.
Windows only, see Note:.
TextWindowFontHeigth
10
The size of the font used in text windows.
Windows only, see Note:.
UserInterfaceFontFamily
MS Sans Serif
The font used in the user interface.
Windows only, see Note:.
UserInterfaceFontHeight
9
The size of the font used in the user interface.
Windows only, see Note:.
SimulatorValidatorFontFamily
Arial
The font used in the simulator and validator user interface.
Windows only, see Note:
SimulatorValidatorFontHeight
11
The size of the font used in the simulator and validator user interface.
Windows only, see Note:.
TabSize
2
Number of spaces inserted when the TAB key is pressed in a text area. Windows only.

Organizer Preferences

Organizer Pack Preferences

Prefix: Organizer*Pack. For more information about the pack operation, see "Pack Archive" .

Preference Parameter | Default | Affects
TarCommand | tar | The command used by the pack archive operation to access the tar utility. On Windows, specify tar.exe to use the gnu version included in the installation.
GzipCommand | gzip | The command used by the pack archive operation to access the gzip utility. On Windows, specify gzip.exe to use the gnu version included in the installation.
ArchiveSdt | on | Decides if a system file adapted for the archive contents should be included.
OriginalSdt | off | Decides if the original system file should be included.
Packages | on | Decides if SDL package diagrams should be included.
OtherSDL | on | Decides if other SDL diagrams (system, block, process...) should be included.
MSC | on | Decides if MSC diagrams (MSC, HMSC) should be included.
UML | on | Decides if UML diagrams (object model, state chart, deployment) should be included.
Chapter | on | Decides if chapters should be included.
Generic | off | Decides if files attached to the Organizer generic symbol should be included.
SimScript | off | Decides if simulator scripts (*.cui and *.com files attached to a plain text symbol) should be included.
OtherText | on | Decides if other text documents (not simulator scripts) should be included.
Scu | off | Decides if configuration unit files (*.scu) should be included.
Index | on | Decides if index files (*.xrf) should be included.
Header | on | Decides if header and footer files should be included.
Extensions | lst | Files in source or target directory with the extensions specified here (space separated) are included.

Other Organizer Preferences

Prefix: Organizer*

Preference Parameter
Default
Affects
AbsolutePath
off
If file names should be specified with an absolute directory path or not. See "Set Directories" .
AllowImplicitTypeConv
off
The default value for the Analyzer option Allow implicit type conversion.
AllPreferences
off
If all preferences or if only the "diff" between current Organizer options and Organizer start-up options should be written as options in the system file. See "Options in the System File" .
Areas
"Analysis Model,Used Files,SDL System Structure,TTCN Test Specification,Other Documents"
The names of the chapters in the Organizer's drawing area, separated by commas. The default is known as the basic Organizer view.
ASN1KeywordFileName
""
The default value for the Analyzer option ASN.1 keyword substitution file.
ASN1Suffix
".asn"
File name extension used to recognize ASN.1 files.
AutoCMUpdate
off
If this preference is on, then a configuration update operation will be done each time a system file is loaded in the Organizer. The system file will be updated with *.scu file information.
AutoSaveBefore
off
If modified diagrams should be saved on file without user confirmation when selecting any of the commands Analyze, Make, SDL Overview and Convert to PR/MP.
BuildScript
".bld"
File name extension used for build script files.
Capitalisation
AsDefined
The default value for the code generation option Capitalization.
ChangeBars
off
If change bars should be created when SDL diagrams are edited.
ClearLog
on
Clear text in Organizer Log before running the Analyzer.
CoderBufferInSDL
"None"
The default value for the encoding used for ASN.1 Buffer in SDL (see ASN.1 encode/decode parameter).
CompileAndLink
on
The default value for the code generation option Compile & link.
DefaultSimulator
"SCTADEBCOM"
The default value for the compile and link option Standard kernel when generating a simulator.
DefaultValidator
"SCTAVALIDATOR"
The default value for the link option Standard kernel when generating a validator.
EchoAnalyzerCommands
off
The default value for the Analyzer option Echo Analyzer commands.
ErrorLimit
30
The default value of the Analyze parameter Error limit.
ExpandPR
off
The value of the Convert to PR option Expand included PR files.
ExpressionLimit
0
The value of the Analyze parameter Log expressions deeper than.
FileNamePrefix
""
The default value for the code generation option File name prefix.
FilterCommand
""
Filter command to invoke before Analyzer stages.
GenerateASN1Coder
off
The default value for the code generation option Generate ASN.1 coder.
GenerateCode
on
The default value for the code generation option Analyze & generate code.
GenerateEnvFunctions
off
The default value for the code generation option Generate environment functions.
GenerateEnvHeader
off
The default value for the code generation option Generate environment header file.
GenerateSDLCoder
off
The default value for the code generation option Generate SDL coder.
GenerateSignalNumbers
off
The default value for the code generation option Generate signal number file.
GenericCommand
On UNIX:
".txt "ls %f""
In Windows:
".txt "notepad %f""
A list of file extensions and the corresponding command to be performed when editing a generic document. See "Generic Document" .
HeaderFileSuffix
".h"
File name extension used to recognize C/C++ header files.
IncludeOptionalFields
off
The default value for the Analyze option Include optional fields in make operator.
Kernel
"SCTADEBCOM"
The default value for the compile and link option Standard kernel.
LicenseInfo
on
If this preference is on, when failing to get a license during Telelogic Tau start-up, then information about license holders and number of available licenses is presented in the command line window.
LogFilter

What Analyzer messages are shown in the log window.
LogNavigationLevel
Error
The navigation between messages in the log window.
MacroExpansion
off
The default value for the Analyze option Macro expansion.
MakefileMode
Generate
The default value for which option to select from the compile and link options
  • Generate makefile
  • Generate makefile and use template
  • Use makefile
MissingAnswerValuesControl
on
The default value for the Analyze option Check missing answer values
MissingElseControl
on
The default value for the Analyze option Check missing else answers
MoveWindow
off
The size and position of the Organizer window when a system file is opened. That is, if the size and position will be the same as when that system file was last saved.
OptionalParamControl
on
The default value for the Analyze option Check optional parameters.
OutputControl
on
The default value for the Analyze option Check output semantics.
PathLineLength
0
How many characters that a file or directory may be, before being split into several lines in the Organizer window. 0 = no limit.
PrefixType
Full
The default value for the code generation option Prefix.
QBAddExisting
Hide
The presence of the Add Existing quick button.
QBAddNew
Space & Show
The presence of the Add New quick button.
QBAnalyze
Space & Show
The presence of the Analyze quick button.
QBGenerateSim
Space & Show
The presence of the Simulate quick button.
QBGenerateVal
Show
The presence of the Validate quick button.
QBGenerateView
Show
The presence of the Generate SDL Overview quick button.
QBHelp
Space & Show
The presence of the Help quick button.
QBLog
Space & Show
The presence of the Organizer Log quick button.
QBLogAnalyze
Space & Show
The presence of the Organizer Log Analyze quick button.
QBLogClear
Show
The presence of the Organizer Log Clear Log quick button.
QBLogClose
Space & Show
The presence of the Organizer Log Close quick button.
QBLogErrorHelp
Show
The presence of the Organizer Log Help on Error quick button.
QBLogHelp
Space & Show
The presence of the Organizer Log Help quick button.
QBLogSave
Show
The presence of the Organizer Log Save quick button.
QBLogShowError
Space & Show
The presence of the Organizer Log Show Error quick button.
QBLogShowOrganizer
Space & Show
The presence of the Organizer Log Show Organizer quick button.
QBMake
Show
The presence of the Make quick button.
QBMoveDown
Show
The presence of the Move Down quick button.
QBMoveUp
Show
The presence of the Move Up quick button.
QBNew
Hide
The presence of the New quick button.
QBOpen
Show
The presence of the Open quick button.
QBPrint
Space & Show
The presence of the Print quick button.
QBSave
Show
The presence of the Save quick button.
QBSearch
Space & Show
The presence of the Search quick button.
QBXref
Show
The presence of the Generate Cross References quick button.
QBZoomIn
Show
The presence of the Increase Scale quick button.
QBZoomOut
Space & Show
The presence of the Decrease Scale quick button.
ReferenceControl
on
The default value for Analyze option Check references.
SemanticControl
on
The default value for Analyze option Semantic analysis.
Separation
No
The default value for the code generation option Separation.
ShowAddExisting
on
If an existing document should be opened in an editor when added.
ShowDashed
on
The default value for the view option Dashed diagrams.
ShowDependencies
on
The default value for the view option Dependency symbols.
ShowDirectories
off
The default value for the view option File directories.
ShowFileName
on
The default value for the view option File names.
ShowFooter
off
The default value for the view option Footer file.
ShowGroups
on
The default value for the view option CM Groups.
ShowHeader
off
The default value for the view option Header file.
ShowInstances
on
The default value for the view option Instance diagrams.
ShowLinkFile
off
The default value for the view option Link file.
ShowLinks
on
The default value for the view option Association symbols.
ShowLogLevel
Warning
Under which circumstances the Organizer Log Window should be raised automatically.
ShowLongMenus
on
The default value for the view options Long / Short.
ShowPages
off
The default value for the view option Page symbols.
ShowPermissions
on
The default value for the view option File access permissions.
ShowSeparators
on
The default value for the view option Separator symbols.
ShowSource
on
The default value for the view option Source directory.
ShowSystemFile
on
The default value for the view option System file.
ShowTarget
off
The default value for the view option Target directory.
ShowTypeName
off
The default value for the view option Type names.
ShowVirtuality
on
The default value for the view option Virtuality.
SourceDirectory
""
The default Source directory when creating a new system.
StandardKernel
on
The default value for the compile and link option Standard kernel.
Statusbar
on
The default value for the view option Status bar.
SuppressLevel
5
The number of issued identical Organizer messages before they are suppressed in the Organizer Log window.
SyntaxControl
on
The default value for Analyze option Syntactic analysis.
TargetDirectory
""
The default Target directory when creating a new system.
TargetLanguage
Cbasic
The default value for the code generation option Code generator.
TerminateAnalyzer
off
The default value for the analysis option Terminate Analyzer when done.
Toolbar
on
The default value for the view option Tool bar.
TrailingParamControl
on
The default value for the Analyze option Check trailing parameters.
TreeRepresentation
List
The default value for the view options Indented list / Vertical tree.
UpperCase
off
The default value of the Convert to PR option Write reserved words in (off means lower case).
UsageControl
on
The default value for Analyze option Check unused definitions.
UserKernel
""
The default value for the compile and link option Use kernel in directory.
UserMakefile
""
The default value for the compile and link option Use makefile.
UserTemplate
""
The default value for the compile and link option Generate makefile and use template.
WelcomeWindow
on
If a Welcome window should be displayed at start-up of the Organizer.
WordSuffix
".doc"
File name extension used to recognize Microsoft Word files.
Windows only, see Note:.
XCodeGenerator
"X"
The name of the code generator that appears last in the option menu Code generator in the Analyze and generate code options.
UNIX only, see Note:.
XRef
on
The default value for Analyze option Generate a cross reference file.

Help Viewer Preferences

Prefix: Help*

Preference Parameter | Default | Affects
HelpDirectory | "" | What help root directory to use for on-line help files. Useful if the on-line help files is available on a network server. See "Configuring the Help Environment" for more information.
HelpViewer | Netscape | The choice of help viewer. "Default Web Browser" (Netscape or Internet Explorer) is the default choice on Windows.
NetscapeCommand | "netscape" | What command the tools use when starting the help viewer when the preference parameter HelpViewer is specified as Netscape.
InternetExplorerCommand | "iexplorer" | What command the tools use when starting the help viewer when the preference parameter HelpViewer is specified as Internet Explorer. This is useful on the UNIX platform when the Internet Explorer is not available via your PATH variable.

Preference Manager Preferences

Prefix: Preference*

Preference Parameter | Default | Affects
Statusbar | on | The presence of a status bar in the window.
Toolbar | on | The presence of a tool bar in the window.

Print Preferences

Prefix: Print*

Preference Parameter | Default | Affects
BlackAndWhite | off | The color used when printing symbols and lines.
DateType | ISO | The date format in printouts.
DestinationFormat | PSFile | The default Format option in the Print dialog.
FooterFile | off | The default value for the option Footer file in the Print dialog.
Frame*PaperFormat | USLetter | The default value for the paper format used when printing to FrameMaker, Interleaf or EPS.
Frame*UserDefinedWidth | 210 | The default value for the paper width when the Frame*PaperFormat preference is set to UserDefined.
Frame*UserDefinedHeight | 297 | The default value for the paper height when the Frame*PaperFormat preference is set to UserDefined.
Frame*MarginUpper | 25 | The default value for the upper margin when printing to FrameMaker, Interleaf or EPS.
Frame*MarginLower | 35 | The default value for the lower margin when printing to FrameMaker, Interleaf or EPS
Frame*MarginLeft | 25 | The default value for the left margin when printing to FrameMaker, Interleaf or EPS
Frame*MarginRight | 27 | The default value for the right margin when printing to FrameMaker, Interleaf or EPS
FrameMakerCommand | "maker" | The default Execute command in the Print dialog when Format is specified as Import into FrameMaker. UNIX only, see Note:.
HeaderFile | "" | The default value for the option Header file in the Print dialog.
HeaderTextHeight | 12 (pt) | The size of the font face used in headers and footers.
Landscape | off | The default value for the option Orientation in the Print dialog (off means landscape).
MarginLeft | 10 (mm) | The default value for the parameter Left margin in the Print Margins dialog.
MarginLower | 25 (mm) | The default value for the parameter Lower margin in the Print Margins dialog.
MarginRight | 10 (mm) | The default value for the parameter Right margin in the Print Margins dialog.
MarginUpper | 42 (mm) | The default value for the parameter Upper margin in the Print Margins dialog.
MaxTextLineLength | 80 | How long a line in a text file can be before it is divided/wrapped, resulting in several lines in the printout. A value of zero means no wrapping. Lines are usually divided at word boundaries.
MinimumLineWidth | 3 (1/10 pt) | The minimum thickness applied on lines in the printout.
OnlyChaptersInTOC | off | If only chapter symbols, or chapter symbols and diagrams and documents will be visible in the table of contents.
OrganizerView | on | The default value for the option Organizer View in the Organizer Print dialog.
PageMarkers | off | The default value for the option Page markers in the Print dialog.
PaperFormat | A4 | The default value for the option Paper format in the Print dialog.
PrintCollapsed | on | If collapsed texts from text, comment and text extension symbols are printed in full on a separate page or not.
PrinterCommand | "lpr -h -r" (In Windows, the lpr command is available in the Telelogic Tau distribution.) | The default Execute command in the Print dialog when Format is specified as One PostScript File.
RemoveTempFiles | on | If temporary files should be removed after printing is done.
Scale | 100 (%) | The default value for the parameter Scale in the Print dialog.
TableOfContents | off | The default value for the option Table of Contents in the Organizer Print dialog.
TextHeight | 10 (mm) | The font size used when printing expanded text symbols.
ToCShowPages | off | The presence of page numbers in generated table of contents.
UserDefinedHeight | 297 (mm) | The default value for the parameter User paper height in the Print Margins dialog.
UserDefinedWidth | 210 (mm) | The default value for the parameter User paper width in the Print Margins dialog.

Text Editor Preferences

Prefix: TE*

Preference Parameter | Default | Affects
AlwaysNewWindow | off | If a new window should be opened or not when opening a text document.
PrintFontFamily | "Courier" | The font face used when printing text.
ShowLinks | on | If endpoints and links should be shown.
StateMatrixShowSelected | on | Decides if processes specified with StateMatrixFilter should be hidden or shown.
StateMatrixSortSignals | on | If signals in state matrices should be sorted.
StateMatrixSortStates | on | If states in state matrices should be sorted.
StateMatrixCalls | off | If a state matrix with procedure call transition information should be shown or not.
StateMatrixFilter | "" | Which processes that state matrices will be generated for.
StateMatrixNextstates | on | If a state matrix with nextstate transition information should be shown or not.
StateMatrixOutputs | off | If a state matrix with output transition information should be shown or not.
StateMatrixPageNumbers | on | If a state matrix with page numbers as transition information should be shown or not.
Statusbar | on | The presence of a status bar in the window.
Toolbar | on | The presence of a tool bar in the window.
TextTemplateDirectory | "" | Directory for common text file templates.


The SDL Suite Specific Preferences

These preferences are only available for the SDL suite tools.

SDL Editor Preferences

Prefix: Editor*
The Beige color used has the RGB values: (255, 249, 242)

Preference Parameter | Default | Affects
AdditionalHeadingOnlyOnFirstPage | off | If the Additional Heading symbol should be shown only on the first page.
AlwaysNewWindow | off | If a new window should be opened or not when opening an SDL diagram. See "Always new Window" .
BlockSubstructureSymbol*Use | on | If the symbol should be available in the symbol menu.
BlockSubstructureSymbol*Color | Black | The color of the symbol.
BlockSubstructureSymbol*FillColor | Beige | The fill color of the symbol.
BlockSymbol*Use | on | If the symbol should be available in the symbol menu.
BlockSymbol*Color | Black | The color of the symbol.
BlockSymbol*FillColor | Beige | The fill color of the symbol.
BlockTypeSymbol*Use | on | If the symbol should be available in the symbol menu.
BlockTypeSymbol*Color | Black | The color of the symbol.
BlockTypeSymbol*FillColor |  | The fill color of the symbol.
ChannelSubstructureSymbol*Use | on | If the symbol should be available in the symbol menu.
ChannelSubstructureSymbol*Color | Black | The color of the symbol.
ChannelSubstructureSymbol*FillColor | Beige | The fill color of the symbol.
ClassSymbol*Use | on | If the symbol should be available in the symbol menu.
ClassSymbol*Color | Black | The color of the symbol.
ClassSymbol*FillColor | Beige | The fill color of the symbol.
CommentLeftSymbol*Use | off | If the symbol should be available in the symbol menu.
CommentLeftSymbol*Color | Black | The color of the symbol.
CommentLeftSymbol*FillColor | Beige | The fill color of the symbol.
CommentSymbol*Use | on | If the symbol should be available in the symbol menu.
CommentSymbol*Color | Black | The color of the symbol.
CommentSymbol*FillColor | Beige | The fill color of the symbol.
CompletionMaxPages | 10 | The maximum number of initial diagram pages searched by the word completion operation.
ConnectorSymbol*Use | on | If the symbol should be available in the symbol menu.
ConnectorSymbol*Color | Black | The color of the symbol.
ConnectorSymbol*FillColor | Beige | The fill color of the symbol.
ContinuousSignalSymbol*Use | on | If the symbol should be available in the symbol menu.
ContinuousSignalSymbol*Color | Black | The color of the symbol.
ContinuousSignalSymbol*FillColor | White | The fill color of the symbol.
CreateRequestSymbol*Use | on | If the symbol should be available in the symbol menu.
CreateRequestSymbol*Color | Black | The color of the symbol.
CreateRequestSymbol*FillColor | Beige | The fill color of the symbol.
DecisionSymbol*Use | on | If the symbol should be available in the symbol menu.
DecisionSymbol*Color | Black | The color of the symbol.
DecisionSymbol*FillColor | Beige | The fill color of the symbol.
FontText*ScreenFontFamily | "Helvetica" | The font face to use when displaying text on screen.
FontText*PrintFontFamily | "Helvetica" | The font face used when printing text.
FontText*TextSymbolFontFamily | "Helvetica" | The font face to use when displaying text in text symbols on screen and in print.
FontText*TextHeight | 9 (pt) | The height of text in symbols (except kernel heading symbols and page name symbols) on flow diagrams, and text symbols and signal list symbols on interaction diagrams.
FontText*NameTextHeight | 12 (pt) | The height of text in kernel heading symbols, page name symbols and text objects on interaction diagrams (exception from text symbols and signal list symbols). See "Default Font Sizes" .
FontText*TaskSymbolLeftAligned | off | If the text in the task, procedure call, macro call, create request and save symbol should be left aligned.
FontText*MinimumTextUpdateDelay | 0 (milliseconds) | The minimum time delay to update text in symbols.
FontText*BlinkingTextCursor | on | If the text cursor (vertical bar) should blink in the drawing area.
GateSymbol*Use | on | If the symbol should be available in the symbol menu.
GateSymbol*Color | Black | The color of the symbol.
GrammarHelp | off | If the Grammar Help window is to be opened automatically at start-up.
InputLeftSymbol*Use | off | If the symbol should be displayed left-oriented or not.
InputLeftSymbol*Color | Black | The color of the symbol.
InputLeftSymbol*FillColor | Beige | The fill color of the symbol.
InputSymbol*Use | on | If the symbol should be available in the symbol menu.
InputSymbol*Color | Black | The color of the symbol.
InputSymbol*FillColor | Beige | The fill color of the symbol.
InteractionPage*GridHeight | 5 (mm) | The vertical grid on interaction pages.
InteractionPage*GridWidth | 5 (mm) | The horizontal grid on interaction pages.
InteractionPage*MarginLeft | 15 (mm) | The distance between the The Frame and the left boundary of the drawing area.
InteractionPage*MarginLower | 15 (mm) | The distance between the The Frame and the lower boundary of the drawing area.
InteractionPage*MarginRight | 15 (mm) | The distance between the The Frame and the right boundary of the drawing area.
InteractionPage*MarginUpper | 15 (mm) | The distance between the The Frame and the upper boundary of the drawing area.
InteractionPage*SymbolHeight | 20 (mm) | The default height of symbols on interaction diagrams.
InteractionPage*SymbolWidth | 30 (mm) | The default width of symbols on interaction diagrams.
MacroCallSymbol*Use | on | If the symbol should be available in the symbol menu.
MacroCallSymbol*Color | Black | The color of the symbol.
MacroCallSymbol*FillColor | Beige | The fill color of the symbol.
MacroInletSymbol*Use | on | If the symbol should be available in the symbol menu.
MacroInletSymbol*Color | Black | The color of the symbol.
MacroInletSymbol*FillColor | Beige | The fill color of the symbol.
MacroOutletSymbol*Use | on | If the symbol should be available in the symbol menu.
MacroOutletSymbol*Color | Black | The color of the symbol.
MacroOutletSymbol*FillColor | Beige | The fill color of the symbol.
OperatorSymbol*Use | on | If the Operator reference symbol should be available or not in the symbol menu. (The symbol is an SDL suite specific extension to Z.100.)
OperatorSymbol*Color | Black | The color of the symbol.
OperatorSymbol*FillColor | Beige | The fill color of the symbol.
OutputLeftSymbol*Use | off | If the symbol should be displayed left-oriented or not.
OutputLeftSymbol*Color | Black | The color of the symbol.
OutputLeftSymbol*FillColor | Beige | The fill color of the symbol.
OutputSymbol*Use | on | If the symbol should be available in the symbol menu.
OutputSymbol*Color | Black | The color of the symbol.
OutputSymbol*FillColor | Beige | The fill color of the symbol.
Page*AutoNumber | on | If added SDL pages should be autonumbered (1, 2,... N). See "The Autonumbered Option" .
Page*Height | 230 (mm) | The height of a new page.
Page*Width | 190 (mm) | The width of a new page.
PrintZ100Symbols | off | Printing SDL symbols with an appearance that complies to Z.100.
PriorityInputLeftSymbol*Use | off | If the symbol should be displayed left-oriented or not.
PriorityInputLeftSymbol*Color | Black | The color of the symbol.
PriorityInputLeftSymbol*FillColor | Beige | The fill color of the symbol.
PriorityInputSymbol*Use | on | If the symbol should be available in the symbol menu.
PriorityInputSymbol*Color | Black | The color of the symbol.
PriorityInputSymbol*FillColor | Beige | The fill color of the symbol.
ProcedureCallSymbol*Use | on | If the symbol should be available in the symbol menu.
ProcedureCallSymbol*Color | Black | The color of the symbol.
ProcedureCallSymbol*FillColor | Beige | The fill color of the symbol.
ProcedureReturnSymbol*Use | on | If the symbol should be available in the symbol menu.
ProcedureReturnSymbol*Color | Black | The color of the symbol.
ProcedureReturnSymbol*FillColor | Beige | The fill color of the symbol.
ProcedureStartSymbol*Use | on | If the symbol should be available in the symbol menu.
ProcedureStartSymbol*Color | Black | The color of the symbol.
ProcedureStartSymbol*FillColor | Beige | The fill color of the symbol.
ProcedureSymbol*Use | on | If the symbol should be available in the symbol menu.
ProcedureSymbol*Color | Black | The color of the symbol.
ProcedureSymbol*FillColor | Beige | The fill color of the symbol.
ProcessPage*GridHeight | 5 (mm) | The vertical grid on flow diagrams.
ProcessPage*GridWidth | 5 (mm) | The horizontal grid on flow diagrams.
ProcessPage*MarginLeft | 0 (mm) | The distance between the The Frame and the left boundary of the drawing area.
ProcessPage*MarginLower | 0 (mm) | The distance between the The Frame and the lower boundary of the drawing area.
ProcessPage*MarginRight | 0 (mm) | The distance between the The Frame and the right boundary of the drawing area.
ProcessPage*MarginUpper | 0 (mm) | The distance between the The Frame and the upper boundary of the drawing area.
ProcessPage*SymbolHeight | 10 (mm) | The default height for symbols on flow pages. (The width / height relationship is fixed to 2:1.)
ProcessSymbol*Use | on | If the symbol should be available in the symbol menu.
ProcessSymbol*Color | Black | The color of the symbol.
ProcessSymbol*FillColor | Beige | The fill color of the symbol.
ProcessTypeSymbol*Use | on | If the symbol should be available in the symbol menu.
ProcessTypeSymbol*Color | Black | The color of the symbol.
ProcessTypeSymbol*FillColor | Beige | The fill color of the symbol.
SaveSymbol*Use | on | If the symbol should be available in the symbol menu.
SaveSymbol*Color | Black | The color of the symbol.
SaveSymbol*FillColor | Beige | The fill color of the symbol.
SDLTraceColor | yellow | The temporary background color to use for visited SDL symbols during SDL trace.
Scale | 100 (%) | The scale when displaying a diagram on screen.
ScreenZ100Symbols | off | Displaying SDL symbols on screen with an appearance that complies to Z.100.
ServiceSymbol*Use | on | If the symbol should be available in the symbol menu.
ServiceSymbol*Color | Black | The color of the symbol.
ServiceSymbol*FillColor | Beige | The fill color of the symbol.
ServiceTypeSymbol*Use | on | If the symbol should be available in the symbol menu.
ServiceTypeSymbol*Color | Black | The color of the symbol.
ServiceTypeSymbol*FillColor | Beige | The fill color of the symbol.
ShowGrid | off | If grid points should be shown on screen.
ShowLinks | on | If endpoints and links should be shown.
ShowPageBreaks | on | If printer page breaks should be visible or not on the screen.
ShowSignalDeclaration | on | If the signal declaration should be shown in the message area for a selected signal name.
SignalDictionary*Use | off | If a Signal Dictionary window should be opened automatically upon start of the SDL Editor.
SignalDictionary*All | off | If the Signal Dictionary option All should be enabled by default.
SignalDictionary*Down | on | If the Signal Dictionary option Down should be enabled by default.
SignalDictionary*External | off | If the Signal Dictionary option External should be enabled by default.
SignalDictionary*MSC | off | If the Signal Dictionary option MSC should be enabled by default.
SignalDictionary*This | off | If the Signal Dictionary option This should be enabled by default.
SignalDictionary*Up | on | If the Signal Dictionary option Up should be enabled by default.
StartSymbol*Use | on | If the symbol should be available in the symbol menu.
StartSymbol*Color | Black | The color of the symbol.
StartSymbol*FillColor | Beige | The fill color of the symbol.
StateSymbol*Use | on | If the symbol should be available in the symbol menu.
StateSymbol*Color | Black | The color of the symbol.
StateSymbol*FillColor | Beige | The fill color of the symbol.
Statusbar | on | The presence of a status bar in the SDL Editor window.
StopSymbol*Use | on | If the symbol should be available in the symbol menu.
StopSymbol*Color | Black | The color of the symbol.
StopSymbol*FillColor | White | The fill color of the symbol.
SymbolMenu | on | The presence of a symbol menu in the SDL Editor window.
SyntaxCheck | on | Enables or disables the syntactic checking performed by the SDL Editor at editing time.
SystemTypeSymbol*Use | on | If the symbol should be available in the symbol menu.
SystemTypeSymbol*Color | Black | The color of the symbol.
SystemTypeSymbol*FillColor | Beige | The fill color of the symbol.
TabEqualsCompletion | on | If the tab key invokes word completion or produces a tab character.
TaskSymbol*Use | on | If the symbol should be available in the symbol menu.
TaskSymbol*Color | Black | The color of the symbol.
TaskSymbol*FillColor | Beige | The fill color of the symbol.
TemplateFile | "sdt.tpl" | The name of the file containing the grammar templates used by the Grammar Help window.
TextExtensionSymbol*Use | on | If the symbol should be available in the symbol menu.
TextExtensionSymbol*Color | Black | The color of the symbol.
TextExtensionSymbol*FillColor | Beige | The fill color of the symbol.
TextReferenceSymbol*Use | on | If the symbol should be available in the symbol menu.
TextReferenceSymbol*Color | Black | The color of the symbol.
TextReferenceSymbol*FillColor | Beige | The fill color of the symbol.
TextSymbol*Use | on | If the symbol should be available in the symbol menu.
TextSymbol*Color | Black | The color of the symbol.
TextSymbol*FillColor | Beige | The fill color of the symbol.
TextWindow | on | The presence of a text window in the SDL Editor window.
TidyUp*MaxCommentLineLength | 22 | Maximum number of characters per line in comment symbols after tidy up
TidyUp*TransNewPage | on | Start each transition on a new page
TidyUp*ExtraSpace | on | Insert extra space after a symbol attached to a large comment or text extension, to avoid overlapping any comment or text extension attached to the next symbol.
TidyUp*FormatInputOutput | on | Format text in input and output symbols using newline characters and text extension symbols, to try to avoid text outside the symbol.
TidyUp*MakeCommentSymbols | on | Replace textual comments with comment symbols.
TidyUp*CommentsLeft | on | Place comment symbols to the left of the symbols that they are attached to.
TidyUp*SmartAutoLabels | on | Generate automatic names for all labels. The names are generated from the closest available statename. If the preference is off the names for the already existing labels will be preserved and new generated labels will have names LblNNN.
TidyUp*NoStateExtension | on | Avoid attaching text extension symbols to state symbols.
TidyUp*NoDecisionExtension | on | Avoid attaching text extension symbols to decision symbols.
TidyUp*SortStates | off | Sort states and transitions in alphabetical order.
Toolbar | on | The presence of a tool bar in the SDL Editor window.
TransitionOptionSymbol*Use | on | If the symbol should be available in the symbol menu.
TransitionOptionSymbol*Color | Black | The color of the symbol.
TransitionOptionSymbol*FillColor | Beige | The fill color of the symbol.

OM/SC/HMSC/MSC/DP Editor Preferences

Prefix: OME*

Preference Parameter | Default | Affects
AlwaysEndpointClass | on | If an endpoint should be automatically added on new class symbols.
AlwaysEndpointObject | off | If an endpoint should be automatically added on a new object symbol.
AlwaysNewWindow | off | If a new window should be opened or not when opening a diagram. See "Always new Window" .
AutoNumberPages | on | If added pages should be autonumbered (1, 2,... N). See "Autonumbered" .
BlinkingTextCursor | on | If the text cursor (vertical bar) should blink in the drawing area.
DPComponentSymbolColor | Black | The color of the symbol.
DPNodeSymbolColor | Black | The color of the symbol.
DPObjectSymbolColor | Black | The color of the symbol.
DPThreadSymbolColor | Black | The color of the symbol.
HMSCConditionSymbolColor | Black | The color of the symbol.
HMSCConnectionSymbolColor | Black | The color of the symbol.
HMSCReferenceSymbolColor | Black | The color of the symbol.
HMSCStartSymbolColor | Black | The color of the symbol.
HMSCStopSymbolColor | Black | The color of the symbol.
MinimumTextUpdateDelay | 0 (milliseconds) | The minimum time delay to update text in symbols.
MSCHorizontalSpacing | 25 (mm) | The horizontal spacing unit between instances. See "Spacing" .
MSCInstanceRuler | on | The presence of an Instance Ruler in the MSC Editor window.
MSCPrintInstanceRuler | on | If an Instance Ruler should be included on the printed pages.
MSCVerticalSpacing | 3 (mm) | The vertical spacing unit between instances. See "Spacing" .
NameTextHeight | 12 (pt) | The height of text in names of symbols.
OMClassSymbolColor | Black | The color of the symbol.
OMObjectSymbolColor | Black | The color of the symbol.
PageHeight | 230 (mm) | The height of a new page.
PageWidth | 190 (mm) | The width of a new page.
PrintFontFamily | "Helvetica" | The font face used when printing text.
Scale | 100 (%) | The scale when displaying a diagram on screen.
ScreenFontFamily | "Helvetica" | The font face to use when displaying text on screen.
SCStartSymbolColor | Black | The color of the symbol.
SCStateSymbolColor | Black | The color of the symbol.
SCStopSymbolColor | Black | The color of the symbol.
ShowGrid | off | If grid points should be shown on screen.
ShowInstanceComposition | on | If the Instance decomposition should be displayed.
ShowInstanceKind | on | If the Instance kind should be displayed.
ShowInstanceName | on | If the Instance name should be displayed.
ShowLinks | on | If endpoints and links should be shown.
ShowMessageName | on | If the Message name should be displayed.
ShowMessageParameters | on | If the Message parameters should be displayed.
ShowPageBreaks | on | If printer page breaks should be visible or not on the screen.
Statusbar | on | The presence of a status bar in the editor window.
SymbolMenu | on | The presence of a symbol menu in the editor window.
TextHeight | 9 (pt) | The height of text in symbols (except heading symbols and page name symbols) and line attributes, except for names of symbols.
TextSymbolColor | Black | The color of the symbol.
TextWindow | on | The presence of a text window in the editor window.
Toolbar | on | The presence of a tool bar in the editor window.

Index Viewer Preferences

Prefix: Index*

Preference Parameter | Default | Affects
FilterTypes | "" | Which SDL entities to be hidden by default in the Filter Types dialog. The entities should be entered as a number of text strings, separated by spaces.
FilterDiagrams | "" | Which SDL entities that will be visible.
FilterUses | "" | Which kind of entity use that will be visible.
IndexAppearance | Detailed | The layout of SDL entity information. The alternatives are Compact, VerticalCompact, HorizontalDetailed and Detailed.
NameFirst | on | If entities will be sorted by name or by type and name.
ShowSelectedDiagrams | on | If diagrams specified with FilterDiagrams should be shown or hidden.
ShowSelectedTypes | on | If types specified with FilterTypes should be shown or hidden.
ShowSelectedUses | on | If uses specified with FilterUses should be shown or hidden.
Statusbar | on | The presence of a status bar in the window.
Toolbar | on | The presence of a tool bar in the window.

Type Viewer Preferences

Prefix: Type*

Preference Parameter | Default | Affects
ShowInstanceSymbols | on | The default value for the Instance symbols option defined in the List Options.
ShowNameText | on | The default value for the Name option defined in the Symbol Options.
ShowQualifierText | off | The default value for the Qualifier option defined in the Symbol Options.
ShowTypeText | on | The default value for the Type option defined in the Symbol Options.
Statusbar | on | The presence of a status bar in the window.
Toolbar | on | The presence of a tool bar in the window.

Coverage Viewer Preferences

Prefix: Cover*

Preference Parameter | Default | Affects
AboveThreshold | on | Which option to select by default between Show symbols executed >= threshold and Show symbols executed <= threshold (on means >=).
FillSymbols | on | Whether to fill symbols or not when displaying a coverage tree.
LogThickness | off | Which option to select by default between Normal line thickness and Logarithmic line thickness (off means normal).
MaxLineThickness | 60 (1/10 mm) | The default value for the parameter Max line thickness.
ShowTransitions | on | Which option to select by default between Transition Coverage and Symbol Coverage (on means transition).
ShowVisibilityLine | on | Which option to select by default between Show visibility line and Hide Visibility line (on means show).
Statusbar | on | The presence of a status bar in the window.
Toolbar | on | The presence of a tool bar in the window.
VisibilityThreshold | 0 | The default value for the parameter Threshold.

SDL Overview Generator Preferences

Prefix: Overview*

Preference Parameter | Default | Affects
DistanceBetweenLines | 3 (mm) | The default value for the option Distance between Lines.
DistanceBetweenSymbols | 10 (mm) | The default value for the option Distance between Symbols.
ExpandedDiagramsOnly | on | The default value for the option Use Expanded Diagrams Only.
IncludeLines | on | The default value for the option Include Lines.
IncludeProcedures | off | The default value for the option Include Procedures & Operators.
IncludeStates | off | The default value for the option Include States.
Margin | 10 (mm) | The default value for the parameter Margin.
MinimumSymbolHeight | 10 | The default value for the option Minimum Symbol Height.
MinimumSymbolLength | 20 | The default value for the option Minimum Symbol Width.
NameTextHeight | 10 (pt) | The size of textual elements in Overview diagrams. See "Default Font Sizes" .
PrintFontFamily | "Helvetica" | The font face used when printing text.
ScreenFontFamily | "Helvetica" | The font face to use when displaying text on screen.
ShowLineNames | on | The default value for the SDL Editor option Show line names.
ShowSignallists | off | The default value for the SDL Editor option Show signal lists.
TextHeight | 8 (pt) | The size of textual elements in Overview diagrams. See "Default Font Sizes" .

Simulator GUI Preferences

Prefix: SGUI*

Preference Parameter | Default | Affects
ButtonFileName | "def.btns" | What file containing Button definitions to load by default.
CommandFileName | "def.cmds" | What file containing Command definitions to load by default.
WatchFileName | "def.vars" | What file containing Variable definitions to load by default.
MaxOutputToRetries | 50 | Maximum number of retries of next-transition and output-to, when output-to fails during simulator script execution.
TextBufferLimit | 10000 | Maximum number of characters in the simulator UI text log. A value of 0 means "no limit".

Validator GUI Preferences

Prefix: VGUI*

Preference Parameter | Default | Affects
ButtonFileName | "val_def.btns" | What file containing Button definitions to load by default.
CommandFileName | "val_def.cmds" | What file containing Command definitions to load by default.
WatchFileName | "val_def.vars" | What file containing Variable definitions to load by default.


4 Managing Preferences

This chapter describes the principles for the management of preference parameters in a Telelogic Tau environment. It also describes how to use the Preference Manager to customize the Telelogic Tau installation.

For a reference to the Preference Manager and the preference parameters, see 3 The Preference Manager.


Introduction

Different users are likely to use Telelogic Tau in different ways. Even the same user may use the tools differently in different work areas. The Preference Manager allows you to customize the default behavior of the Telelogic Tau tools in order to minimize the number of operations that you have to perform manually after having started a tool.

The Preference Manager allows you to set up the default behavior for the following tools:

  • Organizer
  • SDL Editor
  • Diagram editors
  • Text Editor
  • Index Viewer
  • Type Viewer
  • Coverage Viewer
  • Overview Generator and Editor
  • Simulator Graphical User Interface
  • Validator Graphical User Interface
  • Help viewer
  • Preference Manager
  • Print
  • generic Telelogic Tau tool preferences.

Note:

The Preference Manager only handles the SDL suite-specific tools, and the common Telelogic Tau tools. The behavior of the TTCN suite-specific tools cannot be changed by these preferences. For more information, see 30 Customizing the TTCN Suite (on UNIX).

Preferences may be customized for an individual user or may apply to an entire project or even organization that uses the Telelogic Tau tools.


How Preferences Are Managed

Depending on your needs and how you configure your environment, the Telelogic Tau tools handle preference parameters either as:

  • Organization (company) preferences
    These are parameters that should affect all work that is done with the Telelogic Tau tools within an organization; for example you might want to prohibit the use of some specific SDL symbols, to set up printout headers and footers with your company's logotype, etc.
  • Project preferences
    These are parameters that should affect the properties that are specific for a particular project; for instance what make and build options should be used by the Analyzer and Code Generators within the scope of a project. Project preferences can also be regarded as a specialization of the organization preferences, specific for a project.
  • User-defined preferences
    User-defined preferences are parameters that would typically affect the behavior of the tools to have them fulfil the individual user's needs; such as what additional windows to open or not open at start-up of the tool.
  • Default (factory) settings
    These settings are "burnt-in" into the tools and will be used whenever no other preferences are available.

Figure 67 : The user's view of the preference parameters

Preferences and Dialog Options

The Telelogic Tau tools allow you to customize a number of options that define the default behavior of a tool, using the Preference Manager (the TTCN suite specific preferences can be customized as described in 30 Customizing the TTCN Suite (on UNIX)). Some of these preferences may be overridden during the current tool session, by assigning a new value to the option. The option's latest value will then be memorized and reused, where possible.

Example 12 : Print preferences and options.

  1. Assume that you have assigned the Print preference parameter PrinterCommand the value lpr (i.e. send to printer queue).
  2. You print from the SDL Editor, change the option Execute to ghostview (i.e. a PostScript previewer) and click Print. Next time you print from the SDL Editor, the Execute option is memorized and reads ghostview (until you terminate the SDL Editor session).
  3. But, when you print from another tool (the MSC Editor for instance), the Execute option is preset to the preferred value, i.e. lpr.

Preferences and the SDL Suite Diagram Options

The SDL suite uses your preferred values when you create a new diagram and assign it:

  • A width (set with the command Drawing Size)
  • A height (set with the command Drawing Size)
  • A viewing scale (set with the command Set Scale)

Each individual SDL diagram also stores information about:

  • Whether to align symbols and lines to the grid or not
  • Whether to check syntax or not when the diagram is edited
  • Whether to fix endpoints at frame or not
  • Whether to show the Additional Heading symbol only on the first page
    These diagram parameters are set with the SDL Editor command Diagram Options.

Each individual MSC also stores information about:

  • Whether to show the instance name or not
  • Whether to show the instance kind or not
  • Whether to show the instance composition or not
  • Whether to show the message name or not
  • Whether to show message parameters or not
    These diagram parameters are set with the MSC Editor command Diagram Options.

Each individual OM, SC and HMSC diagram also stores information about:

  • Whether to align symbols and lines to the grid or not

When you save a diagram, the current diagram parameter values are saved on the diagram file and will be reused next time you open it, overriding the preference parameters.

Preferences and System File Options

The Telelogic Tau tools use your preferred values when creating new system files (the .sdt files that are managed by the Organizer).

When you save a system file, the parameters that are related to the system are also stored on the system file, overriding the preference parameters:

  • The parameters managed by the Set Directories dialog
  • The parameters managed by the View Options dialog
  • The parameters managed by the Set Scale dialog
  • The parameters managed by the Analyze dialog
  • The parameters managed by the Make dialog

See "Options in the System File" for a reference to the contents of a system file and what parameters are stored on it.


Starting the Preference Manager

Note:

Each individual user should make sure the HOME environment variable is defined in order to take advantage of the Preference Manager. The HOME variable normally denotes the user's home directory.

To start the Preference Manager:

  • Select Preference Manager from the Organizer's Tools menu.
    The Preference Manager will be opened.

Figure 68 : The Preference Manager window

Only one instance of the Preference Manager can be started at a time.


Adjusting a Preference Parameter

To modify a preference parameter:

  1. First, locate the symbol representing the Telelogic Tau tool it governs (you may have to scroll the tree area up or down to make the symbol visible and to expand it with the Expand menu choice from View Menu).
  2. Once the parameter is located, select it. (The information within parentheses is the current value, the item within brackets shows the source, i.e. user-defined / project / organization).
  3. The area at the bottom of the window is updated according to the type of parameter you have selected. The sections below describe how to adjust the preference parameter.

Note:

You have the possibility to revert any parameter to its saved value or default value, using the Set Saved Value / Set Default Value command.

Adjusting a Textual Parameter

To edit a textual value, simply place the cursor on the text field and enter the text of your choice. No control of what is entered takes place.

Adjusting a Boolean Parameter

Click on to turn an option on.

Adjusting a Ranged Integer

Drag the slider for a coarse adjustment or click the slider bar for a fine adjustment.

Adjusting an Option Menu

Clicking on the button brings up a pop-up menu where all permissible values are listed. Select the value of your choice.

    • When you move the mouse pointer over a value in the option menu, a short description of the value is printed in the status bar. Values whose description starts with "(UNIX only)" or "(Windows only)" should only be selected on a UNIX system or a Windows system, respectively.

Adjusting an Option Menu Textual Preference

You may select the preference parameter from a number of predefined values, available on an option menu (see above). As an alternative, you may type in the value into the text field, which grants access to not predefined values.

Adjusting a Font Preference (Windows only)

You must select the font by clicking the folder button, which opens a Microsoft Windows Font dialog. It is not possible to edit the text field to the left of the folder button.

In the font dialog, all TrueType fonts in the system are listed. It is also possible to select font style and size, but these values have no effect. Only the specified font name is used.

    • Any font name can be entered by editing the Font text field in the font dialog. This possibility is useful when setting a font for printing that is not available in the system, but it does exist on the printer.
    • The SDL suite will also recognize the three font names "Times", "Helvetica" and "Courier". These are translated into the TrueType fonts Times New Roman, Arial, and Courier New, respectively.
    • When using other fonts than the three mentioned above for printing, the preference Print*DestinationFormat should be set to MSWPrint to get the best result for symbols that are adjusted to the text size.

Adjusting a File Preference

You may assign the preference parameter any file name, entered as a text string into the text field.

    • You can also click the folder button, which issues a file selection dialog in which you can select a file.


Customizing the On-Line Help

In Telelogic Tau, you can request on-line help by selecting a menu choice in a Help menu, a pop-up menu or by clicking a Help button in a dialog. For more information about Help menu choices, see "Help Menu" .

To be able to view the on-line help, you need to have one of the following HTML-viewers installed:

  • Netscape Navigator
  • Microsoft Internet Explorer1

Also, you have to make sure that the on-line help files (in HTML-format) have been installed.

In the on-line help, you can also find information about how to use it.

Configuring the Help Environment

  1. In the Preference Manager window, locate the icon symbolizing the help preferences.

  2. Double-click the icon. This will expand it and list the available help preferences.
  3. Select and, if required, adjust the preference HelpViewer to an adequate value, either Netscape or Internet Explorer. Use the option menu that appears at the bottom of the window to select the value.
  4. Select and, if required, adjust the preference parameter
    NetscapeCommand or InternetExplorerCommand to a command that starts Netscape Navigator or Internet Explorer in your computer environment. Type the command in the text field that appears at the bottom of the window.

Note:

The command must be available via your PATH variable.

To limit local disk space usage in a multi-user environment, you may optionally put the on-line help files on a network server (unless you already have a network installation of Telelogic Tau, which is usually the case on UNIX). To do this, you move all files in the help directory and its subdirectories (available in the local installation directory, by default C:\Telelogic\SDL_TTCN_Suite4.4) to the network server area. This step may already have been performed on your computer system, so check where the on-line help files are stored.
Then check and adjust the preference parameter HelpDirectory to the help directory on the network server.
  5. Select and, if required adjust the preference parameter HelpDirectory to the help directory (by default C:\Telelogic\SDL_TTCN_Suite4.4\help in Windows and /appl/telelogic/help/ on UNIX).
  6. Save the preference settings and exit the Preference Manager. The on-line help is now configured in accordance to your computer environment.

Timeout Issues

When you request on-line help from Telelogic Tau, the Postmaster supervises the communication. On a heavily loaded computer system, the help viewer may fail to respond within the time limit specified by the environment variable STARTTIMEOUT. When this occurs on UNIX, a message is appended to the console window. The environment variable should be adjusted to a higher value to match the typical response times for the computer system where Telelogic Tau and the help viewer are running.

1

Telelogic Tau supports Microsoft Internet Explorer 4.0 and later versions as help viewer, but it may also work to use earlier versions.


Customizing User-Defined Preferences

Saving Parameters as User-Defined

To preserve the modifications for the future Telelogic Tau tools sessions, you must save the preference settings. The preferences are saved on a preference file denoted by $HOME/.sdtpref (on UNIX), or %HOME%\sdt.ini (in Windows).

Note:

In Windows: If the environment variable HOME is not set, the preferences are stored on a preference file in the directory from which the tool was started.

Whenever you require to save a company or project preference (and thus customize it as your personal preference), you need to confirm the operation by clicking Save in the following dialog:

Figure 69 : Confirming to modify a project or organization parameter

The reason for this is that a parameter which is defined at the company or project level should not be possible to modify inadvertently by any individual user of the Telelogic Tau tools.

Reverting User-Defined Parameters

The Telelogic Tau tools allows you to remove a preference parameter from your personal settings, in which case you will revert to the project or company preferences (or the default settings, if no project or company preferences are defined).

To revert a user-defined preference parameter, you must remove it from your preference file. The Telelogic Tau tools can do this for you:

  1. Locate the preference parameter and select it.
  2. From the Edit menu, select Unsave. A dialog appears, prompting you to confirm the operation.

Figure 70 : The Unsave dialog

    • Click on the OK button to confirm the operation.
  3. The parameter will be removed from your personal preferences next time you Save the preference settings.


Customizing Company Preferences

The Telelogic Tau installation may contains a file with all Preference parameters, along with their default values. The file is identified as $telelogic/.sdtpref (on UNIX), or sdt.ini (in Windows), and resides in the installation directory of the Telelogic Tau tools.

This file is also referred to as the company / organization preference file. In Windows, to be meaningful in a multi-user environment, the company preference file should be stored on a network drive (and, of course, all Telelogic Tau users should have read access to this file).

To customize the company's preferences, do as follows:

  1. UNIX only: Login on a privileged account (for instance as system manager or the user who is the owner of the installation).
  2. On UNIX: Change the default directory to $telelogic. Start the Telelogic Tau tools.
    In Windows: Start a Telelogic Tau tool from the installation directory, i.e. not from a shortcut icon that defines another start directory.
  3. Start the Preference Manager from the Organizer.
  4. Modify the preference parameters of your choice (described in "Adjusting a Preference Parameter" ). For a description of the meaning of the preference parameters, see "Preference Parameters" .
  5. Save the parameter setup. This concludes the procedure. From now on, all users (in Windows, those that are running the Telelogic Tau tool from the network installation) will have the company setup as default (unless they have a different setup in their $HOME/.sdtpref (on UNIX), or %HOME%\sdt.ini (in Windows))

The TTCN suite specific preferences and their default values on UNIX are described in "How Resources Are Read" .


Customizing Project Preferences

It is possible to customize the default preferences by defining a so called project preference file. The values defined here will supersede the company preferences.

To create a preference file that will be used by a specific project, perform the following steps:

  1. UNIX only: Login on a privileged account (for instance as project manager or a user who has write access to a project directory).
  2. On UNIX: Copy the company preference file to a suitable directory (where the project preference file will be stored). Change the default directory to that directory, and start the Telelogic Tau tools.
    In Windows: Copy the company preference file to a suitable directory on a network drive, where the project preference file will be stored (using a directory on a local HDD for this purpose makes no sense). Start the SDL suite using a shortcut icon that designates this directory as the start directory.
  3. Start the Preference Manager from the Organizer.
  4. Modify the preference parameters of your choice (described above in "Adjusting a Preference Parameter" . For a description of the meaning of the preference parameters, see "Preference Parameters" .
  5. Save the parameter setup.
  6. On UNIX: In a suitable file that all project members should source, insert the following statement:
    setenv SDTPREF <directory>
    In Windows 95/98, insert the following in a suitable batch file that each project member runs at start-up (e.g. AUTOEXEC.BAT):
    set SDTPREF <directory>
    In Windows NT/2000, using the System properties in the Control Panel, set a SDTPREF environment variable to <directory>
    In all cases, <directory> denotes the project directory. Failing to do this will cause the Telelogic Tau tools to ignore the project preferences and to use company preferences instead.
  7. This concludes the procedure. From now on, all project members will have the project setup as default (unless they have a different setup in their $HOME/.sdtpref (on UNIX), or %HOME%\sdt.ini (in Windows)).


Locating the Preference Sources

To obtain information about the preference sources that are currently used (i.e. the directories and files that contain the company, project and user-defined preferences):

  • Select Info from the File menu. A message box is issued:

Figure 71 : The message with information about preference sources


5 Printing Documents and Diagrams

This chapter describes the different Print dialogs in Telelogic Tau and the printing differences between the Organizer, the SDL suite and the TTCN suite.

In the beginning of the chapter you can also find some introductory examples of how to print.


General

You can print from virtually all Telelogic Tau tools that provide a graphical user interface. It is possible to print the information that is managed by an individual tool, such as a graphical editor or a viewer, or to print all (or parts of) information that is related to a document structure, from the Organizer.

Print Dialogs

You specify the print options in Print and Print Setup dialog. These dialogs have different appearances, depending on where they are invoked from - the Organizer, the TTCN suite or an SDL suite tool. The TTCN suite in Windows also provides a print preview.

Output Formats

The following output formats are provided:

  • PostScript Output (including Encapsulated PostScript)
  • FrameMaker Output
  • Interleaf Output
  • Web Files (HTML+PNG)
  • MSWPrint Output (Windows only)
  • Microsoft Word Output (Windows only)

When you print a TTCN document, only PostScript output is available. However, in the TTCN suite in Windows, it is also possible to export a document to HTML, see "Converting to HTML" .

Print Preferences

It is also possible to set the default print options. For more information, see "Print Preferences" .


Printing Documents - Some Examples

This section is a brief guide to how to print some types of documents. The remaining sections of this chapter contains more detailed reference information about the print function and the Print dialogs.

You can print documents either from the Organizer or from within an individual Telelogic Tau tool.

Printing from the Organizer

This is an example of how to print a table of contents, one or more SDL interaction diagrams and type views from the Organizer. It is assumed that you have SDL interaction diagrams included in the Organizer and that a Type Viewer is running. The example describes how to print specific diagrams, but what is explained here may of course apply to other types of diagrams.

To print from the Organizer:

  • Select Print | Print All from the File menu.
    • Alternatively, click the quick-button for Print.

The Print dialog will be issued, where you may change the print settings.

Figure 72 : The Organizer Print dialog

You will start by changing the options in the Contents area:

  1. Turn the Table of contents toggle button on.
  2. Turn the SDL Interaction toggle button on.

  3. Click the setup button to the right of the SDL Interaction toggle button.

The Print Setup dialog will be issued where you may specify other options:

Figure 73 : The Print Setup dialog

    • You select what to print by using the arrow buttons to move diagrams between the Print and Do not print lists. Multiple selection is possible.
    • You may change the Scale of the printout.
    • You may change the Orientation of the printout.
  4. Click OK.
    The dialog will be closed.
  5. Turn the Type Diagram toggle button on, and click the setup button to the right of the toggle button.
    The Print Setup dialog will be issued and you may set additional options.
    • In the Print and Do not print lists, you may specify if any of the Type Viewer main window or Tree window (identified as Sub-window in the list) is to be excluded.

.

    • You may also change the other settings in the dialog.
  6. Click OK.
    The Print Setup dialog will be closed.

You may also want to specify the options in the Document area and the Destination area of the Print dialog:

  1. Select the Paper format that you want to use.

  2. Click the Margins button, to open the Paper Format Setup dialog.

Figure 74 : Setting the margins

In the dialog, you may change the paper margins, and in addition you may define your own paper size.
  3. You may also want to change other settings in the Document area.
  4. Select the output format in the Format option menu. You may choose between:
    • One PostScript File, suitable if you are going to print the documents on a PostScript printer.
    • One EPS File (Encapsulated PostScript), suitable if you are going to include graphics in a document. Select One EPS File Per Page if multiple pages are to be printed.
    • One FrameMaker MIF File, suitable if you want a file that can be imported into FrameMaker. Select One MIF File Per Page if multiple pages are to be printed.
    • Import into FrameMaker (UNIX only), suitable if you want to import the file directly into a currently opened FrameMaker document.
    • One Interleaf IAF File, suitable if you want a file that can be imported into Interleaf. Select One Interleaf IAF File Per Page if multiple pages are to be printed.
    • MSW Print (Windows only), which will make the print function use the printer you have set up with the Microsoft Windows Print Manager.
    • One Word DOC File (Windows only), suitable if you want a file that can be used in Microsoft Word 97 or Word 2000.
    • Word Files (DOC + EMF) (Windows only), suitable if you want to edit the document file in Microsoft Word and be able to regenerate the pages.
    • Web Files (HTML+PNG), suitable if you want to publish the document on the Web. HTML (text) and PNG (picture) files are produced that can be viewed in a web browser.
  5. Select the destination of the printout - a file or a printer.
    • If you want to save the printout on a file, you should make sure that the To file/Map file radio button is on. The button is labelled Map file if multiple pages are to be printed (when you have selected a One file Per Page option in the format menu). The map file will contain a translation table that shows the correspondence between the input diagrams and the generated files.
    • If you want to send the printout to a printer, you should ensure that the Execute radio button is on. You also have to type a printer command in the field, for example lpr. (It is possible to enter any post-processing command, such as a PostScript pre-viewer like ghostview.)
  6. Click the Print button to generate the printout.

For more information on how to use advanced printing features, see "Advanced Print Facilities" .

Printing from the SDL Suite

In these examples you will learn how to print from the MSC Editor and the Type Viewer. As most settings in those print dialogs are similar to the ones in the Organizer dialog, described above, the explanations below will be quite brief.

Printing from the MSC Editor

  1. Open a diagram in the MSC Editor.
  2. Select Print from the File menu.
    The MSC Editor Print dialog will be issued.
  3. Optionally, change the settings in the dialog.
  4. Click the Setup button.
    The Print Setup dialog will be issued, where you may specify some additional options:

Figure 75 : The MSC Editor Print Setup dialog

  5. Turn the Print only selected symbols toggle button on, if you have selected parts of the MSC diagram that you want to print. Deselected symbols will not be printed.
  6. Turn the Include Instance Ruler toggle button on, if you want to add an instance ruler into each printed page of an MSC. This means that the instance heads will be visible on each page - useful if you have a vertically extended MSC diagram that will cover more than one page.
  7. Click the OK button in the Print Setup dialog.
  8. Click the Print button in the Print dialog.
    The printout will be generated.

Printing from the Type Viewer

  1. Make sure the Type Viewer is running.
  2. Locate either the main window (the window labelled Type Viewer) or the Tree window.
  3. You may also want to change the contents of the window by using commands in the View menu.
  4. Select Print from the File menu in either the main window or the Tree window of the Type Viewer.
    If you select Print in the main window, the printout will be a type list. If you select Print in the Tree window, the printout will be an inheritance tree.
    The Print dialog will be issued.
  5. Adjust, if required, the options in the Print dialog and the Print Setup dialog.
  6. Click the Print button.
    The printout will be generated, based on the contents of the window that the Print command was selected in.


Default Scope of Print

In this section you will find information on what will be printed by default if you do not change any settings. It may also be possible to select what documents - of parts of documents - to print. See "Print Setup Dialogs" for more information on how to include more in the printout or how to restrict it.

Note:

Link endpoints are never shown in a printed document.

Printing from the Organizer

The default printout in the Organizer depends on selections and which tools are running:

SDL, OM, SC, MSC and HMSC Diagrams; Text Documents; Cross Reference Files

If choosing Print | Print All or Print | Print Selected and no item is selected in the Organizer, all documents that are managed by the Organizer (i.e. are visible in the Organizer view) will by default be included in the printout. If choosing Print | Print Selected and an item is selected in the Organizer, only the document(s) included in that item, and their sub-structure (if any), will by default be included in the printout.

Coverage Files

Coverage files cannot be included in the structure that is managed by the Organizer. The graphical presentation of a coverage file is computed as you request it by running the Coverage Viewer.

Therefore, the graphical presentation of coverage information will be included in the printout if the Coverage Viewer is running. The resulting printout will reflect the current contents of the windows, that is, the Main Window and the Coverage Details Window of the Coverage Viewer.

SDL Types and Type Instances

These entities cannot be included in the structure that is managed by the Organizer. Furthermore, this information is computed automatically by the Type Viewer. Therefore, the Type Viewer must be running in order to include the information in the resulting printout. The contents of the Main Window and Tree Window of the Type Viewer may be included.

TTCN Documents

If a TTCN document is selected in the Organizer, it is possible to print it, and the default scope of print is the selected document. A TTCN document cannot be included in a global printout, i.e. from the main Print dialog in the Organizer.

Printing from the SDL Suite

When you are going to print from an SDL suite tool, the printout will be the information that is currently visible in the active tool window.

The Setup button issues the Print Setup dialog which is used for specifying the scope of print. For example, if you print from the SDL Editor, the default scope of print is the active SDL Editor window, i.e. the SDL page currently being edited. In the Print Setup dialog, the scope of print may include any of the pages contained in the SDL diagram, or be restricted to the SDL symbols currently selected in the active window.

OM, SC, HMSC, SDL, MSC and Text Editor

The default scope of print is the active Editor window, i.e. the diagram page or the MSC currently being edited.

SDL Overview Viewer

The default scope of print is the active SDL Editor window, i.e. the SDL Overview diagram currently being viewed.

Type Viewer, Index Viewer and Coverage Viewer

In a Viewer, the scope of print is the contents of the window from where you invoked print.

Preference Manager and Link Manager

The scope of print is the current contents of the window.

Printing from the TTCN Suite

The default scope of print is the entire, currently active, TTCN document. The printout will contain one table per page.


The Print Dialogs in the SDL Suite and in the Organizer

To print, you select any of the submenus in the Print menu from the File menu. This will open a Print dialog. Since the print functions in the tools are not identical, the print dialogs look somewhat different depending on where they are invoked from. As you can see in Figure 76 and Figure 77, the differences are that the Organizer print dialog includes the Contents area, whereas the SDL suite tool print dialogs include a Setup button.

The main differences between printing from the Organizer and an SDL suite tool are:

  • In an SDL suite tool, it is only possible to print the information or document that is opened in the tool. In the Organizer, you can select to print all or any of the documents that are managed by the Organizer.
  • It is possible to print only selected symbols (when applicable) from an SDL Suite Editor, which is not possible from the Organizer.
  • When you print from a viewer, the printout will be the contents of the active window. If you print from the Organizer, it is possible to include or exclude a window from the printout, independently of which window is currently active.
  • In the Organizer it is also possible to print a table of contents and the contents of the Organizer window.

Note:

Endpoints are not displayed in printed documents/diagrams, regardless of the value of the Show Link Endpoints option.

Figure 76 : The Organizer Print dialog

Figure 77 : An SDL Suite tool print dialog

Both dialogs contain the following areas and buttons:

  • Document Area
  • Destination Area
  • Print button
  • Default button
  • Cancel button

The Organizer print dialog also contains the Contents area with setup buttons, and a Save button. A Setup button is also included in each the SDL suite tool print dialog. The setup buttons in the Contents area of the Organizer print dialog are equivalent to the Setup button in an SDL suite tool print dialog. The Save button is used to save print dialog settings in print selection files, for later use in the print dialog.

All dialog areas and buttons will be described in this chapter.

Contents Area in the Organizer Dialog

The Contents area is only available in the Organizer Print dialog. In the area, it is possible to control what information to print, through a number of toggle buttons and Setup buttons. Each of the toggles identify a group of documents that may be printed:

  • Table of contents
  • Organizer view
  • Link Manager view
  • OM diagram
  • HMSC diagram
  • SC diagram
  • SDL interaction
  • SDL flowchart
  • SDL overview
  • MSC diagram
  • Text document
  • Coverage diagram
  • Cross reference diagram
  • Type diagram

Note:

It is not possible to include TTCN documents in a global printout from the Organizer. See "The Print TTCN Dialog in the Organizer" for information on how to print TTCN documents from the Organizer.

Some toggle buttons may be turned on by default. This is determined by which document types that are present in the default scope of print.

Table of Contents

This option determines whether a table of contents should be generated or not. The table of contents consists of a textual list with information about what source diagrams and generated diagrams that are included in the printout, with references to physical page numbers. There is also a possibility to only include Organizer chapters in the table of contents, i.e. all other printed entities are suppressed in the table of contents.

The table of contents is either printed on the first pages that constitute the resulting printout, or after an initial text document acting as a title page.

Organizer View

This option determines whether a printout of the Organizer main window should be included or not in the generated output. Only the visible parts (i.e. expanded nodes) are included.

The resulting printout will match the Organizer's View Options, i.e. file names, directories, etc. will be shown if they are in the Organizer Main window.

Link Manager View

This option determines whether a printout of the Link Manager Window should be included or not in the generated output. Only the visible parts (i.e. expanded nodes) are included.

OM/HMSC/SC/MSC/Text Diagram,
SDL Interaction,
SDL Flowchart,
SDL Overview

These options determines whether the documents and diagrams that are visible in the Organizer should be included or not in the printout. The SDL Interaction diagrams are: system, system type, block, block type, substructure, package diagrams. The SDL Flow diagrams are: process, process type, service, service type, procedure, operator, macro diagrams.

Note:

Endpoint markers will not be included in printed diagrams.

Coverage Diagram

This option determines whether Transition Coverage and Symbol Coverage trees should be included or not in the generated output.

Cross Ref Diagram

This option determines whether Definitions and Uses should be included or not in the generated output.

The resulting output will show the graphical appearance as when displayed in the Index Viewer, with the exception that only SDL entities defined or used in SDL diagrams printed together with the index will be visible in the index.

Type Diagram

This option determines whether an SDL-92 Type list and SDL Type Inheritance and Redefinition list should be included in the generated output or not.

The resulting output will show the SDL-92 type lists for the SDL system currently in view in the Organizer. The lists will be produced by using the options defined in the List Options, Tree Options and Symbol Options of the Type Viewer.

Setup Buttons in the Contents Area

Furthermore, each group of documents that may be printed is supplied with setup buttons. When you click a setup button, a Print Setup dialog will be issued, see "Print Setup Dialogs" . In the dialog, it is possible to set additional options that affect the printout of the current group of documents.

Document Area

The Document area contains a number of settings that make it possible to specify the size of the paper to use, the print range and additional information to be printed on each individual page.

The Document options are:

  • Paper format
  • Margins
  • Header file
  • Footer file
  • Page markers
  • First page no
  • Print from/to
  • Black & white
  • Print collapsed texts
  • Print chapter pages
  • Forward references
  • Backward references

Note:

When using a printing format other than One Postscript File or MSWPrint the only enabled options in the Document area are Black & white (not for Frame or Interleaf printing) and Print collapsed texts. For these formats the paper layout is determined by the special Print preferences starting with Frame*PaperFormat. However when using Word format the margins and layout are determined by the defaults given by the created Word document.

Paper format

The Paper format option menu specifies what paper format the print function will use. The paper formats are:

  • A4, the European standard size (210 * 297 mm)
  • A3, the European standard double size (297 * 420 mm)
  • US Letter, the American standard (8.5" * 11")
  • US Legal (8.5" * 14")
  • User Defined, which makes it possible to customize a size with the Margins button. The size may also have been set in the Preferences Manager.

Margins

The Margins button provides access to the Paper Format Setup dialog where the print margins may be specified.

Figure 78 : The Paper Format Setup dialog

The print margins govern how much space is reserved around the area used when printing. Values are expressed in millimeters.

  • There are four slide bars for the adjustment of the margins:
    • Upper margin
    • Lower margin
    • Left margin
    • Right margin
      Margins are calculated with respect to the closest border and remain unaffected when rescaling, changing the paper size or the orientation of the printout.
  • The dialog also contains two slide bars used for controlling what paper format to use when the Paper format option User Defined is set:
    • User paper width
    • User paper height
  • The OK button applies the values as currently defined and closes the dialog.
  • The Cancel button closes the dialog without changing any values.

Header file

Footer file

This feature controls whether or not a header/footer should be printed on each page. The page header/footer is defined in a text file of its own, which you need to supply. For information about the contents and syntax of this file, see "Footer and Header Files" .

  • The header/footer file options are turned on/off with toggle buttons.
  • When you click the folder button, a Select File dialog will be issued. In this dialog you may select the header/footer file.
  • It is also possible to type the name and directory of the file directly into the text field.

Note:

Header or footer files are only supported in PostScript Output (not EPS) or MSWPrint Output (Windows only).

Page markers

An SDL/OM page or an MSC diagram may require multiple physical pages when printed. If you want to print an SDL/MSC/OM document and the document is physically spread over more than one physical page, the Page markers toggle button facilitates the reassembling of the paper sheets into the original page.

  • If the toggle button is on, adjacent page markers will be inserted on the edge of each physical page. An adjacent page marker looks like a small arrowhead which refers to the adjacent page. If there are lines crossing a physical page border, line identifiers (like X1, X2... or Y1, Y2...) will be attached to the line, making it easy to find the continuation of the line on the other page.

Figure 79 : The page numbering

Physical page numbering follows a "first right, then down" fashion.

Note:

The physical page breaks are indicated with dashed lines in the diagram editors. A page number is inserted at the lower right corner of each page in the editor.
Page markers and all other options where page numbers are used are only supported in PostScript Output (not EPS) or MSWPrint Output (Windows only).
It is possible to print an individual page number on each printed page. This is done by using a header file. Read more about header files in "Footer and Header Files" .

First page no

When you order multiple print jobs, you may want to restart the page numbering on each printout with a number different from 1, which is the default value.

If you want to change the number of the first page, you should type the number in the First page no: field.

Print from/to

It is possible to exclude a number of pages form a printout. To specify the print range, you type the page numbers in the Print from and Print to fields. Make sure that the toggle button is on, your settings will have no effect otherwise.

When the toggle button is off, all physical pages that constitute the printout will be generated.

Note:

The print range must be in accordance with the page numbering; i.e. the offset specified in the First page no should be added.
The physical page breaks are indicated with dashed lines in the diagram editors. These page breaks are valid only if the printing scale is not changed.

Black & white

If this option is selected, all symbols and lines will be printed with a black border on a white background. If this option is not selected, symbols and lines will be printed with the color they have on screen. As default, this option is off.

For FrameMaker or Interleaf printing this option is always on and disabled as the printing will always be in black and white.

Print collapsed texts

Text symbols, comment symbols and text extension symbols can be collapsed. When they are collapsed, it is not possible to see the complete text these symbols contain in the diagram. Instead, it is possible to print the complete text as a separate text page after the diagram. This option decides if such a text page should be printed or not. As default, this option is on.

Print chapter pages

(Organizer only.) Decides if text connected to chapter symbols in the Organizer should be printed or not. As default, this option is on.

Forward references

(Organizer only.) Decides if forward paper page references should be printed or not. Paper page references makes the printout easier to read. You can get paper page references for the following relations:

  • SDL reference symbol -> SDL diagram
  • (H)MSC reference symbol -> (H)MSC diagram
  • SDL join/out-connector -> SDL label/in-connector
  • SDL procedure call -> SDL procedure diagram
  • SDL nextstate symbol -> SDL state symbol

Note:

The three last relations will only be printed if there exists an index/cross reference file in the Organizer view with up-to-date information about the SDL system. You can get an index for a correct SDL system by pressing the Generate Index Organizer quick button before bringing up the print dialog

As default, forward paper page references are printed.

There is a preference, Print*MaxPageReferences, that decides the maximum number of page references in one place. The default value is 20. A value of 0 is the same as "no limit".

Backward references

Similar to forward references, but produces paper page references that allows the reader of the printout to follow the flow backwards instead.

Destination Area

The Destination area contains print options that affect the output format and the destination of the resulting output. It is for example possible to send a printout to a printer or to look at the results in a pre-viewer.

The options are:

  • Format
  • To file / Map file
  • Execute

Format

This feature controls what output format will be generated when printing. You select the output format in an option menu. The output formats supported are:

  • One PostScript File
    This option produces one self contained PostScript document.
  • One EPS File1
    If only one page is to be printed, this option is valid and will result in an EPS File containing one physical page. If the Print setup caused more than one physical page to be printed, only the first page will be printed. The layout of the page for EPS printing is determined by the preferences in Frame*PaperFormat.
  • One EPS File Per Page
    This format implies that the output will be in the form of multiple EPS files, placed in a specified directory. Along with the EPS files, a map file containing the translation scheme is produced. See "To file / Map file" .
  • One FrameMaker MIF File2
    This format signifies the generation of one FrameMaker MIF file. The file will contain a number of contiguous, cropped anchored frames. The layout of the page for MIF printing is determined by the preferences in Frame*PaperFormat.
  • One FrameMaker MIF File Per Page
    This option produces one FrameMaker MIF file per page. A map file is also produced, showing the translation table. See "To file / Map file" , below.
  • Import into FrameMaker (UNIX only)
    If an instance of FrameMaker is found up and running, this option generates a FrameMaker MIF temporary file that will be imported into an anchored frame, placed below the current insertion point in the active FrameMaker document. If no instance of FrameMaker is found, then an attempt is made to start one with the command maker and create a new FrameMaker document, showing the contents of the file.

Note:

To have this print option function properly, the SDL suite and FrameMaker must run on the same computer.
Temporary files are stored on the directory designated by the environment variable TMPDIR. You have to set up the variable as a complete path specification such as setenv TMPDIR /tmp
To specify TMPDIR such as setenv TMPDIR . is not sufficient.

See also "Importing into FrameMaker (UNIX only)" for how this option functions when multiple instances of FrameMaker are running on your computer.
  • One Interleaf IAF File3
    This format produces one Interleaf ASCII Format file. The layout of the page for IAF printing is determined by the preferences in Frame*PaperFormat.
  • One Interleaf IAF File Per Page
    This option produces one Interleaf ASCII Format file per page. A map file is also produced, showing the translation table. See "To file / Map file" .
  • MSW Print
    (Windows only)
    The Print function uses the printer that has been set up with the Microsoft Windows Print Manager. If a printer that does not support PostScript is used, this option makes sure the printer driver available in Microsoft Windows is used.
  • One Word DOC File
    (Windows only)
    This option produces one Word Document format file for use with Microsoft Word 97 or Word 2000. The layout of the page for Word printing is determined by the margins and paper format as defined when a new document in Word is created.
  • Word Files (DOC + EMF)
    (Windows only)
    This option produces one Word Document format file that is a hub for a set of Enhanced Metafiles. When you select this option you also have to specify the main Word Document file in the To file text field. The produced Enhanced Metafiles are auto-named and placed in the same directory as the main Word Document file.
  • Web Files (HTML+PNG)
    This option produces HTML (text) and PNG (picture) files that can be viewed in a web browser. The PNG file format is similar to the GIF file format and is supported by Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0 or later. When you select this option, you also have to specify the main HTML file in the To file text field. All other produced files are auto-named and placed in the same directory as the main HTML file.

To file / Map file

If this radio button is turned on, the output will be a file. The name of this radio button depends on the format specified in the Format option menu. If the format selected will generate one output file - i.e. the format name ends with Per Page - the name will be Map file. Otherwise it will be To file.

A map file contains a translation scheme of all files generated (containing information about SDL diagram / page and the corresponding printout file). The naming algorithm of the generated files will ensure a fixed mapping between a diagram and the generated files between two subsequent Print jobs. However, if the input to the Print function is changed (its size!), this is not necessarily true.

See "Map File" if you want detailed information on the syntax of a map file.

  • When you click the folder button, a Select File dialog will be issued. In this dialog you may select the name of the file and where it is to be saved.
  • It is also possible to type the name of the file directly into the text field. The directory where the file will be saved is the most currently selected.

Execute

If this radio button is on, the output file will be used as input to an OS command. An example of this is to load a printer with a PostScript file. It may also be used to send the resulting PostScript code to a PostScript previewer. For instance, if type a previewer command in the field - ghostview for example - you may preview the PostScript file.

The command lpr (or any other related) will send the printout to a printer.

The default command is specified in the Preference Manager. In the Windows version, the command lpr is available, which functions much like the corresponding UNIX print spool command.

Setup

When you click the Setup button (only available in an SDL suite tool Print dialog), a Print Setup dialog will be issued. In the dialog, it is possible to set additional options. The additional options differ between the the SDL suite tools. See "Print Setup Dialogs" for more information.

1

EPS stands for Encapsulated PostScript

2

MIF stands for Maker Interchange Format.

3

IAF stands for Interleaf ASCII Format.


The Print TTCN Dialog in the Organizer

To print one or more TTCN documents from the Organizer, you select one of the TTCN document in the Organizer and then you select Print from the Organizer File menu. This will issue the Organizer Print TTCN dialog.

When you print a TTCN document, the main difference between printing from the Organizer and printing from the TTCN suite is:

  • If you have more than one TTCN document included in the Organizer, you may select which of the documents to print. In the TTCN suite, it is only possible to print a document that is displayed in the active Browser.

See also "The Print Dialogs in the TTCN Suite" .

The Organizer Print TTCN dialog contains options for the print range and first page number and whether the document is to be printed to a file or a printer. More options are available in the Print TTCN Setup dialog.

Figure 80 The Organizer Print TTCN dialog

First page number

The number that you type in this field, will be the page number inserted on the first page.

Print from/to

It is possible to exclude a number of pages form a printout. To specify the print range, you type the page numbers in the Print from and Print to fields. Make sure that the toggle button is on, your settings will have no effect otherwise.

When the toggle button is off, all physical pages that constitute the printout will be generated.

Destination Area

The options in the Destination area affects the destination of the printout.

To file

If this radio button is on, the printout will be a PostScript file. You also have to specify the name of the file and where it is to be saved.

  • When you click the folder button, a Select File dialog will be issued. In this dialog you may select the name of the file and where it is to be saved.
  • It is also possible to type the name of the file directly into the text field. The directory where the file will be saved is the most currently selected.

Execute

If this radio button is on, the output file will be used as input to an OS command. An example of this is to load a printer with a PostScript file. It may also be to send the resulting PostScript code to a PostScript previewer. For instance, if type a previewer command in the field - ghostview for example - you may preview the PostScript file.

The command lpr (or any other related) will send the printout to a printer.

Setup

When you click the Setup button, a Print Setup dialog will be issued. In the dialog, it is possible to set additional options, such as which of the existing TTCN documents to print. See "Print Setup Dialogs" for more information.


The Print Dialogs in the TTCN Suite

To print from the TTCN suite:
  • Select Print from the File menu. (On UNIX, this menu choice is included in the Browser.)
    • In Windows, if the test suite overview has not been generated previously, you will have to confirm the generation before the test suite can be printed.
      In the Print dialog that will be opened, you may specify the page range and if the file is to be printed to a file or a printer. The output will be in TTCN-GR format - the graphical format of TTCN - according to ISO/IEC 9646-3, and it will include document indices and automatic page numbers.

When you print a TTCN document, the main difference between printing from the Organizer and printing from the TTCN suite is:

  • If you have more than one TTCN document included in the Organizer, you may select which of the documents to print. In the TTCN suite, it is only possible to print a document that is currently displayed in the active Browser.

See also "The Print TTCN Dialog in the Organizer" .

Printing in the TTCN Suite in Windows

In Windows, the print dialogs are Windows standard. Besides the actual Print dialog there are also Print Setup and Print Preview dialogs.

To open a Print Setup dialog:

  • Select Print Setup from the File menu.
    In the dialog, it is possible to specify what printer, paper size and paper orientation to use.

To open a print preview dialog:

  • Select Print Preview from the File menu.
    In the dialog, the TTCN document is displayed as it will be printed and it is possible to zoom and browse the document.

Printing in the TTCN Suite on UNIX

On UNIX, you can select which Browser parts and items, for example a single table or sets of tables, to include in the printout. The selections may be arbitrary - they will be printed as a coherent document anyway. It is also possible to change the page numbering of the printout.

The settings in the print dialog will be described below:

Figure 81 : The TTCN suite Print dialog on UNIX

  • Log device
    Controls the log device for the print function. The default value is Screen, but the log can be directed to a named file (File) or turned off altogether (None).
    For more information, see "The TTCN Suite Logs" .
  • Output device
    If you specify the output device to be a printer, you also have to fill in a print command. If you want to print to a file, you will have to specify the destination. See also "Printing PostScript Files" .
  • Burst page off
    If this option is set, the burst page will not be printed. The burst page is a generated, unnumbered cover page for the TTCN document, containing the print date and time.
  • Double sided
    If this option is set, the TTCN document will be printed in a page format suitable for a double-sided copying, otherwise it will be printed in a single-sided format. The appearance of both formats is controlled by resources and can therefore be changed (see the file <Itex.sample> in the TTCN suite directory).
  • First page number
    You may change the page number of the first page. However, to ensure consistency between the page numbering of the printed TTCN document and the page numbers that appear in the TTCN document overview, make sure that:
    • The Overview Part is generated before you print.
    • The same first page number is used both in the document overview and the printout.
  • Printing page ranges
    • All causes all pages of the document to be printed.
    • Start page and End page restricts the printout.

Example 13

If a TTCN document contains ten pages numbered 1 to 10, then Start page = 3 and End page = 3 will cause only page 3 to be printed.

Printing PostScript Files

The editable field of the Print dialog not only allows to change the name of the printer or to apply flags to the print command. It is also possible to insert the name of a filter for the produced PostScript code. In the public domain there exist a package of programs called pstools that make various magic operations with a PostScript file. The following example will print four TTCN suite pages on each A4 page (the syntax of pstops is somewhat hard to read though):

Example 14

pstops `4:0@0.5(0.8cm,14cm)+1@0.5(10.5cm,14cm)\
+2@0.5(0.8cm,0cm)+3@0.5(10.5cm,0cm)' | lpr

Other filters are able to print double sided intended to bind into a book, print odd pages first etc.

By using a PostScript viewer as Ghostview instead of the normal print command, the printout of the TTCN document can be viewed on screen rather than being printed:

Example 15

ghostview -

The text in this field is controlled by the resource Itex.print.commandPrefix. This is by default lpr -P or lp -s depending on platform but can be altered (note that the content of the environment variable PRINTER/LPDEST is concatenated to this string). See 30 Customizing the TTCN Suite (on UNIX) which contains a description on how to modify resources in the TTCN suite.


Print Setup Dialogs

A Print Setup dialog will be issued when you click the Setup button in an SDL suite tool Print dialog, or when you click any of the setup buttons in the Contents area of the Organizer Print dialog. When you click the Setup button in the Organizer Print TTCN dialog, the Print TTCN Setup dialog will be issued. The settings in a setup dialog will affect the current group of documents.

The setup dialogs look somewhat different depending on the tool they are invoked from. There are four types of print setup dialogs:

  • Print Setup dialog for Table of contents in the Organizer, see Figure 82.
  • Print Setup dialog in the SDL, OM, SC and HMSC Editors and, when applicable, in the Organizer, see Figure 83.
  • Print Setup dialog in the MSC Editor, see Figure 84.
  • Print Setup dialog in tools not mentioned above and, when applicable, in the Organizer, see Figure 85.
  • Print TTCN Setup dialog in the Organizer, see Figure 86.

Figure 82 : The Table of contents Print Setup dialog

Figure 83 : The Organizer Print Setup dialog

The Print Setup dialog looks the same in the Organizer and the SDL, OM, SC and HMSC Editors.

Figure 84 : The MSC Editor Print Setup dialog

Figure 85 : A viewer Print Setup dialog

The Print Setup dialog looks the same in the Link Manager, Type Viewer, the Index Viewer, the Coverage Viewer and the Text Editor.

Figure 86 The Organizer Print TTCN Setup dialog

The setup dialogs contain the following:

  • All dialogs contain the Scale area, the Orientation option menu, and the OK, Cancel and Help buttons.
  • When applicable, the SDL, HMSC, OM and SC Editor and the Organizer Print Setup dialogs, as well as the Organizer Print TTCN Setup dialog, also contain the Print / Do not print lists.
    The lists are only included in the Print Setup dialog of an editor if the diagram that is to be printed consists of more than one page.
    In the Organizer, the Print Setup dialog will not contain the lists if you clicked the Link Manager View setup button.
  • The Print only selected symbols toggle button is included in the SDL, HMSC, OM and SC Editor Print Setup dialogs.
  • The MSC Print Setup dialog contains the Include Instance Ruler toggle button. This button is also included when MSC setup is invoked from the Organizer Print dialog.
  • The Organizer View Print Setup dialog contains the Paper page references toggle button.
  • The Table of contents Print Setup dialog contains the toggle buttons After initial text document and Only chapters in TOC.
  • The Print TTCN Setup dialog contains the toggle buttons Document burst page, Part burst page and Double sided.

All areas and options mentioned will be explained below.

Print / Do not print

  • The Print list shows the documents/pages that will be printed.
    If the Print Setup dialog is invoked from the Organizer, the list contains the documents included in the Organizer scope of print. When the dialog is invoked from the SDL, OM, SC or HMSC Editor, the list contains the current page.
    In the Print TTCN Setup dialog, this list shows the TTCN document that was selected in the Organizer (or all TTCN documents within a TTCN Module). Any other TTCN documents are listed in the Do Not Print list.
  • The Do not print list shows the documents/pages that will not be printed.
    When invoked from the SDL, OM, SC or HMSC Editor, the list contains the pages that are included in a diagram, except the current page.

To specify what is to be printed and not:

  1. Select one or several items in one of the lists, if you want to move them to the other. Multiple selection is possible.
  2. Use the arrow buttons to move selected items from one list to the other.

Note:

On UNIX, you may transfer all diagrams/pages between the two lists by pressing <Shift> while clicking an arrow button.

Scale

It is possible to set the scale in almost all Print Setup dialogs. You can select Percent, Scale to fit page or Scale to fit width.

Note:

It is not possible to set the scale in the Text Editor Print Setup dialog or in the Organizer Print TTCN Setup dialog.

Percent

With the Percent radio button on, the printout of the current document category will be scaled according to the value defined in the Percent text field. The default value is 100% but you may of course change this.

Scale to fit page

With the Scale to fit page radio button on, the printout will be rescaled - if needed - to fit the physical paper size.

Scale to fit width

With the Scale to fit width button on, the documents will be rescaled in order to fit the physical paper width. The result becomes a column of pages constituting each document.

Orientation

In the Orientation options menu you may choose between the following orientations of the printout:

  • Portrait
  • Landscape

By changing the options, you can rotate the printout in order to optimize paper use.

Note:

The Orientation option is only enabled for the output formats One PostScript File or MSWPrint. Other formats use the portrait orientation but the layout can be adjusted by the preferences Print*Frame*XXX.

Additional Options

Below the Orientation option, there are a number of additional options, depending on which Print Setup dialog you have opened.

Print only selected symbols

If this toggle button is on, only objects that are selected in a window will be printed. This option is not available when you print from the Organizer. In an SDL suite tool, it is disabled if no object is selected or if more than one window contain a selection.

Include Instance Ruler

This toggle button is only available in the MSC Print Setup dialog. It specifies whether an instance ruler (see "Instance Ruler" ) should appear on each printed page or not. The instance ruler is, when printed, given an appearance similar to the one shown in the MSC Editor window.

Paper page references

This toggle button is only available in the Organizer View Print Setup dialog. It specifies whether paper page references to all printed diagrams and documents should be included in the Organizer view listing.

After initial text document

This toggle button is only available in the table of contents Print Setup dialog. It specifies whether the table of contents should be printed after a plain text document placed first among the diagrams and documents that are to be printed. The initial text document then acts as a title page before the table of contents.

Only chapters in TOC

This toggle button is only available in the table of contents Print Setup dialog. It specifies whether only the chapters in the Organizer view should be included in the table of contents, or if all diagrams and documents also should be included.

Document burst page

This toggle button is only available in the Organizer Print TTCN Setup dialog. If the toggle is on, a document burst page will be printed. The burst page is an unnumbered cover page for the TTCN document, where the name of the test suite and the print date are printed.

Part burst page

This toggle button is only available in the Organizer Print TTCN Setup dialog. If the toggle is on, part burst pages will be printed. The part burst pages are unnumbered cover pages, that separate the different parts of a TTCN document. The name of the part, the test suite and the print date, are printed on each part burst page.

Double sided

This toggle button is only available in the Organizer Print TTCN Setup dialog. If the toggle is on, the TTCN document will be printed with a page format suitable for a double-sided copying. The appearance is controlled by resources and can therefore be changed (see the file Itex.sample in the TTCN suite directory of the Telelogic Tau installation).


Footer and Header Files

You may specify if a header and/or footer is to be inserted on each printed page. The first thing you have to do is to define the header and footer in separate text files. The format is ASCII based and line oriented. A number of variables are available, providing additional information of the kind of diagram printed.

Text is written on a white background, which becomes visible if the text appears on top of any graphical object.

Printing Order

The priority order for writing headers and footers is as the inverse order in which the items appear in the file. That is any text, variable or graphical symbol, overwrites an already written item. (The last row in the file has the highest priority).

Syntax

The syntax used in the header and footer files is given below in a BNF notation:

File ::= ( <LINE> | <EXTENSION-LINES> | <EPSF> ) *
<LINE> ::= <X> <Y> ( <TEXT> | <VARIABLE> ) + \n
<X> ::= integer, x - position in millimeter
<Y> ::= integer, y - position in millimeter
<TEXT> ::= any ASCII text - no newlines allowed
<VARIABLE> ::= any variable as described in "Variables" ,
<EXTENSION-LINES> ::= any of the extensions as defined in "Extensions" .
<EPSF> ::= EPSF <X> <Y> <FILE>
<FILE> ::= user provided filename containing EPS code

Note:

The positions are relative the upper left corner of the physical paper in the header and the lower left corner in the footer.

Variables

The following variables are supported in header and footer files:

Variable
Explanation

 <date>
As set by the Print preference date.

 <diagramname>
The name of the diagram. Ignored if the printed diagram was not one of:
  • SDL diagram
  • SDL Overview diagram
  • MSC.
 <diagramtype>
The type of the diagram. Ignored if the printed diagram was not one of:
  • SDL diagram
  • SDL Overview diagram
  • MSC.
 <pagename>
The logical name of current page. Ignored if the printed diagram was not one of:
  • SDL diagram
  • SDL Overview diagram.
 <file>
The current file being printed. Ignored if no corresponding file exists. It could be a New (unsaved) file being printed or it could be a Type View which has no corresponding file.

 <page>
The current page number.

 <directory>
The directory where the current file is located. Ignored if no corresponding file exists. It could be a New (unsaved) file being printed or it could be a Type View which has no corresponding file.

 <chaptername>
The current chapter name, defined by a chapter symbol in the Organizer View.

 <chapternumber>
The current chapter number, defined by a chapter symbol in the Organizer View.

 <totalpages>
The total number of printed pages, excluding the title page and the table of contents.

Obsolete Variables

(i.e. variables used in SDT 2.3)

Variable
Explanation

 <area>
Prints Work Area or Original Area in plain text depending on if the diagram was found in the source directory or not.
The variable is available for backwards compatibility only.

Example 16

For example, you may have a process called Myproc that you are going to print out. First you write a footer file with the following contents:

10 20 Telelogic AB
10 15 <date>
150 15 <diagramtype> <diagramname> <pagename>
180 20 Page <page>

If the date is March 1, 1999, the 15th printed page would look something like this:

Figure 87 : The resulting footer

Extensions

Below are listed the extensions that enhance the appearance of the header and footer.

Frames

The keyword FRAME makes a frame appear at any position on the paper. The function is intended for framing the header and/or footer.

Format

The exact format is:

FRAME x1 y1 x2 y2 [type]

where the start and stop positions are given in millimeters. The optional type argument may be either 3D or plain (default).

Figure 88 : 3D frame and plain frame

Separators

A separator is a horizontal line which is intended to separate the header and/or footer from the data area of a printed page.

Format

The SEPARATOR statement has the general format:

SEPARATOR x1 y1 length [type]

where the start position and length of the separator are given in millimeters. The optional type argument may be either:

  • Filled
  • Double
  • Single (default)

Figure 89 : Filled, double and single separators

Boxes

Use the BOX keyword to make a filled rectangle appear anywhere on the paper. It can be used for highlighting sections of the header and/or footer.

Format

The format is:

BOX x1 y1 x2 y2 [grayscale]

where the start and stop positions are given in millimeters. The optional grayscale argument is a number in the range 0 to 100 (default is 50).

Figure 90 : Boxes

Grayscale=0 = white, grayscale=50 = medium gray and grayscale=100 = black.

Defining Multiple Footers and Headers

It is possible to have a separate footer or header for the first printed page. There are three keywords that can be typed on a separate line in a footer or header definition file to achieve this:

  • IFFIRST

Definitions after this keyword will only be used for the first printed page.

  • IFNOTFIRST

Definitions after this keyword will be used for all pages after the first page, but not for the first page.

  • ENDIF

Definitions after this keyword will be used for all pages.


Map File

When multiple output files are generated for one input diagram, a map file is also generated. It shows the translation table between input diagrams and resulting files. The name of this file should be specified in the Map file field.

Syntax

The map file is an ASCII text file containing lines of the format:

<filename> "[<diagram type>]" "[<diagram name>]" "[<page name>]"

where <filename> is an absolute path to a generated file. The file name is composed of:

  • the first four letters of the diagram name (fewer if the diagram name is shorter than four letters)
  • the first two letters of the page name
  • an extension.

If this naming scheme generates two files with the same name, a number (1-99) is added to the second file name, preceding the extension.

Example 17 : Contents of a UNIX Map File

...
/usr/ope/doc/ContDe.eps "Block" "Controller" "Declarations"
...
/usr/ope/doc/ContDe1.eps "Block" "Container" "Declarations"
...

Example 18 : Contents of a Windows Map File

...
C:\tau\doc\ContDe.EPS "Block" "Controller" "Declarations"
...
C:\tau\doc\ContDe1.EPS "Block" "Container" "Declarations"
...

Should either of the descriptive <diagram type>, <diagram name> or <page name> fields be inapplicable to an item, the corresponding field in the map file will be empty (i.e. "").


More Information on Output Formats

PostScript Output

PostScript output may be generated as one standard PostScript file or one or more Encapsulated PostScript (EPS) files. When multiple EPS files are generated, a translation table will also be produced in a Map File, linking the name of a generated file to the contents.

Standard PostScript

A normal print operation generate one PostScript document. All data is represented uniformly, using the same paper format, header, footer etc. Only the scale and orientation might vary between pages.

Encapsulated PostScript (EPS)

The EPS output makes use of the scale and orientation settings for each document category. Since EPS files are not clipped, the internal scale has little importance when the file is imported into an external documentation or desktop publishing system.

Header, footer and adjacent page markers are not included in the output. Paper layout are determined from the Print preferences Frame*PaperFormat.

Scaling in EPS Files

The scaling options are handled as follows:

  • Scale to fit page
    Each logical page is output as one EPS file with an internal scale adjusted to fit the entire logical page into the bounding box given by the current paper format and margins. When the EPS files are scaled into external documentation software, this will correspond to the "Fit Into Page" option for PostScript files.
  • Percent
    As Scale to fit page, but with a user defined internal scale.
  • Scale to fit width
    As Scale to fit page, but with the internal scale adjusted to fit the width of the logical page into the space given by the paper width and the left and right margins.

Handling of Expanded Text in PostScript

Expanded texts are the text contained in such symbols that are minimized1 in a graphical page, see "Text / Additional Heading / Package Reference Symbols" .

Standard PostScript

Expanded text is output as plain text using the font specified by the SDT*PrintFontFamily and SDT*PrintTextHeight preferences.

Encapsulated PostScript

Expanded text in EPS output is stored on separate files. One text file is generated for each logical page containing expanded text, regardless of the number of expanded texts in that logical page.

  • When generating multiple EPS files, the text file for a logical page called <x>.eps will be <x>.exp.
  • When printing to one EPS file, the text file for <x> will be <x>.exp.

PostScript Standard Conformance

The generated PostScript code conforms to either of these standards:

  • PostScript Language Document Structuring Conventions - Version 3.0
  • Encapsulated PostScript File Format - Version 3.0.

FrameMaker Output

FrameMaker output may be generated either as:

  • One MIF2 file containing cropped anchored frames
  • One or more MIF files containing one logical page each
    The generated pages are the same in both cases. A translation table is also generated in the latter case.
  • One temporary MIF file that can be imported directly into FrameMaker. See "Importing into FrameMaker (UNIX only)" .

Depending on the scale setting (see "Scaling in EPS Files" ), each logical page will be represented as one or more cropped anchored frames in the output.

Header, footer and adjacent page markers are not included in the output. Paper layout are determined from the Print preferences Frame*PaperFormat.

Handling of Expanded Text in MIF

Expanded text (see "Handling of Expanded Text in PostScript" for an explanation) is inserted as plain text after the anchored frames generated for the corresponding logical page. In order to preserve the appearance of the users original text, hard returns are inserted where new lines are found.

MIF Conformance

The generated MIF files conform to FrameMaker Interchange Format version 4.00, which can be read into FrameMaker version 4.x, 5.x and 6.x without problems.

Importing into FrameMaker (UNIX only)

The X Window root window has an atom (property) that governs how FrameMaker communicates with Telelogic Tau. The name is arbitrary, but must defined both in Telelogic Tau and FrameMaker. In the example below, the name _Frame_Tau_Import will be used.

To have Telelogic Tau and FrameMaker behave in accordance, you should specify what resource to be used by Telelogic Tau when starting FrameMaker. The resource values should be entered in the SDT resource file (in which case all users are affected) or in a suitable user X resource file. The resource is called sdtfmimp*rpcProp.

Example 19 : X Resource file sample

...
sdtfmimp*rpcProp: _Frame_Tau_Import
...

There are multiple ways to set up FrameMaker. The resource Maker.rpcProp may be used for this.

Interleaf Output

Interleaf output may be produced as:

  • one IAF3 file containing anchored frames, or
  • one or more IAF files containing one logical page each.

The generated pages are the same in both cases. A translation table is also generated in the latter case.

Depending on the scale setting (see "Scaling in EPS Files" ), each logical page will be represented as one or more anchored frames in the output.

Header, footer and adjacent page markers are not included in the output. Paper layout are determined from the Print preferences Frame*PaperFormat.

Handling of Expanded Text in IAF

Expanded text (see "Handling of Expanded Text in PostScript" ) is inserted as plain text after the frames generated for the corresponding logical page. In order to preserve the appearance of the users original text, hard returns are inserted where new lines are found.

IAF Conformance

The generated IAF files conform to Interleaf ASCII Format version 8.0 (used in Interleaf 5).

MSWPrint Output (Windows only)

The MSWPrint output can be used on Windows to print on any Windows printer, thus this is suitable if the printer does not support Postscript. As the complete print output using this option will be divided into several print jobs the printing should be done only on one side of the paper, otherwise the page numbering will not be as expected.

Handling of Expanded Text in MSWPrint

Expanded text (see "Handling of Expanded Text in PostScript" ) is handled the same as for standard PostScript.

Microsoft Word Output (Windows only)

Word output can be used to print as a Microsoft Word document. A complete Word document is created and the generated pages are created as enhanced metafiles.

Header, footer and adjacent page markers are not included in the output. Paper layout are determined from the defaults when creating a new Word document.

Handling of Expanded Text in Word output

Expanded text (see "Handling of Expanded Text in PostScript" ) is inserted as plain text after the frames generated for the corresponding logical page. In order to preserve the appearance of the user's original text, hard returns are inserted where new lines are found.

1

Meaning resized to a minimal size.

2

MIF stands for Maker Interchange Format.

3

IAF stands for Interleaf ASCII Format.


Adding Printer Fonts (UNIX only)

By default only three printer fonts are available in printouts: Times, Courier and Helvetica. It is possible to add other printer fonts. The requirement is that there exist AFM (Adobe Font Metrics) files for the desired fonts. An AFM file contains the character metrics necessary for correct layout of text in printouts.

  1. Locate AFM files for the regular, bold, italic and bold italic versions of the font. Many AFM files are available from Adobe Systems Inc. through on-line services (e.g. via ftp from ftp.adobe.com).
  2. Store the files in the directory $telelogic/fontinfo.
  3. Name the files according to the scheme in the table below. Note that you have to specify <basename> by using lower case characters (e.g. palatino-I.afm). Otherwise, you are free to choose any <basename> that does not conflict with other fonts or font files.

File contents
File name
regular font

 <basename>.afm
bold font

 <basename>-B.afm
italic font

 <basename>-I.afm
bold italic font

 <basename>-BI.afm

  4. You may then choose the font as <basename> in the Preference Manager (case is not important in this context):

Figure 91 : Specifying print font as Other.

Palatino is selected in the current example.

The generated files will use the true name of the font, extracted from the FontName and FamilyName attributes in the AFM files.


Advanced Print Facilities

This section is divided into three parts.

  • The first part lists all advanced print facilities.
    See "List of Advanced Print Facilities" .
  • The second part describes how to use the advanced print facilities to produce a nice printout, starting with an SDL system that is not already prepared for printing with advanced print facilities.
    See "Introducing Advanced Print Facilities" .
  • The third part is about using the advanced print facilities when an SDL system is prepared for printing with advanced print facilities. See "Using Advanced Print Facilities" .

List of Advanced Print Facilities

The following print facilities will be described in this section:

  • Headers
  • Chapters
  • Title Page
  • State Matrices
  • Index
  • Fonts
  • Text Indentation

Headers

You can create a textual header definition file that defines the appearance of a header that is found at the top of each printed page. All the possibilities for creating a header is described in "Footer and Header Files" , here you will only find the most important ones.

Figure 92 : A header example

Creating a Header Definition File

The Organizer preference ShowHeader defines if the header symbol should be visible as default in the Organizer view. If the header symbol is not visible, you can make the symbol visible by selecting Header File in the View > View Options dialog.

Figure 93 : The header symbol in the Organizer view

You can double-click on the header symbol to open a Text Editor to be able to define the header and create a header definition file. When you have defined the header (read more about some of the possibilities for that below), save the file and you are done with this step.

Defining Text in Headers

In the header definition file, insert a line like this:

60 20 This printout was produced by X

This means that 60 millimeters from the left border and 20 millimeters from the top border, the text "This printout was produced by X" will be placed.

Using Header Variables

In a header definition file, insert a line like this:

100 10 <page>(<totalpages>)

This means that 100 millimeters from the left border and 10 millimeters from the top border, a text such as "3(9)" will be placed, informing the reader of the printout that this is page three of nine.

Using Pictures in Headers

You can introduce pictures in the headers. The pictures must be in Encapsulated PostScript file format (EPSF), and they are referenced from the header definition file. If you have a picture of for instance your company logo in a file /home/lat/logo.eps, then you can get it into your header with the following line:

EPSF 10 35 /home/lat/logo.eps

This line means that the picture defined in the referenced file will be placed 10 millimeters from the left border, and 35 millimeters from the top border.

Separate First-page Header

You can have one header for the first page, and another header for all other pages. To achieve this, you can divide your header definition file in three parts by using three different keywords, or rather keylines:

IFFIRST
(Part 1. Place everything that is unique for the first page header here.)
ENDIF

IFNOTFIRST
(Part 2. Place everything that is unique for the other header here.)
ENDIF

(Part 3. Place everything that is common to both the first page header and the other header here.)

Chapters

You can divide the diagrams and documents in your Organizer view into different chapters by using the chapter symbol. You add a chapter symbol to the Organizer view with Edit > Add New. In the dialog that follows, select one of the Chapter alternatives under the Organizer document type group, and specify the chapter name under New document name. (If you do not want to create a chapter introduction text (see below), make sure that the Show in editor toggle button is off before closing the dialog.)

Figure 94 : Chapters in the Organizer view

Chapters can be auto-numbered and can be moved with the up and down quick buttons. You can select a chapter symbol to restrict the scope for diagrams and documents that are going to be printed.

Creating a Chapter Introduction Text

It is possible to associate a text with a chapter symbol. The text will be printed at the position of the chapter symbol, and the text can be regarded as a chapter introduction text.

To create a chapter introduction text, you should invoke the Text Editor. This can be done in two ways:

  • If you have not closed the Add New dialog, then you can bring up the Text Editor by making sure the Show in editor toggle button is on, before closing the dialog.
  • If you have closed the Add New dialog, then you can double-click on the chapter symbol. In the dialog that follows, select Edit chapter symbol. In the second dialog that follows, make sure that the Show in editor toggle button is on and close the dialog to bring up the Text Editor.

In the Text Editor, type in the chapter introduction text and save the file.

Starting a New Chapter in the Middle of an SDL Diagram

For a large SDL diagram with many pages, it is convenient to divide the different pages of the diagram into different sub chapters.

To make this possible, you have to make the page symbols visible in the Organizer, if they are not visible already. This is done in the View Options dialog by turning on Page Symbols.

Figure 95 : Chapters between SDL pages

When page symbols are visible, you can move chapter symbols into the correct place within the SDL system by using the up and down quick-buttons. You can also create new chapter symbols directly at the correct place, by selecting the SDL symbol that the chapter symbol should be placed after, before invoking Add New.

Note that MSCs can be placed in the middle of an SDL system or diagram, in the same way as chapters. This is useful if you want to print an MSC close to the corresponding SDL.

Defining the Start Chapter Number

Normally, the start chapter number is 1 (or 1.1 if the first chapter symbol has the type Chapter 1.1.) You can change this number in the View > Chapter Options dialog.

Deciding Maximum Chapter Level in the Table of Contents

As default, all chapters are visible in the table of contents. If you have a lot of chapters, you can limit the number of chapters in the table of contents by using the View > Chapter Options dialog. A maximum chapter level of 2 will only include chapter symbols of type Chapter, Chapter 1 and Chapter 1.1 in the table of contents.

Printing a Table of Contents with Only Chapters

To print a table of contents, you have to turn on the Table of contents toggle button in the Contents section in the Print dialog.

Figure 96 : The Table of Contents entry in the Print dialog

As default, the table of contents includes chapters, diagrams and documents. To restrict the table of contents to just chapters, there are two ways:

  • If you want to do a temporary restriction just for one printout, then there is a toggle for doing so in a sub dialog to the Print dialog: To get to the sub dialog from the Print dialog, press the setup button with a picture close to the Table of contents entry in the Contents section. In the sub dialog, turn on the toggle Only chapters in TOC.

Figure 97 : Part of the Print Setup dialog for Table of contents

  • If you want the restriction to be more permanent, go to the Preference Manager. In that tool, double-click on the Print symbol to expand its contents, and set the value of the preference OnlyChaptersInTOC to on. Save the preferences and restart Telelogic Tau.

Title Page

A plain text document can become a title page by placing it first among the diagrams and documents that are printed. There is nothing special about a title page, except that it can be placed before the table of contents.

Figure 98 : A title text document in the Organizer view

Getting the Title Page before the Table of Contents

To print a table of contents, you have to turn on the Table of contents toggle button in the Contents section in the Print dialog.

Normally, you do not have to do anything to get the title page before the table of contents, because the print operation will as default treat an initial text document as a title page. There is however a way to turn this on and off. This is done in the Print Setup dialog for the Table of contents entry in the Contents section in the Print dialog. You can get to this dialog from the Print dialog by pressing the setup button with a picture close to the Table of contents entry.

State Matrices

State Matrices are described in detail in 6 The Text Editor. Here are only the most important things discussed, enabling you to get a nice printout of state matrices for processes in your SDL system.

Creating State Matrices

When you have a correct SDL system, you can create state matrices with the Generate > State Overview menu choice. A state information file (*.ins) will be created in your target directory, a plain text symbol connected to the file will be added in the Organizer view, and a Text Editor will pop up, acting as a State Matrix Viewer.

Figure 99 : A state matrix

Process HelloWorld: nextstates
States
a Start state
b waiting
c stop
| STATES
SIGNALS | a b c
|-------------
- | b
Hello | c

Filter State Matrices

The Text Editor has two menu choices that you can use to get the state matrices that you want.

  • View > State Matrix > Filter Processes. This menu choice allows you to hide state matrices for SDL processes that you are not interested in.
  • View > State Matrix > Transition Information. This menu choice decides the information that should be presented for transitions in your state matrices. As default, you will get two state matrices for each SDL process: One with paper page references to the corresponding SDL transition and one with nextstate information. You can with this menu choice also have state matrices with output/signal sending information and procedure call information.

The options in the two dialogs above can also be set in a more permanent way, using preferences. To do this, use these Text Editor preferences:

  • StateMatrixFilter
  • StateMatrixCalls
  • StateMatrixNextstates
  • StateMatrixOutputs
  • StateMatrixPageNumbers

Printing State Matrices with Paper Page References

When you view state matrices on-line, you will not see any paper page references in a page number state matrix. All page numbers are undefined and replaced by a "*". The page numbers are only visible in your printout, and only if you print the SDL processes together with the state matrices from the Organizer.

Index

The index is described in detail in 47 The SDL Index Viewer. Here are only the most important things discussed, enabling you to get a nice printout of an index of all SDL entities defined and used in your SDL system.

Creating an Index

When you have a correct SDL system, you can press the Generate Index quick button in the Organizer. This will pop up an index viewer with an index of all SDL entities defined and used in your SDL system.

Figure 100 : An SDL entity index example

Filter Index Information

The generated index may be too long to be printed in its entirety. You can make the index smaller by filtering out information that you consider unimportant.

You can filter out SDL entities defined in specific SDL diagrams. This is done with the View > Filter Diagrams dialog. A common use of this possibility is to filter out SDL entities defined in package Predefined.

You can filter out SDL entity types. This is done in the View > Filter Types dialog. For instance, if you want an index of just the signals in your SDL system, then you can use this possibility to filter out all other SDL entity types.

To make your filter more permanent than just for the current Index Viewer session, you should define your filter settings in the Preference Manager before starting the Index Viewer. These two preferences are appropriate:

  • FilterDiagrams
  • FilterTypes

Deciding Index Appearance

Each SDL entity in the index can be presented in four different ways. You can change the index appearance for the current Index Viewer session with the View > Index Appearance dialog. To make your changes more permanent, use the Preference Manager and the following preference:

  • IndexAppearance

As default, the index appearance is set to Detailed. This setting is appropriate for on-line viewing. For a printout, it might produce unnecessary large indexes. To get a smaller index in a printout, use the Compact index appearance.

Printing an Index with Paper Page References

It is possible to get paper page references for both definitions and uses of SDL entities in a printout of an index. To achieve this, leave the Index Viewer window on screen while doing a printout from the Organizer that includes your SDL system and the index view.

Fonts

There are two kinds of fonts:

  • Proportional fonts such as Times. These fonts have the advantage of not needing much space.
  • Non-proportional fonts such as Courier. These fonts have the advantage of being useful for creating tables where it is important that the same character position on different lines are aligned.

Below, you will learn how to set up Telelogic Tau to use appropriate fonts for different uses.

Using a Non-Proportional Font in the Text Editor

State matrices are viewed and printed from the Text Editor. State matrices should be presented using a non-proportional font. To get a non-proportional font in printouts of state matrices, set the preference SDT*PrintFontFamily to Courier.

Using a Non-Proportional Font for SDL Text Symbols

Sometimes, it is convenient to make aligned tables in SDL text symbols. This requires a non-proportional font. On the other hand, you do not want a non-proportional font for all other symbols in a process diagram, because you want to squeeze as much text as possible into a flow symbol without going outside the symbol border.

You can have a separate, non-proportional font for SDL text symbols. This is achieved by setting Editor*FontText*TextSymbolFontFamily to Courier. This preference is valid both on-line and in print. All the other symbols use the fonts set by Editor*FontText*ScreenFontFamily and Editor*FontText*PrintFontFamily.

Title Fonts: Size and Boldness

The table of contents has a title named "Contents" that is always presented in bold.

Font size and boldness for chapter names in text page titles are determined by the chapter level:

  • Chapter level 1 (for instance 1) uses 14 pt bold.
  • Chapter level 2 (for instance 1.1) uses 12 pt bold.
  • Chapter level 3 (for instance 1.1.1) uses 11 pt bold.
  • Chapter level 4 (for instance 1.1.1.1) uses 11 pt, not bold.

A normal text, and a chapter without a chapter number (chapter level 0), uses the same font appearance for the title as the font used for the following text.

To get header titles in a larger font (14 pt) and with a bold text, use a header definition file with a Title keyword. (<#Title>, <#Title 2> or something similar.)

Text Indentation

There are three text indentation levels, and each text indentation level has a corresponding preference:

  • Print*TextIndentation1. Used by text pages for presenting chapter numbers. Default: 44 mm from the left paper edge.
  • Print*TextIndentation2. Used by text pages for presenting chapter names and normal text. Also used by the table of contents for presenting chapter numbers. Default: 67 mm from the left paper edge.
  • Print*TextIndentation3. Used by the table of contents for presenting chapter names. Default: 90 mm from the left paper edge.

Introducing Advanced Print Facilities

In this sub section we will take a more detailed and practical look at how an ordinary SDL system can be turned into an SDL system with enhanced print facilities.

Note:

As default in this section, we are talking about menu choices and dialogs in the Organizer.

Initial Setup

Before starting doing print enhancements for the specific SDL system, we should set up some preferences affecting how the final printout will look like.

  1. Bring up the Preference Manager with the menu choice Tools > Preference Manager.
    • To get a non-proportional font in printouts of state matrices, set the preference SDT*PrintFontFamily to Courier.
    • To get a non-proportional font in text symbols in SDL diagrams, set the preference (SDL) Editor*FontText*TextSymbolFontFamily to Courier.
  2. Save the preferences and exit the Preference Manager.

The Example SDL System

We will use an SDL system called HelloWorld as an example. When we start, we have a correct SDL system that is not adapted in any way for producing a nice printout. If we just do a plain printout of HelloWorld, we will get the following:

Note:

The figures below are not exact copies of a printout, they have been modified slightly to fit in this manual.

Figure 101 : HelloWorld, Organizer view

Figure 102 : HelloWorld, system diagram

Figure 103 : HelloWorld, block diagram

Figure 104 : HelloWorld, process diagram

To get a better printout, we will add the following:

  • A Header on Each Printed Page
  • A Title Page
  • Chapters and Sub Chapters
  • State Matrices for the SDL Process
  • An Index of SDL Entities

When we have done that, we will perform a print operation to actually get our enhanced printout.

A Header on Each Printed Page

The header should have the following properties:

  • A separate header appearance for the first page.
  • The company logo should be visible on every page.
  • The header should include information about page number, total pages, chapter number and chapter name.

Fortunately, someone at our company has provided a company logo in Encapsulated PostScript format (*.eps), and a template header definition file. The template looks like this:

IFFIRST
18 28 Name of designer
ENDIF

IFNOTFIRST
183 20 <page>(<totalpages>)
90 24 Chapter <chapternumber> <chaptername>
ENDIF

EPSF 10 25 /home/lat/hello/telelogic.eps
90 20 Name of SDL system

Action

  1. The header symbol is not visible in the Organizer view. To make it visible, bring up the View Options dialog and select the Header file item and press Apply and Close.
  2. To create a new and unique header for the SDL system, double-click on the header symbol in the Organizer view.
  3. In the Edit dialog that follows, we should specify the template file under Copy existing file. In our case, someone has put the template file in /home/lat/hello/headerTemplate.txt.

Figure 105 : Specifying the template header file in the Add New dialog

  4. When we close the Edit dialog, the text editor pops up with a copy of the template header file.
  5. To get a unique header for our SDL system, we change the following things:
Name of designer -> Lars Tufvesson
Name of SDL system -> HelloWorld

  6. When that is done, we save our specialized header file in the same directory as our SDL diagrams.

A Title Page

A title page is a plain text document that is placed first among all printed pages and documents.

Action

  1. We should add a new plain text document to our SDL system. To make sure it is placed first, select the header symbol before invoking Add New.
  2. In the Add New dialog, set the document type to Plain Text and set the document name to TitlePage.
  3. When you close the dialog, the Text Editor pops up. Type in an appropriate title page text (like the one below) and save the text file in the same directory as the SDL diagrams.
*******************
*System HelloWorld*
*******************

A revolutionary SDL system software package

Chapters and Sub Chapters

We would like to divide our diagrams and documents in three chapters:

  • The first chapter contains state matrices for the SDL process(es).
  • The second chapter contains the SDL system.
  • The third chapter is an appendix that contains the index of SDL entities.

The second chapter will be further divided into two sub chapters. Each chapter and sub chapter should have a chapter introduction text.

Action

  1. We would like to place the first chapter directly after the title page text symbol. Select the title page text symbol and bring up the Add New dialog.
  2. Set the document type to Organizer > Chapter 1, and the document name to State Matrices.
  3. When you close the dialog, the Text Editor will pop up. Type in an appropriate chapter introduction text (like the one below) and save the text file.
This chapter contains two state matrices for the
SDL process: One with page numbers to the SDL
process and one with nextstate information.

We will produce the state matrices for this chapter in the next sub section. For now, we leave this chapter empty.

  4. We introduce a second chapter for the SDL system. Select the State Matrices chapter symbol and bring up the Add New dialog. Set the document type to Organizer > Chapter 1, and the document name to SDL system. When you close the dialog, the Text Editor will pop up. Type in an appropriate chapter introduction text (like the one below) and save the text file.
In this chapter, you will find the actual SDL system.

  5. The SDL system chapter should have two sub chapters for the SDL process. To be able to begin a chapter between two pages in one SDL diagram, we must make page symbols visible in the Organizer. This is done in the View Options dialog by selecting Page symbols and pressing Apply and Close.
  6. The first sub chapter should begin where the process diagram begins. Select the process diagram symbol and bring up the Add New dialog. Set the diagram type to Organizer > Chapter 1.1, and the document name to First process page. When you close the dialog, the Text Editor will pop up. Type in an appropriate chapter introduction text (like the one below) and save the text file.
In this sub chapter, the first process page will be defined.

  7. The second sub chapter should be placed between the two pages of the SDL process. Select the first process page symbol and bring up the Add New dialog. Set the diagram type to Organizer > Chapter 1.1, and the document name to Second process page. When you close the dialog, the Text Editor will pop up. Type in an appropriate chapter introduction text (like the one below) and save the text file.
In this sub chapter, the second process page will be defined.

  8. Finally, we should have an appendix chapter for the index of SDL entities. This chapter should be placed last in the Organizer view. Select the last symbol in the Organizer and bring up the Add New dialog. Set the diagram type to Organizer > Chapter 1, and the document name to Appendix. When you close the dialog, the Text Editor pops up. Type in an appropriate chapter introduction text (like the one below) and save the text file.
The appendix contains an index of all SDL entities.

State Matrices for the SDL Process

The Organizer can with the help of the Analyzer generate a state overview information file (*.ins). The file is placed in the target directory. The Text Editor can display this file as state matrices.

Action

  1. First, we should set the target directory to an appropriate directory where we can allow Telelogic Tau to create files. Bring up the Set Directories dialog and type in an appropriate target directory. When that is done, close the dialog.
  2. Select the SDL system diagram and invoke the state overview information file generation with Generate > State Overview. The Analyzer will check your SDL system and produce some files in the target directory. One of these files is the *.ins file.
  3. When the Analyzer is ready, the Text Editor will pop up, showing you the state matrices created from the information in the state overview file (*.ins). When you have examined the state matrices, exit the Text Editor.
  4. The plain text symbol connected to the *.ins file should be placed in the first chapter instead of in the same chapter as the SDL system. To move the plain text symbol for the *.ins file to the correct location, select the symbol and use the up quick button as many times as required to get the symbol into the first chapter.

An Index of SDL Entities

We would like an index of SDL entities defined in our SDL system last in the printout. The Organizer can with the help of the Analyzer produce a cross reference file. The Index Viewer can present the information in the cross reference file as an index. To keep the size of the index small, we filter out some SDL entities and we present the index in an as compact way as possible.

Action

  1. Make sure that the target directory is set to an appropriate directory where the Analyzer can create some files.
  2. Select the SDL system diagram symbol and press the Generate Index quick button. The Analyzer will check your SDL system and generate some files in the target directory. One of the files is named *.xrf and contains the cross reference information. The Index Viewer pops up when the Analyzer is ready, and presents the cross reference information as an index.
  3. If you examine the index, you will notice that there are a lot of SDL entities defined in package Predefined. Let us assume that we are not interested in these SDL entities. To get rid of them, we bring up the Filter Diagrams dialog and select package Predefined. When the dialog is closed, our Index will be much smaller.
  4. To get an even smaller index, bring up the Index Options dialog and set the index appearance to Compact.
  5. Now, the index is ready for printing. Since there is no symbol in the Organizer view for the cross reference file, we have to leave the Index Viewer window open until we have completed the print operation.

Performing the Print Operation

Now, everything is in place to do the actual print operation.

Action

  1. Make sure you have no selection in the Organizer. This can be done by clicking somewhere outside a symbol or text line. This is done to tell the Organizer that we want to print everything, and not just what we have selected.
  2. Bring up the Print dialog.
  3. Make sure that the following entries in the Contents area are selected:
    • Table of contents
    • Organizer View
    • SDL Interaction
    • Text Diagram
    • Index View
      No other entries in the Contents area should be selected.
  4. Bring up the Table of contents setup dialog with the picture button close to the Table of contents entry. In the setup dialog, make sure that both After initial text document and Only chapters in TOC are both selected. Close the setup dialog.
  5. Make sure that the header file check button is on.
  6. Make sure that the settings in the Destination area are appropriate.
  7. Click the Print button. We will get a printout, looking approximately as the figures below.

Figure 106 : The title page

Figure 107 : The table of contents

Figure 108 : The Organizer view

Figure 109 : The introduction to chapter 1

Figure 110 : The state matrices

Process HelloWorld: page numbers
States
a Start state
b waiting
c stop
| STATES
SIGNALS | a b c
|-------------
- | 8
Hello | 8

Process HelloWorld: nextstates
States
a Start state
b waiting
c stop
| STATES
SIGNALS | a b c
|-------------
- | b
Hello | c

Figure 111 : The introduction to chapter 2

Figure 112 : The SDL system diagram

Figure 113 : The SDL block diagram

Figure 114 : The introduction to chapter 2.1

Figure 115 : The first process page

Figure 116 : The introduction to chapter 2.2

Figure 117 : The second process page

Figure 118 : The introduction to the appendix

Figure 119 : The index

Using Advanced Print Facilities

In the previous section, we took an ordinary SDL system and made enhancements to get a nice printout. In this section, we will look at how we can make the enhancements as permanent as possible. We would like to be able to load a system file, invoke the print operation and get a nice printout without changing any print settings.

Let us take a new look at all the changes we have made, to see how we can make a future print operation as painless as possible.

A Permanent Title Page

Every time the print dialog is invoked, the Table of contents setup option After initial text document will be turned on. This means that the title page will show up as a title page in future print operations also. No extra actions necessary here.

Permanent Chapters and Sub Chapters

The chapter symbols should stay where they were initially placed. Due to implementation reasons, chapter symbols placed between SDL page symbols might be a little more volatile than they should be. The position of a chapter symbol is determined by remembering the name of the next SDL page symbol. If you rename that SDL page symbol, the chapter looses its hook and may end up in the wrong position.

The chapter options that you can set in the Chapter Options dialog are reset every time Telelogic Tau is restarted. This means that if you want the start chapter number to permanently be anything other than 1.1.1.1, or you want to hide sub chapters in the table of contents, then you have to check the Chapter Options settings before each print operation.

Permanent State Matrices

State matrix options are not saved together with the state overview file (*.ins), but they are saved in the system file (*.sdt) and in print selection files (*.sel).

The state overview file (*.ins) is generated in the target directory. You may regard the target directory as a temporary directory where files can be erased after a Telelogic Tau session is ended. It might be cumbersome to regenerate a state overview file each time you want to do a printout. In this situation, it might be a good idea to move the state overview file to the source directory, where your SDL diagram files resides. The file move is most easily done outside of Telelogic Tau, but you have to reconnect the plain text symbol in the Organizer view to the state overview file in the source directory with Telelogic Tau.

A Permanent Index

Index options are not saved together with the cross reference file (*.xrf), but they are saved in the system file (*.sdt) and in print selection files (*.sel).

The cross reference file (*.xrf) is generated in the target directory. You may regard the target directory as a temporary directory where files can be erased after a Telelogic Tau session is ended. It might be cumbersome to regenerate a cross reference file each time you want to do a printout. In this situation, it might be a good idea to move the cross reference file to the source directory, where your SDL diagram files resides. The file move is most easily done outside of Telelogic Tau.

To get paper page references in the index, the index has to be printed from the Organizer together with the SDL system.

Performing a Permanent Print Operation

Every time the print dialog is invoked, the Table of contents setup option Only chapters in TOC will be set to off. This means that if you want only chapters in the table of contents, you have to turn this option on every time you want to print.

In a similar manner, every time Telelogic Tau is started, the Table of contents toggle button in the main print dialog is set to off. This means that every time you want to do a print, you have to check the Table of contents toggle button and turn it on, if it is off.

Print Selection Files and Print Selection Symbols

Most print, index and cross reference options are saved in the system file (*.sdt). This is often enough for most of your print needs. However, in some situations you might want to save more than one set of print settings: You want to easily switch...

  • Header and footer information
  • The set of documents/diagrams/pages that should be printed.

This can be done by saving a couple of print selection files with different print settings, and reference these files with print selection symbols in the Organizer.

  1. To save print settings in a print selection file, bring up the Organizer print dialog, as you would for performing a normal print operation.
  2. Adjust the settings in the dialog to what you want printed, both by changing what diagrams to print and by changing how the print will be performed (paper format etc.).
  3. When all settings are correct, use the Save button to save the print selection file. In the dialog that appears, you can both decide the print selection file name to use, and if a print selection symbol should be created in the Organizer or not.

A print selection can be reused in several ways:

  • Double-click the print selection symbol.
  • Select the print selection symbol and invoke File > Print > Selected.
  • Invoke File > Print > Selection File, and specify the print selection file in the dialog that appears.

In all these cases, the Organizer print dialog will appear, with settings according to the reused print selection file.


6 The Text Editor

The Text Editor is the graphical tool that is used to create, edit, display and print text file documents.

The Text Editor can also be used as a state matrix viewer. One or several state-signal matrices can be presented for each process in an SDL system. The state matrices for an SDL system are presented as one read-only text file. As in any other SDL viewer tool, it is possible to navigate from an entity in a state matrix to the corresponding entity in the SDL system.

This chapter contains a reference manual to the Text Editor; the functionality it provides, its menus and windows.


Text Files

The Text Editor works with ASCII text files. The text editor can be used to view, edit and print text files. In addition to providing typical text editor functions, the Text Editor provides special support for embedding link endpoints into the text. For more information on links and endpoints, see 10 Implinks and Endpoints.

Note:

The Text Editor is only available if the Organizer is started with the preference SDT*TextEditor set to "SDT".

Endpoint Support

In the Text Editor, endpoints are user-defined, non-overlapping, contiguous ranges of characters, possibly spanning several lines of text, that are made visible to other tools, allowing you to define links between fragments in your text and endpoints in other documents.

Endpoints are displayed in the text editor by underlining the range of characters that are part of the endpoint.

Note that when you define an endpoint, you do not impose any particular restrictions on the text in the endpoint, meaning that you can still edit the text in the endpoint using the normal text editing functions to modify the endpoint's contents. The text editor dynamically notifies other tools the changes you make to your endpoints as you make your changes, to make sure that the view of the endpoints in your file is always current.

Considerations when Using Text Endpoints

The requirement that endpoints must be non-overlapping means that you cannot create an endpoint inside another endpoint. Also, while an endpoint is allowed to span several lines, it is generally best to restrict endpoints to small, well-defined fragments of text on a single line, used as external reference points to the information in your files.

Also note that while the Text Editor visualizes endpoints by simply underlining the text in the endpoints, the endpoints are stored in your actual text files using special keywords before and after the characters in the endpoint. This means that it is not advisable to view or edit text documents with endpoints in a text editor that is not aware of the special significance of these keywords. If you do so, you should be careful so as to not destroy information about the endpoints in the file, as this could cause links attached to these endpoints to break.

Another consequence of how the Text Editor stores the endpoint information is that if you are editing text documents that are intended as input to other tools (such as a C or C++ compiler) you should take care to place endpoints only within commented regions of text. This makes sure that the extra text inserted when storing the endpoints does not conflict with the allowed grammar of the type of file you are editing.

Examples

In the examples below you will find typical placements of text endpoints. These endpoints could then be the basis for creation of links into requirements, analysis, design, and specification documents, to name only a few possibilities.

Example 20

Improperly commented C header with endpoints:

/* Primary protocol packet */
struct Packet { ... };

Properly commented C header with endpoints:

/* Primary protocol packet */
struct Packet { ... };

Example 21

Improperly commented C++ header with endpoints:

class Base {
virtual char *name() const = 0;
virtual int size() const = 0;
...
}

Properly commented C++ header with endpoints:

// class Base
class Base {
virtual char *name() const = 0; // get name
virtual int size() const = 0; // get size
...
}


State Overview Files and State Matrices

The Organizer can produce a state overview file, see "State Overview" . The Text Editor recognizes a state overview file by the extension .ins. If such a file is opened in the Text Editor, the Text Editor extracts information from the file and presents the information as a read-only text file containing state matrices. State overview files cannot be edited or saved in the Text Editor.

A state matrix is a textual table with the states in a process or procedure along one dimension and the signals in the same process or procedure along the other dimension. In the table, you will find the transitions for the process or procedure.

A state matrix may look like this: ("-" means no signal)

Process Main: nextstates

States
a Start state
b Game_Off
c Game_On
| STATES
SIGNALS | a b c
|-------------
- | b
Newgame | c
Endgame | b

The Text Editor keeps track of how entities in the state matrix is related to the SDL system. This makes it possible to navigate back to the SDL system. To do so, place the text cursor close to an entity in a state matrix and bring up the pop-up menu for that entity and invoke one of the available menu choices.

A state overview file can be saved as a normal text file. This might be useful if you want to edit a state matrix. But by doing so, you will lose all the extra information associated with the state matrices that is not visible when viewing a state overview file in the text editor. You will no longer be able to:

  • Navigate back to SDL.
  • Get paper page references to SDL pages for transitions in the state matrix (read more about how this is done in "Advanced Print Facilities" ).
  • Decide the kind of information that should be presented for a transition in the state matrix.


Text Editor User Interface

The Text Editor window is depicted below. For a general description of the user interface, see 1 User Interface and Basic Operations.

Figure 120 : The Text Editor window


Text Area

Text in the Text Editor is displayed and printed using the non-proportional font face Courier, which is suitable for displaying ASCII texts such as source code.

While the screen font is fixed, you can change the font face used use for printing by editing the SDT preference SDT*PrintFontFamily.

Text Editing Functions

The following text editing functions are provided in the text window:

Text Selection

To select text you can either:

  • Drag the pointer over the text.
  • Place the cursor in the beginning or end of the text to be selected and then <Shift>-click where you want the selection to end.

Word Selection

Double-click a single word, delimited by spaces, to select it.

Line Selection

Triple-click a line of text to select it.

Text Editing

When you edit text, you can:

  • Position the cursor by clicking or by using the arrow keys.
  • Insert characters after the current position of the text pointer.
  • Delete one character backward by pressing <backspace>.
  • Delete one character forward by pressing <delete>.
  • Replace selected text by typing.
  • Delete selected text by pressing <backspace> or <delete>.

Undoing Text Modifications

The Undo command reverts the previous editing command. Several undo operations can be performed in sequence to undo sequences of editing commands.

Undo can negate the effects of all commands that alter the text in the Text Editor; however, the effect of user operations on endpoints and links cannot be undone by the undo command.

Depending on the nature of the last performed operation, the effects of the last text editing operation is undone, on a per editing operation. For undo purposes, the text editor recognizes the following operations:

  • Typing a character
  • Inserting a character or a fragment of text
  • Deleting a character or a fragment of text

While having to undo each typed character individually may be somewhat inconvenient, a keyboard accelerator (<Ctrl+Z>, see "Keyboard Accelerators" ) can speed up the process.

Note that since the text editor supports unlimited undo, it is not possible to use the undo operation to undo the last undo operation. Instead there is a keyboard accelerator (<Ctrl+Y>, see "Keyboard Accelerators" ) which can be used repeatedly to undo the effects of a sequence of undo operations.

Editing Text Containing Endpoints

It is possible to edit text using normal operations even after endpoints have been embedded in your text. To unambiguously determine the effects of editing operations on endpoints, the Text Editor uses the character just before the position of your insertion cursor or your selection (the initial character) to determine if your editing affects an endpoint:

  • If the initial character belongs to an endpoint (e.g. the insertion cursor is positioned just after an endpoint), inserted text will become part of the endpoint.
  • If the initial character belongs to non-endpoint text (e.g. the insertion cursor is positioned just before an endpoint), the inserted text will not be included in an endpoint.

Note:

When deleting or overwriting text, you should be careful not to delete or overwrite all characters in an endpoint since this will remove the endpoint and the associated links.

Dealing with Consecutive Endpoints

When working with consecutive endpoints (i.e. two endpoints follow each other without any intervening non-endpoint text), it is impossible to insert extra characters between these endpoints using the normal text editing operations, since any text inserted between the two endpoints will be considered a part of the first endpoint.

If this particular case arises, you should use Clear Endpoint (see "Link > Clear Endpoint" ) to remove some characters from one of the endpoints so that some non-endpoint characters become available between your endpoints.

Also note that while the text editor has no difficulty in dealing with consecutive endpoints, visual limitations will make it difficult to distinguish between the two endpoints. You should therefore avoid using consecutive endpoints if possible.


Menu Bar

The menu bar provides commands available in menus and menu choices for editing diagrams and pages of diagrams. Most the functionality that the Text Editor offers is contained within the commands from the menu bar. The Text Editor's menu bar provides the following menus:

  • File Menu
  • Edit Menu
  • View Menu
  • Diagrams Menu
  • Window Menu
  • Tools Menu
  • Help Menu
    (see "Help Menu" )

File Menu

The File menu contains the following menu choices:

  • New
  • Open
  • Save
  • Save As
  • Save a Copy As
  • Save All
  • Close Diagram
  • Revert Diagram
  • Print
  • Exit

The menu choices are described in "File Menu" , except Print which is described in "The Print Dialogs in the SDL Suite and in the Organizer" .

Edit Menu

The Edit menu provides the following choices, which may or may not be dimmed depending upon whether or not some text is selected:

  • Undo
  • Cut
  • Copy
  • Paste
  • Paste As
  • Clear
  • Select All

Undo

This command restores the last text editing operation. The following operations can be undone:

  • Typing, insertions and deletions.
  • Cut, Paste, Paste As and Clear

Note:

Undo does not restore endpoints or links, even though typing, insertions and deletions can destroy both endpoints and links

For more information on the operation of the Undo command, see "Undoing Text Modifications" .

Cut

Cut removes the selected portion of text from the text window and saves it in the clipboard buffer just as if a Copy has been made. Cut is only available if a portion of text has been selected. Cut is not available for state overview files (*.ins), because they are not editable.

Also see "Deleting an Object" .

Copy

Copy makes a copy of the selected portion of text in the clipboard buffer. The content of the text window is not affected. Copy is only valid if a portion of text has been selected.

When copying text to the clipboard buffer it becomes possible to paste into three different contexts:

  • As simple text (without endpoint and link information) into applications that normally support cut/copy of text, such as terminal windows and other text editors.
  • As text with endpoint and link information when pasting into one of the Text Editor windows, which means that endpoints and links are preserved.
  • As a Paste As operation in all the Editors (including the Text Editor itself), provided that the copied text contained no endpoints or exactly matched an endpoint. See "Pasting a Text Fragment" for more information.

Paste

Paste inserts the content of the clipboard buffer into the text window. The text in the clipboard buffer will be appended immediately following the cursor position, or replacing the selected text. Paste is only available if a portion of text has been cut or copied into clipboard buffer. Paste is not available for state overview files.

Also see "Pasting an Object" .

Paste As

Pastes the currently copied object (from the OM or Text Editor) as a text in the text window. The object is transformed and a link is optionally created between the copied object and the pasted text.

The Paste As dialog is opened. See "The Paste As Command" for more information. Paste As is not available for state overview files (*.ins), because these files are not editable.

Clear

Clear removes the selected portion of text from the text window. The content of the clipboard buffer is not affected. Clear is only available if a portion of text has been selected. Clear is not available for state overview files (*.ins), because these files are not editable.

Also see "Deleting an Object" .

Select All

Select All selects all of the text contained in the text window.

View Menu

The View menu provides rescaling functions and access to various options that affect the behavior of the Text Editor. The following menu choices are available:

  • Window Options
  • Editor Options
  • State Matrix > Filter Processes
  • State Matrix > Matrix Options

Window Options

This menu choice issues a dialog where the presence of the tool and status bars can be set:

Figure 121 : The Window Options dialog

  • Clicking OK applies the options as defined in the dialog to the current window only.
  • Clicking All Windows applies the options as defined in the dialog to all windows opened by the Text Editor.

Editor Options

This menu choice issues a dialog where the behavior of the Text Editor can be customized.

Figure 122 : The Editor Options dialog

The options are controlled by toggle buttons. They are:

  • Always new Window
    This option indicates whether or not a new window should be opened whenever the New or Open command or any command from the File menu is operated.
    The default behavior is not to open a new window.
  • Sound
    This option indicates whether or not improper actions in the Text Editor, such as attempting to overlap symbols, should be brought to the user's attention by producing an alert sound.
    The default value for this option is on.
  • Show Link Endpoints
    This option indicates whether link endpoints should be displayed by underlining the endpoint text.

Note:

Regardless of the setting of this option, link endpoints are never shown when printed.

The default value for this option is controlled by the TE*ShowLinks preference.

State Matrix > Filter Processes

This menu choice is only available for state overview files (*.ins).

This menu choice brings up a dialog that decides the group of processes that should be visible as state matrices. As default, all processes in the SDL system are visible. The dialog allows you to show selected processes, hide selected processes or show all processes.

State Matrix > Matrix Options

This menu choice is only available for state overview files (*.ins).

This menu choice brings up a dialog with options for state matrices. The available options are listed below.

Sort states

The states in the state matrices will be sorted in alphabetical order.

Sort signals

The signals in the state matrices will be sorted in alphabetical order.

Show page reference matrix

The page references refer to the printed page where the transition in question starts, i.e. where the SDL input symbol is placed. `-' means no signal.

Page references are normally not visible, they are replaced with `*'. The only chance you have to see page references instead of `*' is to print the SDL process together with the state overview file (*.ins) from the Organizer.

Page reference matrix for process Demon:

States
a Start state
b Generate

| STATES
SIGNALS | a b
|--------
- | *
T | *

Show nextstate matrix

For each transition, the possible nextstates are listed. `-' means no signal.

Nextstate matrix for process Demon:

States
a Start state
b Generate

| STATES
SIGNALS | a b
|--------
- | b
T | b

Show signal sending matrix

For each transition, signals that might be sent from SDL output symbols during the transition are listed. `-' means no signal or no output.

Signal sending matrix for Process Demon:

States
a Start state
b Generate

| STATES
SIGNALS | a b
|--------
- | -
T | 1

1 = Bump

Show procedure call matrix

For each transition, procedures that might be called during the transition are listed. `-' means no signal or no procedure call.

Process Demon: procedure calls

States
a Start state
b Generate

| STATES
SIGNALS | a b
|--------
- | -
T | -

Diagrams Menu

The Diagrams menu records all diagrams and pages that are opened by the Text Editor. The available menu choices are:

  • Back
  • Forward
  • <Diagram Name>
  • List All

Back

Select this menu choice to browse back to the document that was previously displayed in the window.

Forward

Select this menu choice to browse forward to the document that was displayed in the window before you selected Back.

<Diagram Name>

The last edited page always goes to the top of the list, and subsequently moves the other diagrams and pages down a position. A maximum of 9 open pages can be shown. A tenth one will be put at the top of the list, but any subsequent opening of a diagram or page will only show the last 9 that have been opened. Another option - List All (at the bottom of the list) - is available to list all the open diagrams in the Text Editor.

Each item in the menu provides information about the diagram name, possibly followed by the file it is stored on (the file information is missing if the diagram has never been saved). A diagram that is preceded by an asterisk (`*') denotes that it has been modified during the Text Editor session.

List All

This menu choice becomes available when a maximum of 9 open pages has been surpassed. When List All is selected, it provides a dialog containing all diagrams and pages that are currently open in the Text Editor:

Figure 123 : The List All dialog

Window Menu

The Window menu contains the following menu choices:

  • Close Window
  • Entity Dictionary

Close Window

This option closes the open window, but, not necessarily the diagram. If more than one editor window is opened, only the current window is closed and not the diagram. If the last open editor window is closed, the Text Editor will act as if Exit has been chosen, possibly in conjunction with a save of information (see "Close Diagram" ).

Entity Dictionary

Opens the Entity Dictionary window. See "The Entity Dictionary" for more information.

When working with the Entity Dictionary in the Text Editor, note that the Link > Create command will not automatically create an endpoint on the current selection as is the case in the graphical Editors.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
  • Link > Create
  • Link > Create Endpoint
  • Link > Traverse
  • Link > Link Manager
  • Link > Clear
  • Link > Clear Endpoint
    (The Link commands are described in "Link Commands in the Tools Menus" .)
  • Go To Line
  • Search
  • Go To Source
  • Show Transition
  • Show Nextstate
  • Show Output
  • Show Call
  • Show State
  • Show Signal

Go To Line

This menu choice moves the cursor to a line specified by the user. When selected, a dialog will appear querying the user where to move.

Figure 124 : The Go To Line dialog

  • Goto line number
    In this text field the user can specify a line number.
  • Goto line
    Moves the cursor to the specified line and closes the dialog. This button will be dimmed if the Goto line number text field does not contain a valid line number. If you have entered a line number that is larger than the number of lines in the document, the cursor is moved to the end of the document.

Search

This menu choice opens a dialog where you may search through the document for a text string and replace it with some other piece of text.

Figure 125 : The Search dialog

Dialog Fields and Options

The Search dialog contains the following fields and options. Values from the previous invocation is used for settings when the dialog is used again.

  • Search for
    The text to search for.
  • Replace with
    Optionally, you can specify a text to replace the text searched for.
  • Search in
    A read-only field showing the current status of the search. This field will display the text "Current document" until the search has ended, when it will show the text "End of document".
  • Consider case
    If this option is set, search is case sensitive.
  • Wildcard search
    If this option is set, wildcard matching will be used when searching. In wildcard search, the asterisk character ('*') matches a sequence of zero or more characters of any kind. The backslash character ('\') escapes the character following it, which is useful if you want to search for asterisks.

Dialog Buttons

When the dialog is first opened, all buttons except Close are disabled. Buttons will be enabled when appropriate, for instance the Search/Restart Search button will be enabled when a string is entered in the Search for text field.

When the dialog opens, searches always start at the top of the document.

  • Search/Restart Search
    This button changed its name depending on the current search status. When it displays Search, it finds the next match in the text. When it displays Restart Search it will restart the search from the top of the document when pressed.
  • Replace & Search
    Replaces the current match with the replace string and searches for the next match.
  • Replace All
    Replaces all subsequent occurrences of the search string with the replace string.

Go To Source

This command takes the currently selected text fragment and attempts to interpret it as an SDT Reference and display it in the appropriate editor. The selection must include the selected reference exactly. This command corresponds to Go To Source in the Organizer.

The syntax of the graphical references used in the Text Editor is described in 19 SDT References.

Show Transition

This operation is only available for state overview files (*.ins), and only when the text cursor is placed close to a transition in a state matrix.

An SDL Editor window is popped up with the SDL input symbol corresponding to the start of the transition currently in focus in the Text Editor.

Show Nextstate

This operation is only available for state overview files (*.ins), and only when the text cursor is placed close to a transition in a state matrix.

Show Nextstate is a sub menu. The menu choices in the sub menu have the names of the states found in all nextstate symbols that ends the transition currently in focus in the Text Editor. When a nextstate name is selected, an SDL Editor window pops up, showing the nextstate symbol.

Show Output

This operation is only available for state overview files (*.ins), and only when the text cursor is placed close to a transition in a state matrix.

Show Output is a sub menu. The menu choices in the sub menu have the names of all signals that might be sent from an SDL output symbol during the transition currently in focus in the Text Editor. When a signal is selected, an SDL Editor window pops up, showing the output symbol with the signal sending.

Show Call

This operation is only available for state overview files (*.ins), and only when the text cursor is placed close to a transition in a state matrix.

Show Call is a sub menu. The menu choices in the sub menu have the names of all procedures that might be called during the transition currently in focus in the Text Editor. When a procedure call is selected, an SDL Editor window pops up, showing the procedure call symbol.

Show State

This operation is only available for state overview files (*.ins), and only when the text cursor is placed close to a state or transition in a state matrix.

Show State is a sub menu. The menu choices in the sub menu represents all the places where SDL state symbols can be found for the state currently in focus in the Text Editor. If a transition is currently in focus in the Text Editor, the Show State operation operates on the start state for the transition. When a menu choice is selected, an SDL Editor window pops up, showing the corresponding state symbol.

Show Signal

This operation is only available for state overview files (*.ins), and only when the text cursor is placed close to a signal or transition in a state matrix.

When this operation is invoked, an SDL Editor window is popped up with the signal declaration corresponding to the signal in focus in the Text Editor. If a transition is in focus in the Text Editor, the operation operates on the signal that triggers the transition.


Pop-Up Menu

Open the pop-up menu by right-clicking or pressing <F2>. The pop-up menu remains opened until you click the mouse or press <Esc>.

Pop-Up Menu in Text Documents

In text documents, the pop-up menu contains some of the menu choices in the Edit and Tools menus.

In state overview files (*.ins), the pop-up menu contains the state overview menu choices in the Tools menu. The menu choices are different depending on if a state, signal or transition is closest to the cursor position.


Keyboard Accelerators

In addition to the standard keyboard accelerators, described in "Keyboard Accelerators" , the Text Editor includes the following:

Accelerator | Command / functionality
Ctrl+L | Redraw window.
Ctrl+Y | Redo (i.e. undo last undo)
Ctrl+1 | Show Organizer
<Delete> | Clear


7 Emacs Integration

(UNIX Only)

On UNIX, Emacs can be used as an external text editor in Telelogic Tau. By configuring Telelogic Tau to use Emacs for handling text documents, the Organizer can interact with Emacs in the same way as with the other Editors.

Handling of SOMT implementation links is supported.

This chapter contains a user manual to Emacs in Telelogic Tau; the functionality it adds and the new commands.


Overview

Introduction

The implementation works with GNU Emacs version 19.31 or later, and only on UNIX systems. It does not work with any Emacs for Windows.

It is assumed that you are familiar with Emacs terminology and how to use Emacs. Some experience with installing Emacs Lisp packages is also required when setting up the integrated environment.

Text Document Handling

By setting preferences to use Emacs as text editor in Telelogic Tau, text editing support in Emacs is offered both from the Organizer and editors. Text document handling is implemented in the Lisp package "sdtemacs".

In the Organizer, text documents are identified by the document type "Text Plain" when you add new or existing documents. A new Emacs instance will always be started, even though there may exist one already (started from outside Telelogic Tau).

Link Handling

The Lisp package "sdtlinks" defines the minor mode SDTlinks which supports SOMT implementation links in text documents. This gives the possibility to handle link endpoints and follow the links defined for these endpoints. The support for link handling is optional.

When the SDTlinks mode is active, endpoints are displayed with a typeface differing from the plain text. Type faces for endpoints with and without links are configurable, see "Type Faces for Endpoints" .

To be able to represent endpoints in text files, the file contents differ from what is seen in the Emacs buffer containing a file with endpoints. The file format for endpoints look like this:

<SDT_LINK_ENDPOINT_BEGIN anchor >text<SDT_LINK_ENDPOINT_END>

where anchor is an integer uniquely identifying the endpoint and text is the endpoint text. If the SDTlinks mode is inactive, this raw file contents is displayed in the Emacs buffer.

Caution!

When the SDTlinks mode is inactive:

Do not alter any text representing endpoints (described in "Link Handling" ).

Do not duplicate text containing endpoints since this will yield unpredictable results as each endpoint is uniquely identified in a file.

As a general principle, Undo is not available for the link handling commands.w


Installation

Text Document Handling

To be able to use Emacs as an external editor in Telelogic Tau:

  1. Put the file sdtemacs.el in a Lisp directory known to Emacs (load-path). By default, the file is installed in $telelogic/include/lisp.
  2. Byte-compile sdtemacs.el for increased execution speed.
  3. Put the line:
    (require 'sdtemacs)
    in your ~/.emacs file or in the file default.el in the ../lisp directory of the Emacs distribution.

Make sure that the environment variable $telelogicbin is correctly set.

Link Handling

To be able to use link handling functions in Emacs:

  1. Put the file sdtlinks.el in a Lisp directory known to Emacs (load-path). By default, the file is installed in $telelogic/include/lisp.
  2. Byte-compile sdtlinks.el for increased execution speed.
  3. Put the line:
    (require 'sdtlinks)
    in your ~/.emacs file or in the file default.el in the ../lisp directory of the Emacs distribution.

Sdtlinks requires sdtemacs, that is, you must install sdtemacs in order to use sdtlinks.

Installation Example

An example of using both packages:

(setq load-path (cons (substitute-in-file-name "$telelogic/include/lisp") load-path))
(require 'sdtemacs)
(require 'sdtlinks)

Preferences

In the Preference Manager, the following parameters should be set:

Parameter | Value
SDT*TextEditor | Emacs
SDT*EmacsCommand | The command that starts GNU Emacs from a UNIX shell (the default is "emacs").


Customizing

Type Faces for Endpoints

The type face for endpoints without associated links is called sdtlinks-endpoint-face. The default appearance is underlined, blue text.

The type face for endpoints with associated links is called sdtlinks-endpoint-with-links-face. The default appearance is underlined, bold, blue text.

These type faces can be redefined.

Example 22

An example to make endpoints without associated links appear as bold, red text:

...
(make-face 'sdtlinks-endpoint-face)
(make-face-bold 'sdtlinks-endpoint-face nil t)
(set-face-foreground 'sdtlinks-endpoint-face "red")
...
(require 'sdtlinks)

Maximum Number of Endpoints in a Document

Due to the nature of the execution environment for Emacs, only a finite number of endpoints are manageable in a document. By default, this limit is set to 1000 endpoints, which should be sufficient for most situations. If, however, a larger number is required, this can be achieved by setting the variable sdtemacs-max-no-of-endpoints.

Example 23

An example to allow 1500 endpoints:

...
(setq sdtemacs-max-no-of-endpoints 1500)
...
(require 'sdtlinks)


Emacs Commands

This section lists and describes the Emacs commands and key bindings associated with the integration with Telelogic Tau. Both new commands and the affected ordinary (existing) commands are described.

Text Document Handling

New Commands

Connect

M-x sdtemacs-connect connects to Telelogic Tau. Automatic connection can be performed when starting Emacs by providing the UNIX command switch post (emacs -post). This is done when Telelogic Tau starts Emacs.

Disconnect

M-x sdtemacs-disconnect disconnects from Telelogic Tau. All buffers taking part in the interaction with Telelogic Tau will be unloaded after asking about saving modified buffers. Exiting Emacs will disconnect from Telelogic Tau.

Show Organizer

M-x sdtemacs-show-organizer opens or raises the Organizer Main window.

Show SDT Reference

M-x sdtemacs-show-reference shows an SDT reference in an appropriate editor. This requires that the reference text is selected or that the point is placed inside it.

Affected Ordinary Commands

Exit Emacs (C-x C-c)

Disconnects from Telelogic Tau before exiting.

New File (C-x b <new buffer>, C-x C-f <new file>)

The new buffer is notified to Telelogic Tau and takes part in the interaction with Telelogic Tau.

Open File (C-x C-f <filename>)

The loaded buffer is notified to Telelogic Tau and takes part in the interaction with Telelogic Tau.

Save (C-x C-s) and Save As (C-x C-w <filename>)

The buffer is notified as saved to Telelogic Tau.

Close File (C-x k)

The buffer is notified as unloaded to Telelogic Tau.

First Modification of Buffer Text

The buffer is notified as modified to Telelogic Tau.

Link Handling

The minor mode SDTlinks, which implements the link handling commands, requires that Emacs is connected to Telelogic Tau, and will try to connect when switched on if this is not the case. All buffers loaded when connected will automatically have this mode active.

New Commands

SDT Links Mode

M-x sdtlinks-mode toggles the minor mode SDTlinks. This is useful if performing editing operations that cannot be done without unintentionally deleting endpoints, e.g. moving (Cut and Paste) a region of text containing endpoints.

Caution!

When SDTlinks is inactive:

Do not alter any text representing endpoints (described in "Link Handling" ).

Do not duplicate text containing endpoints since this will yield unpredictable results as each endpoint is uniquely identified in a file.

Create Endpoint

M-x sdtlinks-create-endpoint (C-c C-c) creates a new endpoint that will be marked with a special type face in the text (see "Type Faces for Endpoints" ) and notified to Telelogic Tau. This command requires that the region of text to convert to an endpoint is selected, i.e. both mark and point must be set. Endpoints are not allowed to overlap and must consist of at least one character.

Delete Endpoint

M-x sdtlinks-delete-endpoint (C-c C-d) deletes an endpoint. The endpoint text will be converted to plain text and the deletion will be notified to Telelogic Tau. All links associated with the endpoint will be cleared. This command requires that point is placed inside the endpoint text.

Follow Link

M-x sdtlinks-follow-link (C-c C-f) follows one of the links associated with the selected endpoint. This results in displaying the endpoint on the other end of the link in an appropriate editor. If only one link is associated with the endpoint, this link is followed. Otherwise, a choice between the associated links is offered in a popup menu:

Figure 126 Choose link to follow

Each menu item, representing a link, is of the format:

<Link name>(<Direction>), <Other endpoint>(<Type>), <File>

where:

<Link name> = The name of the link
<Direction> = The direction of the link: `in' or `out'
<Other endpoint> = The name of the other endpoint of the link
<Type> = The type of the other endpoint of the link
<File> = The name of the file (including the path)
in which the other endpoint resides

This command requires that point is placed inside the text of an endpoint marked as having associated links, see "Type Faces for Endpoints" .

Show Endpoint in Link Manager

M-x sdtlinks-show-endpoint-in-link-manager (C-c C-s) opens the Link Manager and shows the selected endpoint. This requires that point is placed inside the endpoint text.

Affected Ordinary Commands

Modification of Endpoint Text

The endpoint is notified as modified to Telelogic Tau. When point is placed directly after the endpoint text, added characters will become part of the endpoint text.

Cut/Clear (C-w, C-k, M-k and many more)

For all endpoints within the region, Delete Endpoint (see "Delete Endpoint" ) is executed.

Copy Region (M-w)

Endpoints in the copy of the region is represented as plain text.

Insert File (C-x i <filename>)

For all endpoints in the inserted file, Create Endpoint (see "Create Endpoint" ) is executed. Associated links are not handled.

If point is within an endpoint and the file to insert have endpoints, the operation will fail since overlapping endpoints are not allowed.

Undo (C-x u, C--_)

No undo information is recorded for the link handling commands. Consequently, these commands cannot be undone.

Command Summary

Command
Description
M-x sdtemacs-connect
"Connect"
M-x sdtemacs-disconnect
"Disconnect"
M-x sdtemacs-show-organizer
"Show Organizer"
M-x sdtemacs-show-reference
"Show SDT Reference"
M-x sdtlinks-mode
"SDT Links Mode"
M-x sdtlinks-create-endpoint (C-c C-c)
"Create Endpoint"
M-x sdtlinks-delete-endpoint (C-c C-d)
"Delete Endpoint"
M-x sdtlinks-follow-link
(C-c C-f)
"Follow Link"
M-x sdtlinks-show-endpoint-in-link-manager (C-c C-s)
"Show Endpoint in Link Manager"


8 MS Word Integration

(Windows only)

In Windows, Microsoft Word is integrated with Telelogic Tau and MS Word documents are handled by the Organizer.

Handling of SOMT implementation links is supported.

This chapter contains a user manual to MS Word in Telelogic Tau; the functionality it adds and the new menu.


Overview

Introduction

The implementation works with MS Word 7.0 (MS Office 95) and MS Word 8.0 (MS Office 97) in Windows. It is assumed that you are familiar with MS Word terminology and how to use MS Word. Some experience with MS Word templates and macros is also required when setting up the integrated environment.

MS Word Document Handling

Support for MS Word document editing is available in the Organizer. When connecting MS Word to the Organizer, the process SdtWord will be started in the background.

In the Organizer, MS Word documents are identified by the document type "Text Word" when adding new or existing documents.

In the Organizer, MS Word document are represented with the icon shown to the left. Unlike other document types, when a MS Word documents becomes modified, its icon is not marked as "dirty".

A new MS Word documents is always named "Document<x>", where <x> is an integer, regardless of what name it was given in the Organizer.

Link Handling

SOMT implementation links in MS Word documents are supported. This gives the possibility to handle link endpoints and follow the links defined for these endpoints.

An MS Word endpoint icon in the Organizer looks the same as a document icon.

In MS Word, endpoints are marked with special character formats. The appearance for endpoints without associated links is underlined, blue text. The appearance for endpoints with associated links is double underlined, bold, blue text.

Endpoints in MS Word documents are represented with bookmarks whose names are of the format "SDT_<x>", where <x> is an integer uniquely identifying the endpoint.

Undo is not available for the link handling commands.


Installation

MS Word

To be able to use MS Word with Telelogic Tau, do as follows:

For MS Word 7.0

  1. Put the template file sdt95.dot (available in <Installation Directory>\bin\wini386\sdt95.dot) into the folder \MSOffice\Winword\Startup. This means that the template becomes global and the Telelogic Tau commands will be available in MS Word all the time.
  2. Some macros are template dependent, which requires them to be defined for the template on which the document is based. The macros to be copied from sdt95.dot to your document templates are:
AutoClose
AutoNew
AutoOpen

Consult the MS Word documentation on how to copy the macros to your templates.
The macros are (re)definitions of possibly existing MS Word macros. If you already have them defined in your document templates, you must add the code to your own macros.

For MS Word 8.0

There is an automatic installation program available in <Installation Directory>\bin\wini386\sdtwordinstall.exe. You can also make a manual installation:

  1. Put the template file sdt97.dot (available in <Installation Directory>\bin\wini386\sdt97.dot) into a temporary folder.
  2. Change the file protection from read-only to read/write.
  3. Open this sdt97.dot in MS Word and copy the modules:
    SDTAutomacros
    SDTMisc
    to the template normal.dot. Make sure there are no conflicts with other automacros in normal.dot.
  4. Delete the copied modules from sdt97.dot.
  5. Close MS Word and move the sdt97.dot copy into the folder \Microsoft Office\Office\Startup.
  6. Add a reference (in the MS Word VB-editor) from normal.dot to sdt97.dot.

The Startup Folder

You should check that MS Word points at your start-up folder by choosing Tools > Options. In the dialog that appears, select File Locations and check where the file type Startup is pointing. It should point at the directory where you placed sdt95.dot or sdt97.dot.

Note:

Do not use sdt95.dot or sdt97.dot as a document template. It only contains MS Word macros and should be used solely as a global template.

Preferences

In the Preference Manager, the following parameter should be set:

Parameter | Value
SDT*WordCommand | The command that starts MS Word (the default is "Winword.exe").

Make sure that the path points to its directory.


MS Word Menu Commands

This section lists and describes the MS Word menu commands associated with the integration with Telelogic Tau. Both new commands and the affected ordinary (existing) commands are described.

New Menu Commands

The new commands are accessible from a menu in MS Word called SDT. It contains the following menu choices:

  • Connect to SDT
  • Disconnect from SDT
  • Show Organizer
  • Show Reference
  • Create Endpoint
  • Delete Endpoint
  • Follow Link
  • Show Endpoint in Link Manager
  • Update Endpoints

Connect to SDT

Connects to Telelogic Tau. This is done automatically when starting MS Word.

Disconnect from SDT

Disconnects from Telelogic Tau. This is done automatically when exiting MS Word.

Show Organizer

Opens or raises the Organizer.

Show Reference

Shows the selected SDT reference in an appropriate editor. This requires that the user has selected the reference text or placed the cursor inside it.

Create Endpoint

Creates a new endpoint that will be marked with a special character format in the text (see "Link Handling" ) and notified to Telelogic Tau. This command requires that the user has selected the region of text to convert to an endpoint. Endpoints are not allowed to overlap and must consist of at least one character.

Delete Endpoint

Deletes an endpoint. The endpoint text will be converted to plain text and the deletion will be notified to Telelogic Tau. All links associated with the endpoint will be cleared. This command requires that the user has selected or placed the cursor inside the endpoint text.

Follow Link

Follows one of the links associated with an endpoint. This results in displaying the endpoint on the other end of the link in an appropriate editor. If only one link is associated with the endpoint, this link is followed. Otherwise the user is offered to choose between the associated links in a dialog.

This command requires that the user has selected or placed the cursor inside the text of an endpoint marked as having associated links.

Show Endpoint in Link Manager

Opens the Link Manager and shows the selected endpoint. This requires that the user has selected or placed the cursor inside the endpoint text.

Update Endpoints

When applying styles and character formats to text containing endpoints, the endpoint character format may be changed and thus it becomes impossible to tell where the endpoints are located. By using this command all endpoints in the active document will have the endpoint character format applied to them.

Furthermore, when deleting text containing endpoint using the keyboard (<Delete>) instead of menu choices, or pasting text with endpoints from other documents, this is not notified to Telelogic Tau. By executing this command, a synchronization with the Link Manager takes place in order for it to have a consistent view of the endpoints in the active document.

Affected File Commands

Exit

Disconnects from Telelogic Tau before exiting.

New

The new buffer is notified to Telelogic Tau and takes part in the interaction.

Open

The loaded buffer is notified to Telelogic Tau and takes part in the interaction.

Save and Save As

The buffer is notified as saved to Telelogic Tau.

Close

The buffer is notified as unloaded to Telelogic Tau.

Affected Editing Commands

Modification of Endpoint Text

The endpoint is notified as modified to Telelogic Tau.

Note:

In MS Word, inserted text take the same character format as the character that precedes it. Added characters in front of the endpoint text will not take the character format of the endpoint text until the endpoint is updated (see "Update Endpoints" ). MS Word 7.0 only: When the cursor is placed directly after the endpoint text, added characters will not become part of the endpoint text, even though the character format will indicate so.

Clear

All endpoints within the selection will be deleted. See "Delete Endpoint" .

Cut

All endpoints within the selection will be deleted. See "Delete Endpoint" . Endpoints in the copy of the selection is represented by plain text.

Copy

Endpoints in the copy of the selection is represented by plain text.

Paste

Endpoints (bookmarks) not already defined in the document, in which the Paste operation is done, will be created. However, the text region is still plain text and the endpoints have to be updated in order to apply the endpoint character format to the new endpoints.

Undo

No undo information is recorded for the link handling commands. Consequently, these commands cannot be undone.


9 DOORS Integration

This chapter describes the installation and use of the integration of the requirements and traceability management tool Telelogic DOORS together with the Telelogic Tau SDL and TTCN Suites.


Overview

Introduction

Telelogic DOORS is a tool for creating, structuring and managing complex sets of requirements, such as those for a typical software development project. The objective of the DOORS Integration is to make an up-to-date view of Telelogic Tau SDL and TTCN Suite project development information available in DOORS.

The functionality of DOORS can then be used to carry out tasks involving requirement traceability and impact analysis. For instance, you can use DOORS to link requirement documents to SDL and TTCN Suite information.

Users are required to have a working knowledge of both DOORS and the SDL or TTCN Suite.

The integration works with DOORS version 4.0 or later, and SDL and TTCN Suites version 4.1 or later, on all platforms supported by the SDL Suite.

Main Functionality

The main functionality of the DOORS Integration is to export diagram/document information, from the SDL and TTCN Suites to DOORS. The structure in the Telelogic Tau Organizer is duplicated in a DOORS formal module, which represents the Organizer objects in a "surrogate" module.

The objects in a surrogate module are organized hierarchically in the same way as the corresponding objects in the Organizer.

When the surrogate module is created, two views will be created:

  • Tau View, which shows the names of the objects.
  • Tau View with Deletions, which shows the names of the objects and the Deleted in Tau attribute, which keeps track of objects in the surrogate module which no longer have a corresponding Organizer object.

Surrogate modules can be used just like any other DOORS module, but be careful not to delete or add any objects as this may cause the synchronization procedure to fail. You can link objects in the surrogate module to objects in other modules, you can create your own views and you can exploit the power of DOORS traceability tools.


Installation

The integration of DOORS with the SDL Suite only works properly when both DOORS and the SDL Suite run on the same machine, and have been configured properly. This section describes how to install the DOORS Integration.

Installation Procedure for Windows

Note:

In the instructions below, it is assumed that your CD drive is mounted as drive D:\. If your CD has been mounted using another drive letter, please use this letter instead.

To install the DOORS Integration on Windows:

  • Run D:\doors\win32\setup.exe and follow the instructions on your screen. The setup procedure will add the necessary DXL files to your DOORS installation.

Installation Procedure for Unix

Note:

In the instructions below, it is assumed that your CD drive is mounted in accordance with the instructions in "Installation Procedure.

To install the DOORS Integration on UNIX:

  1. Change directory to the DOORS integration installation directory: cd doors/unix
  2. Start the installation script ./doorsinst.cd and follow the instructions on your screen.

Last Minute Additions

There is a readme.txt file in the doors directory on the CD, describing last minute additions and corrections to the DOORS Integration.


Using the Integration

Initial Steps

To use the DOORS Integration, you must first:

  1. Start DOORS
  2. Open an existing project, or create a new one
  3. Create a new formal module

Note:

Do not use a prefix for the object identifiers in the formal module.
Do not manually add any objects in the formal module, as this will make it impossible to run Connect / Synchronize on this module.

If the DOORS Integration was successfully installed, there will now be a new menu in the formal module window, TauSDL. Otherwise, please check the installation procedure again.

Commands in DOORS

Synchronizing

The Connect / Synchronize command is used for two purposes:

  • Initially populating the DOORS formal module with objects corresponding to the Organizer structure.
  • Synchronizing the DOORS formal module with the current contents of the Tau Organizer, to update the surrogate module with the changes that have been made in the Organizer view since the last Connect / Synchronize.

After issuing this command, the formal module containing the surrogate model will now show a Tau-specific view, containing the symbol names from the Organizer view. If the view in the DOORS formal module is set to Tau View with Deletions, the attribute Deleted in Tau, which is set to Yes if a diagram corresponding to an object in the surrogate model was deleted in the Organizer, will also be shown.

The items from the Organizer that are exported to DOORS depend on the installed licenses:

  • If the SDT-DOORS-Integration license is available, the following will be exported from the Organizer:
    • SDL Package
    • System
    • Block
    • Process
    • Procedure
    • System Type
    • Block Type
    • Process Type
    • MSC
    • HMSC
  • If the ITEX-DOORS-Integration license is available, the TTCN documents will be exported from the Organizer, and the test suites will be expanded to also show test groups and test cases in the formal module.

Figure 127 : The DOORS formal module after synchronization

Figure 128 : The Organizer view after synchronization

Note:

The DOORS Integration uses the Telelogic Tau Link Manager to keep track of the objects which have been exported to DOORS. Do not try to edit the contents of the Link Manger view, as this may cause the synchronization procedure to fail.

After the synchronization is done, the following dialog will appear:

Figure 129 : Synchronization progress dialog

  • Perform autosync when this surrogate model is opened
    If this option is checked (default), an automatic synchronization will be done the next time this formal module is opened in DOORS.
  • Hide this dialog box automatically when sync is done
    If this option is checked, this dialog box will not be shown after the next synchronization is done.

Note:

If this option is checked, there might be difficulties in managing these check boxes, since the dialog box will disappear immediately after a synchronization is performed. However, the checkbooks correspond to the formal module boolean attributes "TD AutoSync" and "TD AutoHide", which can be set using the regular DOORS module attributes settings dialog.

  • Show Log
    If this button is pressed, a log will be displayed, showing the proceedings of the synchronization. If there is a problem during synchronization, this log can be useful to find the possible cause.

Navigating

In the Show Symbol menu, there are two sub-commands for navigating from DOORS to the SDL and TTCN Suites: In Organizer and In Editor.

  • Show Symbol > In Organizer will show the symbol corresponding to the selected DOORS object in the Organizer.
  • Show Symbol > In Editor will show the diagram or document corresponding to the selected DOORS object in an appropriate Telelogic Tau Editor or Browser.

Checking License Information

The command Show License Info can be used to check whether the licenses for the DOORS Integration have been installed properly.

Linking DOORS Requirements and Telelogic Tau Diagrams

To create links between DOORS requirements and Telelogic Tau diagrams:

  1. Open the DOORS module that contains the requirements to be linked.
  2. Open the DOORS module that contains the surrogate model which represents the current Organizer contents.
  3. Use standard DOORS linking methods to create links between objects in the requirements module and objects corresponding to the Telelogic Tau diagrams/documents.

Commands in Telelogic Tau Organizer

The command DOORS > Show Requirements in the Organizer will show a list of requirements which are linked to the DOORS formal module representing the selected diagram in the Organizer.

Figure 130 : Dialog showing DOORS requirements

By clicking on one of the requirements in the list, the corresponding DOORS formal module will open with the selection on the chosen requirement.


10 Implinks and Endpoints

Implementation links and endpoints are important concepts in the SOMT method (described in SOMT Methodology Guidelines in chapters 68-76 in the User's Manual. This chapter describes the tool support for implinks and endpoints. The following topics are covered:

  • Link concepts
  • How endpoints and links are visualized
  • How to create links
  • The Entity Dictionary window
  • Link commands in menus
  • The Paste As command
  • The Link Manager tool


Link Concepts and Overview

The SDL suite supports creating and maintaining links between different objects in a system. Such links are used to show relations between objects in different documents. Objects that may be linked are:

  • Text fragments in text documents
  • Graphical objects and symbols in OM, SC, HMSC, SDL and MSC diagrams (but not text fragments in such diagrams)
  • Documents in the Organizer structure.

Implinks

The link concept in the SDL suite is designed to support the SOMT method, further described in the SOMT Methodology Guidelines in chapters 68-76 in the User's Manual. In SOMT, an important relation is that one object can be seen as an implementation of another object. For this reason, links between objects are often referred to as implementation links, or implinks. For instance, a textual object in the requirement analysis may be implemented as an object class in the system analysis, and later as a process type in the design model.

Implinks are the result of a design decision taken during the development of a system. Using implinks enables traceability between the different models and phases, so that the usage of a particular object or concept can be followed from requirements all the way down to code. Another important aspect of implinks is that they facilitate consistency checks between the different models.

Links and Endpoints

A link has two endpoints, one at each of the objects that are linked together. Endpoints can be created for objects without creating a link, i.e. endpoints are entities separate from links. When a link is created, endpoints are created automatically, if they do not already exist. It is possible to have any number of links connected to an endpoint. Endpoints and links can be created from the Organizer and the editors.

Links are bidirectional, i.e. they can be traversed (followed) in both directions. Even so, a link has a "default" direction, defined when the link is created, to indicate the intended direction. This means that an endpoint is either a logical "from" endpoint, or a logical "to" endpoint.

A link has a name and optionally a comment. The name indicates the type of link, e.g. "implementation link", and the comment is used to describe the link.

Link File

Information about endpoints and links is stored in a central link file (extension .sli), which is referred to from the Organizer's system file. This approach makes it easy to get an overview of existing endpoints and links, and to make consistency checks. The link file is saved whenever the system is saved. The link file, and its defined links, are managed by a dedicated tool, the Link Manager (see "Tool Support and Operations" ).

Information about endpoints are also stored in the individual documents. However, link information is only stored in the link file.

Local Link File

To make it easier to use the endpoint and link features in a multiuser environment, the concept of a local link file is provided. This is a personal link file for one user, storing all changes made to endpoint and link information compared to the global file, the master link file. A controlled merge operation is provided to update the master link file with the local link file information. These operations are available as services in the Telelogic Tau Public Interface (see "Link File Services" ).


Visualization of Endpoints and Links

By default, endpoints are marked in a special way in the editors and in the Organizer. The markers are slightly different depending on whether or not any links are connected to the endpoint.

Endpoints in Graphical Editors

In the SDL Editor and the SDL suite diagram editors, the endpoint marker is a small triangle in the upper left corner of the object's enclosing rectangle. The triangle is filled if the endpoint has any links connected to it.

Figure 131 : Endpoints with and without links

For lines in the SDL, OM. SC and HMSC diagrams, the marker appears on the name or signal list associated with the line. In SDL diagrams, it is also possible to create endpoints on other text elements associated with the line.

Figure 132 : Endpoints on lines and text attributes

For lines in MSC diagrams (messages, timers, create requests), the marker normally appears at the "start" end of the line.

Figure 133 : Endpoints on MSC lines

You can hide the endpoint markers by changing the option Show Link Endpoints in the Editor Options in the View menu, or by setting the editor preference ShowLinks to off.

Note:

Endpoint markers are never shown when printing a diagram.

Endpoints in Text Editors

In the Text Editor, endpoints are shown as underlined text, regardless if they have links connected to them or not. The endpoint text can be shown as normal text by changing the option Show Link Endpoints in the Editor Options in the View menu, or by setting the Text Editor preference ShowLinks to off.

In the Emacs editor (on UNIX), endpoints without links are by default shown as blue, underlined text, whereas endpoints with links are shown as bold, blue, underlined text. The default font faces can be changed; see "Type Faces for Endpoints" .

In MS Word (in Windows), endpoints without links are shown as blue, underlined text, whereas endpoints with links are shown as bold, blue, double underlined text.

Endpoint text is always shown as normal text when printing a text document.

Endpoints in the Organizer

In the Organizer, the endpoint marker appears in the same way as in the graphical editors, i.e. a triangle in the upper left corner of the document icon.

Figure 134 : Endpoints in the Organizer.

The endpoint markers are always shown in the Organizer, and they are also shown when printing the Organizer window.


Tool Support and Operations

Operations on endpoints and links are supported in the Organizer, the diagram editors, the Text Editor and the Link Manager.

In the editors, the possible operations are identical and can be found in the Link submenu of the Tools menu (see "Link Commands in the Tools Menus" ). The operations include:

  • Creating and deleting an endpoint
  • Creating and deleting a link
  • Traversing a link (bringing the other endpoint into view)
  • Opening the Link Manager

In the Organizer, the available operations in the Tools menu are limited to creating and deleting an endpoint, and opening the Link Manager.

In the editors, it is also possible to open the Entity Dictionary from the Window menu. The Entity Dictionary lists all endpoints in the system, together with the documents making up the Organizer structure. It is mainly intended for re-use of entity names, but also supports creating links. See "The Entity Dictionary" .

The Link Manager shows all endpoints and links in the system. It supports the following main operations:

  • File operations on the link file
  • Creating and deleting links
  • Editing a link's direction, name and comment
  • Performing consistency checks on endpoints and links

It is not possible to create and delete endpoints in the Link Manager. For more information about the Link Manager, see "The Link Manager" .


Creating Links

There are basically three different ways to create links:

  1. Manually, by linking together two endpoints.
    This operation requires two already existing endpoints. The endpoints may have been created manually, or as an effect of creating a link earlier.
    This operation is only available through the use of the Link Manager. See "Create Link" .
  2. Manually, by linking together an endpoint and a selected object.
    This operation requires an already existing endpoint (selected in the Entity Dictionary), and a selected object in an editor. The endpoint may have been created manually, or as an effect of creating a link earlier. The selected object does not have to be an endpoint.
    This operation is available from the editors and the Entity Dictionary. See "Link > Create" .
  3. Automatically, by copying and pasting an object (Paste As).
    This operation does not require any existing endpoints. An object is first selected and copied in an editor. The object is then pasted in an editor or in the Organizer by using the Paste As menu choice. This transforms the object, if necessary, and automatically creates a link between the copied and pasted object.
    This operation is available from the SDL, MSC, OM and Text Editors and the Organizer and supports the SOMT method. See "The Paste As Command" . It is not available in the SC/HMSC Editor.


The Entity Dictionary

The Entity Dictionary Concept

The purpose of the Entity Dictionary is to provide easy access to names of entities being used in the system, and a possibility to reuse these names in all parts of the system. The entities that the Entity Dictionary manage are all the link endpoints defined in the system, as well as all diagrams, documents and modules found in the Organizer structure.

The Entity Dictionary is accessible from the SDL suite editors. The names in the Entity Dictionary are available for reuse in all texts and graphical objects found in the graphical diagrams. However, the Text Editor does not support reuse of texts in text documents.

The Entity Dictionary is also used for creating links between objects and existing endpoints when using the editors.

Relations to Editor Windows

The Entity Dictionary is implemented as a modeless dialog window. There is not a single Entity Dictionary window, but one window for each type of diagram (SDL, MSC, OM, SC, HMSC and text). All Entity Dictionary windows contain exactly the same information, and all the windows are updated when a change is made. The reason for having an Entity Dictionary window for each editor type is that operations in the window apply to the object currently selected in the respective editor.

Since there might be several editor windows showing different diagrams/documents, there is a need to define the current window. This is the editor window that will be associated with the Entity Dictionary, and all operations will act on the current window. The current window is the editor window where the user last performed a menu command or a mouse click detected by the editor.

The editor associated with an Entity Dictionary window is known as the parent editor. The editor type is reflected in the window title of the Entity Dictionary window, thus making it possible to distinguish the different Entity Dictionary windows, and to determine the parent editor that the Entity Dictionary operations will affect.

Entity Dictionary Window

The Entity Dictionary Window can be opened from all of the editors through the use of the menu choice Entity Dictionary in the Window menu.

Figure 135 : The Entity Dictionary window

Contents and Structure

The window lists all the defined link endpoints, following the structure of diagrams and files in the Organizer. By default, every item in the Organizer is repeated, and the indentation of items is also repeated. All Organizer items and link endpoints listed in the window are known as entities in the Entity Dictionary.

Below each Organizer item, the link endpoints defined in that item are listed with indentation:

  • Below each SDL diagram, the symbols marked as link endpoints are listed.
  • Below each MSC diagram, the instances, messages and other symbols marked as link endpoints are listed.
  • Below each OM diagram, the names of all the classes, instances and other symbols marked as link endpoints are listed.
  • Below each text document, the text fragments marked as link endpoints are listed.

For an Organizer item that contains both sub-documents and link endpoints, the endpoints are listed first, followed by the sub-documents.

It is possible to hide the Organizer items to display only the link endpoints; see "The Filter Dialog" for more information.

The information in the Entity Dictionary is updated whenever a link endpoint is created, changed or cleared in any of the editors or the Link Manager, or when the Organizer structure is modified.

Entity Icons

Each entity has an associated icon that identifies the type of the entity, i.e. the type of the endpoint object. Entities that already have an established icon in the Organizer or the Index Viewer use the same icon in the Entity Dictionary, with a few exceptions. The icons specific to the Entity Dictionary are:

Diagram Heading

Diagram Extended Heading

OM Class

OM Object

OM Association

OM Aggregation

OM Generalization

SC Transition

MSC Message

MSC Create

MSC Timer Set

(H)MSC Reference

HMSC Start

HMSC Stop

HMSC Connection

Text symbols and text fragments

Textual Notation

The type and name of an entity is shown to the right of the icon. For entities containing a name, such as diagram symbols, this name is listed. For other symbols and text fragments, the first 25 characters are shown.

The cases when a diagram reference symbol, a diagram heading, or an Organizer document is an endpoint will result in duplication of information in the Entity Dictionary. To distinguish between such endpoints and the structure of Organizer documents, the following textual notations are used:

  • Link endpoints are listed using a plain font face.
  • Documents and other Organizer items that are not endpoints are listed using an italic font.
  • Endpoints that are diagram reference symbols contain the word "Reference" after the diagram type.
  • Endpoints that are diagram headings has the word "Heading", "Additional Heading" or "Extended Heading" as the entity type.

Figure 135 shows examples of these textual notations.

Operations in the Entity Dictionary

The Entity Dictionary window does not contain a menu bar. Operations are available as quick buttons or as popup menus.

Quick Buttons

The following quick buttons are special to Entity Dictionary window.

Close
Close the Entity Dictionary window.

Create Link
Create a link between the endpoint selected in the Entity Dictionary and the object selected in the parent editor. The quick button is dimmed if not two such selections are present. If the parent editor is a Text Editor, the selected text must be an already existing endpoint.
The Create Link dialog is opened; see Figure 138.

Insert
Insert the text in the selected symbol in the Entity Dictionary at the insertion point in the object selected in the parent editor. The quick button is dimmed if not two such selections are present. If text is selected in the parent editor's text window, this text is instead replaced.
This button is not available in the Text Editor's Entity Dictionary.

Replace
Replace the text content of the object selected in the parent editor with the text in the selected symbol in the Entity Dictionary. The quick button is dimmed if not two such selections are present.
This button is not available in the Text Editor's Entity Dictionary.

Undo
Undo the most recent text operation in the Entity Dictionary (Insert, Replace, Undo). The quick button is dimmed if the selection in the parent editor has changed to another object.
This button is not available in the Text Editor's Entity Dictionary.

Filter
Filter the information listed in the Entity Dictionary. See "The Filter Dialog" for more information.

Show Editor
Raise the parent editor window.

Popup Menus

The following tables lists the available operations in the popup menus of the Entity Dictionary window.

On the Window Background

Appears when no symbol is selected and the menu is invoked in an area not containing any symbols.

Expand All | Expands all collapsed symbols.
Collapse All | Collapses all symbols; only root symbols will be shown. Collapsed symbols are indicated with a small triangle directly below the symbol.
Show Editor | Raises the parent editor's window.

On a Document Symbol

Appears if an Organizer document symbol is selected, or the menu is invoked where a document symbol is selectable.

Expand | Expands a collapsed symbol one level down.
Expand Substructure | Expands the entire substructure of the symbol.
Collapse | Collapses the substructure of the symbol.

On an Endpoint Symbol

Appears if an endpoint symbol is selected, or the menu is invoked where an endpoint symbol is selectable.

Show Definition
Brings up an editor window, or the Organizer window, where the endpoint is selected.

Double-Clicks

If there is a selection in the parent editor and a symbol in the Entity Dictionary is double-clicked, the text of the symbol is inserted in the parent editor. A double-click thus corresponds to using the Insert quick button; see "Insert" . This functionality is not available in the Text Editor's Entity Dictionary.

The Filter Dialog

The Filter dialog is opened when the Filter quick button is pressed in the Entity Dictionary window. The Filter dialog controls what is to be shown in the Entity Dictionary window.

Figure 136 : The Filter dialog

  • Select endpoint types that should be
    This option menu controls whether the selected endpoint types should be hidden or shown. The possible endpoint types are shown in a multiple selection list, in which any number of items can be selected. If the option menu is set to shown, only the selected endpoint types are listed in the Entity Dictionary. If the option menu is set to hidden, the selected endpoint types are hidden, and the ones not being selected are thereby shown.
  • Show endpoints with filter
    This text field is a pattern for matching endpoint names. Only endpoints whose names match the pattern are shown in the Entity Dictionary. The string has the same syntax as a normal UNIX file pattern, and may contain the elements `*' (zero or more characters), `?' (exactly one character), and `[...]' (any character within the brackets).
    An empty text field matches any name, i.e. it is equal to a single `*'.
  • Organizer Structure
    This option controls whether the documents making up the Organizer structure are shown. If not set, only endpoints are listed in the Entity Dictionary.
  • Diagram type name
    This option controls whether the diagram type names in the Organizer structure are shown. If not set, only the names of the diagrams are shown in the Entity Dictionary.
  • Endpoint type names
    This option controls whether the endpoint type names are shown. If not set, only the names of the endpoints are shown in the Entity Dictionary.
  • Default
    Resets the Filter dialog to its default settings, but does not close the dialog. The default settings are:
    • The endpoint type list contains no selection.
    • The endpoint type option menu is set to hidden.
    • The endpoint name filter is empty.
    • The three Show options are set.


Link Commands in the Tools Menus

This section describes the link-related commands that are available in the Link submenu in the Tools menu of the Organizer and all SDL suite editors.

Note:

None of these commands are possible to Undo.
The Organizer only supports a subset of the link commands.

The Link submenu contains the following menu choices:

  • Link > Create
  • Link > Create Endpoint
  • Link > Traverse
  • Link > Link Manager
  • Link > Clear
  • Link > Clear Endpoint

Link > Create

This menu command creates a link between the object selected in the editor and the object selected in the Entity Dictionary. If two such objects are selected, the Create Link dialog is opened (see Figure 138). The editor object does not need to have a link endpoint defined to be able to create a link, i.e. only one of the objects need to be present in the Entity Dictionary. It is possible to create a link to itself.

Note:

In the Text Editor, the selected text must already be a link endpoint. It is not possible to create links to text that is not an endpoint.

If no object is selected in the editor, or no endpoint is selected in the Text Editor, the menu command is dimmed.

If no object is selected in the Entity Dictionary, or the Entity Dictionary has not been opened, a warning dialog is issued (see Figure 137) and the Entity Dictionary window is opened or raised. When the dialog is closed and the instructions given in it are followed, the Create Link dialog is opened.

Figure 137 : The Create Link warning

The Create Link dialog looks like this:

Figure 138 : The Create Link dialog

  • Link <editor object> to/from <entity dictionary object>
    The two selected objects are listed at either side of the to/from radio buttons. The radio buttons control which of the objects that is to be the logical to and from object. Link to is the default.
  • Link name
    The name of the link. A name can be entered or edited in the text field, or be selected from the associated option menu. The five latest used link names when creating links will be available in the option menu, and the name in the text field is preset to the latest used link name. A link name must be specified.
  • Link comment
    An optional comment text, to be provided by the user. The text box is initially empty.
  • Create
    Creates a link between the two objects. The link will be visible in the Link Manager and the endpoint objects are marked as being an endpoint with at least one link, i.e. if the editor object was not already an endpoint, it will be created.

If the Entity Dictionary window was opened because of the Create Link command, it will stay up until the user explicitly closes it.

Link > Create Endpoint

This menu command defines the currently selected object as a link endpoint. The endpoint is immediately added to the Entity Dictionary and the Link Manager. The object is marked as a link endpoint in the invoking tool - an editor or the Organizer. (See "Visualization of Endpoints and Links" .)

This command is dimmed if not exactly one object that can be defined as a link endpoint is selected, or if the object already is an endpoint.

This command is also available in the popup menus of all editors and the Organizer.

Link > Traverse

This menu command traverses an existing link from the currently selected object. This is done by opening the tool where the other link endpoint is defined (an editor or the Organizer) and selecting the other endpoint object.

This command is dimmed if more than one object is selected, or if the selected object has no links defined.

This command is also available in the popup menus of all editors and the Organizer, as Traverse Link.

If there is only one link defined from the object, that link is traversed, as described above. If more than one link exists, a dialog showing all links is opened and one of the links has to be selected.

Figure 139 : The Traverse Link dialog

The dialog presents a list of all links to and from the object in the following form:

From | To <type and name of linked object>, <file name>

The type and name of the linked object follow the same notation as in the Entity Dictionary; see "Textual Notation" . The file name of the document where the linked object is found contains a path if the file is not in the Organizer's Source Directory.

  • To traverse a link, select the link and click the Traverse Link button, or double-click the link.

Link > Link Manager

This menu command opens or raises the Link Manager window. If exactly one object is selected and this object is a link endpoint, this endpoint will be selected and made visible in the Link Manager. This command is never dimmed.

For more information about the Link Manager, see "The Link Manager" .

Link > Clear

This menu command removes one or more links to or from the currently selected object. However, the link endpoints are preserved. This command is dimmed if more than one object is selected, or if the selected object has no links defined.

Caution!

Removing a link cannot be undone.

A dialog showing all links is opened and one or more of the links has to be selected.

Figure 140 : The Clear Link dialog

The links to and from the object are listed in the following form:

From | To <type and name of linked object>

The list of links is a multiple selection list, in which one or more links can be selected. When a selection is made in the list, the Clear button becomes active.

To remove links, select the links in the list and click the Clear button. A link is removed from both endpoint objects, but the link endpoints themselves are not removed. If either of the endpoint objects had only this link defined, and no others, the mark of the object changes to indicate that the object is only an endpoint with no links defined. For information on how to remove an endpoint, see "Link > Clear Endpoint" (below).

Link > Clear Endpoint

This menu command removes the link endpoint from the currently selected object, and subsequently all links connected to the endpoint.

This command is dimmed if more than one object is selected, or if the selected object is not an endpoint.

If the selected object has no links connected to the endpoint, the endpoint is removed without further user interaction. The endpoint is removed from the Entity Dictionary and the Link Manager. The object is no longer marked as a link endpoint in the invoking tool (an editor or the Organizer).

Note:

In the Text Editor, this command can also be used to reduce the extent of an already existing endpoint. If the selection only indicates a partial range of the endpoint, at the start or end of the endpoint, a dialog will appear allowing you to choose whether to remove the entire endpoint, or just remove the selected part of the endpoint from the selection.
If a partial range in the middle of the endpoint text is selected, the only possibilities are to remove the entire endpoint or cancel the operation.

If the selected object has one or more links connected to the endpoint, a warning dialog is opened, since the operation of removing a link cannot be undone:


The Paste As Command

The command Paste As is available in the Edit menu of the Organizer and in the SDL suite editors (except for SC or HMSC diagrams).

The Paste As command is used to paste a copied object as another object, and at the same time create an implementation link between the copied and pasted objects. It is also possible to paste a cut object, but in this case no link can be created.

It is possible to paste the object into an editor different from the one the object was copied from. This requires a transformation of the object according to the user's choice.

Paste As supports the SOMT method, which governs the possible transformations for a particular object. See the SOMT Methodology Guidelines in chapters 68-76 in the User's Manual, for information and advice on when to use a particular transformation.

Note:

The normal Paste command in the Edit menu is very different from Paste As. A normal paste can only be performed in the same editor as the object was copied from, and the pasted object is as far as possible an identical copy of the object.

The Paste As Process

The process of using Paste As consists of the following steps:

  1. Copy (or cut) an object to the clipboard.
    A single object is selected and copied to the clipboard by using the Copy command in the Edit menu of the editor. The Paste As command supports the following objects being copied:
    • A class symbol in an OM Editor.
    • An object symbol in an OM Editor.
    • A text fragment in a Text Editor that either contains no endpoints or exactly matches an endpoint.
      It is thus not possible to use Paste As with copied SDL or MSC symbols, or with Text symbols copied in an OM Editor.
  2. Paste the object using Paste As.
    In the desired editor or the Organizer, the Paste As command is selected from the Edit menu. The menu choice is dimmed if:
    • More than one object was copied.
    • An object different from the list above was copied.
    • The copied object cannot be pasted into the tool, i.e. there is no transformation defined for this particular object-tool combination. The possible transformations are listed in "Transformation Scheme" .
      After selecting the menu choice, the Paste As dialog is opened. See "The Paste As Dialog" .
  3. Select the type of object to paste the copied object as.
    In the Paste As dialog, the possible resulting object types are listed in an option menu. The object types listed reflects the transformations possible for this particular copy-paste situation. If the desired object type is not present in the list, the user may have to change which object is being copied, the editor where the paste is made, or (for the SDL Editor) the type of SDL diagram being pasted into.
  4. Select the type of link to create, if any.
    In the Paste As dialog, it is possible to change the default of creating an "Implementation Link" between the copied and pasted objects. See "The Link Info Dialog" . If the object was cut instead of copied, no link can be created.
  5. Place the pasted object.
    If the pasted object is a graphical symbol, a "floating" symbol must be placed with the mouse in the usual way, and the paste can be cancelled by pressing <Esc>. If the pasted object is a textual description or an Organizer document, the object is placed at the text cursor or the current selection.
  6. Edit the pasted object, if needed.
    The results of the object transformation may not be complete or accurate. The user may need to change the pasted object to achieve the desired result.

The Paste As Dialog

The Paste As dialog is opened when Paste As is selected from the Edit menu.

Figure 141 : The Paste As dialog

  • Paste <copied object> as
    The option menu contains all possible types of objects that can be created in the current situation; in some cases, only a single alternative is available. A default object type is pre-selected. The possible object types and the default are presented in "Transformation Scheme" .
  • Create link from copied object to pasted object
    This option controls whether a link is to be created between the copied and pasted objects. This is by default set, and the link will always be made from the copied object to the pasted object. If the object was cut instead of copied, this option is dimmed.
  • Link name: <link name>
    States the name of the link to create, and is only valid if the Create link option is set. By default the link name is "Implementation Link", but this can be changed in the Link Info dialog; see below.
  • Paste As
    Closes the dialog, creates an object of the selected type, pastes it in the invoking tool (the Organizer or an editor), and optionally creates a link. In graphical editors, pressing <Esc> cancels the paste.
  • Link Info
    Brings up the Link Info dialog (see below), where the attributes of the link can be changed before it is created. This button is dimmed if the Create link option is dimmed or not set.

The Link Info Dialog

The Link Info dialog is opened when the Link Info button is pressed in the Paste As dialog.

Figure 142 : The Link Info dialog

  • Link name
    An editable text field specifying the name (type) of the link to create. The name is preset to "Implementation Link". The five latest used link names when creating links is available in the Select option menu. Selecting a name from this menu inserts the name into the text field.
    The link name text field must not be empty.
  • Link comment
    An optional comment text to be provided by the user. The text in the comment field is initially empty. The comment associated with a link can only be viewed and changed later on by using the Link Manager.

Transformation Scheme

The table below presents all the possible object type combinations for the copied and pasted object in the Paste As operation. The preselected choice shown when the Paste As dialog is opened is shown in bold face.

Copied object | Paste As in OM Editor | Paste As in SDL Editor | Paste As in MSC Editor | Paste As in Text Editor | Paste As in Organizer
Class (in OM Editor) | Class Object | System Type Block Type Block Process Type Process Service Type Service Text symbol with NEWTYPE Text symbol with SDL interface | -- | C++ class C struct IDL Module IDL interface ASN.1 sequence | System
Object (in OM Editor) | Class Object | Block instance Process instance Service instance | -- | -- | System
Text fragment (in Text Editor) | Class Object | -- | Instance Message | Text fragment | MSC

Note:

Not all object types are possible to Paste As in all situations. Especially in the SDL Editor, the available object types depend on which diagram type the Paste As is performed in.

Transformation Details

The details of the specific object transformations are described in the following subsections. Please refer to the above table to see which tools that support a particular object transformation.

Some general transformation details are:

  • The name of a copied symbol can be empty. When pasted as an SDL diagram, the name "EmptyName" will be used.
  • In SDL diagrams, if the name used for a pasted symbol will be in conflict with an already existing name, the pasted name will be the original name suffixed by "_<number>". For example, if "Name" already exists for a reference symbol in an SDL diagram, the pasted symbol will have the name "Name_1". The number is incremented until the name is unique.
  • The size of the pasted SDL, MSC and OM symbols are the same as when a symbol is manually picked from the editor's symbol menu.
  • The exact layout of generated diagrams may not be depicted correctly in the following illustrations. Only the upper left part of a diagram is shown.

Pasting an OM Class

An OM class may be represented and defined by several class symbols in the OM diagrams. This is the case if more than one class symbol with exactly the same class name is found within the OM scope (the diagram itself or the diagrams in the same Organizer module).

When an OM class is pasted, all class symbols defining the class in the scope are considered. It is the combined set of attributes and operations in the class symbols that will be used in the transformation to the pasted object.

In the following descriptions of object transformations, we use the two class symbols shown in Figure 143 (within the same scope) as a generic example. Regardless of which class symbol is copied, both class symbols are considered in the transformations.

Figure 143 : Two class symbols in the same scope

Note:

Even if there are more than one class symbol in the scope, only the copied symbol will be linked with the pasted object (if a link is created). Links are not created for the other symbols in the scope.

Paste As object, with description
Resulting objects and diagrams
Class symbol

The pasted class is simply a copy of the merged class.

Object symbol

The pasted object contains the merged attributes of the class. The object is named `a' followed by the class name.

System Type diagram
Block Type diagram
Block diagram

In these cases, only a reference symbol is created, not any contents of the diagram.

Process Type diagram
Service Type diagram

A reference symbol is created, as well as the referenced diagram with some contents.
The keyword "{async}" after an operation means that it will be transformed using a signal interface. A gate named `G' followed by the class name, and a signal list named "SL" followed by the class name, is added.
The keyword "{sync}" after an operation means that it will be transformed using an RPC interface. The procedure diagram is created with an additional heading symbol containing FPAR and RETURNS statements for parameters and return type.
If no keyword is given, signal interface is the default for operations without return value, and RPC interface is the default for operations with return value.

NOTE: Text symbols containing the declarations of the signal list and the remote procedures must be created by a separate Paste As operation, usually in a diagram at a higher level. See "Text symbol with SDL interface" (below).

Process diagram
Service diagram

The same transformation as for process type and service type, but the signal interface is added as a SIGNALSET statement in the additional heading symbol.

NOTE: Text symbols containing the declarations of the signal list and the remote procedures must be created by a separate Paste As operation, usually in a diagram at a higher level. See "Text symbol with SDL interface" (below).

Text symbol with SDL interface

A text symbol is added, containing declarations for the signal list and/or remote procedures, as described for process type and service type above.

Text symbol with NEWTYPE

A text symbol is added, containing a NEWTYPE definition. Operator diagrams are added for all operations, with additional heading symbols containing FPAR and RETURNS statements for parameters and return type.
If an operation does not have parameters, a parameter is inserted with the class name as type. The class name is also used as return type if an operation does not specify any.

System diagram

In the Organizer, the system diagram is added in the same way as for the Add New operation, i.e. the diagram is added as a new root diagram at the current selection. The diagram is also opened in the SDL Editor.

C++ class definition

The link to the class definition is inserted inside a C++ comment.

 // class ClassName
 class ClassName {
 public:
   void Oper1();
   ReturnType Oper2(T1 P1);
   void Oper3(T1 P1, T2 P2);

 private:
   Attr1;
   Type Attr2;
 };
C struct definition

The link to the struct definition is inserted inside a C comment.

 /* struct ClassName */
 typedef struct {
   Attr1;
   Type Attr2;
 } ClassName;

 void Oper1(ClassName *);

 ReturnType Oper2(ClassName *,
                  T1 P1);

 void Oper3(ClassName *,
            T1 P1, T2 P2);
IDL module

Only the class name is used.
The link to the module is inserted inside an IDL comment.

 // module ClassName
 module ClassName {
 };
IDL interface

Operations marked with keyword "{async}" will get the string oneway void inserted before the name of the operation.
The link to the interface is inserted inside an IDL comment.

 // interface ClassName
 interface ClassName {
   attribute Attr1;
   attribute Type Attr2;

   oneway void Oper1();
   ReturnType Oper2(T1 P1);
   oneway void Oper3(T1 P1,
                     T2 P2);
 };
ASN.1 sequence

The link to the sequence is inserted inside an ASN.1 comment.

 // ClassName SEQUENCE
 ClassName ::= SEQUENCE {
   Attr1,
   Attr2 Type
 }

Pasting an OM Object

In a similar way as when pasting an OM class, all object symbols of exactly the same class in the scope are considered. It is the combined set of attributes in the object symbols that will be used in the transformation to the pasted object.

In addition, the class that the object is an instance of is also considered, if it exists. That is, it is the combined set of attributes and operations in the class symbols and the objects symbols that will be used in the transformation.

In the following descriptions of object transformations, we use the object symbol shown in Figure 144 as a generic example. In addition, the object is assumed to be located in the same scope as the two class symbols shown in Figure 143.

Figure 144 : An Object symbol

Paste As object, with description | Resulting objects and diagrams
Class symbol The pasted class uses the class name, attributes and operations from the copied object and the object's class symbols. |
Object symbol The pasted object uses the name and attributes from the copied object and the object's class symbols, but without attribute values. |
Block instance diagram Process instance diagram Service instance diagram The pasted diagram becomes an instance diagram (indicated in the Organizer). |
System diagram Works in the same way as when pasting an OM class. The name of the diagram will be "Object : ClassName". | See "System diagram" .

Pasting a Text Fragment

In the following descriptions of object transformations, we use the text fragment "Text Fragment" as a generic example.

Note:

The copied text fragment must either contain no endpoints, or exactly match an existing endpoint in the text. If the text fragment contains both endpoint text and non-endpoint text, it cannot be used for Paste As.

Paste As object, with description
Resulting objects and diagrams
Class symbol

Syntax check is performed on the class name.

Object symbol

Syntax check is performed on the object name.

Text fragment

The pasted text is simply a copy of the copied text.

 Text Fragment
MSC instance
MSC message out
MSC message in

The two message types place the endpoint at different ends of the message line.

MSC diagram

In the Organizer, the MSC diagram is added in the same way as for the Add New operation, i.e. the diagram is added as a new root diagram at the current selection. The diagram is also opened in the MSC Editor.


Other Edit Commands

Some of the commands in the Edit menu in the editors are affected when operating on objects that have endpoints with connected links.

Pasting an Object

If objects with endpoints are cut or copied, the endpoints and any existing links to the objects are saved in the clipboard.

When pasting (by using the ordinary Paste command) an object with an endpoint, but without connected links, the endpoint is pasted together with the object without further user interaction.

When pasting objects that also have links connected to their endpoints, the following dialog appears:

Figure 145 : The Paste dialog

  • The Yes button pastes the objects and keeps the links. An object having connected links will be pasted with new links created between the pasted object and the objects the original object was linked to.
  • The No button pastes the objects without endpoints and links. No pasted objects will have any endpoints or connected links.

Deleting an Object

If you delete an object that has links, the link information will be destroyed and cannot be restored. Therefore, when you want to cut or clear objects with links, a warning dialog will be issued where it is possible to cancel the operation.


The Link Manager

The Link Manager manages endpoints and links in a system. The Link Manager handles the link file, containing information about the endpoints and links in a system. The syntax of the link file is described in "The Link File" .

For an overview of link concepts, see "Link Concepts and Overview" . In addition, the following concepts are used in the Link Manager:

  • Entity
    A collection of endpoints with the same type and name in the same scope is called an entity. The scope is defined as the file the endpoint resides in. If the file is in an Organizer module, the scope is the module.
  • Cardinality
    The number of links associated with an endpoint, i.e. the total number of links going to and from the endpoint.

Link Manager Window

The Link Manager's window is shown in Figure 146. The window title contains the name of the loaded link file, and is appended by an asterisk `*' if the link file is modified.

In the window, the endpoints in the system are presented graphically using icons. The links between the endpoints are represented as lines between them, with an arrow stating the direction of the link. The Link Manager can present different views of the endpoint/link information; these are described in "Presentation Views and Link Trees" .

Figure 146 : The Link Manager window

At the top of the drawing area, the name of the current link file is presented under a "Information from" heading. If several link files are merged, they are all listed here until the next Save operation. If a local link file is used (see "Local Link File" ), both the master link file (read only) and the local link file are listed.

If the information in the Link Manager is not yet saved, "on-line editing" will be displayed to indicate that endpoints have been created in an editor or in the Organizer.

The main part of the drawing area displays all endpoints and links as link trees. Every endpoint is a root node, and the associated links and endpoints are added to that root. Link trees can be collapsed, and endpoints and links can be hidden.

Below the link trees, some statistics are presented under a "Statistics" heading. The number of endpoints and links is displayed, including the number of hidden endpoints and links, as in the following example:

Statistics:
10 endpoints (2 not shown)
4 links (1 not shown)

Endpoint Icons

The Link Manager uses the same icons for endpoints as the Entity Dictionary. See "Entity Icons" for more information.

The icons can have different layouts indicating the state of the associated endpoint:

Normal
The normal state of the icon. Information is not modified.

Invalid
An endpoint is marked invalid if, after a Check Endpoints operation, it is not present in the document where it was supposed to be.

Dirty
The endpoint is modified or newly created from an editor, but the link file is not yet saved.

Dashed
The endpoint is already displayed on a higher level in the same tree, or it belongs to the TO group after a Consistency Check.

The endpoints are added as new root symbols below the last link tree as they are created. The order of the icons can be changed by using the quick buttons Move Down and Move Up.

Presentation Views and Link Trees

The Link Manager has two main methods of displaying endpoints, using an Endpoint view or an Entity view. There is also a Consistency view, used for presenting the results after a consistency check has been performed (see "Consistency Check" ). When there is no selection in the drawing area, the name of the currently displayed view is shown in the status bar.

In Endpoint view, a link tree looks like this:

Figure 147 : Link tree in Endpoint view

To the right of each endpoint icon, the following information identifying the endpoint is displayed (depending on the options set in Options > Endpoint):

  • The endpoint type, i.e. the type of the endpoint object.
  • The name of the endpoint, in a plain type face. For endpoints containing a name, such as diagram symbols, this name is listed. For other symbols and text fragments, the first 25 characters are shown.
  • The file the endpoint resides in. The file name is shown with or without its absolute path depending on the setting in the Organizer.
  • The link cardinality; the number of "out" links followed by the number of "in" links.
  • The number of hidden links, if any, within parenthesis.

For each link in a link tree, the name of the link is displayed above the endpoint information, in bold face. The link name display can be switched on or off by the menu choice Options > Link.

The link comment, if it is used, is shown directly below the link name, in italics. The comment display can be switched on or off by the menu choice Options > Link.

In Entity view, all endpoints representing the same entity are collected into one symbol, and the number of endpoints represented by that entity is presented to the right of the name of the entity, preceded by an asterisk `*'. Also, instead of displaying the filename the endpoint resides in, the scope the entity resides in is displayed. The scope is either a filename or a module. An example of an endpoint in Entity view:

Figure 148 : An entity in Entity view

Link Manager operations on endpoints also apply to entities. If there is a difference in the behavior of a menu choice depending on the view, this will be pointed out in the descriptions of the operations.

Double-Clicks

Double-clicking on an icon invokes the menu choice Show in Editor. In Entity view, if the selected entity corresponds to several endpoints, they will be selected one at a time for each double-click.

Menu Bar

This section describes the menu bar of the Link Manager window and all the available menu choices.

The menu bar contains the following menus:

  • File Menu
  • Edit Menu
  • View Menu
  • Tools Menu
  • Help Menu
    (see "Help Menu" ).

File Menu

The File menu contains the following menu choices:

  • New
  • Open
  • Merge
  • Save
  • Save As
  • Print
  • Close

The menu choices are described in "File Menu" , except Print, which is described in "The Print Dialogs in the SDL Suite and in the Organizer" , and Merge, which is described below.

Merge

This menu choice opens an existing link file, and merges the contents of that file with the information already in the Link Manager. It works in a similar way to Open, but keeps the current endpoint and link information.

If two links are equal (i.e. they have the same source and destination endpoints and the same name) but they have different link comments, the new comment will consist of the old comments separated by a newline character.

Edit Menu

The Edit menu contains the following menu choices:

  • Highlight Endpoint
  • Replace Endpoint
  • Create Link
  • Link Details
  • Clear Link.

Highlight Endpoint

This menu choice highlights an endpoint. Highlighting an endpoint is the first step to replace an endpoint or create a link. The highlighting is presented as a frame around the highlighted endpoint.

The first time this menu choice is used, the selected endpoint will be highlighted. The second time this menu choice is used for the same endpoint the highlighting will be removed. There is at most one highlighted endpoint. If another endpoint already was highlighted, the highlighting is moved to the selected endpoint.

Replace Endpoint

This menu choice replaces an endpoint with another endpoint. This operation is useful if an endpoint has become Invalid and the user has found a replacement endpoint that all links should be moved to.

One endpoint is defined with the Highlight Endpoint menu choice, the other endpoint is defined by the selection.

All links going to or from the replaced endpoint will be updated to go to or from the other endpoint instead. If the replaced endpoint was invalid, the user is given the option to delete the replaced endpoint.

The following dialog appears:

Figure 149 : The Replace Endpoint dialog

  • Replace highlighted <endpoint>
  • Replace selected <endpoint>
    Depending on the setting of the radio button, either the highlighted or the selected endpoint will be replaced.
  • Move links going to/from
    These options are used to select if links going to the replaced endpoint, or links going from the replaced endpoint, will be moved.
  • Delete replaced and invalid endpoint
    If the endpoint to be replaced is invalid, it can optionally be deleted. If any links going to the deleted endpoint are not moved, they will also be deleted.

Create Link

This menu choice creates a link between the highlighted endpoint and the selected endpoint.

One endpoint is defined with the Highlight Endpoint menu choice, the other is defined by the selection.

The Create Link dialog appears, see Figure 138.

Link Details

This menu choice displays information about the link above the selected endpoint; the name, the comment, and the direction of the link. All these attributes can be edited.

The following dialog appears:

Figure 150 : The Link Details dialog

The dialog works in the same way as the Create Link dialog, see Figure 138.

Clear Link

This menu choice clears (deletes) the link above the selected endpoint. Only the link will be cleared, not the associated endpoints. You will be asked to confirm or cancel the deletion.

View Menu

The View menu contains the following menu choices:

  • Expand
  • Expand Substructure
  • Collapse
  • Options > Window
  • Options > Link
  • Options > Endpoint
  • Filter
  • Set Scale.

Expand

This menu choice expands the endpoint structure tree one level down for the selected endpoint. If any endpoints one level down are hidden, they will still be hidden after this operation. (Use the Filter menu choice to show or hide endpoints).

The menu choice is dimmed if:

  • No endpoint is selected
  • The selected icon is a leaf (no children icons)
  • The selected icon is already expanded

Expand Substructure

This menu choice expands the endpoint structure tree the whole way down for the selected endpoint. If there is no selection, all endpoint trees will be expanded.

Collapse

This menu choice collapses the selected endpoint, i.e. the sub symbols are not shown after this operation. A collapsed endpoint has a small triangle drawn below the icon to indicate that it is collapsed. If there is no selection, everything will be collapsed.

Options > Window

This menu choice sets options for controlling the appearance of the Link Manager window.

The following dialog appears:

Figure 151 : The Window Options dialog

  • Show: Tool Bar
  • Show: Status Bar
    These options control whether the tool bar and the status bar should be displayed or not.
  • Show: endpoints/entities
    By using this radio button, Endpoint or Entity view is selected (see "Presentation Views and Link Trees" ).

Options > Link

This menu choice sets options for controlling the appearance of links in the drawing area.

The following dialog appears:

Figure 152 : The Link Options dialog

  • Show: Name
    Show/hide the name of all links.
  • Show: Comment
    Show/hide the comment for all links.
  • Links: reverse first/forward first
    This setting controls whether links going to a root endpoint (reverse first) or links going from a root endpoint (forward first) will be displayed first in the link trees.

Options > Endpoint

This menu choice sets options for controlling the appearance of endpoints in the drawing area.

The following dialog appears:

Figure 153 : The Endpoint Options dialog

  • Show: Type
    Show/hide the type of the endpoints.
  • Show: File
    Show/hide the file name (or module) of the endpoints.
  • Show: Cardinality
    Show/hide the cardinality, i.e. the number of links going to and from an endpoint.
  • Show: Not shown links
    Show/hide the number of hidden links going to and from an endpoint.

Filter

This menu choice is used for filtering out endpoints and/or links which will not be shown. The filter is set in a modeless dialog, i.e. the Link Manager continues working without waiting for the dialog to be closed.

If an endpoint is hidden, all links associated to it will be hidden. If a link is hidden, the endpoints associated to it will still be visible.

The following dialog appears:

Figure 154 : The Filter dialog

  • Filter settings for links/endpoints/documents
    By using this option menu, filtering can be done on endpoint types, link names, and document file names. All filters are active simultaneously, i.e. for the filter to take effect, all three filter conditions must be true.
    The multiple-selection list in the dialog contains all link names, endpoint types or file names in the loaded link file, depending on the current setting of the option menu. By default, nothing is selected.
  • Select <type of filter> that should be hidden/shown
    Depending on this option menu choice, the selected links/endpoints/documents will either be hidden or shown.
  • Hide not linked endpoints
    If this option is set, all endpoints which are not linked will be hidden. This option is dimmed if filtering is not done on endpoint types.
  • Pressing Default will set all the lists to their default values, but the filter is not applied until Apply is pressed.

Set Scale

Issues a dialog where the scale may be set.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
    (see "Show Organizer" )
  • Search
  • Search Again
  • Consistency Check
  • Check Endpoints
  • Show in Editor.

Search

This menu choice searches for a text string in endpoints or links.

The searching is based on ASCII character matching. All texts related to the endpoints and links are searched, i.e. endpoint types and names, link names and comments.

The search will start from the selected endpoint, or from the first endpoint if nothing is selected.

The following dialog appears:

Figure 155 : The Search dialog

  • Search for
    The text string to search for. If a search already has been done, the previous search text is used by default.
  • Ignore Case/Consider case
    Depending on the radio button setting, the search will either be case sensitive or not.

Search Again

This menu choice searches again for the same text string as the last performed search.

The menu choice is dimmed if a search has not yet been done.

Consistency Check

This menu choice is used for checking the consistency between a group of documents (the FROM group) and another group of documents (the TO group).

In Entity view, there are two types of consistency checks to choose from. The following dialog appears:

Figure 156 : The Link Check/Entity Match dialog

  • Link check
    Check that all endpoints/entities in the FROM group are linked with at least one endpoint/entity in the TO group.
  • Entity match
    Check that all entities (not endpoints) in the FROM group has matching entities (not endpoints) in the TO group.

The above dialog is not opened in Endpoint view, in which case a link check always is performed.

First, the documents in the FROM group must be selected. The following dialog appears:

Figure 157 : Selecting the FROM group

In the list of Organizer documents and modules, one or several documents must be selected. Selecting/deselecting a module will select/deselect all the documents in that module. Selecting/deselecting an SDL system will select/deselect all documents in that system. Individual documents in the module/system can then be selected/deselected without affecting the other documents.

When all FROM documents are selected, the Continue button is used to close the dialog and continue to the next dialog.

Then, the documents in the TO group must be selected. The following dialog appears:

Figure 158 : Selecting the TO group

The list of Organizer documents and modules works in the same way as when selecting the FROM documents. When all TO documents are selected, the Check button is used to close the dialog and start the consistency check operation.

The result of the consistency check is presented as a special view in the drawing area. This Consistency view only shows endpoints/entities from the two defined groups of documents. Endpoints/entities from the FROM group are shown in the normal way, and endpoints/entities from the TO group are shown as Dashed symbols.

The Consistency view is only showing links going from the FROM group of entities/endpoints to the TO group. After a link check, the links shown are the "real" links, as defined by the user. After an entity match, the links shown are only temporary links created by the Link Manager to indicate matching entities. The link name for such links are "Matching" and the link comment is "(Temporary link)".

By selecting Endpoint or Entity view in Options > Window, the view will return to the selected normal view. By pressing the quick button Show Endpoints or Entities, the view will return to the previously used view.

Check Endpoints

This menu choice checks if there are endpoints in the Organizer or in the editors that do not exist in the Link Manager, or if there are invalid endpoints in the Link Manager. This menu choice could be used to remove any inconsistencies between the document endpoints in the system and the information in the Link Manager.

The information in the saved files is used for the checking, so if there are unsaved changes in an editor, these will not be taken into account in the checking. If there are any documents in the Organizer which have not been saved, the following dialog appears:

First, the Organizer and all documents in the system are checked. The following dialog appears:

Figure 159 : The first Check Endpoints dialog

In the upper multiple selection list, all endpoints that were found in the Organizer, but do not exist in the Link Manager, are listed. In the lower multiple selection list, all endpoints that were found in the documents belonging to the system, but do not exist in the Link Manager, are listed. It is possible to select one or more of the endpoints in the lists, with the purpose of adding them to the Link Manager.

  • Continue
    Closes the dialog and continues to the next dialog. Any selected endpoints are not added to the Link Manager.
  • Add
    Adds the selected endpoints to the Link Manager. The dialog is not closed until the Continue button is pressed.

Then, the endpoints in the Link Manager are checked. If any non-existing endpoints are found, they will be marked as Invalid. The following dialog appears:

Figure 160 : The second Check Endpoints dialog

In the upper multiple selection list, all Link Manager endpoints which reside in files that have been deleted are listed. In the lower multiple selection list, all Link Manager endpoints that no longer are present in the files they are supposed to be in are listed. It is possible to select one or more of the endpoints in the lists, with the purpose of deleting them from the Link Manager.

  • OK
    Closes the dialog and returns to the main window. Any selected endpoints are not deleted from the Link Manager.
  • Delete
    Deletes the selected endpoints from the Link Manager. The dialog is not closed until the OK button is pressed.

Show in Editor

This menu choice will show the symbol which corresponds to the selected endpoint in an editor.

In Entity view, each entity can represent more than one endpoint. In that case, the menu choice will be replaced by Show 1 in Editor, Show 2 in Editor, etc.

If there are more than nine endpoints, the menu choice Show in Editor will invoke the following dialog, where it is possible to select the appropriate endpoint:

Figure 161 : The Show in Editor dialog

Popup Menus

There are two popup menus available in the Link Manager:

On Endpoints

Highlight Endpoint | "Highlight Endpoint"
Replace Endpoint | "Replace Endpoint"
Create Link | "Create Link"
Link Details | "Link Details"
Clear Link | "Clear Link"
Expand | "Expand"
Expand Substructure | "Expand Substructure"
Collapse | "Collapse"
Show in Editor | "Show in Editor"

On the Background

Consistency Check | "Consistency Check"
Check Endpoints | "Check Endpoints"
Expand Substructure | "Expand Substructure"
Collapse | "Collapse"
Options > Window | "Options > Window"
Options > Link | "Options > Link"
Options > Endpoint | "Options > Endpoint"
Filter | "Filter"
Search | "Search"
Search Again | "Search Again"
Show Organizer | "Show Organizer"

Keyboard Accelerators

In addition to the standard keyboard accelerators, described in "Keyboard Accelerators" , the following accelerators can be used in the Link Manager:

Accelerator
Reference to corresponding command or quick button

 Ctrl+E
"Show in Editor"
 Ctrl+1
"Show Organizer"
 Del
"Clear Link"
 Arrow up
Select the endpoint one step up (move the selection)

 Shift+arrow up
"Move Up"
 Arrow down
Select the endpoint one step down (move the selection)

 Shift+arrow
down
"Move Down"

Quick Buttons

Except for some of the general Telelogic Tau quick buttons (see "General Quick-Buttons" ) the following quick buttons are included the Link Manager.

Show Endpoints or Entities
Switches between the Endpoint and the Entity views; see "Options > Window" .

Consistency Check
Performs a consistency check operation; see "Consistency Check" .

Highlight Endpoint
Highlights the selected endpoint; see "Highlight Endpoint" .

Create Link
Creates a link between the highlighted and the selected endpoint; see "Create Link" .

Switch Link Direction
Changes the order of the links going to or from the (root) endpoint; see "Options > Link" .

Show or Hide Unused Endpoints
Toggles between showing and hiding endpoints that are not linked; see "Filter" .

Move Down
Moves the selected (root) endpoint one step down in the Link Manager view.

Move Up
Moves the selected (root) endpoint one step up in the Link Manager view.


The Link File

The Link Manager maintains a link file that contains a list of all endpoints and links in the system. The link file is a line-oriented, human-readable text file, with the default file name extension .sli.

The file has the following format:

<link file> ::= <endpoints> <links> $

<endpoints> ::= [ENDPOINTS] <endpoint>*
<endpoint> ::= <endpoint id> <endpoint format>
<endpoint id> ::= <integer>
A unique integer identifying the endpoint in the link file.

<endpoint format> ::= `(' <format> , <file name>
(, <anchor> | $) `)' <name>
<type>
<format> ::= SDL | OM | MSC | TEXT | WORD

<file name> ::= <string>
Name of the document file.

<anchor> ::= <string>
A unique string identifying the endpoint in the document. If the endpoint refers to the whole file, i.e. the endpoint is created in the Organizer, the anchor is set to an empty string ("").

<name> ::= <quoted string>
The name of the endpoint, in quotes.

<type> ::= <integer>
Type of document.

<links> ::= [LINKS] <link>*
<link> ::= <endpoint id> <endpoint id> <link name>
<link comment>
<link name> ::= <quoted string>
The name of the link, in quotes.

<link comment> ::= <quoted string>
The link comment, in quotes.


11 The PostMaster

This chapter is a reference to the communication mechanism in the Telelogic Tau tools, the PostMaster. The functionality of the PostMaster makes it possible to integrate applications by using a well-defined means of communication.


Introduction to the PostMaster

Caution!

The PostMaster was originally designed and implemented for integrating tools in the SDL suite environment. Currently it integrates tools in the Telelogic Tau environment. Our experience is that the PostMaster is also suitable for integrating external tools and applications with the Telelogic Tau applications; one application area is for instance quick prototyping.

However, Telelogic does not support using the PostMaster as a communication mechanism between real-time applications, in a run-time environment.

The PostMaster is the mechanism used for communication between the different tools in Telelogic Tau. A C program generated by the Telelogic Tau tools can also take advantage of this communication mechanism. It can communicate with any application connected to the PostMaster that send messages according to a defined format. This makes it possible for an SDL simulator to communicate with, for instance, a user interface process for the Simulator.

The PostMaster also provides the basic means for the Open Telelogic Tau concept, see 12 The Telelogic Tau Public Interface.

The PostMaster provides the following functionality:

  • Starting an application and connecting to it
  • Letting an application connect itself
  • Letting an application send messages to a given recipient
  • Making a "broadcast" of a message.

The PostMaster is a message passing service based on a selective broadcasting mechanism. It will distribute a copy of each message it receives to the tools subscribing to that type of message. By this, the PostMaster provides an integration mechanism between tools without the hard coupling between them that follows from conventional two part communication mechanisms.

Figure 162 illustrates some of the PostMaster concepts. The PostMaster maintains a list of which messages each tool subscribes to. Each tool has a PostMaster part for sending and receiving messages. In the figure, tool F broadcasts a message, i.e. the message is sent to the PostMaster. The subscription lists of tool A and C (but not the lists of B and F) contains the message type. Accordingly the PostMaster broadcasts the message to tool A and C.

Figure 162 : Example of a PostMaster broadcast

The PostMaster configuration is a file that informs the PostMaster about what tools and messages exist in the current context, i.e. it contains the message subscription lists. To include new tools or add new messages, the configuration must be edited.

For detailed information on the configuration, see "The PostMaster Configuration" .


PostMaster Reference

This section describes the external interface to the PostMaster, including messages to send and their format, contents of the configuration, and functions to call.

Note:

In order to promote a high throughput, it is strongly recommended that the PostMaster messages are consumed as soon as they are available.

PostMaster Messages

The PostMaster configuration defines a large number of messages that can be utilized in a Telelogic Tau system. A broad range of these messages are public, that is, they can be used externally. A description of these are found in 12 The Telelogic Tau Public Interface.

All messages contain information about the identity of the sender, the time it was sent, the message type, and the size of an optional data part.

The optional data part can be seen as parameters to the message and is not interpreted by the PostMaster.

Note:

It is the responsibility of the tools using the PostMaster to define the format of the data part and to interpret it correctly.

The PostMaster Configuration

The PostMaster can be configured either statically at start up or dynamically during runtime. When a dynamic configuration is performed, the services Add Tool or Add Tool Subscription is used. The PostMaster is configured statically using the PostMaster configuration file(s)

The PostMaster configuration file(s) informs the PostMaster about what tools and messages exist in the current context. These files are often referred to as simply the configuration.

At start-up the PostMaster reads an environment variable POSTPATH which is a list of directories separated by colons (on UNIX) or semicolons (in Windows). In these directories, the PostMaster searches for configuration files.

Such files should be named post.cfd and are read by the PostMaster whenever it is invoked, for instance when the SDL suite or the TTCN suite is started.

It is not possible to use C preprocessor statements or symbols in the configuration file.

Caution!

The file post.cfd residing in $telelogic/sdt/bin and
$telelogic/itex/bin (on UNIX), or in the Telelogic Tau installation directory (in Windows), defines the existing tools in the environment and must not be edited; otherwise unpredictable behavior may occur.

It is possible to have local configurations which extends the standard PostMaster configuration set up by the Telelogic Tau tools, by simply defining the POSTPATH variable with a directory holding the extended configuration.

File Contents and Syntax

The configuration is a list of tool identities. Each tool identity is bound to an executable, a subscription list of messages and optionally a limit of instances of that tool. Each tool in the file is described in the following way:

Tool <tool number>:<executable>:<instance limit>
<message number>;
<message number>;
...

Description

  • <tool number>
    is an integer defined by SET_ symbols in the file sdt.h, and by IET_ symbols in the file itex.h. The number 27000 (SET_SDLENV) is used for tools acting as an SDL environment.
  • <executable>
    is the name of the executable file associated with the tool. It is used by the PostMaster after receiving an SESTART message when a tool is to be started.
    A file path may prefix the filename of the executable in order to explicitly tell where to find the tool. In this case the complete file description (path + filename) should be surrounded by a pair of quotes (i.e. "/home/sdt/demo/demotool" (on UNIX) or "c:\sdt\demo\demotool" (in Windows)).
  • <instance limit>
    is the maximum number of concurrent running instances of the tool. It may be wildcarded with a `*' to a default value (SPMAXNOOFINSTANCES).
  • <message number>
    is an integer defined by the symbols starting with SE in sdt.h. It is normally specified as <tool number> + <nr>. Symbols which are used in the TTCN suite have the prefix IE and are defined in itex.h.

Adding Tools and Messages

To include new tools or add new messages, the configuration file must be edited. However, the tools and subscription lists existing in the original configuration must not be changed.

To include a new tool, follow the steps below. Note that it is not required to include a new tool in the configuration if it only serves as an SDL/TTCN environment that does not need to be started from other tools by using the Start service.

  1. Select a tool number not conflicting with the ones already existing in the configuration, preferably a number greater than 100,000. The number chosen must be equally divisible by 1,000.
  2. Make a new tool description in the configuration, using the syntax described above.
  3. Define a new SET_ (IET_) symbol in the file sdt.h (itex.h) so that the tool number can be easily accessed in the code.

Example 24

#define SET_MYTOOL 110000

To add a new message, follow these steps:

  1. Decide upon a tool that the new message "belongs to" or "is defined by," which should not be one of the pre-defined tools in the original configuration.
  2. Define a new SE (IE) symbol in the file sdt.h (itex.h) as the tool symbol plus an ordinal number, not conflicting with any other message symbol.

Example 25

#define SEMYMESSAGE SP_MESSAGE(SET_MYTOOL+1)

  3. Use the numeric value of the message symbol when adding the new message to a subscription list in the configuration.

Example 26

110000+1;

Environment Variables

The PostMaster recognizes a number of environment variables setting the context in which the PostMaster is to operate. They are read when the PostMaster starts.

PostMaster Environment Variables

The following environment variables are recognized by the PostMaster:

  • POSTPORT
    UNIX only: Should be set to a valid TCP port number. Causes the PostMaster to try to listen to this port number for possible connections. Makes it possible to connect applications running on other hosts than the PostMaster is running on. Is used in combination with the client side environment variables POSTHOST and POSTPORT.
  • POSTPATH
    A list of directories separated by colons (on UNIX) or semicolons (in Windows), where to search for configuration files named post.cfd.
  • POSTDEBUG
    If set, the PostMaster will log active tools and sent messages as an MSC log. The environment variable takes two optional parameters. The first tells the filename to put the log on. If the parameter is set to '-e' the log is put on stdout. The second parameter tells the log level. Normally only public messages are logged. But if set to a value > 2 all messages will be logged.
    If no parameters are submitted, the log will be stored on the file post.mpr
    See also "Start MSC Log"
  • STARTTIMEOUT
    When the PostMaster executes its start service it assumes that the started client will connect, via SPInit, within a certain amount of time. This timeout (in seconds) sets the limit when the PostMaster considers the start having failed. Default is 60 seconds.
    If the Telelogic Tau tools environment is running on slow computer or on a network which is heavily loaded, start-up of a Telelogic Tau tool might fail due to this timeout. In such case, this environment variable should be increased to an appropriate value.

PostMaster Application Library Environment Variables

The following environment variables are recognized by the PostMaster application library. These environment variables are read in the SPInit function.

  • POSTHOST
    UNIX only: Should be set to a hostname, on which a PostMaster runs. This PostMaster should be started with the environment variable POSTPORT set.
  • POSTPORT
    UNIX only: Should be set to a valid TCP port which is allocated to a PostMaster. Corresponds to POSTPORT set for the PostMaster.
  • POSTPID
    This environment variable is only of interest if multiple PostMasters are simultaneously active. If it is desired to make a connection to one particular PostMaster, this environment variable should be set to the process id corresponding to that PostMaster.
    If only one PostMaster is active, the application library automatically finds the PostMaster.
    If more than one PostMaster is running and this environment variable is not set, a connection is made to the PostMaster instance having the highest process id value.

Functional Interface

Communication with the PostMaster is based on a small set of fundamental functions:

 SPInit
initialization

 SPExit
termination

 SPBroadcast
output message, broadcast

 SPSendToTool
output message, sent to a certain tool

 SPSendToPid
output message, sent to a certain PId

 SPRead
input message

 SPFree
frees memory allocated by SPRead or SPFindActivePostMasters

 SPConvert
translate a symbolic message to an id

 SPErrorString
Error string conversion

 SPRegisterPMCallback
Message notification (Windows only)

 SPQuoteString
Quoting strings

 SPUnquoteString
Unquoting strings

 SPFindActivePostMasters
find all PostMasters

Every function returns a value denoting success or failure of the associated operation.

Calling Conventions

The PostMaster functions should be called in the following ways from the external tool:

  • The first thing to do is to initiate the connection with the PostMaster itself by calling SPInit. This is preferably done early in the main program. This initiation is private to the client and the PostMaster.
  • When having successfully called SPInit, the tool should listen to the PostMaster message port and read the incoming messages by SPRead. The tool should then act upon the messages it subscribes on.
  • If so desired, the tool should send messages by calling SPSendToTool , SPSendToPid or SPBroadcast.
  • When the tool decides to terminate, it should broadcast the standard message SESTOPNOTIFY by calling SPBroadcast. Then it should disconnect from the PostMaster by calling SPExit.
  • Every call to a PostMaster function should check the return value and act properly if an error is detected.

Variables

The following variables are defined.

extern INT16 sperrno;

extern INT16 spPortNO; (on UNIX)
extern int spPortNO; (in Windows)

sperrno contains an error code when a call to a PostMaster function failed. The error codes are defined in sdt.h and should be self-explanatory.

On UNIX, spPortNO contains a descriptor to the port where incoming messages from the PostMaster are found. In Windows, spPortNO contains a process identifier associated with the current process. The state of the variable prior to the call of SPInit is undefined.

These variables are found in the file post.h.

Caution!

Windows only: When linking with the PostMaster's dynamically linked libraries (post.lib and post.dll), the environment variable USING_DLL must be defined before including post.h. Example:

 #define USING_DLL
 #include "post.h"
 #undef USING_DLL

Error Codes

When a function returns SPERROR which indicates an error or an not expected result of the function. In this case sperrno is set to one of the following values.

Error Code
Explanation

 SPNOSESSION
The function SPInit has not been called successfully

 SPALREADYCONNECTED
When calling SPInit more than once without disconnecting

 SPNOPOSTMASTER
No PostMaster could be found when trying to connect

 SPNOCHANNEL
The contact with the PostMaster is lost.

 SPNOMESSAGE
No message available when trying to read by polling or after a timeout.

 SPTIMEDOUT
The connection to the PostMaster timed out.

 SPNOSUCHPID
Sending to a PId with a non positive value (<=0)

 SPNOMEMORY
Cannot allocate anymore dynamic memory (rare)

 SPTOOLNOTFOUND
When sending to a tool, this tool is not found in PostMaster configuration list

 SPINVALIDMESSAGE
Sending a message with a NULL parameter but specifying the length greater than 0.

 SPBADMESSAGE
A not supported message was to be sent.

 SPMANYPOSTMASTERS
Many PostMasters running. Could not decide which one to connect to. (Windows only)

 SPOLDPOSTMASTER
Old PostMaster running. (Windows only)

Functional Description

The available PostMaster functions are described on the following pages. The descriptions use the following format.

First, the function declaration is shown, including data types of parameters, followed by a short explanation of what the function does.

After that, in- and out parameters are described, together with possible return values and error codes.

SPInit

int SPInit(int toolType,
char * argv0,
*SPMList list);

SPInit initiates a session and establishes a connection with the PostMaster. See "Multiple PostMaster Instances" for information on how to connect to a specific instance of the PostMaster.

Inparameters

  • toolType
    The tool number identifies the tool and should be a value available in the PostMasters subscription list. For tools acting as an SDL/TTCN environment, it should be set to SET_SDLENV. See "Run-Time Considerations" for more information.
  • argv0
    The name of the executable (specified with its path). Normally argv[0] as passed to the program could be used.
  • list
    Defines a list of predefined messages allowed to send. It also provides a set of mappings between textual strings and integer values for tools and messages. Normally the list provided in sdt.h (itex.h) is used. This list is later used by the function SPConvert, which translates between a textual string and the corresponding identifier.

Returns

  • >0
    On UNIX, the PId of the calling process. Normally this PId corresponds to an UNIX PId. But if the PostMaster is started with the environment variable POSTPORT set, the PostMaster decides what PId value each client should get. In this case the numbering scheme gives the first started client 1, the next 2 and so on.
    In Windows, an identifier ("PId") which is used internally by the PostMaster in order to uniquely identify the calling process.
    This value could be used when sending messages and in comparisons with PIds contained in received messages.
  • SPERROR
    SPInit failed, sperrno is set.

Errors

SPNOPOSTMASTER
SPTIMEDOUT
SPALREADYCONNECTED
SPNOMEMORY
SPMANYPOSTMASTERS
SPOLDPOSTMASTER

SPExit

int SPExit(void);

SPExit exits a session and disconnects the connection with the PostMaster. Subsequent calls to PostMaster functions will return the error code SPNOSESSION until a new SPInit is performed.

Returns

  • SPOK
    Status OK.
  • SPERROR
    SPExit failed, sperrno is set.

Errors

SPNOCHANNEL
SPNOSESSION

SPSendToTool

int SPSendToTool(int tool,
int event,
void * data,
int size);

SPSendToTool sends a message to the process of kind tool.

Inparameters

  • tool
    Type of tool identifying the tool to send the message to. If such a tool is not running a service reply is sent by the PostMaster.
  • event
    Type of message
  • data
    Handle to an information block
  • size
    Size of data.

Returns

  • SPOK
    Status OK.
  • SPERROR
    SPSendToTool failed, sperrno is set.

Errors

SPNOCHANNEL
SPNOSESSION
SPNOMEMORY
SPBADMESSAGE
SPINVALIDMESSAGE
SPTOOLNOTFOUND
SPBADMESSAGE
SPNOSUCHPID

SPSendToPid

int SPSendToPid(int pid,
int event,
void * data,
int size);

SPSendToPid sends a message to the process which has process id toPid.

Inparameters

  • pid
    PId of the message's receiver. If the specified PId does not exist, an SEOPFAILED message or a service reply is sent by the PostMaster.
  • event
    Type of message.
  • data
    Handle to an information block.
  • size
    Size of data.

Returns

  • SPOK
    Status OK.
  • SPERROR
    SPSendToPid failed, sperrno is set.

Errors

SPNOCHANNEL
SPNOSESSION
SPNOMEMORY
SPBADMESSAGE
SPINVALIDMESSAGE
SPTOOLNOTFOUND
SPNOSUCHPID

SPBroadcast

int SPBroadcast(int event,
void * data,
int size);

SPBroadcast sends a message to all processes that subscribes on the message type.

Inparameters

  • event
    Type of message.
  • data
    Handle to an information block.
  • size
    Size of data.

Returns

  • SPOK
    Status OK.
  • SPERROR
    SPBroadcast failed, sperrno is set.

Errors

SPNOCHANNEL
SPNOSESSION
SPNOMEMORY
SPBADMESSAGE
SPINVALIDMESSAGE

SPRead

int SPRead(int timeOut,
int * pid,
int * message,
void ** data,
int * len);

SPRead reads a message from the queue of unread messages that the PostMaster has sent. When the message is read, it is also consumed, i.e. removed from the queue. The function allocates the necessary amount of memory needed for the data component in the message. The application using this function is responsible for freeing the allocated memory with SPFree when it is no longer needed.

Inparameters

  • timeOut
    Maximum amount of time (in milliseconds) that the function waits for a message. If a message has not arrived when timeOut expires, the function returns with return value SPERROR and sperrno is set to SPNOMESSAGE. If a message arrives, the function reads the message and returns immediately. If the desired behavior is to wait until a message arrives, which could mean forever, timeOut should be set to SPWAITFOREVER.

Outparameters

  • pid
    PId of the tool sending the message.
  • message
    Message identifier.
  • data
    Pointer to data associated with the received message. SPFree should be used to free memory.
    Length of allocated data. If ASCII data is received, it is not assured that data is terminated by a ASCII NUL (`\0'). The application should test if data[len-1] is `\0'.

Returns

  • SPOK
    Status OK.
  • SPERROR
    SPRead failed, sperrno is set.

Errors

SPNOCHANNEL
SPNOMESSAGE
SPNOSESSION
SPNOMEMORY

SPFree

void SPFree (void * ptr)

SPFree should be used to free the memory allocated by SPRead. This is necessary when different compilers with different memory management are used.

Inparameters

  • ptr
    A pointer to the memory block to be freed.

Returns

N/A.

SPErrorString

char * SPErrorString(int code);

Converts an error code into a textual string description of a tool or a message from the corresponding integer value.

Inparameters

  • code
    Error code. Typically set by sperrno.

Returns

An descriptive error string corresponding to the error code.

SPConvert

int SPConvert(char * str);

Converts a textual description of a tool or a message to the corresponding integer value as provided by the parameter list in SPInit.

Inparameters

  • str
    Textual description of the tool or message. The list provided in SPInit is used when searching for a mapping.

Returns

An integer value for the tool or message. If no mapping is found, SPERROR is returned.

SPRegisterPMCallback

typedef void (* SP_PM_MessageCallback) (void);
void SPRegisterPMCallback (SP_PM_MessageCallback cb);

Windows only: Registers a callback function that gets called every time a new PostMaster message arrives. Registering this callback enables (32-bit) Windows applications to function correctly. Console applications need not use this function.

Inparameters

  • cb
    The function to be called when a new PostMaster message is present. If cb is NULL the current callback is removed; otherwise the callback is replaced.

Returns

N/A.

SPQuoteString

int SPQuoteString(char *stringToQuote,
char *buffer,
int bufferLength,
int append)

SPQuoteString quotes a string. The following operations are performed:

  • A quote is added to the beginning and end of the string.
  • All quotes and backslashes in the string are escaped, i.e. a backslash character is added before them.

The quoted string can later be unquoted with a call to SPUnquoteString.

Inparameters

  • stringToQuote
    Pointer to a null-terminated string. This is the string that should be quoted.
  • bufferLength
    The size of the buffer (see the outparameter buffer below).
  • append
    If the value of append is non-zero, buffer is supposed to already contain a null-terminated string. The result of the quoting operation will be appended to this string at the end.
    If several quoted strings are concatenated, they can be extracted and unquoted one at a time with calls to the SPUnquoteString function.

Outparameters

  • buffer
    Pointer to a buffer where the resulting, quoted string will be returned. The buffer must be large enough to contain all the characters of the quoted string plus a trailing null character. The maximum buffer size needed can be quoted with the following formula:
    maximum buffer size = unquoted string size * 2 + 3
    This includes space for escaping every character in the string, plus three bytes for quotes and null character. A larger buffer might of course be needed when appending (see append above).
    The size of the buffer is given in bufferLength. If the quoted string does not fit in the buffer, the function will fail and return zero (further explained in the next section).

Returns

  • 1
    The call was successful.
  • 0
    The function call failed. The buffer was not large enough to contain the quoted representation of the string. The contents of the buffer are undefined.

SPUnquoteString

int SPUnquoteString(char *quotedString,
int inputLength,
char *buffer,
int bufferLength,
int position)

SPUnquoteString unquotes a string previously quoted with SPQuoteString, ignoring leading white-space characters. The following operations are performed:

  • Any white-space characters in the beginning of the string are ignored. If the string is empty or contains only white-space characters, the function call fails and returns zero (see "Returns" ).
  • If the first character after white-spaces is a quote, the function assumes that this quote starts a string quoted with SPQuoteString. In this quoted string, backslashes escape the following character. The string is ended with a non-escaped quote.
    The returned string will have the escaping backslashes and the leading and closing quotes removed.
  • If the first character after white-spaces is not a quote, the function will simply extract and return a substring up to but not including the next white-space character. If no further white-space characters are found, the rest of the string is returned. Backslashes and quotes have no special meaning when unquoting strings in this way.

Several concatenated quoted strings can be extracted with subsequent calls to this function by using the value returned in the position out parameter, see below.

Inparameters

  • quotedString
    Pointer to a string containing the string previously quoted with SPQuoteString. The string should either be null-terminated or inputLength below should have a meaningful value.
  • inputLength
    The maximum number of characters of quotedString that will be scanned. If quotedString is known to be null-terminated, a very large number should be supplied here.
  • bufferLength
    The size of the buffer (see the outparameter buffer below).

Outparameters

  • buffer
    A pointer to a buffer where the unquoted string will be returned. The buffer must be large enough to contain the resulting, unquoted string, including null character. A buffer one character larger than inputLength will always suffice. If the buffer is too small, the function call will fail and return zero (see "Returns" ). The size of the buffer is given in bufferLength.
    buffer can also be null, in which case no unquoting will be performed. The value of position can still be interesting, though.
  • position
    If this pointer is non-null it should point to an integer that will be filled in with the index of the character in the input string immediately following the extracted substring. This will be the character following a closing quote or a whitespace character or the terminating null character.

Returns

  • 1
    The function call was successful.
  • 0
    The function call failed. The supplied string might not be a valid quoted string according to the rules given above. The buffer might not be large enough to contain the result. The contents of the buffer and position are undefined.

SPFindActivePostMasters

int SPFindActivePostMaster (int *bufferPid,
char** bufferText,
int maxBufferlength);

Finds all PostMasters available for the application on the computer. Information retrieved is process id and a description in plain text.

Inparameters

  • maxBufferlength
    The size of the arrays bufferPid and bufferText.

Outparamters

  • bufferPid
    Pointer to an array where all process ids will be stored.
  • bufferText
    Pointer to an array of strings telling when the PostMaster was started. SPFindActivePostMaster will allocate memory for all strings and the application must call SPFree in order to free the memory.

Returns

Number of PostMasters found.

Java Interface

The file postmaster.java contains a java class that encapsulates the postmaster interface for java programmers. The class contains a few fundamental methods.

 Init
initialization

 SendToTool
output message, sent to a certain tool

 SendToPid
output message, sent to a certain Pid

 Broadcast
output message, broadcast

 Read
read a message

 Exit
termination

Init

int Init(int toolType);

SPInit initiates a session and establishes a connection with the PostMaster. See "Multiple PostMaster Instances" for information on how to connect to a specific instance of the PostMaster.

Inparameters

  • toolType
    The tool number identifies the tool and should be a value available in the PostMasters subscription list.

Returns

See functional description for the C interface

SendToTool

int SendToTool(int toolType, int message,
String data);

SPSendToTool sends a message to the process of kind tool.

Inparameters

  • toolType
    Type of tool identifying the tool to send the message to. If such a tool is not running a service reply is sent by the PostMaster.
  • message
    Type of message
  • data
    Data to send

Returns

See functional description for the C interface

SendToPid

int SendToPid(int pId, int message, String data);

SPSendToPid sends a message to the process which has process id toPid.

Inparameters

  • pid
    PId of the message's receiver. If the specified PId does not exist, an SEOPFAILED message or a service reply is sent by the PostMaster.
  • message
    Type of message
  • data
    Data to send

Returns

See functional description for the C interface

Broadcast

int Broadcast(int message, String data);

SPBroadcast sends a message to all processes that subscribes on the message type.

Inparameters

  • message
    Type of message
  • data
    Data to send

Returns

See functional description for the C interface

Read

int Read(int timeOut);

SPRead reads a message from the queue of unread messages that the PostMaster has sent. When the message is read, it is also consumed, i.e. removed from the queue. The data read by the last Read is copied to the Sender, Message and Data members of the class postmaster.

Inparameters

  • timeOut
    Maximum amount of time (in milliseconds) that the function waits for a message. If a message has not arrived when timeOut expires, the function returns with return value SPERROR and sperrno is set to SPNOMESSAGE. If a message arrives, the function reads the message and returns immediately. If the desired behavior is to wait until a message arrives, which could mean forever, timeOut should be set to SPWAITFOREVER.

Returns

See functional description for the C interface

Exit

int Exit();

SPExit exits a session and disconnects the connection with the PostMaster. Subsequent calls to PostMaster functions will return the error code SPNOSESSION until a new SPInit is performed.

Returns

See functional description for the C interface


Run-Time Considerations

Starting Up the PostMaster (in Windows)

When Telelogic Tau is started in Windows, an instance of the PostMaster is automatically started. No additional commands are needed for the PostMaster. There might however be situations when it is necessary to start the PostMaster stand-alone. This is described in the following sections. The examples only handle how the SDL suite is started from the "DOS" command prompt, but in many cases a shortcut with the analogous parameters can be created.

Start-Up

There are several possible ways to start the PostMaster itself and the tools that wish to communicate via the PostMaster. In principle, there are two main alternatives:

  • Starting the tools when the PostMaster is running
  • Starting them without having the PostMaster running.

We will exemplify the start-up methods by using the DemonGame simulator and a User Interface to the DemonGame simulator.

Note:

The PostMaster must be started first, but the communicating tools may be started in any order. An SDL simulator must also execute the commands Start-SDL-Env and Go before communication with another tool can start.

Starting When the PostMaster Is Present

When the SDL suite is started from the "DOS" or UNIX prompt, an instance of the PostMaster is automatically started. No additional commands are needed for the PostMaster in this case.

The DemonGame simulator is preferably started from the SDL suite, thus giving access to all simulation features. It can also be started directly from the "DOS" or UNIX prompt.

Starting from the "DOS" Prompt

Use the following command from the "DOS" prompt:

DemonGame.exe -post

Note:

In Windows, the simulator is a Windows GUI application and not a Console application. It is therefore not possible to run the simulator stand-alone, i.e. without -post.

Starting from the UNIX Prompt

Use the following command from the UNIX prompt:

DemonGame.sct -post

(Without the parameter, the simulator runs stand-alone, which is not desired in this case.) Starting the simulator this way restricts the possibilities of the simulation since there is no connection to the SDL suite tools. For instance, graphical trace is disabled.

The UI is preferably started directly from the UNIX prompt. It can also be started from the DemonGame simulator with the command Start-ITEX-Com, but this requires that the executable is named sdtenv. This is the name specified in the configuration for tool number 27000.

Starting Without the PostMaster

The SDL suite must be started directly from the "DOS" or UNIX prompt with the command:

$telelogic/bin/sdtpm <arg> & (on UNIX)

<Installation Directory>\sdt <arg> (in Windows)

(using one of the start-up arguments, see below).

The DemonGame simulator must also be started directly from the "DOS" or UNIX prompt, as described above.

Note:

On UNIX: If activating the PostMaster this way, the environment variable POSTPATH must be set to include the directory where the executables resides, typically $sdtbin.

The UI can be started in the same way as when the PostMaster is running (see above). It can also be started indirectly when starting the PostMaster by using the "DOS" or UNIX command:

$telelogic/bin/sdtpm -clients 27000 & (on UNIX)

<Installation Directory>\sdt -clients 27000 (in Windows)

This requires that the executable is named sdtenv, the name specified in the configuration for tool number 27000.

Note:

A tool communicating through the PostMaster can also be started from another tool by using the SESTART message. This requires that the tool to be started is specified in the configuration.

Start-Up Arguments

The PostMaster recognizes the following arguments at start-up. Normally they are not needed, but could be used for special purposes

  • -clients <toolid> Used if the PostMaster should invoke a certain tool at start-up. <toolid> is set to the logical tool number of a tool to start as defined in post.cfd.
  • -noclients Used if only the PostMaster is to be invoked without starting any clients. In this case the PostMaster enters an idle state where it waits for a client to connect

All other arguments are passed to the tool started.

SDT-2 Connections (UNIX only)

Applications or tools linked with an SDT 2.X PostMaster application library will not be compatible with SDT 3.X PostMaster. Trying to connect such an old application to an SDT 3.X PostMaster will result in an error message:

Postmaster cannot connect SDT2 tool:<tool> with pid: <pid>

on standard output, if externally started, or as a service reply, if started via the start service, and the connection is aborted.

Version 3.4 PostMaster (Windows only)

If an old PostMaster (version 3.4 or older) is used the SPInit function will fail. The error code is SPOLDPOSTMASTER.

Applications or tools linked with an SDT 3.4 PostMaster application library will not be compatible with the SDT 3.6 PostMaster. Trying to connect such an old application to an SDT 3.6 PostMaster with the SPInit function will fail. The error code is SPNOPOSTMASTER.

Multiple PostMaster Instances

It is possible to have multiple instances of the PostMaster running, for instance when more than one Telelogic Tau tool has been started. In this case it should be made sure that the communicating tools are connected to the correct instance of the PostMaster.

On UNIX, the function SPInit by default looks for the PostMaster instance with the highest process id (PId) number and connects to it.

On Windows, the function SPInit by default fails if more than one PostMaster is found.

To connect to another PostMaster instance, you can set the environment variable POSTPID to the PId number of the desired PostMaster. If this variable is set, SPInit connects to the PostMaster instance with that PId number.

Configuration and Tool Search

The PostMaster configuration is read whenever a PostMaster instance is invoked. The environment variable POSTPATH defines a list of directories where the PostMaster looks for a configuration file named post.cfd.

The user can extend the normal configuration by defining the POSTPATH variable to a directory containing an extended configuration. When a Telelogic Tau tool is started normally, the directories containing the binaries are put as the first directories in the POSTPATH variable.

The same search order is applied when the start service is used. The supplied tool number is matched against the name of an executable in the configuration, which is then searched for as above.


12 The Telelogic Tau Public Interface

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

Three conceptually different facilities are provided:

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

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

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


General Concepts

Introduction

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

Application Areas

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

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

The Public Interface

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

The public interface is made available to the Telelogic Tau tools users using two different mechanisms.

  • Via a programming interface, providing message based services and notifications. The rest of this section provides a description of these services and notifications and their usage.
  • Via applications executed via the OS command line interface. By using this interface:
    • Important services could be executed running the Telelogic Tau tools in a batch mode.
    • A Service Encapsulator could be run, which allows message based services to be issued. This tool is also made available as a an example application. For more information, see "The Service Encapsulator" .

The PostMaster

The PostMaster forms an integral mechanism to integrate tools in the Telelogic Tau tools environment (a reference to the PostMaster is provided in 11 The PostMaster).

It is also used as a low level mechanism to physically integrate the Telelogic Tau tools with external tools. The PostMaster provides three basic facilities:

  • It maintains a list on known tools. Such tools could be connected to the PostMaster and thereby taking part of message sending
  • It provides means to broadcast messages to a list of subscribers
  • It contains functionality to send a message to a certain recipient.

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

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

Services

Provides access to functionality within the Telelogic Tau tools. Such functions could be used by external tool to control the Telelogic Tau tools, to integrate the Telelogic Tau tools with external tools or have the Telelogic Tau tools take part in a larger environment.

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

Notifications

These are broadcast messages which are spontaneously emitted when a significant event takes place in the Telelogic Tau tools. Often these notifications are caused by a service being successfully processed.

Communication with SDL Simulators

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

Overview of Available Services

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

In the following services, the Configuration Services and the System File Services are applicable to Telelogic Tau, and the ITEX Services are only applicable to the TTCN suite. All other services are only applicable to the SDL suite.

Configuration Services

Service | Servers | Graphical correspondence
Start Tool | PostMaster | Start a new tool
Stop Tool | All tools | Exit menu choice
Get Tool Type | PostMaster | N/A
Get Tool Pid | PostMaster | N/A
Add Tool | PostMaster | N/A
Add Tool Subscription | PostMaster | N/A

System File Services

Service | Servers | Graphical correspondence
List System Files | Organizer | N/A
New System | Organizer | New quick button
Open System | Organizer | Open quick button
Save System | Organizer | Save quick button
Add Existing | Organizer | Add Existing menu choice

Link File Services

Service | Servers | Graphical correspondence
Add Local Link File | Organizer | N/A
Merge Local Link File | Organizer | N/A

ITEX Services

Service | Servers | Graphical correspondence
Convert to GR | ITEX | N/A
Opened Documents | ITEX | N/A
Fetch Buffer Identifier Given the Database | ITEX | N/A
Fetch Buffer Identifier Given MP File Path | ITEX | N/A
Convert to MP | ITEX | N/A
Convert Selection to MP | ITEX | N/A
Merge Document | ITEX | N/A
Analyze Document | ITEX | N/A
Close Document | ITEX | N/A
Save Document | ITEX | N/A
Selector | ITEX | N/A
SelectAll | ITEX | N/A
DeselectAll | ITEX | N/A
IsSelected | ITEX | N/A
Get Modify Time | ITEX | N/A
Get Path | ITEX | N/A
Get MP Path | ITEX | N/A
Find Table | ITEX | N/A
Close Table | ITEX | N/A
Get Table State | ITEX | N/A
Get Row Number | ITEX | N/A
Select Row | ITEX | N/A
Clear Selection | ITEX | N/A
Rows Selected | ITEX | N/A

Menu Manipulation Services

Service | Servers | Graphical correspondence
Add Menu | Organizer SDLE MSCE OME TE Coverage Viewer Index Viewer Type Viewer Tree Viewer File Viewer Preference Manager SimUI/ValUI | N/A
Delete Menu | As for Add Menu above. | N/A
Clear Menu | As above. | N/A
Add Item to Menu | As above. | N/A
Add Item to Menu - Organizer | Organizer | N/A
Add Item to Menu - Text Editor | TE | N/A
Add Item to Menu - Graphical Editors | SDLE MSCE OME | N/A

Logging Services

Service | Servers | Graphical correspondence
Start MSC Log | PostMaster | N/A
Stop MSC Log | PostMaster | N/A

SDT Reference Services

Service | Servers | Graphical correspondence
Show Source | Organizer | Show source menu choice
Obtain GR Reference | SDLE MSCE OME | N/A

Editor - Diagram Services

Service | Servers | Graphical correspondence
Load Diagram | SDLE MSCE OME TE | Open menu choice
Unload Diagram | SDLE MSCE OME TE | Close menu choice
Show Diagram | SDLE MSCE OME TE | Diagrams menu
Save Diagram | SDLE MSCE OME TE | Save menu choice
Create SDL Diagram | SDLE | New menu choice
Create MSC Diagram | MSCE | New menu choice
Create OM Diagram | OME | New menu choice
Create Text Diagram | TE | New menu choice

Editor - Object Services

Service | Servers | Graphical correspondence
Select Object | SDLE MSCE OME | Selecting an object
Show Object | SDLE MSCE OME | Selecting an object
Insert SDL Object | SDLE | Select object in symbol menu
Insert MSC Object | MSCE | Select object in symbol menu
Remove Object | SDLE MSCE OME | Clear menu choice
Get Object Text | SDLE MSCE OME | N/A

Editor - Object Attribute Services

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

Information Server Services

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

SDL Editor Services

Service | Servers | Graphical correspondence
GRPR | SDLE | N/A
Tidy Up | SDLE | Tidy Up menu choice

SC Editor Services

Service | Servers | Graphical correspondence
Get Diagram Info | OME | N/A

MSC Editor Services

Service | Servers | Graphical correspondence
MSC GRPR | MSCE | Generate MSC PR menu choice

HMSC Editor Services

Service | Servers | Graphical correspondence
HMSC GRPR | MSCE | Generate MSC PR menu choice

CIF Services

Service | Servers | Graphical correspondence
Create SDL Diagram | SDLE | N/A
Create SDL Page | SDLE | N/A
Insert SDL Object | SDLE | N/A
Create OM Diagram | OME | N/A
Create OM Page | OME | N/A
Insert OM Object | OME | N/A

Text Editor Services

Service | Servers | Graphical correspondence
Show Position | TE | N/A
Select Text | TE | N/A

Client Interface

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

  • A programming interface to communicate with the PostMaster
  • A description of the provided services
  • A description of the available notifications

External Client types

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

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

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

Item | Description
Tools | Use values in steps of 1000
Service Request | Base the value on the tool providing the service and add local base of 100. Then sequentially number the services
Service Reply | Base the value on the corresponding service request and add 100.
Notifications | Base the value on the tool broadcasting the notification and add the messages sequentially.

Message Based Services

Introduction

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

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

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

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

Service Request

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

Service Reply

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

Status Code
Value
Description

 OK

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

 Busy

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

 ErrorString

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

 ErrorCode

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

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

Error Handling

Error handling takes place at two different levels.

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

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

Common Errors

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

Bad parameters
Server busy
Service not supported
Server locked

SDT Reference Errors

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

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

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

Notifications

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

Message Parameters

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

  • Parameters are normally separated by a blank (` `) character.
  • A parameter that has an additional `*' character is a shorthand for none or a number of this type, each one separated by a blank ` ` or a newline `\n'.
    • The character `+' might also appear as an alternative. The difference is that one or more is expected.
  • A preceding attribute tells how many items to expect.

The following parameter types are used:

Type
Description

 integer
32 bit integer in ASCII form.

 bool
Logical. True = 1, False = 0

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

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

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

Files

  • The files sdt.h and itex.h provides two lists of the available services and notifications in terms of message definitions. It also defines a list (see "Adding Tools and Messages" ) providing a textual definition of messages.
  • The file sdtsym.h provides the definitions necessary when working with editors and defines values for diagram types, pages types and symbol types.
  • In Windows, the file post.dll is the DLL that contains the external PostMaster interface. It needs either reside in the same directory as the application that is utilizing it, or in a directory that is in the current PATH.

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

Interpretation of a Service Description

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

Description

A brief textual description of the service.

Tools Supporting the Service

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

Service Request

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

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

Parameter
Type
Description

 symbolic
parameter
name

 parameter
type
Brief description of the parameters.

Service Reply

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

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

Parameter
Type
Description

 status

 integer
Service reply status.

Errors

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

Emitted Notifications

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


The Service Encapsulator

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

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

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

$telelogic/examples/public_interface (on UNIX)

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

The Service Encapsulator binary is invoked by:

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

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

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

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

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

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

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

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

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

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


Tool Services

Configuration Services

Start Tool

Description

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

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

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

The started tool inherits the environment used by the PostMaster.

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

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

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

The service will return to the caller:

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

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

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

-

ITEX Services

Convert to GR

Description

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

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXCONVERTTOGR

Parameter
Type
Description

 filename

 QString
The name of the MP file

 destination

 QString
The name of the destination directory

 ignore page
number

 bool
Ignoring the included page numbers

Service Reply

IEBXCONVERTTOGRREPLY

Parameter
Type
Description

 status

 integer
Service reply status

 itexfile

 QString
The filename of the generated document.

Errors

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

Opened Documents

Description

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

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXOPENEDDOCUMENTS

Service Reply

IEBXOPENEDDOCUMENTSREPLY

Parameter
Type
Description

 status

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

 infolist

 EBNF
The list of open documents identifiers, buffer identifiers and database file.

Errors

-

Fetch Buffer Identifier Given the Database

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETBUFFIDFROMPATH

Parameter
Type
Description

 itexfile

 QString
The database path in the local system syntax.

Service Reply

IEBXGETBUFFIDFROMPATHREPLY

Parameter
Type
Description

 status

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

 buffid

 integer
The document's buffer identifier

Errors

Unable to find database

Fetch Buffer Identifier Given MP File Path

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETBUFFIDFROMMPPATH

Parameter
Type
Description

 mpfile

 QString
The MP file path in the local system syntax.

Service Reply

IEBXGETBUFFIDFROMMPPATHREPLY

Parameter
Type
Description

 status

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

 buffid

 integer
The document's buffer identifier

Errors

Unable to find database

Convert to MP

Description

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

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXCONVERTTOMP

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 standard
flag

 bool
Indicates if the MP shall be TTCN standard. (True if standard MP is required.)

 filename

 QString
The MP filename

Service Reply

IEBXCONVERTTOMPREPLY

Parameter
Type
Description

 status

 integer
Service reply status

Errors

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

Convert Selection to MP

Description

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

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXCONVERTSELTOMP

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 standard
flag

 bool
Indicates if the MP shall be TTCN standard. (True if standard MP is required.)

 filename

 QString
The MP filename

Service Reply

IEBXCONVERTSELTOMPREPLY

Parameter
Type
Description

 status

 integer
Service reply status

Errors

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

Merge Document

Description

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

For more information, see "Merging TTCN Documents" .

Tools Supporting the Service

IET_BASE

Service Request

IEBXMERGEDOCUMENT

Parameter
Type
Description

 srcbuffid

 integer
The source document's buffer identifier

 destbuffid

 integer
The destination document's buffer identifier

Service Reply

IEBXMERGEDOCUMENTREPLY

Parameter
Type
Description

 status

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

Errors

Unable to merge documents

Analyze Document

Description

Analyze the given system node.

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXANALYZE

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 forced
analysis

 bool
Set if forced analysis should be in effect

 verbose

 bool
Indicates if verbose mode is to be on

 errorlimit

 integer
Max number of errors before aborting

Service Reply

IEBXANALYZEREPLY

Parameter
Type
Description

 status

 integer
Service reply status

Errors

Invalid buffer identifier
The document is not connected

Close Document

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXCLOSEDOCUMENT

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXCLOSEDOCUMENTREPLY

Parameter
Type
Description

 status

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

Errors

Invalid buffer identifier
Unable to close document

Save Document

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXSAVE

Parameter
Type
Description

 buffid

 integer
The document reference

 filename

 QString
The filename where the document source must be saved.

Service Reply

IEBXSAVEREPLY

Parameter
Type
Description

 status

 integer
Service reply status.

Errors

No such tool
Invalid buffer identifier
Couldn't write file

Selector

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXSELECTOR

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 namerestr

 string
The name restriction.

 typerestr

 string
The content restriction.

 contentrestr

 string
The type restriction.

 selectormode

 string
The selector mode (restrict, extend or replace REL where REL is references, references_recursive or referenced_by)

 analysestatus

 string
The analysis status (not_analyzed, error_analyzed or ok_analyzed)

Service Reply

IEBXSELECTORREPLY

Parameter
Type
Description

 status

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

Errors

No such tool
Invalid buffer identifier

SelectAll

Description

Select all objects in the document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXSELECTALL

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXSELECTALLREPLY

Parameter
Type
Description

 status

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

Errors

Invalid buffer identifier

DeselectAll

Description

Remove all selections in the document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXDESELECTALL

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXDESELECTALLREPLY

Parameter
Type
Description

 status

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

Errors

Invalid buffer identifier

IsSelected

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXISSELECTED

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXISSELECTEDREPLY

Parameter
Type
Description

 status

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

 selectstate

 bool
Indicates if there is any selected objects in the document.

Errors

Invalid buffer identifier

Get Modify Time

Description

This function fetches the modify time of a document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETDOCUMENTMODIFYTIME

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXGETDOCUMENTMODIFYTIMEREPLY

Parameter
Type
Description

 status

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

 modifytime

 QString
The modify time of the document.

Errors

Invalid buffer identifier

Get Path

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETPATH

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXGETPATHREPLY

Parameter
Type
Description

 status

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

 itexfile

 QString
The database path in the local system syntax.

Errors

Invalid buffer identifier

Get MP Path

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETMPPATH

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

Service Reply

IEBXGETMPPATHREPLY

Parameter
Type
Description

 status

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

 mpfile

 QString
The MP file path in the local system syntax.

Errors

Invalid buffer identifier

Find Table

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXFINDTABLE

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableid

 QString
The name of the table to find

Service Reply

IEBXFINDTABLEREPLY

Parameter
Type
Description

 status

 integer
Service reply status

Errors

Invalid buffer identifier
Unconnected document

Close Table

Description

Close the given table.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCLOSETABLE

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableident

 QString
The table identifier.

Service Reply

IEBXCLOSETABLEREPLY

Parameter
Type
Description

 status

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

Errors

Invalid buffer identifier
No such object

Get Table State

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETTABLESTATE

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableident

 QString
The table identifier.

Service Reply

IEBXGETTABLESTATEREPLY

Parameter
Type
Description

 status

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

 tablestate

 QString
Returns open, close, row_in_open or row_in_close.

Errors

Invalid buffer identifier
No such object

Get Row Number

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETROWNUMBER

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableident

 QString
The table identifier.

 rowname

 identifier
The name of the row.

Service Reply

IEBXGETROWNUMBERREPLY

Parameter
Type
Description

 status

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

 rownumber

 integer
The number of the given row. The first row has number one.

Errors

Invalid buffer identifier
No such object
No such row

Select Row

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXSELECTROW

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableident

 QString
The table identifier.

 rownumber

 integer
The number of the row.

 selectstate

 bool
The select status of the row to be modified.

Service Reply

IEBXSELECTROWREPLY

Parameter
Type
Description

 status

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

 exist

 bool
Returns false if the message was inserted, true if it already existed.

Errors

Invalid buffer identifier
No such object
No such rownumber

Clear Selection

Description

This function removes all row selections in a table.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCLEARSELECTION

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableident

 QString
The table identifier.

Service Reply

IEBXCLEARSELECTIONREPLY

Parameter
Type
Description

 status

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

Errors

Invalid buffer identifier
No such object

Rows Selected

Description

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

Tools Supporting the Service

IET_BASE

Service Request

IEBXROWSSELECTED

Parameter
Type
Description

 buffid

 integer
The document's buffer identifier

 tableident

 QString
The table identifier.

Service Reply

IEBXROWSSELECTEDREPLY

Parameter
Type
Description

 status

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

 nonezero*

 integer
A list of selected row numbers. The list is empty if no row is selected.

Errors

Invalid buffer identifier
No such object

Menu Manipulation Services

Introduction

All graphical tools in 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. Telelogic Tau tools could also take advantage of these extendable menus.

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

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

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

  • A PostMaster message
  • An operating system command

Add Menu

Description

Adds a new menu to the menu bar.

Tools Supporting the Service

SET_ORGANIZER
SET_SDLE
SET_MSCE
SET_OME
SET_TE
SET_SIMULATOR_UI 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:

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

Tools Supporting the Service

SET_ORGANIZER
SET_SDLE
SET_MSCE
SET_OME
SET_TE
SET_SIMULATOR_UI 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.

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

Parameter
Type
Description

 message

 integer
Interpreted as the PostMaster message to send.

 params

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

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

Parameter
Type
Description

 OSblock

 bool
Whether to wait for the command to finish before giving control to the user.

 OScommand

 string
The OS command to perform. Tool-specific context sensitive format codes are evaluated; see the separate tool descriptions later.

Service Reply

SEMENUADDITEMREPLY

Parameter
Type
Description

 status

 integer
Service reply status.

Errors

-

Add Item to Menu - Organizer

Description

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

Tools Supporting the Service

SET_ORGANIZER

Service Request

SEMENUADDITEM

Format Codes

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

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

Format code
Description

 %b
%Bb,
%Db
%Rb
The file name of the system file associated to the Organizer window.

 %f
%Bf
%Df
%Rf
The name of the file that contains the selected object.

 %F
%BF
%DF
%RF
All files in the substructure of the selected object (including the selected object).

 %l
%Bl
%Dl
%Rl
The name of the link file loaded in the Organizer.

 %o
%Bo
%Do
%Ro
The name of the Control Unit file for the selected object.

 %r
Perform the command recursively on all files in the substructure of the selected object (including the selected object).

 %u
The source directory.

 %v
The target directory.

Parameters

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

Parameter
Type
Description

 lastAction

 integer
Controls what happens when a dynamic menu command has been performed. Only available when actionType is OS Command.
This attribute should be one of the following:

 NOTHING (0)

  Perform no action.

 CHECK_FILE (1)

  A check file operation is performed on the selected object when the OS command is completed. If the OS command is non-blocking, the command is performed as soon as the OS command has been issued.

 CHECK_FILE_ON_RECURSIVE
(2)

  This flag works as the CHECK_FILE flag but is used only with a %r command.

 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:

  • An SDL reference.
    The reference is shown in an SDL Editor.
  • An MSC reference.
    The reference is shown in an MSC Editor.
  • An OM reference.
    The reference is shown in an OM Editor.
  • A text reference
    The reference is shown in a text editor. The text editor is chosen by the preference SDT*TextEditor.

For a complete description of the format of an SDT reference, please see 19 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 Telelogic.

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

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

  • SDL diagram
  • MSC diagram
  • OM, SC, HMSC diagram
  • SDL Page
  • OM, SC, HMSC page
  • SDL symbol
  • MSC symbol
  • OM, SC, HMSC symbol

The purpose of the extended data attribute is:

  • To allow the user to add his own-defined data to diagrams managed by the SDL suite.
  • In addition, data extensions can by connected to operations to be performed on that data. Operations are performed through PostMaster messages or Operating System commands.

Extended Data Attribute

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

  • ProprietaryKey
    Provides a means to tag extensions with the originating company / organization. Should normally be set to 0.
  • AttributeKey
    Up to the user's preference when deciding how to use this key.
  • data_length
    Provides information about how many bytes of data the variant_data union consists of. Generally, all elements of variable length need to have their length specified, since the user must be able to store hex 0 as data.
  • data_interpretation and data
    In the SDL suite, data is always interpreted as raw data. The SDL suite have no knowledge about the format and meaning of the data. Raw data may consist of information produced by an external tool. Its format is not known by the SDL suite. Thus, operation of any sort applied on that data, cannot be performed.
  • comment_length
    How many bytes the comment consists of.
  • comment
    Gives the possibility to attach a (preferable) readable comment in plain text. The comment could assist the user in understanding the meaning of data that he has attached to the object.

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.

  • AttributeKey will be omitted if it has value 0
  • If ProprietaryKey is 0 both keys will be omitted.

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.

  • If SDTRef is empty, display all symbols is all diagrams that are read by the tool, and that match the keys
  • If SDTRef denotes a diagram, display all symbols in the diagram that match the keys
  • If SDTRef denotes a page, display all symbols in the page that match the keys
  • If SDTRef denotes a symbol, display the symbol if it matches the keys.

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.

  • AttributeKey will be omitted if it has value 0.
  • If ProprietaryKey is 0 both keys will be omitted.

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.

  • If SDTRef is NULL, list all symbols is all diagrams that are read by the tool, and that match the keys.
  • If SDTRef denotes a diagram, return SDTRef to all objects in the diagram that match the keys.
  • If SDTRef denotes a page, return SDTRef to objects in the page that match the keys.
  • If SDTRef denotes an object, return the SDTRef to the object if it matches 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.

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:

  • Block interaction diagrams,
  • Process interaction diagrams

where the services are supported by the SDL Editor, and

  • OM diagrams,

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:

  • If a line is inserted the symbols connecting the line must already have been inserted.
  • For lines it is an error if there are less than two breakpoints.
  • The object type must be a known symbol or line.

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

  • Ratio for process symbols, should be 1:2 (height vs. width).
  • Positions outside the page area.
  • Text syntax for reference symbols.
  • Illegal texts on flowlines.
  • Sizes less than minimum allowed.
  • That lines are connected to symbols with the correct syntax.
  • That line endpoints fall on enclosing rectangle of the symbol it is connected to.
  • Symbols placed on pages where they should not appear, e.g. a task on a system page.
  • Overlapping symbols

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.

  • Process Interaction diagram symbols
Start(1), ProcedureStart(2), MacroInlet(3), Stop(4), ProcedureReturn(5), MacroOutlet(6), State(7), InputRight(8), InputLeft(9), PriorityInputRight(10), PriorityInputLeft(11), ContinuousSignal(12), EnablingCondition(13), Task(14), OutputRight(15), OutputLeft(16), PriorityOutputRight(17), PriorityOutputLeft(18), ProcedureCall(19), InConnector(20), CreateRequest(21), Decision(22), TransitionOption(23), MacroCall(24), OutConnector(25), Save(26)

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

  • Block Interaction diagram symbols
Procedure(27), Service(41), Process(42), Block(43), BlockSubstructure(45), ChannelSubstructure(46), SystemType(47), BlockType(48), ServiceType(49), ProcessType(50), Operator(56).

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.
  • TextSymbol(28)

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.
  • Comment(29), CommentLeft(30), TextExtension(31) and TextExtensionLeft(32)

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.
  • FrameSymbol(44)

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.
  • AdditionalHeading(52), PackageReference(55)

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.
  • FlowLine(101)

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.
  • SignalRoute(102)

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.
  • DoubleSignalRoute(103)

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.

  • Channel(104)

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.
  • DoubleChannel(104)

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.

  • CreateLine(106), ChannelSubstructureLine(107)

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.
  • GateIn(109), GateOut(110)

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.
  • DoubleGate(111)

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.

  • ConnectionPoint(112)

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:

  • If a line is inserted the symbols connecting the line must already have been inserted.
  • For lines it is an error if there are less than two breakpoints.
  • The object type must be a known symbol or line.

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

  • Positions outside the page area.
  • Text syntax for class and instance symbols. However, when an object is inserted with the updateFlag set there will be a syntactic check and all eventual syntax errors will be marked in the normal way.
  • That lines are connected to symbols with the correct syntax.
  • That line endpoints fall on or inside the enclosing rectangle of the symbol it is connected to.
  • Overlapping symbols

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

  • Class(57)

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.

  • Instance(58)

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.

  • TextSymbol(28)

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

  • AssociationLine(113), AggregationLine(114)

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.
  • GeneralizationLine(115)

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.
  • Class LinkLine(123)

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:

  • If no window is displaying the document identified by bufferId, the buffer is displayed in a window according to the user's window reuse policy.
  • A window is brought to the front.
  • The text in the window is re-centered so that the indicated character is displayed.

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.

  • If no window is displaying the document identified by bufferId, the buffer is displayed in a window according to the user's window reuse policy.
  • A window is brought to the front.
  • The text in the window is re-centered so that the indicated character is displayed.

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 Simulator/Validator UI's can not read menu-definition files.

2

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

3

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

4

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


Notifications

The notifications inform the environment when something significantly in Telelogic Tau happens. Notifications are only available as PostMaster messages.

To receive a notification one must subscribe on that particular notification (or on all notifications). This is accomplished either statically, by an entry in an additional configuration file, or dynamically by the Telelogic Tau services Add Tool and Add Tool Subscription.

Overview of Available Notifications

Tool notifications

Message
Description

 SESTARTNOTIFY
When a tool is started.

 SESTOPNOTIFY
When a tool is stopped.

Diagram notifications

Message
Description

 SELOADNOTIFY
When a diagram is loaded.

 SEUNLOADNOTIFY
When a diagram is unloaded.

 SEDIRTYNOTIFY
When a diagram becomes modified.

 SESAVENOTIFY
When a diagram is saved.

 SESDLENEWNOTIFY
When an SDL diagram is created.

 SEMSCENEWNOTIFY
When an MSC diagram is created.

 SEOMENEWNOTIFY
When an OM diagram is created.

 SETENEWNOTIFY
When a text diagram is created.

Start Notify

Description

This message is broadcast when a new tool is started. That is, when it connects to the PostMaster. It is sent automatically by the SPInit function.

Tools Issuing the Notification

The started tool

Notification

SESTARTNOTIFY

Parameter
Type
Description

 toolType

 integer
The kind of tool that was started.

 argv0

 string
The filename (with a complete path) of the started tool as obtained by reading argv[0].

Stop Notify

Description

This message is broadcast when the tool disconnects from the PostMaster and terminates.

Tools Issuing the Notification

The tool which stops

Notification

SESTOPNOTIFY

Parameter
Type
Description

 toolType

 integer
The kind of tool that stopped.

Load Notify

Description

Broadcast when the diagram is loaded in an editor.

Tools Issuing the Notification

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Notification

SELOADNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the loaded diagram.

 fileName

 string
Name of the loaded file.

 diagramType

 integer
Diagram type of the loaded diagram.

 diagramName

 string
Diagram name of the loaded diagram.

Unload Notify

Description

Broadcast when the diagram is unloaded in the editor. No assumptions could be made whether or not the diagram was saved. The buffer id of the unloaded diagram is then not longer valid and cannot be used anymore.

Tools Issuing the Notification

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Notification

SEUNLOADNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the unloaded diagram.

Dirty Notify

Description

Broadcast when a diagram becomes dirty, i.e. when the user has modified the diagram.

Tools Issuing the Notification

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Notification

SEDIRTYNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the diagram that became dirty.

Save Notify

Description

The message is broadcast when a diagram is saved.

Tools Issuing the Notification

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Notification

SESAVENOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the saved diagram.

 fileName

 string
The filename in which the diagram was saved.

SDL New Notify

Description

Broadcast when a diagram is created in the SDL Editor. In this case a Load Notify is not broadcast.

Tools Issuing the Notification

SET_SDLE

Notification

SESDLENEWNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the new diagram.

 virtuality

 string
Kind of virtuality

 diagramType

 integer
Type of diagram.

 diagramName

 string
Name of the diagram.

 qualifier

 string
A qualifier for the new diagram. The qualifier is not a full qualifier, since it does not include the diagram path to the root diagram.

MSC New Notify

Description

Broadcast when a diagram is created in the MSC Editor. In this case a Load Notify is not broadcast.

Tools Issuing the Notification

SET_MSCE

Notification

SEMSCENEWNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the new diagram.

 diagramName

 string
Name of the new diagram.

OM New Notify

Description

Broadcast when a diagram is created in the OM Editor. In this case a Load Notify is not broadcast.

Tools Issuing the Notification

SET_OME

Notification

SEOMENEWNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the new diagram.

 diagramName

 string
Name of the new diagram.

TE New Notify

Description

Broadcast when a diagram is created in the Text Editor. In this case a Load Notify is not broadcast.

Tools Issuing the Notification

SET_TE

Notification

SETENEWNOTIFY

Parameter
Type
Description

 bufId

 integer
Buffer id of the new diagram.

 diagramName

 string
Name of the new diagram.


Auxiliary Messages

Communicating with Simulators

Description

SESDLSIGNAL is sent by an SDL simulator when it sends an SDL signal to its SDL environment. Other simulators (or any applications connected to the PostMaster) can then receive the message and send back messages of the same type.

The PIds consist of a UNIX PId (on UNIX), or an identifier "pid" known by the PostMaster (in Windows), in both cases an integer, and an SDL process instance number (a hex number), which normally is used only in comparisons. The PIds may be used to uniquely identify a single receiver if several receivers exist, but can be ignored if only two tools are communicating

Tools Issuing and Recognizing the Message

SET_SDLENV

Message

SESDLSIGNAL

Parameter
Type
Description

 signalName

 integer
SDL name of the sent signal

 globalReceiverPid

 integer
See above.

 localReceiverPid

 string
See above.

 globalSenderPid

 integer
See above.

 localsenderPid

 string
See above.

 signalParam

 string
Sea above.

PostMaster Operation Failed

Description

SEOPFAILED is sent by the PostMaster when an internal problem inhibited a message to be handled properly. Three major categories of errors exists:

  • Communication error, i.e. the underlying network (e.g. UNIX socket) reported an error
  • An explicit address did not exist
  • An operation requested from the PostMaster failed.

Tools Issuing and Recognizing the Message

SET_POST

Message

SEOPFAILED

Parameter
Type
Description

 message

 integer
The message causing the error.

 severity

 integer
Kind of error.

 pid

 integer
The PId of the subscriber (if a specific subscriber was involved).

 errorCode

 integer
The error itself.

 messageParam

 string
The remaining information is the data (or the first part of the data) of the message causing the error.


13 Using the Telelogic Tau Public Interface

This chapter contains a number of examples of how the use the features provided by the Telelogic Tau Public Interface.

For a reference to the topics that are exemplified in this chapter, see 12 The Telelogic Tau Public Interface.


Introduction

The first example shows a simple application, the Service Encapsulator, by which it is possible to request Telelogic Tau tools services from the Operating Systems command line. The example shows how to use the PostMaster interface.

The second example uses the Service Encapsulator and shows the usage of some SDL suite Services. Since the "DOS" command prompt is rather weak in its scripting capabilities, no example script file is included for Windows in this example.

The third example uses the Service Encapsulator and shows the usage of some TTCN Suite Services.

The final example exemplifies how to integrate an SDL simulator and a separate user interface (UNIX only). How to design such a user interface is described in a detailed example. It is assumed that the reader has experience of creating and running SDL simulators.

The Service Encapsulator

Introduction to the Service Encapsulator

This section shows an application, the Service Encapsulator, implementing a command line service request encapsulation. That is, Telelogic Tau services as made available by the Telelogic Tau Public Interface, could be obtained from the command line.

The purpose of this example is to show:

  • How the PostMaster interface is used when working with Telelogic Tau services.
  • By using the Service Encapsulator, show the usage of a number of services.

The application is general in the sense that it does not require a Telelogic Tau tool to be running (only the PostMaster is required to be running), but in this context it exemplifies a number of Telelogic Tau services.

From the outside world the application behaves like a tool providing remote procedure call functionality. That is, when the service is requested, the application synchronously waits for the service reply, before returning (the application exits).

The example is found in the Telelogic Tau distribution in the subdirectory examples and then public_interface.

The Service Encapsulator is also available as a tool in the Telelogic Tau environment, see "The Service Encapsulator" .

Design

In this section is a few important aspects in the design and implementation of the Service Encapsulator given. The source file is named serverpc.c and the executable is named serverpc.

The tool connects to the PostMaster by issuing:

SPInit(SET_EXTERN, argv[0], spMList) (in SDL suite)
SPInit(IET_EXTERN, argv[0], ipMList) (in TTCN suite)

The first parameter gives the type of application. In this case SET_EXTERN or IET_EXTERN is used. This application type is a predefined tool type for external applications connecting to Telelogic Tau. The variable spMList or ipMList gives the possibility to convert between textual (symbolic) values and integers.

If SPInit succeeds, SPInit broadcasts a SESTARTNOTIFY, indicating to all other tools in the environment that an additional tool is connected.

if ((tool=atoi(argv[1])) == 0 )
tool = SPConvert(argv[1]);

If the parameter <tool> was given textually, the function SPConvert converts it to the corresponding integer value. If a mapping cannot be found, -1 is returned. This is an error and will be detected in the SPSendToTool function, see below.

if ((sendEvent=atoi(argv[2])) == 0 )
sendEvent = SPConvert(argv[2]);

Allocating memory for the message parameter is done as follows:

for (i=3;i<argc;i++) {
p = realloc(p, strlen(p) + strlen(argv[i]) + 2);
if (strlen(p)>0)
p = strcat(p, " ");
p = strcat(p, argv[i]);
}

The handleescape function allows carriage return "\n", "\r" and "\0" to be used when sending messages:

p = handleescape(p);

A normal service request is issued by:

status=SPSendToTool(tool, sendEvent, p, strlen(p)+1;

The last parameter tells the length of the parameter provided by argv[3] and must be extended by 1 to include the terminating \0 character.

Now the service request message is sent to the PostMaster which forwards it to the server application. If not busy, the Service application starts to process the service request and when finished it replies with a service reply message to the issues. However, during the processing other messages can be sent or broadcast to the Service Encapsulator (the service issuer). Therefor we must enter a loop where we stay until the reply message is received. Other kind of messages are dropped.

do {
if (( status=SPRead(SPWAITFOREVER, &pid,
&replyEvent,(void*)&replyMessage, &len))!=0 )
OnError("Error reading from postmaster: ");
} while ( ! SP_MATCHREPLY(sendEvent, replyEvent) );

The function SPRead reads a message form the PostMaster. The first parameter, the timeout, could be set to wait indefinitely until a message arrives, using the value SPWAITFOREVER.

This simple application has a drawback: if something unexpectedly happens to the server, it might be that no service reply will be sent which means that we block in SPRead forever. The behavior could be enhanced by setting a timeout, and when the timeout expires, check the state of the server (Use the PostMaster service Get Tool Pid).

If the service readattribute was issued, special care must be taken to handle the answer, since it contains binary data. The length of the data part ends the replyMessage. The end is indicated by an ASCII 0. The data part immediately follows the ASCII 0 character and might contain non-ASCII characters. Our printout assumes ASCII data.

if ( sendEvent == SEREADATTRIBUTE ) {
printf("%s", replyMessage+1);
printf("%s\n", replyMessage+ strlen(replyMessage)
+1);
}

The macro SP_MATCHREPLY compares the issued service request message and the reply message and returns true if the correct received message was the correct service reply message.

The service reply is then printed on standard output. The following prints the service reply data:

int i;
for( i=2;i<len;i++ )
putchar(replyMessage[i]);
putchar('\n');

Counting starts at position 2, omitting the service reply status.

free (replyMessage);

replyMessage was dynamically allocated using malloc in SPRead, so it must be freed.

Before terminating the application, notify all other applications in the environment that it is going to break its connection to the PostMaster

SPBroadcast(SESTOPNOTIFY, NULL, 0);

Finally we terminate the PostMaster connection by calling:

SPExit ();

Generating the Application for the SDL Suite

To generate the application do the following:

  1. Change the current directory to the sub directory containing the example:
On UNIX: cd <Installation Directory>/examples/public_interface

In Windows: cd <Installation Directory>\examples\public_interface

  2. Set the environment variable telelogic to point to the right directory. This is platform dependent.
On UNIX: setenv telelogic <Installation Directory>

In Windows: set telelogic=<Installation Directory>

  3. Generate the application:
    On Solaris: make -f Makefile.solaris
    On HP: make -f Makefile.hp
    In Windows using Borland: make -f Makefile.borland
    In Windows using Microsoft: nmake /f Makefile.msvc


Using the SDL Suite Services

Introduction

This section exemplifies the usage of some SDL suite services. The examples take advantage of the Service Encapsulator described in the previous section.

In these examples, we only use textual values of the parameters <tool> and <service>. Available textual values is found in the spMList variable in sdt.h.

In the examples below, the Service Encapsulator is executed from a csh shell (on UNIX), or from the "DOS" prompt (in Windows). If another shell is used, the examples below might need to be modified in order to supply the parameters correctly. Take care how to supply the quoted strings.

Note:

Due to limitations in DOS, this Service Encapsulator example is not as extensive in Windows as the UNIX version.

Load External Signal Definitions into the Information Server

For this service to be available, the Information Server must be started. This could be done by either starting the Type Viewer from the Organizer, by requesting Signal Dictionary support in the SDL Editor or by using the Start service. For a complete service description, See "Start Tool" .

Requesting the Service

It is assumed that a file a.pr is to be loaded. Note that the file to be loaded must be specified with a full directory path.

On UNIX: serverpc info loaddefinition /usr/ab/a.pr

In Windows: serverpc info loaddefinition c:\sdt\ex\a.pr

If the Information Server is started, the following reply message is returned:

Reply status is OK

If the Information Server is not started, we get the following reply message.

Error sending to postmaster: server not connected to postmaster

Obtain Source (SDL/GR Reference)

Returns a complete SDT reference of each of the selected symbols in the specified editor.

serverpc sdle obtainsource

If the editor was already started and there was a selection the reply message might look like:

Reply status is OK
1 "#SDTREF(SDL,c:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongam\demon.spr(1),125(30, 70))"

Note that the reference returns a complete file path of the diagram file in which the selection was made.

If the editor did not contain any selection, the reply becomes:

Reply status is OK
0

For a complete description of the service, see "Obtain GR Reference" .

Show Source

Selects the object given by the parameters in an editor. The editor is started if necessary as a side effect. A system must however be opened in the Organizer containing the specified reference.

To test this service we could now deselect all selections in the SDL Editor and use the reference extracted by obtainsource to select this symbol again. Note how the SDT reference is quoted to pass it from the shell into the tool.

On UNIX: serverpc organizer showsource \
"""#SDTREF(SDL,/usr/sdt-inst/examples/simulator- \
integration/sunos4/demon.spr(1),125(30,70))"""

In Windows: serverpc organizer showsource \"#SDTREF(SDL,c:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\demongam\demon.spr(1),125(30, 70))\"

If the reference is found the following message is replied:

Reply status is OK

For a complete description of the service, see "Show Source" .

For a complete description of how to specify a SDT reference, see "Syntax" .

Dynamic Menus

The following example shows how a dynamic menu is created and how a number of menu items are inserted in the dynamic menu. The script dyn-menu in the example directory performs the example below.

Note:

In Windows, this example is intended for Windows NT/2000. If you are running Windows 95/98, all references below to CMD should be changed into COMMAND.COM

For a complete description of the services, see "Add Menu" , "Delete Menu" , "Clear Menu" and "Add Item to Menu - Graphical Editors" .

Add a new menu to the SDL Editor:

serverpc sdle menuadd \"dyn-menu\"

Reply:

Reply status is OK

Add a menu item which executes the OS command ls (on UNIX) or DIR (in Windows) after a confirmation from the user:

On UNIX: serverpc sdle menuadditem \
\"dyn-menu\" \"ls\" 0 \
\"Perform OS command ls\" 0 0 0 \
\"OK to perform ls!\" 1 1 \"ls\"

In Windows: serverpc sdle menuadditem \"dyn-menu\" \"DIR\" 0 \"Perform OS command DIR\" 0 0 0 \"OK to perform OS command DIR!\" 1 1 \"CMD /C DIR /W\"

Reply:

Reply status is OK

Then a menu item is added displaying the SDT reference of the selected symbol on standard output (on UNIX), or in the Organizer Log window (in Windows):

On UNIX: serverpc sdle menuadditem \
\"dyn-menu\" \"SDT-ref\" 1 \
\"export SDT ref\" 0 0 1 \
\"\" 1 1 \"echo \'%g\'\"

In Windows: serverpc sdle menuadditen \"dyn-menu\" \"SDT-ref\" 1 \"export SDT-ref\" 0 0 1 \"\" 1 1 \"CMD /C echo %%g\"

Reply:

Reply status is OK

Note that only dimmed if more than one item is selected. Normally a selected symbol includes a selection of in-going and out-going flowlines. These flowlines must be de-selected in order to get the SDT reference of the symbol.

Finally display the file containing the selected symbol on standard output (on UNIX), or in the Organizer Log window (in Windows):

On UNIX: serverpc sdle menuadditem \
\"dyn-menu\" \"filename\" 0 \
\"export filename\" 0 0 1 \
\"\" 1 1 \"ls -ls %a\"

In Windows: serverpc sdle menuadditem \"dyn-menu\" \"filename\" 0 \"export filename\" 0 0 1 \"\" 1 1 \"CMD /C DIR %%a\"

Reply:

Reply status is OK

Extended Object Data Attributes (UNIX only)

The SDL suite allows external attributes to be added to SDL suite objects. These extensions are persistent. That is, they are stored in the normal SDL diagram files and could be used at subsequent sessions. This UNIX only example gives a brief introduction to such extended attributes.

An description of extended attributes are found in "Extended Data Attribute" . Extended attributes are handled as binary data by the SDL suite. As such, their services are preferably accessed via C program interface, in which binary data is easily handled.

However, in this example extended attribute services are accessed via the Service Encapsulator, which works for simple examples.

The example assumes one selection in an SDL Editor. This reference is saved in a shell variable

set ref=`serverpc sdle obtainsource`

If we have exactly one selection, we set the extended attribute. Parameter 9 will give us the SDT reference.

serverpc sdle createattribute 0 0 $ref[9] 0 \
\"myComment\" \"\" 6"\0"MyData

Note that the length of data (MyData) must be manually calculated and that the data part must be preceded by a "\0".

We get the reply:

Reply status is OK

Now we extract the extended attribute on the selection.

serverpc sdle readattribute 0 0 $ref[9]

Which replies:

Reply status is OK
0 "myComment" "" 6MyData

Note that data immediately follows its' length without any spaces. In the reply message, there is a ASCII 0 character after the length, preceding the data part.

Then we update the attribute by;

serverpc sdle updateattribute 0 0 $ref[9] 0 \"newComment\" \"\" 7"\0"NewData

Reply:

Reply status is OK

Finally we read the extended attribute and should receive the updated value.

serverpc sdle readattribute 0 0 $ref[9]

Which replies:

Reply status is OK
0 "NewComment" "" 7NewData

The script extended-attributes performs the above described actions.


Using TTCN Suite Services

This section is meant to exemplify the usage of a few TTCN suite services. The examples are made using the Service Encapsulator described in a previous section. For the complete list of supported services, see "ITEX Services" .

Opened Documents

This command retrieves a list of information about the opened TTCN documents.

serverpc itex openeddocuments

This will yield a list of open TTCN documents (not necessarily shown) that looks like this (see complete list for description of the list format):

Reply status is OK
Doc1:1:/path/doc1.itex:/path/#doc1.itex Doc2:2:/path/doc2.itex:/path/#doc2.itex

If the TTCN environment is not yet started the message will be:

Error sending to postmaster: server not connected to postmaster

Find Table

To use this command the TTCN document in which the table is located must be open.

To invoke the service the following Service Encapsulator command is made:

serverpc itex findtable 1 \"Foo\"

which will search for the table named Foo in the open TTCN document with buffer identifier 1 and open it the Table Editor.

If the table is found the table will be shown and the following message will be returned:

Reply status is OK

If the table can not be found, an error message is issued:

Unable to find object 1 Foo


Integrating Applications with SDL Simulators

An example of utilizing the functionality of the PostMaster is to connect a simulator generated by the SDL suite to another application, typically a user interface (UI). The section "Example of Use (UNIX only)" presents a detailed description of such an example (UNIX only). The sections below concentrate on overall design issues and serves as an introduction to that example.

The communication between an SDL simulator and another application is handled by the PostMaster, and can be seen as occurring on two levels:

  • Sending and receiving SDL signals
  • Sending and receiving PostMaster messages, containing the SDL signals

These two levels of communication are described further below.

Transferring SDL Signals

A simulator communicates with the world outside by sending and receiving SDL signals to/from its environment. For another application to communicate with the simulator, it must also be able to interpret those SDL signals, and to send and receive them. This includes mapping the information contained in the SDL signal (name and parameters) to components and actions in the UI, e.g. invoking a command or changing the contents of an output field.

To ensure successful communication with an SDL simulator, the SDL signal interface to the environment should be designed with regard to the connected applications. Decisions made when designing a UI can influence the design of the simulator interface, and vice versa. It is important to have a clearly defined signal interface to the applications that will communicate with the simulator.

Transferring PostMaster Messages

The PostMaster communicates with different tools by sending messages of a defined format. The SDL signals must therefore be transformed to PostMaster messages before they can be transferred between the tools. A few predefined PostMaster messages are available for the purpose of handling SDL signals.

Each tool designed to communicate by using SDL signals must have an interface to the PostMaster that handles the transformation to and from an appropriate message.

In the case of an SDL simulator, this interface is generated automatically. To invoke the transformation, so that SDL signals to and from the environment are transferred using the PostMaster, the monitor command Start-SDL-Env is to be used.

For other tools, the interface to the PostMaster must be implemented separately. The interface must use functions described later in this section to connect to the PostMaster, and to send and receive PostMaster messages containing SDL signals. This includes packing the information contained in the SDL signal (name and parameters) so that it can be sent using a PostMaster message, and unpacking the same information of a received message. See "Input and Output of Data Types" for more information on suitable data formats.

Example of Use (UNIX only)

This section describes an example of how to connect a user interface (UI) to an existing SDL simulator. The simulated system used in the example is the well-known Demon game, described in "The Demon Game. All necessary code for the example is provided with the release.

The DemonGame simulator is connected through the PostMaster to a control program, consisting of two parts; an interface to the PostMaster and a user interface (see Figure 165).

The PostMaster interface establishes a connection to the PostMaster and communicates with the DemonGame simulator. Messages are sent via the PostMaster to the simulator where they are seen as SDL signals coming from the environment. Correspondingly, SDL signals to the environment are sent via the PostMaster as messages back to the PostMaster interface.

The UI facilitates sending and receiving of the SDL signals sent to and from the environment in the Demon game. A command-based UI (written in C) is implemented. However, the ideas are general and could be used if a graphical user interface is to be used. The UI must be able to forward the SDL signals Newgame, Endgame, Probe and Result, and to present the SDL signals Win, Lose and Score.

Figure 165 : System parts and their communication

Note:

The simulator and the control program have the same communication interface to the PostMaster. The simulator's interface to the PostMaster is generated automatically by the SDL suite.

All C functions, C preprocessor symbols and PostMaster messages used in this example are described in "PostMaster Reference" .

The PostMaster Interface

All communication with the DemonGame simulator is handled by the interface to the PostMaster, a C program called env.c. This program contains the functions Init, Send_to_PM, Receive and Exit_PM, all of which must be called by the UI. Please note that the error handling in this program is very simple and does not comply with the design recommendations mentioned above.

Functions in env.c

  • Init establishes a connection to the PostMaster by calling SPInit, identifying this tool as an SDL environment. The function broadcasts the message SESTARTNOTIFY to inform other tools that this tool has started. Finally it calls Init_UI, a function in the UI.
  • Send_To_PM takes the name of an SDL signal as parameter and broadcasts this signal as an SESDLSIGNAL message to the simulator.
  • Receive calls SPRead to wait for messages from the PostMaster, and acts suitably:
    • If the message contains an SDL signal from the simulator (Score, Lose or Win), it is passed on to the UI by calling Send_To_UI, a function in the UI to present the receipt of the signal. It also returns true in these cases.
    • If the message is a request to stop executing (SESTOP), it is accepted by calling Exit_UI, a function in the UI that in turn calls Exit_PM.
    • If the message is SEOPFAILED, the PostMaster has failed to handle a message properly. You should then decode the message's parameters by calling
  • Exit_PM broadcasts the message SESTOPNOTIFY and breaks the connection to the PostMaster by calling SPExit

Command-Based User Interface

The command-based UI prompts for and recognizes the commands "Newgame", "Endgame", "Probe", and "Result", corresponding to the SDL signals. When any of the SDL signals Score, Win or Lose are received, this information is printed. The command "Exit" exits the program.

The C program for the command-based UI is called command.c. It contains the functions:

  • main
  • GetInput
  • Appl_Receive
  • Init_UI
  • Exit_UI
  • Send_To_UI

Functions in command.c

  • main calls Init in the PostMaster interface, prompts for input and examines the reading state of the file descriptors for the keyboard and the PostMaster message port. If input comes from the keyboard, GetInput is called and any valid SDL signal is sent by calling Send_To_PM in the PostMaster interface. If input comes from the message port, the message is read by calling Appl_Receive.
  • GetInput reads the keyboard and compares the entered string with the available commands. If it is an SDL signal, the function returns true. If "exit" is entered, Exit_UI is called.
  • Appl_Receive simply calls Receive in the PostMaster interface. It is included to make the functional interfaces equivalent for both user interfaces.
  • Init_UI sets a file descriptor for the PostMaster message port and initializes unbuffered terminal output.
  • Exit_UI calls Exit_PM in the PostMaster interface and exits the program.
  • Send_To_UI prints the name of the received signal and any signal parameters on the terminal.

The figures below show how the different functions and other parts in the DemonGame UI communicate with each other.

Figure 166 : Communication diagram

Running the Example

To be able to build and execute the example program, the software provided on the distribution media must first be properly installed.

Building the Tools

This section describes how to build the tools that will communicate via the PostMaster, i.e. the DemonGame simulator and the UI to the simulator.

The tools are provided in source code form and in binary form for the architecture on which you have purchased the SDL suite.

The DemonGame Simulator

In the original implementation of DemonGame provided on the Telelogic Tau CD (in the examples/demongame directory), a design error has deliberately been introduced into the game definition. See "Dynamic Errors for more information.

For the example program to execute correctly, this error must be corrected. New diagrams for the block GameBlock (gameblock.sbk) and the process Main (main.spr) are therefore provided, and are to be used to generate a new simulator. You can find the necessary files in the directory named sdt/examples/simulatorintegration.

  1. Either replace the above diagrams in the original DemonGame implementation, or copy the DemonGame diagrams to a new directory.
  2. Re-generate the simulator from the Organizer in the usual way.
  3. Change to the directory containing the files env.c, command.c, and makefile.
  4. Build the application with the UNIX make command. An executable named command is now created.

Executing a Session

This section describes how to start the communicating tools and initiate a session.

  1. Make sure you have the SDL suite running, so that an instance of the PostMaster is started.
  2. Start the newly generated DemonGame simulator from the Organizer.
  3. Give the following commands to the simulator, preferably by including the provided command file init.sim.
    Start-SDL-Env
    Start handling of the SDL environment. See "Start-SDL-Env" .
    Set-Trace 1
    Restrict trace output to show only signals sent to and from the SDL environment.
    Go
    Start executing the simulation.
  4. Start the command-based UI (command) from the UNIX prompt.
  5. Send SDL signals from the UI by entering the signal name or pushing the corresponding button. (See the description earlier in this section.) Note the trace output in the simulator and the output in the UI.
  6. Exit by entering "exit" or using the File menu.


14 The ASN.1 Utilities

The ASN.1 Utilities perform three main functions in Telelogic Tau:

  • They can translate an ASN.1 module to an SDL package. This makes it possible to use ASN.1 types and values in SDL.
  • They make it possible for the TTCN suite to retrieve external ASN.1 types and values that are used in TTCN.
  • They produce type information for BER coders in SDL.

Note: ASN.1 support in the TTCN suite

The TTCN to C compiler supports only a limited subset of ASN.1. See "TTCN ASN.1 BER Encoding/Decoding for further details on the restrictions that apply.

This chapter is the reference manual for the ASN.1 Utilities.


Introduction

This chapter describes the ASN.1 Utilities. It is assumed that the reader is familiar with ASN.1.

Application Areas for the ASN.1 Utilities

The main foreseen applications of the ASN.1 Utilities are the following:

  • A lot of telecommunication protocols and services are defined using ASN.1. The ASN.1 Utilities make it easier to specify and implement these with SDL.
  • The ASN.1 Utilities enable the SDL suite and the TTCN suite to share common data types by specifying these in a separate ASN.1 module.
  • The ASN.1 Utilities generate type information for BER encoding/decoding for the SDL suite.

Overview of the ASN.1 Utilities

The ASN.1 Utilities support the following main functions:

  1. Perform syntactic and semantic analysis of ASN.1 modules.
  2. Generate SDL code from ASN.1 modules.
  3. Extract the ASN.1 types and values which are referred in the TTCN suite.
  4. Generate type information for BER encoding and decoding for the SDL suite.

For further information about BER encoding and decoding, see ASN.1 Encoding and De-coding in the SDL Suite.

In normal cases, the ASN.1 Utilities are completely hidden for the user by the SDL Analyzer and the TTCN Analyzer.

From the user's point of view, an ASN.1 module is very similar to an SDL package: ASN.1 data types can be defined in a module, and then be used within SDL, using operators that are defined in ITU Recommendation Z.105. When an SDL system containing ASN.1 modules is analyzed, the Analyzer will order the ASN.1 Utilities to translate these modules into corresponding SDL packages.

In the TTCN suite, indirect use of the ASN.1 Utilities is made by the ASN.1-by-reference table. When such a table is analyzed, the TTCN suite orders the ASN.1 Utilities to extract the ASN.1 types and values in a specified ASN.1 module. For more information about this functionality, see "ASN.1 External Type/Value References" .


Using the ASN.1 Utilities

The ASN.1 Utilities are implemented in the executable asn1util. asn1util can be used in two ways:

  1. Stand-alone from the organizer (command-line interface).
  2. Via the PostMaster

Command-Line Interface

Usage: asn1util [options] { <file> [options] }*

Option | Meaning
-h | display a help message
-v | display version
-q | be quiet, suppress some output messages
-c | generate encode/decode type information for the SDL Suite and asn1_cfg.h configuration file
-g | generate coder information for TTCN suite
-B | set BER as default encoding
-P | set PER as default encoding
-N <name> | set <name> as default encoding
-m | include module name in encode/decode type nodes and macros
-n <name> | use <name> for the name of the interface (*.ifc) files
-S <config> | use <config> for type names configuration in (*.ifc) files
-s <file> | generate SDL output in <file>
-a | append the output to an existing file instead of creating a new file
-b | generate SDL body only, i.e. do not generate package headings (makes it possible to import generated SDL with #INCLUDE)
-r | generate references (#SDTREF) to source file
-e | generate all operators for the SDL enumerated type as listed in Z.105. Default is to emit some of the operators in Z.105
-O | generate values for SDL Make operator with optional and default support
-u <package> | add "use <package>;" to all generated SDL packages
-J <name> <files> | Join all ASN.1 modules from <files> into one SDL package <name> (see Example 29)
-K <file> | Perform substitution for keywords listed in <file> (see "Keywords substitution" )
-i <file> | generate TTCN output to <file>
-l <file> | take command line from <file>
-post | wait for commands via the PostMaster (see "PostMaster Interface" )
-T<dir> | put generated code in directory <dir>

Example 27

asn1util -r -s myfile.pr -c myfile.asn
(myfile.asn contains ASN.1 module MyModule)

The command in the example translates the module MyModule in file myfile.asn to an SDL package MyModule in file 'myfile.pr'. The generated package will contain backward references to the source file 'myfile.asn'. Encode/decode type nodes are generated in C-source file 'MyModule_asn1coder.c' and C-header file 'MyModule_asn1coder.h'. A configuration file "asn1_cfg."' with compile switches for coder related files is generated.

Example 28

asn1util AsnModule1.asn AsnModule2.asn

If no options are specified, then asn1util only performs syntactic and global semantic analysis for AsnModule1.asn and AsnModule2.asn, no output is generated.

If no input file is specified, then asn1util does nothing except showing help or version number if correspondent options are specified.

Example 29 Joining modules

asn1util -J Join-Module -s my.pr my1.asn my2.asn

The ASN.1 modules from the files my1.asn and my2.asn will be joined together in the SDL package Join_Module. Name clashes may occur if the same name is available in different ASN.1 modules the filed are joined. These problems are resolved according to a set of name clash resolving rules, see "Joining modules" .

Configuration file generation

For the -c option encode and decode type information is generated to C-files. Also asn1util performs the analysis of ASN.1 types and some features used in the specification and generates file asn1_cfg.h.

This file contains compile switches that are referenced from inside the coders code. When asn1_cfg.h is used by the build process the preprocessor automatically throws away useless parts of the code from encoding and decoding related files. This helps to reduce the code size and improve the performance of encoding and decoding procedures.

For example, if the ASN.1 file does not contain OCTET STRING and SET OF types in the module, the following definitions

#ifdef CODER_AUTOMATIC_CONFIG
#define CODER_NOUSE_OCTET_STRING
#define CODER_NOUSE_SET_OF
#endif

will be included in the configuration file.

This feature can be turned on by the CODER_AUTOMATIC_CONFIG compile switch. For more information about available compile switches for the configuration see "Encoding configuration" .

PostMaster Interface

The ASN.1 Utilities can also be invoked via the PostMaster. An example of this is when an SDL system that uses ASN.1 modules is analyzed. The Analyzer will then order the ASN.1 Utilities, via the PostMaster, to perform a translation of the ASN.1 modules to SDL packages. For a complete description of the PostMaster, see 11 The PostMaster.

On UNIX, the PostMaster communication may also be invoked by starting asn1util with the -post command-line option. asn1util will then wait for commands sent to it from the PostMaster.


Translation of ASN.1 to SDL

This section describes the detailed translation rules from ASN.1 to SDL that are implemented in the ASN.1 Utilities. The translation rules all conform to Z.105, except for the cases described in "Restrictions to Z.105.

General

  • Case sensitivity is according to Z.105, i.e. ASN.1 names are converted directly to SDL names. This implies that in rare cases, correct ASN.1 modules may cause name conflicts when used in SDL.

Note:

Since named numbers, named bits, and integer values are all mapped to integer synonyms, the same name should not be used more than once, because this will lead to name conflicts in SDL.

  • `-' (dash) in ASN.1 names is transformed to `_' (underscore), e.g. long-name in ASN.1 is transformed to long_name in SDL.
  • In accordance with Z.105, tag information is ignored in the translation to SDL.
  • As SDL does not have "in-line types", one ASN.1 type may be mapped to more than one SDL type. The generated in-line types get dummy names.
  • External type/value references are mapped to qualifiers. For example A.a is mapped to <<package A>> a. Also a use clause (use A;) is generated.

Keywords substitution

ASN.1 generators can be configured to be sensitive to a certain number of identifiers. There is a special text file named `asn1util_kwd.txt' that contains a list of identifiers and a list of their substitution during mapping. By default this file is used to configure target languages keywords substitution. It can be edited to get another functionality or another set of keywords to be replaced.

`asn1util_kwd.txt' should contain pairs of identifiers where the first one is the identifier from original ASN.1 specification that will be replaced by the second identifier during generation. `asn1util_kwd.txt' should conform to the following syntax:

Example 30 Configuration file syntax

<identifier1> <identifier1 substitution>
<identifier2> <identifier2 substitution>
...
<identifierN> <identifierN substitution>

ASN.1 Utility reads the first configuration file it finds. It searches for the `asn1util_kwd.txt' file first in the current folder, then in the home folder and finally in the installation. If a configuration file named `asn1util_kwd.txt' is put in the home folder or in the current working folder, it will override the default configuration file from the installation. The configuration file to be used can also be specified in the Analyze dialog or from the command line with the `-K' option (see "Command-Line Interface" ).

Figure 167 : Keywords substitution

`asn1util_kwd.txt' is always present in the installation and it is configured to replace keywords from SDL, TTCN, C and C++ languages: the ASN.1 identifier name, that is a keyword in SDL, TTCN or C++, is replaced by name_SDL_KEYWORD, name_TTCN_KEYWORD or name_CPP_KEYWORD to avoid syntax errors in the target languages (see "Appendix A: List of recognized keywords" ). If an original ASN.1 identifier has been modified, a warning message is reported. See "ERROR 2077 ASN.1 identifier #1 is a keyword, it will be replaced by #2" ).

Note: Keywords recognition

ASN.1 in case-sensitive language and target language keywords are also recognized in case-sensitive mode. If generated SDL is analyzed in case-insensitive mode, there could still be keyword problems left. For example, ASN.1 contains the type named Start and it will not be recognized to be an SDL keyword, because the keyword start will be compared, but in case-insensitive mode Start is still a keyword in SDL, which will result in syntax errors.

Example 31 Keywords default substitution

For these ASN.1 definitions:

CASE ::= ENUMERATED { upper, lower }

T ::= SEQUENCE {
int INTEGER,
explicit BOOLEAN,
case CASE,
signal INTEGER
}

value1 T ::= {
int 5,
explicit TRUE,
case lower,
signal 27 }

With default keywords substitution file the following SDL is generated:

newtype CASE_TTCN_KEYWORD
literals upper,lower
operators
ordering;
endnewtype;

newtype T struct
int_CPP_KEYWORD Integer;
explicit_CPP_KEYWORD Boolean;
case_CPP_KEYWORD CASE_TTCN_KEYWORD;
signal_SDL_KEYWORD Integer;
endnewtype;

synonym value1 T = (. 5, true, lower, 27 .);

A configuration file allows the user to control the set of keywords to be replaced. Removing lines with TTCN keywords, for example, will switch off TTCN keywords sensitivity. Providing an empty configuration file will result in switching off keywords substitution completely.

Module

  • An ASN.1 module is translated to an SDL package as specified in Z.105. The DefinitiveIdentifier (object identifier after module name) is ignored. The tag default is also ignored.
  • EXPORTS is mapped to a corresponding interface-clause.
  • IMPORTS is mapped to a corresponding package reference clause. The AssignedIdentifier (object identifier after module name) is ignored.

Note:

On UNIX, the -b option disables generation of package/endpackage, interface and use clauses. Files that have been generated this way can be included in SDL with the #INCLUDE directive, see "Including PR Files" .

Example 32

MyModule DEFINITIONS ::= BEGIN

EXPORTS A, b, C;
IMPORTS X, Y, z FROM SomeModule { iso 3 0 8 }
...
END

is mapped to

package MyModule;
interface newtype A, synonym b, newtype C;
use SomeModule / newtype X, newtype Y, synonym z;
...
endpackage;

Joining modules

Mapping for ASN.1 original module structure can be changed by applying joining module functionality. Several ASN.1 modules can be generated into one SDL package, if ASN.1 modules are arranged into groups in the Organizer. Joining modules can also be controlled from the command line (see "Command-Line Interface" ).

Figure 168 : Joining modules

Joining means throwing away all import/export clauses and module headers and generating all module bodies into one big package with the name specified in the Organizer or command line interface.

When joining definitions from several ASN.1 modules into one SDL package, names in the resulting SDL package change according to the following rules:

  • Clashed names are prefixed by the original ASN.1 module name
  • Package names in the external references are replaced by the join package name

Example 33

M1
DEFINITIONS ::=
BEGIN

IMPORTS S2 FROM M2;

T ::= SET OF SEQUENCE { a S2 }
S1 ::= IA5String

END

M2
DEFINITIONS ::=
BEGIN

T ::= SEQUENCE OF SEQUENCE OF M1.S1
S2 ::= BOOLEAN

END

without joining applied ASN.1 modules M1 and M2 are mapped to

use M2/
newtype S2;
package M1; /*#ASN.1 'M1'*/

newtype T
Bag(T_INLINE_0)
endnewtype;

newtype T_INLINE_0 /*#SYNT*/ struct
a S2;
endnewtype;

syntype S1 = IA5String endsyntype;

endpackage M1;

package M2; /*#ASN.1 'M2'*/

newtype T
String (T_INLINE_0, emptystring)
endnewtype;

newtype T_INLINE_0 /*#SYNT*/
String (<<package M1>>S1, emptystring)
endnewtype;

syntype S2 = Boolean endsyntype;

endpackage M2;

with joining to package Join-Package applied ASN.1 modules are mapped to

package Join_Package; /*#ASN.1 'Join_Package'*/

newtype M1_T
Bag(M1_T_INLINE_0)
endnewtype;
newtype M1_T_INLINE_0 /*#SYNT*/ struct
a S2;
endnewtype;
syntype S1 = IA5String endsyntype;

newtype M2_T
String (M2_T_INLINE_0, emptystring)
endnewtype;
newtype M2_T_INLINE_0 /*#SYNT*/
String (<<package Join_Package>>S1, emptystring)
endnewtype;
syntype S2 = Boolean endsyntype;

endpackage Join_Package;

General Type and Value Assignment

A type assignment is mapped to a newtype or a syntype, depending on the type on the right-hand side of the `::='. Tags are ignored. An ASN.1 value assignment is mapped to a synonym.

Example 34

T1 ::= INTEGER
T2 ::= [APPLICATION 28] T1
a BOOLEAN ::= TRUE

is mapped to

syntype T1 = Integer endsyntype;
syntype T2 = T1 endsyntype;
synonym a Boolean = True;

Inline types naming

The ASN.1 language can use type definitions inside composite types, which are called inline types. Inline types are not allowed in SDL. In SDL, only named types can be used in a composite type. Implicit names are assigned to ASN.1 inline types and they are referenced by this name in SDL.

Implicit names for generated SDL have the following syntax: <parent_definition_name>_INLINE_<counter>, where parent_definition_name is either the name of the parent type or the name of the parent value, depending on if inline type exists in type or value assignment construct in ASN.1.

Example 35

T1 ::= SEQUENCE {
a SET OF INTEGER,
b CHOICE { x BIT STRING,
y OCTET STRING },
c ENUMERATED { sat, sun } }

For type T the following inline types will be generated to SDL

newtype T1 struct
a T1_INLINE_0;
b T1_INLINE_1;
c T1_INLINE_2;
endnewtype;

newtype T1_INLINE_0 /*#SYNT*/
Bag(Integer)
endnewtype;

newtype T1_INLINE_1 /*#SYNT*/ choice
x Bit_string;
y Octet_string;
endnewtype;

newtype T1_INLINE_2 /*#SYNT*/
literals sat,sun
operators
first: T1_INLINE_2 -> T1_INLINE_2;
last: T1_INLINE_2 -> T1_INLINE_2;
succ: T1_INLINE_2 -> T1_INLINE_2;
pred: T1_INLINE_2 -> T1_INLINE_2;
num: T1_INLINE_2 -> Integer;
ordering;

<operator definitions>

endnewtype;

Example 36

T2 SEQUENCE OF INTEGER ::= { {1,1} | {2,2} }

For T2 the following inline types will be generated to SDL

newtype T2 /*#SYNT*/
String (Integer, emptystring)
constants ((. 1, 1 .)), ((. 2, 2 .))
endnewtype;

Example 37

val BIT STRING ( SIZE(3) ) ::= `101'B

synonym val val_INLINE_0 = bitstr('101');

syntype val_INLINE_0 = Bit_string constants size (3) endsyntype;

Note:

SDL inline names can change if you change within the parent type or value in the ASN.1 specification, the counter can differ. If these names are used within an SDL system, then you must update the SDL system.

Boolean, NULL, and Real

BOOLEAN, NULL and REAL are mapped to the corresponding SDL types. Value notations for these types are mapped as follows
ASN.1 type
ASN.1 value
Corresponding SDL value

 ANY
not supported (conform Z.105)

 BOOLEAN

 TRUE
 FALSE
True
False

 NULL

 NULL
NULL

 REAL

 0
 PLUS-INFINITY
 MINUS-INFINITY
 { mantissa 31416,
base 10, exponent
-4 }
0.0
PLUS_INFINITY
MINUS_INFINITY
3.1416

If a REAL value has an exponent bigger than 1000 and if the mantissa is not zero, then it is mapped to PLUS_INFINITY or MINUS_INFINITY. If a REAL value has an exponent less than -1000, then it is mapped to 0.

Bit String

BIT STRING is mapped to the Z.105-specific type Bit_string. Named bits are mapped to integer synonyms. Values for bit strings are mapped to hexstr/bitstr expressions.

Example 38

B ::= BIT STRING { bit0(0), bit23(23) }

b1 BIT STRING ::= `011 1110'B
b2 BIT STRING ::= `3AFC'H

is mapped to

syntype B = Bit_string endsyntype;
synonym bit0 Integer = 0;
synonym bit23 Integer = 23;

synonym b1 Bit_string = bitstr(`0110 1110');
synonym b2 Bit_string = hexstr(`3AFC');

Note:

Bit_string, as opposed to most other string types in SDL, has indices starting with 0!

Type Bit is a Z.105 specific type with literals 0 and 1, and with boolean operators.

Available operators:

bitstr : Charstring -> Bit_string;
/* converts a Charstring consisting of `0' and
`1'-s to a Bit_string */
hexstr : Charstring -> bit_string;
/* converts a Charstring consisting of
hexadecimal characters to a bit_string */
"not" : Bit_string -> Bit_string;
"and" : Bit_string, Bit_string -> Bit_string;
"or" : Bit_string, Bit_string -> Bit_string;
"xor" : Bit_string, Bit_string -> Bit_string;
"=>" : Bit_string, Bit_string -> Bit_string;
/* bitwise logical operators */
mkstring : Bit -> Bit_string;
length : Bit_string -> Integer;
first : Bit_string -> Bit;
last : Bit_string -> Bit;
"//" : Bit_string, Bit_string -> Bit_string;
extract : Bit_string, Integer -> Bit;
modify! : Bit_string, Integer, Bit-> Bit_string;
substring : Bit_string, Integer, Integer ->
Bit_string;
/* normal String operators, except that index
starts with 0;
see also "Sequence of Types" */

Character Strings

PrintableString, NumericString, VisibleString, and IA5String (i.e. all ASN.1 character string types with character sets that are a subset of ASCII) are mapped to syntypes of SDL Charstring. Values for these strings are mapped to corresponding Charstring synonyms in SDL.

The same operators as for Charstring are available for these types, and values of these types can be assigned freely to each other without need for conversion operators.

For example, in SDL an IA5String value can be assigned to a NumericString variable (given that the IA5String only contains numeric characters).

Choice Types

A CHOICE type is mapped to the choice-construct that is described in more detail in "Choice" .

Example 39

C ::= CHOICE {
a INTEGER,
b BOOLEAN}

c C ::= a:7

is mapped to

newtype C choice
a Integer;
b Boolean;
endnewtype;

synonym c C = a:7

The operators that are available for a CHOICE type are (assuming that C is defined as in Example 39 above):

aextract! : C -> Integer;
/* e.g. c!a returns 7 */
bextract! : C -> Boolean;
/* but c!b gives dynamic error! */
amake! : Integer -> C;
bmake! : Boolean -> C;
/* build choice value, e.g. in SDL
it is possible to write b:True */
amodify! : C, Integer -> C;
/* e.g. var!a := -5 */
bmodify! : C, Boolean -> C;
presentextract! : C -> xxx;
/* returns the selected field.
xxx is an anonymous type with values a and b.
E.g. c!present gives a */

Enumerated Types

An ENUMERATED type is mapped to a newtype with a set of literals plus some operators. By default only ordering operators are generated, use command line option -e to get the rest. The list of literals that is generated is reordered in accordance with the associated integer values.

Example 40

N ::= ENUMERATED { yellow(5), red(0), blue(6) }

is mapped to (only signature of operators shown)

newtype N
literals red, yellow, blue
/* note that the literals have been reordered! */
operators
ordering;
first: N -> N;
last: N -> N;
succ: N -> N;
pred: N -> N;
num: N -> Integer;
endnewtype,

The operators that are available for an ENUMERATED type are (assuming that N is defined as in Example 40 above):

num : N -> Integer;
/* num(yellow)=5, num(red)=0, num(blue)=6 */
"<" : N, N -> Boolean;
"<=": N, N -> Boolean;
">" : N, N -> Boolean;
">=": N, N -> Boolean;
/* comparison based on num, i.e. red < yellow */
pred: N -> N;
succ: N -> N;
/* predecessor/successor based on num, i.e.
succ(red)=yellow, succ(yellow)=blue,
pred(red) gives a dynamic error */
first: N -> N;
last : N -> N;
/* first/last element based on num, i.e.
first(red)=red, last(red)=blue */

Integer

INTEGER is mapped to the SDL Integer type, and ASN.1 integer values are mapped to corresponding SDL values.

Named numbers are mapped to synonyms.

Example 41

A ::= INTEGER { a(5), b(7) }

is mapped to

syntype A = Integer endsyntype;
synonym a Integer = 5;
synonym b Integer = 7;

Object Identifier

OBJECT IDENTIFIER is mapped to the Z.105-specific type Object_Identifier. The normal String operators are available for Object_Identifier, listed also in "Sequence of Types" . Indices start as usual with 1.

Octet String

OCTET STRING is mapped to the Z.105-specific type Octet_string. Octet_string is based on type Octet. This type is further described in "SDL Predefined Types" . The mapping for the octet string value notation to SDL is identical to bit strings, see "Bit String" .

Note:

Octet_string, has indices starting with 1.

Operators available:

bitstr : Charstring -> Octet_string;
hexstr : Charstring -> Octet_string;
/* conversion from Charstring to Octet_string,
see also "Bit String" */
bit_string : Octet_string -> Bit_string;
octet_string: Bit_string -> Octet_string;
/* conversion operators
Octet_string <-> Bit_string */
mkstring : Octet -> Octet_string;
length : Octet_string -> Integer;
first : Octet_string -> Octet;
last : Octet_string -> Octet;
"//" : Octet_string, Octet_string ->
Octet_string;
extract! : Octet_string, Integer -> Octet;
modify! : Octet_string, Integer, Octet ->
Octet_string;
substring : Octet_string, Integer, Integer ->
Octet_string;
/* normal String operators, see also
"Sequence of Types" */

Sequence/Set Types

SEQUENCE and SET are both mapped to SDL struct. From an SDL point of view there is no difference between SEQUENCE and SET. In order to support optional and default components, SDL has been extended with corresponding concepts.

Note:

Optional and default fields in struct are both non-standardized extensions to SDL.

Values are mapped to the "(. ... .)" construct (= Make! operator). Values for optional and default components are not supported. Instead, SDL tasks should be used to assign optional and default components.

Example 42

S ::= SEQUENCE {
a INTEGER OPTIONAL,
b BOOLEAN,
c IA5String DEFAULT "xyz" }

s S ::= { b TRUE }

is mapped to

newtype S struct
a Integer optional;
b Boolean;
c IA5String := `xyz';
endnewtype;

synonym s S = (. True .);

The operators that are available for a SEQUENCE or SET type are (assuming that S is defined as in Example 42 above):

make! : Boolean -> S;
/* builds a value for S */
aextract!: S -> Integer;
bextract!: S -> Boolean;
cextract!: S -> IA5String;
/* Extract operators. Note that aextract! gives
dynamic error if the field has not been set */
amodify! : S, Integer -> S;
bmodify! : S, Boolean -> S;
cmodify! : S, IA5String -> S;
/* Modify operators change one component
in a Sequence/Set */
apresent : S -> Boolean;
/* gives True if component a has been assigned
a value, e.g. aPresent(s) = False */

Sequence of Types

SEQUENCE OF is mapped to the String generator. Values are mapped to corresponding synonyms.

Example 43

S ::= SEQUENCE OF INTEGER
s1 S ::= { 3, 2, 5 }
s2 S ::= {}

is mapped to

newtype S
String (Integer, Emptystring)
endnewtype;

synonym s1 S = (. 3, 2, 5 .);
synonym s2 S = (. .);

The normal String operators are available for Sequence types. Indices start at 1.

The operators that are available for a SEQUENCE OF type are (assuming that S is defined as in Example 43 above):

mkstring : Integer -> S;
/* make a sequence of one item */
length : S -> Integer;
/* returns number of elements in sequence */
first : S -> Integer;
/* returns first element in sequence */
last : S -> Integer;
/* returns last element in sequence
"//" : S, S -> S;
/* returns concatenation of two sequences */
extract! : S, Integer -> Integer;
/* returns the indexed element */
modify! : S, Integer, Integer -> S;
/* modify the indexed element */
substring : S, Integer, Integer -> S;
/* Substring(S, i, l) returns substring of S
of length l, starting at index i */
make! : * Integer -> S;
/* adds the included elements to the string,
* corresponds to (. .) */
append : in/out S, Integer;
/* appends one element to the string */

Set of Types

SET OF is mapped to the Z.105 specific Bag generator. For a more complete description of the Bag generator, see "Bag" .

Example 44

S ::= SET OF INTEGER
s1 S ::= { 2, 2, 5 }
s2 S ::= {}

is mapped to

newtype S
Bag (Integer)
endnewtype;

synonym s1 S = (. 2, 2, 5 .);
synonym s2 S = (. .);

The operators that are available for a SET OF type are (assuming that S is defined as in Example 44 above):

incl : Integer, S -> S;
/* add an element to the bag */
del : Integer, S -> S;
/* delete one element */
incl : Integer, in/out S;
del : Integer, in/out S;
length : S -> Integer;
/* returns number of elements */
take : S -> Integer;
/* return some element from the bag */
take : S, Integer -> Integer;
/* return the indexed element in the bag */
makebag : Integer -> S;
/* build a bag of one element */
"in" : Integer, S -> Boolean;
/* gives true if the element is in the bag */
"<" : S, S -> Boolean;
">" : S, S -> Boolean;
"<=" : S, S -> Boolean;
">=" : S, S -> Boolean;
/* subset/superset comparison operators */
"and" : S, S -> S;
"or" : S, S -> S;
/* intersection/union operators */
make! : * Integer -> S;
/* adds the included elements to the bag,
* corresponds to (. .) */

Useful Types

The types GeneralizedTime and UTCTime have been defined in terms of ASN.1 as specified in X.680. It follows from their definition in X.680, together with the information about the translation rules given in this chapter, which operators are available in SDL for these types.

Constrained Types

Constrained types are mapped to sdl syntypes of the associated parent sort. Value constraints are mapped to sdl range condition.

When specifying ASN.1 value constraints, several constructs can be used that are not supported in the SDL suite, such as ALL EXCEPT,INCLUDES <subtype> and value range with MIN or MAX endpoint. Possible values for such a type are computed and mapped to syntype with range condition represented by a sequence of open and closed ranges.

Example 45

T ::= INTEGER ( (1..10) EXCEPT 8 )

T1 ::= INTEGER ( INCLUDES T EXCEPT (3..<6) )

is mapped to

syntype T = Integer
constants 9 : 10, 1 : 7
endsyntype;

syntype T1 = Integer
constants 9 : 10, 6 : 7, 1 : 2
endsyntype;

"COMPONENTS OF" and "WITH COMPONENT" constraints are mapped by using extra inline types. If the present constraint is applied to the parent type, then the new type is generated excluding fields marked as ABSENT and including fields marked as PRESENT.

Example 46

T ::= SEQUENCE {
a INTEGER,
b IA5String
}

T1 ::= T ( WITH COMPONENTS {
a (-5..5),
b (SIZE (7))
} )

is mapped to

newtype T struct
a Integer;
b IA5String;
endnewtype;

newtype T1 struct
a T1_INLINE_0;
b T1_INLINE_1;
endnewtype;

syntype T1_INLINE_0 = Integer constants -5 : 5
endsyntype;

syntype T1_INLINE_1 = IA5String constants size(7)
endsyntype;

Example 47

T ::= SET OF BIT STRING

T1 ::= T ( WITH COMPONENT (SIZE (5)) )

is mapped to

newtype T
Bag(Bit_string)
endnewtype;

syntype T1 = T1_INLINE_0 endsyntype;

newtype T1_INLINE_0 /*#SYNT*/
Bag(T1_INLINE_1)
endnewtype;

syntype T1_INLINE_1 = Bit_string
constants size (5)
endsyntype;

Example 48

T ::= SET {
a INTEGER OPTIONAL,
b REAL OPTIONAL
}
T1 ::= T ( WITH COMPONENTS {
a (0..<MAX) PRESENT,
b ABSENT
} )

is mapped to

newtype T struct
a Integer optional;
b Real optional;
endnewtype;

newtype T1 struct
a T1_INLINE_0;
endnewtype;

syntype T1_INLINE_0 = Integer constants >=0
endsyntype;

Note:

According to ASN.1, the types T and T1 are compatible, because they are derived from each other. In SDL these are different types and values of type T can not be assigned to type T1.

ASN.1 SET OF and SEQUENCE OF types with SIZE or single value constraints are mapped to one SDL type with constraint without introducing any extra inline types.

Example 49

T1 ::= SEQUENCE SIZE (5..15) OF INTEGER

T2 ::= SEQUENCE ( { 1 } | {} ) OF INTEGER

T3 ::= SET (SIZE (MIN .. <100) ) OF BOOLEAN

T4 ::= SET (SIZE (15) | { ''B } ) OF BIT STRING

is mapped to

newtype T1
String(Integer, emptystring)
constants size (5 : 15)
endnewtype;

newtype T2
String(Integer, emptystring)
constants ((. .)), ((. 1 .))
endnewtype;

newtype T3
Bag(Boolean)
constants size (<=99)
endnewtype;

newtype T4
Bag(Bit_string)
constants ((. bitstr('') .)), size (15)
endnewtype;

Extensibility

Extensibility was introduced in X.680 (1997). In ASN.1 extensibility is represented with extension markers and extension addition groups, that can be specified inside SET, SEQUENCE, CHOICE, ENUMERATED types and constraints.

Extension markers are not visible in SDL translations. All square brackets are ignored and all components from extension addition groups are translated into SDL as individual fields. All required components from extension additions, individual or from extension addition groups are mapped to optional ones.

Example 50

S1 ::= SET
{
x [100] INTEGER,
... ,
[[
gr11 REAL
]],
t BIT STRING,
[[
gr21 BOOLEAN OPTIONAL,
gr22 SET OF INTEGER
]],
... ,
y INTEGER
}

is mapped to SDL

newtype S1 struct
x Integer;
gr11 Real optional;
t Bit_string optional;
gr21 Boolean optional;
gr22 S1_INLINE_1 optional;
y Integer;
endnewtype;

newtype S1_INLINE_1 /*#SYNT*/
Bag(Integer)
endnewtype;

Note:

SDL translation removes the borders of additional groups and makes all required components optional.The semantics for assigning values to types with additional groups are: either the whole addition group ( [[ .... ]] ) is absent, or it is all present unless components inside the group are optional. This is not checked in SDL tools but inconsistency will cause errors in ASN.1 encoding.

Extension markers are ignored in constraints. If both root and additional constraints are present, they are translated to the union constraint.

Example 51

T1 ::= INTEGER ( 1..10 ^ 2..20, ... , 12 )

is mapped to SDL

syntype T1 = Integer constants 12, 2 : 10 endsyntype;

T2 ::= INTEGER (1 | 3, ... )

is mapped to SDL

syntype T2 = Integer constants 3, 1 endsyntype;

Information from Object Classes, Objects and Object Sets

Object classes, object and objects sets are not translated to SDL. Only types and values are translated to SDL, but it is possible in ASN.1 to use information from object classes, objects and object sets when specifying types and values. This information is translated into SDL.

ObjectClassFieldType

ObjectClassFieldType is a reference to object class and a field in that class. The translation to SDL depends on the kind of field name used.

An open type is defined if the field name references a type field, a variable type value field or variable type value set field. An open type can be any ASN.1 type. Open types are translated to Octet_string types in SDL.

Example 52

OPERATION ::= CLASS {
&ArgumentType,
&arg &ArgumentType
}

T1 ::= SEQUENCE { a OPERATION.&ArgumentType }

is translated to SDL

newtype T1 struct
a T1_INLINE_0;
endnewtype;

syntype T1_INLINE_0 = Octet_string endsyntype;

T2 ::= OPERATION.&arg

is translated to SDL

syntype T2 = Octet_string endsyntype;

If the field name in the class references a fixed type value or fixed type value set fields, then the fixed type is used when translated to SDL.

Example 53

OPERATION ::= CLASS {
&ValueSet INTEGER
}

T ::= OPERATION.&ValueSet

is translated to SDL

syntype T = Integer endsyntype;

ObjectClassFieldType with table constraint (object set constraint)

Table constraint applied to ObjectClassFieldType restricts the set of possible types or values to those specified in a column of the table. A table corresponds to an object set. The columns of the table correspond to the object class fields and the rows correspond to the objects in the set.

If the field name in ObjectClassFieldType is a type field and constrained with a table, then it is translated to a CHOICE type with fields of the types specified in the table column. The names of the fields in the choice are the same as the names of the types in the column but the first letter is changed from upper case to lower case.

Note: Field names

If the type in the field is inline then the name in the field will be an implicitly generated inline name, like t_INLINE_4.

If the field name in ObjectClassFieldType is a fixed type value or a fixed type value set, then this is translated to a constrained type where only values that are specified in the table column are permitted.

If the field name in ObjectClassFieldType is a variable type value or variable type value set field, then this is translated to a CHOICE type with types, that are constrained to have values specified in the corresponding cell in the same row of the table.

Example 54

OPERATION ::= CLASS {
&ArgumentType,
&operationCode INTEGER UNIQUE,
&ValueSet INTEGER,
&ArgSet &ArgumentType
}

The My-Operations object set

Object name | &ArgumentType | &operationCode | &ValueSet | &ArgSet
operationA | INTEGER | 1 | {1 | 2 | 5 .. 8} | { 111..444 }
operationB | SET OF INTEGER | 2 | { 2 .. 8 } | { {1,2,3} | { 888 } }

C1 ::= OPERATION.&ArgumentType ( {My-Operations} )

is translated to SDL

newtype C1 choice
integer Integer;
c1_INLINE_2 C1_INLINE_1;
endnewtype;

newtype C1_INLINE_1 /*#SYNT*/
Bag(Integer)
endnewtype;

C2 ::= OPERATION.&operationCode ( {My-Operations} )

is translated to SDL

syntype C2 = Integer constants 2, 1 endsyntype;

C3 ::= OPERATION.&ValueSet ( {My-Operations} )

is translated to SDL

syntype C3 = Integer constants 2 : 8, 1, 5 : 8, 2 endsyntype;

C4 ::= OPERATION.&ArgSet ( {My-Operations} )

is translated to SDL

newtype C4 choice
c4_INLINE_1 C4_INLINE_1;
c4_INLINE_1 C4_INLINE_2;
endnewtype;

syntype C4_INLINE_1 = Integer constants 111 : 444 endsyntype;

syntype C4_INLINE_2 /*#SYNT*/
Bag(Integer)
constants ((. 888 .)), ((. 1, 2, 3 .))
endsyntype;

If an open type is constrained by the table for which all type settings are omitted, then it is translated to SDL Octet_string instead of an empty CHOICE type.

Example 55

MY-CLASS ::= CLASS {
&id INTEGER,
&OpenType OPTIONAL
}

The My-Set object set:

Object name | &id | &OpenType
object1 | 1 | -
object2 | 2 | -

S ::= SEQUENCE {
id MY-CLASS.&id({My-Set}),
val MY-CLASS.&OpenType({My-Set}{@id})
}

is translated to SDL

newtype S struct
id S_INLINE_0;
val S_INLINE_2;
endnewtype;

syntype S_INLINE_0 = Integer constants 2, 1 endsyntype;

syntype S_INLINE_2 = Octet_string endsyntype;

TypeFromObject

TypeFromObject is a reference to an object and a type field in that object. This is simply translated to that type in SDL. If the field is optional in the class and not set in the object, then TypeFromObject cannot be translated.

Example 56

OPERATION ::= CLASS {
&ArgumentType,
&ResultType
}

operationA OPERATION ::= {
&ArgumentType INTEGER,
&ResultType BOOLEAN
}

O1 ::= operationA.&ArgumentType

is translated to SDL

syntype O1 = Integer endsyntype;

O2 ::= operationA.&ResultType

is translated to SDL

syntype O2 = Boolean endsyntype;

ValueSetFromObject

ValueSetFromObject is a reference to an object and a field with a set of values in that object. This is translated to a constrained type in SDL, allowing only values from the value set.

Example 57

OPERATION ::= CLASS {
&ValueSet INTEGER
}

operationA OPERATION ::= {
&ValueSet { 1 | 2 | 5..8 }
}

V1 ::= operationA.&ValueSet

is translated to SDL

syntype V1 = Integer constants 2, 5 : 8, 1 endsyntype;

ValueFromObject

ValueFromObject is a reference to an object and a field with a value in that object. This is translated to the same value in SDL.

Example 58

OPERATION ::= CLASS {
&operationCode INTEGER UNIQUE
}

operationA OPERATION ::= { &operationCode 1 }

val2 INTEGER ::= operationA.&operationCode

is mapped to SDL

synonym val2 Integer = 1;

CONSTRAINED BY notation

CONSTRAINED BY is treated like a comment and is not translated to SDL.

Parameterization

Wherever a parameterized type or value is used, it is translated to SDL after all dummy references are replaced by the actual parameters. A parameterized value is also translated after all dummy references are replaced by the actual parameters.

Parameterized assignments are ignored when translating to SDL.

Example 59

Container { ElemType, INTEGER : maxelements } ::=
SET SIZE (0..maxelements ) OF ElemType

Intcontainer ::= Container {INTEGER, 25}

is first internally mapped to

Intcontainer ::= SET SIZE( 0..25 ) OF INTEGER

and then translated to SDL. Container is not translated to SDL.


Support for External ASN.1 in the TTCN Suite

The ASN.1 Utilities are also used by the TTCN suite if a TTCN test suite contains data types and constraints that are defined in the tables "ASN.1 Type Definitions By Reference" and "ASN.1 Constraints By Reference". For more information, see "ASN.1 External Type/Value References" .

Since TTCN is based on the older X.228 standard, while the ASN.1 Utilities are based on the new X.680 standard, users should be careful to use the common subset of X.680 and X.228 if an ASN.1 module is to be used in TTCN. In particular there are a number of differences:

  • In ENUMERATED types, a value must be supplied for all values. For example:
E ::= ENUMERATED { a, b }
should be replaced by
E ::= ENUMERATED { a(0), b(1) }

  • X.680 offers more possibilities for specifying constraints than X.228 does. X.228 does not have the keywords ALL, EXCEPT, UNION, and INTERSECTION.
  • For ASN.1 types that have components (e.g. SET or SEQUENCE), an identifier must be provided for every component (according to X.680), while in X.228 identifiers can be omitted. For example:
S ::= SEQUENCE { INTEGER } -- valid X.228
This is invalid according to X.680. The following should be used instead:
S ::= SEQUENCE { field1 INTEGER }

General

  • `-' (dash) in ASN.1 names is transformed to `_' (underscore), e.g. long-name in ASN.1 is transformed to long_name in TTCN.
  • In general ASN.1 to TTCN translation look like pretty printing of ASN.1 modules into TTCN tables for most of the constructs, but not all of them. Some ASN.1 concepts are not supported in TTCN suite, they have to be modified during TTCN generation:
    • Concepts defined in X.681, X.682 and X.683 (see "Information from Object Classes, Objects and Object Sets" , "CONSTRAINED BY notation" and "Parameterization" )
    • automatic tagging (see "Keywords substitution" )
    • COMPONENTS OF Type notation (see "COMPONENTS OF Type notation" )
    • selection types (see "Selection types" )
    • enumerated types without numbers for enum identifiers (see "Enumerated types" )
    • extensibility (see "Extensibility" )

Keywords substitution

ASN.1 generators can be configured to be sensitive to a certain number of identifiers. There is a special text file named `asn1util_kwd.txt' that contains a list of identifiers and a list of their substitution during mapping. By default this file is used to configure target languages keywords substitution. It can be edited to get another functionality or another set of keywords to be replaced.

`asn1util_kwd.txt' should contain pairs of identifiers where the first one is the identifier from the original ASN.1 specification that will be replaced by the second identifier during generation. `asn1util_kwd.txt' should conform to the following syntax:

Example 60 Configuration file syntax

<identifier1> <identifier1 substitution>
<identifier2> <identifier2 substitution>
...
<identifierN> <identifierN substitution>

ASN.1 Utility reads the first configuration file it finds. It searches for `asn1util_kwd.txt' file first in the current folder, then in the home folder and finally in the installation. If a configuration file named `asn1util_kwd.txt' is put in the home folder or in the current working folder, it will override the default configuration file from the installation. The configuration file to be used can also be specified in the command line with the `-K' option (see "Command-Line Interface" ), for example,

Example 61 Configuration file specification

asn1util -K my_config.txt -i File.ttcn File.asn

`asn1util_kwd.txt' is always present in the installation and it is configured to replace keywords from the SDL, TTCN, C and C++ languages: the ASN.1 identifier name, that is a keyword in SDL, TTCN or C++, is replaced by name_SDL_KEYWORD, name_TTCN_KEYWORD or name_CPP_KEYWORD to avoid syntax errors in the target languages (see "Appendix A: List of recognized keywords" ). If an original ASN.1 identifier has been modified, a warning message is reported. See "ERROR 2077 ASN.1 identifier #1 is a keyword, it will be replaced by #2" ).

Example 62 Keywords default substitution

For these ASN.1 definitions:

CASE ::= ENUMERATED { upper, lower }

T ::= SEQUENCE {
int INTEGER,
explicit BOOLEAN,
case CASE,
signal INTEGER
}

value1 T ::= {
int 5,
explicit TRUE,
case lower,
signal 27 }

With default keywords substitution file the following TTCN is generated:

CASE_TTCN_KEYWORD ::=
ENUMERATED {upper(0), lower(1)}

T ::= SEQUENCE {
int_CPP_KEYWORD INTEGER,
explicit_CPP_KEYWORD BOOLEAN,
case_CPP_KEYWORD CASE_TTCN_KEYWORD,
signal_SDL_KEYWORD INTEGER
}

value1 T ::= {
int_CPP_KEYWORD 5,
explicit_CPP_KEYWORD TRUE,
case_CPP_KEYWORD lower,
signal_SDL_KEYWORD 27
}

A configuration file allows user to control the set of keywords to be replaced. Removing lines with SDL keywords, for example, will switch off SDL keywords sensitivity. Providing an empty configuration file will result in switching off keywords substitution completely.

Automatic tagging

If 'AUTOMATIC TAGS' is written in the header of an external ASN.1 module, then implicit tags are inserted into SET, SEQUENCE and CHOICE types. During the TTCN generation they are inserted in the type definitions explicitly.

Example 63

M1
DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
T ::= SEQUENCE
{
a INTEGER OPTIONAL,
b INTEGER DEFAULT 5
}

C ::= CHOICE
{
x INTEGER,
y BOOLEAN,
z REAL
}
END

is translated to TTCN

SEQUENCE
{
a [0] INTEGER OPTIONAL,
b [1] INTEGER DEFAULT 5
}

CHOICE
{
x [0] INTEGER,
y [1] BOOLEAN,
z [2] REAL
}

COMPONENTS OF Type notation

COMPONENTS OF Type can appear in SET or SEQUENCE field types. Instead of COMPONENTS OF Type a list of components of the referenced type is included, except extension addition components.

Example 64

S1 ::= SEQUENCE
{
x INTEGER,
g NULL,
... ,
[[
y BOOLEAN,
z BIT STRING
]],
[[
c IA5String
]],
d SET OF
INTEGER OPTIONAL,
... ,
f REAL
}

S2 ::= SEQUENCE
{
a IA5String,
COMPONENTS OF S1,
b OCTET STRING
}

Type S2 is translated to TTCN

SEQUENCE
{
a IA5String,
x INTEGER,
g NULL,
f REAL,
b OCTET STRING
}

Selection types

A selection type is mapped to the type it denotes.

Example 65

C ::= CHOICE
{
a INTEGER,
b BOOLEAN
}

T1 ::= a < C

T1 is translated to TTCN

INTEGER

T2 ::= b < C

T2 is translated to TTCN

BOOLEAN

Enumerated types

Enumerated items can be defined using "identifier" notation or "identifier and number" notation. For "identifier" notations, implicit numbers are assigned to the identifiers according to the rules described in X.680 (1997), 19.

For TTCN, all enumeration items are generated with their corresponding numbers using "identifier and number" notation, and they are arranged according to their number values in ascending order in the generated enumeration.

Extension markers are ignored.

Example 66

A ::= ENUMERATED { a, b, c(0), d, e(2) }

is translated to TTCN

ENUMERATED { c(0), a(1), e(2), b(3), d(4) }

B ::= ENUMERATED { a, b(3), ... , c(1) }

is translated to TTCN

ENUMERATED { a(0), c(1), b(3) }

Extensibility

Extensibility was introduced in X.680 (1997). In ASN.1 extensibility is represented with extension markers and extension addition groups, that can be specified inside SET, SEQUENCE, CHOICE, ENUMERATED types and constraints.

Extension markers are not visible in TTCN translation. All square brackets are ignored and all components from extension addition groups are translated into TTCN as individual fields. All required components from extension additions, individual or from extension addition groups, are mapped to optional ones.

Example 67

S1 ::= SET
{
x [100] INTEGER,
... ,
[[
gr11 REAL
]],
t BIT STRING,
[[
gr21 BOOLEAN OPTIONAL,
gr22 SET OF INTEGER
]],
... ,
y INTEGER
}

is translated to TTCN

SET
{
x [100] INTEGER,
gr11 REAL OPTIONAL,
t BIT STRING OPTIONAL,
gr21 BOOLEAN OPTIONAL,
gr22 SET OF INTEGER OPTIONAL,
y INTEGER
}

Note:

TTCN translation removes the borders of additional groups and makes all required components optional. The semantics for assigning values to types with additional groups is: either the whole addition group ( [[ .... ]] ) is absent, or it is all present unless components inside the group are optional. This is not checked in TTCN tools but inconsistency will cause errors in ASN.1 encoding.

Extension markers are ignored in constraints. If both root and additional constraints are present, they are translated to the union constraint.

Example 68

T1 ::= INTEGER ( 1..10 ^ 2..20, ... , 12 )

is translated to TTCN

INTEGER (( 1..10 ^ 2..20 ) | ( 12 ) )

T2 ::= INTEGER (1 | 3, ... )

is translated to TTCN

INTEGER (1 | 3 )

Information from Object Classes, Objects and Object Sets

Object classes, object and objects sets are not translated to TTCN. Only types and values are translated to TTCN, but it is possible in ASN.1 to use information from object classes, objects and object sets when specifying types and values. This information is translated into TTCN.

ObjectClassFieldType

ObjectClassFieldType is a reference to an object class and a field in that class. The translation to TTCN depends on the kind of field name used.

An open type is defined if the field name references a type field, a variable type value field or variable type value set field. An open type can be any ASN.1 type. Open types are translated to OCTET STRING types in TTCN.

Example 69

OPERATION ::= CLASS {
&ArgumentType,
&arg &ArgumentType
}

T1 ::= SEQUENCE { a OPERATION.&ArgumentType }

is translated to TTCN

SEQUENCE { a OCTET STRING }

T2 ::= OPERATION.&arg

is translated to TTCN

OCTET STRING

If the field name in the class references a fixed type value or fixed type value set fields, then the fixed type is used when translated to TTCN.

Example 70

OPERATION ::= CLASS {
&ValueSet INTEGER
}

T ::= OPERATION.&ValueSet

is translated to TTCN

INTEGER

ObjectClassFieldType with table constraint (object set constraint)

A table constraint applied to ObjectClassFieldType restricts the set of possible types or values to those specified in a column of the table. A table corresponds to an object set. The columns of the table correspond to the object class fields and the rows correspond to the objects in the set.

If the field name in ObjectClassFieldType is a type field and constrained with a table, then it is translated to a CHOICE type with fields of the types specified in the table column. The names of the fields in the choice are the same as the names of the types in the column but the first letter is changed from upper case to lower case.

Note:

If the type in the field is inline then the name in the field will be an implicitly generated inline name, like t_INLINE_4.

If the field name in ObjectClassFieldType is a fixed type value or a fixed type value set, then this is translated to a constrained type where only values that are specified in the table column are permitted.

If the field name in ObjectClassFieldType is a variable type value or variable type value set field, then this is translated to a CHOICE type with types, that are constrained to have values specified in the corresponding cell in the same row of the table.

Example 71

OPERATION ::= CLASS {
&ArgumentType,
&operationCode INTEGER UNIQUE,
&ValueSet INTEGER,
&ArgSet &ArgumentType
}

The My-Operations object set:

Object name | &ArgumentType | &operationCode | &ValueSet | &ArgSet
operationA | INTEGER | 1 | {1 | 2 | 5 .. 8} | { 111..444 }
operationB | SET OF INTEGER | 2 | { 2 .. 8 } | { {1,2,3} | { 888 } }

C1 ::= OPERATION.&ArgumentType ( {My-Operations} )

is translated to TTCN

CHOICE {
integer INTEGER,
c1_INLINE_2 SET OF INTEGER
}

C2 ::= OPERATION.&operationCode ( {My-Operations} )

is translated to TTCN

INTEGER ( 1 | 2 )

C3 ::= OPERATION.&ValueSet ( {My-Operations} )

is translated to TTCN

INTEGER ( ( 1 | 2 | 5..8 ) | ( 2..8 ) )

C4 ::= OPERATION.&ArgSet ( {My-Operations} )

is translated to TTCN

CHOICE {
c4_INLINE_1 INTEGER ( (111..444) ),
c4_INLINE_2 SET OF INTEGER ( ( {1,2,3} | {888} ) ) }

If an open type is constrained by the table for which all type settings are omitted, then it is translated to TTCN OCTET STRING instead of an empty CHOICE type.

Example 72

MY-CLASS ::= CLASS {
&id INTEGER,
&OpenType OPTIONAL
}

The My-Set object set:

Object name | &id | &OpenType
object1 | 1 | -
object2 | 2 | -

S ::= SEQUENCE {
id MY-CLASS.&id({My-Set}),
val MY-CLASS.&OpenType({My-Set}{@id})
}

is translated to TTCN

SEQUENCE {
id INTEGER ( 1 | 2 ),
val OCTET STRING
}

TypeFromObject

TypeFromObject is a reference to an object and a type field in that object. This is simply translated to the that type in TTCN. If the field is optional in the class and not set in the object, then TypeFromObject cannot be translated.

Example 73

OPERATION ::= CLASS {
&ArgumentType,
&ResultType
}

operationA OPERATION ::= {
&ArgumentType INTEGER,
&ResultType BOOLEAN
}

O1 ::= operationA.&ArgumentType

is translated to TTCN

INTEGER

O2 ::= operationB.&ResultType

is translated to TTCN

BOOLEAN

ValueSetFromObject

ValueSetFromObject is a reference to an object and a field with a set of values in that object. This is translated to a constrained type in TTCN, allowing only values from the value set.

Example 74

OPERATION ::= CLASS {
&ValueSet INTEGER
}

operationA OPERATION ::= {
&ValueSet { 1 | 2 | 5..8 }
}

V1 ::= operationA.&ValueSet

is translated to TTCN

INTEGER ( 1 | 2 | 5..8 )

ValueFromObject

ValueFromObject is a reference to an object and a field with a value in that object. This is translated to the same value in TTCN.

Example 75

OPERATION ::= CLASS {
&operationCode INTEGER UNIQUE
}

operationA OPERATION ::= { &operationCode 1 }

val2 INTEGER ::= operationA.&operationCode

is translated to TTCN

val2 of type INTEGER equal to 1

CONSTRAINED BY notation

CONSTRAINED BY is treated like a comment and is not translated to TTCN.

Parameterization

Wherever a parameterized type or value is used, it is translated to TTCN after all dummy references are replaced by the actual parameters. A parameterized value is also translated after all dummy references are replaced by the actual parameters.

Parameterized assignments are ignored when translating to TTCN.

Example 76

Container { ElemType, INTEGER : maxelements } ::=
SET SIZE (0..maxelements ) OF ElemType

Intcontainer ::= Container {INTEGER, 25}

is mapped to TTCN

SET SIZE ( 0..25 ) OF INTEGER


Error and Warning Messages

This section contains a list of the error and warning messages in the ASN.1 Utilities. Each message has a short explanation and, where applicable, a reference to the appropriate section of the recommendations X.680,X.681,X.682, X.683 or Z.105.

Some messages include a reference to the object that is the source of the diagnostic. These messages adhere to the format adopted in the SDL suite. See 19 SDT References for a reference to this format and for examples.

WARNING 2000 Unknown option `#1'

This warning message indicates that the ASN.1 Utilities were started with an unknown option. See "Command-Line Interface" for an overview of the valid options.

WARNING 2001 No #1 specified after '#2' option

This warning message indicates that the ASN.1 Utilities were started with an illegal combination of options. See "Command-Line Interface" for an overview of the valid options.

For example,

asn1util -s -r MyModule.asn

In this case no output file for sdl generation is specified after '-s' option.

ERROR 2002 Too many errors

This error message indicates that the maximum number of errors was reached when analyzing an ASN.1 module. The analysis has been aborted by the ASN.1 Utilities.

ERROR 2003 Multiple #1 paths

This warning message indicates an incorrect usage of the options of the ASN.1 Utilities.

For example,

asn1util -Tdir1 -Tdir2 -s MyModule.pr MyModule.asn

Multiple target directories provide a warning message

WARNING 2004 Option missing

This warning message indicates that no option is specified after dash.

ERROR 2005 Can not open #1

This error message indicates that an error occurred when the ASN.1 Utilities attempted to open a file. Modify, if necessary, the file protection and try to run the ASN.1 Utilities again. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

For example,

asn1util -Tdir -i MyModule.ttcn MyModule.asn

This command line can cause an error message "Can not open air/MyModule.ttcn" if there is no target directory 'dir' in the catalogue from which asn1util is called.

ERROR 2006 Illegal characters in bstring

This message indicates that an ASN.1 binary string item (used in BIT STRING and OCTET STRING) contains illegal characters. The only characters allowed are `0', `1' and white space characters. (X.680: 9.9)

ERROR 2007 Illegal characters in hstring

This message indicates that an ASN.1 hexadecimal string item (used in BIT STRING and OCTET STRING) contains illegal characters. The only characters allowed are `0'-'9', `A'-'F' and white space characters. (X.680: 9.10)

For example: 'F30C 973D'H is a valid hexadecimal string item.

ERROR 2008 'H' or 'B' expected

This error message indicates that an ASN.1 BIT STRING or OCTET STRING value is not ended with a `B or an `H. (X.680: 9.9 and 9.10).

For example: '0110'B or '1AFC'H are valid values for BIT STRING and OCTET STRING, '01110' is illegal.

ERROR 2009 Unclosed #1 string

This error is reported when there is no closing apostrophe at the end of string

WARNING 2010 Unknown token `#1'

This warning indicates a syntax error in the ASN.1 module.

ERROR 2011 Syntax error

This message indicates a syntax error in the ASN.1 module with syntax from standard X.680-X.683. This could be caused by a misspelling. It could also be caused by X.228 constructs that are not part of X.680.

ERROR 2012 Out of memory

This message indicates that the ASN.1 Utilities ran out of memory. Try to make the ASN.1 module smaller or supply more memory. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

WARNING 2013 No semantic support for `#1'

This warning indicates that an ASN.1 construct is used that is not supported by the ASN.1 Utilities. The construct will be ignored by the ASN.1 Utilities.

ERROR 2014 Export-file `#1' corrupt

This message indicates that the export file format of an ASN.1 module was corrupt or unknown. This error should normally not occur. Contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 2015 Old ASN1,#1

This message indicates that an ASN.1 construct of the older X.228 recommendation is used that has been superseded in the X.680 Recommendation.

For example:

S ::= SEQUENCE { INTEGER }

is old ASN.1. Correct X.680 ASN.1 is:

S ::= SEQUENCE { field1 INTEGER }

ERROR 2016 Recursive expansion of COMPONENTS OF in type #1

This error message indicates that the ASN.1 type uses directly or indirectly COMPONENTS OF itself.

ERROR 2017 Recursive #1

This message indicates that the ASN.1 construct is recursively defined.

For example: T1::=T2, T2::=T1; T::=SET OF T, or v T ::= v

ERROR 2018 Recursive #1 constraint

This error message indicates that type being constrained is recursively used in applied constraint.

For example: I ::= INTEGER ( 1 .. 10 | INCLUDES I)

ERROR 2019 Field '#1' should be initialized by #2

This message is reported when you assign wrong kind of value for the field in the object, for example when you try to assign a value for the type field in the object

ERROR 2020 Value for `#1' can not be #2

This error message indicates a semantic error in the ASN.1 module.

For example, T ::= BIT STRING { a(-1)} causes the error "Value for 'named bit' can not be negative"

WARNING 2021 Construct `#1' has no mapping in SDL

This warning indicates that an ASN.1 construct is used that can not be mapped to SDL.

For example:

S1 SEQUENCE ::= { }

-- empty SEQUENCE/SET

s SEQUENCE { a INTEGER OPTIONAL } ::= {}

-- value for SEQUENCE/SET without components

ERROR 2022 Ambiguous reference, symbol `#1' imported more than once

A value is used that is imported more than once. Use an external value reference to specify unambiguously the module of the value that you want to use.

ERROR 2023 Multiple definition of #1

This error message appears, when the same identifier appears more then once on the right side of assignment.

For example, X ::= INTEGER, X ::= SET OF REAL

ERROR 2024 Exported symbol #1 not defined

This error message is reported when symbol is exported, but it is neither defined in the module nor imported to it

ERROR 2025 Ambiguous export, symbol #1 is imported more than once

This error message indicates that it is impossible to decide which symbol to export, because two symbols with the name #1 are imported to the module

ERROR 2026 Ambiguous export, symbol #1 is defined and imported

This error message indicates that it is impossible to decide which symbol to export, because symbol #1 is defined in the module and imported to it at the same time

ERROR 2027 Nothing known about module #1

This message appears when module referenced from imports clause does not exist. You should specify all modules from which symbols are imported to the analyzed module in the same command line, otherwise it is impossible to perform global semantic analysis

ERROR 2028 Import from empty module #1

This message appears when importing symbols from a module, that does not contain any definitions

ERROR 2029 Module does not export symbols

This message appears when you are trying to import symbols from module with empty export: "EXPORTS ;"

ERROR 2030 Imported symbol #1 is not exported from module #2

This message appears when symbol #1 is present in imports from module #2 clause, but it is not exported from #2. "EXPORTS ;" indicates that nothing is exported, while empty exports clause indicates that all definitions are exported from the module.

ERROR 2031 Imported symbol #1 is not defined in module #2

This error situation occurs when symbol is imported from module that exports all, but symbol is not defined there

ERROR 2032 Ambiguous import, symbol #1 imported more than once to module #2

This indicates that all symbols are exported from module #2, but it is impossible to import symbol #1 from module #2 because symbol #1 is imported more than once to #2. The symbols have the same name, but defined in different modules.

ERROR 2033 Ambiguous import, symbol #1 defined and imported to module #2

This indicates that all symbols are exported from module #2, but it is impossible to import symbol #1 from module #2 due to ambiguity between symbol #1defined in module #2 and symbol #1 imported to module #2.

For example;

M1 DEFINITIONS ::= BEGIN
IMPORTS a FROM M2;
END

M2 DEFINITIONS ::= BEGIN
IMPORTS a FROM M3;
a INTEGER ::=5
END

M3 DEFINITIONS ::= BEGIN
EXPORTS a;
a BOOLEAN ::= TRUE

END

In the above case you can not import a to M1, although a is exported from M2.

ERROR 2034 Multiple declaratiom of module name #2

Module name shall appear only once in IMPORTS clause.

For example

IMPORTS a , b FROM X c FROM X; is wrong ASN.1 declaration

ERROR 2035 Recursive import for #1

This error message is reported, for example, when module A imports T from B, and B imports T from A at the same time

ERROR 2036 Multiple occurance of #1 '#2' in #3

This error is reported when some types are defined incorrectly - they have the same identifier, for example enumeration can not have the same identifiers, named number list for INTEGER type can not have the same identifiers in the list, #2 is a string

ERROR 2037 Multiple occurance of #1 #2 in #3

The same class of error as ERROR 2036 above, but #2 is an integer value.

ERROR 2038 External references are not allowed

When imports clause looks like "IMPORTS ;",no external references are allowed from the module (X.680, 10.14, d), NOTE 2)

ERROR 2039 Referenced #1 '#2' not defined

This error is reported when you use reference that is not assigned value or type anywhere.

ERROR 2040 Value of type #1 needed

This error message indicates that value does not correspond to the type. For example x INTEGER ::= TRUE - this results in an error "Value of type INTEGER needed"

ERROR 2041 #1 type needed after COMPONENTS OF

The type after in COMPONENTS OF expansion should be either SET or SEQUENCE, and it should be the same as the type to which it is extracted.

For example SET { a INTEGER, b COMPONENTS OF T }, where T is SEQUENCE type is wrong usage of COMPONENTS OF notation(X.680, 22.4, 24.2)

ERROR 2042 Field names in type after COMPONENT OF already declared

After performing the COMPONENTS OF transformation, all field names should be distinct.

For example, type S1 is wrong (it has two fields named 'a')

S ::= SET { a INTEGER, b REAL }

S1 ::= SET { a SET OF IA5String, COMPONENTS OF S }

ERROR 2043 #1 type needed

This error is reported when type in selection type is not choice.

For example x < INTEGER does not satisfy that requirement

ERROR 2044 No alternative named #1 in Choice type

This error is reported when type notation is "#1 < type", type is a CHOICE type, but it does not have alternative named #1

ERROR 2045 Too many components

This error message appears when you are trying to assign extra components, which are not defined in the type, when specifying the value of SET or SEQUENCE

ERROR 2046 No such field '#1' in #2 type

This error indicates that type #2 does not have field named #1, but you are trying to assign it a value.

ERROR 2047 Missing values for non-optional #1 fields : #2

This message indicates that not all required #1 components have been initialized in the value, and #2 is the list of names of fields, for which values are missing. The example S ::= SET { a INTEGER, b REAL, c NULL OPTIONAL }, s S ::= { a 57 } results in error message "Missing values for non-optional SET fields: 'b'".

ERROR 2048 More than one #1 for the field '#2'

This error occurs when you are trying to assign more then one component to one field.

For example

T ::= SET { a IA5String , b NULL }

t T ::= { a "val1", b NULL, a "val2" }

ERROR 2049 Nothing known about bit named '#1'

This error is reported when bitstring value contains identifier that is not declared in the correspondent type definition

ERROR 2050 Value for #1 should be #2

If you specify table for the value of IA5String, TableColumn should be in the range from 0 to 7, if this constraint is violated then the above error message is reported

ERROR 2051 Type is required to be derived from #1

This error indicates that type used in SubtypeConstraint is not derived from the type being constrained and thus does not satisfy X.680,45.3.2

ERROR 2052 Can not apply #1 constraint to #2 type

Not all constraints can be applied to every type, X.680, Table 6 describes which constraints can be applied to which types, if the requirements declared in Table 6 are not satisfied, the above error message is reported

ERROR 2053 There shall be at most one #1

Two presents constraints are not allowed when constraining a CHOICE type.

For example:

C ::= CHOICE { a T1 , b T2 } (WITH COMPONENTS {a PRESENT, b PRESENT} )

causes the error message

ERROR 2054 Wrong value : out of constraint

This error is reported when value does not correspond to the constraint applied to the type.

For example: x INTEGER (1..10) ::= -1, x is out of constraint

ERROR 2055 The same tags for #1 components

This error message indicates that type does not correspond to the requirements for distinct tags specified in X.680, 22.5, 24.3, 26.2; If you use AUTOMATIC TAGS in the module, requirement for distinct tags will always be satisfied if automatic tagging has been applied

ERROR 2056 OBJECT IDENTIFIER value should have at least two components

x OBJECT IDENTIFIER ::= { iso } is wrong object identifier value because encode/decode functions require at least two components for object identifier value

WARNING 2057 Construct #1 has no mapping in SDL

This warning is reported if no mapping to sdl exist but it does not prevent further code generation.

ERROR 2058 Construct #1 has no mapping in SDL

This error indicates that no mapping to sdl exist and is fatal for further code generation.

WARNING 2059 Value given for #1 component

This warning indicates that a value has been given to an optional or default component of an ASN.1 SEQUENCE or SET type. Values for optional and default components cannot be translated to SDL.

WARNING 2060 Constraint could have been extended when mapped to sdl

This warning indicates that constraint transformation has been applied when mapping complex ASN.1 constraints to sdl but the sdl type can allow more values than the ASN.1 type. This can occur when there is no exact mapping of ASN.1 constraints.

ERROR 2061 INTERNAL ERROR in #1

This message indicates an error in the implementation in the utilities. Please send a report to Telelogic Customer Support, especially if the error can be reproduced as the only error message of an analysis. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support"

ERROR 2062 Code generation : #1

Error in the generation of SDL, TTCN or encode/decode output.

WARNING 2063 Too big exponent

Exponent in a real value is too big to translate to SDL. This warning message is shown if the exponent is bigger than 1000 or less than -1000.

WARNING 2064 Duplicate synonym name, this synonym will not be mapped to SDL

This message indicates that there are synonym name clashes between named numbers and named bits from INTEGER and BIT STRING types and ASN.1 values if they all will be mapped to SDL (see "Integer" and "Bit String" ), and in order to avoid errors only one synonym will be mapped, others are ignored.

ERROR 2065 Number #1 is already assigned to previously defined enumeration item

This error message is reported when NamedNumber alternative is used in an enumerated type definition in an addition enumeration after extension marker and the number #1 has already been assigned to identifier from root enumeration, for example A ::= ENUMERATED {a,b, ... , c(0)} First corresponding numbers are assigned to identifiers in root enumeration, and then in additional enumeration. The above case is invalid, since both 'a' and 'c' are equal to 0.

ERROR 2066 Value for the field '#1' needed #2

This message indicates that value for the field '#1' is missing, but it should be present in #2

ERROR 2067 #1 omitted in #2

Indicates that #1 is omitted, but it should be present in #2

ERROR 2068 #1 should reference #2

This message indicates that a field name references an object class field that is not allowed to be referenced.

ERROR 2069 Wrong object specification

This message indicates that an object specification is incorrect

ERROR 2070 #1 of class #2 needed

This message indicates that an object or object set does not match the governing object class specified in object or object set's definitions

ERROR 2071 Wrong defined syntax

This message indicates that an error in defined syntax for the object definition

ERROR 2072 #1 can not be used in object set specification

This message indicates that an illegal construct is used in the object set specification

ERROR 2073 #1 in the field '#2' is not specified in the #3

This message is reported when information, for example, type or value, is extracted from object field that has not been initialized in the object. This can occur when the field is optional or default in the object class.

WARNING 2074 #1 is not supported in the encoders / decoders

This warning message is reported when ASN.1 notation is used that the encoder / decoder library cannot support

ERROR 2075 #1 can be used only for #2

This message is reported when #1 is used in a component relation constraint but is not allowed to be used in that context.

ERROR 2076 #1

This is used for several different messages concerning component relation constraint, each message is listed and explained below:

Referenced component should refer to the same object class as the referencing one

This message indicates that the referenced and referencing components in a component relation constraint do not stem from the same object class.

Only fixed type value fields are allowed to be specified in a referenced component

This message indicates that a referenced component in a component relation constraint is not a fixed type value field, for example

SET {
a MY-CLASS.@id ({My-set}),
b MY-CLASS.@TypeField ({My-set})
}

For the field a, @id should reference fixed type value field in class 'MY-CLASS'

Only values of INTEGER types can be used as component relation identifiers";

This message is reported when a referenced fixed type value field is not an INTEGER, only INTEGERS are supported.

SET {
a MY-CLASS.@id ({My-set}),
b MY-CLASS.@TypeField ({My-set})
}

In the example above @id should be derived from an INTEGER.

Wrong referenced component

This message indicates that a wrong type of component is referenced in a component relation constraint, for example not using ObjectClassFieldType notation.

Referenced components should be constrained by the same object set as the referencing one

This message indicates that the referenced and referencing component are not constrained with the same object sets.

ERROR 2077 ASN.1 identifier #1 is a keyword, it will be replaced by #2

This message is reported when an ASN.1 identifier is a keyword in one of the target languages and will be changed according to the keywords configuration file during mapping for avoiding syntax errors in the target languages.

ERROR 2078 Module #1 has got name clashes within joined modules group '#2'

This message is reported when an ASN.1 definition name causes name clashes within joined SDL package and will be prefixed by the original ASN.1 module name during mapping to avoid errors in SDL (see "Joining modules" ).


Restrictions

The ASN.1 Utilities handle all constructs of ASN.1 as defined in ITU-T recommendations X.680, X.681, X.682, X.683, X.690, X.691. There is no support for features defined in the old ASN.1 version X.208 that have been superseded in X.680.

For a list of restrictions see "ASN.1 Utilities.


Appendix A: List of recognized keywords

By default target language keywords are recognized among ASN.1 identifiers and a postfix `_<language>_KEYWORD' is added at the end of the identifier when SDL (<language> = SDL), TTCN (<language> = TTCN) or C (<language> = CPP) is generated. This appendix describes lists of supported keywords for all supported target the target languages.

SDL keywords

active, adding, all, alternative, and, any, as, atleast, axioms, block, break, call, channel, choice, comment, connect, connection, constant, constants, continue, create, dcl, decision, default, else, endalternative, endblock, endchannel, endconnection, enddecision, endgenerator, endmacro, endnewtype, endoperator, endpackage, endprocedure, endprocess, endrefinement, endselect, endservice, endstate, endsubstructure, endsyntype, endsystem, env, error, export, exported, external, fi, finalized, for, fpar, from, gate, generator, if, import, imported, in, inherits, input, interface, join, literal, literals, macro, macrodefinition, macroid, map, mod, nameclass, newtype, nextstate, nodelay, noequality, none, not, now, offspring, operator, operators, optional, or, ordering, out, output, package, parent, priority, procedure, process, provided, redefined, referenced, refinement, rem, remote, reset, return, returns, revealed, reverse, save, select, self, sender, service, set, signal, signallist, signalroute, signalset, size, spelling, start, state, stop, struct, substructure, synonym, syntype, system, task, then, this, timer, to, type, use, via, view, viewed, virtual, with, xor

TTCN keywords

ACTIVATE, AND, BITSTRING, BIT_TO_INT, BY, CANCEL, CASE, COMPLEMENT, CP, CREATE, DO, DONE, ELSE, ENC, ENDCASE, ENDIF, ENDVAR, ENDWHILE, F, FAIL, fail, GOTO, HEXSTRING, HEX_TO_INT, I, IF, IF_PRESENT, INCONC, inconc, INFINITY, INT_TO_BIT, INT_TO_HEX, IS_CHOSEN, IUT, LT, min, MOD, ms, MTC, NOT, ns, OMIT, OR, OTHERWISE, P, LENGTH_OF, none, NUMBER_OF_ELEMENTS, OCTETSTRING, OBJECTIDENTIFIER, PASS, pass, PDU, PERMUTATION, ps, PTC, R, READTIMER, REPEAT, REPLACE, RETURN, RETURNVALUE, R_Type, s, START, STATIC, SUPERSET, SUBSET, THEN, TIMEOUT, TIMER, TO, UNTIL, us, UT, VAR, WHILE

C++ keywords

bool, catch, class, const_cast, delete, dynamic_cast, explicit, false, friend, inline, __multiple_inheritance, mutable, namespace, new, operator, private, protected, public, reinterpret_cast, __single_inheritance, static_cast, template, this, throw, true, try, typeid, typename, using, virtual, __virtual_inheritance, xalloc

auto, asm, break, case, char, const, continue, default, do, double, else, enum, extern, float, for, goto, if, int, long, register, return, short, signed, sizeof, static, struct, switch, typedef, union, unsigned, void, volatile, while


15 The CPP2SDL Tool

The CPP2SDL tool is a C/C++-to-SDL translator that makes it possible to access C or C++ declarations in SDL. The tool takes a set of C/C++ header files as input and generates SDL declarations for a configurable set of the C/C++ declarations in these files.

CPP2SDL is the new generation of the H2SDL utility. Compared to its predecessor, CPP2SDL offers a comprehensive C++ support as well as superior translation configurability. CPP2SDL is fully integrated in Telelogic Tau SDL suite, but can also be executed as a stand-alone utility from the command shell.

This chapter is the reference manual for CPP2SDL. The reader is assumed to be familiar with C/C++ and SDL.


Introduction

The overall purpose of the CPP2SDL tool is to provide a convenient means of making external C or C++ declarations available in an SDL context. This is accomplished by translating the C/C++ declarations into representing SDL declarations. These resulting declarations can be injected at an arbitrary level in the SDL scope hierarchy, and may then be used just as if they actually were declared at that scope level. When target code is generated for the SDL system, the Code Generator produces C or C++ code for usages of generated SDL declarations that matches the original C/C++ declarations. The picture below depicts the data flow when using CPP2SDL, and the context of the tool.

.

Figure 169 CPP2SDL Data Flow and Context

As can be seen in the figure, the input to CPP2SDL is a set of C/C++ header files and, optionally, an import specification. From this input CPP2SDL generates an SDL/PR file containing SDL representations for the declarations in the header files, or for a subset of these declarations according to what is specified in the import specification. The generated SDL/PR is analyzed together with other SDL/PR, e.g. the SDL/PR for the SDL system. The Code Generator then generates target C/C++ code which is compiled by a C/C++ compiler. Note that the original C/C++ headers are used in this compilation. The resulting object code is linked together with the object files belonging to the C/C++ headers. Other object files are also included, e.g. the precompiled SDL kernel that is to be used. The result is an executable application.

CPP2SDL translates from C/C++ to SDL according to certain translation rules. These translation rules have been designed to be as simple and intuitive as possible. A user that is familiar with C/C++ should find it straight-forward to use a C/C++ declaration from SDL. The translation rules are described in full detail in "C/C++ to SDL Translation Rules" . Although CPP2SDL supports translation of a major part of the C and C++ languages, not everything is supported. The limitations of CPP2SDL are listed in "Known Limitations" .


Executing CPP2SDL

Normally, CPP2SDL is automatically invoked by the SDL Analyzer as part of the make process. Input header files and tool options are then specified in the Organizer. However, CPP2SDL may also be executed as a stand-alone tool from a command shell, and in that case input headers and tool options are given as command-line options.

This section begins with a description of the integration with the Organizer and the Analyzer. Then how to execute CPP2SDL from the command-line is described. Finally, follows a section on how to run the tool through the PostMaster.

Execution from the Organizer

The most common way to execute CPP2SDL should be from the Organizer. In fact CPP2SDL will be started automatically by the Analyzer once for each import specification symbol it finds in the Organizer view (see "Import Specifications" to learn about import specifications). The Analyzer executes CPP2SDL by means of the PostMaster as described in "Execution from the PostMaster" . All messages that are output during the execution will be printed in the Organizer Log Window.

Example 77 : Executing CPP2SDL from the Organizer

Consider a simple SDL system with one block and one process that needs to access some C++ declarations. At system level certain declarations of the C++ header file general.h is used, and at process level declarations of the files f1.h and f2.h are needed. Figure 170 below shows how the Organizer view of this SDL system could look like.

Figure 170 Organizer view with headers to be translated by CPP2SDL

When this system is analyzed, the Analyzer will execute CPP2SDL once for the file general.h, and once for the files f1.h and f2.h. The result of the first translation is a set of SDL declarations that are injected at system level, and thus will be accessible in all scopes. The result of the second translation is a set of SDL declarations that are injected at process level and thus are not accessible in the system or in the block scope.

Adding Import Specifications to the Organizer view

The first step in accessing C/C++ declarations from SDL is to insert a PR symbol at the place in the SDL specification where the C/C++ declarations are to be used. The PR symbol represents the inclusion of the SDL PR that is the translation of the C/C++ declarations.

To specify that this should be an import specification, double-click the PR symbol either in the Organizer or in the SDL Editor to open the Edit Document dialog. In the dialog it is possible to select either C Import Specification or C++ Import Specification.

An import specification can be edited manually by means of the Text Editor (see "Import Specifications" to learn about import specifications). However, an import specification can also be edited in the CPP2SDL Options dialog described below.

After adding an import specification it is necessary to specify which C/C++ header files are to be translated. This is done by selecting the import specification in the Organizer and then use the Add Existing and Add New commands to select or create C/C++ header files respectively.

Setting CPP2SDL Options in the Organizer

Required options to CPP2SDL may be specified in the Organizer for each import specification by using the CPP2SDL Options dialog. This dialog may be opened from the menu that appears when the right mouse button is pressed on an import specification symbol. Figure 171 shows this dialog.

Figure 171 The CPP2SDL Options Dialog

The fields and buttons of the CPP2SDL Options dialog correspond directly to the command-line options described in "Command-Line Options" :

  • Language
    These radio buttons select the input language. If C is selected, CPP2SDL will be executed in C mode, i.e. as with the -c command-line option.
  • Dialect
    These check boxes determine what dialects to support in the input, and correspond to the -dialects command-line option. If no check-boxes are marked, the ANSI C/C++ dialect is supported.
  • Run-Time Type Information
    This check box should be set if Run-Time Type Information (RTTI) is available in C++ and should be supported in the SDL translation. It corresponds to the -rtti command-line option.
  • Allow object slicing
    This check box should be set if object slicing should be supported in the SDL translation. It corresponds to the -slicing command-line option.
  • Recognize SDL sorts in input
    This check box should be set if SDL sorts should be recognized in the input. It corresponds to the -sdlsorts command-line option.
  • Preprocessor
    This field is used to specify the preprocessor to use for preprocessing the input. It corresponds to the -preprocessor command-line option. This field also has a browse button that makes it possible to select the preprocessor from a file selection dialog.
  • Preprocessor options
    This field should contain the options to the preprocessor. It corresponds to the -cppoptions command-line option.
  • Pointer, Array, Template, Keyword, Incomplete, Underscore
    These fields specify the prefixes and suffixes that are used when C/C++ names must be modified in the SDL translation. They correspond to the -prefix and -suffix command-line options.
  • Generate SDL representations for fundamental types
    This check box should be set if SDL representations for fundamental C/C++ types should be included in the translation. It corresponds to the -generatecpptypes command-line option.
  • Only generate class pointer types when necessary
    If this check box is set, CPP2SDL will optimize the generation of class pointer types. It corresponds to the -optclasspointers command-line option.

Execution from the Command-Line

CPP2SDL is invoked from the command-line by the command:

cpp2sdl [options] <C/C++ header files>

Unless the -post option is set, all messages that are output by the tool, e.g. errors and warnings, will be printed on the standard error stream (stderr).

CPP2SDL will translate the declarations in the specified C/C++ header files, or a subset of these declarations if a suitable import specification is used (see "Import Specifications" ). The resulting SDL declarations will be saved in a file called name.pr, where name is the name of the import specification used. If no import specification is used, name will be the name of the first input header file.The output file will be placed in the same directory from where CPP2SDL is executed.

Command-Line Options

The command-line options recognized by CPP2SDL are listed and explained below. Note that an option may be abbreviated as indicated by the underlined part of the option name.

  • -a ppend
    Append the generated SDL declarations to the file that is specified with the -output option. If that file does not exist, this option will be ignored and CPP2SDL will create a new file for the output as usual.
  • -c
    Execute in C mode. CPP2SDL will assume that no C++ specific constructs are encountered in the input headers. If this assumption does not hold, the result of the translation is undefined. See "Special Translation Rules for C Compilers" for a detailed description of translation rule modifications that are caused by using this option.
  • -cppopt ions <optionsstring>
    Send the specified option string to the preprocessor. If the string contains white spaces, it must be quoted.
  • -dia lects <dialect> <dialect> ... <dialect>
    Accept the specified C/C++ dialects in the input headers. Supported dialects are
    • ANSI (ANSI C/C++)
    • BC (Borland C/C++)
    • GCC (Gnu C/C++)
    • MSVC (Microsoft Visual C/C++)
    • ALL (all supported C/C++ dialects)
      If this option is not used, CPP2SDL will assume that the input headers conform to the ANSI C/C++ dialect.
  • -err orlimit <number>
  • Set the maximum number of errors to report before terminating the translation. The default it to terminate when 5 errors have been found.
  • -gen eratecpptypes
    Include SDL representations for fundamental C/C++ types in the translation. See "SDL Library for Fundamental C/C++ Types" for more information about what actually is generated when this option is used.
  • -h elp
    Print a help message about CPP2SDL. No translation will be performed.
  • -imp ortspecification <file>
    Use the specified file as import specification for the translation. Import specifications are described in "Import Specifications" .
  • -noch eckinput
    Do not check that all input headers are existing and readable before trying to translate them. The use of this option could make it easier to use CPP2SDL from scripts.
  • -nodep end
    Do not translate depending declarations when using an import specification. Only the identifiers that are explicitly present in the import specification will be translated. If this option is set, CPP2SDL cannot guarantee that the resulting set of SDL declarations is complete and consistent. See "Import Specifications" for more information.
  • -novar iables
    Do not generate external variables. This option is needed since the rules for where SDL allows declarations of external variables are more restrictive than for other declarations. For example, SDL does not allow external variables declared at system or block level. If this option is used, CPP2SDL will output a warning if it finds a construct that otherwise would be translated to an external variable.
  • -optc lasspointers
    Optimize the generation of class pointer types so that they are only generated when they appear in the input headers. If this option is not used, CPP2SDL will automatically generate a pointer type to all translated classes. Read more about this in "Classes, Structs and Unions" .
  • -o utput <file>
    Write the resulting SDL declarations to the specified file. If the
    -append option is set, the result will be appended to the file. Otherwise a new file will be created, overwriting an existing file with the same name, if any.
    Note that all files that CPP2SDL generates will be placed in the same directory as the generated SDL/PR file.
  • -post
    Start CPP2SDL as a PostMaster client waiting for requests from the PostMaster. The PostMaster messages that are handled by CPP2SDL are described in "Execution from the PostMaster" .
  • -pref ix "ptr=<string> arr=<string> keyword=<string> incomplete=<string> tpl=<string>"
    Use the specified name prefixes when generating SDL. CPP2SDL uses name prefixes when the original C/C++ names for some reason cannot be used in SDL. This option makes it possible to fully configure how such modified names are generated. This is often useful in order to avoid name clashes in SDL.
  • -prep rocessor <executable>
    Use the specified executable for preprocessing the input headers. The executable should be a preprocessor or C/C++ compiler that is supported by CPP2SDL:
    • `cl' (Microsoft Visual C/C++ Compiler), in Windows.
    • `cpp32' (Borland C/C++ Preprocessor), in Windows.
    • `cpp' (C/C++ Preprocessor), on Unix.
    • `cc' and `CC' (Sun Workshop C and C++ Compilers), on Unix.
    • `gcc' and `g++' (GNU C and C++ Compilers), on Unix.
      If this option is not used, CPP2SDL will attempt to use `cl' in Windows, and `cpp' on Unix.
      Note that CPP2SDL uses name matching of the specified filename, with the file name extension stripped, to determine what preprocessor or compiler to use for preprocessing. If the specified name does not match the name of any supported preprocessor or compiler on the current platform, CPP2SDL will attempt to call the executable like this:

      <executable> <options> <input file> <output file>

      <options> are the option string specified with the -cppoptions options.
      If this call fails, CPP2SDL does not know how to preprocess the input headers and terminates.

Hint:

If you want to preprocess the input headers using a preprocessor that is not supported by CPP2SDL, you can write a simple shell script that wraps the call to the desired preprocessor. The script should conform to the call style that CPP2SDL uses for unknown preprocessors. Then execute CPP2SDL, using the -preprocessor option to specify the script as the preprocessor to use.

  • -r ef
    Include source references in the generated SDL. The format of these source references is described in "Source and Error References" .
  • -rtti
    Assume Run-Time Type Information, and support dynamic casting. See "Run-Time Type Information and Dynamic Cast" for more information what this means.
  • -sdl sorts
    Recognize SDL sorts in input. CPP2SDL will translate C/C++ types that are prefixed with `SDL_' to the corresponding SDL sort. Refer to "SDL Sorts in C/C++" for an example on how this feature can be used.
  • -sli cing
    Generate SDL cast operators to support slicing of C++ objects. See "Type Compatibility between Inherited Classes" for more information.
  • -sort members
    Sort struct members in SDL newtypes alphabetically.
  • -suf fix "uscore=<string>"
    Use the specified name suffixes in the generated SDL. CPP2SDL uses name suffixes when the original C/C++ name for some reason cannot be used in SDL. This option makes it possible to fully configure how such modified names are generated.
  • -targetdir <directory>
    Set the target directory for generated files. CPP2SDL produces one single header file which includes all the header files that are to be translated. If this option is used, this generated header file is placed in the specified target directory. Otherwise the file will be placed in the same directory as the generated SDL/PR file.
  • -v ersion
    Show version information.

Example 78 : Executing CPP2SDL from the command-line

% cpp2sdl -preprocessor /usr/ccs/lib/cpp -output result.pr -prefix "ptr=p arr=a" -rtti -ref input.h

This command will translate the input header input.h to SDL and write the resulting SDL declarations to the file result.pr. The specified preprocessor `cpp' will be used to preprocess the input. If the input contains pointer or array types, the corresponding SDL names will be prefixed with `p' and `a' respectively. Source references to the declarations in input.h will be generated by CPP2SDL, and Run-Time Type Information is assumed so that dynamic cast operators are generated.

Execution from the PostMaster

As mentioned above, CPP2SDL may be started as a PostMaster client by using the -post option at the command-line. As a PostMaster client, CPP2SDL will handle two different PostMaster events.

  • SESTOP
  • SECPP2SDLCOMMAND <optionstring>

The reception of a SESTOP event has the expected behavior; CPP2SDL ceases to be a PostMaster client and terminates.

The SECPP2SDLCOMMAND event has an option string as argument. The event will cause CPP2SDL to execute according to the options specified in that string. The format of the option string is the same as when CPP2SDL is executed from the command-line (see "Execution from the Command-Line" ). All messages that are output by the tool will be broadcast to the PostMaster.

After the execution of a SECPP2SDLCOMMAND event a reply is sent:

SECPP2SDLCOMMANDREPLY <#errors> <#warnings> <status>

The <#errors> and <#warnings> arguments tell the number of errors and warnings that occurred during the translation, and <status> is a text string with the same information in a more readable form.

Example 79 : Executing CPP2SDL from the PostMaster

A single PostMaster may be started with this command:

% sdt -noclients

Then CPP2SDL is started as a PostMaster client:

% cpp2sdl -post &

CPP2SDL is now waiting for requests to come from the PostMaster. By using for example the SERVERPC application, events can be sent to it.

% serverpc 58000 58101 "-rtti -ref input.h"

58000 is the tool id of CPP2SDL, and 58101 is the event id for the SECPP2SDLCOMMAND event. As a result the following reply event could for example be received:

SECPP2SDLCOMMANDREPLY 0 2 "0 errors and 2 warnings"

Finally, CPP2SDL is terminated using the SESTOP event (id 58303):

% serverpc 58000 58303


Import Specifications

A simple but powerful way of configuring the translation of a set of C/C++ declarations is to use an import specification. As the name suggests, an import specification specifies how to import external code into SDL. An import specification for CPP2SDL is a textfile written in a simple C/C++-style syntax. The file consists of two sections that both are optional:

  • CPP2SDLOPTIONS
    This section may contain options to the CPP2SDL tool. The syntax is the same as when CPP2SDL is executed as a stand-alone tool from the command-line. See "Command-Line Options" .
  • TRANSLATE
    This section may contain a list of C/C++ identifiers. CPP2SDL will attempt to make these identifiers available in SDL by translating the corresponding declarations.

Options and identifiers in an import specification are delimited by newlines.

The example below shows a simple import specification where the identifiers func, C and myint are made available in SDL.

Example 80 : A simple import specification

CPP2SDLOPTIONS {
-preprocessor /usr/ccs/lib/cpp
}

TRANSLATE {
func
C
myint
// C++ style comment (if supported by preproc.)
/* C style comment */
}

The import specification file will be preprocessed by CPP2SDL with the same preprocessor and preprocessor options that are used when preprocessing the input C/C++ headers. This makes it possible to use, for instance, C/C++ comments and macros in an import specification.

Note:

Some preprocessors will refuse to preprocess files that have an unknown file name extension (for example .is). In that case the import specification file must be given a file name extension that is known to the preprocessor (for example .h).

If an identifier in an import specification refers to a declaration that depends on other declarations, CPP2SDL will, by default, translate all these depending declarations as well. This principle is applied recursively to all declarations that depend on depending declarations, thereby making sure that the resulting SDL declarations are complete and consistent. If the -nodepend option is set, depending declarations will not be translated automatically. Then the tool cannot guarantee that the resulting set of SDL declarations is complete and consistent.

Example 81 : Translation of depending declarations

File data.h:

typedef int myint;

class C {
public:
myint* mvar;
};

File import.is:

TRANSLATE {
C
}

Execution of CPP2SDL from the command-line,

% cpp2sdl -importspecification import.is data.h

will produce resulting SDL declarations in the file import.pr:

SYNTYPE myint = int
ENDSYNTYPE myint;EXTERNAL 'C++';
NEWTYPE ptr_myint Ref( myint);
OPERATORS
ptr_myint : -> ptr_myint;
ptr_myint : ptr_myint -> ptr_myint;/
ENDNEWTYPE ptr_myint;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
mvar ptr_myint;
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

Here, the import specification only specifies that the class C shall be translated, but since the declaration of C depends on myint*, which in turn depends on myint, these declarations will be translated as well.

Note:

CPP2SDL will only translate those identifiers in an import specification that refer to declarations in namespaces (including the global namespace). If an identifier refers to another kind of declaration, for example a class member, it will be ignored and CPP2SDL will issue a warning.

Advanced Import Specifications

Besides from specifying which identifiers that should be translated to SDL, there are some more advanced constructs that may be used in an import specification.

Type Declarators

It is possible to append type declarators to identifiers that represent types. The same type declarators as in C/C++ are allowed, i.e. pointer (*), array ([]), and reference (&). Prefix and postfix declarators are separated by a dot (.).

Example 82 : Type declarators in import specification

TRANSLATE {
char* // A pointer to char.
MyClass.[8] // An array of 8 MyClass.
mytype& // A reference to mytype.
C*.[10] // An array of 10 pointers to C.
}

Prototypes for Ellipsis Functions

The translation rule for a function with unspecified arguments (a.k.a an ellipsis function) requires that information is provided about which versions of the function that should be made available in SDL (see "Unspecified Arguments" ). This information may be given in an import specification by specifying prototypes for the function.

Example 83 : Prototypes for ellipsis functions in import specification

Input declaration:

int printf(const char*, ...);

Import specification:

TRANSLATE {
printf
printf(int)
printf(double, char)
}

Resulting SDL declarations:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
printf : ptr_char, double, char -> int;
printf : ptr_char, int -> int;
printf : ptr_char -> int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

NEWTYPE ptr_char Ref( char);
OPERATORS
ptr_char : -> ptr_char;
ptr_char : ptr_char -> ptr_char;/
ENDNEWTYPE ptr_char;EXTERNAL 'C++';

Template Instantiations

Similar to ellipsis functions, the translation of templates requires additional information about how the templates should be instantiated (see "Templates" ). This information may be specified in an import specification, using the same syntax as when templates are instantiated in C++.

Example 84 : Template instantiations in import specification

Input declarations:

template <class C, int i> class S {
public:
C arr[i];
};

template <class D> D func(const D& p1);

Import specification:

TRANSLATE {
S<double, 5>
func<unsigned int>
}

Resulting SDL declarations:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
tpl_func_unsigned_int /*#REFNAME 'func<unsigned
int >'*/ : unsigned_int -> unsigned_int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

NEWTYPE arr_5_double CArray( 5, double);
ENDNEWTYPE arr_5_double;EXTERNAL 'C++';

NEWTYPE ptr_tpl_S_double_5 Ref( tpl_S_double_5);
OPERATORS
ptr_tpl_S_double_5 : -> ptr_tpl_S_double_5;
ptr_tpl_S_double_5 : ptr_tpl_S_double_5 ->
ptr_tpl_S_double_5;
ENDNEWTYPE ptr_tpl_S_double_5;EXTERNAL 'C++';

NEWTYPE tpl_S_double_5 /*#REFNAME 'S<double, 5 >'*/
STRUCT
arr arr_5_double;
OPERATORS
tpl_S_double_5 /*#REFNAME 'S'*/ : ->
tpl_S_double_5;
tpl_S_double_5 /*#REFNAME 'S'*/ : tpl_S_double_5 -> tpl_S_double_5;
ENDNEWTYPE tpl_S_double_5;EXTERNAL 'C++';

Note that since class template instantiations define types, it is possible to use type declarators for them.


Source and Error References

A source reference is a reference from a generated SDL declaration to the corresponding original C/C++ declaration. Source references are placed in the generated SDL/PR file.

An error reference is also a reference to a declaration in the input header file, but is used to point out an error (or a warning) in that file. Error references are therefore printed as messages to the standard error stream or to the Organizer Log Window.

CPP2SDL uses the #SDTREF format both for source and error references. See 19 SDT References for more about #SDTREF.

Source References

When CPP2SDL is executed from the Organizer, or from the command-line with the -ref option set, the generated SDL/PR file will contain references to the input source files. Such a reference occurs just before a generated SDL declaration, and is on the form

/*#SDTREF(TEXT,filename,line)*/

where

  • filename is the name of the input file where the corresponding C/C++ declaration can be found.
  • line is the line number in that input file where the C/C++ declaration starts.

A source reference is shown in Example 85 below.

Example 85 : Source references

/*#SDTREF(TEXT,input.h,226)*/
NEWTYPE S STRUCT
a int;
OPERATORS
get_a: S -> int;
ENDNEWTYPE S;EXTERNAL `C++';

Error References

Error references have a similar format as source references but with a column position added after the line number:

/*#SDTREF(TEXT,filename,line,column)*/

CPP2SDL prints error references when errors or warnings are found during the translation. They are output to the standard error stream (stderr) or to the Organizer Log Window depending upon whether CPP2SDL is executed from the command-line or from the PostMaster.

Problems with error references may arise because of the preprocessor. Among other things, the preprocessor expands macros, and a typical problem is illustrated in Example 86 below.

Example 86 : Error References

File def.h:

#define init InitializingFunction

void init(undefinedType *, int);

If CPP2SDL translates this file, the following error message will be printed:

#SDTREF(TEXT,def.h,3,27)
ERROR 3200 Syntax error.

Here the syntax error occurs at position (3,11) in the source file, but because of the macro expansion of init to InitializingFunction, CPP2SDL will report the error at position (3,27) instead. Thus the column position is several characters off the target in the original file. When using the Organizer Log's Show Error function (see "Show Error" ) to view the source of this error message, the cursor will be placed at int instead of at
undefinedType. CPP2SDL calculates both source and error references from the preprocessed source code, and this may lead to reference problems when macros are involved.


C/C++ to SDL Translation Rules

The general idea behind the CPP2SDL tool is to take a set of C/C++ header files, preprocess them, and translate some or all of the declarations in these headers into SDL/PR representations. This section describes the rules for this translation process.

Each C/C++ construct is described in a subsection of its own. First, a general rule for the translation of the construct is presented. Then follows a description of exceptions to this rules, and rationals for these exceptions.

Before proceeding, it should be noted that the translation rules have been designed to support both C and C++ target compilers. To a large extent the translation rules are actually independent of whether a C or C++ target compiler is used. However, there are some differences, so when CPP2SDL executes in "C mode" (i.e. with the -c option set) a few translation rules are slightly modified. These modifications are described in "Special Translation Rules for C Compilers" .

Names

Rule: The name of a C/C++ identifier is the same in SDL.

The naming rules of identifiers in SDL and C/C++ are rather similar but differs in two important aspects:

  • SDL is a case-insensitive language, while C/C++ is case-sensitive.
  • SDL has some restrictions for how underscores may be used in names. C/C++ has no such restrictions.

To overcome these differences tool specific extensions have been made in the supported SDL dialect. The Analyzer has an option to handle case sensitive SDL (see "Set-Case-Sensitive" ), and most of the restrictions with underscores have been removed. However, the rule that a name that ends with an underscore should be concatenated with the following name, makes it necessary to modify such names in the SDL mapping. This is done by appending a string suffix to such names. This string is by default "uscore" but may be configured to an arbitrary string be means of the CPP2SDL option
-suffix.

Another case where a name in C/C++ cannot be retained in the SDL translation is when the name is an SDL keyword. Such names are prefixed with a user-configurable string that by default is keyword_. The option -prefix can be used to configure this string.

Example 87 below gives some examples of the translation rules for names.

Example 87 : Translation of names

C++:

int ABC, abc; // Case sensitivity
char u__sc, _w, x_; // Unrestricted use of underscores
double signal; // SDL keyword

SDL:

DCL ABC int; EXTERNAL 'C++';
DCL abc int; EXTERNAL 'C++';
DCL u__sc char; EXTERNAL 'C++';
DCL _w char; EXTERNAL 'C++';
DCL x_uscore /*#REFNAME 'x_'*/ char; EXTERNAL 'C++';
DCL keyword_signal /*#REFNAME 'signal'*/ double; EXTERNAL 'C++';

Note the #REFNAME directive that passes the original C/C++ name to the Code Generator for names that are modified in the SDL translation.

Fundamental Types

Rule: A fundamental C/C++ type is mapped to an SDL sort with the same name.

The SDL sorts that represent fundamental C/C++ types are not generated by CPP2SDL but are defined in special SDL/PR files that are included if the -generatecpptypes option is set. The SDL sorts in these files are normally syntypes of predefined SDL sorts. Refer to "SDL Library for Fundamental C/C++ Types" for more information.

The table below shows how the fundamental C/C++ types are translated to SDL sorts, and what predefined SDL sort that correspond to these SDL sorts.

C/C++ Fundamental Type
SDL Sort
Predefined SDL Sort

 signed int
 int

      int

 Integer

 unsigned int
 unsigned

 unsigned_int

 Integer

 signed long int
 signed long
 long int
 long

 long_int

 Integer

 unsigned long int
 unsigned long

 unsigned_long_int

 Integer

 signed short int
 signed short
 short int
 short

 short_int

 Integer

 unsigned short int
 unsigned short

 unsigned_short_int

 Integer

 signed long long int
 signed long long
 long long int
 long long

 long_long_int

 Integer

 unsigned long long int
 unsigned long long

 unsigned_long_long_int

 Integer

 char

 char

 Character

 signed char

 signed_char

 Character

 unsigned char

 unsigned_char

 Octet

 wchar_t

 wchar_t

 N/A

 float

 float

 Real

 double
 long double

 double

 Real

 bool

 bool

 Boolean

 void

 N/A

 N/A

Note that the wchar_t type has no counterpart in SDL, and thus is represented by a newtype rather than a syntype of a predefined sort.

Also note that the special void type is not represented explicitly in SDL. Instead this type is translated by omitting input and result arguments to operators as described in "Functions" .

Type Declarators

There are two different type declarators in C; pointer (*), and array ([]). C++ has one additional type declarator; reference (&).

Pointers

Rule: A type with a pointer declarator is translated by applying the Ref generator on the SDL sort that corresponds to that type.

The name of the generated newtype for the pointer is prefixed with a user-configurable string that by default is ptr_. The option -prefix can be used to configure this string.

Untyped pointers (void*) are translated to a special SDL sort called ptr_void. See "SDL Library for Fundamental C/C++ Types" for more information about the Ref generator and the special ptr_void sort.

Example 88 : Translation of pointers

C++:

typedef int* p_int;
extern void* generalp;

SDL:

NEWTYPE ptr_int Ref( int);
OPERATORS
ptr_int : -> ptr_int;
ptr_int : ptr_int -> ptr_int;
ENDNEWTYPE ptr_int;EXTERNAL 'C++';
SYNTYPE p_int = ptr_int
ENDSYNTYPE p_int;EXTERNAL 'C++';
DCL generalp ptr_void; EXTERNAL 'C++';

Arrays

Rule: A type with an array declarator is translated by applying the
CArray generator on the SDL sort that corresponds to that type.

There is one important exception to this rule. Array declarators that do not specify the size of the array are translated in the same way as pointers (see "Pointers" ).

The name of the generated newtype for an array type with a specified size is prefixed with a user-configurable string that by default is "arr_". The option -prefix can be used to configure this string. The name also contains the size of the array, since the size is used in the CArray generator instantiation and thus is significant in SDL. This makes SDL array sorts of different sizes type incompatible, but this is normally not a big problem since the elements of the arrays are type compatible.

Note:

SDL array sorts corresponding to C/C++ arrays with different sizes are normally type incompatible.

Example 89 : Translation of arrays

C++:

extern char c_arr1[20];
extern char c_arr2[];

SDL:

NEWTYPE arr_20_char CArray( 20, char);
ENDNEWTYPE arr_20_char;EXTERNAL 'C++';
DCL c_arr1 arr_20_char; EXTERNAL 'C++';
NEWTYPE ptr_char Ref( char);
OPERATORS
ptr_char : -> ptr_char;
ptr_char : ptr_char -> ptr_char;
ENDNEWTYPE ptr_char;EXTERNAL 'C++';
DCL c_arr2 ptr_char; EXTERNAL 'C++';

References

Rule: A type with a reference declarator is translated as normal, i.e. the reference declarator is not translated to SDL.

A C++ reference can be looked upon as a constant pointer that is automatically de-referenced each time it is used. This makes a reference an alternative name for an object. Since no difference will be made between an object and a reference to an object in the SDL mapping, references will appear to be objects in SDL.

Example 90 : Translation of references

C++:

extern int i; /* i is initialized elsewhere */
extern int& r; /* r is initialized to i elsewhere
(int& r = i;), i.e. r and i refers to
the same int. */

SDL:

DCL i int; EXTERNAL 'C++';
DCL r int; EXTERNAL 'C++';/* N.B. C++ reference! */

Note that if r in this example is assigned a value in SDL, it is in fact the object that r refers to (i.e. i) that gets a new value. This could be confusing if only the SDL translation of r is considered, and to avoid this a comment is attached to the declaration of r that tells that it is a reference in C++.

References could also appear as specifiers for formal function arguments. Such arguments will be translated to operator arguments marked with the IN/OUT keyword if they are non-constant (see "Argument Passing and Return Value" ).

Enumerated Types

Rule: An enumerated type is translated to a newtype with literals corresponding to the enum literals.

A special case is when the enumerated type has no literals. Such a type can be treated as an integer in C/C++, and is consequently translated to a syntype of int.

Example 91 : Translation of enumerated types

C/C++:

enum {} v;
enum E2 {};
enum E1 {a, b, c=10};

SDL:

DCL v int; EXTERNAL 'C++';
SYNTYPE E2 = int
ENDSYNTYPE E2;EXTERNAL 'C++';
NEWTYPE E1
LITERALS a, b, c;
OPERATORS
IntToEnum /*#REFNAME '(E1)'*/ : int -> E1;
EnumToInt : E1 -> int; /*#OP(PY)*/
ORDERING;
ENDNEWTYPE E1;EXTERNAL 'C++';

By using the "type conversion" operators EnumToInt and IntToEnum integer arithmetic and comparisons become available in SDL also for enumerations. As can be seen from the #REFNAME directive in the example above, the generated code for calls to the IntToEnum operator will be a C style cast from int to enum. This explicit type conversion should be acceptable by all target compilers. Also note that the #OP(PY) directive means that there will be no generated code for calls to the EnumToInt operator, which is desired since that type conversion is implicit in C/C++.

If the enumerated type is incomplete, i.e. if the enum tag is missing, the translation rule is slightly modified according to the translation rules for incomplete types (see "Incomplete Types" ). For enumerations, these rules have the following impact:

· The name of the generated newtype follows the naming rules for incomplete types described in "Incomplete Types" .

· The newtype will not be external, since it does not correspond to a C/C++ type that may be referred to.

· The IntToEnum operator will not be generated for the same reason.

Typedef Declarations

Rule: A typedef declaration is translated to an SDL syntype declaration.

There are two exceptions to this rule:

  • A typedef declaration of a tagged type1, where the typedef name is the same as the name of the tag.
  • A typedef declaration where the typedef name has been omitted. This is a legal but not very common case.

In these cases the typedef declarations do not define new typenames, and thus no syntypes need to be generated.

Another special case is when a synonym for void is introduced by means of a typedef declaration. Such a typedef declaration is not translated, but the typedef name will be remembered. References to the typedef name will then be translated in the same way as void would have been translated in that context.

Example 92 : Translation of typedef declarations

C++:

typedef int MyInt;
typedef struct r {
int a;
} r; // Typedef name is the same as the tag name!
typedef struct s {
MyInt a;
}; // Omitted typedef name - legal but rare!
typedef void myvoid;
typedef myvoid myvoid2;
myvoid f(myvoid2);

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
f :;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
SYNTYPE MyInt = int
ENDSYNTYPE MyInt;EXTERNAL 'C++';
NEWTYPE ptr_r Ref( r);
OPERATORS
ptr_r : -> ptr_r;
ptr_r : ptr_r -> ptr_r;
ENDNEWTYPE ptr_r;EXTERNAL 'C++';
NEWTYPE r
STRUCT
a int;
OPERATORS
r : -> r;
r : r -> r;
ENDNEWTYPE r;EXTERNAL 'C++';
NEWTYPE ptr_s Ref( s);
OPERATORS
ptr_s : -> ptr_s;
ptr_s : ptr_s -> ptr_s;
ENDNEWTYPE ptr_s;EXTERNAL 'C++';
NEWTYPE s
STRUCT
a MyInt;
OPERATORS
s : -> s;
s : s -> s;
ENDNEWTYPE s;EXTERNAL 'C++';

Note:

Typedefs of function types are not supported by CPP2SDL, and will not be translated to SDL.

Functions

Rule: A function prototype is translated to an SDL operator signature.

This rule is valid both for member and non-member functions. Operators that result from functions that are members of a class will be placed in the newtype that is the translation of that class. Operators that result from non-member functions will be placed in a special newtype called global_namespace 2.

Member functions are described in "Members" , and the rest of this section will focus on non-member functions.

Example 93 : Translation of non-member functions

C++:

char myfunc1(char);
int myfunc1();
void myfunc2();
void myfunc2(int);

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
myfunc1 : char -> char;
myfunc1 : -> int;
myfunc2 :;
myfunc2 : int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

Note that functions without input arguments or return value, will be translated to operators without input arguments or return value. Such operators are not allowed according to the SDL96 standard, but are accepted by the SDL Analyzer as a tool specific language extension.

Overloaded Functions

Rule: Overloaded functions are translated to overloaded SDL operators.

The semantics of overloaded functions in C++ differs slightly from the semantics of overloaded operators in SDL. For example, C++ allows overloading on constant arguments which is not possible in SDL. A C++ header file may therefore contain overloaded functions that cannot be translated to SDL. Normally this is not a problem since the C++ compiler resolves generated calls to these functions correctly anyway.

Example 94 : Translation of overloaded functions

C++:

int f0();
int f0(double);
int f1(int&);
int f1(const int&);

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
f0 : -> int;
f0 : double -> int;
f1 : int -> int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

Argument Passing and Return Value

Rule: Function arguments that are passed by reference are translated to IN/OUT operator arguments in SDL.

There is one exception to this rule; arguments that are references to constants do not translate to IN/OUT arguments since C++ allows these arguments to take variables as well as constant values.

Example 95 : Translation of function arguments and return value

C++:

int f1 (int p1, int &p2, const int &p3, const int *p4, int *const p5);
int &f2();
const int &f3();

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
f1 : int, IN/OUT int, int, ptr_int, ptr_int -> int;
f2 : -> int;
f3 : -> int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
NEWTYPE ptr_int Ref( int);
OPERATORS
ptr_int : -> ptr_int;
ptr_int : ptr_int -> ptr_int;
ENDNEWTYPE ptr_int;EXTERNAL 'C++';

The example shows that information about constant arguments is lost in the SDL mapping. Also note that no difference will be made in SDL between functions that return data by value, data by reference, or constant data by reference.

Finally note that IN/OUT arguments to operators is a tool specific SDL extension.

Default Arguments

Rule: A function with default arguments are translated to several overloaded SDL operators.

This translation is reasonable given the fact that each C++ function with default arguments may be rewritten to an equivalent set of overloaded C++ functions.

Example 96 : Translation of functions with default arguments

C++:

int func(int a, int b = 5, int c = 7);
int func(int a); // Ambiguous function!

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
func : int, int, int -> int;
func : int, int -> int;
func : int -> int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

In C++, ambiguities between overloaded functions are allowed provided that the functions are never called. SDL is, however, more strict, and operator resolution is made from the declarations of the operators. The second version of func in the example above is therefore not accessible in the SDL mapping.

Unspecified Arguments

Rule: The translation of a function with unspecified arguments (a.k.a. an ellipsis function) requires the usage of an import specification that specifies the types of the unknown arguments.

See "Prototypes for Ellipsis Functions" for information about how an import specification can be used to "expand" ellipsis functions.

Inline Functions

Rule: A function that is declared to be inline is translated as an ordinary function.

This is natural since the inline keyword on functions can be seen as a directive to the C++ compiler, which only affects the way that calls to these functions are generated. This is of course nothing that needs to be visible in SDL.

Example 97 : Translation of inline functions

C++:

inline int fac(int n){/*...*/};

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
fac : int -> int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

Function Pointers

Rule: A function pointer is translated to an untyped pointer in SDL, i.e. to ptr_void.

This translation rule makes it possible to represent a function pointer in SDL, but it is not possible to call the function that it points to, or to assign the address of another function to it. That has to be done with inline C/C++ code, for example by means of the #CODE operator.

Example 98 : Translation of function pointers

C++:

typedef int (*fp)(int, char);
fp g(double);

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
g : double -> fp;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
SYNTYPE fp = ptr_void
ENDSYNTYPE fp;EXTERNAL 'C++';

The special ptr_void sort is described in "SDL Library for Fundamental C/C++ Types" .

Scope Units

Rule: A C/C++ scope unit is translated to an SDL newtype.

Note that the global scope (known as the global namespace in C++) is also translated to an SDL newtype. This newtype is called global_namespace and is a container for all operators that are the translation of non-member or global functions in the program. Other global declarations are however placed directly in the SDL scope that is the context of the translation.

Example 99 : Translation of the global namespace

C++:

int i;
void op(unsigned int);

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
op : unsigned_int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
DCL i int; EXTERNAL 'C++';

The most important scope units that may be found in a C/C++ header file are:

  • Namespaces
  • Classes, structs and unions
  • Template classes

In C++ these scope units may be nested to arbitrary depth, but since nested newtypes are not allowed in SDL, the translation of a nested scope unit will be a newtype that has a name that is prefixed with a scope qualification prefix. This prefix consists of the names of all enclosing scope units separated by underscores ("_").

Example 100 : Translation of nested scope units

C++:

class C {
public:
int ci;
class CC {
public:
int op();
};
};

SDL:

NEWTYPE ptr_C_CC Ref( C_CC);
OPERATORS
ptr_C_CC : -> ptr_C_CC;
ptr_C_CC : ptr_C_CC -> ptr_C_CC;
ENDNEWTYPE ptr_C_CC;EXTERNAL 'C++';
NEWTYPE C_CC /*#REFNAME 'C::CC'*/
OPERATORS
op : C_CC -> int;
C_CC /*#REFNAME 'CC'*/ : -> C_CC;
C_CC /*#REFNAME 'CC'*/ : C_CC -> C_CC;
ENDNEWTYPE C_CC;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
ci int;
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

Compare the name "C_CC" of the nested class CC in this example, with the fully qualified name "C::CC" of this class in C++. The latter name is provided in a #REFNAME directive as information to the Code Generator.

Namespaces

Rule: A namespace is translated to a newtype that may not be instantiated in SDL.

Classes, structs, unions and template classes not only define scope units, but also types. They may thus be instantiated in for example variable declarations. Namespaces, on the other hand, are plain scope units and may not be instantiated. This is indicated in the SDL mapping by means of a Code Generator directive called #NOTYPE. This directive enables the Code Generator to catch attempts to instantiate newtypes that originates from namespaces.

Example 101 : Translation of namespaces

C++:

namespace N {
const int ci;
class CC {
public:
int op();
};
int f(char);
}

SDL:

SYNONYM N_ci /*#REFNAME 'N::ci'*/ int = EXTERNAL 'C++';
NEWTYPE ptr_N_CC Ref( N_CC);
OPERATORS
ptr_N_CC : -> ptr_N_CC;
ptr_N_CC : ptr_N_CC -> ptr_N_CC;
ENDNEWTYPE ptr_N_CC;EXTERNAL 'C++';
NEWTYPE N_CC /*#REFNAME 'N::CC'*/
OPERATORS
op : N_CC -> int;
N_CC /*#REFNAME 'CC'*/ : -> N_CC;
N_CC /*#REFNAME 'CC'*/ : N_CC -> N_CC;
ENDNEWTYPE N_CC;EXTERNAL 'C++';
NEWTYPE N /*#NOTYPE*/
OPERATORS
N_f /*#REFNAME 'N::f'*/ : char -> int;
ENDNEWTYPE N;EXTERNAL 'C++';

Note that the newtype that corresponds to the namespace only contains the operators that are the translation of the functions declared in that namespace. This is analogous to how the global namespace is translated (see Example 99). Other declarations in the namespace will appear outside the newtype. All SDL declarations that are generated from namespace declarations will be prefixed with the name of the newtype that is the translation of that namespace. Also, their fully qualified C++ name is given in #REFNAME directives.

Variables

Rule: A variable is translated to an external variable if it is a non-member or global variable, or to a newtype field if it is a member variable.

Newtype fields that result from member variables of a class will be placed in the newtype that is the translation of that class. Member variables are described in "Members" , and the rest of this section will focus on non-member variables.

Example 102 : Translation of non-member variables

C++:

int ivar, jvar;
class X {
int j;
public:
int Get() { return j;};
} xvar;

SDL:

DCL ivar int; EXTERNAL 'C++';
DCL jvar int; EXTERNAL 'C++';
NEWTYPE ptr_X Ref( X);
OPERATORS
ptr_X : -> ptr_X;
ptr_X : ptr_X -> ptr_X;
ENDNEWTYPE ptr_X;EXTERNAL 'C++';
NEWTYPE X
OPERATORS
Get : X -> int;
X : -> X;
X : X -> X;
ENDNEWTYPE X;EXTERNAL 'C++';
DCL xvar X; EXTERNAL 'C++';

External variables are a tool-specific SDL extension that are similar to external synonyms.

External variables may only be declared in a process, procedure, service or operator diagram. Since CPP2SDL does not know the SDL context where the translation takes place, it has a command-line option called
-novariables that tells whether external variables may be generated or not. When CPP2SDL is executed from the Organizer, this option is set automatically. If the option is set, and a C/C++ construct is found that would map to an external variable, CPP2SDL will print a warning.

Constants

Rule: A constant is translated to an external synonym.

This rule applies for all true C/C++ constants, i.e. constants that have been declared using the const type specifier. It is not uncommon, especially in older C API:s, to use macros to represent constants. Such constants will not be directly accessible in SDL since the preprocessor expands them before CPP2SDL begins the translation. However, simple macro constants may often be accessed by using inline target code, for example by means of the #CODE operator. As an alternative external synonyms could be declared to represent such macros.

Example 103 : Translation of constants

C++:

class MyClass;
const double pi = 3.1415;
const MyClass m(7, 'x');

SDL:

SYNONYM pi double = EXTERNAL 'C++';
NEWTYPE MyClass /*#NOTYPE*/
ENDNEWTYPE MyClass;EXTERNAL 'C++';
SYNONYM m MyClass = EXTERNAL 'C++';

Constant Expressions

Rule: Constant expressions are evaluated while translated to SDL.

Constant expressions may be encountered at a number of places in a C/C++ header, for example as constant initializers, or as size specifiers of array declarators or bitfields. If a constant expression has to be translated to SDL, CPP2SDL attempts to evaluate it during the translation in order to simplify its representation in SDL.

Example 104 : Translation of constant expressions

C++:

enum e {a, b, c=10};
const int i = (2+c)*b;
struct s{
int f1 : (2+c)*b;
};
typedef int intarr[sizeof(int)+1];

SDL:

NEWTYPE e
LITERALS a, b, c;
OPERATORS
IntToEnum /*#REFNAME '(e)'*/ : int -> e;
EnumToInt : e -> int; /*#OP(PY)*/
ORDERING;
ENDNEWTYPE e;EXTERNAL 'C++';
SYNONYM i int = EXTERNAL 'C++';
NEWTYPE ptr_s Ref( s);
OPERATORS
ptr_s : -> ptr_s;
ptr_s : ptr_s -> ptr_s;
ENDNEWTYPE ptr_s;EXTERNAL 'C++';
NEWTYPE s
STRUCT
f1 int : 12;
OPERATORS
s : -> s;
s : s -> s;
ENDNEWTYPE s;EXTERNAL 'C++';
NEWTYPE arr_2_int CArray( 2, int);
ENDNEWTYPE arr_2_int;EXTERNAL 'C++';
SYNTYPE intarr = arr_2_int
ENDSYNTYPE intarr;EXTERNAL 'C++';

Note that not all the constant expressions in this example are visible in the SDL translation, and thus need not be evaluated by CPP2SDL.

Most constant expressions can be evaluated by CPP2SDL, but not all. In particular, expressions containing the sizeof() operator are difficult to evaluate since CPP2SDL has no information about what compiler that will be used to compile the generated C/C++ code. Some standard assumptions are therefore used when a sizeof() operator is encountered, and a warning will be issued to encourage manual inspection of the translation.

Classes, Structs and Unions

Rule: A class, struct or union is translated to an SDL newtype.

This rule follows from the fact that classes, structs and unions are scope units (see "Scope Units" ).

This section mainly uses classes in the discussions and examples, but since the translation rules make no difference between classes, structs and unions, the same is valid for structs and unions. Example 105 shows the translation of an empty class, struct and union.

Example 105 : Translation of classes, structs and unions

C++:

class C {};
struct S {};
union U {};

SDL:

NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';
NEWTYPE ptr_S Ref( S);
OPERATORS
ptr_S : -> ptr_S;
ptr_S : ptr_S -> ptr_S;
ENDNEWTYPE ptr_S;EXTERNAL 'C++';
NEWTYPE S
OPERATORS
S : -> S;
S : S -> S;
ENDNEWTYPE S;EXTERNAL 'C++';
NEWTYPE ptr_U Ref( U);
OPERATORS
ptr_U : -> ptr_U;
ptr_U : ptr_U -> ptr_U;
ENDNEWTYPE ptr_U;EXTERNAL 'C++';
NEWTYPE U
OPERATORS
U : -> U;
U : U -> U;
ENDNEWTYPE U;EXTERNAL 'C++';

In the example above three C++ types translate to six SDL sorts. The reason for this is that when CPP2SDL generates a newtype for a class, it will also, by default, generate a newtype that represents a pointer type for this class. This is convenient since pointers to a class often are needed. If the class inherits other classes this pointer newtype is in fact necessary, since it then holds cast operators to the base types of the class (see "Type Compatibility between Pointers to Inherited Classes" ). If the command-line option -optclasspointers has been set, CPP2SDL will not generate this extra newtype unless a pointer to the class is explicitly present in the input code.

If the class, struct, or union has no tag, it is an incomplete type declaration. The translation rules for incomplete types are described in "Incomplete Types" .

Anonymous Unions

Rule: An anonymous union is translated by making its members become fields of the newtype that represents the enclosing scope unit.

This translation rule is natural since an anonymous union is no scope unit.

Example 106 : Translation of Anonymous Unions

C++:

struct S {
int i;
union {
int j;
int k;
};
};

SDL:

NEWTYPE ptr_S Ref( S);
OPERATORS
ptr_S : -> ptr_S;
ptr_S : ptr_S -> ptr_S;
ENDNEWTYPE ptr_S;EXTERNAL 'C++';
NEWTYPE S
STRUCT
j int;/* member of anonymous union */
k int;/* member of anonymous union */
i int;
OPERATORS
S : -> S;/* implicit parameter-less constructor */
S : S -> S;/* implicit copy constructor */
ENDNEWTYPE S;EXTERNAL 'C++';

Note that an anonymous union is not an incomplete type declaration, although the syntax is similar. An anonymous union is not used to declare a type nor a variable, and does not define a type at all. Consequently, the translation rules for anonymous unions and incomplete types differ significantly. Compare with "Incomplete Types" .

Constructors

Rule: A constructor for a class is translated to an operator with the same name as the newtype that represents the class.

The return sort of the operator will be the sort defined by the newtype for the class, and the operator will of course also be placed in that newtype.

There are two different kinds of constructors in C++:

  • User-defined constructors. These constructors are manually declared and implemented.
  • Implicit constructors. These constructors are implicitly declared and are auto-generated by the C++ compiler, provided that they are not already declared by the user.

While a class may contain an arbitrary number of user-defined constructors, it may at the most contain two auto-generated ones; a parameter-less (or default) constructor and a copy constructor. A parameter-less constructor is available only if the class has no user-defined constructors, and a copy constructor is available only if no user-defined copy constructor is declared.

CPP2SDL will generate operators both for user-defined and implicit constructors. Example 107 below shows a class with three user-defined constructors, and one implicit copy constructor.

Example 107 : Translation of constructors

C++:

class C {
public:
C();
C(int i);
C(char c);
~C();
};

SDL:

NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
OPERATORS
C : -> C;
C : char -> C;
C : int -> C;
C : C -> C;/* implicit copy constructor */
ENDNEWTYPE C;EXTERNAL 'C++';

Destructors

Rule: A destructor is not translated to SDL.

The reason why a class destructor is not made accessible in SDL, is that it normally should not be called explicitly. Instead it will be called automatically when an object of the class goes out of scope or is deleted. See Example 107 for an example of how a destructor disappears in the SDL mapping.

Members

Rule: Member variables of a C++ class are translated to fields in the newtype that is the translation of that class, and member functions are translated to operators in the same newtype.

Other declarations than variables and functions in a class, for example type declarations, are also sometimes called members of the class, but they are not translated according to the translation rule above. Instead they are considered to be declarations on their own, but defined in an enclosing scope unit (i.e. the class). See "Scope Units" for more information.

Example 108 : Translation of class members

C++:

class C {
public:
int mv1; // Member variable
void mf1(long long p1); // Member function
enum e {a,b,c}; // "Member" type declaration
};

SDL:

NEWTYPE C_e /*#REFNAME 'C::e'*/
LITERALS a, b, c;
OPERATORS
IntToEnum /*#REFNAME '(C::e)'*/ : int -> C_e;
EnumToInt : C_e -> int; /*#OP(PY)*/
ORDERING;
ENDNEWTYPE C_e;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
mv1 int;
OPERATORS
mf1 : C, long_long_int;
C : -> C;/* implicit parameter-less constructor */
C : C -> C;/* implicit copy constructor */
ENDNEWTYPE C;EXTERNAL 'C++';

Note that the operator that represents a member function will have an additional initial formal argument. This argument has the sort of the newtype that represents the class where the member function is declared. Member functions are called from SDL in a functional style, where the first actual argument to the member function operator is the class instance on which the member function is to be invoked.

Member Access Specifier

Rule: Only members with public access specifier are translated to SDL.

This rule follows from the fact that public members of a class are the only members that are accessible from outside that class or its derived classes.

Example 109 : Translation of members with different access specifiers

C++:

class C {
private:
int i;
protected:
int j;
public:
int k;
int GetI();
int GetJ();
int Calc (int x, int y);
};

SDL:

NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
k int;
OPERATORS
Calc : C, int, int -> int;
GetI : C -> int;
GetJ : C -> int;
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

Virtual Member Functions

Rule: A virtual member function is translated in the same way as an ordinary member function.

In C++, virtual functions of a base class may be redefined in derived classes. Although this means that there is only one version of a particular virtual function in a derived class, the version defined in the base class may still be called by means of explicit qualification. Both versions of the function must thus be present in the SDL translation, exactly as is the case for non-virtual functions. See "Inheritance" for more about how C++ inheritance is represented in SDL.

Example 110 : Translation of virtual member functions

C++:

class CPen {
public:
virtual void Draw(); // Virtual member function
double GetRep(); // Non-virtual member function
};
class CPenD : public CPen {
public:
virtual void Draw(); // Redefinition of CPen::Draw()
};

SDL:

NEWTYPE ptr_CPen Ref( CPen);
OPERATORS
ptr_CPen : -> ptr_CPen;
ptr_CPen : ptr_CPen -> ptr_CPen;
ENDNEWTYPE ptr_CPen;EXTERNAL 'C++';
NEWTYPE CPen
OPERATORS
Draw : CPen;
GetRep : CPen -> double;
CPen : -> CPen;
CPen : CPen -> CPen;
ENDNEWTYPE CPen;EXTERNAL 'C++';
NEWTYPE ptr_CPenD Ref( CPenD);
OPERATORS
cast : ptr_CPenD -> ptr_CPen; /*#OP(PY)*/
ptr_CPenD : -> ptr_CPenD;
ptr_CPenD : ptr_CPenD -> ptr_CPenD;
ENDNEWTYPE ptr_CPenD;EXTERNAL 'C++';
NEWTYPE CPenD
OPERATORS
Draw : CPenD;
CPen_Draw /*#REFNAME 'CPen::Draw'*/ : CPenD;/* Inherited from CPen */
GetRep : CPenD -> double;/* Inherited from CPen */
CPenD : -> CPenD;/
CPenD : CPenD -> CPenD;
ENDNEWTYPE CPenD;EXTERNAL 'C++';

Pure Virtual Member Functions

Rule: A pure virtual member function is translated in the same way as an ordinary member function.

Although "pure virtuality" does not affect the translation of the member function itself, it will have impact on how the containing class, which is an abstract class, is translated. The reason is that special translation rules apply for abstract classes. See "Abstract Classes" for more information and an example on how pure virtual member functions are translated.

Static Members

Rule: A static member is translated both as an ordinary member, and as if it was declared in the global namespace.

There will thus be two representations in SDL of a static C++ member. The additional representation is caused by the fact that a static member is accessible without having an instance of the class where it is defined.

As shown in Example 111 below, a static member variable will be translated both to a newtype field and an external variable (see "Variables" ), while a static member function will result in both an operator in the newtype for the class and an operator in the special global_namespace newtype (see "Functions" ).

Example 111 : Translation of static members

C++:

class C {
public:
static int k;
static void InitI(int);
};

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
C_InitI /*#REFNAME 'C::InitI'*/ : int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
DCL C_k /*#REFNAME 'C::k'*/ int; EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
k int;
OPERATORS
InitI : C, int;
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

If the resulting SDL declarations are to be inserted in an SDL context where external variables are not allowed (i.e. if CPP2SDL executes with the -novariables option set), static member variables cannot be translated to external variables. In that case only the standard translation of class members can be applied. Naturally, CPP2SDL will issue a warning if this happens.

Constant Members

Rule: A constant member is translated as an ordinary member, but with a #CONSTANT directive attached.

The semantics of a constant member variable is that it may not be written to after its initialization, and a constant member function may not change the state of its object. There is no way to express these restrictions in SDL, so the Analyzer will not be able to detect if they are violated. However, by attaching the #CONSTANT directive to SDL declarations that result from constant members, the Code Generator can do the necessary checks.

Example 112 : Translation of constant members

C++:

class C {
public:
const int cm; // constant member
C(int k) : cm(k) {};
void Do(double);
void Undo(double) const; // constant member function
};

SDL:

NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
cm /*#CONSTANT*/ int;
OPERATORS
C : int -> C;
Do : C, double;
Undo : C, double; /*#CONSTANT*/
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

Member Constants

Rule: A member constant is translated both as an ordinary member with a #CONSTANT directive attached, and as if it was declared in the global namespace.

This translation rule is a combination of the translation rules for static and constant members, which is natural since a member constant is declared both to be constant and static in C++.

Example 113 : Translation of member constants

C++:

class X {
public:
static const int i = 99; // member constant
};
const int X::i; // definition of i

SDL:

SYNONYM X_i /*#REFNAME 'X::i'*/ int = EXTERNAL 'C++';
NEWTYPE ptr_X Ref( X);
OPERATORS
ptr_X : -> ptr_X;
ptr_X : ptr_X -> ptr_X;
ENDNEWTYPE ptr_X;EXTERNAL 'C++';
NEWTYPE X
STRUCT
i /*#CONSTANT*/ int;
OPERATORS
X : -> X;
X : X -> X;
ENDNEWTYPE X;EXTERNAL 'C++';

Mutable Member Variables

Rule: A mutable member variable is translated as an ordinary member variable.

The mutable keyword in C++ can be looked upon as some kind of compiler directive, and needs therefore not be visible in the SDL translation.

Bitfield Member Variables

Rule: A bitfield member variable is translated to an SDL bitfield.

This rule applies for all bitfields that have a name. Bitfields without name are not translated to SDL.

It would have been possible to translate bitfields to ordinary newtype fields. However, by including the bitfield size in the SDL translation, the Analyzer is given a possibility to check that these fields are not assigned values that will not fit in the corresponding bitfield.

Example 114 : Translation of bitfields

C++:

struct A {
unsigned int i : 12;
int : 3;
bool dirty : 1;
};

SDL:

NEWTYPE ptr_A Ref( A);
OPERATORS
ptr_A : -> ptr_A;
ptr_A : ptr_A -> ptr_A;
ENDNEWTYPE ptr_A;EXTERNAL 'C++';
NEWTYPE A
STRUCT
dirty bool : 1;
i unsigned_int : 12;
OPERATORS
A : -> A;
A : A -> A;
ENDNEWTYPE A;EXTERNAL 'C++';

Note that bitfields are a tool-specific SDL extension.

Friends

Rule: Friend declarations will not be translated to SDL.

Friendship between a class C and another declaration D only affects what members of C that the implementation of D may access. It is therefore uninteresting to supply this information in the SDL translation of the class C.

Inheritance

Rule: C++ inheritance is represented in SDL by adding the translation of all public base class members to the newtype that represents a derived class.

This rule simply means that the C++ inheritance hierarchy is flattened in the SDL newtype representation. The reason for choosing this translation strategy, instead of using SDL inheritance between newtypes, is that the semantics of C++ and SDL inheritance is quite different.

All public member variables and member functions (but not constructors) of direct or indirect bases of a class will be generated in the newtype that is the translation of that class. Such an inherited field or operator will normally have the same name in SDL as in C++, but in some cases it is necessary to prefix the name with the name of the class from which it is inherited3. This happens when the name of the inherited member is the same as the name of one of the members in the derived class. Example 115 below shows how such ambiguities between inherited members are handled.

Example 115 : Translation of inheritance

C++:

class A {
public:
int am;
A(char);
};
class B : public A {
public:
char bm;
virtual void calc();
void set();
};
class C : public B {
public:
int am;
double cm;
void calc(); // Redefines B::calc()
void set();
};

SDL:

NEWTYPE ptr_A Ref( A);
OPERATORS
ptr_A : -> ptr_A;
ptr_A : ptr_A -> ptr_A;
ENDNEWTYPE ptr_A;EXTERNAL 'C++';
NEWTYPE A
STRUCT
am int;
OPERATORS
A : char -> A;
A : A -> A;
ENDNEWTYPE A;EXTERNAL 'C++';
NEWTYPE ptr_B Ref( B);
OPERATORS
cast : ptr_B -> ptr_A; /*#OP(PY)*/
ptr_B : -> ptr_B;
ptr_B : ptr_B -> ptr_B;
ENDNEWTYPE ptr_B;EXTERNAL 'C++';
NEWTYPE B
STRUCT
am int;/* Inherited from A */
bm char;
OPERATORS
calc : B;
keyword_set /*#REFNAME 'set'*/ : B;
B : B -> B;
ENDNEWTYPE B;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
cast : ptr_C -> ptr_A; /*#OP(PY)*/
cast : ptr_C -> ptr_B; /*#OP(PY)*/
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
am int;
B_am /*#REFNAME 'B::am'*/ int;/* Inherited from A */
bm char;/* Inherited from B */
cm double;
OPERATORS
calc : C;
B_calc /*#REFNAME 'B::calc'*/ : C;/* Inherited from B */
keyword_set /*#REFNAME 'set'*/ : C;
B_keyword_set /*#REFNAME 'B::keyword_set'*/ : C;/* Inherited from B */
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

In C++, it is always possible to use a fully qualified name when accessing a class member, even if the name of the member is unambiguous without qualification. In the example above, the member variable bm in C that is inherited from B, may be referred to both as bm and B::bm. To avoid getting too many fields and operators in the generated newtypes, only the unqualified name can be used from SDL. This is natural since qualification in C++ normally only is done when necessary to resolve ambiguities.

There are more cases where C++ allows a member to be accessed by more than one name, while the SDL translation only supplies one of these possible names. For example, this applies for inherited types and static members as shown in Example 116 below.

Example 116 : Translation of inherited types and static members

C++:

class B {
public:
static int mv;
static char mf(double);
struct s {
int y;
} ms;
};
class D : public B {
};

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
B_mf /*#REFNAME 'B::mf'*/ : double -> char;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
NEWTYPE ptr_B Ref( B);
OPERATORS
ptr_B : -> ptr_B;
ptr_B : ptr_B -> ptr_B;
ENDNEWTYPE ptr_B;EXTERNAL 'C++';
NEWTYPE B
STRUCT
ms B_s;
mv int;
OPERATORS
mf : B, double -> char;
B : -> B;
B : B -> B;
ENDNEWTYPE B;EXTERNAL 'C++';
DCL B_mv /*#REFNAME 'B::mv'*/ int; EXTERNAL 'C++';
NEWTYPE ptr_B_s Ref( B_s);
OPERATORS
ptr_B_s : -> ptr_B_s;
ptr_B_s : ptr_B_s -> ptr_B_s;
ENDNEWTYPE ptr_B_s;EXTERNAL 'C++';
NEWTYPE B_s /*#REFNAME 'B::s'*/
STRUCT
y int;
OPERATORS
B_s /*#REFNAME 's'*/ : -> B_s;
B_s /*#REFNAME 's'*/ : B_s -> B_s;
ENDNEWTYPE B_s;EXTERNAL 'C++';
NEWTYPE ptr_D Ref( D);
OPERATORS
cast : ptr_D -> ptr_B; /*#OP(PY)*/
ptr_D : -> ptr_D;
ptr_D : ptr_D -> ptr_D;
ENDNEWTYPE ptr_D;EXTERNAL 'C++';
NEWTYPE D
STRUCT
ms B_s;/* Inherited from B */
mv int;/* Inherited from B */
OPERATORS
mf : D, double -> char;/* Inherited from B */
D : -> D;
D : D -> D;
ENDNEWTYPE D;EXTERNAL 'C++';

The declarations B::mv, B::mf and B::s in this example may in C++ also be referred to by means of the names D::mv, D::mf and D::s. This is not possible in the SDL translation, i.e. there are no declarations called D_mv, D_mf or D_s. CPP2SDL will choose the first version of the names since the members are declared in B.

Multiple Inheritance

The translation rule for C++ inheritance works also when a class inherits from more than one base class. However, the naming strategy described in "Inheritance" for handling ambiguous inherited members have to be generalized to also cover the case when a class inherits the same base class more than once.

Example 117 : Translation of multiple inheritance

C++:

class A {
public:
int m;
};
class B {
public:
int m;
int n;
};
class C: public A, public B {
};

SDL:

NEWTYPE ptr_A Ref( A);
OPERATORS
ptr_A : -> ptr_A;
ptr_A : ptr_A -> ptr_A;
ENDNEWTYPE ptr_A;EXTERNAL 'C++';
NEWTYPE A
STRUCT
m int;
OPERATORS
A : -> A;
A : A -> A;
ENDNEWTYPE A;EXTERNAL 'C++';
NEWTYPE ptr_B Ref( B);
OPERATORS
ptr_B : -> ptr_B;
ptr_B : ptr_B -> ptr_B;
ENDNEWTYPE ptr_B;EXTERNAL 'C++';
NEWTYPE B
STRUCT
m int;
n int;
OPERATORS
B : -> B;
B : B -> B;
ENDNEWTYPE B;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
cast : ptr_C -> ptr_B; /*#OP(PY)*/
cast : ptr_C -> ptr_A; /*#OP(PY)*/
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
A_m /*#REFNAME 'A::m'*/ int;/* Inherited from A */
B_m /*#REFNAME 'B::m'*/ int;/* Inherited from B */
n int;/* Inherited from B */
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

The names of the generated fields and operators correspond to the qualified names that must be used in C++ to access the members in question. The rule is to qualify an ambiguous member with the most specialized base class that makes the name of the member unique. In most cases this base class is the class where the ambiguous member is declared, but when the inheritance hierarchy forms a graph rather than a tree (see Example 118) it might be necessary to qualify with the name of a class further down on the inheritance path.

Note that in some extraordinary inheritance hierarchies, it is possible that a member of a base class is inaccessible in a derived class. This happens when the inherited member cannot be unambiguously qualified according to the naming rule described above. If this happens, CPP2SDL will not translate the member to SDL, and a warning will be printed.

Virtual and Non-Virtual Inheritance

Rule: Virtual inheritance is translated in the same way as ordinary inheritance.

Virtual inheritance affects the way data is replicated when multiple inheritance is used. As shown in "Multiple Inheritance" members that are inherited more than once from the same base class need to be prefixed in SDL.

Since data from a base class is not replicated in derived classes that inherit from the base class with virtual inheritance, it would be possible to avoid prefixing the name of the members that are virtually inherited from the base class. However, since a virtually inherited member in general may be accessed using many alternative prefixes (corresponding to possible paths for reaching the member in the inheritance graph), and none of these prefixes can be said to be more natural to use than the others, all versions of the member's name are included in the SDL translation. This is the reason why no difference is made between virtual and non-virtual inheritance in SDL.

Example 118 : Translation of virtual inheritance

C++:

class A {
public:
int a;
};
class C : public A {
};
class D : public virtual A {
};
class E : public virtual A {
};
class G : public C, public D, public E {
};

SDL:

NEWTYPE ptr_A Ref( A);
OPERATORS
ptr_A : -> ptr_A;
ptr_A : ptr_A -> ptr_A;
ENDNEWTYPE ptr_A;EXTERNAL 'C++';
NEWTYPE A
STRUCT
a int;
OPERATORS
A : -> A;
A : A -> A;
ENDNEWTYPE A;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
cast : ptr_C -> ptr_A; /*#OP(PY)*/
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
STRUCT
a int;/* Inherited from A */
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';
NEWTYPE ptr_D Ref( D);
OPERATORS
cast : ptr_D -> ptr_A; /*#OP(PY)*/
ptr_D : -> ptr_D;
ptr_D : ptr_D -> ptr_D;
ENDNEWTYPE ptr_D;EXTERNAL 'C++';
NEWTYPE D
STRUCT
a int;/* Inherited from A */
OPERATORS
D : -> D;
D : D -> D;
ENDNEWTYPE D;EXTERNAL 'C++';
NEWTYPE ptr_E Ref( E);
OPERATORS
cast : ptr_E -> ptr_A; /*#OP(PY)*/
ptr_E : -> ptr_E;
ptr_E : ptr_E -> ptr_E;
ENDNEWTYPE ptr_E;EXTERNAL 'C++';
NEWTYPE E
STRUCT
a int;/* Inherited from A */
OPERATORS
E : -> E;
E : E -> E;
ENDNEWTYPE E;EXTERNAL 'C++';
NEWTYPE ptr_G Ref( G);
OPERATORS
cast : ptr_G -> ptr_E; /*#OP(PY)*/
cast : ptr_G -> ptr_D; /*#OP(PY)*/
cast : ptr_G -> ptr_C; /*#OP(PY)*/
ptr_G : -> ptr_G;
ptr_G : ptr_G -> ptr_G;
ENDNEWTYPE ptr_G;EXTERNAL 'C++';
NEWTYPE G
STRUCT
C_a /*#REFNAME 'C::a'*/ int;/* Inherited from A */
D_a /*#REFNAME 'D::a'*/ int;/* Inherited from A */
E_a /*#REFNAME 'E::a'*/ int;/* Inherited from A */
OPERATORS
G : -> G;
G : G -> G;
ENDNEWTYPE G;EXTERNAL 'C++';

Inheritance Access Specifier

Rule: Only members that are inherited using public inheritance are translated to SDL.

When the inheritance is private or protected, the members of the base class are not accessible from outside the class. It is therefore natural to exclude members, that are inherited from private and protected bases, in the newtype that represents the derived class.

Example 119 : Translation of inheritance with different access specifiers

C++:

class X {
public:
int a;
void f();
};
class Y1 : public X {};
class Y2 : protected X {};
class Y3 : private X {};

SDL:

NEWTYPE ptr_X Ref( X);
OPERATORS
ptr_X : -> ptr_X;
ptr_X : ptr_X -> ptr_X;
ENDNEWTYPE ptr_X;EXTERNAL 'C++';
NEWTYPE X
STRUCT
a int;
OPERATORS
f : X;
X : -> X;
X : X -> X;
ENDNEWTYPE X;EXTERNAL 'C++';
NEWTYPE ptr_Y1 Ref( Y1);
OPERATORS
cast : ptr_Y1 -> ptr_X; /*#OP(PY)*/
ptr_Y1 : -> ptr_Y1;
ptr_Y1 : ptr_Y1 -> ptr_Y1;
ENDNEWTYPE ptr_Y1;EXTERNAL 'C++';
NEWTYPE Y1
STRUCT
a int;/* Inherited from X */
OPERATORS
f : Y1;/* Inherited from X */
Y1 : -> Y1;
Y1 : Y1 -> Y1;
ENDNEWTYPE Y1;EXTERNAL 'C++';
NEWTYPE ptr_Y2 Ref( Y2);
OPERATORS
ptr_Y2 : -> ptr_Y2;
ptr_Y2 : ptr_Y2 -> ptr_Y2;
ENDNEWTYPE ptr_Y2;EXTERNAL 'C++';
NEWTYPE Y2
OPERATORS
Y2 : -> Y2;
Y2 : Y2 -> Y2;
ENDNEWTYPE Y2;EXTERNAL 'C++';
NEWTYPE ptr_Y3 Ref( Y3);
OPERATORS
ptr_Y3 : -> ptr_Y3;
ptr_Y3 : ptr_Y3 -> ptr_Y3;
ENDNEWTYPE ptr_Y3;EXTERNAL 'C++';
NEWTYPE Y3
OPERATORS
Y3 : -> Y3;
Y3 : Y3 -> Y3;
ENDNEWTYPE Y3;EXTERNAL 'C++';

The inheritance access specifier also affects how casting from the derived type to the base type can be done. This is described in "Type Compatibility between Inherited Classes" and in "Type Compatibility between Pointers to Inherited Classes" .

Type Compatibility between Inherited Classes

Rule: An object of a derived class may be assigned to an object of a base class by using an explicit cast operator in SDL.

The above assignment (known as slicing) is type-compatible in C++ without the use of a cast operator. Since only the common members are copied in the assignment, this operation is somewhat dangerous and is not generally recommended. Therefore, the cast operators that are needed in SDL to do slicing between objects, are only generated when the
-slicing option is set.

Example 120 : Generation of operators for slicing

C++:

class C {};
class D {};
class CD : public C, public D {};

SDL:

NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';
NEWTYPE ptr_D Ref( D);
OPERATORS
ptr_D : -> ptr_D;
ptr_D : ptr_D -> ptr_D;
ENDNEWTYPE ptr_D;EXTERNAL 'C++';
NEWTYPE D
OPERATORS
D : -> D;
D : D -> D;
ENDNEWTYPE D;EXTERNAL 'C++';
NEWTYPE ptr_CD Ref( CD);
OPERATORS
cast : ptr_CD -> ptr_D; /*#OP(PY)*/
cast : ptr_CD -> ptr_C; /*#OP(PY)*/
ptr_CD : -> ptr_CD;
ptr_CD : ptr_CD -> ptr_CD;
ENDNEWTYPE ptr_CD;EXTERNAL 'C++';
NEWTYPE CD
OPERATORS
cast : CD -> D; /*#OP(PY)*/
cast : CD -> C; /*#OP(PY)*/
CD : -> CD;
CD : CD -> CD;
ENDNEWTYPE CD;EXTERNAL 'C++';

Note that the inheritance access specifier affects how these cast operators are generated. A cast operator from a class D to a class B will only be generated if B is a public unambiguous base of D. If it is private or protected, or is an ambiguous base for D, it is not allowed to cast from D to B.

Type Compatibility between Pointers to Inherited Classes

Rule: A pointer to an object of a derived class may be assigned to a pointer to an object of a base class by using an explicit cast operator in SDL.

The above assignment is type-compatible in C++, i.e. "up-casts" in a class hierarchy are implicit in C++. This is an important property of object-oriented languages that support for example polymorphism. In SDL, however, the newtypes for a base class and a derived class will be unrelated and thus type incompatible. To support up-casting in SDL, explicit cast operators are generated in the newtype that represents the pointer type to a derived class.

Example 121 : Generation of cast operators for up-casting

C++:

class C {};
class D {};
class CD : public C, public D {};

SDL:

NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';
NEWTYPE ptr_D Ref( D);
OPERATORS
ptr_D : -> ptr_D;
ptr_D : ptr_D -> ptr_D;
ENDNEWTYPE ptr_D;EXTERNAL 'C++';
NEWTYPE D
OPERATORS
D : -> D;
D : D -> D;
ENDNEWTYPE D;EXTERNAL 'C++';
NEWTYPE ptr_CD Ref( CD);
OPERATORS
cast : ptr_CD -> ptr_D; /*#OP(PY)*/
cast : ptr_CD -> ptr_C; /*#OP(PY)*/
ptr_CD : -> ptr_CD;
ptr_CD : ptr_CD -> ptr_CD;
ENDNEWTYPE ptr_CD;EXTERNAL 'C++';
NEWTYPE CD
OPERATORS
CD : -> CD;
CD : CD -> CD;
ENDNEWTYPE CD;EXTERNAL 'C++';

Note that the inheritance access specifier is taken into consideration so that a cast operator from Ref(D) to Ref(B) only will be generated if the class B is a public unambiguous base of the class D.

Sometimes it is necessary to do down-casts, or even cross-casts, in a class hierarchy. Such casts (known as dynamic casts) are explicit both in C++ and SDL. See "Run-Time Type Information and Dynamic Cast" for more information.

Abstract Classes

Rule: An abstract class is translated to a newtype without constructor operators.

This translation rule makes it possible to declare pointers to an abstract class, but no objects of such a class may be allocated since there are no constructor operators that can be used as argument to the new operator (see "Dynamic Memory Management" ).

Example 122 : Translation of abstract classes

C++:

class C {
public:
virtual int f(int) = 0; // pure virtual member function
C() {};
};
class D : public C {
};

SDL:

NEWTYPE ptr_C Ref( C);
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
OPERATORS
f : C, int -> int;
ENDNEWTYPE C;EXTERNAL 'C++';
NEWTYPE ptr_D Ref( D);
OPERATORS
cast : ptr_D -> ptr_C; /*#OP(PY)*/
ENDNEWTYPE ptr_D;EXTERNAL 'C++';
NEWTYPE D
OPERATORS
f : D, int -> int;/* Inherited from C */
ENDNEWTYPE D;EXTERNAL 'C++';

Note from the example above that abstractness is inherited to a derived class if not each pure virtual member function of all its base classes are redefined in the derived class.

Run-Time Type Information and Dynamic Cast

Rule: A pointer to an object of a base class may be assigned to a pointer to an object of a derived class, or to a pointer to an object of a base class of such a derived class, by using an explicit cast operator in SDL.

The above assignments require a dynamic cast in C++, which is done with an explicit cast operator that supports down-casts and cross-casts in an inheritance hierarchy. Since these casts require run-time type information (RTTI) about the dynamic type of an object, most C++ compilers have an option that must be set to safely support dynamic casts. For the same reason, CPP2SDL also has such an option called -rtti. If it is set, cast operators will be generated that enable the type conversions that are possible in C++ using dynamic casts.

The source type of a dynamic cast must be polymorphic, i.e. contain one or more virtual member functions, possibly inherited ones. For each such polymorphic class X, cast operators will be generated that convert from Ref(X) to Ref(Y), for each class Y that either inherits from X (down-casts), or is a public base class of a class that inherits from X (cross-casts).

Example 123 below illustrates this translation rule. It is assumed that all classes in the example contain virtual functions and thus are polymorphic.

Example 123 : Generation of cast operators for dynamic casting

C++:

class A {};
class B: public A {};
class E {};
class D: protected E {};
class C: public B, public D {};

SDL:

NEWTYPE ptr_A Ref( A);
OPERATORS
ptr_A : -> ptr_A;
ptr_A : ptr_A -> ptr_A;
ENDNEWTYPE ptr_A;EXTERNAL 'C++';
NEWTYPE A
OPERATORS
A : -> A;
A : A -> A;
ENDNEWTYPE A;EXTERNAL 'C++';
NEWTYPE ptr_B Ref( B);
OPERATORS
cast /*#REFNAME 'dynamic_cast<B*>'*/ : ptr_A -> ptr_B;
cast : ptr_B -> ptr_A; /*#OP(PY)*/
ptr_B : -> ptr_B;
ptr_B : ptr_B -> ptr_B;
ENDNEWTYPE ptr_B;EXTERNAL 'C++';
NEWTYPE B
OPERATORS
B : -> B;
B : B -> B;
ENDNEWTYPE B;EXTERNAL 'C++';
NEWTYPE ptr_E Ref( E);
OPERATORS
ptr_E : -> ptr_E;
ptr_E : ptr_E -> ptr_E;
ENDNEWTYPE ptr_E;EXTERNAL 'C++';
NEWTYPE E
OPERATORS
E : -> E;
E : E -> E;
ENDNEWTYPE E;EXTERNAL 'C++';
NEWTYPE ptr_D Ref( D);
OPERATORS
ptr_D : -> ptr_D;
ptr_D : ptr_D -> ptr_D;
ENDNEWTYPE ptr_D;EXTERNAL 'C++';
NEWTYPE D
OPERATORS
D : -> D;
D : D -> D;
ENDNEWTYPE D;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
cast /*#REFNAME 'dynamic_cast<A*>'*/ : ptr_D -> ptr_A;
cast /*#REFNAME 'dynamic_cast<B*>'*/ : ptr_D -> ptr_B;
cast /*#REFNAME 'dynamic_cast<D*>'*/ : ptr_A -> ptr_D;
cast /*#REFNAME 'dynamic_cast<D*>'*/ : ptr_B -> ptr_D;
cast /*#REFNAME 'dynamic_cast<C*>'*/ : ptr_D -> ptr_C;
cast : ptr_C -> ptr_D; /*#OP(PY)*/
cast /*#REFNAME 'dynamic_cast<C*>'*/ : ptr_A -> ptr_C;
cast : ptr_C -> ptr_A; /*#OP(PY)*/
cast /*#REFNAME 'dynamic_cast<C*>'*/ : ptr_B -> ptr_C;
cast : ptr_C -> ptr_B; /*#OP(PY)*/
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
OPERATORS
C : -> C;
C : C -> C;
ENDNEWTYPE C;EXTERNAL 'C++';

Note that no cast operators are generated that cast to ptr_E since E is a protected base of D. But in fact there are no cast operators that cast from ptr_E neither. The somewhat subtle reason for this is that those operators cannot be used in practice, since the protected inheritance makes it impossible to have a variable with ptr_E as static type and ptr_C as dynamic type. CPP2SDL will therefore not generate these cast operators.

In C++ dynamic casts work both for pointers and references to objects. In SDL, however, it is only possible to do dynamic casts between pointers, since references are not explicitly represented in the translation (see "References" ).

Forward Declarations

Rule: A forward declaration is not translated to SDL.

This rule is valid for all forward declarations for which there are definitions later on in the header file. This is the most common case, and the purpose of such forward declarations is simply to make an identifier known to the C/C++ compiler so that it may be used before it is defined.

However, it is possible to make a forward declaration for which no definition exists in the header file. In that case CPP2SDL must generate an extra newtype to represent the missing definition. Since this extra newtype does not correspond to a real C/C++ type, it is marked with a
#NOTYPE directive.

Example 124 below contains two forward declarations, one of which has no corresponding definition (class C).

Example 124 : Translation of forward declarations

C++:

typedef struct S *fwdS;
class C *fwdC;
struct S {
int a;
};

SDL:

SYNTYPE fwdS = ptr_S
ENDSYNTYPE fwdS;EXTERNAL 'C++';
NEWTYPE C /*#NOTYPE*/
ENDNEWTYPE C;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
OPERATORS
ptr_C : -> ptr_C;
ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
DCL fwdC ptr_C; EXTERNAL 'C++';
NEWTYPE ptr_S Ref( S);
OPERATORS
ptr_S : -> ptr_S;
ptr_S : ptr_S -> ptr_S;
ENDNEWTYPE ptr_S;EXTERNAL 'C++';
NEWTYPE S
STRUCT
a int;
OPERATORS
S : -> S;
S : S -> S;
ENDNEWTYPE S;EXTERNAL 'C++';

Incomplete Types

Rule: An incomplete type declaration is translated to a newtype that may not be instantiated in SDL. This rule applies to all incomplete types even if they are declared within complete types. For example a tagless type within a container type will not be correctly instantiated in SDL.

Compare this translation rule with the one for namespaces (see "Namespaces" ). While a namespace does not define a type at all, an incomplete type declaration defines an incomplete type that may not be referred to. That is the reason why such a newtype must not be instantiated in SDL.

C/C++ allows declarations of incomplete classes, structs, unions and enums, i.e. all types having a tag. Incomplete types are therefore also called tag-less types.

Incomplete types can be used in

  • data declarations (i.e. variables, constants etc.)
  • type declarations (i.e. typedefs)
  • "useless" declarations (i.e. without declaring data or type)

Example 125 : Translation of incomplete types

C++:

struct S {
int i;
struct {
int j;
} ss1, *ss2, ss3[2]; // Data declarations
};
typedef enum {
a, b, c
} ss1, *ss2, ss3[2]; // Type declarations
typedef struct {
int i;
}; // Missing type name - "useless" declaration
struct {
int i;
}; // Missing variable name - "useless" declaration

SDL:

NEWTYPE S_incomplete_ss3
STRUCT
j int;
ENDNEWTYPE S_incomplete_ss3;
NEWTYPE ptr_S_incomplete_ss3 Ref( S_incomplete_ss3);
OPERATORS
ptr_S_incomplete_ss3 : -> ptr_S_incomplete_ss3;
ptr_S_incomplete_ss3 : ptr_S_incomplete_ss3 ->
ptr_S_incomplete_ss3;
ENDNEWTYPE ptr_S_incomplete_ss3;EXTERNAL 'C++';
NEWTYPE arr_2_S_incomplete_ss3 CArray(2, S_incomplete_ss3);
ENDNEWTYPE arr_2_S_incomplete_ss3;EXTERNAL 'C++';
NEWTYPE ptr_S Ref( S);
OPERATORS
ptr_S : -> ptr_S;
ptr_S : ptr_S -> ptr_S;
ENDNEWTYPE ptr_S;EXTERNAL 'C++';
NEWTYPE S
STRUCT
i int;
ss1 S_incomplete_ss3;
ss2 ptr_S_incomplete_ss3;
ss3 arr_2_S_incomplete_ss3;
OPERATORS
S : -> S;
S : S -> S;
ENDNEWTYPE S;EXTERNAL 'C++';
NEWTYPE incomplete_ss3
LITERALS a, b, c;
OPERATORS
EnumToInt : incomplete_ss3 -> int; /*#OP(PY)*/
ORDERING;
ENDNEWTYPE incomplete_ss3;
SYNTYPE ss1 = incomplete_ss3
ENDSYNTYPE ss1;EXTERNAL 'C++';
NEWTYPE ptr_incomplete_ss3 Ref( incomplete_ss3);
OPERATORS
ptr_incomplete_ss3 : -> ptr_incomplete_ss3;
ptr_incomplete_ss3 : ptr_incomplete_ss3 ->
ptr_incomplete_ss3;

ENDNEWTYPE ptr_incomplete_ss3;EXTERNAL 'C++';
SYNTYPE ss2 = ptr_incomplete_ss3
ENDSYNTYPE ss2;EXTERNAL 'C++';
NEWTYPE arr_2_incomplete_ss3 CArray( 2, incomplete_ss3);
ENDNEWTYPE arr_2_incomplete_ss3;EXTERNAL 'C++';
SYNTYPE ss3 = arr_2_incomplete_ss3
ENDSYNTYPE ss3;EXTERNAL 'C++';

As can be seen in the example, incomplete types that are used in data or type declarations will have the name of the last declared variable or type, prefixed with a user-configurable string that by default is "incomplete_". The option -prefix can be used to configure this string.

Incomplete types in "useless" declarations will not be translated to SDL, and CPP2SDL will issue warnings that the declarations were ignored.

Note that the translation of incomplete enum declarations differs from the normal translation rule of an enum declaration. The differences are listed in "Enumerated Types" .

Finally note that incomplete classes, structs and unions define scope units although they are incomplete. Their names thus follows the rules for naming of scope units described in "Scope Units" .

Dynamic Memory Management

Rule: The C/C++ primitives for dynamic memory management is represented in SDL by means of special operators.

Dynamic memory management is done differently in C and C++. How C or C++ data is dynamically allocated and deallocated in SDL therefore depends on whether CPP2SDL executes in C or C++ mode (controlled by the option -c). In both cases dynamic memory management is done by means of special SDL operators that are defined in the Ref generator. However, the definition of the Ref generator is different in C and C++ mode (see "SDL Library for Fundamental C/C++ Types" ).

C Mode

The following operators are used to support dynamic memory management of C data from SDL:

  • Make!
    Enables dynamic allocation of simple C data.
  • free
    Enables dynamic deallocation of data that was allocated by the Make! operator.

Example 126 : Dynamic memory management of C data from SDL

C:

struct S {
int i;
double j;
};

SDL:

NEWTYPE ptr_S Ref( S);
ENDNEWTYPE ptr_S;EXTERNAL 'C';
NEWTYPE S /*#REFNAME 'struct S'*/
STRUCT
i int;
j double;
ENDNEWTYPE S;EXTERNAL 'C';

SDL Usage:

dcl var s, ptrs ptr_s;
task {
ptrs := (. var .);
ptrs*>!i := 4;
free(ptrs);
};

C++ Mode

The following operators are used to support dynamic memory management of C++ data from SDL:

  • new4
    Enables dynamic allocation of scalar C++ data of, for example, class type, fundamental type, or pointer type. It corresponds to the C++ operator with the same name.
  • delete
    Enables dynamic deallocation of data that was allocated by the new operator. It corresponds to the C++ operator with the same name.
  • new_array
    Enables dynamic allocation of arrays of C++ data of, for example, class type, fundamental type, or pointer type. It corresponds to the C++ operator new[].
  • delete_array
    Enables dynamic deallocation of data that was allocated by the new_array operator. It corresponds to the C++ operator delete[].

Example 127 : Dynamic memory management of C++ data from SDL

C++:

struct S {
int i;
double j;
};

Import Specification:

TRANSLATE {
S**
int*
}

SDL:

NEWTYPE ptr_int Ref( int);
OPERATORS
ptr_int : -> ptr_int;
ptr_int : ptr_int -> ptr_int;
ENDNEWTYPE ptr_int;EXTERNAL 'C++';
NEWTYPE ptr_ptr_S Ref( ptr_S);
OPERATORS
ptr_ptr_S : -> ptr_ptr_S;
ptr_ptr_S : ptr_ptr_S -> ptr_ptr_S;
ENDNEWTYPE ptr_ptr_S;EXTERNAL 'C++';
NEWTYPE ptr_S Ref( S);
OPERATORS
ptr_S : -> ptr_S;
ptr_S : ptr_S -> ptr_S;'
ENDNEWTYPE ptr_S;EXTERNAL 'C++';
NEWTYPE S
STRUCT
i int;
j double;
OPERATORS
S : -> S;
S : S -> S;
ENDNEWTYPE S;EXTERNAL 'C++';

SDL Usage:

dcl ptrs ptr_s, ptrptrs ptr_ptr_s, ptri ptr_int;
task {
ptrs := new(s);
ptrs*>!i := 4;
ptrptrs := new(ptr_s);
ptri := new(int);
delete(ptrs);
delete(ptrptrs);
delete(ptri);
ptri := newArray(int, 5);
deleteArray(ptri);
};

The input to the new and new_array operators must be an operator that corresponds to a constructor in C++. To enable dynamic allocation of data with non-class types, there must thus exist constructor operators for these types. These operators correspond to the implicit parameter-less and copy constructors, which exist for each C++ type. The definition of these constructor operators are part of the non-generated SDL declarations that are included when the -generatecpptypes option is set (see "SDL Library for Fundamental C/C++ Types" ).

Overloaded Operators

Rule: An overloaded C++ operator is translated to a corresponding overloaded SDL operator.

Since the sets of operators that may be overloaded are different in C++ and SDL, not all overloaded C++ operators can be translated to SDL.

The table below shows which C++ operators that can be translated to SDL

:
C++ operator | Description | SDL operator
+ | (binary) Addition | +
- | (binary) Subtraction | -
* | (binary) Multiplication | *
* | (unary prefix) Dereference | *>
/ | (binary) Division | /
% | (binary) Modulo | rem
! | (unary prefix) Not | not
< | (binary) Less | <
> | (binary) Greater | >
<< | (binary) Left Shift | <
>> | (binary) Right Shift | >
== | (binary) Equal | =
!= | (binary) Not Equal | /=
<= | (binary) Less Equal | <=
>= | (binary) Greater Equal | >=
&& | (binary) And | and
|| | (binary) Or | or

Note that even if there is a corresponding SDL operator to translate to, a C++ operator could be declared in a way that would make it necessary to qualify its SDL name, which is not possible. This happens for example if the operator is declared to be static, or declared inside a namespace (see "Scope Units" for more about scope name qualifications). It may also happen due to name qualification rules for inherited members (see "Multiple Inheritance" ). CPP2SDL will issue a warning if it encounters an overloaded operator that cannot be translated.

The table above shows that the translation of the less and greater operators (<, >) is the same as the translation of the shift operators (<<, >>). Obviously, this may lead to ambiguities if both these operator pairs are overloaded in a class. In that case, the less and greater operators will have precedence, and CPP2SDL will issue a warning that the overloaded shift operators cannot be translated to SDL.

Example 128 : Translation of overloaded operators

C++:

class ostream {
public:
ostream& operator<(const char* p1);
ostream& operator<<(const char* p1);
ostream& operator>>(const char* p1);
static int operator%(int p1);
bool operator!();
};

SDL:

NEWTYPE ptr_char Ref( char);
OPERATORS
ptr_char : -> ptr_char;
ptr_char : ptr_char -> ptr_char;
ENDNEWTYPE ptr_char;EXTERNAL 'C++';
NEWTYPE ptr_ostream Ref( ostream);
OPERATORS
ptr_ostream : -> ptr_ostream;
ptr_ostream : ptr_ostream -> ptr_ostream;
ENDNEWTYPE ptr_ostream;EXTERNAL 'C++';
NEWTYPE ostream
OPERATORS
"not" /*#REFNAME 'operator!'*/ : ostream -> bool;
"rem" /*#REFNAME 'operator%'*/ : ostream, int -> int;
"<" /*#REFNAME 'operator<'*/ : ostream, ptr_char -> ostream;
ostream : -> ostream;
ostream : ostream -> ostream;
ENDNEWTYPE ostream;EXTERNAL 'C++';

Conversion Operators

Rule: A conversion operator is translated to a special conv operator in SDL.

In C++, a conversion operator is implicitly called by the compiler when a matching type conversion is needed. The conv operator, however, must be called explicitly in SDL.

Example 129 : Translation of conversion operators

C++:

class Tiny {
public:
operator int(); // Implicit conversion from Tiny to int
};

SDL:

NEWTYPE ptr_Tiny Ref( Tiny);
OPERATORS
ptr_Tiny : -> ptr_Tiny;
ptr_Tiny : ptr_Tiny -> ptr_Tiny;
ENDNEWTYPE ptr_Tiny;EXTERNAL 'C++';
NEWTYPE Tiny
OPERATORS
conv : Tiny -> int; /*#OP(PY)*/
Tiny : -> Tiny;
Tiny : Tiny -> Tiny;
ENDNEWTYPE Tiny;EXTERNAL 'C++';

Note that the conv operator returns the target type of the type conversion specified by the conversion operator. The #OP(PY) directive tells the Code Generator that the operator is implicitly called in C++.

Templates

Rule: A template declaration is translated to SDL by instantiating it.

A template declaration as such cannot be translated to SDL. Only specified instantiations of the template can be translated. CPP2SDL will print a warning about this when a template declaration is encountered.

A template instantiation may of course be present in the input headers. In that case CPP2SDL will translate the template instantiation by substituting all formal template arguments in the template declaration with the actual template arguments used in the template instantiation. If the input headers contain no suitable instantiation of a certain template, an import specification may be used to provide such an instantiation. See "Template Instantiations" to learn more about that.

There are two main kinds of template declarations in C++; class templates and function templates.

Class Templates

Rule: An instantiation of a class template is translated in the same way as the non-template class that is obtained if all formal arguments of the class template declaration are substituted with the actual arguments of the class template instantiation.

This translation rule implies that class template instantiations will become newtypes in SDL. The name of such a newtype will consist of the name of the template class, followed by the names of all actual template arguments of the template instantiation. The name will also be prefixed with a string that by default is "tpl_". The option -prefix can be used to configure this string.

Example 130 : Translation of class template instantiations

C++:

template <class T> class C {
public:
T t;
T f();
C(T v);
};
typedef C<int> mytype; // Class template instantiation

SDL:

NEWTYPE ptr_tpl_C_int Ref( tpl_C_int);
OPERATORS
ptr_tpl_C_int : -> ptr_tpl_C_int;
ptr_tpl_C_int : ptr_tpl_C_int -> ptr_tpl_C_int;
ENDNEWTYPE ptr_tpl_C_int;EXTERNAL 'C++';
NEWTYPE tpl_C_int /*#REFNAME 'C<int >'*/
STRUCT
t int;
OPERATORS
tpl_C_int /*#REFNAME 'C'*/ : int -> tpl_C_int;
f : tpl_C_int -> int;
tpl_C_int /*#REFNAME 'C'*/ : tpl_C_int -> tpl_C_int;
ENDNEWTYPE tpl_C_int;EXTERNAL 'C++';
SYNTYPE mytype = tpl_C_int
ENDSYNTYPE mytype;EXTERNAL 'C++';

Note that a #REFNAME directive passes the C++ name of the class template instantiation to the Code Generator.

Function Templates

Rule: An instantiation of a function template is translated in the same way as the non-template function that is obtained if all formal arguments of the function template declaration are substituted with the actual arguments of the function template instantiation.

This translation rule implies that function template instantiations will become operators in SDL. The name of such an operator will consist of the name of the template function, followed by the names of all actual template arguments of the template instantiation. The name will also be prefixed with a string that by default is "tpl_". The option -prefix can be used to configure this string.

Since a function template is instantiated when called, a C++ header file will normally not contain any function template instantiations. Instead an import specification should be used to provide the necessary instantiations (see "Template Instantiations" ). In Example 131 below an import specification is used to instantiate the template function with the type int*.

Example 131 : Translation of function template instantiations

C++:

template <class T> T func(T t);

Import Specification:

TRANSLATE {
func<int*>
}

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
tpl_func_ptr_int /*#REFNAME 'func<int* >'*/ : ptr_int
-> ptr_int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
NEWTYPE ptr_int Ref( int);
OPERATORS
ptr_int : -> ptr_int;
ptr_int : ptr_int -> ptr_int;
ENDNEWTYPE ptr_int;EXTERNAL 'C++';

As can be seen from the translation of the example above, the #REFNAME directive contains the C++ name of the template instantiation written on the so called explicit form5. This makes the Code Generator use this explicit form when the template function is called from SDL.

Note:

Calling a function template from SDL requires that the target C++ compiler can handle calls using the explicit form of the function template instantiation.

Default Template Arguments

Rule: An instantiation of a template declaration with default arguments is translated in the same way as an ordinary template instantiation, where omitted actual arguments in the instantiation are substituted with the specified default types or values.

This translation rule is very similar to the one used for functions with default arguments (see "Default Arguments" ).

Example 132 : Translation of templates with default arguments

C++:

template <class T, class U = char, int i = 5> class C {
public:
T t[i];
T f();
C(U p1);
};
C<int> var1; // Using all the default values
C<int, bool> var2; // Using the default value for i
C<int, bool, 5> var3; // Not using any default value

SDL:

NEWTYPE ptr_tpl_C_int_char_5 Ref( tpl_C_int_char_5);
OPERATORS
ptr_tpl_C_int_char_5 : -> ptr_tpl_C_int_char_5;
ptr_tpl_C_int_char_5 : ptr_tpl_C_int_char_5 ->
ptr_tpl_C_int_char_5;
ENDNEWTYPE ptr_tpl_C_int_char_5;EXTERNAL 'C++';
NEWTYPE tpl_C_int_char_5 /*#REFNAME 'C<int, char, 5 >'*/
STRUCT
t arr_5_int;
OPERATORS
tpl_C_int_char_5 /*#REFNAME 'C'*/ : char ->
tpl_C_int_char_5;
f : tpl_C_int_char_5 -> int;
tpl_C_int_char_5 /*#REFNAME 'C'*/ : tpl_C_int_char_5
-> tpl_C_int_char_5;
ENDNEWTYPE tpl_C_int_char_5;EXTERNAL 'C++';
DCL var1 tpl_C_int_char_5; EXTERNAL 'C++';
DCL var2 tpl_C_int_bool_5; EXTERNAL 'C++';
NEWTYPE arr_5_int CArray( 5, int);
ENDNEWTYPE arr_5_int;EXTERNAL 'C++';
NEWTYPE ptr_tpl_C_int_bool_5 Ref( tpl_C_int_bool_5);
OPERATORS
ptr_tpl_C_int_bool_5 : -> ptr_tpl_C_int_bool_5;
ptr_tpl_C_int_bool_5 : ptr_tpl_C_int_bool_5 ->
ptr_tpl_C_int_bool_5;
ENDNEWTYPE ptr_tpl_C_int_bool_5;EXTERNAL 'C++';
NEWTYPE tpl_C_int_bool_5 /*#REFNAME 'C<int, bool, 5 >'*/
STRUCT
t arr_5_int;
OPERATORS
tpl_C_int_bool_5 /*#REFNAME 'C'*/ : bool ->
tpl_C_int_bool_5;
f : tpl_C_int_bool_5 -> int;
-> tpl_C_int_bool_5;
ENDNEWTYPE tpl_C_int_bool_5;EXTERNAL 'C++';
DCL var3 tpl_C_int_bool_5; EXTERNAL 'C++';

Note that although the template instantiations of var2 and var3 in the example above look different, they evaluate to the same template type both in C++ and in the SDL translation.

Miscellaneous

This section covers some miscellaneous issues that have not been discussed so far. They are divided into constructs that are part of the C or C++ languages, and constructs that are not part of the languages as such, but that nevertheless may be found in an input C/C++ header file.

Language Constructs

Volatile

Rule: A volatile declaration is translated in the same way as an ordinary declaration.

The volatile specifier can be looked upon as some kind of compiler directive, and needs therefore not be visible in the SDL translation.

Linkage

Rule: The linkage of a C/C++ identifier is not visible in the SDL translation of the identifier.

There is one important exception to this rule; static linkage of class members affects their translation as described in "Static Members" .

In general, the linkage of a C/C++ identifier can be specified to be internal or external using the keywords static or extern (although the former is a deprecated feature in C++ for all declarations but class members). In C++ it is also possible to use the extern keyword to specify that a set of declarations have C linkage, i.e. belong to a translation unit that is compiled with a C compiler.

Example 133 : Translation of identifiers with different linkage

C++:

extern int a; // Declaration of a
extern int a; // Legal redeclaration of a
int a; // Definition of a
extern "C" {
struct S {
int x;
};
}

SDL:

DCL a int; EXTERNAL 'C++';
NEWTYPE ptr_S Ref( S);
OPERATORS
ptr_S : -> ptr_S;
ptr_S : ptr_S -> ptr_S;
ENDNEWTYPE ptr_S;EXTERNAL 'C++';
NEWTYPE S
STRUCT
x int;
OPERATORS
S : -> S;
S : S -> S;
ENDNEWTYPE S;EXTERNAL 'C++';

Note that the extern "C" directive in this example does not affect the mapping of S at all. For example, it will be possible to instantiate S using the new operator.

Non-Language Constructs

Macros

Rule: Macros are not translated to SDL.

The reason for not translating macros is that they are not part of the C or C++ languages. Macros are expanded and removed by the preprocessor before CPP2SDL performs the translation.

Some header files (especially C headers) contain numerous macros that could be useful or even essential to access in SDL. Fortunately most macros can actually be accessed from SDL, although they are not translated by CPP2SDL. Refer to "Constants" for more information.

SDL Sorts in C/C++

Rule: A C/C++ type called "SDL_<sort>", where <sort> is a predefined SDL sort, is translated to that SDL sort.

Since this translation rule restricts the way ordinary C/C++ types may be named, it is only respected by CPP2SDL if the -sdlsorts option is set.

Example 134 : Translation of types referring to SDL sorts

C++:

SDL_Real func(SDL_Integer, int);

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
func : Integer, int -> Real;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';

The feature of referring to SDL sorts from a C/C++ header file may be useful if the header has been designed to be used from SDL exclusively.

1

A tagged type is a class, struct, union or enum type with a tag.

2

This name indicates that the newtype represents the global scope in C/C++. In C++ terminology this scope is often called the global namespace.

3

This naming rule is generalized in "Multiple Inheritance" .

4

In fact the Make! operator can also be used in C++ mode. In that case it behaves exactly like the new operator.

5

In the explicit form of a function template instantiation, all actual template arguments are provided explicitly in the instantiation rather than being deduced from the types of the actual arguments in a call to the function template.


Special Translation Rules for C Compilers

CPP2SDL by default assumes that its input is C++ code, and that the target compiler is a C++ compiler. In order to also support C code and C target compilers, the translation rules have to be slightly modified. CPP2SDL does this if the -c option is set. The tool then executes in "C mode".

A general difference is how the external specifier for all SDL declarations will be generated. Normally this specifier is followed by the string `C++' to tell the Code Generator that the declaration was translated from a C++ declaration. In C mode the string will instead be `C'.

Example 135 : Different external specifier in C mode

C++:

const int a;

SDL:

SYNONYM a int = EXTERNAL 'C';

In C, a struct or a union is not a scope unit, which means that declarations inside a struct or a union should be treated as ordinary declarations. This means that the #REFNAME directive that normally is used for specifying the qualified name of for example a nested struct declaration, will not be printed in C mode.

Instead, a #REFNAME directive will be inserted after the name of newtypes that represent tagged types (i.e. structs, unions and enums). The reason is that C, contrary to C++, does not allow such types to be referenced only with the name of the tag. Another place where the "full" type name is required in C mode is in the C style cast that is generated by means of a #REFNAME directive for IntToEnum operators (see "Enumerated Types" ).

Example 136 : Differences in translation of structs, unions and enums

C++:

struct S {
int a;
struct SS {
int b;
};
};
typedef enum E {e1, e2, e3} Etype;

SDL:

NEWTYPE ptr_SS Ref( SS);
ENDNEWTYPE ptr_SS;EXTERNAL 'C';
NEWTYPE SS /*#REFNAME 'struct SS'*/
STRUCT
b int;
ENDNEWTYPE SS;EXTERNAL 'C';
NEWTYPE ptr_S Ref( S);
ENDNEWTYPE ptr_S;EXTERNAL 'C';
NEWTYPE S /*#REFNAME 'struct S'*/
STRUCT
a int;
ENDNEWTYPE S;EXTERNAL 'C';
NEWTYPE E /*#REFNAME 'enum E'*/
LITERALS e1, e2, e3;
OPERATORS
IntToEnum /*#REFNAME '(enum E)'*/ : int -> E;
EnumToInt : E -> int; /*#OP(PY)*/
ORDERING;
ENDNEWTYPE E;EXTERNAL 'C';
SYNTYPE Etype = E
ENDSYNTYPE Etype;EXTERNAL 'C';

Finally, note that memory allocation is done differently in C and C++. This is reflected in SDL by using a different definition of the Ref generator when CPP2SDL executes in C mode, where for example the new, delete, new_array, and delete_array operators are not present. See "Dynamic Memory Management" and "SDL Library for Fundamental C/C++ Types" for more information.


SDL Library for Fundamental C/C++ Types

The SDL declarations that are generated by CPP2SDL will normally not be semantically correct on their own. They typically contain several references to SDL sorts that represent fundamental C/C++ types, for example int, char and bool, and type declarators such as pointers (*) and arrays ([]). The SDL representations of all fundamental C/C++ types and type declarators are defined in a library consisting of a few SDL/PR files. The table below lists these files and their contents.

SDL/PR file
Contents
BasicCTypes.pr

Contains SDL representations of fundamental C types. Also contains representations for an untyped pointer (void*) and the array type declarator ([]).
SYNTYPE int = Integer
ENDSYNTYPE int;

SYNTYPE unsigned_int = Integer
ENDSYNTYPE unsigned_int;

SYNTYPE long_int = Integer
ENDSYNTYPE long_int;

SYNTYPE unsigned_long_int = Integer
ENDSYNTYPE unsigned_long_int;

SYNTYPE short_int = Integer
ENDSYNTYPE short_int;

SYNTYPE unsigned_short_int = Integer
ENDSYNTYPE unsigned_short_int;

SYNTYPE char = Character
ENDSYNTYPE char;

SYNTYPE signed_char = Character
ENDSYNTYPE signed_char;

SYNTYPE unsigned_char = Octet
ENDSYNTYPE unsigned_char;

SYNTYPE float = Real
ENDSYNTYPE float;

SYNTYPE double = Real
ENDSYNTYPE double;

NEWTYPE ptr_void
LITERALS Null;
DEFAULT Null;
ENDNEWTYPE ptr_void;

GENERATOR CArray (CONSTANT Length, TYPE
Itemsort)
OPERATORS
modify!: CArray, Integer, Itemsort -> CArray;
extract!: CArray, Integer -> Itemsort;
ENDGENERATOR CArray;
BasicC++Types.pr

Contains SDL representations of fundamental C++ types. Also contains operators representing implicit constructors for fundamental types.

Note that this file includes the files BasicCtypes.pr and ExtraCTypes.pr.
/*#INCLUDE 'BasicCTypes.pr'*/
/*#INCLUDE 'ExtraCTypes.pr'*/

SYNTYPE bool = Boolean
ENDSYNTYPE bool;

NEWTYPE wchar_t
ENDNEWTYPE wchar_t;

NEWTYPE __ConstructorOperators /*#NOTYPE*/
OPERATORS
int: -> int;
int: int -> int;
unsigned_int: -> unsigned_int;
unsigned_int: unsigned_int -> unsigned_int;
long_int: -> long_int;
long_int: long_int -> long_int;
unsigned_long_int: -> unsigned_long_int;
unsigned_long_int: unsigned_long_int -> unsigned_long_int;
short_int: -> short_int;
short_int: short_int -> short_int;
unsigned_short_int: -> unsigned_short_int;
unsigned_short_int: unsigned_short_int -> unsigned_short_int;
char: -> char;
char: char -> char;
signed_char: -> signed_char;
signed_char: signed_char -> signed_char;
unsigned_char: -> unsigned_char;
unsigned_char: unsigned_char -> unsigned_char;
float: -> float;
float: float -> float;
double: -> double;
double: double -> double;
ptr_void: -> ptr_void;
ptr_void: ptr_void -> ptr_void;
bool: -> bool;
bool: bool -> bool;
wchar_t: -> wchar_t;
wchar_t: wchar_t -> wchar_t;
ENDNEWTYPE __ConstructorOperators;EXTERNAL 'C++';
ExtraCTypes.pr

Contains SDL representations of additional fundamental C types.
SYNTYPE long_long_int = Integer
ENDSYNTYPE long_long_int;

SYNTYPE unsigned_long_long_int = Integer
ENDSYNTYPE unsigned_long_long_int;
ExtraC++Types.pr

Contains SDL representations of additional fundamental C++ types.
NEWTYPE__ExtraConstructorOperators
long_long_int : -> long_long_int;
long_long_int : long_long_int -> long_long_int;
unsigned_long_long_int : -> unsigned_long_long_int;
unsigned_long_long_int : unsigned_long_long_int -> unsigned_long_long_int
ENDNEWTYPE__ExtraConstructorOperators
CPointer.pr

Contains SDL representation of the C pointer type declarator (*).
GENERATOR Ref (TYPE Itemsort)
LITERALS Null, Alloc;
OPERATORS
modify! : Ref, Integer, Itemsort -> Ref;
extract! : Ref, Integer -> Itemsort;
"*>" : Ref, Itemsort -> Ref;
"*>" : Ref -> Itemsort;
"&" : Itemsort -> Ref;
make! : Itemsort -> Ref;
free : in/out Ref;
"+" : Ref, Integer -> Ref;
"-" : Ref, Integer -> Ref;
cast : Ref -> ptr_void;
cast : ptr_void -> Ref;
DEFAULT Null;
ENDGENERATOR Ref;
C++Pointer.pr

Contains SDL representation of the C++ pointer type declarator (*).
GENERATOR Ref (TYPE Itemsort)
LITERALS Null;
OPERATORS
modify! : Ref, Integer, Itemsort -> Ref;
extract! : Ref, Integer -> Itemsort;
"*>" : Ref, Itemsort -> Ref;
"*>" : Ref -> Itemsort;
"&" : Itemsort -> Ref;
new : Itemsort -> Ref;
delete : Ref;
new_array : Itemsort, Integer -> Ref;
delete_array : Ref;
"+" : Ref, Integer -> Ref;
"-" : Ref, Integer -> Ref;
cast : Ref -> ptr_void;
cast : ptr_void -> Ref;
DEFAULT Null;
ENDGENERATOR Ref;

If the option -generatecpptypes is set, CPP2SDL will include some of the files from the table above in the SDL translation. Which files that are included depends on if CPP2SDL executes in C or C++ mode (controlled by the -c option).

The following files will be included in C mode:

  • BasicCTypes.pr
  • CPointer.pr

The following files will be included in C++ mode:

  • BasicC++Types.pr
  • C++Pointer

The reason for breaking out the types long long int and unsigned long long int into separate files, is that not all compilers support these types. These files must be manually included if these types are present in the input headers.

Hint:

The syntype definitions of the SDL sorts that represent fundamental C/C++ types can easily be changed. For example, the definitions of the SDL sorts `char' and `unsigned char' could be swapped if the target platform specifies that a simple `char' is unsigned rather than signed.


Example usage of some C/C++ functionality

Overloaded Operators

This example illustrates how to call an operator which has been made accessible by CPP2SDL. There are two operators defined and used, the first being a member operator, and the second a non-member operator. Also see "Overloaded Operators" .

C++:

class CInt {
int val;
public:
CInt() : val(0) {};
CInt(int i) : val(i) {};
int value() const { return val; };

int operator+(const int& i){val+= i; return val;};
};

int operator+(const int& left, const CInt& right) {return right.value()+left;};

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
"+" /*#REFNAME 'operator+'*/ : int, CInt -> int;
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
/*#SDTREF(TEXT,header_CPP2SDL.i,16,7)*/
NEWTYPE ptr_CInt Ref( CInt);
OPERATORS
ptr_CInt : -> ptr_CInt;/* implicit parameter-less constructor */
ptr_CInt : ptr_CInt -> ptr_CInt;/* implicit copy constructor */
ENDNEWTYPE ptr_CInt;EXTERNAL 'C++';
/*#SDTREF(TEXT,header_CPP2SDL.i,16,7)*/
NEWTYPE CInt
OPERATORS
"+" /*#REFNAME 'operator+'*/ : CInt, int -> int;
CInt : -> CInt;
CInt : int -> CInt;
value : CInt -> int; /*#CONSTANT*/
CInt : CInt -> CInt;/* implicit copy constructor */
ENDNEWTYPE CInt;EXTERNAL 'C++';

Use in SDL:

String handling

It is possible to do C-style string handling in SDL, by using the standard C header string.h. By including `string.h' and `stdio.h' we are given access to the functions defined within them in SDL. You may notice that strcpy is defined in the hand written header as well as in `string.h'. The former definition allows us to assign the string "goodbye" to empty, without using the return value of strcpy, and importing it to SDL. Also needed is an allocate and deallocate function. An example allocate function has been defined in the header, a deallocate function should also be done in the practice to avoid memory leaks.

C:

#include<string.h>
#include<stdio.h>

#ifdef __CPP2SDL__
void strcpy(char*,char*);
#endif

typedef char* string;
char ara[10];
string hello= "hello";
string empty;

char* allocateString(int length) {
return (char*) calloc(length,sizeof(char));
}

SDL:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
memcpy : ptr_void, ptr_void, size_t -> ptr_void;
memcmp : ptr_void, ptr_void, size_t -> int;
memset : ptr_void, int, size_t -> ptr_void;
_strset : ptr_char, int -> ptr_char;
strcpy : ptr_char, ptr_char -> ptr_char;
strcat : ptr_char, ptr_char -> ptr_char;
strcmp : ptr_char, ptr_char -> int;
strlen : ptr_char -> size_t;
....
unlink : ptr_char -> int;
strcpy : ptr_char, ptr_char;
allocateString : int -> ptr_char;
ENDNEWTYPE global_namespace;EXTERNAL 'C';
...
SYNTYPE string = ptr_char
ENDSYNTYPE string;EXTERNAL 'C';
/*#SDTREF(TEXT,header_CPP2SDL.i,728,6)*/
NEWTYPE arr_10_char CArray( 10, char);
ENDNEWTYPE arr_10_char;EXTERNAL 'C';
/*#SDTREF(TEXT,header_CPP2SDL.i,728,6)*/
DCL ara arr_10_char; EXTERNAL 'C';
/*#SDTREF(TEXT,header_CPP2SDL.i,729,8)*/
DCL hello string; EXTERNAL 'C';
/*#SDTREF(TEXT,header_CPP2SDL.i,730,8)*/
DCL empty string; EXTERNAL 'C';

Use in SDL:

Type conversion

Some type conversions are easier in C/C++ than in SDL, in particular those that are implicit. An implicit type conversion must often be explicit in SDL, by introducing a simple cast operator that performs the conversion. For example, by using the mapping of SDL sorts between unsigned_char and char we can create a cast operator in SDL that converts a char to an Octet. (See "Fundamental Types" for more information). This corresponds to the implicit conversion in C/C++ between char and unsigned char.

Use in SDL:


Error Handling

The input headers to CPP2SDL have in many cases been compiled with a C/C++ compiler previously, and it should then be relatively uncommon that CPP2SDL will have to issue any error messages. However, differences in language support, and inappropriate preprocessor settings, are common sources for error reports also from input files that otherwise are perfectly correct.

If CPP2SDL finds an error in the input, a message will be printed that briefly describes the reason for the error.

Note:

The error messages produced by CPP2SDL are often less descriptive than the corresponding error messages from a C/C++ compiler. If CPP2SDL reports errors in a header file, it is therefore a good idea to run a C/C++ compiler on the same header file to get more information about the reason for the error.

The format of printed error messages are described in "Source and Error References" .

CPP2SDL performs a complete syntactic analysis of the input C/C++ code, and syntax errors are reported as shown in Example 137 below.

Example 137 : Syntax errors

File syn.h:

int f(};
conts int i = 7;

Command Prompt:

% cpp2sdl syn.h
Parsing C/C++ input...
Syntax errors found. Cannot perform SDL translation.
#SDTREF(TEXT,syn.h,1,7)
ERROR 3200 Syntax error.
#SDTREF(TEXT,syn.h,2,7)
ERROR 3200 Syntax error.
2 errors and 0 warnings.

CPP2SDL will proceed with semantic analysis only if no errors were found during the syntactic analysis. The semantic analysis that is done by CPP2SDL is not complete according to the C/C++ standards, but only a limited number of semantic tests are performed:

  • The type of variables, constants, typedefs, functions, function arguments, actual template arguments, and base classes are checked. If a type is undeclared, or if it depends on an undeclared type1, an error message will be issued.
  • The actual arguments of a template instantiation are checked against the formal arguments of the template definition. If there are too few or too many actual arguments, or if there are type mismatches between actual and formal arguments, an error message will be issued.

Example 138 : Semantic errors

File sem.h:

template <class U, int d> class S {
public:
U arr[d];
};
typedef unknown T; // T depends on undeclared type
const unknown a = 3;
T f(int, char);
S<T, 3> var;
typedef S<> t1; // Too few actual arguments
typedef S<char, 5, 5> t2; // Too many actual arguments
typedef S<int, int> t3; // Argument type mismatch

Command Prompt:

% cpp2sdl -errorlimit 10 sem.h
Parsing C/C++ input...
Translating C/C++ to SDL...
Generating SDL...
#SDTREF(TEXT,sem.h,11,9)
ERROR 3263 Illegal instantiation of template 'S'.
#SDTREF(TEXT,sem.h,10,9)
ERROR 3263 Illegal instantiation of template 'S'.
#SDTREF(TEXT,sem.h,9,9)
ERROR 3263 Illegal instantiation of template 'S'.
#SDTREF(TEXT,sem.h,8,3)
ERROR 3261 The type 'T' is undeclared, or is depending on an undeclared type.
#SDTREF(TEXT,sem.h,7,3)
ERROR 3261 The type 'T' is undeclared, or is depending on an undeclared type.
#SDTREF(TEXT,sem.h,6,15)
ERROR 3261 The type 'unknown' is undeclared, or is depending on an undeclared type.
#SDTREF(TEXT,sem.h,5,17)
ERROR 3261 The type 'unknown' is undeclared, or is depending on an undeclared type.
#SDTREF(TEXT,sem.h,1,33)
WARNING 3211 Cannot translate template declaration. The declaration will be ignored.
7 errors and 1 warnings.

Note that the command-line option -errorlimit can be used to set a limit for the number of errors to report before terminating a translation.

1

One example of such a type dependency is when the source type of a typedef type is undeclared. Usages of the typedef type will then be considered to be undeclared.


CPP2SDL Messages

CPP2SDL may produce three kinds of messages during the translation of a set of header files.

  • Error messages are printed if CPP2SDL finds any syntactic or semantic errors in the input header files. See "Example usage of some C/C++ functionality" for more information about how CPP2SDL handles errors in the input.
  • Warnings are given if CPP2SDL finds language constructs that for some reason cannot be fully translated. The tool also prints warnings if it has to make assumptions about a construct that not necessarily are valid.
  • Information messages are all other messages that are printed.

The rest of this section lists and explains all errors and warnings that may be issued by CPP2SDL.

Errors

ERROR 3200 Syntax error.

An error was found during the syntactic analysis of the input. CPP2SDL will not continue with semantic analysis and translation to SDL, since the program is not correct.

Note:

If this error message is printed for a program that is accepted by a C/C++ compiler, make sure that the correct language dialect has been set to CPP2SDL by means of the -dialect option.

ERROR 3260 The identifier <identifier name> is undeclared.

An identifier is undeclared, i.e. the program is not semantically correct and will therefore not be translated to SDL.

ERROR 3261 The type <type name> is undeclared, or is depending on an undeclared type.

A type is undeclared, or depends on a type that is undeclared. A type defined by a typedef of an undeclared type is an example of a type that depends on a undeclared type. Since the program is not semantically correct, it will not be translated to SDL.

ERROR 3262 The base <base class name> is undeclared.

A class inherits from a base class that is undeclared. This is a semantic error, and the program will thus not be translated to SDL.

ERROR 3263 Illegal instantiation of template <template name>.

A template instantiation is semantically incorrect. Make sure that the number of actual arguments in the template instantiation matches the number of formal arguments in the template declaration, and that the kinds of the arguments are correct. Since the program is not semantically correct, it will not be translated to SDL.

Warnings

WARNING 3201 Static member variable <variable name> will not be globally accessible since no SDL variables are allowed.

A static member variable cannot be fully translated, since no external variables are allowed in the context where the generated SDL declarations are to be injected. The static variable will still be accessible as an ordinary member variable, but not as a globally accessible variable. Unset the option -novariables to allow generation of external SDL variables.

WARNING 3202 Static overloaded operator <operator name> will not be globally accessible.

A static overloaded operator cannot be fully translated, since it is not possible to qualify the name of an overloaded operator in SDL which otherwise would be required. The static operator will still be accessible as an ordinary member overloaded operator, but not as a globally accessible overloaded operator. Refer to "Overloaded Operators" .

WARNING 3203 Cannot translate incomplete type declaration without declared objects. The declaration will be ignored.

An incomplete type declaration that is not used as the type of at least one object (e.g. variable, constant, or type) is a useless declaration that will not be translated to SDL. See "Incomplete Types" for more about useless incomplete type declarations.

WARNING 3204 Cannot translate overloaded operator, since it is declared in a namespace.

An overloaded operator declared in a namespace cannot be translated to SDL, since it is not possible to qualify the name of an overloaded operator in SDL which otherwise would be required. Refer to "Overloaded Operators" .

WARNING 3205 Cannot translate overloaded shift operator, since the '<' or '>' operator also is overloaded in this scope.

The translation rule for overloaded operators only supports translation of either the < and > operators or the << and >> operators. This warning is given if an operator from both these operator pairs are overloaded in a certain scope. See "Overloaded Operators" for more information.

WARNING 3206 Cannot translate overloaded operator, since no corresponding SDL operator exists.

An overloaded operator cannot be translated to SDL, since no appropriate SDL operator exists that could represent it. The table in "Overloaded Operators" shows what overloaded C++ operators that may be represented in SDL.

WARNING 3207 Unable to evaluate sizeof expression properly.

A constant expression contains a usage of the sizeof() operator, and could therefore not be safely evaluated by CPP2SDL. The translation of the constant expression may thus be incorrect, and should be manually reviewed. See "Constant Expressions" for more information about constant expressions.

WARNING 3208 The member <member name> of <class name> inherited via <base class names> is inaccessible and will not be translated.

An inherited class member cannot be accessed in C++ due to a combination of multiple inheritance and base classes with members having the same name. The member will thus not be translated to SDL.

WARNING 3209 Cannot translate function pointer type. It will be represented by ptr_void.

This warning is given when a function pointer type is encountered in the input. The support for function pointers is limited (see "Function Pointers" ), and they will be represented as untyped pointers in SDL (i.e. ptr_void).

WARNING 3210 Cannot translate typedef of function type. The declaration will be ignored.

A typedef declaration where the source type is a function type cannot be translated to SDL, since there is no translation rule for function types.

WARNING 3211 Cannot translate template declaration. The declaration will be ignored.

A template declaration cannot be translated to SDL. Only instantiations of a template declaration can be translated. Note that this warning is given also when a template instantiation has been specified in an import specification (see "Template Instantiations" ). In that case the warning could be ignored.

WARNING 3212 Cannot fully translate ellipsis function. Unspecified function arguments will be ignored.

A function with unspecified arguments (a.k.a. an ellipsis function) cannot be fully translated to SDL, since no information has been provided about the unspecified arguments. The function will be translated, but without taking the unspecified arguments into consideration. See "Prototypes for Ellipsis Functions" to learn how to use an import specification to provide CPP2SDL with actual arguments for unspecified formal arguments of ellipsis functions.

WARNING 3213 The typedef name <name> conflicts with the name of another non-compatible type. The declaration will be ignored.

A typedef declaration cannot be translated to SDL, since the typedef name is the same as another type that is not type compatible with the type defined by the typedef itself. This warning may be given for typedefs of pointers or arrays of tagged types. For example:

typedef struct T {
int i;
} *T;

This declaration, which is illegal in C++ but legal in C, contains two types called T that are type incompatible. CPP2SDL will make the type struct T available in SDL (called T there), while the type T will not be translated.

It is recommended to change the name of either the typedef name or the type tag to enable CPP2SDL to translate both types, and thus avoid getting this warning.

WARNING 3290 The identifier <identifier name> does not refer to a declared object. It will be ignored.

This warning is given if CPP2SDL finds an identifier in an import specification that does not exist in the input program. The identifier will be ignored.

WARNING 3291 Cannot translate the identifier <identifier name>, since it is a class member.

This warning is given if CPP2SDL finds an identifier in an import specification that refers to a class member in the input program. The identifier will not be translated, since only declarations in namespaces may be translated (see "Import Specifications" ).


16 CPP2SDL Migration Guide

This chapter is a practical guide on how to convert an SDL specification that uses the H2SDL tool, which is not supported any longer, into an equivalent specification that uses the new CPP2SDL tool.

A complete description of the CPP2SDL tool can be found in "The CPP2SDL Tool" .


Introduction

The purpose of this chapter is to help H2SDL users to smoothly migrate from the obsolete H2SDL tool to CPP2SDL. In addition, Telelogic Customer Support will be happy to assist in solving any migration problems not covered by this chapter.

The H2SDL tool provided automated support for accessing C code from within the Telelogic Tau SDL Suite. The CPP2SDL tool works according to the same fundamental principle, i.e. by automatically translating C/C++ declarations into SDL representations.

However, due to the difference between the C and C++ languages, CPP2SDL is not entirely backward compatible with H2SDL. This means that existing SDL systems that use H2SDL, may need to be updated when upgrading to CPP2SDL.


Reasons to Migrate

Apart from H2SDL being obsolete, there are several reasons to migrate from H2SDL to CPP2SDL:

  • CPP2SDL has superior language support. Not only does it support C++, but it also covers a larger set of the C language.
  • CPP2SDL allows the user to configure the translation from C/C++ to SDL by means of import specifications. This is a technique which often cuts the build time significantly, when large APIs are interfaced from SDL.
  • With H2SDL, the user often has to edit input header files, to make them suitable for translation. This need is significantly reduced with CPP2SDL, since the import specification mechanism lets the user configure the translation of each C/C++ declaration individually.
  • Translation rules implemented by CPP2SDL are considerably improved, compared to the ones implemented by H2SDL. These improvements are due to the implementation of language extensions oriented towards SDL2000.
  • CPP2SDL has an improved reference generator, allowing more precise analysis.
  • The SDL package generated by H2SDL may only be used at system level, while the SDL declarations generated by CPP2SDL may be injected at any level in the SDL hierarchy. This is possible by means of a new SDL-PR symbol in the SDL Editor.
  • CPP2SDL supports a wider range of preprocessors and compilers to be used for preprocessing input header files.
  • CPP2SDL is built with state-of-the-art compiler technology on top of a commercial C/C++ parser. This provides for rapid incorporation of future extensions to C/C++.


Migration Guidelines

This section describes the procedure of upgrading an SDL system from H2SDL to CPP2SDL usage. Required changes are grouped into subsections corresponding to the main reasons for the changes.

Note:

The CPP2SDL tool takes advantage of SDL2000 being case-sensitive, therefore you should make sure that your SDL system is possible to analyze in case-sensitive mode prior to starting the migration work.
The Telelogic Tau SDL Suite includes a tool that helps you convert your SDL system into a case-sensitive SDL system (see Update to case-sensitive SDL.

Update to case-sensitive SDL

The following steps will help you convert your SDL system into case-sensitive mode.

  1. Make sure you use the standard Text Editor for editing text files in the SDL Suite.
  2. Files should be write enabled. If not, the files will be updated but stored with the extension .keep.
  3. Check the correctness of the system with the batch commands described in "Checking diagrams for duplicated object IDs" .
    You should now be ready to convert to case-sensitive mode. Start with creating an extended cross reference file and a file with references to all keywords in the system.
  4. Issue the following command:
sdtbatch[.bat] -a systemPath/systemname.sdt -options optionFile.txt
The file optionFile.txt should include the following lines of options to the Analyzer:
[ANALYSEROPTIONS]
SDLKeywordFile=True
SetPredefinedXRef=True
XRef=True
CaseSensitiveSDL=False
Two files will be created in the target directory of the system. They are called casesensitive.xrf and casesensitive.key and should be used in the next step.
  5. Now you can start the update of the system by invoking the following command.
sdtbatch[.bat] -changecase targetDir/casesensitive.xrf
The result of the operation is sent to sdtout and contains information about what have been done, problems that have arisen and finally which files that was updated and saved. Since it is a lot of information you should probably pipe the output to a file.
When the case is updated we recommend that you analyze the system again. Proceed as follow:
  6. Change the last row in the optionFile.txt from above. The last row should now be:
CaseSensitiveSDL=True
  7. If your system uses the ctypes package and H2SDL you will need to use a special ctypes package that makes it possible to analyze in case-sensitive mode. Open the system in the Organizer and connect ctypes package to the file <installation directory>/sdt/include/ADT/ctypes_migration.sun.
  8. Analyze the system by issuing the following command:
sdtbatch[.bat] -a systemPath/systemname.sdt -options optionFile.txt
There are known restrictions that may make it necessary to manually make further changes of the case in some places in the system. Known problems are:
  • Text in class symbols are ignored.
  • Words spanning two symbols using the possibility to divide a word with `_' are not updated.
  • When generating SDL PR files from SDL GR files some words are trimmed for spaces. Those may not be handled correctly.

We recommend that you update the system further until you have no known errors in the system when running in case-sensitive mode before continuing the process to migrate to CPP2SDL.

Changed Tool Integration

CPP2SDL is integrated with the Organizer and the SDL Editor in a slightly different way than H2SDL is. Instead of placing the header files one by one at root level in the Organizer view, it is now possible to define a set of header files which will be translated by CPP2SDL as a group. Each such set is organized by an import specification which controls what declarations should be translated and how they should be translated. The SDL/PR file that results from the processing of an import specification is represented by means of a PR symbol in the SDL Editor.

  1. Remove all header files from the root level in the Organizer view. Also remove the symbol for the ctypes package.
  2. In the extended heading of the SDL system diagram, remove the use clauses of the packages, which were generated by H2SDL for the header files. Also remove the use clause of the ctypes package.

Note:

The ctypes package must not be used with CPP2SDL as it is designed exclusively for H2SDL. A set of SDL/PR files plays the same role as the ctypes package and will be included by selecting an option in an import specification as described in step 5.

Now all dependencies on H2SDL have been removed, and the specification may be set up for using CPP2SDL instead.

  3. Add an import specification at system level in the Organizer view. Do this by placing a PR symbol in the SDL system diagram. Then double-click the PR symbol, and select it to be a C import specification in the dialog that appears.
  4. Add the removed header files to the import specification, by selecting the import specification and using the Add Existing command in the Organizer. The symbols for the added header files will appear below the import specification symbol in the Organizer.
  5. Go to the CPP2SDL Options dialog for the import specification and set the option1 to generate SDL representations for fundamental types.

When the above steps have been performed, the SDL specification should be equivalent to the original specification from a tool integration point-of-view. However, while doing these changes there are a few optimizations that are enabled by CPP2SDL which should be considered. We will look at these later in "Configuring CPP2SDL Translation" .

Differences in Translation Rules

Although the translation rules implemented by CPP2SDL in many ways are similar to the ones implemented by H2SDL, they are not identical. Therefore, it may be necessary to do some modifications in the SDL specification.

The following sections follow the presentation in 15 The CPP2SDL Tool.

Names

The names of generated SDL identifiers may differ in prefixes and suffixes. All references to such identifiers from the SDL specification should be updated, if needed.

  1. Remove suffixes generated by H2SDL to handle case-sensitivity. These suffixes have the format "_i", where i is a natural number.
  2. Remove prefixes generated by H2SDL to handle combinations of underscores that previously were not supported. These prefixes have the format "zz_UScr_ij_", where i and j are natural numbers. Also change the name of these identifiers to be the same as the corresponding C identifiers.
  3. Change prefixes generated by H2SDL to handle SDL keywords. These prefixes have the format "zz_CCod_" and should be replaced with "keyword_".

Hint:

An alternative to changing all keyword prefixes manually, is to set the keyword prefix to be "zz_CCod_" in the CPP2SDL Options dialog.

Fundamental Types

The ctypes package used by H2SDL, is replaced by one of two sets of SDL/PR files, depending on the used input language; BasicCTypes and CPointer, or BasicC++Types and C++Pointer. They are included automatically in the SDL generated by CPP2SDL if the Generate SDL representations for fundamental types is set. Refer to "Fundamental Types" for more information.

The table below describes the differences between the H2SDL ctypes package and the corresponding CPP2SDL SDL/PR files. The most obvious difference is that the SDL names of the sorts that represent fundamental C/C++ types are more consistent and intuitive when CPP2SDL is used.

Also note that the CharStar and VoidStarStar sorts of ctypes (representing char* and void** in C/C++) are not predefined in the CPP2SDL included SDL/PR files. See "Predefined Pointer Types" and "Predefined Operators" .

C/C++ Fundamental Type | SDL Sort when using H2SDL | SDL Sort when using CPP2SDL
signed int int | Integer | int
unsigned int unsigned | UnsignedInt | unsigned_int
signed long int signed long long int long | LongInt | long_int
unsigned long int unsigned long | UnsignedLongInt | unsigned_long_int
signed short int signed short short int short | ShortInt | short_int
unsigned short int unsigned short | UnsignedShortInt | unsigned_short_int
signed long long int signed long long long long int long long | LongLongInt | long_long_int
unsigned long long int unsigned long long | UnsignedLongLongInt | unsigned_long_long_int
char | Character | char
signed char | Character | signed_char
unsigned char | Octet | unsigned_char
char * | CharStar | N/A
float | Float | float
double long double | Real | double
bool | N/A | bool
wchar_t | N/A | wchar_t
void * | VoidStar | ptr_void
void ** | VoidStarStar | N/A

  4. Update all references to sorts corresponding to fundamental types, with the names of the corresponding SDL sorts generated by CPP2SDL.

Hint:

An alternative to changing all these references manually is to define a set of syntypes mapping the old names to the new ones.

Type Declarators

The names of SDL sorts representing pointer and array types have been changed to be more intuitive and shorter when CPP2SDL is used.

  5. Update all references to sorts corresponding to pointer types by changing the old pointer prefix "Ref_filename_" to "ptr_".
  6. Update all references to sorts corresponding to array types by changing the old array prefix "CA_filename_i_X_" to "arr_i_", where i is the number of elements in the array.

As the H2SDL array prefix "CA_filename_i_X_" would result in very long SDL sort names when translating multi-dimensional arrays, H2SDL generates syntypes to shorten the sort names. These syntypes are named "MA_filename_j", where j is a natural number. Example 139 gives an example of this technique and the corresponding CPP2SDL translation.

Example 139 : H2SDL translation of multi-dimensional array compared to CPP2SDL translation

C header:

int func(int[2][3][4]);

H2SDL translation:

newtype CA_filename_4_X_Integer /*#SYNT*/
CArray(4,Integer);
endnewtype CA_filename_4_X_Integer;

newtype CA_filename_3_X_CA_filename_4_X_Integer /*#SYNT*/
CArray(3,CA_filename_4_X_Integer);
endnewtype CA_filename_3_X_CA_filename_4_X_Integer;

syntype MA_filename_0 /*#SYNT*/ =
CA_filename_3_X_CA_filename_4_X_Integer
endsyntype;

newtype CA_filename_2_X_MA_filename_0 /*#SYNT*/
CArray(2,MA_filename_0);
endnewtype CA_filename_2_X_MA_filename_0;

procedure func;
fpar
fpar_0 CA_filename_2_X_MA_filename_0;
returns Integer;
external;

CPP2SDL translation:

NEWTYPE global_namespace /*#NOTYPE*/
OPERATORS
func : arr_2_arr_3_arr_4_int -> int;
/*#ADT(A(S) E(S) K(H))*/
ENDNEWTYPE global_namespace;EXTERNAL 'C++';
NEWTYPE arr_4_int CArray( 4, int);
/*#ADT(A(S) E(S) K(H))*/
ENDNEWTYPE arr_4_int;EXTERNAL 'C++';
NEWTYPE arr_3_arr_4_int CArray( 3, arr_4_int);
/*#ADT(A(S) E(S) K(H))*/
ENDNEWTYPE arr_3_arr_4_int;EXTERNAL 'C++';
NEWTYPE arr_2_arr_3_arr_4_int CArray( 2, arr_3_arr_4_int);
/*#ADT(A(S) E(S) K(H))*/
ENDNEWTYPE arr_2_arr_3_arr_4_int;EXTERNAL 'C++';

  7. If syntypes for multi-dimensional arrays are present ("MA_filename_j"), replace them with one "arr_i_" prefix for each array dimension.

Predefined Pointer Types

The H2SDL ctypes package includes the definition of the SDL sorts CharStar and VoidStarStar corresponding to the C/C++ pointer types char* and void**. These predefined sorts are not supported by CPP2SDL. Instead CPP2SDL will translate these pointer types using the Ref generator as they are needed.

  8. Update all references to the obsolete sort CharStar to the translated sort ptr_char.
  9. Update all references to the obsolete sort VoidStarStar to the translated sort ptr_ptr_void.

Predefined Operators

The ctypes package also defines a number of obsolete conversion operators for the Ref generator and the CharStar and VoidStarStar sorts, these are replaced with the cast operator according to the table below.

H2SDL operator | CPP2SDL operator | Comment
ref2vstar | cast |
vstar2ref | cast |
ref2vstarstar | N/A | Use cast(cast( )) instead, i.e <type>* to void* to void**
cstar2cstring | cast | Defined in CharConvert.pr
cstring2cstar | cast | Defined in CharConvert.pr
cstar2vstar | cast |
vstar2cstar | cast |
cstar2vstarstar | N/A | Use cast(cast( )) instead, i.e <type>* to void* to void**
vstarstar2vstar | cast |
vstar2vstarstar | cast |

  10. If the cstar2cstring or cstring2cstar operators are used, add a PR symbol and connect it to the file <installation directory>/include/ADT/CharConvert.pr.
  11. Replace all occurrences of the obsolete conversions operators with the cast operator according to the table above.

Enumerated Types

H2SDL has two alternative translations of enum declarations; using integer synonyms or using newtype literals. CPP2SDL only supports the latter of these alternatives.

If H2SDL was configured to translate enum literals to integer synonyms instead of newtype literals, and such a generated SDL synonym is used as an arithmetic expression, then the EnumToInt operator generated by CPP2SDL should be invoked on the newtype literal that corresponds to that synonym. See "Enumerated Types" for more information.

Another difference in the translation of enumerated types is that H2SDL adds an Enum_ prefix to the generated newtype, while CPP2SDL uses the name as it is.

  12. Remove all Enum_ prefixes from identifiers in references to newtypes representing enumerated types.

Functions

While H2SDL translates function prototypes to SDL procedures, CPP2SDL translates them to operators.

  13. Convert all calls to procedures that represent C functions into operator calls by removing the call keyword.
  14. If the Procedure call symbol is used to call procedures representing C functions, replace the Procedure call symbol with a Task symbol.

Note:

A procedure without parameters is called differently than an operator without parameters:
/* Calling a procedure p without parameters. */
task call p();
/* Calling an operator o without parameters. */
task o;

Variables

H2SDL does not translate C variables directly, but generates two procedures for getting and setting the value of the variable. CPP2SDL, on the other hand, generates external SDL variables, which is a tool-specific SDL extension.

  15. For each accessed variable v, replace all procedure calls to Set_v(value) with the assignment v := value. Replace procedure calls to Get_v() with the variable name v.

Note:

CPP2SDL will only translate variables when the Import Specification is placed in a SDL diagram that allows declaration of variables.

Structs and Unions

With CPP2SDL, the names of newtypes generated from structs and unions are retained, while H2SDL adds a Struct_ or a Union_ prefix to these names.

  16. Remove all Struct_ and Union_ prefixes from identifiers in references to newtypes representing structs or unions.

Dynamic Memory Management

The definition of the Ref generator that was used with H2SDL only contained an operator (Make!) or literal (Alloc) for instance allocation, while instance deallocation was made with a Free procedure, defined outside the generator. With CPP2SDL, the Free procedure has been replaced with a free operator in the Ref generator.

  17. Convert all calls to the Free procedure into calls to the free operator by removing the call keyword and changing Free to free.

Configuring CPP2SDL Translation

While H2SDL performs a full translation of all supported C constructs to the system scope of the SDL specification, the Import Specification makes it possible to define what CPP2SDL translates and where to import it.

Additionally, it is also possible to use multiple Import Specifications to import C declarations to different scopes in the SDL specification.

Note:

The SDL language does not contain any construct like the C #ifdef construct, so take care not to import any declarations more than once if you are planning to use multiple Import Specifications.

Where to place the Import Specifications

For example, instead of always placing an import specification at system level, it should be placed at the most narrow scope that encloses all SDL usages of the declarations in the header files that are present under that import specification.

CPP2SDL Options

H2SDL used a centralized setting controlling which preprocessor and what preprocessor options to use for preprocessing input headers. CPP2SDL is more flexible, and makes it possible to specify these settings for each import specification.

  1. Open the CPP2SDL Options dialog for each import specification, and enter the preprocessor and preprocessor options to use for preprocessing the headers grouped by that import specification.

Also note that H2SDL defines the macro __H2SDL__ while preprocessing the C header files. When using CPP2SDL this macro is replaced by the __CPP2SDL__ macro.

  2. If the __H2SDL__ macro is used in your C headers change this to __CPP2SDL__.

Hint:

An alternative to changing the __H2SDL__ macro is to use the preprocessor options in the CPP2SDL Options dialog to define the __H2SDL__ macro.

For more information on the options available in the CPP2SDL Options dialog please refer to "Setting CPP2SDL Options in the Organizer" .

What to Translate

The TRANSLATE section of the Import Specification controls which C identifier that should be translated, by default CPP2SDL will also translate any declarations that these identifiers are depending on.

With the TRANSLATE section it is also possible to add type declarators to types and supply prototypes for ellipsis functions making these available in SDL.

Read more about the TRANSLATE section in "Import Specifications" .

New Build Options

Contrary to H2SDL, CPP2SDL requires the generated SDL to be analyzed as case sensitive SDL.

  3. In the Analyzer Options dialog, set the Case sensitive SDL option.

It should now be possible to analyze the SDL specification.

When the SDL specification has been accepted by the Analyzer, it should also be possible to generate code without further modification. Note, however, that using the Targeting Expert is the recommended way of generating code when CPP2SDL is used. This means that if a makefile or makefile template was used with H2SDL to link the external object files to the generated application, this could now be achieved in an easier way using the Targeting Expert. For more information, see "Generated Makefile" .

1

This option plays the same role as the ctypes package did for H2SDL. When it is set, the generated SDL will include suitable SDL/PR files with SDL representations of fundamental C/C++ types and type declarators (e.g. int, char, pointers and arrays). If set at more than one specification, errors will occur. Therefore, set this option at the broadest scope in which it will be used.


17 CIF Converter Tools

This chapter is a reference manual for the CIF2SDT and SDT2CIF converter tools. The CIF2SDT tool converts CIF (the Common Interchange Format as defined in the Z.106 recommendation) files to binary format files, while SDT2CIF tool converts binary files or system files to CIF files.

CIF is a human readable text format for storing SDL diagrams, making it possible to store SDL diagrams in version control systems that only accept text files. In addition, it provides a base for converting diagrams to and from other SDL toolsets. The CIF2SDT and SDT2CIF tools bring the advantage of CIF to the SDL suite tools.


Introduction

Common Interchange Format

CIF (Common Interchange Format) is a text format specified by -
ITU-T (International Telecommunication Union) in the recommendation Z.106 to ease the interchange of graphical SDL specifications. SDL-CIF is an extension to SDL/PR and is based on the SDL/PR syntax and can be read and written by tools as well as users. The CIF constructs are expressed as comments preceding the PR code. The advantages of such a text format are:

  • SDL diagrams may be stored in version control systems that only accept text files.
  • The format is human readable.
  • It makes it possible to convert diagrams, including their layout, to and from other SDL toolsets that support CIF.
  • It also makes it possible to revert to previous versions of the SDL suite, by using CIF as an intermediate format and re-opening the CIF files in an older version of the SDL suite to become SDL-GR.

However, CIF cannot be used as a storage format for files in the SDL suite as it is required that specification stored in CIF file must be complete and correct.

CIF <-> SDT Converters

The CIF2SDT and SDT2CIF converters make the advantages of the CIF format available to the SDL suite tools. The converters are implemented as a binary that can be run in a textual, command-line mode from the OS prompt, or as separate applications with graphical user interfaces (in Windows). The converter tools can also be launched from the Organizer using the menu choices Convert GR to CIF and Convert CIF to GR from the Generate menu.

The conversion between CIF and the binary format is performed as follows:

  • When converting to CIF, the tool SDT2CIF is used. CIF comments will be generated close to the corresponding SDL/PR code.
  • When converting from CIF, the tool CIF2SDT is used. Both CIF comments and SDL/PR code are considered. CIF comments control conversion, while the text for symbols is extracted from the SDL/PR code.

Note:

The CIF2SDT or SDT2CIF tools require the SDL suite environment when running; meaning that there should be enough licenses available to be able to convert to/from CIF.
On UNIX, when running the CIF converters without having started the SDL suite tools, the environment variable $telelogic must be set. This will be set by souring the file telelogic.sou in the Telelogic Tau installation directory.

Generally, one CIF file contains several SDL diagrams. However, the placement of generated diagrams can be specified by the user.


CIF2SDT Converter Tool

The CIF2SDT tool converts CIF files to binary format files. It can convert one or more specified CIF files or all CIF files in a specified directory.

The CIF2SDT converter never overwrites existing data files. If the converter finds that the file it was going to write already exists, it generates a new name for the output file by replacing the two last characters at the end of the file name.

The CIF2SDT converter can be started in the following ways:

  • From the OS command line; see "Command Line Syntax" .
  • As a separate application with a graphical user interface (Windows only); see "Graphical User Interface (Windows only)" .
  • From the Organizer's Generate menu choice Convert CIF to GR.
    • On UNIX, a dialog is then opened; see "Convert CIF to GR Dialog (UNIX only)" .
    • In Windows, the separate application is then started; see "Graphical User Interface (Windows only)" .

Command Line Syntax

The CIF2SDT tool can be invoked from the OS prompt as follows:

cif2sdt [-v[ersion]] [-h] [-r] [-k]
[ -o <output file name> ]
( <CIF file> | <directory> )*

The meaning of the command-line options is given in the following sections.

(Windows only) When started without options or with -r option only, the Graphical User interface will be started, otherwise the application will execute as a command line application. However, to be able to get the output in the command window when run as a command line application you must use the special application conspawn as a wrapper (assuming C:\Telelogic\SDL_TTCN_Suite4.4 is the installation directory)

C:\Telelogic\SDL_TTCN_Suite4.4\bin\wini386\conspawn.exe -b

C:\Telelogic\SDL_TTCN_Suite4.4\bin\wini386\cif2sdt.exe myciffile

When using the converter as a command line application and invoking it within emacs pathnames in input files are lost. Therefore be sure to do a "cd" to the directory where the files are before invoking the converter.

Command Line Options

  • -v or -version (show the version)
    This option displays the version number of the tool.
  • -h (show the command line syntax)
    This option displays a help message about the command line syntax.
  • -r (reuse a started Telelogic Tau session)
    This option allows to reuse and connect to an already started Telelogic Tau session if it exists. The default behavior is to start a new Telelogic Tau session.
  • -k (keep original file name)
    If the CIF file being converted was converted from an SDL diagram, the converter will use the original file name for the output file.

Note:

This option will only work if the CIF file contains the CIF comment OriginalFileName.

  • -o (save the generated files under the name specified)
    When given this option, the SDT2CIF converter will save the generated diagrams in the file named <output file name>.

Examples of Usage

Example 140

cif2sdt myfile.cif

The CIF2SDT tool will convert the diagrams contained in the CIF file myfile.cif to the file myfile.sif (if a file named myfile.sif does not already exist), myfile01.sif (if a file named myfile.sif already exists, but the file myfile01.sif does not), myfile02.sif and so on.

Example 141

cif2sdt -o lift.sbk lift.cif

The CIF2SDT tool will convert the diagrams contained in the CIF file lift.cif to binary format and put it into an SDL block file named lift.sbk (again, if the file named lift.sbk does not already exist - otherwise, the name will be modified and a corresponding message issued).

Example 142

cif2sdt mycifdir

(where mycifdir specifies a directory name)

The CIF2SDT tool will search for CIF files in the directory named mycifdir, convert all CIF files found to binary format files.and put the converted diagrams in the directory mycifdir. For information on how the search for CIF files is done, see "How the Converter Works" .

Example 143

cif2sdt myblock.cbk myprocss.cpr myservce.csv

The CIF2SDT tool will convert the CIF files myblock.cbk, myprocss.cpr and myservce.csv and put the converted diagrams into the binary files myblock.sbk, myprocss.spr and myservce.ssv.

Example 144

cif2sdt mysystem.csy mycifdir

(where mycifdir specifies a directory name)

The CIF2SDT tool will convert the CIF file mysystem.csy and put the converted diagrams into an system file, then it will search the directory mycifdir and convert all CIF files found in this directory.

Convert CIF to GR Dialog (UNIX only)

On UNIX, the CIF2SDT converter can also be started by selecting Convert CIF to GR from the Organizer's Generate menu. This opens the Convert CIF to GR dialog:

Figure 172 : The Convert CIF to GR dialog

The dialog functions as a front-end to the cif2sdt converter described in "Command Line Syntax" . The only functionality not supported by the dialog is the possibility to specify a directory name as input to the conversion.

  • Source CIF file
    This text field specifies the name of the CIF file to be converted (a directory name cannot be specified). To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Keep original file names
    If this option is enabled, the converter will preserve the original file name (i.e. the file from which this CIF file was generated).

Note:

This option will only work if the CIF file contains the CIF comment OriginalFileName.

  • Destination SDL/GR file name
    This text field specifies the name of the file which will contain the converted diagrams. To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Convert
    Clicking this button will initiate the conversion, using the options currently displayed in the dialog. Messages issued by the converter will appear in the Organizer Log window. The possible messages are listed in "Messages from CIF2SDT Converter" .

Graphical User Interface (Windows only)

In Windows, the CIF2SDT converter is either started outside the SDL suite by using the cif2sdt executable in the release, or by selecting Convert CIF to GR from the Organizer's Generate menu. It provides a graphical user interface to control the conversions:

Figure 173 : CIF2SDT Graphical User Interface

To convert a CIF file or all CIF files in a directory, perform the following steps:

  1. Type a CIF file or directory name in the text field under CIF file or directory to convert.
    • To select a file using a standard dialog box, click the folder button which is located to the right of the text field.
  2. Specify the desired options by clicking on check boxes which specify conversion options; look for option explanations in "Converter Options" .
  3. Click the Generate SDT button.

After these steps, the conversion will proceed, possibly printing warning/errors/information messages into the Conversion log text box.

After the conversion has been performed, the CIF2SDT converter can be used again to convert more CIF files or directories.

Converter Options

  • CIF file or directory to convert
    This text field specifies the name of the CIF file or directory to be converted. To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Keep original SDT file names
    If this option is enabled, the converter will preserve the original file name (i.e. the file from which this CIF file was generated).

Note:

This option will only work if the CIF file contains the CIF comment OriginalFileName.

  • Desired SDT file name
    This text field specifies the name of the file which will contain the converted diagrams. To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Conversion log
    This text box contains warning/error/information messages issued by the converter during the last conversion. The possible messages are listed in "Messages from CIF2SDT Converter" .
  • Generate SDT
    Clicking this button will initiate the conversion, using the options currently displayed in the window.
  • Exit
    Clicking this button exits the converter.

How the Converter Works

First of all, the converter analyzes the input and builds a list of files to convert. If one or a set of files was specified, it adds all the files specified to the list of files to convert. If a directory was specified, the converter searches in the specified directory for files with the extensions .cif, .cun, .csy, .cbk, .csu, .cpr, .csv, .cpd, .cmc, .cst, .cbt, .cpt, .cvt, .cop (which are assumed to contain CIF diagrams) and adds the files found to the list of files to convert. The extension for the output file is formed by replacing the first character of the extension of the input file with the character `s'.

When the list of files to convert is ready, the converter tries to convert each file in the list. The file being converted is parsed, analyzed, transformed, and saved. During parsing, CIF comments take precedence over the PR text, which is supposed to contain additional attributes for CIF objects. If the converter finds an error in the PR text, it proceeds by printing a warning message about that fact, using only the information extracted from the CIF comments.

The advantage of the CIF2SDT converter is that it supports incomplete PR text. For example, it can handle empty text of symbols, empty signal lists, and empty gate constraints. However, there is an exception when the PR text is required to be correct: after the "Diagram Start" CIF comment.

If a line is found that does not have the correct breakpoints (to be correct, it should be a point on the symbol border), an auto layout method is used to place the line.

The converter never overwrites any existing files. If the file to be written gets the same name as an existing file, a new name is generated for the output file to avoid overwriting existing files.

Messages from CIF2SDT Converter

The CIF2SDT converter issues an information message when it needs to inform the user about something; for example, when it changes the output file name in order not to overwrite an existing file. It also issues a warning message when some non-fatal error is found; for example, when some symbol on a diagram occurs in a wrong context. It prints an error message when it is not possible to continue the conversion; for example, when the input file is wrong or corrupt.

Message Format

The general format for warning/error messages is the following:

ERROR <error code>: [<line>, <column>:] <error text> <additional information>
WARNING <warning code>: [<line>, <column>:] <warning text> <additional information>

The <error code> specifies the error code which can be used to find the warning/error explanation (see the following sections). The <line> and <column> specify a position in the source CIF file where the error has occurred. The <error text> gives a short explanation of what is wrong. The <additional information> specifies additional information about the error (for example, it can specify the name of an endpoint constraint that could not be bound).

The list of possible warning/error messages follows in the next sections.

List of Error Messages

Error 1: Arguments required (UNIX only)

This error indicates that no command-line arguments were given to the CIF2SDT converter, which thus cannot continue processing. To remedy the situation, specify one or more file/directory name(s) to convert.

Error 2: Illegal option (UNIX only)

This message is issued when an invalid option is found in the command line. To remedy the situation, supply an appropriate option instead of the invalid one.

Error 3: Duplicate option (UNIX only)

This message is issued when a duplicate command-line option is found. The command-line options can be specified only once. To remedy the situation, remove duplicated options from the command line.

Error 4: Missing output file (UNIX only)

This message is issued when the option -o has been specified, but no output file name follows. To remedy the situation, supply an output file name after the -o option.

Error 5: Illegal command line syntax (UNIX only)

This message is issued when the command line is found not to obey the command-line syntax. To remedy the situation, make the command line conform to the command-line syntax.

Error 6: Impossible to connect to SDT PostMaster

This message is issued when the CIF2SDT converter cannot connect to the PostMaster.

In Windows, the CIF2SDT converter requires the PostMaster to be running in order to perform conversion. Start the Organizer and try again.

On UNIX, the most likely cause of this message is that either the path to the SDL suite tools is not in the search path, or the maximum number of licenses is reached. To remedy the situation, ensure that the SDL Editor can be started (i.e. it is in the search path) and that there are enough licenses available.

Error 7: Error creating diagram

This message is issued when the CIF2SDT converter cannot create a diagram in the SDL Editor. This message is most probably caused by a corrupt input CIF file. To remedy the situation, correct the CIF file.

Error 8: Error creating page

This message is issued when the CIF2SDT converter cannot create a page in the SDL Editor. This message is most probably caused by a corrupt input CIF file. To remedy the situation, correct the CIF file.

Error 9: Error creating symbol

This message is issued when the CIF2SDT converter cannot create a symbol in the SDL Editor. This message is most probably caused by a corrupt input CIF file. To remedy the situation, correct the CIF file.

Error 10: Error saving diagram in file

This message is issued when the CIF2SDT converter cannot save the resulting diagram on the output file. This message may be caused by an invalid output path/file name. If this is the case, specify a valid path. This message may also be caused by insufficient disk space available. If this is the case, free some disk space.

Error 11: Size of symbol is not specified

This message is issued when the CIF2SDT converter encounters a symbol without an explicit size specified and without any default size specified in a diagram in the input CIF file. This is illegal according to the Z.106 standard. To remedy the situation, correct the source CIF file.

Error 12: Cannot bind gate reference

This message is issued when the CIF2SDT converter cannot bind a gate reference to a list of connections. This means the input file is corrupt. To remedy the situation, correct the source CIF file.

Error 13: Cannot bind connect for...

This message is issued when the CIF2SDT converter cannot bind a connection statement with a list of channels/signal routes. This means the input file is corrupt or illegal. To remedy the situation, correct the source CIF file.

Error 14: Cannot bind FROM endpoint for...

This message is issued when the CIF2SDT converter cannot bind a FROM endpoint of a channel or signal route to a block or process. This means that the input CIF file is corrupt or illegal. To remedy the situation, correct the CIF file.

Error 15: Cannot bind TO endpoint for...

This message is issued when the CIF2SDT converter cannot bind a TO endpoint of a channel or signal route to a block or process. This means that input CIF file is corrupt or illegal. To remedy the situation, correct the CIF file.

Error 16: Cannot bind endpoint of line

This message is issued when the CIF2SDT converter encounters a flow line statement and cannot find symbols which are supposed to be connected. To remedy the situation, correct the CIF file.

Error 17: Dashed should be used if keyword Adding is used for gate

Error 18: Wrong first endpoint in gate

Error 19: Gate constraint symbol is omitted for gate

These three messages mean that the source CIF file contains contradictory CIF comments and SDL/PR and is thus corrupt. To remedy the situation, correct the CIF file.

Error 20: Wrong page name

This message is issued when the CIF2SDT converter encounters a CIF PageSwitch comment in a source file that references an undefined page in the diagram. To remedy the situation, correct the CIF file.

Error 21: Wrong number of points in pointlist for gate

This message is issued when the CIF2SDT converter encounters a CIF Gate comment with a pointlist consisting of more than two points. This is a violation of the Z.106 standard, the input file is thus corrupt. To remedy the situation, correct the CIF file.

Error 22: Create line can occur only inside block (type) without decomposition

This message means that the source CIF file is corrupt. To remedy the situation, correct the source CIF file.

Error 23: Flowline can occur only inside diagrams with process body

This message means that the source CIF file is corrupt. To remedy the situation, correct the source CIF file.

Error 24: Symbol cannot occur in this context

This message means that the CIF2SDT converter encountered a graphical symbol in a wrong context in the source diagram (for example, a start symbol in a system diagram). To remedy the situation, correct the source CIF file.

Error 25: Syntax error

This message means that the CIF2SDT converter encountered a violation of the CIF syntax in the source CIF file. To remedy the situation, correct the source CIF file.

Error 26: Illegal name of output file

This message means that either no unique name was found for the output file or there was an input/output error during saving of the output file. To remedy the situation, try to convert the diagrams to a file with a different name (on UNIX, see the -o option).

Error 27: Cannot bind connection point text position

This message means that the position of text in a connection statement could not be bound. To remedy the situation, try to move the text of connection symbol in the source diagram, then re-run the converter.

Error 28: Wrong page type(s) on the diagram

This message means that the CIF2SDT converter found a process diagram with several pages of different types, which is a violation of the Z.106 standard. To remedy the situation, correct the CIF file.

Error 29: Analysis of CIF failed

This message means that the CIF2SDT converter failed to analyze the input CIF file. In this case nothing is generated in the output file. To remedy the situation, correct the CIF file.

Error 30: Wrong syntax of extended task

This message means that the CIF2SDT converter found a syntax error in the PR text of an extended task symbol. The incorrect text is printed as the rest of the error message. Either the left or right curly bracket is missing or they appear in the wrong place in the PR text. To remedy the situation, correct the CIF file.

List of Warning Messages

Warning 2: No input files

This warning is issued when the CIF2SDT converter finds out that no valid file or directory names were specified on the command line. To remedy the situation, ensure that the specified path/file names are correct.

Warning 3: Cannot convert file or directory

This warning is issued when the CIF2SDT converter cannot determine if the specified file is a CIF file or a directory. This is most probably caused by an invalid file/path name. To remedy the situation, ensure that the specified path/file names are correct.

Warning 4: SDLE says: ...

This warning is issued when the CIF2SDT converter receives a reply from the SDL Editor with a message explaining the reason of the error. To see the more detailed explanation of the reason for the error, see the text following the colon.

Warning 5: Empty diagram

This warning means that no diagrams are contained in the source CIF file.

Warning 6: Sorry, Select symbol is not supported in SDT SDLE

Since Select symbol is not supported in the SDL Editor, the converter has no option but to ignore it.

Warning 7: ... cannot contain ... text position specification, specification ignored

Warning 7: ... text placement specification is already specified, ignoring extra specification

Warning 8: This is location of previous specification

These warning messages mean that the source CIF file is corrupt. To remedy the situation, correct the CIF file.

Warning 9: Parsing of PR has failed

This means that there is incorrect SDL/PR after some CIF comment in the source CIF file. To remedy the situation, correct the CIF file.

Warning 10: Dashed attribute synthesized

Warning 11: Dashed attribute ignored

Warning 12: Ignoring gate references

These three messages mean that there are errors in source CIF file that have been automatically corrected.

Warning 13: Integer value expected, zero assumed

This message means that some other text was encountered instead of integer number in the source CIF file, thus the value has been assumed to be zero.

Warning 14: PR is not allowed in ...

This message means that the CIF2SDT converter encountered SDL/PR where it is not allowed to be. This also indicates that the source CIF file is corrupt. To remedy the situation, correct the CIF file.

Warning 15: Descriptors are not allowed (in typebased system)

This means that the source CIF file contained a type based system diagram with some symbols in it, which is a violation of the Z.106 standard. These symbols have been ignored.

Warning 16: Bad coordinate for line endpoint. Autolayout is used for this line

This means that a coordinate for a line endpoint has been found but this coordinate does not fall on the perimeter of the symbol that is connected to the line. Autolayout of the line will be used to place the line.


SDT2CIF Converter Tool

The SDT2CIF tool converts binary format files to CIF files. It can convert one or more specified binary format files, SDL system files or all SDL diagram files in a specified directory.

The SDT2CIF converter also supports the mixed platform feature of the SDL suite (for more information on this topic, see "Windows and UNIX File Compatibility" . If the converter finds a [DRIVES] section during the conversion of an SDL system file, it assumes that this system file is used on mixed platforms. This makes the converter change all characters in output file name to lower case (on UNIX) or replace the part of the path by the drive letter (in Windows).

The SDT2CIF converter never overwrites existing data files. If the converter finds that the file it was going to write already exists, it generates a new name for the output file by replacing the two last characters at the end of the file name.

The SDT2CIF converter can be started in the following ways:

  • From the OS command line; see "Command Line Syntax" .
  • As a separate application with a graphical user interface (Windows only); see "Graphical User Interface (Windows only)" .
  • From the Organizer's Generate menu choice Convert GR to CIF.
    • On UNIX, a dialog is then opened; see "Convert GR to CIF Dialog (UNIX only)" .
    • In Windows, the separate application is then started; see "Graphical User Interface (Windows only)" .

Command Line Syntax

On UNIX, the SDT2CIF tool can be invoked from the OS prompt as follows:

sdt2cif [-v[ersion]] [-h] [-r] [-g] [-i] [-s]
[-o <output file name>] ( <binary diagram file> | <system file> | <directory> )*

(Windows only) When started without options or with -r option only, the Graphical User interface will be started, otherwise the application will execute as a command line application. However, to be able to get the output in the command window when run as a command line application you must use the special application conspawn as a wrapper (assuming C:\Telelogic\SDL_TTCN_Suite4.4 is the installation directory)

C:\Telelogic\SDL_TTCN_Suite4.4\bin\wini386\conspawn.exe -b

C:\Telelogic\SDL_TTCN_Suite4.4\bin\wini386\cif2sdt.exe myciffile

When using the converter as a command line application and invoking it within emacs pathnames in input files are lost. Therefore be sure to do a "cd" to the directory where the files are before invoking the converter.

The meaning of the command-line options is given in the following sections.

Command Line Options

  • -v or -version (show the version)
    This option displays the version number of the tool.
  • -h (show the command line syntax)
    This option displays a help message about the command line syntax.
  • -r (reuse a started Telelogic Tau session)
    This option allows to reuse and connect to an already started Telelogic Tau session if it exists. The default behavior is to start a new Telelogic Tau session.
  • -g (include graphical SDT references)
    This option directs the SDT2CIF converter to include graphical SDT references into the generated CIF file. If -g is given, graphical references are stored as SDL/PR comments; otherwise they are omitted.
  • -i (omit CIF comments)
    When using this option, only SDL/PR will be generated by SDT2CIF.
  • -s (single file)
    When using this option, all diagrams will be saved on one single file. The name of the file is the same name as the first CIF file would get after conversion if this option was not used.
  • -o (save the generated files under the name specified)
    When given this option, the SDT2CIF converter will save the generated diagrams in the file named <output file name>.

Examples of Usage

Example 145

sdt2cif mysystem.sdt

where mysystem.sdt has the following diagrams:

myblock.sbk
myprocss.spr
myservce.ssv
myproced.spd

The SDT2CIF tool will convert all the diagrams referred to in the system file and save them in the CIF format under transformed names:

myblock.sbk -> myblock.cbk
myprocss.spr -> myprocss.cpr
myservce.ssv -> myservce.csv
myproced.spd -> myproced.cpd

Example 146

sdt2cif mysdtdir

(where mysdtdir specifies a directory name)

The SDT2CIF tool will look in the directory mysdtdir and convert all binary files (but not system files - this would cause double conversion) to the corresponding CIF files.

Example 147

sdt2cif myblock.sbk myprocss.spr myservce.ssv

The SDT2CIF tool will convert the three binary files to the CIF files myblock.cbk, myprocss.cpr and myservce.csv.

Example 148

sdt2cif -o blocks.cif block_a.sbk block_b.sbk block_c.sbk

The SDT2CIF tool will convert the three binary files block_a.sbk, block_b.sbk, block_c.sbk and put all diagrams converted into the file blocks.cif.

Example 149

sdt2cif -s block_a.sbk block_b.sbk block_c.sbk

The SDT2CIF tool will convert the three binary files block_a.sbk, block_b.sbk, block_c.sbk and put all diagrams converted into the file named blocks_a.cbk (resulting from the name under which the first file in the list of files to convert would be saved if the -s switch was not specified).

Convert GR to CIF Dialog (UNIX only)

On UNIX, the SDT2CIF converter can also be started by selecting Convert GR to CIF from the Organizer's Generate menu. This opens the Convert GR to CIF dialog:

Figure 174 : The Convert GR to CIF dialog

The dialog functions as a front-end to the sdt2cif converter described in "Command Line Syntax" . The only functionality not supported by the dialog is the possibility to specify a directory name as input to the conversion.

  • Source SDL/GR file or system file
    This text field specifies the name of the SDL/GR file or system file to be converted (a directory name can not be specified). To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Generate one CIF file
    If this option is enabled, the converter will save all converted diagrams into one file. The name of this file is determined from the Destination CIF file name check box state. If the check box is not selected, the name of the file will be the same as the name the first file being converted would get. This option is disabled by default. If the check box is selected, the name of the file with diagrams will be the name specified in the Destination CIF file name text field.
  • Include graphical SDL/GR references
    This option directs the SDT2CIF converter to include graphical SDT references in the generated CIF files (see 19 SDT References for more information on this topic). If this option is enabled, graphical SDT references are stored as SDL/PR comments; otherwise they are omitted. This option is disabled by default.
  • Include CIF comments
    If this option is disabled, only SDL/PR will be generated to output file; otherwise CIF comments will be included. This option is enabled by default.
  • Destination CIF file name
    This text field specifies the name of the file that will contain the converted diagrams. To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Convert
    Clicking this button will initiate the conversion, using the options currently displayed in the dialog. Messages issued by the converter will appear in the Organizer Log window. The possible messages are listed in "Messages from SDT2CIF Converter" .

Graphical User Interface (Windows only)

In Windows, the SDT2CIF converter is either started outside the SDL suite by using the sdt2cif executable in the release, or by selecting Convert GR to CIF from the Organizer's Generate menu. It provides a Graphical User Interface to control the conversions:

Figure 175 : SDT2CIF Graphical User Interface

To convert a single binary file, system file or all binary files in a directory, perform the following steps:

  1. Type an file or directory name in the text field under file or directory to convert.
    • To select a file using a standard dialog box, click the folder button which is located to the right of the text field.
  2. Specify the desired options by clicking on check boxes which specify conversion options; look for option explanations in the following subsections.
  3. Click the Generate CIF button.

After these steps, the conversion will proceed, possibly printing warning/errors/information messages into the Conversion log text box.

After the conversion has been performed, the SDT2CIF converter can be used again to convert more files or directories.

Converter Options

  • file or directory to convert
    This text field specifies the name of the file or directory to be converted. To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Generate one CIF file
    If this option is enabled, the converter will save all converted diagrams into one file. The name of this file is determined from the Desired CIF file name check box state. If the check box is not selected, the name of the file will be the same as the name the first file being converted would get. This option is disabled by default. If the check box is selected, the name of the file with diagrams will be the name specified in the Desired CIF file name text field.
  • Include graphical SDT references
    This option directs the SDT2CIF converter to include graphical SDT references in the generated CIF files (see 19 SDT References for more information on this topic). If this option is enabled, graphical SDT references are stored as SDL/PR comments; otherwise they are omitted. This option is disabled by default.
  • Include CIF comments
    If this option is disabled, only SDL/PR will be generated to output file; otherwise CIF comments will be included. This option is enabled by default.
  • Desired CIF file name
    This text field specifies the name of the file that will contain the converted diagrams. To select a file using a standard file selection dialog box, press the folder button located to the right of the text field.
  • Conversion log
    This text box contains warning/error/information messages issued by the converter during the last conversion. The possible messages are listed in "Messages from SDT2CIF Converter" .
  • Generate CIF
    Clicking this button will initiate the conversion, using the options currently displayed in the dialog.
  • Exit
    Clicking this button will exit the converter.

Messages from SDT2CIF Converter

The SDT2CIF converter issues an information message when it needs to inform the user about something; for example, when it changes the output file name so as not to overwrite an existing file. It also issues a warning message when some non-fatal error is found; for example, when some symbol on a diagram occurs in a wrong context. It prints an error message when it is not possible to continue the conversion; for example, when the input file is wrong or corrupt.

Message Format

The general format for warning/error messages is the following:

ERROR <error code>: <error text> <additional information>
WARNING <warning code>: <warning text> <additional information>

The <error code> specifies the error code which can be used to find the warning/error explanation (see the following sections). The <error text> gives a short explanation of what is wrong. The <additional information> specifies additional information about the error (for example, it can specify the name of an endpoint constraint that could not be bound).

The list of possible warning/error messages follows in the next sections.

List of Error Messages

Error 1: Arguments required (UNIX only)

This error indicates that no command-line arguments were given to the SDT2CIF converter, which thus cannot continue processing. To remedy the situation, supply one or more file/directory name(s) to convert.

Error 2: Illegal option (UNIX only)

This message is issued when an invalid option is found in the command line. To remedy the situation, supply an appropriate option instead of the invalid one.

Error 3: Duplicate option (UNIX only)

This message is issued when a duplicate command-line option is found. The command line options can be specified only once. To remedy the situation, remove duplicated options from the command line.

Error 4: Missing output file (UNIX only)

This message is issued when the option -o has been specified, but no output file name follows. To remedy the situation, supply an output file name after the -o option.

Error 5: Illegal command line syntax (UNIX only)

This message is issued when the command line is found not to obey the command-line syntax. To remedy the situation, make the command line conform to the command-line syntax.

Error 6: Impossible to connect to SDT PostMaster

This message is issued when the SDT2CIF converter cannot connect to the PostMaster.

In Windows, the SDT2CIF converter requires the PostMaster to be running in order to perform conversion. Start the Organizer and try again.

On UNIX, the most likely cause of this message is that either the path to the SDL suite tools is not in the search path, or the maximum number of licenses is reached. To remedy the situation, ensure that the SDL Editor can be started (i.e. it is in the search path) and that there are enough licenses available.

Error 7: SDLE cannot convert the file

This message means that either the file is corrupt or the SDL Editor cannot read the source file or write to output file. To remedy the situation, ensure that the source file is valid and that there is enough disk space. Try to Restart the SDL suite and re-run the converter.

List of Warning Messages

Warning 1: No input files (UNIX only)

This message means that the SDT2CIF converter did not find any suitable file for conversion among those specified on the command line. To remedy the situation, ensure the specified file/path names are correct.

Warning 2: Cannot convert file or directory

This message is most probably caused by a path/file name misspelling. To remedy the situation, ensure that the specified file/path names are correct.

Warning 3: SDLE says: ...

This warning is issued when the SDT2CIF converter receives reply from the SDL Editor with message explaining the reason of the error. To see the more detailed explanation of the reason for the error, see the text following the colon.


18 The Information Server

This chapter is a reference to the error messages that are issued by the Information Server.


General

The Information Server is an application that serves the SDL suite tools as a response to the following requests:

  • Type Viewer request to list SDL diagram types along with their relationships and their instantiations. See 46 The SDL Type Viewer for more information.
  • SDL Editor request to list SDL signals according to the options selected in the Signal Dictionary options. See "Specifying the Signal Dictionary Options" .

The Information Server has no user interface and its operation is managed under the supervision of the SDL suite, beyond user control.


Information Server Error Messages

This section is a reference to the error messages that may be produced by the Information Server.

Some messages contain a `#' followed by a number, which is used to indicate where information, specific to the error situation, will be included.

Some messages include a reference to the object that is the source of the diagnostic. These messages adhere to the format adopted in the SDL suite. See 19 SDT References for a reference to this format and for examples.

ERROR 1000 #1 #2 contains parse error at '#3'

The message contains a reference to an entity that could not be parsed by the Information Server. It is likely that the symbol contains syntactically incorrect information. The error message also contains a reference to the object where the error was detected.

ERROR 1001 #1 #2 is not connected to a file

#1 and #2 refer to the type and name of a diagram that is not connected in the Organizer structure. Use the Organizer command Connect (see "Connect" ) to connect the diagram to a suitable file.

ERROR #1002 Inheritance for #1 #2 is circular

#1 and #2 refer to the type and name of a diagram that contain a circular inheritance. Circular inheritance is not supported by the SDL suite. The error message also contains a reference to the object where the error was detected.

ERROR 1003 Could not create temporary filename, status: #1

The Information Server failed when creating the name of a temporary file. #1 contains more information about what operation failed.

ERROR 1004 Could not create temporary file, status: #1

The Information Server failed when creating a temporary file. #1 provides additional information about the error code.

ERROR 1005 #1 #2 contains yacc stack overflow at '#3'

The message contains a reference to an entity which caused the parser stack to overflow. This message may occur when the parsers processes statements that contain a large amount of lexical elements. Break down the expression. The error message also contains a reference to the object where the error was detected.


19 SDT References

This chapter contains a reference to the syntax used by the SDL suite when referring to entities managed by the SDL suite.

Through these references, the SDL suite environment provides a means to:

  • Obtain a graphical trace back from Analyzer diagnostics to the source SDL diagrams
  • Trace simulations in graphical mode
  • Obtain a trace back from generated MSCs to the source SDL diagrams
  • Navigate between SDL type diagrams, cross-reference diagrams, coverage charts and the source SDL diagrams
  • Navigate between the generated PR or C files and the source SDL diagrams.


General

The concept "GR reference", introduced in the SDT 2.X tool family, has been extended in order to support references to virtually all entities that are managed in an SDT 3.X environment (or will be managed in future versions):

  • SDL diagrams
  • SDL pages
  • SDL symbols
  • Text within an SDL symbol
  • SDL Overview diagrams
  • SDL/PR files
  • OM, SC, MSC, HMSC diagrams
  • OM, SC, HMSC pages
  • OM, SC, MSC, HMSC symbols
  • Text within an MSC symbol
  • Text within an OM symbol1
  • Cross-reference files
  • Coverage files
  • C files
  • ASN.1 files
  • Other ASCII text files

The term GR reference has been replaced by the term SDT reference. It is possible to retrieve SDT references from the SDL suite tools using commands such as Show GR Reference in the SDL Editor, and to show the source that matches a reference using commands such as Go To Source in the Organizer.

1

This refers to the text in the name compartment in class definition and class instance symbols. Text in the operation and attributes compartments are not possible to refer to in this version.


Syntax

Below follows the syntax for an SDT reference:

<SDT_Reference> ::=
`#SDTREF' `('
( <SDT_GR_Ref> | <SDT_Textfile_Ref>
| <SDT_MSC_Ref> | <SDT_HMSC_Ref> | <SDT_OM_Ref>
| <SDT_SC_Ref> )
`)'

<SDT_GR_Ref> ::=
`SDL' `,' <FileName>
[ `(' <PageName> `)' ]
[ `,' <ObjectId> [ <Object_Coordinates> ]
[ `,' <LineNumber> [ `,' <Column> ] ] ]

<SDT_Textfile_Ref> ::=
`TEXT' `,' <FileName>
[ `,' <LineNumber> [ `,' <Column> ] ]

<SDT_MSC_Ref> ::=
`MSC' `,' <FileName>
[ `,' <ObjectId>
[ `,' <LineNumber> [ `,' <Column> ] ] ]

<SDT_HMSC_Ref> ::=
`HMSC' `,' <FileName>
[ `(' <PageName> `)' ]
[ `,' <ObjectId> [ <Object_Coordinates> ]
[ `,' <LineNumber> [ `,' <Column> ] ] ]

<SDT_OM_Ref> ::=
`OM' `,' <FileName>
[ `(' <PageName> `)' ]
[ `,' <ObjectId> [ <Object_Coordinates> ]
[ `,' <LineNumber> [ `,' <Column> ] ] ]

<SDT_SC_Ref> ::=
`SC' `,' <FileName>
[ `(' <PageName> `)' ]
[ `,' <ObjectId> [ <Object_Coordinates> ]
[ `,' <LineNumber> [ `,' <Column> ] ] ]

<FileName> ::=
File name

<PageName> ::=
name of a page according to SDT 3.X rules

<ObjectId> ::=
integer, unique id for object

<Object_Coordinates> =
`(` <x-coord> `,' <y-coord> `)'

<x-coord> ::=
x coordinates in mm from upper left corner
<y-coord> ::=
y coordinates in mm from upper left corner

<LineNumber> ::=
line number within symbol or file

<Column> ::=
column within the line


Examples

Below follow some examples of SDT references.

Example 150 : SDL graphical references

Reference
Explanation

 #SDTREF(SDL,test.sbk)
SDL diagram.

 #SDTREF(SDL,test.sbk(P1))
SDL page

 #SDTREF(SDL,test.sbk(P1),10)
SDL symbol

 #SDTREF(SDL,test.sbk,10)
SDL symbol

 #SDTREF(SDL,test.sbk(P1),10(30,130))
SDL symbol

 #SDTREF(SDL,test.sbk(P1),10,5)
Line within symbol

 #SDTREF(SDL,test.sbk(P1),10(30,130),5)
Line within symbol

 #SDTREF(SDL,test.sbk(P1),10,5,15)
Column at line within symbol

Example 151 : MSC graphical references

Reference
Explanation

 #SDTREF(MSC,test.msc)
MSC

 #SDTREF(MSC,test.msc,10)
Symbol in MSC

 #SDTREF(MSC,test.msc,10,5)
Line within symbol

 #SDTREF(MSC,test.msc,10,5,15)
Column at line within symbol

Example 152 : OM graphical references

Reference
Explanation

 #SDTREF(OM,test.som)
OM diagram.

 #SDTREF(OM,test.som(P1))
OM page

 #SDTREF(OM,test.som(P1),10)
OM symbol

 #SDTREF(OM,test.som,10(30,130))
OM symbol

 #SDTREF(OM,test.som,10,5)
Line within symbol

 #SDTREF(OM,test.som(P1),10(30,130),5)
Line within symbol

 #SDTREF(OM,test.som(P1),10,5,15)
Column at line within symbol

Example 153 : Textual references

Reference
Explanation

 #SDTREF(TEXT,test.pr)
Text file

 #SDTREF(TEXT,test.pr,10)
Line in text file

 #SDTREF(TEXT,test.pr,10,15)
Column at line
within file


20 Using OM Access

This chapter describes the OM Access feature.

OM Access is a module that provides the end user with access to the information in a diagram created by the OM Editor through a C++-interface, based on the UML Meta-model.


OM Access

OM Access is a C++ application programmer's interface to the OM Editor. It can be used in applications that uses the information contained in OM diagrams, such as:

  • Code generators
  • Documentation generators
  • Report generators
  • Statistics.

Note:

This chapter is an OM Access primer and is not intended to provide knowledge about C++ programming.

OM Access Files

These files can be found under the
<installation dir>/orca/omaccess/> directory of your installation.

Filename | Description
stlmini.h | Minimal implementation of the standard C++ library, used by omaccess.cc
uml.h | Declarations of UML Meta-structure
omaccess.h | Header-file for omaccess.cc
omaccess.cc | Functions for accessing the data in an OM diagram
pmtool.h | Declarations for low-level communications with the OM Editor
om2cpp.cc | A small demo program that takes a diagram and makes a C++ include file
trace.cc | A small demo program that prints almost everything it gets from OM Access


General Concepts

The OM Access Application

An OM Access application is an application that uses the data in an OM Diagram. This OM Diagram is represented in the program by a data structure similar to UML's metamodel.

The first section introduces the basic methods.

Basic Methods

First of all there are some definitions needed; these can be found in the include file omaccess.h:

#include "omaccess.h"

This file also includes uml.h and stlmini.h. The file uml.h contains declarations for the UML metamodel, and stlmini.h 1 contains a minimal implementation of string and list classes in the standard C++ library used for handling the data.

An instance of the OMModule is needed to hold the information:

OMModule module;

To load the contents of a diagram into the module either GetFile or GetBufID can be used:

bool result = GetFile(module, filename);
bool result = GetBufID(module, bufid);

Returns true on success, false if failed to load the module.

Accessing the Information

The OMModule class keeps the information fetched from the OM Editor in lists. The lists are:

list<Class> classList
list<Generalization> generalizationList
list<AssociationClass> associationlist

Aggregations and associations are stored into the associationList, to simplify handling. To pick out the associations and aggregations separately, use the functions:

GetAggregations(OMModule&, list<AssociationClass>*)
GetAssociations(OMModule&, list<AssociationClass>*)

These functions fill the list in the second parameter with the associations and aggregations in the module.

The lists can be traversed using iterators. The following example shows how to print all the names of the classes in a module:

Example 154

for (list<Class>::iterator ci=omModule.classList.begin();
ci != omModule.classList.end();
++ci) {
const Class &omClass = *ci;
cout << omClass.name << endl;
}

Relations

The links between associations/aggregations/generalizations and classes are represented as the names of classes, stored as strings.

Generalizations

The Generalization class contains the data members subtype and supertype. The names of the super- and subclass are stored as string.

The data member discriminator contains the discriminator, stored as string.

To list the superclasses and subclasses of a class, the following functions can be used:

GetSuperClassList(OMModule&, string&, list<string>*)
GetSubClassList(OMModule&, string&, list<string>*)

They put the names of the superclasses or subclasses belonging to the name of the class in string, into the list.

Aggregations/Associations

The AssociationClass class can contain both aggregations and associations as well as associations with association classes connected to them. The boolean member isAggregation can be used to determine if it is an aggregation or association.

To get a list of the names of the classes connected to the association/aggregation, the function

GetEndPoints(AssociationClass&, list<string>*)

can be used.

Example

Here follows a small example that shows how to access the class information. For each class in the diagram it prints the name of the class and the name of its subclasses.

Example 155 : printclasses.cc

#include <iostream.h>
#include "omaccess.h"

#include "stlmini.h"

int main(int argc, char *argv[]) {
if (argc !=2) {
cout << "Usage : printclasses <filename>" << endl;
return EXIT_FAILURE;
}

OMModule omModule;

// Retrieve the file from the OM Editor
if(! GetFile(argv[1], &omModule) )
return EXIT_FAILURE;

// Iterate over the classes
for (list<Class>::iterator ci=omModule.classList.begin();
ci != omModule.classList.end();
++ci) {
const Class &omClass = *ci;
cout << omClass.name << endl;

// Extract the subclassess
list<string> classlist;
GetSubClassList(omModule,omClass.name,&classlist);
// And iterate through them
for (list<string>::iterator ni=classlist.begin();
ni != classlist.end();
++ni) {
const string &name = *ni;
cout << " Subclass: " << name << endl;
}
}
return EXIT_SUCCESS;
}

1

stlmini.h can be replaced by the appropriate standard C++ headers <list.h> and <string.h> if you have access to an implementation of the standard C++ library.


Files and Compiling

General

To use OM Access a C++ compiler that can handle templates is needed, such as g++ 2.7.2, Borland C++ 5.02, or MSVC 5.

There are some Makefiles together with the examples ($telelogic/orca/omaccess/examples) that might be usable as templates.

OM Access is based on the public interface to Telelogic Tau; see "PostMaster Reference" .

UNIX

The following files should be included into the compilation/linking phase for UNIX is:

$telelogic/orca/omaccess/src/omaccess.cc
$telelogic/orca/omaccess/src/pmtool.cc
$telelogic/lib/<platform>lib/post.o

where $telelogic refers to the installation path, and <platform> can be one of hppa or sunos5.

Two paths to the include files is also necessary:

-I$telelogic/orca/omaccess/include
-I$telelogic/include/post

Example 156 : Compile printclasses.cc with g++ on HP

g++ -o printclasses -I$telelogic/orca/omaccess/include \
-I$telelogic/include/post \
printclasses.cc \
$telelogic/orca/omaccess/src/omaccess.cc \
$telelogic/orca/omaccess/src/pmtool.cc \
$telelogic/lib/hppalib/post.o

If Solaris is used, the switches -lgen -lsocket -lnsl have to be added.

Example 157 : Compile printclasses.cc with g++ on Solaris

g++ -o printclasses -I$telelogic/orca/omaccess/includes \
-I$telelogic/include/post \
printclasses.cc \
$telelogic/orca/omaccess/src/omaccess.cc \
$telelogic/orca/omaccess/src/pmtool.cc \
$telelogic/lib/sunos5lib/post.o -lgen -lsocket -lnsl

The OM Access files could also be copied to a local directory to ease up compilation.

Windows

Note:

During runtime the DLL post.dll (located in a subdirectory to <installation directory>\sdt\sdtdir\wini386\include) must either be in the path or the directory the application is started from.

Borland C++

Add the files omaccess.cc, pmtool.cc (can be found in <installation directory>\orca\src) and post.lib (can be found in <installation directory>\sdt\sdtdir\wini386\include\borland502) to the project.

Add <installation directory>\orca\includes and <installation directory>\include\post to the include path.

Microsoft Visual C++

Add the files omaccess.cc, pmtool.cc (can be found in <installation directory>\orca\src) and post.lib (can be found in <installation directory>\sdt\sdtdir\wini386\include\msvc50) to the project.

Add <installation directory>\orca\includes and <installation directory>\include\post to the include path.


Using OM Access Together with the SDL Suite

Applications written with OM Access can easily be called from within the OM Editor, for example from a menu (for more info about defining your own menus see "Defining Menus in the SDL Suite" .

The following example adds a choice to generate C++ code skeleton of an OM Diagram from the OM Editor and pops up a text editor with the generated file in it.

Example 158 : ome-menus.ini

SDT-DYNAMICMENUS-3.6
[MENU]
Name=&OM Access
[MENUITEM]
ItemName=Generate C++
Separator=off
StatusbarText=Generate C++ code skeleton
ProprietaryKey=1
AttributeKey=0
Scope=Always
ConfirmText=You might want to change the name of the output file
ActionInterpretation=OS_COMMAND
BlockCommand=off
FormattedCommand=om2cpp %b `basename %b .som`.h
[MENUEND]


Reference

The reference contains two parts:

  • Data Model: information about the data model used. For each class, a description is provided and then the members of the class are presented in a table.
  • Functions: information about the functions in OM Access. For each function, the definition is shown followed by a description and a table of the parameters.

Data Model

The data model in OM Access is based on the UML Metamodel. For more information about the UML Metamodel, see the "UML Semantics" chapter of the "Unified Modeling Language, version 1.1" documentation. This document can be found at
http://www.rational.com/uml/documentation.html.

If not mentioned otherwise, the members are of type string.

OMModule

An instance of the OMModule class contains information about an OM Diagram.

Member
Description

 classList
A list of Class, containing all of the classes.

 generalizationList
A list of Generalization, containing all of the generalizations.

 associationList
A list of AssocationClass, containing all of the associations/aggregations.

Class

An instance of the Class class contains information about a class.

Member
Description

 name
The class name as a string.

 attributeList
A list of Attribute, each entry representing one attribute in the class.
 operationList
A list of Operation, each entry representing one attribute in the class.

Operation

An instance of the Operation class contains information about an operation.

Member
Description

 visibility
Visibility of operation.

 name
Name of operation.

 returnType
Return type of operation.

 parameterList
List of Parameter containing information about the operations parameters.

Parameter

An instance of the Parameter class contains information about a parameter.

Member
Description

 name
Name of the parameter.

 type
Type of the parameter.

Attribute

An instance of the Attribute class contains information about an attribute.

Member
Description

 visibility
Visibility of attribute.

 name
Name of attribute.

 type
Type of the attribute.

 value
Default value.

Generalization

An instance of the Generalization class contains information about a generalization.

Member
Description

 subtype
The name of the subtype, `subclass' of the generalization.

 supertype
The name of the supertype, `superclass' of the generalization.

 discriminator
The discriminator of the generalization.

AssociationClass

An instance of the AssociationClass class contains information about an association/aggregation. The connection between the different classes is maintained by fromEnd and toEnd.

Member
Description

 fromEnd
An AssociationEnd representing one of the ends of the association.

 toEnd
An AssociationEnd representing the other end of the association.

 isAggregation
A boolean that is true if the association is an aggregation.

 hasAssociationClass
A boolean that is true if the association also have an AssocationClass.

If the association also has an associationclass, the class-information is contained in the instance, inherited from Class.

AssociationEnd

An instance of the AssociationEnd class contains information about a connection to a class, for example in an association.

Member
Description

 name
Name of this end.

 rolename
Role name of association.

 type
Name of the class connected to.

 multiplicity
Multiplicity of association.

 qualifier
Qualifier of association.

 constraint
Constraint of association.

 aggregation
Represents the type of the association.

 isSorted
True if the association is sorted.

 isOrdered
True if the association is ordered.

Functions

GetFile

bool GetFile(filename, omModule, status)

Description

Loads the contents of filename into omModule.Returns true on success, false if failed to load the module.

Parameters

Parameter
Type
Description

 filename

 string
The (absolute) name of the file containing the diagram.

 omModule

 OMModule *
A pointer to the OMModule where the diagrams data will be put.

 status

 string *
(optional) If loading failed a diagnostic message is inserted into this string.

GetBufID

bool GetBufID(bufID,omModule,status)

Description

Loads the contents of the buffer bufID into omModule. Returns true on success, false if failed to load the module.

Parameters

Parameter
Type
Description

 bufID

 string
The bufferID of the diagram.

 omModule

 OMModule *
A pointer to the OMModule where the diagrams data will be put.

 status

 string *
(optional) If loading failed a diagnostic message is inserted into this string.

GetSuperClassList

GetSuperClassList(omModule,className,superClasses)

Description

Fills the list superClasses with the names of the superclasses to className in omModule.

Parameters

Parameter
Type
Description

 omModule

 OMModule &
The OMModule containing the diagram information.

 className

 string
The name of the class whose superclasses are searched for.

 superClasses

 list<string> *
The list to put the name of the superclasses in.

GetSubClassList

GetSubClassList(omModule,className,superClasses)

Description

Fills the list subClasses with the names of the subclasses to className in omModule.

Parameters

Parameter
Type
Description

 omModule

 OMModule &
The OMModule containing the diagram information.

 className

 string
The name of the class whose subclasses are searched for.

 subClasses

 list<string> *
The list to put the name of the subclasses in.

SourceAggregationEnd

string SourceAggregationEnd(association)

Description

Returns the name of the class which starts the aggregation (the end with the square in it), the owner-part. (The source contains the end.)

Parameters

Parameter
Type
Description

 association

 AssociationClass
The association to check.

TargetAggregationEnd

string TargetAggregationEnd(association)

Description

Returns the name of the class that ends the aggregation (the end without the square in it), the owned-part. (The source contains the end.)

Parameters

Parameter
Type
Description

 association

 AssociationClass
The association to check.

GetEndPoints

void GetEndPoints(association, classes)

Description

Fills the classes list with the names of the classes that this association/aggregation is connected to.

Parameters

Parameter
Type
Description

 association

 AssociationClass
The association to check.

 classes

 list<string> *
The list to insert the names into.

HasEndpoint

bool hasEndPoint(association, name)

Description

Returns true if association has an endpoint at name.

Parameters

Parameter
Type
Description

 association

 AssociationClass
The association to check.

 name

 string
The class to check.

GetAggregations

void GetAggregations(omModule,aggregations)

Description

Fills aggregations with all the aggregations in omModule.

Parameters

Parameter
Type
Description

 omModule

 OMModule
The OMModule containing the diagram information.

 aggregations

 list<Associ
ationClass>
The list to fill with aggregations.

GetAggregations

void GetAggregations(comModule,aggregations,owner)

Description

Fills aggregations with all the aggregations in omModule, that has owner as source.

Parameters

Parameter
Type
Description

 omModule

 OMModule
The OMModule containing the diagram information.

 aggregations

 list<AssociationClass>
The list to fill with aggregations.

 owner

 string
the name of the class that has to be the owner.

GetAssociations

void GetAssociations(omModule, associations)

Description

Fills associations with all the associations in omModule.

Parameters

Parameter
Type
Description

 omModule

 OMModule
The OMModule containing the diagram information.

 associations

 list<AssociationClass>
The list to fill with associations.

GetAssociations

void GetAssociations(omModule, associations,
firstEnd)

Description

Fills associations with all the associations in omModule, that is connected to firstEnd, in some end.

Parameters

Parameter
Type
Description

 omModule

 OMModule
The OMModule containing the diagram information.

 associations

 list<AssociationClass>
The list to fill with associations.

 firstEnd

 string
The name of one of the classes that the association has to be connected to.

GetAssociations

void GetAssociations(omModule,associations,
firstEnd,secondEnd)

Description

Fills associations with all the associations in omModule, that is connected to firstEnd, and secondEnd.

Parameters

Parameter
Type
Description

 omModule

 OMModule
The OMModule containing the diagram information.

 associations

 list<AssociationClass>
The list to fill with aggregations.

 firstEnd

 string
The name of one of the classes that the association has to be connected to.

 secondEnd

 string
The name of the second class that the association has to be connected to.

TraceModule

void TraceModule(omModule,os)

Description

Outputs a textual dump of omModule to os, with as much information as possible, useful for debugging purposes.

Parameters

Parameter
Type
Description

 omModule

 OMModule
The OMModule containing the diagram information.

 os

 ostream
The stream to output the dump to.


21 Basic Compiling Theory

This chapter gives the ground basis for basic compiling theory. It will give an introduction to compiling theory as it is the corner-stone on which TTCN Access is built upon. See 22 TTCN Access.

This chapter is intended to be read by developers of executable test suites, translator developers and test result analyzers.

Note: UNIX only

TTCN Access is only available on UNIX.


Basic Compiling Theory

A programming language can be defined by describing what its programs look like (the syntax of the language) and what its programs mean (the semantics of the language).

For specifying the syntax of a language, such as TTCN, the widely used notation called context-free grammar, or BNF (Backus-Naur Form) is used. (A more precise definition of context-free grammar will be defined in "Syntax Definition" ).

To describe the semantics of a language is more difficult, as no appropriate notation for semantic description is available. Consequently, when specifying the semantics of a language an informal description technique has to be used. TTCN uses Semantic actions that, in natural language, describes the actual semantic given a specific context.

Besides specifying the syntax of a language, a context-free grammar can be used to help guide the translation of a programs. A grammar oriented compiling technique, known as syntax-directed translation, is very helpful for organizing a compiler front end.


The Compiler

Conceptually, a compiler operates in phases, each of which transforms the source program from one representation to another. Often, some of the phases may be grouped together and the intermediate representation between the grouped phases need not be explicitly constructed.

The first three phases of a compiler, forming the bulk of the analysis portion is often called front end. The front end consist of those phases that depend primarily on the source language and are largely independent of the target language. This front end normally includes lexical and syntactic analysis, the creation of the symbol table, semantic analysis and the generation of intermediate code.

The last phases of a compiler, the back end, include those portions of a compiler that depend on the target language. In the back end, one will find code optimization, code generation along with the necessary error handling and symbol-table operation.

This chapter will discuss and explain the concept of the front end thoroughly. The back end will be mentioned just for completeness. The reason for this is quite obvious:

TTCN Access is the front end to a TTCN compiler.


Lexical Analyzer

The lexical analyze is the first phase of a compiler. Its main task is to read input characters and produce as output a sequence of tokens that the parser uses for the next phase, the syntax analysis.

Since the lexical analyzer is the part of a compiler that reads the source text, it may also perform certain secondary tasks at the user interface. One such task is stripping out comments and white space in the form of blank, tab, and newline character. Another is correlating error messages from the compiler with the source program. For example, the lexical analyzer may keep track of the number of newline characters seen, so that a line number can be associated with an error message.

In lexical analysis the stream of characters making up the program is read from left-to-right and grouped into tokens that are sequences of characters having a collective meaning.

Example 159

For example, the characters in the assignment statement below:

position := initial + rate * 60

would be grouped into the following tokens:

  1. The identifier position
  2. The assignment symbol :=
  3. The identifier initial
  4. The plus sign
  5. The identifier rate
  6. The multiplicand sign
  7. The number 60

The blanks separating the characters of these tokens would normally be eliminated during lexical analysis.


Syntax Definition

In this section, a notation called a context-free grammar (grammar for short) is introduced. This notation is used for specifying the syntax of a language.

A grammar naturally describes the hierarchical structure of many programming language constructs. For example, an if-else statement in C has the form as below.

if ( expression ) statement else statement

That is, the statement is the concatenation of the keyword if, an opening parenthesis, an expression, a closing parenthesis, a statement, the keyword else, and another statement. Using the variables expr to denote an expression and the variables stmt, stmt1 and stmt2 to denote three (possible different) statements, this structuring rules can be expressed as

stmt -> if ( expr ) stmt1 else stmt2

in which the arrow may be read as "can have the form". Such a rule is called a production. In a production lexical elements like the keyword if and the parentheses are called tokens. Variables like expr and stmt2 represent sequence of tokens and are called nonterminals.

A context-free grammar has four components:

  • A set of tokens, known as terminal symbols.
  • A set of nonterminals.
  • A set of productions where each production consists of a nonterminal, called the left side of the production, an arrow, and a sequence of tokens and/or nonterminals, called the right side of the production.
  • A destination of one of the nonterminals as the start symbol.

Through this chapter, examples and pictures will be present in order to clarify a topic or explain a specific concept. As TTCN, at this stage, has a too large grammar definition to be included in this document, a language called SMALL is defined that in this chapter will be used for examples and discussions.

SMALL will be defined as a language only consisting of digits and the plus and minus signs, e.g., 9-5+2, 3-1 and 7. In the language SMALL, a plus or minus sign must appear between two digits, and expressions as above will be referred to as "lists of digits separated by plus or minus sign".

The following grammar specifies the syntax of this language with list as its start symbol:

1:list -> list + digit
2:list -> list - digit
3:list -> digit
4:digit -> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

From production (3), a single digit by itself is a list. Productions (1) and (2) express the fact that if one take any list and follow it by a plus or a minus sign and then another digit one has a new list. For example, it is possible to deduce that 9-5+2 is a list as follows:

a) 9 is a list by production (3), since 9 is a digit.
b) 9-5 is a list by production (2), since 9 is a list and 5 is a digit.
c) 9-5+2 is a list by production (1), since 9-5 is a list and 2 is a digit.

This reasoning is illustrated by the tree in the next figure. Each node in the tree is labelled by a grammar symbol. An interior node and its children correspond to a production; the interior node corresponds to the left side of the production, the children to the right side. Such trees are called parse trees and are discussed in the next chapter.

Figure 176 : A parse tree for 9-5+2


Syntax Analyzer

Every programming language has rules that prescribe the syntactic structure of well-formed programs. In Pascal, for example, a program is made out of blocks, a block out of statement, a statement out of expressions, an expression out of tokens, and so on. The syntax of programming language constructs can be described by context-free grammars or BNF notation. Grammars offer significant advantages to both language designers and compiler writes:

  • A grammar gives a precise, yet easy-to-understand, syntactic specification of a programming language.
  • From certain classes of grammars it is possible to automatically construct an efficient parser that determines if a source program is syntactically well formed.
  • A properly designed grammar imparts a structure to a programming language that is useful for translation of source programs into correct object code and for the detection of errors.
  • Languages evolve over a period of time, acquiring new constructs and performing additional task. These new constructs can be added to a language more easily when there is an existing implementation based on a grammatical description of the language.

During syntax analysis the tokens of the source program are grouped into grammatical phrases that are used by a compiler to synthesis the output. Usually, the grammatical phrase of the source program is represented by a parse tree.

Figure 177 : A syntax tree for the assign statement 9-5+2


Parse Trees

A parse tree pictorially shows how the start symbol of a grammar derives a string in the language. If nonterminal A has a production as:

A -> X Y Z

then a parse tree may have an interior node labelled A with three children labelled X, Y and Z, from left to right:

Figure 178 : Parse tree

Formally, given a context-free grammar, a parse tree is a tree with the following properties:

  1. The root is labelled by the start symbol.
  2. Each leaf is labelled by a token or empty.
  3. Each interior node is labelled by a nonterminal.
  4. If A is the nonterminal labelling some interior node, and X1, X2, ..., Xn (where Xi are terminals or nonterminals) are the labels of the children of that node, then
    A -> X1 X2 ..., Xn
    is a production in the grammar.

The leaves of a parse tree read from left to right form the yield of the parse tree, which is the string generated or derived from the nonterminal at the root of the parse tree. Any tree imparts a natural left-to-right order to its leaves, based on the idea that if a and b are two children with the same parent, and a is to the left of b, then all descendants of a are to the left of descendants of b.

Another definition of a language generated by a grammar is as the set of strings that can be generated by some parse tree. The process of finding a parse tree for a given string of tokens is called parsing that string.


Parsing

Parsing is the process of determining if a string of tokens can be generated by a grammar. In discussing this topic, it is helpful to think of a parse tree being constructed, even though a compiler may not actually construct such a tree. However, a parser must be capable of constructing the tree, or else the translation cannot be guaranteed correct.


Intermediate Code

After syntax and semantic analysis, some compilers generate an explicit intermediate representation of the source program. This intermediate representation can be seen as a program for an abstract machine. In the context of the TTCN suite and TTCN Access, the intermediate representation is the actual parse tree generated by the Analyzer. For more information see 27 Analyzing TTCN Documents (on UNIX).


Code Generator

The final phase of a compiler is the generation of target code, that is transforming the intermediate code into something useful such as an executable. As TTCN Access is an application programmers interface towards the intermediate representation, the parse tree, it is the TTCN Access application that will define the actual transformation of the intermediate code. It can be an executable as well as a reporter, interpreter, etc.


The Phases of a Compiler

Conceptually, a compiler operates in phases, each of which transforms the source program from one representation to another. A typical decomposition of a compiler is shown in the next picture. In practice, some of the phases may be grouped together and the intermediate representation between the grouped phases need not be explicitly constructed.

Figure 179 : The phases of a compiler

The first three phases, forming the bulk of the analysis portion of a compiler has previously been discussed. Two other activities, symbol-table management and error handling, are shown interacting with the five phases of lexical analysis, syntax analysis, semantic analysis, intermediate code generation and code generation. Informally, the symbol-table management and the error handler are also called phases.


Symbol Table Management

An essential function of a compiler is to record the identifiers used in the source program and collect information about various attributes of each identifier. These attributes may provide information about the identifier as its type, its scope (where in the source program it is valid) and, in the case of procedure names, such things as the number and type of its arguments, the method for passing each argument (e.g., by reference), and the type returned, if any.

A symbol table is a data structure containing a record for each identifier, with fields for the attributes of the identifier. The data structure allows us to find the record for a specific identifier quickly and to store or retrieve data from that record.

When an identifier in the source program is detected by the lexical analysis, the identifier is entered into the symbol table. However, the attributes of an identifier cannot normally be determined during lexical analysis. The remaining phases enter information about identifiers into the symbol table and then use this information in various ways. For example, when doing semantic analysis, the compiler needs to know what types the identifiers have, so it can be checked that the source program uses them in a valid way.


Error Detection and Reporting

Each phase can encounter errors. However, after detecting an error, a phase must somehow deal with that error, so that compilation can proceed, allowing further errors in the source program to be detected.

The syntax and semantic analysis phase usually handle a large fraction of the errors detectable by the compiler. The lexical phase can detect errors where the characters remaining in the input do not form any token of the language. During semantic analysis the compiler tries to detect constructs that have the right syntactic structure but no meaning to the operations involved, e.g., when adding two identifiers, one of which is the name of an array and the other is a name of a procedure.


22 TTCN Access

This chapter describes TTCN Access. It is intended to be read by developers of executable test suites, translator developers and test result analyzers. It requires some basic programming knowledge in C++ as TTCN Access is a C++ programming tool.


Introduction to TTCN Access

A TTCN test suite can be looked upon as a formal description of a collection of test sequences where each test sequence involves signals and values. The abstract test suite contains formal definitions of these signals and values as well as a structural description of each test sequence. A common formal notation used to describe these test sequences, as well as all the other items in an abstract test suite, is TTCN.

TTCN Access is a C++ application programmers interface towards an arbitrary abstract test suite written in TTCN and incorporated in the TTCN suite. TTCN Access reveals the content of the test suite in a high level abstraction and allows various users to access the content in a read-only manner.

TTCN Access is a platform for writing applications related to an abstract test suite such as:

  • Executable test suites
  • Interpreters
  • Encoders and decoders
  • Analyzers
  • Reporters

By using TTCN Access, a variety of applications can be implemented that will ease the maintenance of abstract test suites and the development of executable test suites. TTCN Access is an easy-to-use application programmers interface that provides the required functionality for applications in these areas.

Terms Used in This Document:

  • ISO/IEC 9646-3 : 1991 is called the TTCN standard.
  • ISO/IEC 8824 : 1990 is called the ASN.1 standard.
  • Backus-Naur Format is called BNF.

General Concepts

The easiest, and simplest way of describing TTCN Access would be to state that TTCN Access is a TTCN compiler. Unfortunately this statement is not fully true and also somewhat misleading as it might, conceptually, bring the reader (and TTCN Access users) towards the domain of executable test suites and thereby not reveal all the other possibilities that TTCN Access brings. A more correct statement would thereby be that TTCN Access is a half compiler, more precisely the first phase of a compiler, often called the front-end. For a general explanation of compiler theory and compiler front-ends, see 21 Basic Compiling Theory. The fact is that the TTCN to C compiler is built on top of TTCN Access.


TTCN Access and the TTCN Analyzer

All the components and definitions mentioned in 21 Basic Compiling Theory, together build up the basics for compiling theory. As mentioned, TTCN Access is a C++ application programmers interface towards a test suite written in TTCN. It reveals the content of the test suite in a high level abstraction and allows various users to access the content in a read-only manner.

This section will once again mention these components, but this time put them in the context of the TTCN suite and the functionality that it provides, thereby explaining the relationship between the TTCN suite and TTCN Access.

Lexical Analysis

The lexical analysis in the TTCN suite is done in two phases, depending on the format of the abstract test suite.

  • If the source code is in MP format, a basic lexical analysis is done at the import stage, verifying that the imported test suite is written in correct MP format. A full lexical analysis is done when using the Analyzer. The complete lexical analysis is the first phase in the analysis.
    For more information see "Importing a TTCN-MP Document" .
  • If the source code is written directly into the TTCN suite via one of the editors, a lexical analysis is done by using the Analyzer as mentioned above.
    For more information see 27 Analyzing TTCN Documents (on UNIX).

Syntax Analysis

The syntax analysis is done when executing the Analyzer and it is done in the second phase. This second phase also contains a semantic analysis of the test suite, all in order to verify that the test suite complies with the standardized notations for TTCN and ASN.1.

Parse Tree

The last phase of the analysis is to generate a parse tree. This can only be done if the lexical and syntax analysis have been successfully completed.

Symbol Table Management

During execution of an TTCN Access application the symbol table is accessible at any time.


Example of TTCN Access Functionality

As TTCN Access looks upon a test suite as a parse tree, it provides the required primitives and functionality for parse tree handling. This includes parse tree traversing and hooks into the parse tree as well as templates for main() and several examples in source code format. The best way to visualize the functionality of TTCN Access is by using an example:

Figure 180 : The PCO Declarations table

The PCO Declarations table, containing just one PCO declaration will generate the parse tree visualized below:

Figure 181 : Parse tree

Traversing

The basics of parse tree functionality has to include traversing primitives. TTCN Access therefore provides a special visitor class with a default traverser that, given any node in the parse tree, traverses that parse tree in a Left-Right-Depth-First manner. In the parse tree previously described, the default traversing order for the sub tree PCO_Dcl will be:

Figure 182 : Default traversing tree

This default translating algorithm may be customized in order to fit any user specific traversing order. For the above example, a customized traverser could be implemented as traversing sub tree PCO_TypeId before sub tree PCO_Id and ignoring sub tree Comment.

Translating

The second most important functionality when discussing parse trees, is the possibility to access specific nodes in the parse tree in order to generate side effects, such as executing external code, print parse tree information, etc. By being able to modify the default traverser, TTCN Access provides the user with the possibility of defining such side effects.


Example of TTCN Access Usability

To visualize the strength of TTCN Access, this section will discuss a small TTCN Access application. The example is a generic encoder.

The Encoder

Transforming an abstract test suite into an executable test suite will eventually involve the problem of representing the actual ASP and PDU signals as bit patterns. The step from abstract syntax (TTCN) to transfer syntax (bit patterns) has to be provided and implemented by someone with vast knowledge of the actual protocol as well as the test system and the test environment.

The encoder described in this small example will assume the following:

  • Elements of the same type are encoded identically.
  • Encoding an ASP or PDU is performed by encoding its components recursively.

These assumptions tell us that encoding functions are data driven and that the encoding function has to be derived from the type definitions. It also tells us that the encoding of base types, that is INTEGER, BOOLEAN, etc., are identical.

Before looking at the algorithm for the generic encoder, let us have a look at a specific type and how the corresponding encoding function may be implemented. The type will be a small PDU as below:

Figure 183 : TTCN PDU type definition

The corresponding encoding function may look like:

void AUTHENT_REQ1_encode( AUTHENT_REQ1* me, char* enc_buf )
{
INTEGER_encode( &me->message_flag, enc_buf );
BITSTRING_encode( &me->message_type, enc_buf );
AUTH_TYPE_encode( &me->auth_type, enc_buf );
}

It is a data driven encoding function that given any element of type AUTHENT_REQ1 will encode them all identical. The first argument is a pointer to the element that shall be encoded, the second argument is the buffer where the result of the encoding shall be stored.

The function may of course contain more code and more information, but for this example, the above is the smallest encoder function needed.

The following example will give an algorithm for how the encode functions may be generated via TTCN Access. The algorithm is followed by a small TTCN Access application generating the actual encoder.

FUNCTION GenerateEncoder( type : typedefinition )
BEGIN
/* Generate encoder function header such as: */
/* void type_encode( type* me, char* enc_buf ) */
/* { */
FOR( "every element in the structured type" )
/* Generate a call to the element type encoder
/* function
/* such as: */
/* element_type_encode( &type->element, enc_buf );
END
/* Generate encoder function footer such as: */
/* } */
END

The above algorithm will generate generic encoders for any type. Of course, header files and base type encoder functions must be provided/generated as well. Below is a nearly complete TTCN Access application that generates encoders for any TTCN PDU type definition. Observe how the visitor class is customized to traverse and generate side effects for the specific parts we are interested in.

// Start by customizing the default visitor class

class Trav : public AccessVisitor
{
public:
void VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me );
void VisitPDU_FieldDcl( const PDU_FieldDcl& Me );
};

void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
// Generate the header part

cout << Me.pdu_Identifier( ) << "_encode( const ";
cout << Me.pdu_Identifier( ) << "& me, char* enc_buf )";
cout << "\n{" << endl;

// Traverse fields using default traverser

AccessVisitor::VisitPDU_FieldDcls( Me.pdu_FieldDcls( ) );

// Generate the footer part

cout << "}" << endl;
}

void Trav::VisitPDU_FieldDcl( const PDU_FieldDcl& Me )
{
Astring type = get_type( Me.pdu_FieldType( ) );
Astring name = get_name( Me.pdu_FieldId( ) );

cout << "void " << type << "_encode( me->"
<< name << "( ), enc_buf );" << endl;
}

All that remains now is a main function for the generic encode generator.

#include <stdio.h>
#include <iostream.h>
#include <time.h>
#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
void VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me );
void VisitPDU_FieldDcl( const PDU_FieldDcl& Me );
};

int main( int argc, char **argv )
{
//The actual suite

AccessSuite suite;

if ( argc != 2 )
{
fprintf( stderr, "usage: %s suitename\n", argv[ 0 ] );
return 0;
}

/* Open the suite and go for it! */

if ( suite.open( argv[ 1 ] ) )
{
Trav trav;

trav.Visit( suite );
suite.close( );
}
}

The get_type and get_name functions can be simple or complex. See the example below:

Astring get_type( const PDU_FieldType& Me )
{
TypeAndAttributes ta = Me.typeAndAttributes( );
switch ( ta.choice( ) )
{
case Choices::c_TypeAndLengthAttribute:
return get_type( ta.typeAndLengthAttribute( ) );
default:
cerr << "ERROR: Type not supported: "
<< Me.content( ) << endl;
return "***#***";
}
}

Astring get_type( const TypeAndLengthAttribute& Me )
{
const TTCN_Type tt = Me.ttcn_Type( );

switch ( tt.choice( ) )
{
case Choices::c_PredefinedType:
if ( tt.predefinedType( ).choice( ) ==
Choices::c_INTEGER )
return "INTEGER";
break;
case Choices::c_ReferenceType:
return tt.referenceType( ).identifier( );
default:
break;
}
cerr << "ERROR: Type not supported: "
<< Me.content( ) << endl;
return "***#***";
}

Astring get_name( const PDU_FieldId& Me )
{
const PDU_FieldIdOrMacro pfid = Me.pdu_FieldIdOrMacro( );
if ( pfid.choice( ) != Choices::c_PDU_FieldIdAndFullId )
{
cerr << "ERROR: Slot name not supported: "
<< Me.content( ) << endl;
return "***#***";
}

return pfid->pdu_FieldIdAndFullId( ).pdu_FieldIdentifier( );
}


TTCN Access in Relation to TTCN and ASN.1

TTCN Access is created for the purpose of accessing and traversing the contents of a TTCN test suite. As a basis for the development of TTCN Access, the TTCN-MP syntax productions in BNF [ISO/IEC 9646-3, appendix A] together with the ASN.1 standard [ISO/IEC 8824] have been used.

Differences

Every node in TTCN Access reflects a rule in the BNF. However there are some small differences between the BNF and TTCN Access:

The Present Nodes

The intention is to map the ASN.1 and TTCN standards as good as possible. In a perfect world this would mean that no extra nodes could be found in TTCN Access and that each rule in the standards would have exactly one corresponding node in TTCN Access. Some differences between the perfect world and our world are listed in detail below. Differences exist due to redundancies in the standardized grammar or design decisions made during the development of TTCN Access. The goal of any implementation of TTCN Access is to make as few changes compared to the perfect world as possible. However, some extra nodes have been added to TTCN Access, and in a few places the exact calling order of the pre/post functions has been altered to what we feel is a more straight forward approach for executable languages.

The SEQUENCE OF

The TTCN and ASN.1 notations at times allow for arbitrary many nodes to be grouped in lists of nodes or sequences of nodes. For example there is the SubTypeValueSetList rule of the ASN.1 standard and there is the AssignmentList rule of the TTCN standard. In both BNF notations a difference is made between lists that are allowed to be empty and those which must contain at least one element, corresponding to the {} and {}+ notation in the TTCN standard.

In TTCN Access no difference is made between the two forms of lists, since a well defined and simple access method is of prime interest. All lists are allowed to be empty, and it is the work of the Analyzer to ensure non-empty lists where appropriate. In the ASN.1 standard the non-empty lists are sometimes written by re-grouping already existing rules. This re-grouped structure will not be represented in TTCN Access. The decision does not alter the number of nodes or the names of nodes, but merely the visiting order when traversing the nodes, i.e. SubTypeValueSetList before SubTypeValueSet.

Example 160

ASN.1 rule SubTypeSpec:

SubTypeSpec ::= ( SubTypeValueSet SubTypeValueSetList )

becomes:

SubTypeSpec ::= ( SubTypeValueSetList )

In the TTCN standard there are nodes which contain an implicit grouping.

Example 161

TTCN BNF rule:

TestStepLibrary ::= ({TestStepGroup | TestStep})

becomes:

TS_ConstDcls ::= {TS_ConstDcl}+ [Comment].

Furthermore there are nodes that contain groupings without the list postfix name convention.

Example 162

TTCN BNF rule:

TimerOps ::= TimerOp {Comma TimerOp}.

Whenever necessary, a grouping or/and choice node will be inserted between rules in the TTCN standard. When nodes are created without corresponding node in any of the standards, the nodes will be named according to the convention used in the ASN.1 standard, i.e. these nodes will have postfix "List". Nodes which are a grouping but do not follow the naming convention will be left as they are.

OPTIONAL

In the BNF rules for TTCN-MP, the use of [ abc ] implies zero or one instance of abc. In the definition of TTCN Access the same effect is achieved by the use of the symbol "OPTIONAL" after the TTCN Access definition. If a TTCN Access element defined as "OPTIONAL" is not present in a specific instance, no TTCN Access representation for that specific field will be available. To detect whether or not a TTCN Access node defined as "OPTIONAL" is present or not, a boolean TTCN Access function will be necessary to apply to that TTCN Access node in order to verify the presence/absence of the parse tree related to the specific slotname.

FIELD

A difference between TTCN Access and the BNF rules is that TTCN Access views every BNF production reflecting a field in the TTCN-GR format to be optional even though the field is not defined as such in the BNF. The reason for this is that no TTCN Access tree can be built for a field unless a successful analysis has been performed on that field. If the analysis failed, the field will not carry any TTCN Access information and the field may not be accessed.

In TTCN Access all fields are marked with the symbol "FIELD". This "FIELD" symbol implies that the field may be empty. The field may be empty even though the field is not defined as optional in the BNF. To detect whether or not a field is present or not present, a boolean TTCN Access function will be necessary to apply to that TTCN Access node in order to verify the presence/absence of the parse tree related to the specific field. This extension is applicable to all fields except if a field is implemented in TTCN Access as a node of type TERMINAL. All TERMINAL types are strings and TTCN Access sees the absence of a TERMINAL as an empty string.

The Value Notation

The Common Value Notation

The value notations of the two standards must be unified. Some values are clearly within one standard only (SetValue for instance), while others are in both standards (7 for instance). Those values that have the same syntax in both standards are considered to belong to the TTCN standard. Note that the ASN.1 standard might specify some other chain of productions to reach such a value and that this chain of productions is not represented in TTCN Access.

The Expression Tree

The expression rule has been re-written since it is undesirable to have the flat representation from the standard. Instead a normal tree oriented representation of an expression is used. This means that the rules making up an expression are heavily changed.

The Base Nodes

Base nodes are the representation of the terminals in the TTCN Access tree. They can in most aspects be treated as strings, they can be printed directly for example. The base nodes are:

  • Identifier
    Has an associated type
  • Number
  • All nodes having a single child of type BoundedFreeText (FullIdentifier or SO_SelExprId for example).
  • Ostring, Cstring, Bstring and Hstring

Note:

The Keyword class in ITEX Access 1.0 does not exist in ITEX Access 2.0. Neither of the standards has the notion of a keyword class/rule, and therefore there is no node/class named Keyword in ITEX Access 2.0. It has been replaced with ITEX Access node TERMINAL.

Tree Traversing in the Dynamic Part

An extension to the BNF adds the possibility to access the content of test cases, test steps and defaults, by using the logical tree structure of the test. This is achieved by adding a slot in the node type definition BehaviourLine named "children". By accessing that slot an TTCN Access object is returned that holds a vector of children to the current statement line. A child is a BehaviourLine with a level of indentation one greater that the preceding BehaviourLine.

Naming Conventions

As a basis for naming TTCN Access nodes, the names in the BNF for TTCN and ASN.1 have been used. There are some differences though, and they will be discussed and explained in this subsection.

  • No slot name, type name or type definition contains the symbol "&" as it is a reserved symbol in C++. It is replaced with "and" or "And" where appropriate.
  • All type definitions start with an upper case letter (and are written in bold).
  • All slot names start with a lower case letter.
  • All type names start with an upper case letter.


The TTCN Access Notation

The notation used to describe a node in TTCN Access is described as below (a simple BNF for an example node):

Node ::= TypeReference Assign TypeAssignment
TypeReference ::= Identifier
--has to start with an upper case letter
Assign ::= "::="
TypeAssignment ::= ClassType ClassBody | "TERMINAL"
ClassType ::= "SEQUENCE" | "SEQUENCE OF" | "CHOICE"
ClassBody ::= "{" { Slot }+ "}"
Slot ::= SlotName TypeReference
[ "OPTIONAL" | "FIELD"]
SlotName ::= Identifier
--has to start with a lower case letter

Example 163

StructTypeDef ::= SEQUENCE {
structId FullIdentifier FIELD
comment Comment FIELD
elemDcls ElemDcls
detailedComment DetailedComment FIELD
}

  • A TTCN Access node type is defined in Bold starting with an upper case letter.
  • A node can be of type SEQUENCE, SEQUENCE OF or CHOICE. A SEQUENCE contains an ordered collection of elements, a SEQUENCE OF a vector of elements (possibly empty) and a CHOICE is a collection of possible elements.
  • Each slot in a TypeAssignment starts with a SlotName followed by a SlotType. Each SlotType has a corresponding node in TTCN Access.
  • The SlotType can be followed by a FIELD symbol meaning that the slot is associated with a field in the TTCN-GR format.
  • The SlotType can be followed by a OPTIONAL symbol meaning that the slot can be absent.
  • Each slot is followed by a page reference to the node corresponding to the SlotType. This page reference is not a part of the Abstract Data Structure.

For more information see 24 The TTCN Access Class Reference Manual.


TTCN Access Primitives

Each node in TTCN Access is translated to a C++ class definition. Each instance of a specific C++ class definition contains one or more elements as defined in the specific C++ class definition. For each type definition there are a collection of TTCN Access functions.

In this chapter names written in italic are referred to as meta names. Words written in courier are taken from the definition of TTCN Access.

Note:

For further details see the TTCN Access include file access.hh.

General TTCN Access Functions Description

  • For every node definition with assignment of type SEQUENCE or SEQUENCE OF there exists a general method
SlotType TypeReference.SlotName()
that returns an object of type SlotType. This type is the type of the corresponding slot in TTCN Access.

Example 164

Attach MyRepeat.attach()
where MyRepeat is of type Repeat and the return value is of type Attach.

  • For every TypeAssignment of type CHOICE there is a general method
Choices::choice TypeReference.choice()
that returns the allowed SlotName type for current object. It is then possible to use the general method
SlotType TypeReference.SlotName()
that returns an object of type SlotType.

Example 165

switch ( MyEvent.choice() ) {
case Choice::c_send:
do_something( Me.send() );
break;
case Choice::c_receive:
do_something( Me.receive() );
break;
case Choice::c_otherwise:
do_something( Me.otherwise() );
break;
case Choice::c_timeout:
do_something( Me.timeout() );
break;
case Choice::c_done:
do_something( Me.done() );
break;
default:
do_something_default();
break;
}

  • For every node of type SEQUENCE OF there is a general method
SlotTypeList TypeReference.SlotName()
that returns an object of type SlotTypeList which is a vector of elements of type SlotType.

Example 166

Assume that MyEvent.choice() in the previous example returned the value Choice::c_done. Then, TTCN Access method MyEvent.done().tcompIdList will then be a valid method and return an object of type TCompIdList.

  • Every object of type SlotTypeList has a method
int Object.nr_of_items()
that returns the number of elements in the vector. The elements can be accessed with the method
SlotType Object[ index ]
where Object is an element of type SlotTypeList and index starts with 0 for the first element. It returns an element of type SlotType.

Example 167

According to the above example the method MyTCompIdList.nr_of_items() returns an integer value of the number if items in the vector object MyTCompIdList and MyTCompIdList[ 2 ] will return the third element in the vector.

  • For slots with ending OPTIONAL or FIELD there is a general method
Boolean TypeReference.is_present_SlotName()
used for verifying if an object is present or not. It is the responsibility of the TTCN Access programmer to ensure that all calls to optional slots are preceded with a call to the is_present method of that slot. It is a fatal error to attempt to access a non-present optional slot.
  • For slots with ending FIELD and slots residing in a sub tree to a field there is a general method
Astring Node.content()
that returns an object of type Astring holding the content of the current field in a vector of characters.

Example 168

The following C++ code will print out the content of a behavior line:
BehaviourLine BLine = MyLine;

cout << BLine.line( ).content() << endl;

Terminal Nodes in TTCN Access

Every TTCN Access node that represents a leaf in the parse tree is considered to be a terminal TTCN Access node. A terminal TTCN Access node is a node that does not have any TTCN Access child nodes and can therefore not be accessed any further.

Terminal TTCN Access children are nodes containing identifiers, strings, keywords as well as numbers (i.e. TTCN Access nodes of type Identifier, IA5String, INTEGER, NUMBER, etc.). However, the content of such terminal nodes can be accessed through the methods supplied by the inherited class Astring.

TTCN Access Class Astring

Every terminal TTCN Access node carries information in string format. In order to access that information, every terminal TTCN Access node inherits a class named Astring. This class contains various methods for treating string information.

For terminal TTCN Access nodes, the following operations are available:

  • Initialization operations

Example 169

The following C++ code will create and initiate a variable of type Astring:
Astring tmp1; // tmp1 is empty
Astring tmp2( "test1" ); // tmp2 contains "test1"
Astring tmp3 = "test2"; // tmp3 contains "test2"
Astring tmp4 = tmp2; // tmp4 contains "test1"

  • Relational operations

Example 170

The following relational operations are available between Astring elements:
==, !=

  • Astring objects are type cast equivalent with const char*

Example 171

The following code is valid C++ code:
Astring myString( "test" );

cout << myString;
printf( "%s", ( const char* ) myString );

  • Address the nth character in the string, starting with 0.

Example 172

The following is valid C++ code:
char c = myString[ 2 ]; // save the third character of the string

Note:

For further details see class Astring in TTCN Access include file ITEXAccessClasses.hh.

Direct Access

AccessSuite

The AccessSuite object is the TTCN Access representation of a TTCN test suite. The test suite is in turn contained in a TTCN suite data base. The AccessSuite services include opening and closing the TTCN suite data bases as well as services to start an TTCN Access application and accessing the symbol table manager.

Example 173

Opening and closing the test suite Test.itex for use in TTCN Access:

AccessSuite suite;

Boolean ok_open = suite.open( "Test.itex" );
if( ok_open )
{
// do something
Boolean ok_close = suite.close();
}

After opening a test suite for TTCN Access use, it is possible to use the following methods to get a handle to the contents of the data base file:

  • Get a handle to the root node of the document.

Example 174

Getting a handle to the root object of a document:
AccessSuite suite;
Boolean ok_open = suite.open( "Test.itex" );
if( ok_open ) {
const AccessNode node = suite.root();
// do something with NSAPaddr
Boolean ok_close = suite.close();
}

Note:

For further details see class AccessSuite in TTCN Access include file access.hh.

  • Ask the AccessSuite object for a specific TTCN Access object in the test suite. The object asked for must be a global object in the test suite. This is performed by using TTCN Access class AccessNode.

Example 175

Find the TTCN Access object NSAP in test suite Test.itex:
AccessSuite suite;
Boolean ok_open = suite.open( "Test.itex" );
if( ok_open ) {
const AccessNode node = suite.find("NSAPaddr");
// do something with NSAPaddr
Boolean ok_close = suite.close();
}

The AccessNode object now holds the TTCN Access item corresponding to the name NSAPaddr, if any.

To gain access to the data in an AccessNode, you must now find out the runtime type of the object. Based on that type, you will be able to use the conversion routine for an object of the corresponding type:

Example 176

Find the type of the TTCN Access node corresponding to a name:

extern void HandleSimpleType( const SimpleType * );

AccessSuite suite;
Boolean ok_open = suite.open( "Test.itex" );
if( ok_open ) {
AccessNode node = suite.find( "SomeName" );
switch( node.choice() ) {
case Choice::_SimpleType:
HandleSimpleType(node.SimpleType());
break;
default:
break;
}}

Note:

For further details see class AccessNode in TTCN Access include file access.hh


The AccessVisitor Class

TTCN Access is a large class library, with over 600 classes, and therefore we also need suitable tools for simplifying the creation of TTCN Access applications. The preferred solution is the usage of the class AccessVisitor, which definition is available in the C++ header file ITEXAccessVisitor.hh.

The AccessVisitor class is a very close relative to the design pattern `Visitor' (described by, for instance, Gamma, Helm, Johnson and Vlissides in `Design Patterns - Elements of reusable software', Addison-Wesley1994). The difference is that the TTCN Access classes contain runtime type information which eliminates the need for them to have dependencies to the Visitor class (and therefore there is no need for `Accept' methods in the visited classes).

An object of a class which is derived from the class AccessVisitor is later on referred to as a `visitor'.

AccessVisitor Class Members

Common Classes

The AccessVisitor class has two methods for visiting objects of common classes AccessSuite and AccessNode. These are declared

public:
void Visit( const AccessNode );
void Visit( const AccessSuite & );

and calling them with, will start a chain of calls in the visitor which effectively is a pre-order traversal of the subtree of the AccessNode, or the complete syntactical tree of the AccessSuite.

TTCN/ASN.1 Derived Classes

The AccessVisitor class has one virtual member function for each TTCN and ASN.1 derived class in TTCN Access. Each of the member functions are declared

public:
virtual void Visit<class>( const <class> & );

Example 177

Visitor member method for an Identifier (excerpt from ITEXAccessVisitor.hh):

class AccessVisitor
{
public:
...
virtual void VisitIdentifier(const Identifier&);
virtual void VisitVerdict(const Verdict&);
...
};

The base class implementation of this method calls the related Visit<child-class> function for all of the child objects to the current object.

If you need to change the behavior, for instance in order to generate some code or report from the TTCN Access Suite, just derive a new class from the AccessVisitor class and override the relevant method(s). Call the base class implementation of the method to traverse the children if needed.

Data Members

The AccessVisitor class contains no explicitly declared data members and is therefore stateless. It therefore makes program re-entrance possible, and several visitors may be active in the same tree/document at the same time if needed.

Using the AccessVisitor

The intended usage of the AccessVisitor class is by derivation. Derive one or several specialized classes for each of the purposes which you use TTCN Access. Override the relevant methods.

Use Case - Information Collection

It is simple to create a visitor class for collection of some kind of information from the test suite. The basic method for this is to have a handle or actual information in the visitor class.

Example 178

An information collecting visitor class:

#include <time.h>
#include <iostream.h>
#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

//
// A visitor which counts the number of testcases
// in a test suite.

class TestCounter : public AccessVisitor
{
public:
TestCounter() : _count( 0 ) { }
~TestCounter() { cout << _count << endl; }
void VisitTestCase(const TestCase&) { _count++; }
private:
unsigned int _count;
};

// Small example usage, no real fault control...

int main( int argc, char ** argv )
{
AccessSuite suite;
if ( suite.open( argv[1] ) ) {
TestCounter testCounter;
testCounter.Visit( suite );
}
return 0;
}

Use Case - Code Generation

It is likewise simple to create a class for simple code generation. The following example is a class for generation of a c-style declaration which contains a list of all SimpleType names in a test suite.

Example 179

An information collecting visitor class:

#include <stdio.h>
#include <time.h>
#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

// A visitor which generate a c-style declaration
// of a null-terminated array of all Simple Type
// Declarations (identifiers) in a test suite.

class ListGenerator : public AccessVisitor
{
public:
ListGenerator(FILE * f) : _file( f ) {
printf( "const char *ids[]={\n");
}
void VisitSimpleTypeId(const SimpleTypeId& id) {
printf( " \"%s\",\n", (const char*)
id.simpleTypeIdentifier());
}
~ListGenerator() {
printf( " NULL\n};\n");
}
};

// Small example usage, no real fault control...

int main( int argc, char ** argv )
{
AccessSuite suite;
if ( suite.open( argv[1] ) ) {
ListGenerator generator;
generator.Visit( suite );
}
return 0;
}

The last two examples are not the most efficient implementations due to the fact that they traverse the whole tree even though we are only interested in small parts, and therefore we may want to improve the efficiency. This may be done using any of the techniques described in "Optimizing Visitors" .

Advanced Use Case - Combined Visitors

More advanced designs may be possible by combining several visitors for performing more advanced tasks. You may for instance have visitors which are parameterized with other visitors for specialized tasks, where you still would want to maintain decent performance and yet not have trade-offs in clarity of the design.

Example 180

A TTCN Interpreter would need a mechanism for building an internal representation of values. Values are always built by using the same structure, but you may wish to have several possible representations of atomic values. A visitor could be used to generate the value objects, where one visitor is used for building the overall structure, and another is used for building individual fields. There are at least two choices available in the design:

  • To inherit the structure building class into the class which builds the atomic values
  • To parameterize the structure building class with the atomic value handing class (which gives you a possibility to tune the behavior at runtime).

In this example, the value building class inherits from the AccessVisitor class and the Visit<xxx> functions are used to generate a new value. The class GciValueBuilder in the example, may visit any structured type and will on the Visit<class> function either create itself a data value, or if it is a structured type, create a dynamic array, and then invoke a new visitor for each of the fields, which results will later be assigned to each of the fields in the same array. The implementation is not present in the example. It is just outlined below.

The solution of using visitors for building the values, removes the switch statements, which otherwise would undoubtedly clobber an implementation which uses Direct Access as described in a previous section.

class GciValueBuilder : public AccessVisitor
{
// basic structure for building/matching values
virtual void VisitXxxx( const Xxxx & );
...
// built value
GciValue * _value;
};

class GciValueBinaryBuilder : public GciValueBuilder
{
// suitable overrides for efficient binary value
// handling
...
};

class GciValueBigNumBuilder : public GciValueBuilder
{
// suitable ovverides for a `bignum'
// implementation
...
};

Optimizing Visitors

A visitor is a potentially inefficient way to find and process objects, since it in its unmodified version traverses the whole document, without regarding what parts of the document the inherited visitor is interested in. All optimizations are in the domain of limiting the subtree for which we are traversing. The following examples shows methods for avoiding unnecessary traversal and optimally, constant time access.

Example 181

Optimizing a visitor class to avoid traversal of all parts but the declarations part, may improve performance for suite traversal by over 100 times for some fairly representable suites (since most suites contain more and larger syntactical trees in the dynamic part than in all other parts, possibly with the exception of ASN.1 constraint declarations).

class DeclarationChecker : public AccessVisitor
{
public:
void VisitSuiteOverviewPart(
const SuiteOverViewPart& ) { }
void VisitConstraintsPart(
const ConstraintsPart & ) { }
void VisitDeclarationsPart (
const DeclarationsPart & ) { }

// Add the functions which actually do processing
// below ...
};

Optimizing a visitor class to traverse only parts we are interested in, is also possible, by using one or a few levels of Direct Access instead of the default traversal.

Example 182

This example skips all traversal down to the Simple Type Definitions table, and only traverses those.

class SimpleTypeIdPrinter : public AccessVisitor
{
public:
void VisitASuite( const ASuite& );
void VisitSimpleTypeId ( const SimpleTypeId & );
};

void
SimpleTypeIdPrinter::VisitASuite(const ASuite & s)
{
VisitSimpleTypeDefs( s.declarationsPart().
definitions().
ts_TypeDefs().
simpleTypeDefs());
}

void
SimpleTypeIdPrinter::VisitSimpleTypeId( const
SimpleTypeId & id )
{
cout << "Id: "
<< id.simpleTypeIdentifier()
<< endl;
}

Finally, you may combine several visitors into one visitor, thus avoiding multiple passes when processing a suite. This implies that you define several classes which are not truly visitors, and define a inherited class from AccessVisitor which calls methods in these classes.

Example 183

Two objects driven by a visitor, thus performing two passes on one traversal.

class IdOperation
{
public:
virtual void AtIdentifier(const Identifier&) = 0;
};

// A IdOperation

class IdCounter : public IdOperation
{
public:
IdCounter( ) : _count( 0 ) { }
void AtIdentifier( const Identifier & id )
{ _count++; }
~IdCounter( ) { cout << _count << endl; }
private:
unsigned int _count;
};

// Another IdOperation

class IdPrinter : public IdOperation
{
public:
void AtIdentifier( const Identifier & id )
{ cout << id << endl; }
};

// A class which drives up to IdOpDriverMax
// IdOperations

const int IdOpDriverMax = 10;

class IdOpDriver : public AccessVisitor
{
public:
IdOpDriver() : _ops_used(0) { }
void VisitIdentifier( const Identifier & id ) {
for (unsigned int op = 0 ; op < _ops_used; ++op)
_ops[op].AtIdentifier( id );
}
void AddIdOp( IdOperation * op )
{ _ops[_ops_used++] = op; }
private:
IdOperation _ops[IdOpDriverMax];
unsigned int _ops_used;
};

// Main routine which opens a suite and applies two
// IdOperations.

int main( int argc, char ** argv )
{
AccessSuite suite;
if ( suite.open( argv[1] ) ) {
IdCounter counter;
IdPrinter printer;
IdOpDriver driver;
driver.AddIdOp( &counter );
driver.AddIdOp( &printer );
driver.Visit( suite );
suite.close( );
}
return 0;
}


Common Class Definitions

This part contains the declaration of the three common TTCN Access classes AccessSuite, AccessNode and Astring. For further information see TTCN Access include file access.hh.

AccessSuite

class AccessSuite
{
public:
AccessSuite();
~AccessSuite();
AccessSuite( const AccessSuite& orig );
void operator=( const AccessSuite& orig );

Boolean open( const char* suite_name );
Boolean open( Suite* suite );
Boolean close();

const AccessNode root();
const AccessNode find( const Identifier & id );
const AccessNode find( const char* id );
};

AccessNode

class AccessNode
{
public:
AccessNode();
AccessNode(NodeInfo nodeinfo);
~AccessNode();
AccessNode(const AccessNode& Me);

int operator==(const AccessNode& o) const;
void operator=(const AccessNode& orig);

Boolean is_equal(const AccessNode& o) const;
Choices::Choice choice() const;
Boolean ok() const;

};

Astring

class Astring
{
public:
Astring();
Astring(const char* s);
// end should point to the char after the last char
Astring(const char* begin, const char* end);
Astring(Field* field, PT* pt);
Astring(const Astring& orig);

~Astring();

//operators
Astring* operator->();
const Astring* operator->() const;
operator const char*() const;
char& operator[](unsigned i) ;
char operator[](unsigned i) const ;

void operator=(const Astring&);
void operator=(const String&);
void operator=(const char*);
void operator=(const char);

int operator==(const Astring& s) const;
int operator!=(const Astring& s) const;
int operator==(const char* cs) const;
int operator!=(const char* cs) const;
};


Getting Started with TTCN Access

Setting Up the TTCN Access Environment

When building applications using TTCN Access, the compiler will need to find a few files, the ITEXAccessClasses.hh include file and the libaccess.a library file. Normally these files are found in the .../itex/include/CC and .../itex/lib/CC directory respectively. The include file must be included in every TTCN Access application and the library libaccess.a must be used when linking.

Note:

For further information, contact your system administrator.

TTCN Access operates on the TTCN suite data bases. These data bases must have passed analysis and be saved before using TTCN Access. If the data base contains a TTCN test suite that is not analyzed, the TTCN Access application can not reach into the fields of the tables. The default behavior of TTCN Access is to simply skip those fields that are not analyzed. De-referencing a particular field in an non-analyzed data base, will result in undefined behavior.

TTCN test suite data bases are managed by the AccessSuite object, which has member functions for opening and closing the TTCN suite data bases and also for starting traversing. From an AccessSuite object it is also possible to access tables in a random manner via the symbol table manager.

Using Example Applications

TTCN Access is delivered with some simple example applications. To compile the examples, the installation directory, where the ITEXAccessClasses.hh and libaccess.a files reside, must be known to the makefiles. Do this by setting the environment variable ACCESS or by explicitly filling in the local variable ACCESS in every makefile or using make with the syntax make ACCESS=$telelogic/itex/access.

Starting an TTCN Access Application

You have to retrieve the TTCN Access license when you start the TTCN suite. To do this, start the TTCN suite from the command line with the switch -access.

Then you can execute TTCN Access applications from the command line or from the window manager.

You can also select Start Application in the Access menu in the Browser. This will open a dialog in which you may change settings and start the TTCN Access application.

Figure 184 : The Start Application dialog

Save selection first

Select this to save the current selection in the Browser before executing the TTCN Access application.

Switches

Switches may be passed to the chosen TTCN Access application. The switches are written as free text. As the last argument is the name of the the TTCN suite database passed. This name is always passed to the TTCN Access application.

Note:

Observe that it is the name of the (working) database file and not the name of the test suite that is passed to the TTCN Access application.

Filter

Sets the filter for the files that will be displayed in the Suites list. There are no predefined naming conventions for TTCN Access applications.

For example the name filter *.acc will cause only those files whose names end with .acc to be displayed.

Access application

Displays the selected application.


23 Creating a TTCN Access Application

This chapter is intended to be an introduction to how to create a TTCN Access application, and it is expected to be read sequentially. As TTCN Access is a C++ application programmers interface, this chapter will contain several TTCN Access applications written in C++. The chapter includes general TTCN Access application concepts as well as specific examples.

For reference, the test suite that is used as input to the various TTCN Access applications, is included in TTCN-GR form at the end of this chapter together with the source code for each example.


TTCN Access

TTCN Access is a C++ application programmers interface. It is a platform for writing applications related to TTCN test suites such as:

  • Executable test suites
  • Interpreters
  • Encoders and decoders
  • Reporters

TTCN Access is meant to be used by executable test suite developers, translator developers as well as test result analyzers.

In order to make this chapter as complete as possible and thereby cover as many different TTCN Access application domains as we can, this chapter contains several different examples, each described in its own section. However, before we start with the examples, we will explain some general concepts that apply to every TTCN Access application.

Note:

This chapter is an TTCN Access primer and is not intended to provide a chapter in C++ programming.


General Concepts

The TTCN Access Application

A TTCN Access application is typically an application that produces some kind of output during the traversing of an Access tree. The Access tree, tree for short, is a tree oriented representation of a test suite. This tree is stored in the database <TestSuite>.itex where <TestSuite> is the user given name of the database.

The first section introduces the basic methods. These include the main function and how to initialize a test suite in a TTCN Access application. The second section describes how the traversing is done.

Basic Methods

When executing a TTCN Access application there are some basic methods that have to be applied before and after traversing the tree. First of all, to be able to get all the definitions needed, the header files ITEXAccessClasses.hh and ITEXAccessVisitor.hh have to be included. These files must be included in all TTCN Access applications as shown below:

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

Once this is done, we need to create an instance of the AccessSuite class. This can be done as follows:

AccessSuite suite;

The AccessSuite class can be seen as a handle to the Access tree and the symbol table. It will be used for opening and closing the database and for finding specific, named Access objects stored in the symbol table.

To open a database for reading, the following method has to be called:

Boolean open_ok = suite.open( arg );

where arg is a string containing the name of the database that shall be opened. This method must always be applied to the database before traversing the Access tree. The method returns a boolean value stating whether the database could be opened or not. To close a database the following method must be called:

Boolean close_ok = suite.close();

This method requires no database name to be given as the database that will be closed is associated with suite. The method returns a boolean value stating whether the database could be closed or not. Below is a generic TTCN Access main function where argv[1] contains the name of the database:

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

int main( int argc, char **argv )
{
AccessSuite suite;

if ( suite.open( argv[ 1 ] ) ) // OK open database?
{
// Write your Access application here
// Typically start the traverser

if ( suite.close( ) ) // OK close database?
return 1;
else // Error close database!
return 0;
}
else //Error open database!
return -1;
}

Traversing the Access Tree

The traversing of a test suite is the "engine" that actually drives the TTCN Access application to execute.

The previous section was only concerned with opening and closing of the database. This section will describe and explain the different methods that TTCN Access provides for starting the actual TTCN Access application, i.e. starting the traversing from different nodes in the Access tree.

To be able to allow the user to traverse the tree in a simple way, TTCN Access provides a visitor class that can be customized in a flexible way by the user. The class is called AccessVisitor and provides different ways of traversing.

In all the examples discussed in the following sub sections, we assume that we have a global instance of the class AccessSuite called suite, a global instance of the class AccessVisitor called visitor and that a test suite has been opened as described in the previous section.

Traversing from the Root of the Tree

As TTCN Access can be seen as a huge tree, the basic method for traversing will be to start traversing from the root. This will result in a traversing that will traverse the full Access tree starting from top. This is performed by calling the method:

Boolean root_ok = visitor.Visit( suite );

It is an error to try to traverse a database that has not been previously opened.

Traversing by Reference

In some cases it is desirable to start traversing from a specific table, i.e. a test case or a type definition. TTCN Access provides means for this in terms of using its symbol table.

The symbol table handles global entities, that is elements that must be globally unique within a test suite according to the TTCN standard (9646-3). Such elements are all variable names, all type names, all test case names, etc.

To start traversing the Access tree from a specific element, TTCN Access provides a simple solution divided into four steps:

  1. The first step is to get a handle to the symbol table:
AccessNode node = suite.find( name );

This method will return a handle to the symbol table.
  2. The second step is to verify that this handle holds an element present in the symbol table. This is performed by applying the following method:
Boolean symbol_table_ok = node.ok();

  3. Assuming that the argument name was a global name in the test suite, we still do not know what kind of element it is. It could for example be a TTCN PDU type definition, a test case or a test step. The handle to the symbol table provides a method for finding the Access type of its corresponding element. The third step will be to ask the symbol table what type its corresponding element has:
Choices::Choice type = node.choice();

This method will return an enumerated value of type Choices::Choice revealing the type of the element. As there are several different Access types, this type check is best solved in a switch statements. Assuming that the name can be either a test case or a TTCN PDU type definition, the following switch statement will detect that.
switch( node.choice( ) )
{
case Choices::c_TTCN_PDU_TypeDef:
//
// do something
//
break;
case Choices::c_TestCase:
//
// do something else
//
break;
default:
//
// do something default
//
break;
}
  4. The fourth step is to call the corresponding traverser function.
    Below is a complete example that will traverse a test suite starting from a specific element. The example assumes that the function main( ) is called with two arguments where the first is the name of the database and the second is the name of the element that the traversing shall start from. This application can only handle TTCN PDU type definitions and test cases.
int main( int argc, char **argv )
{
AccessSuite suite;
AccessVisitor visitor;

if ( suite.open( argv[ 1 ] ) ) // OK open database?
{
//Get the handle

AccessNode node = suite.find( arg[ 2 ] );

if ( node.ok( ) ) // Handle ok?
visitor.Visit( node );
else // Error in symbol table
return -2

if ( suite.close( ) ) // OK close database?
return 1;
else // Error close database!
return 0;
}
else // Error open database!
return -1;
}


Examples

This section provides all the examples in this chapter. It starts with a simple TTCN Access application and continues from there. Every example is discussed in its own subsection. In each subsection, only the interesting parts are discussed. A complete solution to every example can be found in "Solutions to the Examples" .

Every TTCN Access application can be seen as an application providing a solution to a problem. These problems are related to TTCN test suites in general, such as reporters or style checkers, encoders and decoders. Therefore, every example in this chapter will be preceded with a small discussion of the actual problem that the corresponding TTCN Access application shall solve. Of course, the problems discussed in this chapter will mainly be of a fictive nature, but they will reflect the simplicity of TTCN Access and the different implementation techniques and methods that TTCN Access provides.

In all examples, we assume that there exist a global instance of the class AccessSuite called suite, a global instance of the class AccessVisitor called visitor and that a test suite has been opened.

The Identifiers

Objective

In every test suite there exists a set of identifiers. The objective of this example is to print out every identifier present in the test suite.

Solution 1

Every identifier present in an Access tree will be represented as an Access node of type Identifier. The solution will therefore only include one user defined method in the visitor class instance that, when entering the node Identifier, prints the content of that class. In this case it is the name of the identifier. The method is provided below.

void Trav::VisitIdentifier( const Identifier& Me )
{
printf( "Identifier %s\n", (const char*) Me );
}

This method will be called from TTCN Access every time the traverser enters the Identifier node. The name Identifier is the name of the Access node and the prefix tag Visit means that this is a visiting method.

As the task of a TTCN Access application is to traverse a test suite according to the traverser and call possibly user defined functions or methods, we need to create a traverser that will use the default traversing, but have the desired small change. This is done by sub classing as follows:

class Trav : public AccessVisitor
{
public:
void VisitIdentifier( const Identifier& id );
};

As identifiers are present everywhere in the Access tree, no change to the traversing order needs to be done. The default traverser will be used and the traversing will start from root.

The full solution is found in "Solution 1" .

Context

Objective

When executing the previous example, all identifiers in the given test suite will be printed. By looking at the output one might think that there should not be so many identifiers in the test suite, but the way in which the grammars are specified (both TTCN and ASN.1), nearly every grammar rule ends in a identifier. This example will explain the importance of calling the user defined function at their correct place, or to be more specific, in its right context.

Let us assume, with the previous example in mind, that we want to distinguish between TTCN PDU type definition identifiers and TTCN PDU constraint identifiers (the rest is of no concern). This can be achieved in several different ways. Below are two different solutions to this problem.

Solution 2

This first solution, looking at each identifiers type, will be implemented in the visiting method used in the previous example. However, it has to be extended to look at each identifier type and only print the appropriate ones. The updated method is found below.

void Trav::VisitIdentifier( const Identifier& Me )
{
switch( Me.choice( ) )
{
case Choices::c_TTCN_PDU:
printf( "Identifier `%s' is a TTCN PDU type\n",
(const char*) Me );
break;

case Choices::c_TTCN_PDU_Cons:
printf( "Identifier `%s' is a TTCN PDU constraint\n",
(const char*) Me );
break;

default:
break;
}
}

Solution 3

The second solution will replace the used method with two new ones. The first method will print out every TTCN PDU type definition identifier. This will be done in the method VisitTTCN_PDU_TypeDef. The second, VisitTTCN_PDU_Constraint, will print out every TTCN PDU constraint identifier. In each method the Identifier Access node is reached by explicit addressing, that is, explicitly naming the path to the Access node Identifier. Their corresponding definitions are supplied below.

void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
printf( "Identifier `%s' is a TTCN PDU type\n",
(const char*) Me.pdu_Id( ).pdu_IdAndFullId( )
.pdu_Identifier( ) );
}

void Trav::VisitTTCN_PDU_Constraint( const TTCN_PDU_Constraint& Me)
{
printf( "Identifier `%s' is a TTCN PDU constraint\n",
(const char*) Me.consId( ).consIdAndParList( ).
.constraintIdentifier( ) );
}

The definition of the visitor object is done as follows:

class Trav : public AccessVisitor
{
public:
void VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& );
void VisitTTCN_PDU_Constraint( const TTCN_PDU_Constraint& );
};

Comments

When executing the two examples above with the test suite in the end of this chapter as input, one will find that the output is not equivalent. The first solution will have some more output lines that the second one. By adding the following line to each method, one will detect in which table the identifier was found.

printf( "In table `%s': ", (const char*) Me.table_name() );

One will find that the extra lines of output in the first solution are produced from the Constraints Part and the Dynamic Part. This is true due to the fact that the type identifiers are being used in each constraint and the constraint identifiers are being used in the Constraint Reference column in each test case and test step table.

The full solutions are found in "Solution 2" and "Solution 3" .

Translating TTCN

A very common and useful TTCN Access application is to translate a test suite to another target language. Examples are C, C++, Pascal etc. By doing this translation we can thereby create an executable test suite. To achieve this, one needs a TTCN translator that translates a TTCN test suite to the specific source code. This example will not be a full translator, but will rather show how such a translator can be written by using TTCN Access.

Objective

In this example, we will translate TTCN PDU type definitions to C where each PDU will be a unique C type. To achieve this, we need to have some kind of mapping between TTCN and C. One way to do this is to do a case study. First we will look at a TTCN PDU type definition in the table format and from that table extract how the corresponding C representation shall be. Then, a generic representation of all TTCN PDUs in C will be defined. This generic representation will then be implemented in TTCN Access, and thereby a generic TTCN PDU type definition to C translator will be implemented.

Solution 4

Let us have a look at a TTCN PDU type definition in table format. The table below, the TTCN PDU type definition SEND, is taken from the test suite attached to the end of this chapter.

Figure 185 : TTCN PDU Type Definition

A corresponding C representation of the above type could look something like:

typedef struct {
INTEGER Field_1;
BOOLEAN Field_2;
} SEND;

That is, a structured type holding the same number of elements as the corresponding TTCN type definition. In this example, no consideration is taken to the PCO type. This is only done for simplicity and can of course be included in the type as well.

As one can see in this example there are a lot similarities between the TTCN definition and the C representation in terms of names of elements and their corresponding type. This helps us define a generic C representation of a TTCN PDU type definition as below:

typedef struct {
Element1_Type Element1_Name;
Element2_Type Element2_Name;
...
ElementN_Type ElementN_Name;
} PDU_TypeName;

The type and name of each element is taken from the corresponding names in the TTCN type definition and the type defined is named as in TTCN.

Now, the next step is to implement this generic type in TTCN Access! To do this, we divide the generic C type into three distinct elements; the header, the body and the footer.

The Header and Footer

The visitor method that traverses the TTCN PDU type definitions, will be the one responsible for generating the header and footer of the generated C structure definition. The method may look something like this:

void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
// Generate the header part

cout << Me.pdu_Id( ) << "_encode( const ";
cout << Me.pdu_Id( ) << "& me, char* enc_buf )";
cout << "\n{" << endl;

// Traverse fields using default traverser

AccessVisitor::VisitPDU_FieldDcls( Me.pdu_FieldDcls( ) );

// Generate the footer part

cout << "}" << endl;
}

This method will be called every time the traverser enters the Access node TTCN_PDU_TypeDef.

The Body

The body of the type definition, is a collection of rows where each row is translated identically. A row can be translated by defining the following method:

void Trav::VisitPDU_FieldDcl( const PDU_FieldDcl& Me )
{
printf( " %s %s;\n",
(const char*) get_type_str( Me.pdu_FieldType( ),
(const char*) get_id( Me.pdu_FieldId( ) );
}

where get_type_str and get_id are two functions returning the type and the name of the element respectively. This method shall be called every time the traverser enters the Access node PDU_FieldDcl.

The full solution is found in "Solution 4" .


Summary

TTCN Access provides a platform for generating applications in the domain of TTCN, conformance testing and related applications such as translators, interpreters, analyzers, reporters, etc. TTCN Access is a C++ representation of the related grammars that spans the language TTCN. We hope that this chapter has revealed the basis of TTCN Access, the methods it supplies and how easy it is to use. All examples in this chapter have full solutions in "Solutions to the Examples" .


Solutions to the Examples

This section contains fully implemented solutions to each example given in the "Examples" . It will also contain the expected output when executing each TTCN Access application with the example test suite as input.

Makefile

This generic Makefile has been used for compilation and linking:

#----------------------------------------------------------
# Name: Makefile
#
# Destcription:
# Generic Makefile for Access applications
# Note that the makefile requires the variable
# itexaccess to be set.
#----------------------------------------------------------

ACCESS-INCL = $(itexaccess)/include
ACCESS-LIB = $(itexaccess)/lib

TARGET = the name of the target
OBJS = $(TARGET).o

#------------------------------------------------------

$(TARGET) : $(OBJS)
$(CCC) -L$(ACCESS-LIB) -Bstatic -o $@ $(OBJS) -laccess
strip $@

#------------------------------------------------------

clean :
/bin/rm $(TARGET) $(OBJS)

#----------------------------------------------------------

.SUFFIXES: .cc .o

.cc.o :
$(CCC) -I$(ACCESS-INCL) -c -o $@ $<

Solution 1

Code

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
void VisitIdentifier( const Identifier& id );
};

void Trav::VisitIdentifier( const Identifier& Me )
{
printf( "Identifier %s\n", (const char*) Me );
}

int main( int /* argc */, char **argv )
{
AccessSuite suite;

if( suite.open( argv[ 1 ] ) ) // OK open database?
{
Trav visitor;

visitor.Visit( suite );

if( suite.close( ) ) // OK close database?
return 1;
else // Error close database!
return 0;
}

else // Error open database!
return -1;
}

Output

> ./print-ids ../Example_Suite_A.itex
Identifier Example_Suite_A
Identifier Example_Suite_A
Identifier L
Identifier LOWER_PCO
Identifier SEND
Identifier LOWER_PCO
Identifier Field_1
Identifier Field_2
Identifier RECEIVE
Identifier LOWER_PCO
Identifier Field_1
Identifier Field_2
Identifier S1
Identifier SEND
Identifier Field_1
Identifier Field_2
Identifier R1
Identifier RECEIVE
Identifier Field_1
Identifier Field_2
Identifier TEST_CASE_1
Identifier L
Identifier SEND
Identifier S1
Identifier TEST_STEP_1
Identifier TEST_STEP_1
Identifier L
Identifier RECEIVE
Identifier R1
Identifier L
>

Solution 2

Code

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
void VisitIdentifier( const Identifier& Me );
};

int main( int /* argc */, char **argv )
{
AccessSuite suite;

if( suite.open( argv[ 1 ] ) ) // OK open database?
{
Trav visitor;

visitor.Visit( suite );

if( suite.close( ) ) // OK close database?
return 1;
else // Error close database!
return 0;
}

else // Error open database!
return -1;
}

void Trav::VisitIdentifier( const Identifier& Me )
{
switch( Me.choice( ) )
{
case Choices::c_TTCN_PDU:
printf( "Identifier `%s' is a TTCN PDU type\n",
(const char*) Me );
break;

case Choices::c_TTCN_PDU_Cons:
printf( "Identifier `%s' is a TTCN PDU constraint\n",
(const char*) Me );
break;

default:
break;
}
}

Output

> ./print-ids ../Example_Suite_A.itex

Identifier `SEND' is a TTCN PDU type
Identifier `RECEIVE' is a TTCN PDU type
Identifier `S1' is a TTCN PDU constraint
Identifier `SEND' is a TTCN PDU type
Identifier `R1' is a TTCN PDU constraint
Identifier `RECEIVE' is a TTCN PDU type
Identifier `SEND' is a TTCN PDU type
Identifier `S1' is a TTCN PDU constraint
Identifier `RECEIVE' is a TTCN PDU type
Identifier `R1' is a TTCN PDU constraint
>

Solution 3

Code

#include <access.hh>

void id_pre_TTCN_PDU_TypeDef(const TTCN_PDU_TypeDef& Me);
void id_pre_TTCN_PDU_Constraint(const TTCN_PDU_Constraint& Me);

int main( int /* argc */, char **argv )
{
AccessSuite suite;

if( suite->open( argv[ 1 ] ) ) // OK open database?
{
// Setup the id writing functions
pre_TTCN_PDU_TypeDef = id_pre_TTCN_PDU_TypeDef;
pre_TTCN_PDU_Constraint = id_pre_TTCN_PDU_Constraint;

// Start traversing from root.
if( !suite->trav_root() )
return 1;

if( suite->close() ) // OK close database?
return 0;
else // Error close database!
return 2;
}

else // Error open database!
return -1;
}

void id_pre_TTCN_PDU_TypeDef(const TTCN_PDU_TypeDef& Me)
{
printf( "Identifier `%s' is a TTCN PDU type\n",
(const char*) Me->pdu_Id()->pdu_IdAndFullId()
->pdu_Identifier() );
}

void id_pre_TTCN_PDU_Constraint(const TTCN_PDU_Constraint& Me)
{
printf( "Identifier `%s' is a TTCN PDU constraint\n",
(const char*) Me->consId()->consIdAndParList()
->constraintIdentifier() );
}

Output

> print-ids ../Example_Suite_A.itex

Identifier `SEND' is a TTCN PDU type
Identifier `RECEIVE' is a TTCN PDU type
Identifier `S1' is a TTCN PDU constraint
Identifier `R1' is a TTCN PDU constraint
>

Solution 4

Code

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
void VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me );
void VisitPDU_FieldDcl( const PDU_FieldDcl& Me );
};

Astring get_type_str(const AccessNode& n);
Astring get_id(const AccessNode& n);

int main( int /* argc */, char **argv )
{
AccessSuite suite;

if( suite.open( argv[ 1 ] ) ) // OK open database?
{
Trav visitor;

visitor.Visit( suite );

if( suite.close() ) // OK close database?
return 0;
else // Error close database!
return 2;
}

else // Error open database!
return -1;
}

void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
// Generate the header part

cout << Me.pdu_Id( ) << "_encode( const ";
cout << Me.pdu_Id( ) << "& me, char* enc_buf )";
cout << "\n{" << endl;

// Traverse fields using default traverser

AccessVisitor::VisitPDU_FieldDcls( Me.pdu_FieldDcls( ) );

// Generate the footer part

cout << "}" << endl;
}

void Trav::VisitPDU_FieldDcl( const PDU_FieldDcl& Me )
{
printf( " %s %s;\n",
(const char*) get_type_str( Me.pdu_FieldType( ),
(const char*) get_id( Me.pdu_FieldId( ) );
}

// Help functions

Astring get_type_str(const AccessNode& n)
{
switch ( n.choice( ) )
{
case Choices::c_PDU_FieldType:
return n.PDU_FieldType().content();

default:
fprintf( stderr, "Bad case in get_type %d\n",
(int) n.choice( ) );
abort();
}
}

Astring get_id(const AccessNode& n)
{
switch ( n.choice( ) )
{
case Choices::c_PDU_FieldId:
if ( n.PDU_FieldId( ).pdu_FieldIdOrMacro( )
.choice( )
== Choices::c_MacroSymbol )
return n.PDU_FieldId( ).pdu_FieldIdOrMacro( )
.macroSymbol( );
else
return n.PDU_FieldId( ).pdu_FieldIdOrMacro( )
.pdu_FieldIdAndFullId( )
.pdu_FieldIdentifier( );

case Choices::c_PDU_Id:
return n.PDU_Id( ).pdu_IdAndFullId( )
.pdu_Identifier( );

default:
fprintf( stderr, "Bad case in get_id %d\n",
(int) n.choice( ) );
abort( );
}
}

Output

> ./pdu2c ../Example_Suite_A.itex

typedef struct {
INTEGER Field_1;
BOOLEAN Field_2;
} SEND;

typedef struct {
INTEGER Field_1;
BOOLEAN Field_2;
} RECEIVE;
>


24 The TTCN Access Class Reference Manual

This chapter contains the class definitions in TTCN Access.

The definitions are grouped into the following areas:

  • "Static and Table Nodes"
  • "Parse Tree Nodes"
  • "Terminal Nodes"


Static and Table Nodes

This section contains all static nodes and table nodes (that is those visible in the Browser) and also the nodes representing rows inside tables. Common for these nodes are that they are always present, there may be any number of them, but they are generally well defined and cannot just be missing.

AliasDef ::= SEQUENCE {

aliasId AliasId FIELD --See page 1026

expandedId ExpandedId FIELD --See page 1043

comment Comment FIELD --See page 1081

}

Referenced from: AliasDefList (p. 994)

AliasDefList ::= SEQUENCE OF {

aliasDef AliasDef --See page 994

}

Referenced from: AliasDefs (p. 994)

AliasDefs ::= SEQUENCE {

aliasDefList AliasDefList --See page 994

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ComplexDefinitions (p. 1003)

ASN1_ASP_Constraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

asp_Id ASP_Id FIELD --See page 1028

derivPath DerivPath FIELD --See page 1040

comment Comment FIELD --See page 1081

asn1_ConsValue ASN1_ConsValue FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_ASP_Constraints (p. 994)

ASN1_ASP_Constraints ::= SEQUENCE OF {

asn1_ASP_Constraint ASN1_ASP_Constraint --See page 994

}

Referenced from: ASP_Constraints (p. 999)

ASN1_ASP_TypeDef ::= SEQUENCE {

asp_Id ASP_Id FIELD --See page 1028

pco_Type PCO_Type FIELD --See page 1055

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_ASP_TypeDefs (p. 995)

ASN1_ASP_TypeDefByRef ::= SEQUENCE {

asp_Id ASP_Id FIELD --See page 1028

pco_Type PCO_Type FIELD --See page 1055

asn1_TypeReference ASN1_TypeReference FIELD --See page 1080

asn1_ModuleId ASN1_ModuleId FIELD --See page 1080

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

}

Referenced from: ASN1_ASP_TypeDefByRefList (p. 995)

ASN1_ASP_TypeDefByRefList ::= SEQUENCE OF {

asn1_ASP_TypeDefByRef ASN1_ASP_TypeDefByRef --See page 995

}

Referenced from: ASN1_ASP_TypeDefsByRef (p. 995)

ASN1_ASP_TypeDefs ::= SEQUENCE OF {

asn1_ASP_TypeDef ASN1_ASP_TypeDef --See page 995

}

Referenced from: ASP_TypeDefs (p. 1000)

ASN1_ASP_TypeDefsByRef ::= SEQUENCE {

asn1_ASP_TypeDefByRefList ASN1_ASP_TypeDefByRefList --See page 995

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASP_TypeDefs (p. 1000)

ASN1_CM_Constraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

cm_Id CM_Id FIELD --See page 1033

derivPath DerivPath FIELD --See page 1040

comment Comment FIELD --See page 1081

asn1_ConsValue ASN1_ConsValue FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_CM_Constraints (p. 996)

ASN1_CM_Constraints ::= SEQUENCE OF {

asn1_CM_Constraint ASN1_CM_Constraint --See page 996

}

Referenced from: CM_Constraints (p. 1001)

ASN1_CM_TypeDef ::= SEQUENCE {

cm_Id CM_Id FIELD --See page 1033

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_CM_TypeDefs (p. 996)

ASN1_CM_TypeDefs ::= SEQUENCE OF {

asn1_CM_TypeDef ASN1_CM_TypeDef --See page 996

}

Referenced from: CM_TypeDefs (p. 1002)

ASN1_PDU_Constraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

pdu_Id PDU_Id FIELD --See page 1056

derivPath DerivPath FIELD --See page 1040

encRuleId EncRuleId FIELD --See page 1042

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

asn1_ConsValue ASN1_ConsValue FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_PDU_Constraints (p. 997)

ASN1_PDU_Constraints ::= SEQUENCE OF {

asn1_PDU_Constraint ASN1_PDU_Constraint --See page 996

}

Referenced from: PDU_Constraints (p. 1010)

ASN1_PDU_TypeDef ::= SEQUENCE {

pdu_Id PDU_Id FIELD --See page 1056

pco_Type PCO_Type FIELD --See page 1055

pdu_EncodingId PDU_EncodingId FIELD --See page 1055

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_PDU_TypeDefs (p. 997)

ASN1_PDU_TypeDefByRef ::= SEQUENCE {

pdu_Id PDU_Id FIELD --See page 1056

pco_Type PCO_Type FIELD --See page 1055

asn1_TypeReference ASN1_TypeReference FIELD --See page 1080

asn1_ModuleId ASN1_ModuleId FIELD --See page 1080

pdu_EncodingId PDU_EncodingId FIELD --See page 1055

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

}

Referenced from: ASN1_PDU_TypeDefByRefList (p. 997)

ASN1_PDU_TypeDefByRefList ::= SEQUENCE OF {

asn1_PDU_TypeDefByRef ASN1_PDU_TypeDefByRef --See page 997

}

Referenced from: ASN1_PDU_TypeDefsByRef (p. 998)

ASN1_PDU_TypeDefs ::= SEQUENCE OF {

asn1_PDU_TypeDef ASN1_PDU_TypeDef --See page 997

}

Referenced from: PDU_TypeDefs (p. 1010)

ASN1_PDU_TypeDefsByRef ::= SEQUENCE {

asn1_PDU_TypeDefByRefList ASN1_PDU_TypeDefByRefList --See page 997

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: PDU_TypeDefs (p. 1010)

ASN1_TypeConstraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

asn1_TypeId ASN1_TypeId FIELD --See page 1028

derivPath DerivPath FIELD --See page 1040

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

asn1_ConsValue ASN1_ConsValue FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_TypeConstraints (p. 998)

ASN1_TypeConstraints ::= SEQUENCE OF {

asn1_TypeConstraint ASN1_TypeConstraint --See page 998

}

Referenced from: TS_TypeConstraints (p. 1021)

ASN1_TypeDef ::= SEQUENCE {

asn1_TypeId ASN1_TypeId FIELD --See page 1028

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ASN1_TypeDefs (p. 998)

ASN1_TypeDefs ::= SEQUENCE OF {

asn1_TypeDef ASN1_TypeDef --See page 998

}

Referenced from: TS_TypeDefs (p. 1021)

ASN1_TypeRef ::= SEQUENCE {

asn1_TypeId ASN1_TypeId FIELD --See page 1028

asn1_TypeReference ASN1_TypeReference FIELD --See page 1080

asn1_ModuleId ASN1_ModuleId FIELD --See page 1080

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

asn1_TypeDefinition ASN1_TypeDefinition FIELD --See page 1027

}

Referenced from: ASN1_TypeRefList (p. 999)

ASN1_TypeRefList ::= SEQUENCE OF {

asn1_TypeRef ASN1_TypeRef --See page 999

}

Referenced from: ASN1_TypeRefs (p. 999)

ASN1_TypeRefs ::= SEQUENCE {

asn1_TypeRefList ASN1_TypeRefList --See page 999

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TS_TypeDefs (p. 1021)

ASP_Constraints ::= SEQUENCE {

ttcn_ASP_Constraints TTCN_ASP_Constraints --See page 1022

asn1_ASP_Constraints ASN1_ASP_Constraints --See page 994

}

Referenced from: ConstraintsPart (p. 1003)

ASP_ParDcl ::= SEQUENCE {

asp_ParId ASP_ParId FIELD --See page 1029

asp_ParType ASP_ParType FIELD --See page 1029

comment Comment FIELD --See page 1081

}

Referenced from: ASP_ParDcls (p. 999)

ASP_ParDcls ::= SEQUENCE OF {

asp_ParDcl ASP_ParDcl --See page 999

}

Referenced from: TTCN_ASP_TypeDef (p. 1023)

ASP_ParValue ::= SEQUENCE {

asp_ParId ASP_ParId FIELD --See page 1029

consValue ConsValue FIELD --See page 1036

comment Comment FIELD --See page 1081

}

Referenced from: ASP_ParValues (p. 1000)

ASP_ParValues ::= SEQUENCE OF {

asp_ParValue ASP_ParValue --See page 1000

}

Referenced from: TTCN_ASP_Constraint (p. 1022)

ASP_TypeDefs ::= SEQUENCE {

ttcn_ASP_TypeDefs TTCN_ASP_TypeDefs --See page 1023

asn1_ASP_TypeDefs ASN1_ASP_TypeDefs --See page 995

asn1_ASP_TypeDefsByRef ASN1_ASP_TypeDefsByRef --See page 995

}

Referenced from: ComplexDefinitions (p. 1003)

ASuite ::= SEQUENCE {

suiteId SuiteId FIELD --See page 1067

suiteOverviewPart SuiteOverviewPart --See page 1014

declarationsPart DeclarationsPart --See page 1004

constraintsPart ConstraintsPart --See page 1003

dynamicPart DynamicPart --See page 1006

}

BehaviourDescription ::= SEQUENCE {

rootTree RootTree --See page 1011

localTreeList LocalTreeList --See page 1008

}

Referenced from: TestCase (p. 1016) TestStep (p. 1017) DefaultCase (p. 1004)

BehaviourLine ::= SEQUENCE {

lineNumber LineNumber FIELD --See page 1047

labelId LabelId FIELD --See page 1047

line Line FIELD --See page 1047

cref Cref FIELD --See page 1038

verdictId VerdictId FIELD --See page 1078

comment Comment FIELD --See page 1081

children Children --See page 1001

}

Referenced from: RootTree (p. 1011) BehaviourLineList (p. 1001) Children (p. 1001)

BehaviourLineList ::= SEQUENCE OF {

behaviourLine BehaviourLine --See page 1001

}

Referenced from: LocalTree (p. 1008)

Children ::= SEQUENCE OF {

behaviourLine BehaviourLine --See page 1001

}

Referenced from: BehaviourLine (p. 1001)

CM_Constraints ::= SEQUENCE {

ttcn_CM_Constraints TTCN_CM_Constraints --See page 1023

asn1_CM_Constraints ASN1_CM_Constraints --See page 996

}

Referenced from: ConstraintsPart (p. 1003)

CM_ParDcl ::= SEQUENCE {

cm_ParId CM_ParId FIELD --See page 1033

cm_ParType CM_ParType FIELD --See page 1033

comment Comment FIELD --See page 1081

}

Referenced from: CM_ParDcls (p. 1001)

CM_ParDcls ::= SEQUENCE OF {

cm_ParDcl CM_ParDcl --See page 1001

}

Referenced from: TTCN_CM_TypeDef (p. 1023)

CM_ParValue ::= SEQUENCE {

cm_ParId CM_ParId FIELD --See page 1033

consValue ConsValue FIELD --See page 1036

comment Comment FIELD --See page 1081

}

Referenced from: CM_ParValues (p. 1002)

CM_ParValues ::= SEQUENCE OF {

cm_ParValue CM_ParValue --See page 1002

}

Referenced from: TTCN_CM_Constraint (p. 1023)

CM_TypeDefs ::= SEQUENCE {

ttcn_CM_TypeDefs TTCN_CM_TypeDefs --See page 1024

asn1_CM_TypeDefs ASN1_CM_TypeDefs --See page 996

}

Referenced from: ComplexDefinitions (p. 1003)

CompactTestCase ::= SEQUENCE {

testCaseId TestCaseId FIELD --See page 1069

testPurpose TestPurpose FIELD --See page 1091

testStepAttachment TestStepAttachment FIELD --See page 1069

comment Comment FIELD --See page 1081

selExprId SelExprId FIELD --See page 1062

description Description FIELD --See page 1081

}

Referenced from: CompactTestCaseList (p. 1002)

CompactTestCaseList ::= SEQUENCE OF {

compactTestCase CompactTestCase --See page 1002

}

Referenced from: CompactTestGroup (p. 1003)

CompactTestGroup ::= SEQUENCE {

testGroupId TestGroupId FIELD --See page 1069

defaultsRef DefaultsRef FIELD --See page 1039

selExprId SelExprId OPTIONAL --See page 1062

objective Objective OPTIONAL --See page 1088

compactTestCaseList CompactTestCaseList --See page 1002

}

Referenced from: TestGroupOrTestCase (p. 1017)

ComplexDefinitions ::= SEQUENCE {

asp_TypeDefs ASP_TypeDefs --See page 1000

pdu_TypeDefs PDU_TypeDefs --See page 1010

cm_TypeDefs CM_TypeDefs --See page 1002

aliasDefs AliasDefs --See page 994

}

Referenced from: DeclarationsPart (p. 1004)

ConstraintsPart ::= SEQUENCE {

ts_TypeConstraints TS_TypeConstraints --See page 1021

asp_Constraints ASP_Constraints --See page 999

pdu_Constraints PDU_Constraints --See page 1010

cm_Constraints CM_Constraints --See page 1001

}

Referenced from: ASuite (p. 1000)

CP_Dcl ::= SEQUENCE {

cp_Id CP_Id FIELD --See page 1037

comment Comment FIELD --See page 1081

}

Referenced from: CP_DclList (p. 1003)

CP_DclList ::= SEQUENCE OF {

cp_Dcl CP_Dcl --See page 1003

}

Referenced from: CP_Dcls (p. 1004)

CP_Dcls ::= SEQUENCE {

cp_DclList CP_DclList --See page 1003

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

Declarations ::= SEQUENCE {

ts_ConstDcls TS_ConstDcls --See page 1019

ts_ConstRefs TS_ConstRefs --See page 1020

ts_VarDcls TS_VarDcls --See page 1022

tc_VarDcls TC_VarDcls --See page 1015

pco_TypeDcls PCO_TypeDcls --See page 1009

pco_Dcls PCO_Dcls --See page 1009

cp_Dcls CP_Dcls --See page 1004

timerDcls TimerDcls --See page 1019

tcompDcls TCompDcls --See page 1016

tcompConfigDcls TCompConfigDcls --See page 1015

}

Referenced from: DeclarationsPart (p. 1004)

DeclarationsPart ::= SEQUENCE {

definitions Definitions --See page 1005

paramAndSelection ParamAndSelection --See page 1008

declarations Declarations --See page 1004

complexDefinitions ComplexDefinitions --See page 1003

}

Referenced from: ASuite (p. 1000)

DefaultCase ::= SEQUENCE {

defaultId DefaultId FIELD --See page 1038

defaultRef DefaultRef FIELD --See page 1039

objective Objective FIELD --See page 1088

comment Comment FIELD --See page 1081

description Description FIELD --See page 1081

behaviourDescription BehaviourDescription --See page 1000

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: DefaultGroupOrDefault (p. 1005)

DefaultGroup ::= SEQUENCE {

defaultGroupId DefaultGroupId FIELD --See page 1038

defaultGroupOrDefaultList DefaultGroupOrDefaultList --See page 1005

}

Referenced from: DefaultGroupOrDefault (p. 1005)

DefaultGroupOrDefault ::= CHOICE {

defaultGroup DefaultGroup --See page 1005

defaultCase DefaultCase --See page 1004

}

Referenced from: DefaultGroupOrDefaultList (p. 1005)

DefaultGroupOrDefaultList ::= SEQUENCE OF {

defaultGroupOrDefault DefaultGroupOrDefault --See page 1005

}

Referenced from: DefaultsLibrary (p. 1005) DefaultGroup (p. 1005)

DefaultIndex ::= SEQUENCE {

SO_defIndexList SO_DefIndexList --See page 1012

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: SuiteOverviewPart (p. 1014)

DefaultsLibrary ::= SEQUENCE {

defaultGroupOrDefaultList DefaultGroupOrDefaultList --See page 1005

}

Referenced from: DynamicPart (p. 1006)

Definitions ::= SEQUENCE {

ts_TypeDefs TS_TypeDefs --See page 1021

encodingDefs EncodingDefs --See page 1007

ts_OpDefs TS_OpDefs --See page 1020

ts_ProcDefs TS_ProcDefs --See page 1021

}

Referenced from: DeclarationsPart (p. 1004)

DynamicPart ::= SEQUENCE {

testCases TestCases --See page 1017

testStepLibrary TestStepLibrary --See page 1018

defaultsLibrary DefaultsLibrary --See page 1005

}

Referenced from: ASuite (p. 1000)

ElemDcl ::= SEQUENCE {

elemId ElemId FIELD --See page 1041

elemType ElemType FIELD --See page 1041

pdu_FieldEncoding PDU_FieldEncoding FIELD --See page 1055

comment Comment FIELD --See page 1081

}

Referenced from: ElemDcls (p. 1006)

ElemDcls ::= SEQUENCE OF {

elemDcl ElemDcl --See page 1006

}

Referenced from: StructTypeDef (p. 1014)

ElemValue ::= SEQUENCE {

elemId ElemId FIELD --See page 1041

consValue ConsValue FIELD --See page 1036

comment Comment FIELD --See page 1081

}

Referenced from: ElemValues (p. 1006)

ElemValues ::= SEQUENCE OF {

elemValue ElemValue --See page 1006

}

Referenced from: StructTypeConstraint (p. 1013)

EncodingDefinition ::= SEQUENCE {

encodingRuleId EncodingRuleId FIELD --See page 1041

encodingRef EncodingRef FIELD --See page 1041

encodingDefault EncodingDefault OPTIONAL --See page 1041

comment Comment FIELD --See page 1081

}

Referenced from: EncodingDefList (p. 1007)

EncodingDefinitions ::= SEQUENCE {

encodingDefList EncodingDefList --See page 1007

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: EncodingDefs (p. 1007)

EncodingDefList ::= SEQUENCE OF {

encodingDefinition EncodingDefinition --See page 1006

}

Referenced from: EncodingDefinitions (p. 1007)

EncodingDefs ::= SEQUENCE {

encodingDefinitions EncodingDefinitions --See page 1007

encodingVariations EncodingVariations --See page 1007

invalidFieldEncodingDefs InvalidFieldEncodingDefs --See page 1008

}

Referenced from: Definitions (p. 1005)

EncodingVariation ::= SEQUENCE {

encodingVariationId EncodingVariationId FIELD --See page 1041

variationRef VariationRef FIELD --See page 1077

variationDefault VariationDefault OPTIONAL --See page 1077

comment Comment FIELD --See page 1081

}

Referenced from: EncodingVariationList (p. 1007)

EncodingVariationList ::= SEQUENCE OF {

encodingVariation EncodingVariation --See page 1007

}

Referenced from: EncodingVariationSet (p. 1008)

EncodingVariations ::= SEQUENCE OF {

encodingVariationSet EncodingVariationSet --See page 1008

}

Referenced from: EncodingDefs (p. 1007)

EncodingVariationSet ::= SEQUENCE {

encodingRuleId EncodingRuleId FIELD --See page 1041

encoding_TypeList Encoding_TypeList FIELD --See page 1082

comment Comment FIELD --See page 1081

encodingVariationList EncodingVariationList --See page 1007

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: EncodingVariations (p. 1007)

InvalidFieldEncodingDef ::= SEQUENCE {

invalidFieldEncodingId InvalidFieldEncodingId FIELD --See page 1046

encoding_TypeList Encoding_TypeList FIELD --See page 1082

comment Comment FIELD --See page 1081

invalidFieldEncodingDefinition InvalidFieldEncodingDefinition FIELD --See page 1085

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: InvalidFieldEncodingDefs (p. 1008)

InvalidFieldEncodingDefs ::= SEQUENCE OF {

invalidFieldEncodingDef InvalidFieldEncodingDef --See page 1008

}

Referenced from: EncodingDefs (p. 1007)

LocalTree ::= SEQUENCE {

header Header FIELD --See page 1045

behaviourLineList BehaviourLineList --See page 1001

}

Referenced from: LocalTreeList (p. 1008)

LocalTreeList ::= SEQUENCE OF {

localTree LocalTree --See page 1008

}

Referenced from: BehaviourDescription (p. 1000)

ParamAndSelection ::= SEQUENCE {

ts_ParDcls TS_ParDcls --See page 1021

selectExprDefs SelectExprDefs --See page 1011

}

Referenced from: DeclarationsPart (p. 1004)

PCO_Dcl ::= SEQUENCE {

pco_Id PCO_Id FIELD --See page 1054

pco_TypeId PCO_TypeId FIELD --See page 1055

p_Role P_Role FIELD --See page 1053

comment Comment FIELD --See page 1081

}

Referenced from: PCO_DclList (p. 1009)

PCO_DclList ::= SEQUENCE OF {

pco_Dcl PCO_Dcl --See page 1009

}

Referenced from: PCO_Dcls (p. 1009)

PCO_Dcls ::= SEQUENCE {

pco_DclList PCO_DclList --See page 1009

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

PCO_TypeDcl ::= SEQUENCE {

pco_TypeId PCO_TypeId FIELD --See page 1055

p_Role P_Role FIELD --See page 1053

comment Comment FIELD --See page 1081

}

Referenced from: PCO_TypeDclList (p. 1009)

PCO_TypeDclList ::= SEQUENCE OF {

pco_TypeDcl PCO_TypeDcl --See page 1009

}

Referenced from: PCO_TypeDcls (p. 1009)

PCO_TypeDcls ::= SEQUENCE {

pco_TypeDclList PCO_TypeDclList --See page 1009

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

PDU_Constraints ::= SEQUENCE {

ttcn_PDU_Constraints TTCN_PDU_Constraints --See page 1024

asn1_PDU_Constraints ASN1_PDU_Constraints --See page 997

}

Referenced from: ConstraintsPart (p. 1003)

PDU_FieldDcl ::= SEQUENCE {

pdu_FieldId PDU_FieldId FIELD --See page 1056

pdu_FieldType PDU_FieldType FIELD --See page 1056

pdu_FieldEncoding PDU_FieldEncoding FIELD --See page 1055

comment Comment FIELD --See page 1081

}

Referenced from: PDU_FieldDcls (p. 1010)

PDU_FieldDcls ::= SEQUENCE OF {

pdu_FieldDcl PDU_FieldDcl --See page 1010

}

Referenced from: TTCN_PDU_TypeDef (p. 1024)

PDU_FieldValue ::= SEQUENCE {

pdu_FieldId PDU_FieldId FIELD --See page 1056

consValue ConsValue FIELD --See page 1036

pdu_FieldEncoding PDU_FieldEncoding FIELD --See page 1055

comment Comment FIELD --See page 1081

}

Referenced from: PDU_FieldValues (p. 1010)

PDU_FieldValues ::= SEQUENCE OF {

pdu_FieldValue PDU_FieldValue --See page 1010

}

Referenced from: TTCN_PDU_Constraint (p. 1024)

PDU_TypeDefs ::= SEQUENCE {

ttcn_PDU_TypeDefs TTCN_PDU_TypeDefs --See page 1024

asn1_PDU_TypeDefs ASN1_PDU_TypeDefs --See page 997

asn1_PDU_TypeDefsByRef ASN1_PDU_TypeDefsByRef --See page 998

}

Referenced from: ComplexDefinitions (p. 1003)

RootTree ::= SEQUENCE OF {

behaviourLine BehaviourLine --See page 1001

}

Referenced from: BehaviourDescription (p. 1000)

SelectExprDef ::= SEQUENCE {

selectExprId SelectExprId FIELD --See page 1061

selectExpr SelectExpr FIELD --See page 1061

comment Comment FIELD --See page 1081

}

Referenced from: SelectExprDefList (p. 1011)

SelectExprDefList ::= SEQUENCE OF {

selectExprDef SelectExprDef --See page 1011

}

Referenced from: SelectExprDefs (p. 1011)

SelectExprDefs ::= SEQUENCE {

selectExprDefList SelectExprDefList --See page 1011

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ParamAndSelection (p. 1008)

SimpleTypeDef ::= SEQUENCE {

simpleTypeId SimpleTypeId FIELD --See page 1064

simpleTypeDefinition SimpleTypeDefinition FIELD --See page 1064

pdu_FieldEncoding PDU_FieldEncoding FIELD --See page 1055

comment Comment FIELD --See page 1081

}

Referenced from: SimpleTypeDefList (p. 1011)

SimpleTypeDefList ::= SEQUENCE OF {

simpleTypeDef SimpleTypeDef --See page 1011

}

Referenced from: SimpleTypeDefs (p. 1012)

SimpleTypeDefs ::= SEQUENCE {

simpleTypeDefList SimpleTypeDefList --See page 1011

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TS_TypeDefs (p. 1021)

SO_CaseIndex ::= SEQUENCE {

SO_testGroupRef SO_TestGroupRef FIELD --See page 1091

SO_testCaseId SO_TestCaseId FIELD --See page 1091

SO_selExprId SO_SelExprId FIELD --See page 1090

SO_description SO_Description FIELD --See page 1090

}

Referenced from: SO_CaseIndexList (p. 1012)

SO_CaseIndexList ::= SEQUENCE OF {

SO_caseIndex SO_CaseIndex --See page 1012

}

Referenced from: TestCaseIndex (p. 1016)

SO_DefIndex ::= SEQUENCE {

SO_defaultRef SO_DefaultRef FIELD --See page 1090

SO_defaultId SO_DefaultId FIELD --See page 1090

SO_description SO_Description FIELD --See page 1090

}

Referenced from: SO_DefIndexList (p. 1012)

SO_DefIndexList ::= SEQUENCE OF {

SO_defIndex SO_DefIndex --See page 1012

}

Referenced from: DefaultIndex (p. 1005)

SO_StepIndex ::= SEQUENCE {

SO_testStepRef SO_TestStepRef FIELD --See page 1091

SO_testStepId SO_TestStepId FIELD --See page 1091

SO_description SO_Description FIELD --See page 1090

}

Referenced from: SO_StepIndexList (p. 1013)

SO_StepIndexList ::= SEQUENCE OF {

SO_stepIndex SO_StepIndex --See page 1012

}

Referenced from: TestStepIndex (p. 1018)

SO_StructureAndObjective ::= SEQUENCE {

SO_testGroupRef SO_TestGroupRef FIELD --See page 1091

SO_selExprId SO_SelExprId FIELD --See page 1090

SO_objective SO_Objective FIELD --See page 1090

}

Referenced from: SO_StructureAndObjectives (p. 1013)

SO_StructureAndObjectives ::= SEQUENCE OF {

SO_structureAndObjective SO_StructureAndObjective --See page 1013

}

Referenced from: SuiteStructure (p. 1014)

StructTypeConstraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

structId StructId FIELD --See page 1066

derivPath DerivPath FIELD --See page 1040

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

elemValues ElemValues --See page 1006

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: StructTypeConstraints (p. 1013)

StructTypeConstraints ::= SEQUENCE OF {

structTypeConstraint StructTypeConstraint --See page 1013

}

Referenced from: TS_TypeConstraints (p. 1021)

StructTypeDef ::= SEQUENCE {

structId StructId FIELD --See page 1066

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

elemDcls ElemDcls --See page 1006

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: StructTypeDefs (p. 1014)

StructTypeDefs ::= SEQUENCE OF {

structTypeDef StructTypeDef --See page 1014

}

Referenced from: TS_TypeDefs (p. 1021)

SuiteOverviewPart ::= SEQUENCE {

suiteStructure SuiteStructure --See page 1014

testCaseIndex TestCaseIndex --See page 1016

testStepIndex TestStepIndex --See page 1018

defaultIndex DefaultIndex --See page 1005

}

Referenced from: ASuite (p. 1000)

SuiteStructure ::= SEQUENCE {

SO_suiteId SO_SuiteId FIELD --See page 1065

SO_standardsRef SO_StandardsRef FIELD --See page 1091

SO_picsRef SO_PICSRef FIELD --See page 1090

SO_pixitRef SO_PIXITRef FIELD --See page 1090

SO_testMethods SO_TestMethods FIELD --See page 1091

comment Comment FIELD --See page 1081

SO_structureAndObjectives SO_StructureAndObjectives --See page 1013

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: SuiteOverviewPart (p. 1014)

TC_VarDcl ::= SEQUENCE {

tc_VarId TC_VarId FIELD --See page 1067

tc_VarType TC_VarType FIELD --See page 1068

tc_VarValue TC_VarValue FIELD --See page 1068

comment Comment FIELD --See page 1081

}

Referenced from: TC_VarDclList (p. 1015)

TC_VarDclList ::= SEQUENCE OF {

tc_VarDcl TC_VarDcl --See page 1014

}

Referenced from: TC_VarDcls (p. 1015)

TC_VarDcls ::= SEQUENCE {

tc_VarDclList TC_VarDclList --See page 1015

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

TCompConfigDcl ::= SEQUENCE {

tcompConfigId TCompConfigId FIELD --See page 1068

comment Comment FIELD --See page 1081

tcompConfigInfoList TCompConfigInfoList --See page 1015

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TCompConfigDcls (p. 1015)

TCompConfigDcls ::= SEQUENCE OF {

tcompConfigDcl TCompConfigDcl --See page 1015

}

Referenced from: Declarations (p. 1004)

TCompConfigInfo ::= SEQUENCE {

tcompUsed TCompUsed FIELD --See page 1068

pcos_Used PCOs_Used FIELD --See page 1055

cps_Used CPs_Used FIELD --See page 1037

comment Comment FIELD --See page 1081

}

Referenced from: TCompConfigInfoList (p. 1015)

TCompConfigInfoList ::= SEQUENCE OF {

tcompConfigInfo TCompConfigInfo --See page 1015

}

Referenced from: TCompConfigDcl (p. 1015)

TCompDcl ::= SEQUENCE {

tcompId TCompId FIELD --See page 1068

tc_Role TC_Role FIELD --See page 1067

numOf_PCOs NumOf_PCOs FIELD --See page 1052

numOf_CPs NumOf_CPs FIELD --See page 1052

comment Comment FIELD --See page 1081

}

Referenced from: TCompDclList (p. 1016)

TCompDclList ::= SEQUENCE OF {

tcompDcl TCompDcl --See page 1016

}

Referenced from: TCompDcls (p. 1016)

TCompDcls ::= SEQUENCE {

tcompDclList TCompDclList --See page 1016

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

TestCase ::= SEQUENCE {

testCaseId TestCaseId FIELD --See page 1069

testGroupRef TestGroupRef FIELD --See page 1069

testPurpose TestPurpose FIELD --See page 1091

configuration Configuration OPTIONAL --See page 1034

defaultsRef DefaultsRef OPTIONAL --See page 1039

comment Comment FIELD --See page 1081

selExprId SelExprId FIELD --See page 1062

description Description FIELD --See page 1081

behaviourDescription BehaviourDescription --See page 1000

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TestGroupOrTestCase (p. 1017)

TestCaseIndex ::= SEQUENCE {

SO_caseIndexList SO_CaseIndexList --See page 1012

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: SuiteOverviewPart (p. 1014)

TestCases ::= SEQUENCE {

testGroupOrTestCaseList TestGroupOrTestCaseList --See page 1017

}

Referenced from: DynamicPart (p. 1006)

TestGroup ::= SEQUENCE {

testGroupId TestGroupId FIELD --See page 1069

selExprId SelExprId OPTIONAL --See page 1062

objective Objective OPTIONAL --See page 1088

testGroupOrTestCaseList TestGroupOrTestCaseList --See page 1017

}

Referenced from: TestGroupOrTestCase (p. 1017)

TestGroupOrTestCase ::= CHOICE {

testGroup TestGroup --See page 1017

testCase TestCase --See page 1016

compactTestGroup CompactTestGroup --See page 1003

}

Referenced from: TestGroupOrTestCaseList (p. 1017)

TestGroupOrTestCaseList ::= SEQUENCE OF {

testGroupOrTestCase TestGroupOrTestCase --See page 1017

}

Referenced from: TestCases (p. 1017) TestGroup (p. 1017)

TestStep ::= SEQUENCE {

testStepId TestStepId FIELD --See page 1069

testStepRef TestStepRef FIELD --See page 1070

objective Objective FIELD --See page 1088

defaultsRef DefaultsRef FIELD --See page 1039

comment Comment FIELD --See page 1081

description Description FIELD --See page 1081

behaviourDescription BehaviourDescription --See page 1000

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TestStepGroupOrTestStep (p. 1018)

TestStepGroup ::= SEQUENCE {

testStepGroupId TestStepGroupId FIELD --See page 1069

testStepGroupOrTestStepList TestStepGroupOrTestStepList --See page 1018

}

Referenced from: TestStepGroupOrTestStep (p. 1018)

TestStepGroupOrTestStep ::= CHOICE {

testStepGroup TestStepGroup --See page 1018

testStep TestStep --See page 1017

}

Referenced from: TestStepGroupOrTestStepList (p. 1018)

TestStepGroupOrTestStepList ::= SEQUENCE OF {

testStepGroupOrTestStep TestStepGroupOrTestStep --See page 1018

}

Referenced from: TestStepLibrary (p. 1018) TestStepGroup (p. 1018)

TestStepIndex ::= SEQUENCE {

SO_stepIndexList SO_StepIndexList --See page 1013

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: SuiteOverviewPart (p. 1014)

TestStepLibrary ::= SEQUENCE {

testStepGroupOrTestStepList TestStepGroupOrTestStepList --See page 1018

}

Referenced from: DynamicPart (p. 1006)

TimerDcl ::= SEQUENCE {

timerId TimerId FIELD --See page 1070

duration Duration FIELD --See page 1040

unit Unit FIELD --See page 1075

comment Comment FIELD --See page 1081

}

Referenced from: TimerDclList (p. 1019)

TimerDclList ::= SEQUENCE OF {

timerDcl TimerDcl --See page 1018

}

Referenced from: TimerDcls (p. 1019)

TimerDcls ::= SEQUENCE {

timerDclList TimerDclList --See page 1019

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

TS_ConstDcl ::= SEQUENCE {

ts_ConstId TS_ConstId FIELD --See page 1071

ts_ConstType TS_ConstType FIELD --See page 1071

ts_ConstValue TS_ConstValue FIELD --See page 1071

comment Comment FIELD --See page 1081

}

Referenced from: TS_ConstDclList (p. 1019)

TS_ConstDclList ::= SEQUENCE OF {

ts_ConstDcl TS_ConstDcl --See page 1019

}

Referenced from: TS_ConstDcls (p. 1019)

TS_ConstDcls ::= SEQUENCE {

ts_ConstDclList TS_ConstDclList --See page 1019

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

TS_ConstRef ::= SEQUENCE {

ts_ConstId TS_ConstId FIELD --See page 1071

ts_ConstType TS_ConstType FIELD --See page 1071

asn1_ValueReference ASN1_ValueReference FIELD --See page 1080

asn1_ModuleId ASN1_ModuleId FIELD --See page 1080

comment Comment FIELD --See page 1081

ts_ConstValue TS_ConstValue OPTIONAL --See page 1071

}

Referenced from: TS_ConstRefList (p. 1020)

TS_ConstRefList ::= SEQUENCE OF {

ts_ConstRef TS_ConstRef --See page 1019

}

Referenced from: TS_ConstRefs (p. 1020)

TS_ConstRefs ::= SEQUENCE {

ts_ConstRefList TS_ConstRefList --See page 1020

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

TS_OpDef ::= SEQUENCE {

ts_OpId TS_OpId FIELD --See page 1072

ts_OpResult TS_OpResult FIELD --See page 1072

comment Comment FIELD --See page 1081

ts_OpDescription TS_OpDescription FIELD --See page 1092

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TS_OpDefs (p. 1020)

TS_OpDefs ::= SEQUENCE OF {

ts_OpDef TS_OpDef --See page 1020

}

Referenced from: Definitions (p. 1005)

TS_ParDcl ::= SEQUENCE {

ts_ParId TS_ParId FIELD --See page 1072

ts_ParType TS_ParType FIELD --See page 1072

pics_PIXITref PICS_PIXITref FIELD --See page 1089

comment Comment FIELD --See page 1081

}

Referenced from: TS_ParDclList (p. 1020)

TS_ParDclList ::= SEQUENCE OF {

ts_ParDcl TS_ParDcl --See page 1020

}

Referenced from: TS_ParDcls (p. 1021)

TS_ParDcls ::= SEQUENCE {

ts_ParDclList TS_ParDclList --See page 1020

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: ParamAndSelection (p. 1008)

TS_ProcDef ::= SEQUENCE {

ts_ProcId TS_ProcId FIELD --See page 1072

ts_ProcResult TS_ProcResult FIELD --See page 1073

comment Comment FIELD --See page 1081

ts_ProcDescription TS_ProcDescription FIELD --See page 1092

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TS_ProcDefs (p. 1021)

TS_ProcDefs ::= SEQUENCE OF {

ts_ProcDef TS_ProcDef --See page 1021

}

Referenced from: Definitions (p. 1005)

TS_TypeConstraints ::= SEQUENCE {

structTypeConstraints StructTypeConstraints --See page 1013

asn1_TypeConstraints ASN1_TypeConstraints --See page 998

}

Referenced from: ConstraintsPart (p. 1003)

TS_TypeDefs ::= SEQUENCE {

simpleTypeDefs SimpleTypeDefs --See page 1012

structTypeDefs StructTypeDefs --See page 1014

asn1_TypeDefs ASN1_TypeDefs --See page 998

asn1_TypeRefs ASN1_TypeRefs --See page 999

}

Referenced from: Definitions (p. 1005)

TS_VarDcl ::= SEQUENCE {

ts_VarId TS_VarId FIELD --See page 1073

ts_VarType TS_VarType FIELD --See page 1073

ts_VarValue TS_VarValue OPTIONAL --See page 1073

comment Comment FIELD --See page 1081

}

Referenced from: TS_VarDclList (p. 1022)

TS_VarDclList ::= SEQUENCE OF {

ts_VarDcl TS_VarDcl --See page 1022

}

Referenced from: TS_VarDcls (p. 1022)

TS_VarDcls ::= SEQUENCE {

ts_VarDclList TS_VarDclList --See page 1022

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: Declarations (p. 1004)

TTCN_ASP_Constraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

asp_Id ASP_Id FIELD --See page 1028

derivPath DerivPath FIELD --See page 1040

comment Comment FIELD --See page 1081

asp_ParValues ASP_ParValues --See page 1000

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TTCN_ASP_Constraints (p. 1022)

TTCN_ASP_Constraints ::= SEQUENCE OF {

ttcn_ASP_Constraint TTCN_ASP_Constraint --See page 1022

}

Referenced from: ASP_Constraints (p. 999)

TTCN_ASP_TypeDef ::= SEQUENCE {

asp_Id ASP_Id FIELD --See page 1028

pco_Type PCO_Type FIELD --See page 1055

comment Comment FIELD --See page 1081

asp_ParDcls ASP_ParDcls --See page 999

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TTCN_ASP_TypeDefs (p. 1023)

TTCN_ASP_TypeDefs ::= SEQUENCE OF {

ttcn_ASP_TypeDef TTCN_ASP_TypeDef --See page 1023

}

Referenced from: ASP_TypeDefs (p. 1000)

TTCN_CM_Constraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

cm_Id CM_Id FIELD --See page 1033

derivPath DerivPath FIELD --See page 1040

comment Comment FIELD --See page 1081

cm_ParValues CM_ParValues --See page 1002

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TTCN_CM_Constraints (p. 1023)

TTCN_CM_Constraints ::= SEQUENCE OF {

ttcn_CM_Constraint TTCN_CM_Constraint --See page 1023

}

Referenced from: CM_Constraints (p. 1001)

TTCN_CM_TypeDef ::= SEQUENCE {

cm_Id CM_Id FIELD --See page 1033

comment Comment FIELD --See page 1081

cm_ParDcls CM_ParDcls --See page 1001

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TTCN_CM_TypeDefs (p. 1024)

TTCN_CM_TypeDefs ::= SEQUENCE OF {

ttcn_CM_TypeDef TTCN_CM_TypeDef --See page 1023

}

Referenced from: CM_TypeDefs (p. 1002)

TTCN_PDU_Constraint ::= SEQUENCE {

consId ConsId FIELD --See page 1034

pdu_Id PDU_Id FIELD --See page 1056

derivPath DerivPath FIELD --See page 1040

encRuleId EncRuleId FIELD --See page 1042

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

pdu_FieldValues PDU_FieldValues --See page 1010

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TTCN_PDU_Constraints (p. 1024)

TTCN_PDU_Constraints ::= SEQUENCE OF {

ttcn_PDU_Constraint TTCN_PDU_Constraint --See page 1024

}

Referenced from: PDU_Constraints (p. 1010)

TTCN_PDU_TypeDef ::= SEQUENCE {

pdu_Id PDU_Id FIELD --See page 1056

pco_Type PCO_Type FIELD --See page 1055

pdu_EncodingId PDU_EncodingId FIELD --See page 1055

encVariationId EncVariationId FIELD --See page 1042

comment Comment FIELD --See page 1081

pdu_FieldDcls PDU_FieldDcls --See page 1010

detailedComment DetailedComment FIELD --See page 1082

}

Referenced from: TTCN_PDU_TypeDefs (p. 1024)

TTCN_PDU_TypeDefs ::= SEQUENCE OF {

ttcn_PDU_TypeDef TTCN_PDU_TypeDef --See page 1024

}

Referenced from: PDU_TypeDefs (p. 1010)


Parse Tree Nodes

This section contains all nodes within the Parse Trees. The Parse Trees are the output of the Analyzer, and they are a representation of whatever code the Test Suite writer put into the fields. Being user written, this part is much less well behaved than, say, the Static part, nodes may or may not be present, fields may or may not be well analyzed and some nodes have different children in different places in the Parse Tree (choices). All this is well specified however, using the mechanisms of is_present, is_analyzed (for tables) and the choice member function, but it is up to the user of TTCN Access to be aware of these constructs.

Activate ::= SEQUENCE {

defaultRefList DefaultRefList --See page 1039

}

Referenced from: Construct (p. 1036)

ActualCrefParList ::= SEQUENCE OF {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: ConsRef (p. 1035)

ActualParList ::= SEQUENCE OF {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: EncVariationCall (p. 1042) InvalidFieldEncodingCall (p. 1046) DefaultReference (p. 1039) Attach (p. 1029) CreateAttach (p. 1037) OpCall (p. 1053)

AddExpression ::= SEQUENCE {

simpleExpression SimpleExpression --See page 1063

addOp AddOp --See page 1025

term Term --See page 1069

}

Referenced from: SimpleExpression (p. 1063)

AddOp ::= CHOICE {

plus Plus --See page 1089

minus Minus --See page 1086

or Or --See page 1088

}

Referenced from: AddExpression (p. 1025)

AliasId ::= SEQUENCE {

aliasIdentifier Identifier --See page 1084

}

Referenced from: AliasDef (p. 994)

AlternativeTypeList ::= SEQUENCE OF {

namedType NamedType --See page 1051

}

Referenced from: ChoiceType (p. 1032)

AnyDefinedBy ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: AnyType (p. 1026)

AnyType ::= CHOICE {

any ANY --See page 1079

anyDefinedBy AnyDefinedBy --See page 1026

}

Referenced from: BuiltinType (p. 1031)

AnyValue ::= SEQUENCE {

referenceType ReferenceType --See page 1059

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: ASN1_Value (p. 1028)

ArrayRef ::= SEQUENCE {

componentNumber ComponentNumber --See page 1034

}

Referenced from: ComponentReference (p. 1034)

ArrayRefOrComp ::= CHOICE {

componentIdentifier ComponentIdentifier --See page 1033

bitRef BitRef --See page 1030

componentPosition ComponentPosition --See page 1034

}

Referenced from: ReferenceList (p. 1059)

ASN1_ConsValue ::= SEQUENCE {

constraintValueAndAttributesOrReplace ConstraintValueAndAttributesOrReplace --See page 1036

}

Referenced from: ASN1_TypeConstraint (p. 998) ASN1_ASP_Constraint (p. 994) ASN1_PDU_Constraint (p. 996) ASN1_CM_Constraint (p. 996)

ASN1_LocalTypes ::= SEQUENCE {

typeAssignmentList TypeAssignmentList --See page 1074

}

Referenced from: ASN1_TypeAndLocalTypes (p. 1027)

ASN1_Type ::= CHOICE {

builtinType BuiltinType --See page 1031

definedType DefinedType --See page 1039

subType SubType --See page 1066

}

Referenced from: ASN1_TypeAndLocalTypes (p. 1027) ComponentsOf (p. 1034) NamedType (p. 1051) SequenceOfType (p. 1062) SetOfType (p. 1063) SelectionType (p. 1061) TaggedType (p. 1067) ContainedSubType (p. 1036) ParentType (p. 1054) SetSubType (p. 1063) SequenceSubType (p. 1062) TypeAssignment (p. 1074)

ASN1_TypeAndLocalTypes ::= SEQUENCE {

asn1_Type ASN1_Type --See page 1027

asn1_LocalTypes ASN1_LocalTypes --See page 1027

}

Referenced from: ASN1_TypeDefinition (p. 1027)

ASN1_TypeDefinition ::= SEQUENCE {

asn1_TypeAndLocalTypes ASN1_TypeAndLocalTypes --See page 1027

}

Referenced from: ASN1_TypeDef (p. 998) ASN1_TypeRef (p. 999) ASN1_ASP_TypeDef (p. 995) ASN1_ASP_TypeDefByRef (p. 995) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefByRef (p. 997) ASN1_CM_TypeDef (p. 996)

ASN1_TypeId ::= SEQUENCE {

asn1_TypeIdentifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: ASN1_TypeDef (p. 998) ASN1_TypeRef (p. 999) ASN1_TypeConstraint (p. 998)

ASN1_Value ::= CHOICE {

bitStringValue BitStringValue --See page 1030

nullValue NullValue --See page 1087

sequenceValue SequenceValue --See page 1062

sequenceOfValue SequenceOfValue --See page 1062

setValue SetValue --See page 1063

setOfValue SetOfValue --See page 1063

choiceValue ChoiceValue --See page 1032

selectionValue SelectionValue --See page 1061

anyValue AnyValue --See page 1026

objectIdentifierValue ObjectIdentifierValue --See page 1052

realValue RealValue --See page 1059

}

Referenced from: Value (p. 1076)

ASN1_ValueList ::= SEQUENCE OF {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: SequenceOfValue (p. 1062) SetOfValue (p. 1063)

ASP_Id ::= SEQUENCE {

asp_IdAndFullId ASP_IdAndFullId --See page 1028

}

Referenced from: TTCN_ASP_TypeDef (p. 1023) ASN1_ASP_TypeDef (p. 995) ASN1_ASP_TypeDefByRef (p. 995) TTCN_ASP_Constraint (p. 1022) ASN1_ASP_Constraint (p. 994)

ASP_IdAndFullId ::= SEQUENCE {

asp_Identifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: ASP_Id (p. 1028)

ASP_ParId ::= SEQUENCE {

asp_ParIdOrMacro ASP_ParIdOrMacro --See page 1029

}

Referenced from: ASP_ParDcl (p. 999) ASP_ParValue (p. 1000)

ASP_ParIdAndFullId ::= SEQUENCE {

asp_ParIdentifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: ASP_ParIdOrMacro (p. 1029)

ASP_ParIdOrMacro ::= CHOICE {

asp_ParIdAndFullId ASP_ParIdAndFullId --See page 1029

macroSymbol MacroSymbol --See page 1086

}

Referenced from: ASP_ParId (p. 1029)

ASP_ParType ::= SEQUENCE {

typeAndAttributes TypeAndAttributes --See page 1073

}

Referenced from: ASP_ParDcl (p. 999)

Assignment ::= SEQUENCE {

dataObjectReference DataObjectReference --See page 1038

expression Expression --See page 1044

}

Referenced from: AssignmentList (p. 1029)

AssignmentList ::= SEQUENCE OF {

assignment Assignment --See page 1029

}

Referenced from: EventStatement (p. 1043)

Attach ::= SEQUENCE {

treeReference TreeReference --See page 1071

actualParList ActualParList --See page 1025

}

Referenced from: TestStepAttachment (p. 1069) Construct (p. 1036) Repeat (p. 1060)

Base ::= CHOICE {

two Two --See page 1092

ten Ten --See page 1091

}

Referenced from: NumericRealValue (p. 1052)

BitIdentifier ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: BitRef (p. 1030)

BitNumber ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: BitRef (p. 1030)

BitRef ::= CHOICE {

bitIdentifier BitIdentifier --See page 1030

bitNumber BitNumber --See page 1030

}

Referenced from: ArrayRefOrComp (p. 1026) ComponentReference (p. 1034)

BitStringType ::= SEQUENCE {

namedBitList NamedBitList --See page 1050

}

Referenced from: BuiltinType (p. 1031)

BitStringValue ::= SEQUENCE {

identifierList IdentifierList --See page 1045

}

Referenced from: ASN1_Value (p. 1028)

BooleanValue ::= CHOICE {

Atrue ATrue --See page 1080

Afalse AFalse --See page 1079

}

Referenced from: LiteralValue (p. 1048)

Bound ::= CHOICE {

number Number --See page 1087

identifier Identifier --See page 1084

}

Referenced from: SingleLength (p. 1064) LowerBound (p. 1048) UpperBound (p. 1075)

BuiltinType ::= CHOICE {

booleanType BooleanType --See page 1080

integerType IntegerType --See page 1046

bitStringType BitStringType --See page 1030

octetStringType OctetStringType --See page 1088

nullType NullType --See page 1087

sequenceType SequenceType --See page 1062

sequenceOfType SequenceOfType --See page 1062

setType SetType --See page 1063

setOfType SetOfType --See page 1063

choiceType ChoiceType --See page 1032

selectionType SelectionType --See page 1061

taggedType TaggedType --See page 1067

anyType AnyType --See page 1026

objectIdentifierType ObjectIdentifierType --See page 1088

characterString CharacterString --See page 1032

usefulType UsefulType --See page 1076

enumeratedType EnumeratedType --See page 1042

realType RealType --See page 1090

}

Referenced from: ASN1_Type (p. 1027)

CancelTimer ::= SEQUENCE {

timerIdentifier Identifier OPTIONAL --See page 1084

}

Referenced from: TimerOp (p. 1070)

CharacterString ::= CHOICE {

numericString NumericString --See page 1087

printableString PrintableString --See page 1089

teletexString TeletexString --See page 1091

videotexString VideotexString --See page 1092

visibleString VisibleString --See page 1092

ia5String IA5String --See page 1083

graphicString GraphicString --See page 1083

generalString GeneralString --See page 1083

t61String T61String --See page 1091

iso646String ISO646String --See page 1085

}

Referenced from: PredefinedType (p. 1057) BuiltinType (p. 1031)

ChoiceType ::= SEQUENCE {

alternativeTypeList AlternativeTypeList --See page 1026

}

Referenced from: BuiltinType (p. 1031)

ChoiceValue ::= SEQUENCE {

namedValue NamedValue --See page 1051

}

Referenced from: ASN1_Value (p. 1028)

ClassNumber ::= CHOICE {

number Number --See page 1087

definedValue DefinedValue --See page 1039

}

Referenced from: Tag (p. 1067)

ClassType ::= CHOICE {

universal UNIVERSAL --See page 1092

application APPLICATION --See page 1080

private_ PRIVATE_ --See page 1089

}

Referenced from: Tag (p. 1067)

CM_Id ::= SEQUENCE {

cm_Identifier Identifier --See page 1084

}

Referenced from: TTCN_CM_TypeDef (p. 1023) ASN1_CM_TypeDef (p. 996) TTCN_CM_Constraint (p. 1023) ASN1_CM_Constraint (p. 996)

CM_ParId ::= SEQUENCE {

cm_ParIdOrMacro CM_ParIdOrMacro --See page 1033

}

Referenced from: CM_ParDcl (p. 1001) CM_ParValue (p. 1002)

CM_ParIdAndFullId ::= SEQUENCE {

cm_ParIdentifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: CM_ParIdOrMacro (p. 1033)

CM_ParIdOrMacro ::= CHOICE {

cm_ParIdAndFullId CM_ParIdAndFullId --See page 1033

macroSymbol MacroSymbol --See page 1086

}

Referenced from: CM_ParId (p. 1033)

CM_ParType ::= SEQUENCE {

typeAndAttributes TypeAndAttributes --See page 1073

}

Referenced from: CM_ParDcl (p. 1001)

Complement ::= SEQUENCE {

valueList ValueList --See page 1077

}

Referenced from: MatchingSymbol (p. 1049)

ComponentIdentifier ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: ArrayRefOrComp (p. 1026) RecordRef (p. 1059)

ComponentNumber ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: ArrayRef (p. 1026)

ComponentPosition ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: ArrayRefOrComp (p. 1026)

ComponentReference ::= CHOICE {

recordRef RecordRef --See page 1059

arrayRef ArrayRef --See page 1026

bitRef BitRef --See page 1030

}

Referenced from: ComponentReferenceList (p. 1034)

ComponentReferenceList ::= SEQUENCE OF {

componentReference ComponentReference --See page 1034

}

Referenced from: ReferenceList (p. 1059) DataObjectReference (p. 1038)

ComponentsOf ::= SEQUENCE {

asn1_Type ASN1_Type --See page 1027

}

Referenced from: ElementType (p. 1040)

Configuration ::= SEQUENCE {

tcompConfigIdentifier Identifier --See page 1084

}

Referenced from: TestCase (p. 1016)

ConsId ::= SEQUENCE {

consIdAndParList ConsIdAndParList --See page 1035

}

Referenced from: StructTypeConstraint (p. 1013) ASN1_TypeConstraint (p. 998) TTCN_ASP_Constraint (p. 1022) TTCN_PDU_Constraint (p. 1024) ASN1_ASP_Constraint (p. 994) ASN1_PDU_Constraint (p. 996) TTCN_CM_Constraint (p. 1023) ASN1_CM_Constraint (p. 996)

ConsIdAndParList ::= SEQUENCE {

constraintIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: ConsId (p. 1034)

ConsRef ::= SEQUENCE {

constraintIdentifier Identifier --See page 1084

actualCrefParList ActualCrefParList --See page 1025

}

Referenced from: ConstraintReference (p. 1035) ConstraintValue (p. 1035) Primary (p. 1058)

Constraint ::= SEQUENCE {

valueConstraint ValueConstraint OPTIONAL --See page 1077

presenceConstraint PresenceConstraint OPTIONAL --See page 1057

}

Referenced from: NamedConstraint (p. 1050)

ConstraintExpression ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: ConstraintValue (p. 1035) LowerRangeBound (p. 1048) UpperRangeBound (p. 1075)

ConstraintReference ::= CHOICE {

consRef ConsRef --See page 1035

formalParIdentifier Identifier --See page 1084

}

Referenced from: Cref (p. 1038)

ConstraintValue ::= CHOICE {

constraintExpression ConstraintExpression --See page 1035

matchingSymbol MatchingSymbol --See page 1049

consRef ConsRef --See page 1035

}

Referenced from: ConstraintValueAndAttributes (p. 1036)

ConstraintValueAndAttributes ::= SEQUENCE {

constraintValue ConstraintValue --See page 1035

valueAttributes ValueAttributes OPTIONAL --See page 1076

}

Referenced from: ConsValue (p. 1036) ConstraintValueAndAttributesOrReplace (p. 1036) Replace (p. 1060) ActualCrefParList (p. 1025) ValueList (p. 1077) SuperSet (p. 1067) SubSet (p. 1066) ActualParList (p. 1025) SingleValue (p. 1065) UpperEndValue (p. 1075) LowerEndValue (p. 1048) ASN1_ValueList (p. 1028) AnyValue (p. 1026) NamedValue (p. 1051) DefaultValue (p. 1039)

ConstraintValueAndAttributesOrReplace ::= CHOICE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

replacementList ReplacementList --See page 1060

}

Referenced from: ASN1_ConsValue (p. 1027)

Construct ::= CHOICE {

goTo GoTo --See page 1045

attach Attach --See page 1029

repeat Repeat --See page 1060

return_ RETURN_ --See page 1090

activate Activate --See page 1025

create Create --See page 1037

}

Referenced from: StatementLine (p. 1065)

ConsValue ::= SEQUENCE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: ElemValue (p. 1006) ASP_ParValue (p. 1000) PDU_FieldValue (p. 1010) CM_ParValue (p. 1002)

ContainedSubType ::= SEQUENCE {

asn1_Type ASN1_Type --See page 1027

}

Referenced from: SubtypeValueSet (p. 1066)

CP_Id ::= SEQUENCE {

cp_Identifier Identifier --See page 1084

}

Referenced from: CP_Dcl (p. 1003)

CP_List ::= SEQUENCE OF {

cp_Identifier Identifier --See page 1084

}

Referenced from: CPs_Used (p. 1037)

CPs_Used ::= SEQUENCE {

cp_List CP_List --See page 1037

}

Referenced from: TCompConfigInfo (p. 1015)

Create ::= SEQUENCE {

createList CreateList --See page 1037

}

Referenced from: Construct (p. 1036)

CreateAttach ::= SEQUENCE {

treeReference TreeReference --See page 1071

actualParList ActualParList --See page 1025

}

Referenced from: CreateTComp (p. 1037)

CreateList ::= SEQUENCE OF {

createTComp CreateTComp --See page 1037

}

Referenced from: Create (p. 1037)

CreateTComp ::= SEQUENCE {

tcompIdentifier Identifier --See page 1084

createAttach CreateAttach --See page 1037

}

Referenced from: CreateList (p. 1037)

Cref ::= SEQUENCE {

constraintReference ConstraintReference --See page 1035

}

Referenced from: BehaviourLine (p. 1001)

DataObjectReference ::= SEQUENCE {

dataObjectIdentifier Identifier --See page 1084

componentReferenceList ComponentReferenceList --See page 1034

}

Referenced from: Assignment (p. 1029) ReadTimer (p. 1059) Primary (p. 1058)

DeclarationValue ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: TS_ConstValue (p. 1071) TS_VarValue (p. 1073) TC_VarValue (p. 1068) Duration (p. 1040)

DefaultExpression ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: EncodingDefault (p. 1041)

DefaultGroupId ::= SEQUENCE {

defaultGroupIdentifier Identifier --See page 1084

}

Referenced from: DefaultGroup (p. 1005)

DefaultId ::= SEQUENCE {

defaultIdAndParList DefaultIdAndParList --See page 1038

}

Referenced from: DefaultCase (p. 1004)

DefaultIdAndParList ::= SEQUENCE {

defaultIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: DefaultId (p. 1038)

DefaultRef ::= SEQUENCE {

defaultGroupReference DefaultGroupReference --See page 1081

}

Referenced from: DefaultCase (p. 1004)

DefaultReference ::= SEQUENCE {

defaultIdentifier Identifier --See page 1084

actualParList ActualParList --See page 1025

}

Referenced from: DefaultRefList (p. 1039)

DefaultRefList ::= SEQUENCE OF {

defaultReference DefaultReference --See page 1039

}

Referenced from: DefaultsRef (p. 1039) Activate (p. 1025)

DefaultsRef ::= SEQUENCE {

defaultRefList DefaultRefList --See page 1039

}

Referenced from: CompactTestGroup (p. 1003) TestCase (p. 1016) TestStep (p. 1017)

DefaultValue ::= SEQUENCE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: NamedTypeAttribute (p. 1051)

DefinedType ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: ASN1_Type (p. 1027)

DefinedValue ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: ClassNumber (p. 1032)

DerivationPath ::= SEQUENCE OF {

constraintIdentifier Identifier --See page 1084

}

Referenced from: DerivPath (p. 1040)

DerivPath ::= SEQUENCE {

derivationPath DerivationPath --See page 1040

}

Referenced from: StructTypeConstraint (p. 1013) ASN1_TypeConstraint (p. 998) TTCN_ASP_Constraint (p. 1022) TTCN_PDU_Constraint (p. 1024) ASN1_ASP_Constraint (p. 994) ASN1_PDU_Constraint (p. 996) TTCN_CM_Constraint (p. 1023) ASN1_CM_Constraint (p. 996)

Done ::= SEQUENCE {

tcompIdList TCompIdList --See page 1068

}

Referenced from: Event (p. 1043)

Duration ::= SEQUENCE {

declarationValue DeclarationValue --See page 1038

}

Referenced from: TimerDcl (p. 1018)

ElementType ::= CHOICE {

namedTypeAndAttributes NamedTypeAndAttributes --See page 1051

componentsOf ComponentsOf --See page 1034

}

Referenced from: ElementTypeList (p. 1040)

ElementTypeList ::= SEQUENCE OF {

elementType ElementType --See page 1040

}

Referenced from: SequenceType (p. 1062) SetType (p. 1063)

ElementValueList ::= SEQUENCE OF {

namedValue NamedValue --See page 1051

}

Referenced from: SequenceValue (p. 1062) SetValue (p. 1063)

ElemId ::= SEQUENCE {

elemIdAndFullId ElemIdAndFullId --See page 1041

}

Referenced from: ElemDcl (p. 1006) ElemValue (p. 1006)

ElemIdAndFullId ::= SEQUENCE {

elemIdentifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: ElemId (p. 1041)

ElemType ::= SEQUENCE {

typeAndAttributes TypeAndAttributes --See page 1073

}

Referenced from: ElemDcl (p. 1006)

EncodingDefault ::= SEQUENCE {

defaultExpression DefaultExpression --See page 1038

}

Referenced from: EncodingDefinition (p. 1006)

EncodingRef ::= SEQUENCE {

encodingReference EncodingReference --See page 1082

}

Referenced from: EncodingDefinition (p. 1006)

EncodingRuleId ::= SEQUENCE {

encodingRuleIdentifier Identifier --See page 1084

}

Referenced from: EncodingDefinition (p. 1006) EncodingVariationSet (p. 1008)

EncodingVariationId ::= SEQUENCE {

encVariationIdAndParList EncVariationIdAndParList --See page 1042

}

Referenced from: EncodingVariation (p. 1007)

EncRuleId ::= SEQUENCE {

encodingRuleIdentifier Identifier --See page 1084

}

Referenced from: TTCN_PDU_Constraint (p. 1024) ASN1_PDU_Constraint (p. 996)

EncVariationCall ::= SEQUENCE {

encVariationIdentifier Identifier --See page 1084

actualParList ActualParList --See page 1025

}

Referenced from: PDU_FieldEncodingCall (p. 1056) EncVariationId (p. 1042)

EncVariationId ::= SEQUENCE {

encVariationCall EncVariationCall --See page 1042

}

Referenced from: StructTypeDef (p. 1014) ASN1_TypeDef (p. 998) ASN1_TypeRef (p. 999) TTCN_PDU_TypeDef (p. 1024) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefByRef (p. 997) StructTypeConstraint (p. 1013) ASN1_TypeConstraint (p. 998) TTCN_PDU_Constraint (p. 1024) ASN1_PDU_Constraint (p. 996)

EncVariationIdAndParList ::= SEQUENCE {

encVariationIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: EncodingVariationId (p. 1041)

EnumeratedType ::= SEQUENCE {

enumeration Enumeration --See page 1042

}

Referenced from: BuiltinType (p. 1031)

Enumeration ::= SEQUENCE OF {

namedNumber NamedNumber --See page 1050

}

Referenced from: EnumeratedType (p. 1042)

Event ::= CHOICE {

send Send --See page 1062

receive Receive --See page 1059

otherwise Otherwise --See page 1053

timeout Timeout --See page 1070

done Done --See page 1040

}

Referenced from: EventStatement (p. 1043)

EventStatement ::= SEQUENCE {

event Event OPTIONAL --See page 1043

qualifier Qualifier OPTIONAL --See page 1058

assignmentList AssignmentList --See page 1029

timerOps TimerOps --See page 1070

}

Referenced from: StatementLine (p. 1065)

ExpandedId ::= SEQUENCE {

expansion Expansion --See page 1043

}

Referenced from: AliasDef (p. 994)

Expansion ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: ExpandedId (p. 1043)

Exponent ::= CHOICE {

signedNumber SignedNumber --See page 1063

number Number --See page 1087

}

Referenced from: NumericRealValue (p. 1052)

Expression ::= CHOICE {

relExpression RelExpression --See page 1060

simpleExpression SimpleExpression --See page 1063

}

Referenced from: VariationDefault (p. 1077) SelectionExpression (p. 1061) DeclarationValue (p. 1038) Assignment (p. 1029) Qualifier (p. 1058) TimerValue (p. 1070) ConstraintExpression (p. 1035) DefaultExpression (p. 1038) ParenExpression (p. 1054) ComponentNumber (p. 1034) BitNumber (p. 1030)

Factor ::= CHOICE {

unaryExpression UnaryExpression --See page 1074

primary Primary --See page 1058

}

Referenced from: Term (p. 1069) MultExpression (p. 1049)

Fail ::= CHOICE {

fail FAIL --See page 1082

preliminaryFAIL PreliminaryFAIL --See page 1089

}

Referenced from: Verdict (p. 1078)

FormalParAndType ::= SEQUENCE {

formalParIdList FormalParIdList --See page 1044

formalParType FormalParType --See page 1045

}

Referenced from: FormalParList (p. 1044)

FormalParIdList ::= SEQUENCE OF {

formalParIdentifier Identifier --See page 1084

}

Referenced from: FormalParAndType (p. 1044)

FormalParList ::= SEQUENCE OF {

formalParAndType FormalParAndType --See page 1044

}

Referenced from: EncVariationIdAndParList (p. 1042) InvalidFieldEncodingIdAndParList (p. 1047) TS_OpIdAndParList (p. 1072) TS_ProcIdAndParList (p. 1072) ConsIdAndParList (p. 1035) TreeHeader (p. 1071) TestStepIdAndParList (p. 1070) DefaultIdAndParList (p. 1038)

FormalParType ::= CHOICE {

ttcn_Type TTCN_Type --See page 1073

pdu PDU --See page 1088

cp CP --See page 1081

timer TIMER --See page 1092

}

Referenced from: FormalParAndType (p. 1044)

FullSpecification ::= SEQUENCE {

typeConstraints TypeConstraints --See page 1074

}

Referenced from: MultipleTypeConstraints (p. 1049)

GoTo ::= SEQUENCE {

label Label --See page 1047

}

Referenced from: Construct (p. 1036)

Header ::= SEQUENCE {

treeHeader TreeHeader --See page 1071

}

Referenced from: LocalTree (p. 1008)

IdentifierList ::= SEQUENCE OF {

identifier Identifier --See page 1084

}

Referenced from: BitStringValue (p. 1030)

IdOrNum ::= CHOICE {

identifier Identifier --See page 1084

number Number --See page 1087

signedNumber SignedNumber --See page 1063

}

Referenced from: NamedNumber (p. 1050)

ImplicitSend ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: StatementLine (p. 1065)

Inconclusive ::= CHOICE {

inconc INCONC --See page 1085

preliminaryINCONC PreliminaryINCONC --See page 1089

}

Referenced from: Verdict (p. 1078)

Indentation ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: Line (p. 1047)

InnerTypeConstraints ::= CHOICE {

withComponent WithComponent --See page 1078

withComponents WithComponents --See page 1078

}

Referenced from: SubtypeValueSet (p. 1066)

IntegerRange ::= SEQUENCE {

lowerTypeBound LowerTypeBound --See page 1048

upperTypeBound UpperTypeBound --See page 1076

}

Referenced from: Restriction (p. 1061)

IntegerType ::= SEQUENCE {

namedNumberList NamedNumberList --See page 1051

}

Referenced from: BuiltinType (p. 1031)

InvalidFieldEncodingCall ::= SEQUENCE {

invalidFieldEncodingIdentifier Identifier --See page 1084

actualParList ActualParList --See page 1025

}

Referenced from: PDU_FieldEncodingCall (p. 1056)

InvalidFieldEncodingId ::= SEQUENCE {

invalidFieldEncodingIdAndParList InvalidFieldEncodingIdAndParList --See page 1047

}

Referenced from: InvalidFieldEncodingDef (p. 1008)

InvalidFieldEncodingIdAndParList ::= SEQUENCE {

invalidFieldEncodingIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: InvalidFieldEncodingId (p. 1046)

Label ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: LabelId (p. 1047) GoTo (p. 1045)

LabelId ::= SEQUENCE {

label Label --See page 1047

}

Referenced from: BehaviourLine (p. 1001)

LengthAttribute ::= CHOICE {

singleLength SingleLength --See page 1064

rangeLength RangeLength --See page 1058

}

Referenced from: TypeAndLengthAttribute (p. 1074)

LengthRestriction ::= CHOICE {

singleTypeLength SingleTypeLength --See page 1064

rangeTypeLength RangeTypeLength --See page 1058

}

Referenced from: Restriction (p. 1061)

Line ::= SEQUENCE {

indentation Indentation --See page 1046

statementLine StatementLine --See page 1065

}

Referenced from: BehaviourLine (p. 1001)

LineNumber ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: BehaviourLine (p. 1001)

LiteralValue ::= CHOICE {

number Number --See page 1087

booleanValue BooleanValue --See page 1030

bstring Bstring --See page 1080

hstring Hstring --See page 1083

ostring Ostring --See page 1088

cstring Cstring --See page 1081

r_Value R_Value --See page 1058

}

Referenced from: SimpleValue (p. 1064) Value (p. 1076)

LowerBound ::= SEQUENCE {

bound Bound --See page 1031

}

Referenced from: RangeLength (p. 1058)

LowerEndpoint ::= SEQUENCE {

lowerEndValue LowerEndValue --See page 1048

inclusive INCLUSIVE OPTIONAL --See page 1085

}

Referenced from: ValueRange (p. 1077)

LowerEndValue ::= CHOICE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

min Min --See page 1086

}

Referenced from: LowerEndpoint (p. 1048)

LowerRangeBound ::= CHOICE {

constraintExpression ConstraintExpression --See page 1035

minusINFINITY MinusINFINITY --See page 1086

}

Referenced from: ValRange (p. 1076)

LowerTypeBound ::= CHOICE {

signedNumber SignedNumber --See page 1063

number Number --See page 1087

minusINFINITY MinusINFINITY --See page 1086

}

Referenced from: RangeTypeLength (p. 1058) IntegerRange (p. 1046)

LowerValueBound ::= SEQUENCE {

valueBound ValueBound --See page 1077

}

Referenced from: RangeValueLength (p. 1058)

Mantissa ::= CHOICE {

signedNumber SignedNumber --See page 1063

number Number --See page 1087

}

Referenced from: NumericRealValue (p. 1052)

MatchingSymbol ::= CHOICE {

complement Complement --See page 1033

omit Omit --See page 1053

anyValue ANYValue --See page 1079

anyOrOmit AnyOrOmit --See page 1079

valueList ValueList --See page 1077

valRange ValRange --See page 1076

superSet SuperSet --See page 1067

subSet SubSet --See page 1066

permutation Permutation --See page 1057

}

Referenced from: ConstraintValue (p. 1035)

MultExpression ::= SEQUENCE {

term Term --See page 1069

multOp MultOp --See page 1050

factor Factor --See page 1044

}

Referenced from: Term (p. 1069)

MultipleTypeConstraints ::= CHOICE {

fullSpecification FullSpecification --See page 1045

partialSpecification PartialSpecification --See page 1054

}

Referenced from: WithComponents (p. 1078)

MultOp ::= CHOICE {

mult Mult --See page 1087

div Div --See page 1082

mod Mod --See page 1086

and And --See page 1079

}

Referenced from: MultExpression (p. 1049)

NameAndNumberForm ::= SEQUENCE {

nameForm NameForm --See page 1051

numberForm NumberForm --See page 1052

}

Referenced from: ObjIdComponent (p. 1053)

NamedBitList ::= SEQUENCE OF {

namedNumber NamedNumber --See page 1050

}

Referenced from: BitStringType (p. 1030)

NamedConstraint ::= SEQUENCE {

identifier Identifier --See page 1084

constraint Constraint --See page 1035

}

Referenced from: NamedConstraintList (p. 1050)

NamedConstraintList ::= SEQUENCE OF {

namedConstraint NamedConstraint --See page 1050

}

Referenced from: TypeConstraints (p. 1074)

NamedNumber ::= SEQUENCE {

identifier Identifier --See page 1084

idOrNum IdOrNum --See page 1045

}

Referenced from: NamedNumberList (p. 1051) Enumeration (p. 1042) NamedBitList (p. 1050)

NamedNumberList ::= SEQUENCE OF {

namedNumber NamedNumber --See page 1050

}

Referenced from: IntegerType (p. 1046)

NamedType ::= SEQUENCE {

identifier Identifier --See page 1084

asn1_Type ASN1_Type --See page 1027

}

Referenced from: AlternativeTypeList (p. 1026) NamedTypeOrSelection (p. 1051)

NamedTypeAndAttributes ::= SEQUENCE {

namedTypeOrSelection NamedTypeOrSelection --See page 1051

namedTypeAttribute NamedTypeAttribute OPTIONAL --See page 1051

}

Referenced from: ElementType (p. 1040)

NamedTypeAttribute ::= CHOICE {

optional OPTIONAL --See page 1088

defaultValue DefaultValue --See page 1039

}

Referenced from: NamedTypeAndAttributes (p. 1051)

NamedTypeOrSelection ::= CHOICE {

namedType NamedType --See page 1051

selectionType SelectionType --See page 1061

}

Referenced from: NamedTypeAndAttributes (p. 1051)

NamedValue ::= SEQUENCE {

identifier Identifier --See page 1084

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: ElementValueList (p. 1040) ChoiceValue (p. 1032) SelectionValue (p. 1061)

NameForm ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: ObjIdComponent (p. 1053) NameAndNumberForm (p. 1050)

Num_CPs ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: NumOf_CPs (p. 1052)

Num_PCOs ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: NumOf_PCOs (p. 1052)

NumberForm ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: ObjIdComponent (p. 1053) NameAndNumberForm (p. 1050)

NumericRealValue ::= SEQUENCE {

mantissa Mantissa --See page 1049

base Base --See page 1030

exponent Exponent --See page 1043

}

Referenced from: RealValue (p. 1059)

NumOf_CPs ::= SEQUENCE {

num_CPs Num_CPs --See page 1052

}

Referenced from: TCompDcl (p. 1016)

NumOf_PCOs ::= SEQUENCE {

num_PCOs Num_PCOs --See page 1052

}

Referenced from: TCompDcl (p. 1016)

ObjectIdentifierValue ::= SEQUENCE {

objIdComponentList ObjIdComponentList --See page 1053

}

Referenced from: ASN1_Value (p. 1028)

ObjIdComponent ::= CHOICE {

nameForm NameForm --See page 1051

numberForm NumberForm --See page 1052

nameAndNumberForm NameAndNumberForm --See page 1050

}

Referenced from: ObjIdComponentList (p. 1053)

ObjIdComponentList ::= SEQUENCE OF {

objIdComponent ObjIdComponent --See page 1053

}

Referenced from: ObjectIdentifierValue (p. 1052)

Omit ::= SEQUENCE {

omit OMIT --See page 1088

}

Referenced from: MatchingSymbol (p. 1049)

OmitReference ::= SEQUENCE {

referenceList ReferenceList --See page 1059

}

Referenced from: Replacement (p. 1060)

OpCall ::= SEQUENCE {

ts_OpIdentifier Identifier --See page 1084

actualParList ActualParList --See page 1025

}

Referenced from: Primary (p. 1058)

Otherwise ::= SEQUENCE {

identifier Identifier OPTIONAL --See page 1084

}

Referenced from: Event (p. 1043)

P_Role ::= SEQUENCE {

pco_Role PCO_Role --See page 1055

}

Referenced from: PCO_TypeDcl (p. 1009) PCO_Dcl (p. 1009)

ParenExpression ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: Primary (p. 1058)

ParentSubType ::= SEQUENCE {

parentType ParentType --See page 1054

subTypeSpec SubTypeSpec --See page 1066

}

Referenced from: SubType (p. 1066)

ParentType ::= SEQUENCE {

asn1_Type ASN1_Type --See page 1027

}

Referenced from: ParentSubType (p. 1054)

PartialSpecification ::= SEQUENCE {

typeConstraints TypeConstraints --See page 1074

}

Referenced from: MultipleTypeConstraints (p. 1049)

Pass ::= CHOICE {

pass PASS --See page 1088

preliminaryPASS PreliminaryPASS --See page 1089

}

Referenced from: Verdict (p. 1078)

PCO_Id ::= SEQUENCE {

pco_Identifier Identifier --See page 1084

}

Referenced from: PCO_Dcl (p. 1009)

PCO_List ::= SEQUENCE OF {

pco_Identifier Identifier --See page 1084

}

Referenced from: PCOs_Used (p. 1055)

PCO_Role ::= CHOICE {

ut UT --See page 1092

lt LT --See page 1085

}

Referenced from: P_Role (p. 1053)

PCO_Type ::= SEQUENCE {

pco_TypeIdentifier Identifier --See page 1084

}

Referenced from: TTCN_ASP_TypeDef (p. 1023) ASN1_ASP_TypeDef (p. 995) ASN1_ASP_TypeDefByRef (p. 995) TTCN_PDU_TypeDef (p. 1024) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefByRef (p. 997)

PCO_TypeId ::= SEQUENCE {

pco_TypeIdentifier Identifier --See page 1084

}

Referenced from: PCO_TypeDcl (p. 1009) PCO_Dcl (p. 1009)

PCOs_Used ::= SEQUENCE {

pco_List PCO_List --See page 1054

}

Referenced from: TCompConfigInfo (p. 1015)

PDU_EncodingId ::= SEQUENCE {

encodingRuleIdentifier Identifier --See page 1084

}

Referenced from: TTCN_PDU_TypeDef (p. 1024) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefByRef (p. 997)

PDU_FieldEncoding ::= SEQUENCE {

pdu_FieldEncodingCall PDU_FieldEncodingCall --See page 1056

}

Referenced from: SimpleTypeDef (p. 1011) ElemDcl (p. 1006) PDU_FieldDcl (p. 1010) PDU_FieldValue (p. 1010)

PDU_FieldEncodingCall ::= CHOICE {

encVariationCall EncVariationCall --See page 1042

invalidFieldEncodingCall InvalidFieldEncodingCall --See page 1046

}

Referenced from: PDU_FieldEncoding (p. 1055)

PDU_FieldId ::= SEQUENCE {

pdu_FieldIdOrMacro PDU_FieldIdOrMacro --See page 1056

}

Referenced from: PDU_FieldDcl (p. 1010) PDU_FieldValue (p. 1010)

PDU_FieldIdAndFullId ::= SEQUENCE {

pdu_FieldIdentifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: PDU_FieldIdOrMacro (p. 1056)

PDU_FieldIdOrMacro ::= CHOICE {

pdu_FieldIdAndFullId PDU_FieldIdAndFullId --See page 1056

macroSymbol MacroSymbol --See page 1086

}

Referenced from: PDU_FieldId (p. 1056)

PDU_FieldType ::= SEQUENCE {

typeAndAttributes TypeAndAttributes --See page 1073

}

Referenced from: PDU_FieldDcl (p. 1010)

PDU_Id ::= SEQUENCE {

pdu_IdAndFullId PDU_IdAndFullId --See page 1057

}

Referenced from: TTCN_PDU_TypeDef (p. 1024) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefByRef (p. 997) TTCN_PDU_Constraint (p. 1024) ASN1_PDU_Constraint (p. 996)

PDU_IdAndFullId ::= SEQUENCE {

pdu_Identifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: PDU_Id (p. 1056)

PermittedAlphabet ::= SEQUENCE {

subTypeSpec SubTypeSpec --See page 1066

}

Referenced from: SubtypeValueSet (p. 1066)

Permutation ::= SEQUENCE {

valueList ValueList --See page 1077

}

Referenced from: MatchingSymbol (p. 1049)

PredefinedType ::= CHOICE {

integer INTEGER --See page 1085

boolean BOOLEAN --See page 1080

bitstring BITSTRING --See page 1080

hexstring HEXSTRING --See page 1083

octetstring OCTETSTRING --See page 1088

r_Type R_TYPE --See page 1090

characterString CharacterString --See page 1032

}

Referenced from: TTCN_Type (p. 1073)

PresenceConstraint ::= CHOICE {

present PRESENT --See page 1089

absent ABSENT --See page 1079

optional OPTIONAL --See page 1088

}

Referenced from: Constraint (p. 1035)

Primary ::= CHOICE {

value Value --See page 1076

dataObjectReference DataObjectReference --See page 1038

opCall OpCall --See page 1053

consRef ConsRef --See page 1035

selectExprId SelectExprId --See page 1061

parenExpression ParenExpression --See page 1054

}

Referenced from: Factor (p. 1044) UnaryExpression (p. 1074)

Qualifier ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: EventStatement (p. 1043) Repeat (p. 1060)

R_Value ::= CHOICE {

pass PASS --See page 1088

fail FAIL --See page 1082

inconc INCONC --See page 1085

none NONE --See page 1087

}

Referenced from: LiteralValue (p. 1048)

RangeLength ::= SEQUENCE {

lowerBound LowerBound --See page 1048

upperBound UpperBound --See page 1075

}

Referenced from: LengthAttribute (p. 1047)

RangeTypeLength ::= SEQUENCE {

lowerTypeBound LowerTypeBound --See page 1048

upperTypeBound UpperTypeBound --See page 1076

}

Referenced from: LengthRestriction (p. 1047)

RangeValueLength ::= SEQUENCE {

lowerValueBound LowerValueBound --See page 1049

upperValueBound UpperValueBound --See page 1076

}

Referenced from: ValueLength (p. 1077)

ReadTimer ::= SEQUENCE {

timerIdentifier Identifier --See page 1084

dataObjectReference DataObjectReference --See page 1038

}

Referenced from: TimerOp (p. 1070)

RealValue ::= CHOICE {

numericRealValue NumericRealValue --See page 1052

specialRealValue SpecialRealValue --See page 1065

}

Referenced from: ASN1_Value (p. 1028)

Receive ::= SEQUENCE {

identifier1 Identifier OPTIONAL --See page 1084

identifier2 Identifier --See page 1084

}

Referenced from: Event (p. 1043)

RecordRef ::= SEQUENCE {

componentIdentifier ComponentIdentifier --See page 1033

}

Referenced from: ComponentReference (p. 1034)

ReferenceList ::= SEQUENCE {

arrayRefOrComp ArrayRefOrComp --See page 1026

componentReferenceList ComponentReferenceList --See page 1034

}

Referenced from: Replace (p. 1060) OmitReference (p. 1053)

ReferenceType ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: TTCN_Type (p. 1073) AnyValue (p. 1026)

RelExpression ::= SEQUENCE {

simpleExpression1 SimpleExpression --See page 1063

relOp RelOp --See page 1060

simpleExpression2 SimpleExpression --See page 1063

}

Referenced from: Expression (p. 1044)

RelOp ::= CHOICE {

equal Equal --See page 1082

less Less --See page 1085

greater Greater --See page 1083

notEqual NotEqual --See page 1087

greaterOrEqual GreaterOrEqual --See page 1083

lessOrEqual LessOrEqual --See page 1085

}

Referenced from: RelExpression (p. 1060)

Repeat ::= SEQUENCE {

attach Attach --See page 1029

qualifier Qualifier --See page 1058

}

Referenced from: Construct (p. 1036)

Replace ::= SEQUENCE {

referenceList ReferenceList --See page 1059

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: Replacement (p. 1060)

Replacement ::= CHOICE {

replace Replace --See page 1060

omitReference OmitReference --See page 1053

}

Referenced from: ReplacementList (p. 1060)

ReplacementList ::= SEQUENCE OF {

replacement Replacement --See page 1060

}

Referenced from: ConstraintValueAndAttributesOrReplace (p. 1036)

Restriction ::= CHOICE {

lengthRestriction LengthRestriction --See page 1047

integerRange IntegerRange --See page 1046

simpleValueList SimpleValueList --See page 1064

}

Referenced from: TypeAndRestriction (p. 1074)

Result ::= SEQUENCE {

r R --See page 1089

}

Referenced from: Verdict (p. 1078)

SelectExpr ::= SEQUENCE {

selectionExpression SelectionExpression --See page 1061

}

Referenced from: SelectExprDef (p. 1011)

SelectExprId ::= SEQUENCE {

selectExprIdentifier Identifier --See page 1084

}

Referenced from: SelectExprDef (p. 1011) Primary (p. 1058)

SelectionExpression ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: SelectExpr (p. 1061)

SelectionType ::= SEQUENCE {

identifier Identifier --See page 1084

asn1_Type ASN1_Type --See page 1027

}

Referenced from: BuiltinType (p. 1031) NamedTypeOrSelection (p. 1051)

SelectionValue ::= SEQUENCE {

namedValue NamedValue --See page 1051

}

Referenced from: ASN1_Value (p. 1028)

SelExprId ::= SEQUENCE {

selectExprIdentifier Identifier --See page 1084

}

Referenced from: TestGroup (p. 1017) CompactTestGroup (p. 1003) CompactTestCase (p. 1002) TestCase (p. 1016)

Send ::= SEQUENCE {

identifier1 Identifier OPTIONAL --See page 1084

identifier2 Identifier --See page 1084

}

Referenced from: Event (p. 1043)

SequenceOfType ::= SEQUENCE {

asn1_Type ASN1_Type OPTIONAL --See page 1027

}

Referenced from: BuiltinType (p. 1031)

SequenceOfValue ::= SEQUENCE {

asn1_ValueList ASN1_ValueList --See page 1028

}

Referenced from: ASN1_Value (p. 1028)

SequenceSubType ::= SEQUENCE {

sizeConstraint SizeConstraint --See page 1065

asn1_Type ASN1_Type --See page 1027

}

Referenced from: SubType (p. 1066)

SequenceType ::= SEQUENCE {

elementTypeList ElementTypeList --See page 1040

}

Referenced from: BuiltinType (p. 1031)

SequenceValue ::= SEQUENCE {

elementValueList ElementValueList --See page 1040

}

Referenced from: ASN1_Value (p. 1028)

SetOfType ::= SEQUENCE {

asn1_Type ASN1_Type OPTIONAL --See page 1027

}

Referenced from: BuiltinType (p. 1031)

SetOfValue ::= SEQUENCE {

asn1_ValueList ASN1_ValueList --See page 1028

}

Referenced from: ASN1_Value (p. 1028)

SetSubType ::= SEQUENCE {

sizeConstraint SizeConstraint --See page 1065

asn1_Type ASN1_Type --See page 1027

}

Referenced from: SubType (p. 1066)

SetType ::= SEQUENCE {

elementTypeList ElementTypeList --See page 1040

}

Referenced from: BuiltinType (p. 1031)

SetValue ::= SEQUENCE {

elementValueList ElementValueList --See page 1040

}

Referenced from: ASN1_Value (p. 1028)

SignedNumber ::= SEQUENCE {

minus Minus --See page 1086

number Number --See page 1087

}

Referenced from: LowerTypeBound (p. 1048) UpperTypeBound (p. 1076) SimpleValue (p. 1064) IdOrNum (p. 1045) Mantissa (p. 1049) Exponent (p. 1043)

SimpleExpression ::= CHOICE {

addExpression AddExpression --See page 1025

term Term --See page 1069

}

Referenced from: Expression (p. 1044) RelExpression (p. 1060) RelExpression (p. 1060) AddExpression (p. 1025)

SimpleTypeDefinition ::= SEQUENCE {

typeAndRestriction TypeAndRestriction --See page 1074

}

Referenced from: SimpleTypeDef (p. 1011)

SimpleTypeId ::= SEQUENCE {

simpleTypeIdentifier Identifier --See page 1084

}

Referenced from: SimpleTypeDef (p. 1011)

SimpleValue ::= CHOICE {

literalValue LiteralValue --See page 1048

signedNumber SignedNumber --See page 1063

}

Referenced from: SimpleValueList (p. 1064)

SimpleValueList ::= SEQUENCE OF {

simpleValue SimpleValue --See page 1064

}

Referenced from: Restriction (p. 1061)

SingleLength ::= SEQUENCE {

bound Bound --See page 1031

}

Referenced from: LengthAttribute (p. 1047)

SingleTypeConstraint ::= SEQUENCE {

subTypeSpec SubTypeSpec --See page 1066

}

Referenced from: WithComponent (p. 1078)

SingleTypeLength ::= SEQUENCE {

number Number --See page 1087

}

Referenced from: LengthRestriction (p. 1047)

SingleValue ::= SEQUENCE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: SubtypeValueSet (p. 1066)

SingleValueLength ::= SEQUENCE {

valueBound ValueBound --See page 1077

}

Referenced from: ValueLength (p. 1077)

SizeConstraint ::= SEQUENCE {

subTypeSpec SubTypeSpec --See page 1066

}

Referenced from: SetSubType (p. 1063) SequenceSubType (p. 1062) SubtypeValueSet (p. 1066)

SO_SuiteId ::= SEQUENCE {

suiteIdentifier Identifier --See page 1084

}

Referenced from: SuiteStructure (p. 1014)

SpecialRealValue ::= CHOICE {

plus_INFINITY Plus_INFINITY --See page 1089

minus_INFINITY Minus_INFINITY --See page 1086

}

Referenced from: RealValue (p. 1059)

StartTimer ::= SEQUENCE {

timerIdentifier Identifier --See page 1084

timerValue TimerValue OPTIONAL --See page 1070

}

Referenced from: TimerOp (p. 1070)

StatementLine ::= CHOICE {

eventStatement EventStatement --See page 1043

construct Construct --See page 1036

implicitSend ImplicitSend --See page 1045

}

Referenced from: Line (p. 1047)

StructId ::= SEQUENCE {

structIdAndFullId StructIdAndFullId --See page 1066

}

Referenced from: StructTypeDef (p. 1014) StructTypeConstraint (p. 1013)

StructIdAndFullId ::= SEQUENCE {

structIdentifier Identifier --See page 1084

fullIdentifier FullIdentifier OPTIONAL --See page 1083

}

Referenced from: StructId (p. 1066)

SubSet ::= SEQUENCE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: MatchingSymbol (p. 1049)

SubType ::= CHOICE {

parentSubType ParentSubType --See page 1054

setSubType SetSubType --See page 1063

sequenceSubType SequenceSubType --See page 1062

}

Referenced from: ASN1_Type (p. 1027)

SubTypeSpec ::= SEQUENCE OF {

subtypeValueSet SubtypeValueSet --See page 1066

}

Referenced from: PermittedAlphabet (p. 1057) SizeConstraint (p. 1065) ParentSubType (p. 1054) SingleTypeConstraint (p. 1064) ValueConstraint (p. 1077)

SubtypeValueSet ::= CHOICE {

singleValue SingleValue --See page 1065

containedSubType ContainedSubType --See page 1036

valueRange ValueRange --See page 1077

permittedAlphabet PermittedAlphabet --See page 1057

sizeConstraint SizeConstraint --See page 1065

innerTypeConstraints InnerTypeConstraints --See page 1046

}

Referenced from: SubTypeSpec (p. 1066)

SuiteId ::= SEQUENCE {

suiteIdentifier Identifier --See page 1084

}

Referenced from: ASuite (p. 1000)

SuperSet ::= SEQUENCE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: MatchingSymbol (p. 1049)

Tag ::= SEQUENCE {

classType ClassType OPTIONAL --See page 1032

classNumber ClassNumber --See page 1032

}

Referenced from: TaggedType (p. 1067)

TagAttributes ::= CHOICE {

Aimplicit AIMPLICIT --See page 1079

Aexplicit AEXPLICIT --See page 1079

}

Referenced from: TaggedType (p. 1067)

TaggedType ::= SEQUENCE {

tag Tag --See page 1067

tagAttributes TagAttributes OPTIONAL --See page 1067

asn1_Type ASN1_Type --See page 1027

}

Referenced from: BuiltinType (p. 1031)

TC_Role ::= SEQUENCE {

tcomp_Role TComp_Role --See page 1068

}

Referenced from: TCompDcl (p. 1016)

TC_VarId ::= SEQUENCE {

tc_VarIdentifier Identifier --See page 1084

}

Referenced from: TC_VarDcl (p. 1014)

TC_VarType ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

}

Referenced from: TC_VarDcl (p. 1014)

TC_VarValue ::= SEQUENCE {

declarationValue DeclarationValue --See page 1038

}

Referenced from: TC_VarDcl (p. 1014)

TComp_Role ::= CHOICE {

mtc MTC --See page 1086

ptc PTC --See page 1089

}

Referenced from: TC_Role (p. 1067)

TCompConfigId ::= SEQUENCE {

tcompConfigIdentifier Identifier --See page 1084

}

Referenced from: TCompConfigDcl (p. 1015)

TCompId ::= SEQUENCE {

tcompIdentifier Identifier --See page 1084

}

Referenced from: TCompDcl (p. 1016)

TCompIdList ::= SEQUENCE OF {

tCompIdentifier Identifier --See page 1084

}

Referenced from: Done (p. 1040)

TCompUsed ::= SEQUENCE {

tcompIdentifier Identifier --See page 1084

}

Referenced from: TCompConfigInfo (p. 1015)

Term ::= CHOICE {

multExpression MultExpression --See page 1049

factor Factor --See page 1044

}

Referenced from: SimpleExpression (p. 1063) AddExpression (p. 1025) MultExpression (p. 1049)

TestCaseId ::= SEQUENCE {

testCaseIdentifier Identifier --See page 1084

}

Referenced from: CompactTestCase (p. 1002) TestCase (p. 1016)

TestGroupId ::= SEQUENCE {

testGroupIdentifier Identifier --See page 1084

}

Referenced from: TestGroup (p. 1017) CompactTestGroup (p. 1003)

TestGroupRef ::= SEQUENCE {

testGroupReference TestGroupReference --See page 1091

}

Referenced from: TestCase (p. 1016)

TestStepAttachment ::= SEQUENCE {

attach Attach --See page 1029

}

Referenced from: CompactTestCase (p. 1002)

TestStepGroupId ::= SEQUENCE {

testStepGroupIdentifier Identifier --See page 1084

}

Referenced from: TestStepGroup (p. 1018)

TestStepId ::= SEQUENCE {

testStepIdAndParList TestStepIdAndParList --See page 1070

}

Referenced from: TestStep (p. 1017)

TestStepIdAndParList ::= SEQUENCE {

testStepIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: TestStepId (p. 1069)

TestStepRef ::= SEQUENCE {

testStepGroupReference TestStepGroupReference --See page 1092

}

Referenced from: TestStep (p. 1017)

Timeout ::= SEQUENCE {

timerIdentifier Identifier OPTIONAL --See page 1084

}

Referenced from: Event (p. 1043)

TimerId ::= SEQUENCE {

timerIdentifier Identifier --See page 1084

}

Referenced from: TimerDcl (p. 1018)

TimerOp ::= CHOICE {

startTimer StartTimer --See page 1065

cancelTimer CancelTimer --See page 1031

readTimer ReadTimer --See page 1059

}

Referenced from: TimerOps (p. 1070)

TimerOps ::= SEQUENCE OF {

timerOp TimerOp --See page 1070

}

Referenced from: EventStatement (p. 1043)

TimerValue ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: StartTimer (p. 1065)

TimeUnit ::= CHOICE {

picoSeconds PicoSeconds --See page 1088

nanoSeconds NanoSeconds --See page 1087

microSeconds MicroSeconds --See page 1086

milliSeconds MilliSeconds --See page 1086

seconds Seconds --See page 1090

minutes Minutes --See page 1086

}

Referenced from: Unit (p. 1075)

TreeHeader ::= SEQUENCE {

treeIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: Header (p. 1045)

TreeReference ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: Attach (p. 1029) CreateAttach (p. 1037)

TS_ConstId ::= SEQUENCE {

ts_ConstIdentifier Identifier --See page 1084

}

Referenced from: TS_ConstDcl (p. 1019) TS_ConstRef (p. 1019)

TS_ConstType ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

}

Referenced from: TS_ConstDcl (p. 1019) TS_ConstRef (p. 1019)

TS_ConstValue ::= SEQUENCE {

declarationValue DeclarationValue --See page 1038

}

Referenced from: TS_ConstDcl (p. 1019) TS_ConstRef (p. 1019)

TS_OpId ::= SEQUENCE {

ts_OpIdAndParList TS_OpIdAndParList --See page 1072

}

Referenced from: TS_OpDef (p. 1020)

TS_OpIdAndParList ::= SEQUENCE {

ts_OpIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: TS_OpId (p. 1072)

TS_OpResult ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

}

Referenced from: TS_OpDef (p. 1020)

TS_ParId ::= SEQUENCE {

ts_ParIdentifier Identifier --See page 1084

}

Referenced from: TS_ParDcl (p. 1020)

TS_ParType ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

}

Referenced from: TS_ParDcl (p. 1020)

TS_ProcId ::= SEQUENCE {

ts_ProcIdAndParList TS_ProcIdAndParList --See page 1072

}

Referenced from: TS_ProcDef (p. 1021)

TS_ProcIdAndParList ::= SEQUENCE {

ts_ProcIdentifier Identifier --See page 1084

formalParList FormalParList --See page 1044

}

Referenced from: TS_ProcId (p. 1072)

TS_ProcResult ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

}

Referenced from: TS_ProcDef (p. 1021)

TS_VarId ::= SEQUENCE {

ts_VarIdentifier Identifier --See page 1084

}

Referenced from: TS_VarDcl (p. 1022)

TS_VarType ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

}

Referenced from: TS_VarDcl (p. 1022)

TS_VarValue ::= SEQUENCE {

declarationValue DeclarationValue --See page 1038

}

Referenced from: TS_VarDcl (p. 1022)

TTCN_Type ::= CHOICE {

predefinedType PredefinedType --See page 1057

referenceType ReferenceType --See page 1059

}

Referenced from: TypeAndRestriction (p. 1074) TypeAndLengthAttribute (p. 1074) TS_OpResult (p. 1072) TS_ProcResult (p. 1073) TS_ParType (p. 1072) TS_ConstType (p. 1071) TS_VarType (p. 1073) TC_VarType (p. 1068) FormalParType (p. 1045)

TypeAndAttributes ::= CHOICE {

typeAndLengthAttribute TypeAndLengthAttribute --See page 1074

pdu PDU --See page 1088

}

Referenced from: ElemType (p. 1041) ASP_ParType (p. 1029) PDU_FieldType (p. 1056) CM_ParType (p. 1033)

TypeAndLengthAttribute ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

lengthAttribute LengthAttribute OPTIONAL --See page 1047

}

Referenced from: TypeAndAttributes (p. 1073)

TypeAndRestriction ::= SEQUENCE {

ttcn_Type TTCN_Type --See page 1073

restriction Restriction OPTIONAL --See page 1061

}

Referenced from: SimpleTypeDefinition (p. 1064)

TypeAssignment ::= SEQUENCE {

typeReference TypeReference --See page 1074

asn1_Type ASN1_Type --See page 1027

}

Referenced from: TypeAssignmentList (p. 1074)

TypeAssignmentList ::= SEQUENCE OF {

typeAssignment TypeAssignment --See page 1074

}

Referenced from: ASN1_LocalTypes (p. 1027)

TypeConstraints ::= SEQUENCE {

namedConstraintList NamedConstraintList --See page 1050

}

Referenced from: FullSpecification (p. 1045) PartialSpecification (p. 1054)

TypeReference ::= SEQUENCE {

identifier Identifier --See page 1084

}

Referenced from: TypeAssignment (p. 1074)

UnaryExpression ::= SEQUENCE {

unaryOp UnaryOp --See page 1075

primary Primary --See page 1058

}

Referenced from: Factor (p. 1044)

UnaryOp ::= CHOICE {

plus Plus --See page 1089

minus Minus --See page 1086

not Not --See page 1087

}

Referenced from: UnaryExpression (p. 1074)

Unit ::= SEQUENCE {

timeUnit TimeUnit --See page 1071

}

Referenced from: TimerDcl (p. 1018)

UpperBound ::= CHOICE {

bound Bound --See page 1031

infinity INFINITY --See page 1085

}

Referenced from: RangeLength (p. 1058)

UpperEndpoint ::= SEQUENCE {

upperEndValue UpperEndValue --See page 1075

inclusive INCLUSIVE OPTIONAL --See page 1085

}

Referenced from: ValueRange (p. 1077)

UpperEndValue ::= CHOICE {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

max Max --See page 1086

}

Referenced from: UpperEndpoint (p. 1075)

UpperRangeBound ::= CHOICE {

constraintExpression ConstraintExpression --See page 1035

infinity INFINITY --See page 1085

}

Referenced from: ValRange (p. 1076)

UpperTypeBound ::= CHOICE {

signedNumber SignedNumber --See page 1063

number Number --See page 1087

infinity INFINITY --See page 1085

}

Referenced from: RangeTypeLength (p. 1058) IntegerRange (p. 1046)

UpperValueBound ::= CHOICE {

valueBound ValueBound --See page 1077

infinity INFINITY --See page 1085

}

Referenced from: RangeValueLength (p. 1058)

UsefulType ::= CHOICE {

generalizedTime GeneralizedTime --See page 1083

utcTime UTCTime --See page 1092

external EXTERNAL --See page 1082

objectDescriptor ObjectDescriptor --See page 1087

}

Referenced from: BuiltinType (p. 1031)

ValRange ::= SEQUENCE {

lowerRangeBound LowerRangeBound --See page 1048

upperRangeBound UpperRangeBound --See page 1075

}

Referenced from: MatchingSymbol (p. 1049)

Value ::= CHOICE {

literalValue LiteralValue --See page 1048

asn1_Value ASN1_Value --See page 1028

}

Referenced from: Primary (p. 1058)

ValueAttributes ::= SEQUENCE {

valueLength ValueLength OPTIONAL --See page 1077

if_PRESENT IF_PRESENT OPTIONAL --See page 1085

}

Referenced from: ConstraintValueAndAttributes (p. 1036)

ValueBound ::= CHOICE {

number Number --See page 1087

identifier Identifier --See page 1084

}

Referenced from: SingleValueLength (p. 1065) LowerValueBound (p. 1049) UpperValueBound (p. 1076)

ValueConstraint ::= SEQUENCE {

subTypeSpec SubTypeSpec --See page 1066

}

Referenced from: Constraint (p. 1035)

ValueLength ::= CHOICE {

singleValueLength SingleValueLength --See page 1065

rangeValueLength RangeValueLength --See page 1058

}

Referenced from: ValueAttributes (p. 1076)

ValueList ::= SEQUENCE OF {

constraintValueAndAttributes ConstraintValueAndAttributes --See page 1036

}

Referenced from: MatchingSymbol (p. 1049) Complement (p. 1033) Permutation (p. 1057)

ValueRange ::= SEQUENCE {

lowerEndpoint LowerEndpoint --See page 1048

upperEndpoint UpperEndpoint --See page 1075

}

Referenced from: SubtypeValueSet (p. 1066)

VariationDefault ::= SEQUENCE {

expression Expression --See page 1044

}

Referenced from: EncodingVariation (p. 1007)

VariationRef ::= SEQUENCE {

variationReference VariationReference --See page 1092

}

Referenced from: EncodingVariation (p. 1007)

Verdict ::= CHOICE {

pass Pass --See page 1054

fail Fail --See page 1044

inconclusive Inconclusive --See page 1046

result Result --See page 1061

}

Referenced from: VerdictId (p. 1078)

VerdictId ::= SEQUENCE {

verdict Verdict --See page 1078

}

Referenced from: BehaviourLine (p. 1001)

WithComponent ::= SEQUENCE {

singleTypeConstraint SingleTypeConstraint --See page 1064

}

Referenced from: InnerTypeConstraints (p. 1046)

WithComponents ::= SEQUENCE {

multipleTypeConstraints MultipleTypeConstraints --See page 1049

}

Referenced from: InnerTypeConstraints (p. 1046)


Terminal Nodes

This section contains all the Terminal Nodes. A Terminal Node is defined to be a node without children in the Parse Tree, and they generally represents some actual piece of text in the field. The Identifier class is a good example of a Terminal Node. It is the Access representation of a name or identifier. The Terminal Nodes have some special properties, they can be printed directly, yielding the piece of text they represent, and their positions in the field string can be easily found. The Identifier is a special Terminal Node since all Identifiers have an type which is information about in what table the identifier was declared (or Unknown if this could not be found during analysis).

ABSENT ::= TERMINAL

Referenced from: PresenceConstraint (p. 1057)

AEXPLICIT ::= TERMINAL

Referenced from: TagAttributes (p. 1067)

AFalse ::= TERMINAL

Referenced from: BooleanValue (p. 1030)

AIMPLICIT ::= TERMINAL

Referenced from: TagAttributes (p. 1067)

And ::= TERMINAL

Referenced from: MultOp (p. 1050)

ANY ::= TERMINAL

Referenced from: AnyType (p. 1026)

AnyOrOmit ::= TERMINAL

Referenced from: MatchingSymbol (p. 1049)

ANYValue ::= TERMINAL

Referenced from: MatchingSymbol (p. 1049)

APPLICATION ::= TERMINAL

Referenced from: ClassType (p. 1032)

ASN1_ModuleId ::= TERMINAL

Referenced from: ASN1_TypeRef (p. 999) TS_ConstRef (p. 1019) ASN1_ASP_TypeDefByRef (p. 995) ASN1_PDU_TypeDefByRef (p. 997)

ASN1_TypeReference ::= TERMINAL

Referenced from: ASN1_TypeRef (p. 999) ASN1_ASP_TypeDefByRef (p. 995) ASN1_PDU_TypeDefByRef (p. 997)

ASN1_ValueReference ::= TERMINAL

Referenced from: TS_ConstRef (p. 1019)

ATrue ::= TERMINAL

Referenced from: BooleanValue (p. 1030)

BITSTRING ::= TERMINAL

Referenced from: PredefinedType (p. 1057)

BOOLEAN ::= TERMINAL

Referenced from: PredefinedType (p. 1057)

BooleanType ::= TERMINAL

Referenced from: BuiltinType (p. 1031)

Bstring ::= TERMINAL

Referenced from: LiteralValue (p. 1048)

Comment ::= TERMINAL

Referenced from: ASN1_CM_Constraint (p. 996) CompactTestCase (p. 1002) TestCase (p. 1016) BehaviourLine (p. 1001) TestStep (p. 1017) DefaultCase (p. 1004) SuiteStructure (p. 1014) EncodingDefinition (p. 1006) EncodingVariationSet (p. 1008) EncodingVariation (p. 1007) InvalidFieldEncodingDef (p. 1008) SimpleTypeDef (p. 1011) StructTypeDef (p. 1014) ElemDcl (p. 1006) ASN1_TypeDef (p. 998) ASN1_TypeRef (p. 999) TS_OpDef (p. 1020) TS_ProcDef (p. 1021) TS_ParDcl (p. 1020) SelectExprDef (p. 1011) TS_ConstDcl (p. 1019) TS_ConstRef (p. 1019) TS_VarDcl (p. 1022) TC_VarDcl (p. 1014) TCompDcl (p. 1016) TCompConfigDcl (p. 1015) TCompConfigInfo (p. 1015) PCO_TypeDcl (p. 1009) PCO_Dcl (p. 1009) CP_Dcl (p. 1003) TimerDcl (p. 1018) TTCN_ASP_TypeDef (p. 1023) ASP_ParDcl (p. 999) ASN1_ASP_TypeDef (p. 995) ASN1_ASP_TypeDefByRef (p. 995) TTCN_PDU_TypeDef (p. 1024) PDU_FieldDcl (p. 1010) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefByRef (p. 997) TTCN_CM_TypeDef (p. 1023) CM_ParDcl (p. 1001) ASN1_CM_TypeDef (p. 996) AliasDef (p. 994) StructTypeConstraint (p. 1013) ElemValue (p. 1006) ASN1_TypeConstraint (p. 998) TTCN_ASP_Constraint (p. 1022) ASP_ParValue (p. 1000) TTCN_PDU_Constraint (p. 1024) PDU_FieldValue (p. 1010) ASN1_ASP_Constraint (p. 994) ASN1_PDU_Constraint (p. 996) TTCN_CM_Constraint (p. 1023) CM_ParValue (p. 1002)

CP ::= TERMINAL

Referenced from: FormalParType (p. 1045)

Cstring ::= TERMINAL

Referenced from: LiteralValue (p. 1048)

DefaultGroupReference ::= TERMINAL

Referenced from: DefaultRef (p. 1039)

Description ::= TERMINAL

Referenced from: CompactTestCase (p. 1002) TestCase (p. 1016) TestStep (p. 1017) DefaultCase (p. 1004)

DetailedComment ::= TERMINAL

Referenced from: SuiteStructure (p. 1014) TestCaseIndex (p. 1016) TestStepIndex (p. 1018) DefaultIndex (p. 1005) EncodingDefinitions (p. 1007) EncodingVariationSet (p. 1008) InvalidFieldEncodingDef (p. 1008) SimpleTypeDefs (p. 1012) StructTypeDef (p. 1014) ASN1_TypeDef (p. 998) ASN1_TypeRefs (p. 999) TS_OpDef (p. 1020) TS_ProcDef (p. 1021) TS_ParDcls (p. 1021) SelectExprDefs (p. 1011) TS_ConstDcls (p. 1019) TS_ConstRefs (p. 1020) TS_VarDcls (p. 1022) TC_VarDcls (p. 1015) TCompDcls (p. 1016) TCompConfigDcl (p. 1015) PCO_TypeDcls (p. 1009) PCO_Dcls (p. 1009) CP_Dcls (p. 1004) TimerDcls (p. 1019) TTCN_ASP_TypeDef (p. 1023) ASN1_ASP_TypeDef (p. 995) ASN1_ASP_TypeDefsByRef (p. 995) TTCN_PDU_TypeDef (p. 1024) ASN1_PDU_TypeDef (p. 997) ASN1_PDU_TypeDefsByRef (p. 998) TTCN_CM_TypeDef (p. 1023) ASN1_CM_TypeDef (p. 996) AliasDefs (p. 994) StructTypeConstraint (p. 1013) ASN1_TypeConstraint (p. 998) TTCN_ASP_Constraint (p. 1022) TTCN_PDU_Constraint (p. 1024) ASN1_ASP_Constraint (p. 994) ASN1_PDU_Constraint (p. 996) TTCN_CM_Constraint (p. 1023) ASN1_CM_Constraint (p. 996) TestCase (p. 1016) TestStep (p. 1017) DefaultCase (p. 1004)

Div ::= TERMINAL

Referenced from: MultOp (p. 1050)

Encoding_TypeList ::= TERMINAL

Referenced from: EncodingVariationSet (p. 1008) InvalidFieldEncodingDef (p. 1008)

EncodingReference ::= TERMINAL

Referenced from: EncodingRef (p. 1041)

Equal ::= TERMINAL

Referenced from: RelOp (p. 1060)

EXTERNAL ::= TERMINAL

Referenced from: UsefulType (p. 1076)

FAIL ::= TERMINAL

Referenced from: Fail (p. 1044) R_Value (p. 1058)

FullIdentifier ::= TERMINAL

Referenced from: StructIdAndFullId (p. 1066) ElemIdAndFullId (p. 1041) ASN1_TypeId (p. 1028) ASP_IdAndFullId (p. 1028) ASP_ParIdAndFullId (p. 1029) PDU_IdAndFullId (p. 1057) PDU_FieldIdAndFullId (p. 1056) CM_ParIdAndFullId (p. 1033)

GeneralizedTime ::= TERMINAL

Referenced from: UsefulType (p. 1076)

GeneralString ::= TERMINAL

Referenced from: CharacterString (p. 1032)

GraphicString ::= TERMINAL

Referenced from: CharacterString (p. 1032)

Greater ::= TERMINAL

Referenced from: RelOp (p. 1060)

GreaterOrEqual ::= TERMINAL

Referenced from: RelOp (p. 1060)

HEXSTRING ::= TERMINAL

Referenced from: PredefinedType (p. 1057)

Hstring ::= TERMINAL

Referenced from: LiteralValue (p. 1048)

IA5String ::= TERMINAL

Referenced from: CharacterString (p. 1032)

Identifier ::= TERMINAL

Referenced from: Send (p. 1062) ImplicitSend (p. 1045) Receive (p. 1059) Receive (p. 1059) Otherwise (p. 1053) Timeout (p. 1070) TCompIdList (p. 1068) StartTimer (p. 1065) CancelTimer (p. 1031) ReadTimer (p. 1059) TreeReference (p. 1071) CreateTComp (p. 1037) ConstraintReference (p. 1035) ConsRef (p. 1035) TreeHeader (p. 1071) TestGroupId (p. 1069) TestStepGroupId (p. 1069) TestStepIdAndParList (p. 1070) DefaultGroupId (p. 1038) DefaultIdAndParList (p. 1038) ValueBound (p. 1077) DataObjectReference (p. 1038) ComponentIdentifier (p. 1033) BitIdentifier (p. 1030) OpCall (p. 1053) TypeReference (p. 1074) DefinedType (p. 1039) NamedNumber (p. 1050) IdOrNum (p. 1045) NamedType (p. 1051) SelectionType (p. 1061) SuiteId (p. 1067) SO_SuiteId (p. 1065) EncVariationIdAndParList (p. 1042) InvalidFieldEncodingIdAndParList (p. 1047) SimpleTypeId (p. 1064) ReferenceType (p. 1059) AnyDefinedBy (p. 1026) EncVariationCall (p. 1042) NamedConstraint (p. 1050) InvalidFieldEncodingCall (p. 1046) IdentifierList (p. 1045) EncodingRuleId (p. 1041) NamedValue (p. 1051) NameForm (p. 1051) DefinedValue (p. 1039) FormalParIdList (p. 1044) EncRuleId (p. 1042) PDU_EncodingId (p. 1055) StructIdAndFullId (p. 1066) ElemIdAndFullId (p. 1041) Bound (p. 1031) ASN1_TypeId (p. 1028) TS_OpIdAndParList (p. 1072) TS_ProcIdAndParList (p. 1072) TS_ParId (p. 1072) SelectExprId (p. 1061) TS_ConstId (p. 1071) TS_VarId (p. 1073) TC_VarId (p. 1067) TCompId (p. 1068) TCompConfigId (p. 1068) TCompUsed (p. 1068) PCO_List (p. 1054) CP_List (p. 1037) PCO_Id (p. 1054) PCO_TypeId (p. 1055) CP_Id (p. 1037) TimerId (p. 1070) ASP_IdAndFullId (p. 1028) PCO_Type (p. 1055) ASP_ParIdAndFullId (p. 1029) PDU_IdAndFullId (p. 1057) PDU_FieldIdAndFullId (p. 1056) CM_Id (p. 1033) CM_ParIdAndFullId (p. 1033) AliasId (p. 1026) Expansion (p. 1043) ConsIdAndParList (p. 1035) DerivationPath (p. 1040) TestCaseId (p. 1069) Configuration (p. 1034) SelExprId (p. 1062) DefaultReference (p. 1039) Label (p. 1047) Send (p. 1062)

Impl. Note: Every Identifier has an associated type, which refers to the context where the Identifier was declared. If, for example, an Identifier refers to a TTCN ASP declaration table, then its type will be Choices::_TTCN_ASP, and if the Identifier refers to a parameter of a constraint or test step, then its type will be Choices::_FormalParam_Id. The associated type is reached through the member function Identifier::choice().

Identifier types: Alias ASN1_ASP ASN1_ASP_Cons ASN1_Cons ASN1_CM ASN1_CM_Cons ASN1_PDU ASN1_PDU_Cons ASN1_LocalType ASN1_NamedType ASN1_NameForm ASN1_Type ASP_Par BitString_NamedNumber CM_Par CP DefaultCase DefaultGroup Elem Enumeration_NamedNumber FormalParam Integer_NamedNumber Label LocalTree PCO PCO_Type PredefinedOp PDU_Field Result SelectExpr SimpleType StructType StructCons Suite TC_Var TComp TCompConfig TestCase TestStep TestStepGroup TestGroup Timer TS_Const TS_Op TS_Par TS_Var TTCN_ASP TTCN_ASP_Cons TTCN_CM TTCN_CM_Cons TTCN_PDU TTCN_PDU_Cons Unknown Verdict

IF_PRESENT ::= TERMINAL

Referenced from: ValueAttributes (p. 1076)

INCLUSIVE ::= TERMINAL

Referenced from: LowerEndpoint (p. 1048) UpperEndpoint (p. 1075)

INCONC ::= TERMINAL

Referenced from: Inconclusive (p. 1046) R_Value (p. 1058)

INFINITY ::= TERMINAL

Referenced from: UpperTypeBound (p. 1076) UpperBound (p. 1075) UpperRangeBound (p. 1075) UpperValueBound (p. 1076)

INTEGER ::= TERMINAL

Referenced from: PredefinedType (p. 1057)

InvalidFieldEncodingDefinition ::= TERMINAL

Referenced from: InvalidFieldEncodingDef (p. 1008)

ISO646String ::= TERMINAL

Referenced from: CharacterString (p. 1032)

Less ::= TERMINAL

Referenced from: RelOp (p. 1060)

LessOrEqual ::= TERMINAL

Referenced from: RelOp (p. 1060)

LT ::= TERMINAL

Referenced from: PCO_Role (p. 1055)

MacroSymbol ::= TERMINAL

Referenced from: ASP_ParIdOrMacro (p. 1029) PDU_FieldIdOrMacro (p. 1056) CM_ParIdOrMacro (p. 1033)

Max ::= TERMINAL

Referenced from: UpperEndValue (p. 1075)

MicroSeconds ::= TERMINAL

Referenced from: TimeUnit (p. 1071)

MilliSeconds ::= TERMINAL

Referenced from: TimeUnit (p. 1071)

Min ::= TERMINAL

Referenced from: LowerEndValue (p. 1048)

Minus ::= TERMINAL

Referenced from: AddOp (p. 1025) UnaryOp (p. 1075) SignedNumber (p. 1063)

Minus_INFINITY ::= TERMINAL

Referenced from: SpecialRealValue (p. 1065)

MinusINFINITY ::= TERMINAL

Referenced from: LowerTypeBound (p. 1048) LowerRangeBound (p. 1048)

Minutes ::= TERMINAL

Referenced from: TimeUnit (p. 1071)

Mod ::= TERMINAL

Referenced from: MultOp (p. 1050)

MTC ::= TERMINAL

Referenced from: TComp_Role (p. 1068)

Mult ::= TERMINAL

Referenced from: MultOp (p. 1050)

NanoSeconds ::= TERMINAL

Referenced from: TimeUnit (p. 1071)

NONE ::= TERMINAL

Referenced from: R_Value (p. 1058)

Not ::= TERMINAL

Referenced from: UnaryOp (p. 1075)

NotEqual ::= TERMINAL

Referenced from: RelOp (p. 1060)

NullType ::= TERMINAL

Referenced from: BuiltinType (p. 1031)

NullValue ::= TERMINAL

Referenced from: ASN1_Value (p. 1028)

Number ::= TERMINAL

Referenced from: SingleTypeLength (p. 1064) LowerTypeBound (p. 1048) UpperTypeBound (p. 1076) Bound (p. 1031) Num_PCOs (p. 1052) Num_CPs (p. 1052) LineNumber (p. 1047) Indentation (p. 1046) ValueBound (p. 1077) ComponentPosition (p. 1034) LiteralValue (p. 1048) IdOrNum (p. 1045) ClassNumber (p. 1032) NumberForm (p. 1052) Mantissa (p. 1049) Exponent (p. 1043) SignedNumber (p. 1063)

NumericString ::= TERMINAL

Referenced from: CharacterString (p. 1032)

ObjectDescriptor ::= TERMINAL

Referenced from: UsefulType (p. 1076)

ObjectIdentifierType ::= TERMINAL

Referenced from: BuiltinType (p. 1031)

Objective ::= TERMINAL

Referenced from: TestGroup (p. 1017) CompactTestGroup (p. 1003) TestStep (p. 1017) DefaultCase (p. 1004)

OCTETSTRING ::= TERMINAL

Referenced from: PredefinedType (p. 1057)

OctetStringType ::= TERMINAL

Referenced from: BuiltinType (p. 1031)

OMIT ::= TERMINAL

Referenced from: Omit (p. 1053)

OPTIONAL ::= TERMINAL

Referenced from: NamedTypeAttribute (p. 1051) PresenceConstraint (p. 1057)

Or ::= TERMINAL

Referenced from: AddOp (p. 1025)

Ostring ::= TERMINAL

Referenced from: LiteralValue (p. 1048)

PASS ::= TERMINAL

Referenced from: Pass (p. 1054) R_Value (p. 1058)

PDU ::= TERMINAL

Referenced from: TypeAndAttributes (p. 1073) FormalParType (p. 1045)

PicoSeconds ::= TERMINAL

Referenced from: TimeUnit (p. 1071)

PICS_PIXITref ::= TERMINAL

Referenced from: TS_ParDcl (p. 1020)

Plus ::= TERMINAL

Referenced from: AddOp (p. 1025) UnaryOp (p. 1075)

Plus_INFINITY ::= TERMINAL

Referenced from: SpecialRealValue (p. 1065)

PreliminaryFAIL ::= TERMINAL

Referenced from: Fail (p. 1044)

PreliminaryINCONC ::= TERMINAL

Referenced from: Inconclusive (p. 1046)

PreliminaryPASS ::= TERMINAL

Referenced from: Pass (p. 1054)

PRESENT ::= TERMINAL

Referenced from: PresenceConstraint (p. 1057)

PrintableString ::= TERMINAL

Referenced from: CharacterString (p. 1032)

PRIVATE_ ::= TERMINAL

Referenced from: ClassType (p. 1032)

PTC ::= TERMINAL

Referenced from: TComp_Role (p. 1068)

R ::= TERMINAL

Referenced from: Result (p. 1061)

R_TYPE ::= TERMINAL

Referenced from: PredefinedType (p. 1057)

RealType ::= TERMINAL

Referenced from: BuiltinType (p. 1031)

RETURN_ ::= TERMINAL

Referenced from: Construct (p. 1036)

Seconds ::= TERMINAL

Referenced from: TimeUnit (p. 1071)

SO_DefaultId ::= TERMINAL

Referenced from: SO_DefIndex (p. 1012)

SO_DefaultRef ::= TERMINAL

Referenced from: SO_DefIndex (p. 1012)

SO_Description ::= TERMINAL

Referenced from: SO_CaseIndex (p. 1012) SO_StepIndex (p. 1012) SO_DefIndex (p. 1012)

SO_Objective ::= TERMINAL

Referenced from: SO_StructureAndObjective (p. 1013)

SO_PICSRef ::= TERMINAL

Referenced from: SuiteStructure (p. 1014)

SO_PIXITRef ::= TERMINAL

Referenced from: SuiteStructure (p. 1014)

SO_SelExprId ::= TERMINAL

Referenced from: SO_StructureAndObjective (p. 1013) SO_CaseIndex (p. 1012)

SO_StandardsRef ::= TERMINAL

Referenced from: SuiteStructure (p. 1014)

SO_TestCaseId ::= TERMINAL

Referenced from: SO_CaseIndex (p. 1012)

SO_TestGroupRef ::= TERMINAL

Referenced from: SO_StructureAndObjective (p. 1013) SO_CaseIndex (p. 1012)

SO_TestMethods ::= TERMINAL

Referenced from: SuiteStructure (p. 1014)

SO_TestStepId ::= TERMINAL

Referenced from: SO_StepIndex (p. 1012)

SO_TestStepRef ::= TERMINAL

Referenced from: SO_StepIndex (p. 1012)

T61String ::= TERMINAL

Referenced from: CharacterString (p. 1032)

TeletexString ::= TERMINAL

Referenced from: CharacterString (p. 1032)

Ten ::= TERMINAL

Referenced from: Base (p. 1030)

TestGroupReference ::= TERMINAL

Referenced from: TestGroupRef (p. 1069)

TestPurpose ::= TERMINAL

Referenced from: CompactTestCase (p. 1002) TestCase (p. 1016)

TestStepGroupReference ::= TERMINAL

Referenced from: TestStepRef (p. 1070)

TIMER ::= TERMINAL

Referenced from: FormalParType (p. 1045)

TS_OpDescription ::= TERMINAL

Referenced from: TS_OpDef (p. 1020)

TS_ProcDescription ::= TERMINAL

Referenced from: TS_ProcDef (p. 1021)

Two ::= TERMINAL

Referenced from: Base (p. 1030)

UNIVERSAL ::= TERMINAL

Referenced from: ClassType (p. 1032)

UT ::= TERMINAL

Referenced from: PCO_Role (p. 1055)

UTCTime ::= TERMINAL

Referenced from: UsefulType (p. 1076)

VariationReference ::= TERMINAL

Referenced from: VariationRef (p. 1077)

VideotexString ::= TERMINAL

Referenced from: CharacterString (p. 1032)

VisibleString ::= TERMINAL

Referenced from: CharacterString (p. 1032)


25 The TTCN Browser (on UNIX)

This chapter contains a reference manual to the TTCN Browser. The Browser presents an overview of the TTCN document. In the Browser, it is possible to edit the TTCN document structure, to determine which parts of the document to view, and to apply different tools.

The functionality of the Browser, the menus, windows and quick buttons, are described in this chapter. The TTCN Table Editor is described in 26 The TTCN Table Editor (on UNIX). How to analyze and find tables is described in 27 Analyzing TTCN Documents (on UNIX).

For an overview of the TTCN suite, see Introduction to the TTCN Suite (on UNIX).

Note: UNIX version

This is the UNIX version of the chapter. The corresponding Windows chapter is 31 Editing TTCN Documents (in Windows).


Introduction to the TTCN Browser

The TTCN Browser is the part of the TTCN suite that presents TTCN document structures. When a new TTCN document is opened, place holders for the static parts of the document are already created. Then you can add and delete the dynamic parts.

The amount of information actually displayed in a Browser can be collapsed and expanded. It is also possible to display selected parts of the TTCN document in a sub Browser. You open a sub Browser from the main Browser or from another sub Browser.

The functionality of a menu choice is applied to all items or selections of items in the Browser. If an operation is invoked from the Organizer (see 2 The Organizer), it is always applied to all items in the TTCN document.

Opening the Browser and a TTCN Document

You open the TTCN Browser by selecting a TTCN document already included in the Organizer followed by the menu choice Edit, or by double-clicking the TTCN document. You may also add a new TTCN document with Add New or Add Existing from the Edit menu, or start a Browser directly by selecting Editors > TTCN Browser from the Tools menu. See 2 The Organizer for more information.


The Browser User Interface

For a general description of the Telelogic Tau user interface, see 1 User Interface and Basic Operations.

The TTCN document in the Browser contains items. These are:

  • Static items, common to every TTCN document, such as the declarations part or constraints part.
  • Dynamic items - that is TTCN objects - such as tables, groups or objects in a table, for example test case variables.

The Browser displays all the static items in the order defined in the TTCN standard. This ordering cannot be changed. For example, it is not possible to have the constraints part coming before the declarations part. Only the dynamic items - the tables - may be added and deleted. The structure is indicated by indention.

Figure 186 : The the TTCN Browser window on UNIX

Figure 186 depicts the Browser window. The test suite overview, the import part, the declarations part, the constraints part, the test cases and the defaults library are collapsed. This is indicated by the three dots.

The dynamic part and the test step library are expanded. The test step library contains two test steps: LT and UT. LT has been edited but not analyzed. This is indicated by the shaded bar (gray on a color screen). The table icon indicates that UT is opened and the filled bar (red on a color screen) that UT has been analyzed and is erroneous. Items with no analysis bars have been analyzed and contain no errors.

Items in bold font represent the static (or structural) parts of the TTCN document and cannot be opened or edited. The items in normal font represent named TTCN tables which can be opened and edited.

Some of the static items may remain unused. For example, if Test Case Variables is not used it will still be displayed in the Browser. However, it will not be printed or output in the TTCN-MP format.


Controlling the Items in the Browser

Selecting Items

There is a difference between selection and input focus. Selection is an inverted item or text string. The input focus is indicated by a rectangular border surrounding the relevant item. Keyboard commands operate on the item with input focus, not the selection.

Point and click once to select a single item in a Browser - note that this also sets the input focus. Selecting a new item will deselect the previous item (if any).

To select several items, press <Ctrl> while selecting items. Note that the input focus is set to the last selected item. Pressing <Ctrl> while selecting items works in toggle mode: a selected item will be deselected and vice versa.

When clicking the middle mouse button, the input focus will be set to the new item. The selection will not be changed.

You can also select items by using:

  • The popup menus, see "Using Popup Menus" .
  • Selector, see "Using More Complex Selections" .
  • Compare, see "Comparing TTCN Documents" .

Hint:

Some of the commands in the TTCN suite only work when a single item is selected in a Browser. Before applying such commands, it is recommended that you deselect all items before you select a single item.

Controlling What is Displayed

The View menu is used for deciding how much of the test suite that should be displayed in a Browser. This is useful when you work with large test suites. This menu also contains commands to access any opened Table Editor and to close all opened editors, as well as to access any loaded TTCN document.

View > Collapse

Hides all items under the marked item. A collapsed item is indicated by an ellipsis (...). A shortcut for Collapse is to type <c> without invoking the View menu.

View > Expand

Displays all items at the next level below the marked item. A short-cut for Expand is to type <e> without invoking the View menu.

View > Expand Tree

Displays all items at all levels below the marked item. A short-cut for Expand Tree is to type <Shift+e> without invoking the View menu.

View > Close All Editors

Closes all open Table Editors, regardless of which document they belong to.

View > Show Editor

This sub menu presents a list of all open Table Editors, in any TTCN document. By selecting an item in this list, the corresponding Table Editor is brought forward.

View > Show Document

This sub menu presents a list of all loaded TTCN documents. By selecting an item in this list, the main Browser of the corresponding document is brought forward.

Creating a Sub Browser

Sub Browsers may be created to display selected portions of a test suite. These selections may be made manually or with the Selector (see above).

This facility is useful when working with a large test suite or with items that fulfil certain criteria.

Tools > Browser

Causes a sub Browser to be displayed containing only the selected items from this Browser. There is no limit on the number of sub Browsers that may be displayed.

Note:

Closing the main Browser also closes any sub Browsers that are opened.


Editing the TTCN Document Structure

The TTCN suite displays all the components of a TTCN document in the structured format of the Browser. Part of this structure is static and common to every TTCN document. This static structure is automatically generated when the TTCN document is first created.

To build an individual TTCN document, named tables (such as PDUs, Constraints and Behaviours) and named objects to the multi-object tables (such as Test Case Variables, PCOs and Timers) must be added to this static structure.

The Edit menu is used to add, delete, copy, cut, paste etc. editable items (i.e. groups, tables or objects in a multiple object table) in a Browser.

Adding and Inserting Items

Edit > Add

Adds a new table to the Browser or adds an object to a table in the Browser.

In the case of single-object tables, select the Browser item that "holds" the table. Choosing Add will add a new table to the end of the list of tables. The new table will be unnamed. Use the Rename command to give the table its correct name, or open the table and edit the name there.

Example 184

To add a new TTCN PDU to a Browser, select the item TTCN PDU Type Definitions and apply Add.

In the case of multiple-object tables, select the item that is the name of the table. Choosing Add will add a new object to the end of the list of objects in this table. The new object will be unnamed. Use the Rename command to give the table its correct name, or open the table and edit the name there.

Example 185

To add a new Test Case Variable to a Browser, select the item Test Case Variables item and apply Add.

Edit > Insert Before

Similar to Add but the new table (or object in a table) is inserted before a selected table (or selected object).

Note:

Only a single item should be selected.

Edit > Insert After

Similar to Add but the new table (or object in a table) is inserted after a selected table (or selected object).

Note:

Only a single item should be selected.

Adding and Inserting Groups

The following commands are used to add/insert new groups to the Test Case, Test Step and Default libraries.

Edit > Add Group

Adds a new Test (Case) Group, a new Test Step Group or a new Default Group in the Dynamic Part. The new group is added at the next level after the selected group.

Use the Rename command to edit the temporary name NoName. Note that the trailing slash (/) is automatically added.

To add a table to a group, select the group and use the Add command.

Edit > Insert Group Before

Inserts a new group before a selected item.

Edit > Insert Group After

Inserts a new group after a selected item.

Adding and Inserting Compact Tables

It is possible to specify that all the Test Cases in a given group are displayed in the compact format (see Annex C, clause C.3 of ISO/IEC 9646-3). The following commands allow the insertion of compact groups in the test suite hierarchy:

Edit > Add Compact Group

Adds a compact group at the next level after the selected group.

Edit > Insert Compact Group Before

Inserts a compact group before a selected item.

Edit > Insert Compact Group After

Inserts a compact group after a selected item.

Sorting Items

The places where the Add command may be used, may also be sorted.

Edit > Sort

Sort the list of items below the selected item lexicographically.

Cutting, Copying and Pasting Items

Editable items may be cut or copied to the clipboard. The contents of the clipboard may be pasted according to compatible classes, for example:

  • Test Suite Parameters, Test Suite Constants, Test Suite Variables and Test Case Variables may be pasted into each other.
  • TTCN ASP, PDU, Structured Type and CM Definitions may be pasted into each other and into TTCN ASP, PDU, Structured Type and CM Constraints (and vice versa).
  • ASN.1 ASP, PDU, Structured Type and CM Definitions may be pasted into each other and into ASN.1 ASP, PDU, Structured Type and CM Constraints (and vice versa).
  • Test Case, Test Step and Default Behaviours may be pasted into each other.

However, it is not possible to paste a Constraint for example as a Test Case Behaviour.

The Paste command is not available if the clipboard contains an object of an incompatible type to the selected object.

Note:

On the table row and text levels, no paste restrictions apply.

Edit > Cut

Deletes the selected items from the Browser and stores them in the clipboard.

Edit > Copy

Copies selected items from the Browser to the clipboard.

Edit > Paste Before

Pastes the contents of the clipboard before a selected item.

Edit > Paste After

Pastes the contents of the clipboard after a selected item.

Edit > Paste In

Pastes the contents of the clipboard to the end of a list of tables (or list of objects in a multi-object table).

Deleting Items

Editable items may be removed from the Browser.

Edit > Delete

Deletes selected items from the Browser.

Caution!

The TTCN suite has no undo so this command is irreversible.

Browser Shortcut Keys for Navigation

The cursor and mouse may be used to set the input focus on an item in a Browser. However, you may find the following shortcut keys more useful:

  • <Down Arrow> moves the input focus to the next item. This movement is not sensitive to the structure of a Browser.
  • <Shift+Down Arrow> moves the input focus to the next item at the same level of indentation.
  • <Up Arrow> moves the input focus to the previous item. This movement is not sensitive to the structure of a Browser.
  • <Shift+Up Arrow> moves the input focus to the previous item at the same level of indentation.
  • <Left Arrow> moves the input focus to the previous level of indentation.
  • <Shift+Left Arrow> moves the input focus to the previous level of indentation and collapses that branch in a Browser.
  • <Right> moves the input focus to the first item at the next level of indentation. If the next level is collapsed then it is automatically expanded.
  • <Shift+Right Arrow> moves the input focus to the last item at the next level of indentation. If the next level is collapsed then it is automatically expanded.

Renaming Dynamic Items

The Rename command is used to give names to newly created Browser items that have the temporary name NoName or to rename existing Browser items. It is available in the popup menu for the item.

Rename

Renames the dynamic item. A text box with a cursor appears for the item. Type the new name and then press <Return>. It is also possible to copy, cut, paste and delete text.

  • <Copy> or <L6> on a Sun keyboard copies selected text.
  • <Cut> or <L10> on a Sun keyboard cuts selected text. <Ctrl+k> cuts text from the current position to the end of the line.
  • <Paste> or <L8> on a Sun keyboard pastes text that is stored in the paste buffer. <Ctrl+y> pastes the most recently cut line at the current position.
  • <Delete> or <Backspace> deletes one character to the left of the insertion point. <Ctrl+d> deletes one character to the right of the insertion point.

Note:

The TTCN suite has no undo function. This means that <Undo> has no effect.

A shortcut for Rename is to type <r> without invoking the pop-up menu. The item with the input focus will then be renamed.


Opening a Table

A table is opened from a Browser when you double click on the specific item. Observe that this command has the additional effect of deselecting every item in the Browser. If this additional effect is undesirable, it can be inhibited by holding down <Ctrl> simultaneously.

In the case of single-object tables, point to the table name (e.g. Test Case name). To open a multiple-object table, point to a Browser item that is the title of the table (e.g. Test Case Variables) or to an object in the table (e.g. a Test Case Variable name).

In the case of collapsed items, point and double-click to expand the item (e.g. displaying all items at the next level below the pointed item). A double-click on a group table (regardless if it is collapsed or not) opens the group table. If the item pointed at is a leaf node that is not a table, the double-click will instead create a new item below it.

Alternatively, you may point and click once with the middle mouse button (i.e. set the input focus) and then press <t> to open the table. Note that the input focus can also be set with shortcut keys. See "Key and Button Bindings" .

If a table has previously been opened, but it is for some reason hard to get at, it may be brought forward by selecting the name of the table in the submenu Show Editor of the menu View.


Printing a TTCN Document

To print a TTCN document:
  • Select Print from the File menu.
    • The shortcut is <Ctrl+P>.

For more information, see "The Print Dialogs in the TTCN Suite" .


Requesting License Information

Help > License Info

The TTCN suite consists of several tools and for running each tool it is required that the appropriate license is installed. The the TTCN suite License Information dialog is used to list these licenses.

Figure 187 : The Information dialog

  • Clicking Recompute List retrieves the list of licensees and lists them in the scrollable area below.
  • The Licensees area shows a list of licensees and the licenses available.


Using Popup Menus

Node Specific Popup Menu

This menu is shown when you point to an item in the Browser and click the right mouse button. Most of the commands are also available in the main menu bar. The commands in this menu are applied on the pointed item. Using this menu moves the input focus to the item pointed to, but does not change the selection.

Background Popup Menu

This menu is shown when you point to the background of the Browser and click the right mouse button. Using this menu does not affect the selection or the input focus.

Popup Menu Commands

The following commands in the popup menus are not available elsewhere.

Select All

Selects all items in the Browser. The same effect can be achieved by pressing <Ctrl+/>.

Deselect All

Deselects all selected items. The same effect can be achieved by pressing <Ctrl+\>.

Toggle Select

Toggles the selection state for the item. The same effect can be achieved by pressing <Ctrl+space>.

Toggle Select Tree

Toggles the selection state for the whole sub-tree below the item. The same effect can be achieved by pressing <Ctrl+Shift+space>.

Rename

Renames the item, see "Rename" .


Using More Complex Selections

Apart from manually selecting items in the Browser, you can make more complex selections by using the Selector. These selections can then be displayed in a sub Browser.

The Selector tool is available from the Browser Tools menu. Like the other TTCN suite tools, the Selector tool works on selections. The purpose of the Selector tool is to, from an existing selection, create a new selection.

With the Selector, you can make selections in three ways:

  • By restricting the existing selection
  • By making additions to the existing selection
  • By replacing the existing selection

You can make selections by specifying restrictions on table names, restrictions on tables types and even restrictions on the contents of the tables.

Restrictions can also include the analysis status of the table, i.e. not analyzed, error and OK.

Selections can also be made depending on references between TTCN objects. A typical use of this feature might be to select (and perhaps later Convert to TTCN-MP) an entire Test Case, i.e. the Test Case Behaviour and all its associated declarations, constraints, Test Steps etc.

Note: UNIX only

The Selector is only available on UNIX.

Tools > Selector

Creates a new selection from a given selection. The Selector dialog is opened:

Figure 188 : Selector dialog

Name Restriction

Enables the user to define the restrictions on the identifiers of the named TTCN tables (e.g. ASPs, PDUs, Constraints, Test Cases, Test Steps and Defaults) to be selected. This restriction is a regular expression (see "Regular Expressions" ). If the name restriction field is empty then no restrictions on the table names will apply.

Example 186

The name restriction ^abc will select all tables whose names begin with the string "abc".

Type Restriction

Enables the user to define the restrictions on which kind of TTCN tables that are to be selected. Click once to select one or more table types.

Example 187

Suppose that the initial selection is the entire Dynamic Part. Choosing the table types Test Case Dynamic Behaviour and Test Step Dynamic Behaviour together with the name restriction ^abc will select all test cases and test steps whose names begin with the string "abc".

If no table types at all are selected then no type restrictions are assumed to apply (i.e. the same effect as selecting all table types).

Content Restriction

Enables the user to define the restrictions on the contents of TTCN tables that are to be selected. This restriction is a regular expression (see "Regular Expressions" ). If the content restriction field is empty then no restrictions on the contents of tables will apply.

Example 188

Suppose that the initial selection is the entire TTCN document. Choosing the table type TTCN PDU Type Definition together with the Content restriction ^xyz will select all TTCN PDUs which have a field beginning with the string "xyz".

Select Mode

Enables the user to choose a select mode: restrict, extend or replace.

Figure 189 : Selector mode

  • In the Restrict mode the initial selection will be reduced to those items which fulfill the user supplied restrictions. The examples above illustrate the Restrict mode.
    Note that in this mode the Relations option is not available.
  • In the Extend mode the initial selection will be extended with the items that 1) fulfill the references given by the Relations option and 2) fulfill the user supplied restrictions (if any).
  • In the Replace mode items in the initial selection will be replaced by the items that 1) fulfill the references given by the Relations option and 2) fulfill the user supplied restrictions (if any).

Relations

When a TTCN document is analyzed, the TTCN suite builds a symbol table of all the named TTCN objects that are in the TTCN document. If required, the Selector will perform a `look-up' in this table in order to select referenced objects.

It is required that the TTCN document is analyzed before applying the Selector with the Relations option. This will ensure that the entries in the symbol table are consistent with the TTCN document on the screen.

There are three kinds of references: References, References recursively and Referenced by

  • References
    Selects all other objects that are referenced by the initially selected objects. This new selection may be further restricted if any Name and/or Type and/or Content restrictions are chosen.
    In the first case, suppose that we have object A. Choosing References will select all the other objects, e.g. B, C and D that object A references.

Example 189

If the initial selection is a single test case and we make a type restriction of Test Step Dynamic Behaviour but no Name or Content restrictions, then choosing Extend and References will add to the current selection all the test steps (if any) that the selected test case references.

  • References recursively
    Same as above except that all recursive references are also selected.
    The second case is the same as the first, except that the references are selected recursively, e.g. B, C, D, E, F and G.

Example 190

To extract an entire test, select the desired test case and apply Extend and References recursively without any other restrictions. The Selector will select the Test Case Behaviour and all its associated declarations, constraints, attached Test Steps (including any Test Steps that these Test Steps may attach), Defaults etc. The Convert to MP command can then be used to output this test case in TTCN-MP format.

  • Referenced by
    Selects all objects that have references to the selected object. This new selection may be further restricted if any Name and/or Type and/or Content restrictions are chosen.
    In the third case suppose that we have object A. Choosing Referenced by will select all the other objects, e.g. B, C and D that reference object A.

Example 191

If the initial selection is a single PDU definition, then choosing Extend and Referenced by without any other restrictions will select all the objects (e.g. constraints and behaviours) that use this PDU type.

Keeping and Retrieving a Selection

File > Keep Selection

Saves the current selection for later retrieval. This operation may, for example, be used when an Access application is to be applied on the TTCN document. To be able to retrieve the saved selection in another session the Save Document command needs to be issued after this command. For more information see "Getting Started with TTCN Access" .

File > Retrieve Selection

Retrieves the saved selection.

Searching by Using the Selector

A search pattern (regular expression) can be defined for either the complete content of a set of objects or only for the names.

A search always operates with a Browser selection as its scope. It will produce another selection as the result. By creating a sub Browser from the resulting selection a convenient environment for viewing the objects that fulfilled the search predicate is achieved.

Making Sub Browsers from Selections

Often, after making a selection, it is useful to make a sub Browser which only contains the items which are selected. This can easily be done by using the Browser command from the Tools menu of the Browser.

Example 192

Applying the Selector on an entire TTCN document with the Analyze status option set to error will select all objects that have syntax and/or static semantic errors. Choosing the Browser command from the Tools menu of the Browser where the selection was applied will create a Sub-browser that only contains the error objects (including the structure needed to "glue" them together).

Regular Expressions

When you use the Selector or search from the Table Editor, string patterns are used for matching and searching for named objects or text strings. In UNIX terminology these patterns are called regular expressions. Regular expressions include symbols specifying the pattern to be searched for. Some of these symbols are:

\ < > ^ $ [ ] *

Use of these symbols in regular expressions involves a quite complicated syntax which can be very powerful. We illustrate some common uses below, but for full information we suggest that the user takes a look at the UNIX manual entry for regexp (do a man regexp), and look under the heading Regular Expressions.

Example 193

TTCN tables contain fields. Fields contain text strings. Text strings contain words.

The pattern abc will match all words that include the string "abc", e.g. abcxyz xyzabc, xyzabcxyz, abc.

The pattern \<abc\> will match all words that are exactly "abc". This is useful for finding TTCN identifiers embedded in strings and comments.

The pattern ^abc will match any field that begins with the string "abc", e.g. abcxyz abc, abcabc.

The pattern abc$ will match any field that ends with the string "abc", e.g. xyzabc, abc, abcabc.

The pattern ^abc$ will only match fields containing exactly "abc".

The pattern abc[1-5]$ will select all fields that end with "abc" and a single number between 1 and 5, e.g. abc1 and xyzabc4, but not abc7 or abc12.


Searching and Replacing

You specify the text to search for and the replacement text in the Table Editor, see "Searching and Replacing" . However, you can invoke the search from the Browser too and in this case, an empty Table Editor will be opened.

Edit > Find & Replace

Opens an empty Table Editor where you can specify what to search for.


Presenting Status Information

The Reporter presents status information on selected Browser items (i.e. TTCN objects) in the form of a simple list. This list can include such information as analyze status and modification dates etc. The Reporter also provides limited formatting of the list.

Reporter output may be stored to file for later use, for example printing or as input to an AWK script for further processing.

Note: UNIX only

The Reporter tool is only available on UNIX.

Constructing Lists with the Reporter

The Reporter tool is available from the Browser Tools menu.

Tools > Reporter

The Reporter tool is applied to selected items in a Browser, and presents them in the form of a simple list. Selections can either be made by using the mouse or by using the Selector tool (see "Using More Complex Selections" ).

Figure 190 : Reporter dialog

Log Device

Controls the log (output) device for the Reporter tool. The default value is Screen, but the log can be directed to a named file by choosing File or turn it off altogether by choosing None. The file extension for the reporter log is .rpt.

For a full description of this command see "The TTCN Suite Logs" .

Action

The following options specify which information about each selected item shall appear in each Reporter list entry.

  • Name
    The name of the item (e.g. ESTABLISH_CONNECTION)
  • Type
    The type of the item (e.g. Test Step Dynamic Behaviour)
  • Modify Time
    The date and time that the item was last modified (edited) (e.g. Thu Aug 20 13:05:55 1992).
  • Analyze Time
    The date and time that the item was last analyzed (e.g. Thu Aug 20 13:08:35 1992).
  • Analyze Status
    The analyze status of the item (e.g. error))
  • Reference List
    The other objects that this object references. This information is used, for example, by the Selector when the References option is set (e.g. N_SAP:L:LT_DEFAULT:CR1:NDr:CR:CC1:NDi:CC).

Formatting

The list can be formatted using either tab or nl + tab, where nl stands for new line.

  • tab
    In this format the components of each list entry are separated by a tab.

Example 194

Part of a Reporter log showing two test steps. The list was generated using only the Name and Type option with the format option set to tab.

Figure 191 : The TTCN suite log for Reporter (tab)

  • nl + tab
    In this format the components of each list entry each are printed on a new line. Each component, except the first component in the list entry, is preceded by a tab.

Example 195

Part of a Reporter log showing two test steps. The list was generated using all the options and with the nl + tab format.

Figure 192 : The TTCN suite log for Reporter (nl+tab)

Verbosity

Full verbosity gives more detailed information. The following extra information is available with full verbosity:

  • Reanalysis
    It is obvious that if the item is not OK (its analyze status), it needs to be reanalyzed. Even if the item has an OK status, the item may need to be reanalyzed since it may contain references to items which have been modified. The reporter with full verbosity will determine if the item need to be reanalyzed or not. This information is reported together with the analysis status.
  • Reference status
    For each reference the following extra information is available with full verbosity:
    • If the reference does not exist (has been removed)
    • If it is not unique
    • If it is a named object
    • If the reference has been analyzed more recently

Revision Control

There is no integrated revision control system in the TTCN suite. Since normal visible files are used to store the TTCN documents it is easy to integrate the TTCN suite in a revision control system like SCCS or RCS. The .itex file format, being binary, is however not very suitable for that, it is better to use the TTCN-MP format to store in the revision control system.

Increased functionality is obtained if not only the TTCN-MP file is stored. The output from the Reporter contains useful information like modification dates and cross-reference lists.

By applying the following procedure whenever a check-point is desired the revision system becomes even more powerful:

  1. Select the entire document.
  2. Use the Convert to MP command to create a TTCN-MP file. Store it as e.g. Test-Suite.mp.
  3. Use the Reporter, setting relevant options, to create a report. This report could now include modification date, cross-reference lists, etc. The formatting option tab should be chosen. This means that each TTCN object will occupy one line.
  4. Store the log-window created by the reporter as e.g. Test-Suite.rpt.
  5. Allow both files to be handled by the revision control system

It is now easy to obtain useful information about the difference between revisions by simply comparing the stored report files. A compare could be made using e.g. sccs diff (if SCCS is used).


Comparing TTCN Documents

The Compare tool is used for comparing two TTCN documents with respect to finding similarities that exist between them, i.e. two TTCN objects that have the same name. These objects need not necessarily be of the same type.

The Compare tool is accessed from a Browser and is applied to selections of items in that Browser.

Compare will check either only for similar names or for names and object type. The comparison can also include the contents of tables if required.

The Compare tool can also check the group structure of TTCN documents for similarities, i.e. it will indicate Test Group, Test Step Group and Default Group paths that are the same in both TTCN documents.

Any similarities that are found may be logged in a log file. There are three levels of log verbosity: quiet, some and full. Execution of the Compare tool may result in a new selection, which can be used to create a separate Browser if so wished.

One of the main uses of this tool will be to help remove conflicts from two TTCN documents prior to performing a merge operation.

Note: UNIX only

The Compare tool is only available on UNIX.

Comparing by Using the Compare Tool

To use the Compare tool, you need two TTCN documents to operate on: the destination document and the compare document.

Figure 193 : How Compare works

A selection from the destination document may be compared with the compare document. If any similarities are found between the two TTCN documents this will result in the modification of the original selection in the destination TTCN document.

Tools > Compare

Compares a Browser selection from one TTCN document with another TTCN document with respect to similarities. Make the selection in a destination TTCN document Browser and call the Compare tool from the same Browser.

Figure 194 : Compare Documents dialog

Log Device

Controls the log device for the Compare tool. The default value is Screen, but the log can be directed to a named file by choosing File or turn it off altogether by choosing None.

For a full description of this command see "The TTCN Suite Logs" .

Documents

Presents a list of currently open documents. For Compare to work correctly at least two documents must be present in this list. The document name in bold italic font is the document from which the Compare tool was called, i.e. the destination document. The user must choose another document in this list, i.e. the compare document, in order to do a comparison.

Example 196

In the dialog above the destination document is Test_Suite_A and hence the compare document may only be Test_Suite_B.

Action

Specifies the effect that the Compare operation will have on the original selection in the destination TTCN document.

Figure 195 : Compare: Action

  • Select
    All items in the original selection that are similar to items in the compare TTCN document will remain selected, otherwise the items will be deselected.
    In other words, the result of the Compare operation will result in a selection that shows the similarities between the destination and the compare TTCN documents.
  • Deselect
    All items in the original selection that are similar to items in the compare TTCN document will be deselected, otherwise the items will remain selected.
    In other words, the result of the Compare operation will result in a selection that shows the differences between the TTCN documents.
  • Nothing
    Means that the Compare operation will have no effect on the destination selection. However, the results of the Compare operation will still be recorded in the log, if this option is set.

Verbosity

Sets the verbosity level for the log file.

Figure 196 : Compare: Verbosity

  • Quiet
    Turns the log off. No information will be recorded in the log, even if the Log Device is on.

Note:

Using the Nothing action together with the Quiet option is rather meaningless!

  • Some
    Causes the names of all identically named objects to be printed in the log.

Figure 197 : Compare: log (Verbosity: some)

If the Content switch is on, the log will also indicate that a difference has been detected.
  • Full
    Causes the names of all identically named objects to be printed in the log. However, if the objects are of different types this will be indicated as well.

Figure 198 : Compare: log (Verbosity: full)

If the Compare Content switch is on, the log will also indicate in detail the differences detected.

Compare Content

Extends the scope of the comparison to include the contents (down to the level of a single character) of the tables as well. Thus, two objects are considered to be identical if their names, object types and entire contents are identical. If the verbosity is full the differences are detailed.

Compare structure

Extends the scope of the comparison to include the Test Group, Test Step Group and Default Group references in the relevant behaviour tables. This option is only available when the Compare content option is chosen.

Comparing by Using itexdiff

A separate program, itexdiff, may also be used to quickly compare the contents of two TTCN suite files. The tool is less powerful than the Compare tool, but it may be very useful when there is a need for quickly comparing two revisions of the same TTCN document for equality.

The program is run like:

itexdiff FooSuite.itex /home/user1/FooSuite.itex

This will test the content of the two TTCN documents for equality and report the result in a printout. To get a more elaborate compare, the -d switch may be added like:

itexdiff -d FooSuite.itex /home/user1/FooSuite.itex

This will give the output of running the program diff on the MP representation of the content of the two documents.

Running the program without any arguments will print out a terse usage message.

Using Compare Before Merging Two TTCN Documents

The Merge tool will only work if the two TTCN documents to be merged do not conflict. A conflict occurs if any TTCN objects in the TTCN documents have the same name.

One of the first things Merge does is to compare the two TTCN documents. If any conflicts are found it will be notified and the Merge operation will not be initiated. Use the Compare tool to find and resolve the conflicts.

For a full description of this command see "Merging TTCN Documents" .


Merging TTCN Documents

The Merge tool is used for merging one TTCN document (complete or partial) into another TTCN document.

A useful application of the Merge tool is to use the Selector tool and the Convert to MP tool to extract a complete test case (the Test Case Dynamic Behaviour together with its declarations, constraints etc.) and merge it with another TTCN document.

Note: UNIX only

The Merge tool is only available on UNIX.

Preparing for a Merge

The merge tool requires that two TTCN documents are opened. We shall call them the merge TTCN document and the destination TTCN document or selection.

Figure 199 : Shows how Merge works

Merge will only work if the two TTCN documents do not conflict. A conflict occurs if any selected TTCN object in the merged TTCN document has the same name as any TTCN object in the destination document.

One of the first things Merge does is to compare the two documents. Any conflicts that are found will be notified and the Merge operation will be aborted. Use the Compare tool to find and resolve the conflicts.

For a full description of this command see "Comparing TTCN Documents" .

Merging Two TTCN Documents

Once the selected objects in the merge TTCN document do not conflict with the destination TTCN document, the Merge tool can be used.

Tools > Merge

Merges a selection into another TTCN document. Make the selection in the merge TTCN document and call the merge tool to merge the selected nodes into the destination document.

Figure 200 : Merge Documents dialog

  • Log device
    Enables the user to define the log device for the Merge tool. The default value is Screen, but the user can direct the log to a named file by choosing File or turn it off altogether by choosing None.
    For a full description of this command see "The TTCN Suite Logs" .
  • Documents
    Presents a list of currently open documents. For Merge to work correctly at least two documents must be present in this list. The document name in bold italic font is the document from which the Merge tool was called, i.e. the merge document. The user must choose another document in this list, i.e. the destination document, in order to do a merge.
    In the dialog above the destination document is Test_Suite_B and the merge document is Test_Suite_A.

Creating Documents by Using the Merge Tool

The Merge Tool is not only useful when merging two documents together. It can also be used in the creation of a new document that needs to obtain some information from another document. The following procedure can be useful:

  1. Create a new (empty) document.
  2. Open the document containing objects that are to be copied.
  3. Select the desired objects in the Browser (possibly aided by the Selector tool).
  4. Merge them into the empty document.

There are also alternate ways of doing this. Copy/Paste between the documents or using the Convert to MP tool and the Convert to GR tool or the Merge from MP tool.


Merging from MP Files

Use the menu choice Merge from MP or Autolink Merge for merging the content of an MP file into a TTCN document. For additional information on merging an Autolink generated MP file, see "Merging TTCN Test Suites in the TTCN Suite" .

Four steps are involved in a merge from MP:

  1. It first converts the MP file to a temporary GR format TTCN document, see "Importing a TTCN-MP Document" for details.
  2. The second step is to use the Merge tool to copy all the content of the new document into the existing document, see "Merging TTCN Documents" for details (note the conflict resolution difference).
  3. The third step is to remove the temporary document.
  4. The optional fourth step is to analyze the destination document (this last step is mandatory if called under the name AutoLink Merge)

The Merge from MP tool requires that one TTCN document is open. We shall call it the destination TTCN document. This is where the merge from MP is called from.

Figure 201 : How a merge from MP works

Merge from MP will only work as depicted above if the two TTCN documents do not conflict. A conflict occurs if any TTCN object in the MP file has the same name as any TTCN object in the destination document. If such a conflict is detected, the conflicting object in the MP file will be skipped and the merge process continued.

Merging of constraint tables are handled specially. For example, an MP file may contain a TTCN ASP Constraint constraint1 that refers to the type type1, where the type1 Type table is of the incompatible type TTCN PDU TypeDef. This will make the merge process insert a copy of constraint1 as a table of type TTCN PDU Constraint instead of the original type1. There are, however, limitations to this "type conversion". The conversion will not convert an ASN.1 Constraint to a TTCN Constraint nor vice versa.

Tools > Merge from MP

SDT Link > Autolink Merge

The menu choice Merge from MP in the Tools menu and Autolink Merge in the SDT Link menu makes it possible to merge the content of an MP file into the current TTCN document.

Figure 202 : The Merge from MP dialog

  • Log device
    Enables you to define the log device for the merge from MP. The default value is Screen, but the user can direct the log to a named file by choosing File or turn it off altogether by choosing None.
    For a full description of this command see "The TTCN Suite Logs" .
  • Ignore Page Numbers
    Ignore any page number information in the MP file if set.
  • Analyze After Merge
    Runs the Analyzer on the whole destination document after successful merge if set. This option is not possible to disable when using AutoLink Merge and so is not displayed in that dialog.
  • Filter
    Sets the filter for the files that will be displayed in the Files list. By convention TTCN-MP files are given the suffix .mp.

Example 197

The name filter *.mp will cause only those files whose names end with .mp to be displayed, e.g. example.mp

  • Directories
    Lists the directories in the current file system directory. To change directory, point to the required directory name and double-click.
  • Files
    Lists the files (if any) that are in the current directory and which match the filter.
  • Selection
    Displays the selected document.
  • Merge
    Terminates the dialog and executes the merge from MP.
  • Filter
    Updates the Files list according to the current filter.
1

This feature does not exist in the regular Merge tool.


Exporting a TTCN Document to TTCN-MP

TTCN-MP - the textual notation (machine processable) - can be used when you want to import a TTCN document into a non-TTCN suite tool or make backups.

By using the menu command Convert to MP, you can convert a TTCN-GR document to TTCN-MP. However, note that it is also possible to simply use Save Document As for changing the format. The difference between the two menu commands is that Convert to MP gives the option to save as TTCN Suite MP or standard MP, while Save As produces TTCN Suite MP. How this differs from the standard MP format is described in "The TTCN Suite MP format" .

There are no restrictions on the analysis state of the TTCN document with regards to its correctness, i.e. it will generate TTCN-MP even for TTCN documents that are neither complete nor error-free. This implies that the generated MP file may be, but is not necessarily, conformant to the standardized TTCN-MP format.

However, to ensure that a TTCN document that is output in TTCN-MP by the TTCN suite can be read by a non-TTCN suite tool, it is necessary to make sure that the TTCN document is correctly analyzed, that the test suite overview have been recently updated. You also have to select everything in the document before convert to MP. The TTCN suite format option in the dialog will in most such cases have to be non-selected.

Convert to MP, invoked from the Browser, works on Browser selections, i.e. it is possible to output selected items (e.g. a single test case or just the constraints). Convert to MP will add the necessary keywords to the MP file to make it into a TTCN-MP that can be converted back into GR format.

An optional but non-standard TTCN-MP for compact tables and ASN.1 references is supported. Additional fields in dynamic tables (fields which are transferred to test suite overview tables) are also supported. This format is the recommended format for transferring TTCN document between the TTCN suite instances, and also for making backups of the TTCN documents.

Convert to MP is accessible from the Browser File menu and from the Organizer Generate menu.

Converting to TTCN-MP in the TTCN Suite

The items selected in the Browser will be converted to TTCN-MP. Selections can be arbitrary - the TTCN suite will add the necessary keywords to the MP file to make it into a TTCN-MP that can be converted back into GR format.

To convert an entire TTCN document, do a Select All and then select Convert to MP from the File menu, or invoke this operation from the Organizer. For more information, see "Convert to MP (TTCN)" .

For example, to convert a complete test case, use the Selector, together with the References recursively option and then apply Convert to MP on the resulting selection.

File > Convert to MP

Presents a dialog in which you can convert the selected items to MP.

Figure 203 : Convert to MP file dialog

Log Device

Controls the log device for the Convert to MP tool. The default value is Screen, but the log can be directed to a named file by choosing File or disabled by choosing None.

For a full description of this command see "The TTCN Suite Logs" .

The TTCN Suite MP format

Enables the user to convert a TTCN document to a non-standard MP with the following extra information:

  • Compact tables
    Is intended for TTCN documents where the Test Case Dynamic Behaviours (i.e. compact test cases) table has been used. Check this option to generate an MP file that contains additional keywords that specifically identify compact tables. If this option is not used the TTCN suite will output a standard TTCN-MP file where each test case in the compact test cases table is represented as a single test case (i.e. the information about the compact table is lost).
  • Additional fields in dynamic tables
    If the ITEX MP format option is used, the TTCN suite will convert the additional Selection Ref and Description fields in the behaviour tables.
  • ASN.1 reference tables
    The additional field in ASN.1 type by reference and Test Suite Constant Declarations By Reference tables will be converted if this option is checked. These additional fields contain the definition of the ASN.1 type and value.
  • Import tables
    The additional column fields in Import tables will also be converted if this option is checked.

Filter

Sets the filter for the files that will be displayed in the Files list. By convention TTCN-MP files are given the suffix .mp.

Example 198

The name filter *.mp will cause only those files whose names end with .mp to be displayed, e.g. example.mp

Directories

Lists the directories in the current file system directory. To change directory, point to the required directory name and double-click.

Files

Lists the TTCN suite TTCN-MP files (if any) that are in the current directory and which match the filter.

Selection

Displays the selected document.

Filter

Updates the Files list according to the filter.

Exporting by Using itex2mp

A separate program, itex2mp, may be used to quickly export the content of a TTCN suite file. The generated MP format includes the TTCN suite-specific extensions.

The program is run like:

itex2mp FooSuite.itex FooSuite.mp

This will export the content of the TTCN document into the specified MP file. You may notice that the program has the "style" of a specialized cp program.

Running the program without any arguments will print out a terse usage message.


Importing a TTCN-MP Document

By using the menu choice Convert to GR in the Organizer, you can convert a TTCN-MP document to TTCN-GR and open it in the TTCN suite. However, note that it is also possible to simply open an MP document.

The Convert to GR tool is flexible, it will read any TTCN-MP file that has been successfully generated by the Convert to MP tool, even if the MP file only contain parts of a test suite. Convert to GR will also read TTCN-MP from other products which support TTCN assuming that this TTCN-MP follows the ISO standard.

For a full EBNF supported by the Convert to GR tool, see "The TTCN-MP Syntax Productions in BNF" .

An optional but non-standard TTCN-MP for converting TTCN documents that use compact tables and ASN.1 references with an explicit definition, is also supported.

Converting a TTCN Document

For a full description of this command see "Convert to GR (TTCN)" .

MP File Format Problem

When converting certain TTCN documents, a problem with transferring the information (e.g. Description) in the Overview tables to the tables in Dynamic Part, may occur.

The TTCN standard allow path specifications to optionally include the document name first. This has the unfortunate effect that if the TTCN document contains a top level group with the same name as the TTCN document there is, in general, no way of knowing if the first part of the paths is a group identifier or the TTCN document identifier.

The TTCN suite assumes that if the first part of the path is equal to the document name, it is the optional document name and, when converting, strips it away. When exporting, the document name is always added to the front of all paths. That way the TTCN suite is always able to convert the MP files it exports. Note that ITEX 2.0 did not add the document name at export, and therefore the problem described here may also apply when converting MP files exported by ITEX 2.0.

If the TTCN document contains top level group identifiers equal to the document name, and the TTCN suite is unable to resolve the paths, temporarily change the document name in the MP file and change it back once inside the TTCN suite.

Converting Fields Containing the Dollar Character

Normally the Convert to GR tool ignores the content of the fields of tables in the MP file but, to allow converting of non-BoundedFreeText fields (e.g. TS_VarValue field) with embedded dollar characters (e.g. "$") the Convert to GR tool has been enhanced with a simple syntax checker of the fields. This has the implication that it is no longer possible to convert TTCN documents containing unmatched single or double quotes in non-BoundedFreeText fields, i.e. Convert to GR is less tolerant about syntax errors in the fields.


Generating the Test Suite Overview Tables

The TTCN suite generates the contents of the Test Suite Overview tables (i.e. The Test Suite Structure, Test Case Index, Test Step Index and Default Index tables) and the TTCN Module Overview (i.e. The TTCN Module Structure and the index tables).

These tables are not editable. The extra information that they require (such as references to selection expressions and descriptions) are entered at the corresponding table rather than in the Test Suite Overview tables. This ensures consistency between the TTCN document and the contents of the Test Suite Overview.

Selection Expressions

The Test Case Dynamic Behaviour table displayed by the TTCN Table Editor has an additional field in the table header called: Selection Ref.

This field is used to hold the reference to a Selection Expression (if any) declared in the Test Case Selection Expression Definitions table. This reference will then appear in the Selection Ref column of the Test Case Index when the index is generated using the Generate tool.

If the Selection Reference needs to be edited this must be done in the relevant Test Case table and not in the Test Case Index table (which cannot be edited). The Test Suite Overview (or the TTCN Module Overview) must be re-generated in order to update any changes.

The additional Selection Ref field in the Test Case header is not printed in the TTCN-GR form. It is however exported in the TTCN suite specific MP format.

Test Case, Test Step and Default Descriptions

The Test Case, the Test Step and the Default Dynamic Behaviour tables displayed by the TTCN Table Editor have an additional field in the table header called Description.

The Description field is used to hold the description of the behaviour table, which in many cases may simply be a copy or a shortened form of the Test Purpose or Test Step or Default Objective. This description will then appear in the Description column of the relevant index when it is generated using the Generate Overview tool.

If the Description needs to be edited this must be done in the relevant behaviour table and not in the index tables (which cannot be edited). The Test Suite Overview (or the TTCN Module Overview) must be re-generated in order to update any changes.

The additional Description field in the Test Case, Test Step and Default headers is not printed in the TTCN-GR form. It is however exported in the TTCN suite specific MP format.

The Group Table

The TTCN Browser supports additional non-standard tables for groups. These tables are: the Test Group table, the Test Step Group table and the Default Group table. None of these tables are printed in the TTCN-GR form.

The Test Group table has two fields in its header that are used to hold information for the Test Suite Structure table. These fields are: Selection Ref and Test Group Objective.

The Selection Ref field is used to hold a reference to a Selection Expression (if any) declared in the Test Case Selection Expression Definitions table. This reference will then appear in the Selection Ref column of the Test Suite Structure when it is generated using the Generate tool.

The Test Group Objective field is used to hold the description of the Test Group. This description will then appear in the Test Group Objective column of the Test Suite Structure when it is generated using the Generate tool.

If either the Selection Reference or the Test Group Objective needs to be edited this must be done in the relevant Test Group table and not in the Test Suite Structure table (which cannot be edited). The Test Suite Overview must be re-generated in order to update any changes.

All of these fields are exported in the TTCN suite specific MP format.

Generation of the Test Suite Overview and Indices

The Generate tool is available from the Tools menu in the Browser and the Tools menu in the Table Editor. Unlike other tools it does not require a selection: it always applies to the entire TTCN document and its action is the same whether it is invoked from a Browser or from a Table Editor.

Tools > Generate SO

Generates the Test Suite Overview (or the TTCN Module Overview) tables (i.e. The Test Suite Structure, TTCN Module Structure, Test Case Index, Test Step Index and Default Index tables). It makes use of the additional Group tables and the additional Selection Ref and Description fields in the behaviour tables.

Figure 204 : Generate Suite Overview dialog

  • The Log Device option controls the log device for the Generate tool. The default value is Screen, but the log can be directed to a named file by choosing File or turn it off altogether by choosing None.
    For a full description of this command see "The TTCN Suite Logs" .
  • The First Page Number option enables setting the first page number of the TTCN document. The default value is 1.


Crash Recovery

In the event of a TTCN suite crash, it is possible to recover up-to-the-minute changes. The auto-save content is stored in two "comma files": filename,s and filename,t, where filename is derived from the first five characters of the name of the file they are associated with. The files can be found in the designated temporary directory, usually /var/tmp. To be able to open those files, you need to concatenate them into a .itex format file. This is accomplished with the iconcat program.

The program is run like:

iconcat /var/tmp/FooSuJAAa002l89 FooSuite-saved.itex

This will concatenate the content of the TTCN suite files /var/tmp/FooSuJAAa002l89,s and /var/tmp/FooSuJAAa002l89,t into the FooSuite-saved.itex ITEX file. Note that the program ignores any existing /var/tmp/FooSuJAAa002l89 file, despite the argument syntax.

You may notice that the program has the "style" of a specialized cp program. Running the program without any arguments will print out a terse usage message.


Key and Button Bindings

Key | Action
Ctrl+Shift+space | Toggles the select status of all nodes in the subtree.
Ctrl+space | Toggles the select status of the focused node.
Shift+space | Set the select status of all nodes in the subtree. Remove select status on all others.
Space | Set the select status of the focused node. Remove select status on all others.
t | Open an editor on the focused node.
osfHelp | Get help on Browser.
c | Hide subtree.
e | Make children of the focused node visible.
Shift+e | Make whole subtree visible.
r | Rename the focused node.
Ctrl+c | Copy the focused node (for later paste).
Ctrl+x | Cut the focused node (for later paste).
Ctrl+v | Paste the content of the paste buffer before/above the focused node.
Ctrl+Shift+osfInsert | Add a new child to the focused node. It is placed last in the child list.
Ctrl+osfInsert | Add a new sibling before/above the focused node.
Ctrl+Meta+osfInsert | Add a new sibling after/below the focused node.
Ctrl+Shift+G | Add a new group child to the focused node. It is placed last in the child list.
Ctrl+g | Add a new group sibling before/above the focused node.
Ctrl+Meta+g | Add a new group sibling after/below the focused node.
F2 | Move down in tree such that if we start on root node we come to "Test Cases".
Ctrl+/ | Select all nodes in browser.
Ctrl+\ | Deselect all nodes in browser.
osfUp | Move focus to previous visible node.
osfDown | Move focus to next visible node.
osfLeft | Move focus to parent of the focused node.
osfRight | If the children of the focused node are hidden, make them visible. Then move focus to first child.
Shift+osfUp | Move focus to previous node at same level.
Shift+osfDown | Move focus to next node at same level.
Shift+osfLeft | Move focus to parent of the focused node, and hide the subtree.
Shift+osfRight | If the children of the focused node are hidden, make them visible. Then move focus to last child.
osfBeginLine | Move to first visible node of browser.
osfEndLine | Move to last visible node of browser.
Shift+F10 | Show node popup menu.
Ctrl+Z | Run "Analyze & Stop"

Mouse button (OSF Names) | Action
Button1 | Set focus to the node and set selection status of the node. Remove select status on all others.
Ctrl+Button1 | Set focus to the node and toggle selection status of the node.
Shift+Button1 | Set focus to the node and set selection status of the subtree. Remove select status on all others.
Ctrl+Shift+Button1 | Set focus to the node and toggle selection status of the subtree.
Button1 twice | Set focus to the node and start an editor on that node if that is at all reasonable. If the node is a static node, make its children visible or hidden. Remove select status on all nodes.
Ctrl+Button1 twice | Set focus to the node and start an editor on that node.
Button2 | Move focus to the node.
Button3 | Show popup menu.


26 The TTCN Table Editor (on UNIX)

This chapter contains reference information about the Table Editor, used for editing various TTCN tables.

The functionality of the Table Editor, the menus, windows and quick-buttons are described in this chapter. The TTCN Browser is described in 25 The TTCN Browser (on UNIX). How to analyze and find tables is described in 27 Analyzing TTCN Documents (on UNIX).

For an overview of the TTCN suite, see Introduction to the TTCN Suite (on UNIX).

Note: UNIX version

This is the UNIX version of the chapter. The corresponding Windows chapter is 31 Editing TTCN Documents (in Windows).


Introduction to the TTCN Table Editor

The Table Editor is used for editing the various TTCN tables. It is possible to have any number of tables open for editing at any given time.

The TTCN suite supports all of the standardized, non-compact tables that are defined in ISO/IEC 9646-3. The compact Test Case Dynamic Behaviour table (ISO/IEC 9646-3, clause C.3) and the concurrent TTCN tables are supported, as well as the modular TTCN tables to be added in the upcoming new TTCN version.

The compact tables for constraints (also in Annex C of ISO/IEC 9646-3) are not supported.

On screen, the TTCN suite presents all tables exactly as defined in ISO/IEC 9646-3, apart from some minor additions to the regular dynamic behaviour tables (for test cases, test steps and defaults), to the compact test case dynamic behaviour table, to the ASN.1 type by reference tables, to the test suite constant declarations by reference, and to the import tables.

These changes have been introduced to aid the automatic generation of the TTCN document overview and index tables. For more information, see "Generating the Test Suite Overview Tables" . However, in the printed GR form the TTCN document is presented according to the ISO standard (that is, the additions are not present in the printed version).

As a visual aid, dotted lines separate rows in a table. Again, this is not present in the printed GR form.

The TTCN suite always displays the optional comments column and comments footer of a table, even if they are empty.

You can use both menu choices and keyboard shortcuts for editing tables. It is also possible to search and replace text patterns. By providing a Data Dictionary, the Table Editor supports semi-automatic generation of send and receive statement lines. In the Data Dictionary, you select the components in a send or receive statement from lists of PCOs, types and constraints. The TTCN suite prevents you from selecting incompatible items.

The Table Editor also shows the analysis status of the table contents.

Figure 205 : A TTCN Table Editor for a test case


Opening a Table

Tables are opened from a Browser when you double-click on a selected table name, or with the popup menu. For more detailed information see "Opening a Table" .


Renaming a Table

A table can be renamed either by using the Rename command in the Browser (for more information see "Renaming Dynamic Items" ) or by editing the table name in the table itself. This choice also exists for objects in multiple-object tables.


Navigating and Editing Text in a Table

The Table Editor facilitates fast and efficient editing. The input focus determines which field is open for editing at any given time.

Setting the Input Focus

The input focus is automatically set on the name field of the table when it is opened. Reset the input focus by using the following shortcuts:

To move to: | Use this key combination:
Next field | <Tab>
Previous field | <Shift+Tab>
Next part of the table | <Ctrl+Tab>
Next field in same column | <Ctrl+down arrow>
Previous field in same column | <Ctrl+up arrow>
Field on the left | <Ctrl+left arrow>
Field on the right | <Ctrl+right arrow>

You can also use the mouse for setting the input focus. However, note that a middle-click only moves the focus to that field but it is not possible to edit text. To do this, you have to left-click in the field.

Editing Text in a Table

To edit the text in a field, you set the input focus and start typing. The table fields will expand automatically to accommodate the text and you can add a line break by simply pressing <Return>. To move the insertion point in the same field, you can either use the mouse or the following shortcuts:

To move the insertion point: | Use this key combination
Down | <Ctrl+N>, <down arrow>
Up | <Ctrl+P>, <up arrow>
Left | <Ctrl+B>, <left arrow>
Right | <Ctrl+F>, <right arrow>
To the beginning of the line | <Ctrl+A>
To the end of the line | <Ctrl+E>
Left and extending selection | <Shift+left arrow>
Right and extending selection | <Shift+right arrow>

If you initially type with very high speed, race problems may arise and you will be notified with a beep. This means that the text typed in will not appear correct in the buffer. If this happens often, you should make a brief pause between typing the first and consecutive characters.

Cut, Copy and Paste Text

To cut, copy and paste text in the fields, you can use the following shortcuts. Note that you do not use the same commands or shortcuts as when editing entire rows in a table.

To do this: | Use this key combination:
Delete one character forward | <Ctrl+D>
Cut selected text | <Cut>, <Shift+Delete>
Cut text to the end of the line | <Ctrl+K>
Copy selected text | <Copy>, <Ctrl+Insert> 1
Paste cut or copied text | <Paste>, <Shift+Insert>
Paste the most recently cut line | <Ctrl+Y>
1

<Ctrl+Shift+Insert> also works.

Note:

The paste buffer for text is not the same as the one used for entire rows in the body of a table.

Caution!

The TTCN suite has no undo function. This means that <Undo> has no effect.


Editing Rows in a Table

Rows can be added, deleted, copied, etc. in the bodies of all TTCN tables that contain more than one column. The ASN.1 tables only have a single column with a single row and therefore adding, deleting and copying rows is not applicable. However, you can still copy and paste the contents of these tables as text.

You cannot add or remove rows in table headers and footers, as the formats of these parts of a table are defined by the TTCN standard.

Selecting Rows in a Table

In the dynamic behaviour tables, you select a single row by clicking the row number.

You select a behaviour tree of rows by <Ctrl+Shift>-clicking.

You select rows in the body of a table by <Ctrl>-clicking. Selecting a row does not deselect other selected rows.

To deselect a row, you select it again.

Note:

Setting the input focus will also deselect all selected rows.

Cutting, Copying and Pasting Rows

Rows in a table may be cut, copied and pasted. This not only possible among tables of the same or similar type, but also across different types of tables.

Edit > Cut

Removes selected row or rows from the table and stores them in the clipboard.

Edit > Copy

Copies selected rows to the paste buffer. Any number of rows may be selected.

Note:

The paste buffer used for entire rows in the body of a table, is not the same as the one used for text.

Edit > Delete

Deletes the selected row or rows.

Caution!

The TTCN suite has no undo so this command is irreversible.

Inserting Rows

Edit > Insert Row

Inserts a new row before a selected row. Only one row may be selected.

Edit > Insert Row After

Inserts a new row after a selected row. Only one row may be selected.

Edit > Insert Tree Header

Inserts a new Tree Header row before a selected row. Only one row may be selected. This command only works in dynamic behaviour tables.

Edit > Insert Tree Header After

Inserts a new Tree Header row after a selected row. Only one row may be selected. This command only works in dynamic behaviour tables.

The <Ins> Key

The <Ins> key (on the right-hand keypad) can be used for inserting rows. If you press this key while input focus is in the header or footer of a table, a new row is appended after the last row in the body of the table. If the input focus is set on a field in the body of the table, <Ins> will insert a new row after the field that has the input focus. The input focus will be transferred to the corresponding field in the new row.

Indenting Rows in Behaviour Descriptions

TTCN behaviour tables include a number of commands and shortcut keys that simplify indenting behaviour lines.

Caution!

Do not use the <Tab> character to represent indentation in behaviour trees.

Edit > Increase Indent

Increases the indentation of selected behaviour lines by one position. This command can only be used to indent behaviour lines.

  • Keypad <+>
    Pressing <+> (Plus) on the right-hand keypad (the normal <+> key does not have this effect) will indent the field that currently has the input focus.
  • <Ctrl> + Keypad <+>
    Pressing <Ctrl> together with the keypad <+> key will cause selected behaviour lines to be indented one position, i.e. it has the same effect as the Increase Indent command.
  • <Shift> + Keypad <+>
    Pressing <Shift> together with the keypad <+> key will cause an entire branch in the behaviour tree to be indented one position.

Edit > Decrease Indent

Decreases the indentation (i.e. undent) of the selected rows by one position. This command can only be used on behaviour lines.

  • Keypad <->
    Pressing <-> (Minus) on the right-hand keypad (the normal <-> key does not have this effect) will undent the field that currently has the input focus.
  • <Ctrl> + Keypad <->
    Pressing <Ctrl> together with the keypad <-> key will cause selected behaviour lines to be undented one position, i.e. it has the same effect as the Decrease Indent command.
  • <Shift> + Keypad <->
    Pressing <Shift> together with the keypad <-> key will cause an entire branch in the behaviour tree to be undented one position.

Selecting Branches in Behaviour Descriptions

TTCN behaviour tables include the following short-cut key that simplifies the task of selecting behaviour lines.

  • <Shift+Ctrl> + Left Mouse Button
    Pressing <Shift+Ctrl> together with the left mouse button while the cursor is pointing to a behaviour line, will select that behaviour line and all the subsequent behaviour lines that are in the same branch of the behaviour tree.

Showing the Indentation Level

Show > Show Indent

Causes the indentation level of behaviour lines to be displayed in the line number column of behaviour tables. Choosing this command again will cause the display to revert to line numbering.


Searching and Replacing

From the Table Editor, you can search for and replace text, either on system, document or table level. You specify the search in the search bar of the Table Editor and start the search (and replace) from menu choices in the Search menu.

Figure 206 : The TTCN Table Editor search bar

Specifying Search and Replace Settings

Delimiting the Scope of Search

You can search for text on three levels:

  • System means all documents of the associated document - except for any Flat View document - or only the associated document if it is a Flat View.
  • Document means the associated document only.
  • Table means the current table only.

Selecting the Type of Search

There are three types of search patterns:

  • Text means ordinary literal strings.
  • Wildcard means a pattern with * and ?.
  • Regular Exp means regular expression.
    See also "Regular Expressions" .

Selecting the Search Direction

The search direction can be forward (down arrow) or backward (up arrow).

Specifying the Text to Search For

You specify the text to search for in the Look for field. If you search for text using a regular expression, you will be notified if you try to use an incorrect regular expression.

Specifying the Replacement Text

You specify the replacement text (or replacement pattern, if the type of search is regular expression) in the Change to field.

If you search and replace using regular expressions, the replacement pattern must be compatible with the search pattern. If it is not, you will be notified.

Something important to note about regular expressions, is that the actual replacement text is a result of a combination of the search pattern, the match found and the replacement pattern. This means that the actual replacement text may not literally match the text in the Change to field. However, the actual replacement text will be presented in the status bar when you start searching and a match is found.

Starting the Search and Replace

Search > Search

Starts the search from the current position. If you search in the current table, selected text will be skipped. If the Table Editor is empty, the search will start from the beginning or end of the document or system, depending on the scope and direction that you have specified.

Search > Replace

Replaces currently selected text with the replacement text. If you searched using regular expressions, the replacement text will be presented in the status bar when a match is found.

You can also replace manually selected text. This only requires that Text or Wildcard is selected and that the Change to field contains some text. Note that you cannot manually make an empty selection, but it is possible to search and find an empty match that you can replace.

Search > Proceed

Searches for and replaces text sequentially. If text is selected, it will be replaced and after that the search will proceed.

Search > Replace All

Replaces selected text and then continues the search and replace from the current position. If the Table Editor is empty, the search will start from the beginning or end of the document or system, depending on the scope and direction that you have specified. The number of replacements will be presented in the status bar.


Exporting and Importing Objects

Generate Exports and Generate Import assist in the use of the Modular TTCN feature of exporting and importing objects to and from other documents.

Tools > Generate Exports

Fills the TTCN Exports table with rows that provide access to the objects of the current document. Only rows that are not already present will be added (at the end of the table), so it is supported to repeat this operation at a later time to detect if any object has been added since the last time. Generate Exports is only available when the Table Editor contains a TTCN Exports table.

Tools > Generate Import

Fills the Import table with rows that enables access to the objects of the document to import from. Only rows that are not already present will be added (at the end of the table), so it is supported to repeat this operation at a later time to detect if any object has been added since the last time. Generate Import is, naturally, only available when the Table Editor contains an Import table.


Browsing in the Table Editor

With the Previous Table and the Next Table commands, you can easily browse the contents of the TTCN document.

File > Previous Table

Replaces the table shown in the Table Editor with the previous table in the document. To open the table five tables before the current, use <Ctrl> + Previous Table.

File > Next Table

Replaces the table shown in the Table Editor with the next table in the document. To open the table five tables after the current, use <Ctrl> + Next Table.

See also "Context Sensitive Popup Menu" and "Finding Tables by Name" .


Generating Behaviour Statements

In TTCN behaviour tables it is possible to get lists of user defined objects (e.g. constraints, timers etc.). Through these lists, you can generate a statement.

When you invoke the following commands, a row in the table should have the input focus.

Data Dictionary > Add Send Statement

Generate a Send statement by selecting a PCO, a type and a constraint.
This functionality requires that the TTCN document is analyzed. The PCOs, types and constraints with major reference problems or missing type references will not be presented in these lists.

Each list is split in two parts. The upper part contains the items corresponding to the selected items in the other lists. The lower part contains the rest of the items.

Figure 207 : Add Send statement dialog (receive is analogous)

  • PCOs
    Select a PCO or CP in this list and the Types and Constraints lists will be split accordingly.
  • Types
    Select an ASP, PDU or CM type in this list and the corresponding constraints and PCOs lists will be split accordingly.
  • Constraints
    Select a constraint in this list and the corresponding Types and PCOs will be split accordingly.
  • Open
    The selected constraint will be opened.
  • New
    A new constraint of the selected type is created. The new constraint will be opened.
  • Copy
    A new constraint which is a copy of the selected constraint is created. The new constraint will be opened.
  • Refresh
    Recompute the contents of the lists and re-display the dialog. The selection will be preserved.
  • Parameters
    If the selected constraint has a parameter list, an actual parameter list is specified here.
  • OK
    A Send statement is generated with the selected PCO (or CP), type and constraint.

Data Dictionary > Add Receive Statement

Generate a Receive statement by selecting a PCO, a type and a constraint.

A dialog which is analogous with Add Send Statement will be displayed.

Data Dictionary > Add StartTimer Statement

Generate a StartTimer statement by selecting a timer.

Figure 208 : Add StartTimer Statement dialog

  • When OK is clicked, a StartTimer statement is generated with the selected timer.

Data Dictionary > Add CancelTimer Statement

Generate a CancelTimer statement by selecting a timer.

A dialog which is analogous with Add StartTimer Statement will be displayed.

Data Dictionary > Add Attach Statement

Generate an Attach statement by selecting a test step and specifying an actual parameter list (if the test step has a formal parameter list).

Figure 209 : Add Attach Statement dialog

Data Dictionary > Add Timeout Statement

Generate a Timeout statement by selecting a timer.

A dialog which is analogous with Add StartTimer Statement will be displayed.


Reverting a Table

File > Revert

Causes all edits to the table since it was last opened to be discarded. In other words, the contents of the table are restored to what they were at the point when the table was opened.

This gives the TTCN suite a limited undo capability. Note that the analyze status of the table may be set to not analyzed by this command.


Creating a New Constraint Table

The Create Constraint and Copy Constraint commands, facilitate the creation of Constraint tables:

Tools > Create Constraint

Creates a new Constraint table - related to the Type table currently shown in the Table Editor - in a new Table Editor window.

If you use <Ctrl> + Create Constraint, the new Constraint table will instead be shown in the current Table Editor.

Tools > Copy Constraint

Creates a new Constraint table - that is an exact copy of the Constraint table currently shown in the Table Editor - in a new Table Editor window.

If you use <Ctrl> + Copy Constraint, the new Constraint table will instead be shown in the current Table Editor.


Generating the Test Suite Overview Tables

The generation of Test Suite Overview Tables is described in "Generating the Test Suite Overview Tables" .


Using Popup Menus

The background popup menu is accessible when you click the right mouse button. When you click the right mouse button and <Ctrl>, the context sensitive menu will be available.

Context Sensitive Popup Menu

The context popup menu contains only one operation, Find Table, but in addition it also contains some of the content of the table to be opened by this Find Table operation. The identifier to use in the Find Table operation is retrieved from the field content under the mouse pointer when the context menu was invoked.

Figure 210 : Example use of the TTCN Table Editor context popup menu

Background Popup Menu

The background popup menus are available in all the TTCN suite tables but the appearance differs in accordance with the applicable operations. The popup menus in synchronized behaviour tables and desynchronized behaviour tables have a totally different appearance and will be described below:

Synchronized Behaviour Tables

If the Table Editor contains a behaviour table which is synchronized, the popup menu will display the same menu entries as the SDT Link menu. For an explanation of synchronized and the commands in the SDT Link menu see 36 TTCN Test Suite Generation.

Desynchronized Behaviour Tables

If the Table Editor contains a behaviour table which is not synchronized, the popup menu will have a different appearance than in the previous case.

The popup menu will contain a sub menu containing all the menu entries of the Data Dictionary pull-down menu. It will also contain the following entries:

Cut Focused Row

Removes the focused row from the table and stores it in the clipboard.

Copy Focused Row

Copies the focused row to the paste buffer.

Paste Before Focused Row

Pastes the contents of the paste buffer before the focused row.

Delete Focused Row

Deletes the focused row.

Increase Indent

Increases the indentation of the focused behaviour line by one position.

Decrease Indent

Decreases the indentation of the focused behaviour line by one position.

Increase Sub Tree Indent

Increases the indentation of an entire branch in the behaviour tree by one position starting from the focused row.

Decrease Sub Tree Indent

Decreases the indentation of an entire branch in the behaviour tree by one position starting from the focused row.

Insert Row After

Insert a new row after the focused row.

Show Error Message

Displays the analysis status message (if any) of the focused field.

Find Table

Finds a named table.


Key and Button Bindings

Some bindings operate on the body rows as if they were organized as a tree (work only in the dynamic part of the TTCN document). The indentation level defines the tree structure.

Key | Action
osfUp | Move focus to a neighbor field.
osfDown | Move focus to a neighbor field.
osfRight | Move focus to a neighbor field.
osfLeft | Move focus to a neighbor field.
Ctrl+osfUp | Move focus to a neighbor field even when editing.
Ctrl+osfDown | Move focus to a neighbor field even when editing.
Ctrl+osfRight | Move focus to a neighbor field even when editing.
Ctrl+osfLeft | Move focus to a neighbor field even when editing.
osfInsert | Insert a new row, after focused row if already in body, otherwise last in body.
osfHelp | Get help on Table Editors.
Ctrl+Z | Run "Analyze & Stop"
Ctrl+S | Search forward with the current settings
Ctrl+R | Search backward with the current settings
character keys | Start editing field and then apply key.
Delete | Start editing field and then apply key.
... | Start editing field and then apply key.
Tab | Move focus to a neighbor field.
Shift+Tab | Same as <Tab> but in the opposite direction.
Ctrl+Tab | Navigate in the tool bar, the search bar, the scroll bars and the table
Ctrl+Shift+Tab | Same as <Ctrl+Tab> but in the opposite direction
Ctrl+space | Toggle selection of focused row
KP_Add | Increase indentation level of focused row
Ctrl+KP_Add | Increase indentation level of selected rows
Shift+KP_Add | Increase indentation level of focused subtree
Ctrl+Shift+KP_Add | Increase indentation level of subtree of single selected row
KP_Subtract | Decrease indentation level of focused row
Ctrl+KP_Subtract | Decrease indentation level of selected rows
Shift+KP_Subtract | Decrease indentation level of focused subtree
Ctrl+Shift+KP_Subtract | Decrease indentation level of subtree of single selected row
Ctrl+Shift+osfUp | Move focus to previous row at same indentation level
Ctrl+Shift+osfDown | Move focus to next row at same indentation level
Ctrl+Shift+osfRight | Move focus to last child row of focused row
Ctrl+Shift+osfLeft | Move focus to parent of focused row

Mouse button (OSF names) | Action
Button1 | Set focus to the field, and start editing.
Button2 | Move focus to the field.
Ctrl+Button1 | Toggle selection status of the row
Ctrl+Shift+Button1 | Toggle selection status of the subtree with the row as root, move the focus to the field under pointer


27 Analyzing TTCN Documents (on UNIX)

This chapter contains a reference manual to the Analyzer in the TTCN suite. A description of the Find Table command is also included. It can, for example, be used when you want to find erroneous tables that are displayed in the Analyzer log.

The TTCN Browser and the TTCN Table Editor are described in 25 The TTCN Browser (on UNIX) and 26 The TTCN Table Editor (on UNIX) respectively.

See Introduction to the TTCN Suite (on UNIX) for an overview of the TTCN suite tool-set.

Note: UNIX version

This is the UNIX version of this chapter. The Windows version is 32 Analyzing TTCN Documents (in Windows).


The TTCN Analyzer

The TTCN Analyzer in the TTCN suite does a complete syntax check on both TTCN and ASN.1 (as it is used in TTCN). The Analyzer also performs a number of static semantic checks, mainly the uniqueness and existence of identifiers.

For implementation reasons, the Analyzer does not exactly follow the TTCN standard - some syntax restrictions and relaxations apply. These differences will not affect the vast majority of users, but for reference they are documented together with the standard syntax in 39 Languages Supported in the TTCN Suite. This chapter also includes the static semantics supported by the TTCN suite.

During analysis, the TTCN suite compiles an extensive symbol table containing all named objects in the TTCN document and the references between them. This symbol table is used not only during the static semantic checks, but also by tools such as the Selector tool and the Compare tool.

The Analyzer can be called from various tools: from the Organizer, from a Browser, or from a Table Editor. It is possible to analyze an entire TTCN system, a whole TTCN document or just selected portions of a TTCN document (e.g. a single test case or all the PDU definitions).

The Analyzer considers a TTCN system to not contain any Flat View document, so it needs to be explicitly applied in order to analyze the flat view.

Using the Analyzer from the Organizer

Invoking the Analyzer from the Organizer is described in "Analyze TTCN" .

Using the Analyzer from a Browser

The Analyzer works either on the entire TTCN system or on selected items in the Browser it is applied on. Selections can either be made by using the mouse or by using the Selector tool (see "Using More Complex Selections" .

Selections can be arbitrary - the TTCN suite will analyze each selected item independently.

To analyze an entire TTCN document, do a Select All in the TTCN document browser and then apply the Analyzer. Alternatively apply the Analyzer on the TTCN document in the Organizer (see "Analyze TTCN" ).

Tools > Analyze

Conducts a syntax and static semantic check on the TTCN system or on the selected items (tables) in a Browser.

If an item is analyzed as incorrect, this will be recorded as an error message in the Analyzer log. Erroneous items are indicated by a black analysis bar in the Browser. On a color display this bar will be red.

Showing Progress

The Analyzer will, if invoked for a document or a whole system, display the progress made in the relevant Browser status window. This mechanism also provides the means to abort the analysis while it is running. Aborting is accomplished by clicking in the status window.

Tools > Analyze & Stop

Conducts a syntax and static semantic check on the TTCN system or on the selected items (tables) in a Browser but stops on the first found error and shows the table containing that error in a Table Editor.
  • To execute this command via the quick-button, <Ctrl> must be pressed.

Using the Analyzer from a Table Editor

When used from the Table Editor the Analyzer will be applied to the contents of that particular table.

Tools > Analyze

Conducts a syntax and static semantic check on the table contents.
If a field in a table is analyzed as incorrect this will be recorded as an error message in the Analyzer log. Erroneous fields are indicated by a black status bar and the field is shaded grey (red on a color display).

Tools > Analyze & Stop

Conducts a syntax and static semantic check on the TTCN system but stops on the first found error and replaces the table in the Table Editor with the table containing the found error.
  • To execute this command via the quick-button, <Ctrl> must be pressed.

Note:

When using the Table Editor, the On Field menu choice in the Help menu displays the TTCN BNF syntax applicable for the relevant field.

The Analyzer Dialog

The Analyzer uses the same dialog when started either from a Browser or a Table Editor:

Figure 211 : Analyzer dialog

Log Device

This option controls the log device for the Analyzer. The default value is Screen, but the log can be directed to a named file by choosing File or turned off altogether by choosing None.

For a full description of this command see "The TTCN Suite Logs" .

Enable Forced Analysis

Indicates that all selected items are going to be analyzed and no item will be skipped. An item is normally skipped if it is OK.

Retrieve ASN.1 Definitions

Indicates that the definitions of encountered ASN.1 references should be retrieved. An ASN.1 definition is retrieved if this option is set or if the definition has not been fetched before.

Only Browser Selection

Check this item if the analysis shall be restricted to the Browser selection (this option is not applicable if started from a Table Editor).

Verbosity

Full verbosity gives more detailed information. The following extra information is available with full verbosity:

  • Processing Cyclic references
    The items which will be left with incorrect references and incorrect analyze status are listed.
  • Detect unused objects
    If applied on a complete test suite without finding any errors, an additional search for unused objects is performed.

Error Messages

Errors detected during analysis are recorded in the log. For the fields in the header of a table the error messages have the general format:

==================================
Table name and table type
Field type 1
Error message
Field type 2
Error message
:
:
Field type n
Error message
==================================

Example 199

An error found in the Default Name (identifier) field of the Default Dynamic Behaviour called UT_DEFAULT:

=============================================
Analysis messages in table: UT_DEFAULT of type: Default Dynamic Behaviour
Default Name:
The referenced identifier UPPER_PCO is not declared.
UT_DEFAULT (p : UPPER_PCO)
----------------^
=============================================

In the body of a table (where the field type name does not uniquely define a field) the row number is also included:

  • Row number
  • Body type
  • Error message

Example 200

Errors found in a Test Step table header (the Default field) and in the body (rows 1 and 2 of the Behaviour Description):

=============================================
Analysis messages in table: ESTABLISH_CONNECTION of type: Test Step Dynamic Behaviour
Default:
Mismatched number of parameters: is 1, should be 0.
Row: (#1)
Behaviour Description:
The referenced identifier CR is of wrong type.
UPPER_PCO ! CR
------------^
Row: (#2)
Behaviour Description:
The referenced identifier CC is of wrong type.
UPPER_PCO ? CC
------------^
=============================================

Showing Error Messages

It is possible to display the Analyzer error message (if any) that is associated with the field in a table that has the current input focus. To do this, select Error Messages from the Table Editor Show menu.

Resolving Forward References

During analysis, the TTCN suite does two main tasks:

  • It checks the syntax of the abstract TTCN document.
  • It checks some of the static semantics of the TTCN document.

The syntax of TTCN is defined in ISO/IEC 9646-3 Annex A as a list of BNF productions or rules. See also "The TTCN-MP Syntax Productions in BNF" . The TTCN suite checks all these rules except for a very few minor deviations; for more information, see "The Restrictions in the TTCN Suite" ). If a rule is not followed in the TTCN document then this will be reported as an error by the Analyzer.

The static semantic rules of TTCN are also defined in Annex A of ISO/IEC 9646. These are in the form of text statements which limit the use of some of the syntax rules, usually in a specific context. "TTCN Static Semantics" and "ASN.1 Static Semantics" describe the static semantics which are controlled by the Analyzer. The static semantics currently supported are mainly of the following types:

  • Identifiers (names) are checked for uniqueness with respect to the scoping rules defined in ISO/IEC 9646-3
  • The existence of referenced TTCN objects (e.g. a Test Step) from another TTCN object (e.g. Test Case) is verified
  • Type control and type restriction control

In order to achieve this, the Analyzer constructs a symbol table of all the named TTCN objects that it finds during analysis, e.g. variable names, type identifiers, tables, etc.

This symbol table is used by some of the other tools, such as the Selector and the Reporter. This explains why it is necessary to ensure that the TTCN document is analyzed before applying these tools - the symbol table is updated each time the TTCN document is analyzed.

It is important to note that TTCN allows forward references. For example a Test Step may attach another Test Step that is declared later on in the TTCN document, that is, the referenced (i.e. attached) Test Step, appears after the Test Step that has done the attach.

The Analyzer has a feature called back-pass designed to resolve forward references. The back-pass is automatically invoked at certain points in the analysis process.

Forward references usually appear in the context of ASP/PDU definitions, constraints and as the result of attachment statements in behaviour trees. This is the reason that the Analyzer does not traverse the items to be analyzed in exactly the listed order. The Analyzer order deviates from the listed order in a few places:

  • Items in the PDU Type Definitions sub-tree are analyzed before items in the ASP Type Definitions sub-tree.
  • Items in the PDU Constraint Declarations sub-tree are analyzed before items in the ASP Constraint Declarations sub-tree.
  • Items in the Defaults Library sub-tree are analyzed before items in the Test Step Library sub-tree and those are analyzed before items in the Test Cases sub-tree.
  • Items in the Declarations Part, Constraints Part and Dynamic Part are analyzed before any items in the Import Part (where applicable) and overviews.

ASN.1 External Type/Value References

References to ASN.1 definitions in external ASN.1 modules can occur in the following four TTCN tables:

  • Test Suite Constant Declarations By Reference
  • ASN.1 Type Definitions By Reference
  • ASN.1 ASP Type Definitions By Reference
  • ASN.1 PDU Type Definitions By Reference

In these tables there are three important fields to consider:

  • Module Identifier (set by user)
    The name of the ASN.1 Module. This should be the real name of the model, i.e. the name stated inside the module itself.
  • Type Reference/Value Reference (set by user)
    This is the name of the desired type (or value).
  • Type Definition/Value (set automatically when fetched)
    This is the field where the fetched type definition/value is copied into.

The term definition is used below both to denote an ASN.1 type definition and an ASN.1 value.

When an ASN.1 reference is analyzed, the referred definition must be available to the Analyzer. In the pro formas for this kind of reference in the TTCN suite, there is an extra column where both the definition and the parse tree is stored.

Since the ASN.1 module is accessible from the Organizer the Analyzer can fetch the definition. If the Analyzer encounters any reference to a type/value, the definition is fetched, given the type/value name and the module identifier, and copied into the external field before the field is analyzed. The operation of fetching the definition of the reference is controlled by an option in the Analyzer dialog. Important to note is that the fields Module Identifier and Type/Value Reference are not parsed. This means that if a change is made in either of these two fields, the row will not be analyzed and thus no fetching will be made. The solution to this is to set the Enable Forced Analysis in the Analyzer dialog when altering a reference. See "The Analyzer Dialog" .

To use external ASN.1 module references in the TTCN suite, information about the referred ASN.1 module must be available. That is why the ASN.1 module must appear in the Organizer and a dependency must be defined from the ASN.1 Module to the TTCN document. See "Dependencies" .

Analysis can be invoked either from the TTCN suite or from the Organizer. The only difference, regarding dependencies, is that when the analysis is made from the TTCN suite the dependencies are fetched explicitly while the Organizer always precedes an analysis with a dependency update.

Analyzing ASN.1 References

This is the general algorithm when encountering an ASN.1 in the analysis phase.

  1. First of all, an attempted fetch is only made if no current definition exists or if the Analyzer fetching-option is selected.
  2. The actual fetching is made, see "Retrieving External ASN.1 Definitions" .
  3. If the definition is successfully fetched, the identifiers in the definition is converted to TTCN compatible syntax, see "Syntactic Conversion" .
  4. Finally a possible update of the definition is made and the analysis is continued.

Retrieving External ASN.1 Definitions

From the ASN.1 module a simple parse tree is built to access its contents. The parse tree is (re-)built when either it has not been built before or the ASN.1 module has been modified since last access. The parse tree for an ASN.1 module "lives" for the duration of the whole analysis phase.

Syntactic Conversion

The received definition must be manipulated in the following sense. All identifiers must be syntactically checked and altered if they include any characters that is disallowed in TTCN. The rule is that all `-' (dash) characters in an ASN.1 name is replaced by a `_' (underscore).

No special care has to be considered to ASN.1 comments since they are ignored when the parse tree is built from the module.

External type references in the type definition (e.g "... Module.Type...") will only be converted like above and left for the Analyzer to deal with (see also "Restrictions" ).

Restrictions

These features are not supported in TTCN:

  • External type reference identifiers on the form ModuleIdentifier.Type/Valuereference are not supported.
  • Type/value references within the same ASN.1 module are not supported.

Furthermore there are restrictions in the ASN.1 Utilities when it is used to extract the external types and values. These restrictions are introduced in translating ASN.1 to SDL but since the same algorithm is used for extracting types and values, the restrictions are also relevant for the TTCN suite. For more information, see "Translation of ASN.1 to SDL" .

Error Handling

Any error that occurs while finding, parsing or accessing the ASN.1 module will cause the old definition to remain. Only when a completely successful fetch has been made, the definition will be updated. Possible errors could be:

  • The ASN.1 Module not found among the dependencies.
  • The ASN.1 Module file could not be found or was not readable.
  • The ASN.1 Module file was not syntactically correct.
  • The referred type/value could not be found in the module.

See 14 The ASN.1 Utilities for a more general view on ASN.1 usage.

TTCN Static Type Restriction Control

The TTCN standard defines a set of semantic rules for type definitions. In particular it defines simple types as types which might contain a true subset of the values which the parent type might contain. The Analyzer now analyzes the TTCN type system and also reports violations of these rules. This analysis is implemented as a post-pass over the related tables, and is only applied when the previous passes have been successful.

Furthermore, restriction control is performed on a number of other constructs in the TTCN language, thus facilitating the task of writing semantically correct TTCN documents. Most of the TTCN types and values are checked and thereby reducing the chance of programming errors slipping through to other tools which depends upon the correctness of the TTCN document.

Application of Static Type Restriction Control

Static Type Restriction Control is applied to at least the following TTCN tables and fields:

  • Simple type definitions
  • TTCN structured type / ASP / PDU / CM definitions
  • Test Suite Constant Declarations
  • Test Suite Variable Declarations
  • TTCN Structured Type / ASP / PDU / CM Constraint declarations
  • Actual constraint reference parameter lists
  • Actual parameter lists

The Static Type Restriction Control also evaluates expressions in advance, where possible, and checks that the result does not violate the type restrictions of the field where the value is found. It operates on both types and values, regarding specific values as special cases of types.

Reducing Level of Restriction Control

Setting the environment variable ITEX_RESTRICT_LEVEL to the value NONE will disable the strict checking of type restrictions. This might be useful for allowing test suites with deliberate type errors pass through the analysis. A setting of SOME will relax the analysis somewhat, and is recommended before trying NONE. In order to get the most strict analysis (default), the value STRICT might be used.

Generating a Flat View

A Flat View is the part of the modular TTCN suite environment that presents the tree structure of an expanded modularized TTCN source. This complete view includes all explicit defined objects in the TTCN system.

The Flat View interactive interfaces is similar to the Browser. Unlike the Browser, the Flat View is started (generated) from the Organizer.

The structure of the TTCN source in a Flat View is similar to a Test Suite. Neither the Import tables nor Export tables are displayed in a Flat View.

Generating a Flat View in a system, requires that at least the root document of the system to be connected to a file. The connected document must be of one of these types:

  • Test Suite
  • Modular Test Suite
  • TTCN Module

If this condition is not fulfilled, the operation Generate Flat View fails. Also if the current Flat View is modified or is locked (by any user) the operation fails.

If a Flat View is edited by the user, it must be saved in another document file. The user is asked for a new file name. Otherwise, if the existing Flat View file is not modified, it is overwritten by the new generated Flat View if the generation is redone.

For each TTCN system in the organizer only one instance of Flat View can be generated. A Flat View can be regenerated. A Flat View includes all explicit defined objects in the system at the time of the (re)generation.

The first time the Flat View in a system is generated, the name of the Flat View file is the same as the file name of the root document in the system if the name is not already used. The file extension for a Flat View file is .ifv.

An already existing Flat View is always connected to a document file. If this existing Flat View is in the current target directory (and neither is modified nor locked) the Flat View file is reused (the Flat View is regenerated). Otherwise a new Flat View file in the current target directory is used.

Algorithm

When the command Generate Flat View is invoked the following cases may occur:

No Flat View is Available

In other words this is the first time a Flat View is generated for the given system. A new Flat View is generated in the target directory. The name of the document file is generated. This name is derived from the file name of the root document in the system. A Flat View icon is added to the selected TTCN system in the Organizer and it is connected to the generated document file.

A Flat View is Available

If the file connected to the existing Flat View either is locked or modified the operation fails. If the existing file is not in the target directory do as the previous case except not to add a Flat View system node.

Otherwise if the existing file is in the current target directory the file is reused (the current document file name must have been derived from the file name of the root document in the system).

If the Flat View is modified, the operation (Generate Flat View) fails and the user is asked to save the Flat View (into another file) before regenerating.

Save a Flat View

A user modified Flat View must be saved as a document of type (non-modular) Test Suite in another file than the Flat View file.

When the user invokes the save operation from the Organizer, a new file name must be given otherwise the save operation fails. If the user invokes the save operation from the TTCN suite a file browser pops up and the user is asked for a file name.

Merging Objects into a Flat View

A Flat View contains a copy of all explicitly defined objects in a system. When a Flat View is generated for a TTCN system, explicitly defined objects in each system node is merged into the Flat View. The merged objects may have the same name.

Objects of the following types are treated special:

Overview Tables

The main table in the Overview Part is the Test Suite Structure table. Depending on the type of the root node in the system the Overview tables in the generated Flat View contain the following information.

Test Suite (Modular or Non-Modular)

This type of system nodes have a Test Suite Structure table. The header of the corresponding table in the Flat View inherits the information in the header of the root table.

The Detailed Comments in the index tables are copied to the index tables in the Overview part of the generated Flat View.

TTCN Module

In this case the TTCN Module Exports table is the corresponding table to the Test Suite Structure table in the Flat View. The TTCN Module Exports contains two extra header fields: Objective and TTCN ModuleRef. These two fields are ignored when the Flat View is generated.

The Detailed Comments in the index tables are copied to the index tables in the Overview part of the generated Flat View.

Package

In this case there is no corresponding table to the Test Suite Structure table in the generated Flat View.

Import and Export Tables

These tables contain no explicit defined object and therefore they are ignored.

External Tables

These tables contain no explicit defined object and therefore they are ignored.

Multiple Tables

The objects in the multiple tables are added to the corresponding multiple table in the generated Flat View. The Detailed Comment in the multiple table is added to the Detailed Comment in the corresponding multiple table.

Single Tables

Add each single table to the appropriate place in the generated Flat View.

Group Nodes

For each group node if it does not exist already in the generated Flat View create a new group node.


Finding Tables

The Find Table tool searches for and displays named tables. The name searched for is given by the currently marked piece of text in any TTCN suite window. This tool is very useful when debugging a TTCN document from an Analyzer log.

Finding Tables by Name

The Find Table tool is available from the Tools menu in the TTCN sub menu in the Organizer, from the Tools menu in a Browser and from the Tools menu in a Table Editor. Unlike most other tools it does not require a selection: it applies to the context given by where the tool is started (i.e. a TTCN table or a TTCN document), and its action is the same whether it is invoked from the Organizer, from a Browser or from a Table Editor.

Tools > Find Table

Finds a named table or the table in which a named object, such as a test case variable, is declared. The name searched for is given by the currently marked piece of text in a TTCN suite window. If no text is marked Find Table will use the contents of the text clipboard (used for Cut and Copy).

A typical use of this tool would be to debug a TTCN document when analyzing. Erroneous tables identified in the Analyzer log window can be easily found by marking the names of these tables in the log window and applying the Find Table tool.

The Find Table tool is able to find named objects with the name specified as <document name>::<object name> (e.g. Test_Suite_A::SEND), where <document name> is the name of a document in the TTCN system and <object name> is the name of an object available in the context of that document. This may also be specified as <document name>__<object name> (i.e. with underscores instead of colons).

Note:

The Find Table tool will in fact use marked text as the look-up string from any X Window, not just TTCN suite windows.

Example 201

Marking the PDU name CON_req in, say, the behaviour line L! CON_req (X:=1) of a test step, and then choosing the Find Table tool will cause the PDU definition of CON_req to be displayed (assuming it exists).

On the other hand, marking the test case variable X in the same line would cause the Test Case Variables table, in which X is declared, to be displayed.


28 The TTCN to C Compiler (on UNIX)

This chapter describes what the TTCN to C compiler is used for, how to run it and the structure of the generated code.

When the TTCN to C compiler has translated TTCN into C code, the code must be adapted with the system that is to be tested. The adaption process is described in 37 Adaptation of Generated Code.

Note: ASN.1 support

The TTCN to C compiler supports only a limited subset of ASN.1. See "Support for External ASN.1 in the TTCN Suite for further details on the restrictions that apply.

Note: UNIX version

This is the UNIX version of the chapter. The Windows version is 33 The TTCN to C Compiler (in Windows).


Introduction to the TTCN to C Compiler

When developing new systems or implementations of any kind, the developing process is divided into well defined phases. Most commonly, the first phases involve some kind of specification and abstract design of the new system. After a while, the implementation phase is entered and finally, when all parts are joined together, the test phase is activated.

In any case when a system is tested, we want to make sure that its behavior conforms to a set of well defined rules. TTCN was developed for the specification of test sequences. Unfortunately, as very few systems interpret or compile pure TTCN, we need to translate the TTCN notation into a language which can be compiled and executed. In the case of the TTCN suite, the TTCN to C compiler translates TTCN to ANSI-C.

Even after the TTCN code has been translated, there are a couple of things that need to be taken care of. In this case, we must adapt the generated code with the system it intends to test. This chapter describes how the TTCN to C compiler is used. The adaption process is described in 37 Adaptation of Generated Code.


Getting Started

Unfortunately a test sequence description expressed in TTCN can not easily be executed as it is. This is because the test notation is not executable and only few test environments interpret pure TTCN. A different approach to create an executable test suite (ETS), is to translate the formal test description into a language which can be compiled into an executable format.

The TTCN to C compiler translates TTCN into ANSI-C which can be compiled by an ANSI-C compiler. Figure 212 depicts the first step in the process of creating an ETS using the TTCN to C compiler.

The generated code, called the TTCN runtime behavior, is only one of the two major modules of an ETS.

The second module which is needed includes test support functions which are dependent on the protocol used, the host machine, test equipment, etc. For this reason, it is up to the user to write this second module and in such way adapt the TTCN runtime behavior to the system he/she wants to test.

Figure 212 : Translating TTCN to ANSI-C

The adaption process is described in 37 Adaptation of Generated Code. Figure 213 displays the anatomy of the final result.

Figure 213 : The anatomy of an ETS

Running the TTCN to C Compiler

The TTCN to C compiler can be activated either from the TTCN Browser, both as a quick button and a menu command, or from the Organizer when a TTCN test suite is selected.

Note:

Observe that the TTCN to C compiler is unable to function correctly if the test suite is not fully verified correct. This verification is accomplished by running the Analyzer tool on all the parts of the test suite.

Tools > Make

When you select Make, the TTCN Make dialog is opened. The dialog contains two important toggle buttons, Analyze & Generate and Compile & Link.

Figure 214 : Dialog for starting the TTCN to C compiler

Analyze & Generate

If Analyze & Generate is set, the Analyzer will first be called to analyze the test suite before any code is generated. If errors are found, these will be reported and no code will be written to file. The generation phase performed after the analysis phase will only generate code for the parts that need to be re-generated.

Directory for generated files

If code is generated, that code will reside in the directory specified in this field.

Makefile

If Compile & Link is set, the TTCN suite will also take care of the making and linking of the generated code. At this point you have the possibility to specify how you want the code to be built. Either you can specify that the default generated makefile is to be used, or your own special makefile. This is done by setting the radio buttons in the field below the Makefile toggle button.

Compile & Link

The compiler needs to know what files to link into the executable. Three different possibilities are at hand:

  • You have not yet written an adaptor, but you want an empty template to allow compilation to go through successfully.
  • You have already written an adaptor which you want to link into the executable.
  • You want to link to a simulator kernel to allow you to simulate.

The TTCN to C compiler assumes the first case to be the default one. In this case the Generate empty adaptor files radio button is set. If you do not have adaptor files (adaptor.c and adaptor.h) in the target directory, these will be created, as empty templates, for you. If you already have generated and edited adaptor files these will of course not be overwritten.

If you already have your own compiled adaptor files elsewhere in the file system, these files, as object files, should be listed in the text field below the Use the object files dialog button. Observe that you should use absolute path names for the adaptor files to avoid problems for the makefile to find these files! An absolute path name is a path name that identifies a file uniquely from the root of the files system, for example /home/myhome/myadaptor.o.

Finally, if you want to generate code for simulation, the Use standard kernel radio button should be set with the option Simulation. This is the only available kernel at the moment so no other choice is valid here.

TTCN to C Compiler Options

By pressing the TTCN to C Compiler Options button in the Make dialog, the dialog depicted in Figure 215 will be displayed.

Figure 215 : Setting extra TTCN to C compiler options

  • If the Generate debug information in code button is set, the compiler will generate extra code for tracing and debugging.
  • If the Generate a local make options file button is set, the compiler will generate a file called makeopts in the target directory. This file is used to define settings used by the makefile. You have the flexibility to choose compiler and add extra information for the make process.
  • If the Ignore bodies of test suite operations button is set, the compiler will ignore to generate code for test suite operations. This is useful if you already have a file with your own test suite operations that only need to be linked to the rest of the code. If the button is not set, the test suite operators will be generated and included in the file tsop_gen.c.
  • If the Allow old style encoders/decoders button is set, the compiler will generate two extra files that will allow you to use an adaptor written for the old code generator to be used with the new one.
  • If the Generate, but do not write to file button is on, the compiler will not generate code. This is useful for users that only wish to generate code when they know no generation errors will occur.
  • If the Do not report warnings button is set, the compiler will not inform you about warnings.
  • By selecting one of the radio buttons None, Generate BER encoders/decoders or Generate PER encoders/decoders the compiler will either omit generation of encoders/decoders or generate extra code for BER or PER encoding and decoding support. See ASN.1 Encoding and De-coding in the SDL Suite.
  • By selecting one of the radio buttons Suppress messages, Normal Messages or Verbose messages you can set the level of verbosity when the compiler generates code. The default value is Normal messages.

You can also choose the names of the files you want to use. This is done in the fields in the lower part of the TTCN to C compiler options dialog.

  • The optional Static file directory field should only be used by users that brutally want to change the behavior of the compiler by using their own static files. For "normal" users it is recommended that this field is not set.
  • The Types file field determines the name of the file to which type definitions from your test suite are generated. The default value is types_gen.c.
  • The Constraints file field determines the name of the file to which constraint definitions from your test suite are generated. The default value is constraints_gen.c.
  • The Dynamic part file field determines the name of the file to which the dynamic part from your test suite is generated. The default value is dynamic_gen.c.
  • The Log file field determines the name of the file to which messages about the generation are to be written. Default is standard out.

Make

If the Make button is pressed, the compiler will only generate code for the parts that really need to be re-generated.

Full Make

If the Full Make button is pressed, everything will be regenerated again.

When the generation phase is started, a new log window will be displayed where information about the compiler actions will be displayed.

Running the TTCN to C Compiler from the Command Line

Please see "Running the TTCN to C Compiler from the Command Line" .


What Is Generated?

In the case of the code generated from the compiler we also need a set of static functions which handle TTCN basics and other internal events. Even if these functions are vital for the successful compilation and execution of the generated code, the user should not have to worry about this part. These functions are gathered in a small set of static files which are compiled by the generated makefile and linked with the rest of the code.

The Code Files

The generated makefile is the file containing a definition of how the code should be compiled and linked.

The adaptor.h and adaptor.c files are the files that contain the adaptation code. If code is generated for the first time, these files will be generated by the compiler with empty function templates for the user to implement. On the other hand, if these files are present in the target directory the user does not have to worry about getting them overwritten.

The *_gen.{c,h} files contains the code generated for the TTCN test suite.

The asn1ende.h file contains the encode and decode functions for the ASN.1 Types. See ASN.1 Encoding and De-coding in the SDL Suite. (Only generated if ASN.1 encoding/decoding support has been selected)

The Adaptation

We are now ready to deal in greater detail with the adaptation phase which is the final phase to create an executable test suite. The adaptation process is described in "Adaptation of Generated Code" .


TTCN Test Logs in MSC Format

Please refer to "TTCN Test Logs in MSC Format" .


29 The TTCN-SDL Co-Simulator (on UNIX)

This chapter describes the TTCN-SDL Co-simulator in the UNIX version of the TTCN suite. It gives an introduction to the concept of the TTCN-SDL Co-simulator, as well as a guide to its functionality and an introduction to using the TTCN-SDL Co-simulator for controlling real Executable Test Suites.

Note: UNIX version

This is the UNIX version of the chapter. The Windows version is 34 The TTCN-SDL Co-Simulator (in Windows).


The TTCN-SDL Co-Simulator

The TTCN-SDL Co-simulator allows you to:

  • Execute a compiled test suite and inspect the results.
  • Execute test cases and test groups by stepping through the TTCN lines or executing at full speed with the possibility to set breakpoints at given tables/lines.
  • View the actions performed by the various parallel test components (PTCs) in multiple windows if needed when executing a concurrent test suite.

The possibilities to pinpoint the cause of the test result beyond the test verdict fail are vast, and will undoubtedly help in improving the time needed for testing in the development phase.


Performing a Co-Simulation

Given a test suite containing a set of tests you want to execute together with a simulated SDL system, the following steps are to be performed:

  1. Analyze the test suite and make sure it contains no errors. (This can be done using the TTCN suite Make dialog.)
  2. Using the TTCN suite Make dialog, build an executable test suite with the Use standard kernel radio button set, and with the Co-Simulation kernel selected.

  3. Start the TTCN-SDL Co-simulator by pressing the co-simulation quick-button on the top of the TTCN Browser, or selecting Start Co-Simulator from the Browser Tools menu.


Setting Up a TTCN-SDL Co-Simulation

A complete test of a system design can be performed prior to building a prototype by designing the system in SDL, and using the TTCN suite to write test specifications in TTCN, or using a tool to automatically or semi-automatically generate test suites from a system description in any language. The actual testing is then a matter of connecting the two simulators.

To achieve the connection, follow these steps:

  1. Generate and start the SDL Simulator.
  2. Start the TTCN-SDL Co-Simulator by selecting the Co-Simulator quick-button from the tool bar of the Browser.
  3. When the TTCN-SDL Co-Simulator has appeared, along with a selection of executable test cases and test groups, enter the command
    start-itex in the SDL Simulator.
  4. Select one or more test cases or test groups in the TTCN-SDL Co-simulator Setup window, and click the Run Test button.
  5. In the SDL Co-Simulator, give any of the start commands (Forever, Go...).

The loaded SDL system is now being simulated on the SDL suite side, and conformance tested from the TTCN suite side with the TTCN-SDL Co-Simulator.


The TTCN-SDL Co-Simulator User Interface

Figure 216 : The TTCN-SDL Co-simulator Test Setup window

The Test Setup window is the main window of the TTCN-SDL Co-simulator. It manages an Executable Test Suite and a number of associated documents. The main part of the window is used for test selection. The left list depicts the currently available tests, and the right list depicts a selection of test cases and/or test groups.


Managing Setup Documents

The menu choices in the File menu are used for creating and saving documents. For information on the operations not mentioned here, see the general description of a Telelogic Tau File menu in "File Menu" .

File > New

Creates a new Setup document. The new setup inherits the Executable Test Suite from the current Setup.

File > Open

Opens a previously saved Setup file in a new window.

File > Save

Saves the current Setup file. If the Setup was not previously saved, a name will be prompted for. A saved Setup consists of the file names of the associated documents, as well as the ETS name.

File > Save As...

Saves the Setup file with another file name. A running ETS might need to be restarted in order for changes to become effective.

File > Restart ETS

Restarts the Executable Test Suite / TTCN-SDL Co-simulator. This may compromise the consistency of running test cases, but might be necessary in order to make changes to the Setup effective.

File > Close

Closes the current view of the Setup document. If there are no more views of the Setup, the ETS will be terminated along with any test cases. If the Setup has been changed, a dialog will prompt for a file name for saving the Setup before it is closed. If the Setup is the only one currently open, the program will quit.


Selecting Test Cases and Groups

This section lists the TTCN-SDL Co-Simulator commands available in the Edit menu.

Edit > Documents > Select ETS

Enables you to select another ETS for the test Setup. This might be useful for selecting a new ETS, using the same Setup as the old one.

Edit > Documents > Add Document

Enables you to add a document type to this Setup. A standard set of document types are provided by default at program start-up.

Edit > Show > Test Cases

Sends a command to the ETS such that it lists all Test Cases in the Available list.

Edit > Show > Test Groups

Sends a command to the ETS such that it lists the Test Groups.

Edit > Add All

Adds all tests from the set of available tests to the set of selected tests.

Edit > Add

Adds the tests currently selected in the Available list, to those present in the Selected list. Both test cases and test groups may be present in the Selected list at the same time.

Edit > Remove

Removes the selected tests from the Selected list.

Edit > Remove All

Removes all tests from the Selected list.


Executing a Test

This section lists the TTCN-SDL Co-simulator commands available in the Execute menu.

Execute > Test > Cancel

Cancels a test in progress. All information will be lost and the ETS returns to its initial state. This might compromise the consistency of a test since it might leave the IUT in any state.

Execute > Test > Pause

Temporarily pauses the test execution. This might be used to examine the state of the IUT or of the ETS.

Execute > Test > Step

Steps one line of TTCN code. In a simulated environment this is a well-defined operation, as opposed to a real test system. In the latter case, timing might be compromised.

Execute > Test > Run test

Runs/Continues a test at full speed until it is finished or until a breakpoint is reached.

Execute > Breakpoints > Breakpoints

Shows the breakpoint editor, as described in "The TTCN-SDL Co-Simulator Editor" . Notice: If the quick button is disabled, this is because no breakpoint document is currently associated with the Setup. Use this menu item to add such a breakpoint document to the Setup.

Execute > Breakpoints > Enable

Enables all breakpoints (default).

Execute > Breakpoints > Disable

Temporarily disables all breakpoints.

Execute > Monitor > PCOs

Monitors all PCO Queues in a separate monitor window.

Execute > Monitor > Timers

Monitors all Timers in a separate monitor window.

Execute > Monitor > PTCs

Monitors all CPs in a separate monitor window.

Execute > Monitor > CPs

Monitors all CPs in a separate monitor window.

Execute > Enable ITEX Tracking

Highlights the next statement line to be executed in the Table Editor. This is on condition that you are running a TTCN-SDL Co-simulator session and that the TTCN-SDL Co-simulator was started from within the TTCN Suite.


Viewing Documents

This section lists the TTCN-SDL Co-simulator commands available in the Window menu.

Window > New Window

Enables you to display a new view of the same Setup, with a possibly different test selection. No new Setup is created with this command.

Window > Execution Trace

Shows a new view of the Test Execution trace. If the item is not accessible, select Document and then Add Trace Document in the Edit menu to add a document of this type to the current Setup.

Window > Conformance Log

Shows a new view of the Test Conformance Log. If the item is not accessible, select Document and then Add Log Document in the Edit menu to add a document of this type to the current Setup.

Window > Configuration Editor

Shows a new editor for the Test Configuration, see "The TTCN-SDL Co-Simulator Editor" . If the item is not accessible, select Document and then Add Configuration Document in the Edit menu to add a document of this type to the current Setup. The Test configuration is system dependent and not used for co-simulation.

Window > Parameter Editor

Shows a new editor for the Test Suite Parameters, see "The TTCN-SDL Co-Simulator Editor" . If the item is not accessible, select Document and then Add Parameter Document in the Edit menu to add a document of this type to the current Setup.


The TTCN-SDL Co-Simulator Editor

A generic editor is present for editing some of the documents, as for instance the Breakpoints, Parameter and the Configuration. It is of limited interest to those who are only interested in TTCN-SDL co-simulation, but it might be of more interest if you consider using the GUI for running real executable test suites.

Figure 217 : The TTCN-SDL Co-simulator editor for breakpoints

The editor is row oriented and the format of each row is determined by the current ETS. It is up to the ETS to warn the user for syntactic and/or semantic errors in the edited document. Please refer to the documentation of the ETS for more throughout definitions of the expected contents of each row.

Managing Documents in the TTCN-SDL Co-Simulator Editor

The menu choices in the File menu are used for creating and saving documents. For more information, see the general description of a Telelogic Tau File menu in "File Menu" .

Editing Documents in the TTCN-SDL Co-Simulator Editor

The following section lists the TTCN-SDL Co-simulator Editor commands available in the Edit menu.

Edit > Undo

Undoes the last change of the document. This functionality is disabled when the document is saved or if a new document is opened. There are more than 200 undo steps.

Edit > Redo

Redoes the next undone change to the document. Applying a new operation removes any non-redone steps.

Edit > Cut

Cuts the currently selected row from the document. The row is placed in an internal clipboard.

Edit > Copy

Copies the currently selected row from the document to the internal clipboard.

Edit > Paste

Pastes the contents of the internal clipboard before the currently selected row.

Edit > Add

Inserts an empty row before the currently selected row.


Files Handled by the TTCN-SDL Co-Simulator

A total of 7 file types are handled by the TTCN-SDL Co-simulator user interface. Fortunately, most sessions involve only a subset of those file types. The file types and a short description are listed below:

  • ETS file
    Executable Test Suite file. This is a file generated by the TTCN to C compiler. It might in particular be a co-simulator which has a specialized kernel for running in cooperation with an SDL suite simulated system.
  • Setup file (.tts)
    A Setup file is a collection of the other file types and is used to manage a particular test Setup such that it can easily be re-created.
  • Log file (.log)
    A Conformance Log File consists of the output from an ETS, as specified in the ISO-9646 standard.
  • Trace file (.ttt)
    A simplified version of the Log file, more corresponding to the actual TTCN tables contents.
  • Test Suite Parameters file (.ttp)
    A file for transferring the test suite parameters to the ETS. Comparable to the PICS/PIXIT file of ISO-9646. Please see the ETS kernel implementators user guide for details.
  • Configuration file (.ttc)
    Test platform dependent file. Please see the ETS kernel implementators user guide for details.
  • Breakpoints file (.ttb)
    A given set of breakpoints might be saved in the editor for later reuse.


Information Messages

The TTCN-SDL Co-simulator can present messages to the user in three forms:

  • Informative messages
  • Warning messages
  • Error messages

Informative Messages

Informative messages are normally presented at the status bar. These might be for instance progress reports or other simple messages, which are only of a temporary interest (such as the tool tips).

Warnings Messages

Warnings, also known as "non-critical errors", are events that indicate a problem during the preparation for a co-simulation, or during the actual co-simulation run. These are always presented in standard Motif warning dialogs. Warnings normally does not cause a co-simulation to halt.

Error Messages

Critical errors will halt the co-simulation. They are presented by an error dialog that appears in front of the application. The error dialog can often appear large and intimidating, but it simply gives a more verbose reason to why the error occurred, and what steps should be taken to avoid it.


Using the UI with an ETS

The user interface uses a publicly available format for communication with the ETS. Implementation of a management interface for an ETS is simple since the ETS only uses the standard I/O channels for communication with the GUI. Please request a protocol definition from Telelogic if you consider adapting your own test suite using this GUI. It is currently unlicensed and might be started using this command:

$telelogic/itex/bin/${hosttype}bin/isimui -help


Type Mappings in Co-Simulation

This section specifies the data type mapping used by the co-simulation of the SDL Simulator and the TTCN-SDL Co-simulator. Specifically it identifies the transfer syntax used in the communication between the SDL Simulator and the TTCN-SDL Co-simulators for each supported data type.

TTCN Types

This subsection describes the mapping from TTCN types to SDL types. For each TTCN type the corresponding SDL type and some examples of the transfer syntax is given.

Predefined Types

TTCN Type
SDL Type
Transfer Syntax Example

 INTEGER

 integer
1 -3

 BOOLEAN

 boolean
true false

 BITSTRING

 bit_string
`0101'B

 HEXSTRING

 -

 OCTETSTRING

 octet_string
`4BA0'O

 NumericString

 NumericString
`3295' (0..9 + space)

 PrintableString

 PrintableString
`ask38-'

 TeletexString

 -

 VideotextString

 -

 VisibleString

 VisibleString
`xy'

 IA5String

 charstring
`123 abc'

 GraphicString

 -

 GeneralString

 -

References Types

TTCN Type
SDL Type
Transfer Syntax Example

 SimpleType

 syntype
same as referenced type

 Struct

 struct
(. 1, true .)

 PDU

 struct
(. 1, true .)

 ASP
- (ASPs maps to signals)

ASN.1 Types

This subsection describes the mapping from ASN.1 types to SDL types. For each ASN.1 type the corresponding SDL type and some examples of the transfer syntax is given.

ASN.1 Type
SDL Type
Transfer Syntax Example

 BOOLEAN

 boolean
true false

 INTEGER

 integer
1 0 -55

 ENUMERATED
enumeration types
The enumerated values

 REAL
- (Not supported in the TTCN to C compiler)

 BIT STRING

 bit_string
`0100'B

 OCTET STRING

 octet_string
`4BA0'O

 NULL

 null
Null

 SEQUENCE

 struct
(. 1, true .)

 SEQUENCE OF

 array, string
(: 1, 2 :)

 SET

 -

 SET OF

 bag, powerset
[ 1, 2, 2 ]

 CHOICE

 choice
<name> : <value>
 ANY

 -

 OBJECT IDENTIFIER

 -

Selection type

 -

Tagged type

 -

SubType
syntype
same as referenced type

SDL Types

This subsection defines the mapping from SDL to TTCN and to ASN.1. For each SDL type first the TTCN type is given, then the ASN.1 type and finally an example of transfer syntax.

Predefined Sorts

SDL Type
TTCN Type
ASN.1 Type
Transfer Syntax Example

 Bit

 BITSTRING

 BIT STRING
(SIZE (1))
`1'B

 Bit_String

 BITSTRING

 BIT STRING
`1010'B

 Boolean

 BOOLEAN

 BOOLEAN
true false

 Character

 IA5String

 IA5String (SIZE
(1))
`a'

 Charstring

 IA5String

 IA5String
`123 abc'

 IA5String

 IA5String

 IA5String
`123 abc'

 NumericString

 NumericString

 NumericString
`123'

 PrintableString

 PrintableString

 PrintableString
`ask38-'

 VisibleString

 VisibleString

 VisibleString
`xy'

 Duration

 -

 -

 Time

 -

 -

 Integer

 INTEGER

 INTEGER
0 4 -66

 Natural

 INTEGER

 INTEGER
0 55

 Null

 -

 NULL
Null

 Object_Identifier

 -

 -

 Octet

 OCTETSTRING

 OCTET STRING
(SIZE (1))
`FE'O

 Octet_String

 OCTETSTRING

 OCTET STRING
`F0E2'O

 PId

 -

 -

 Real

 -

 -

User Defined Sorts

SDL Type
TTCN Type
ASN.1 Type
Transfer Syntax Example
Syntypes
SimpleTypes
SubType
same as referenced type
Enumeration Sorts

 -

 ENUMERATED
the enumerated values

 Struct

 struct

 SEQUENCE
(. 1, true .)

     Bit Fields

 -

 -
(. 2, 3, 0 .)

     Optional

 -

 -

 Choice

 -

 CHOICE
C1 : 1

Predefined Generators

SDL Type
TTCN Type
ASN.1 Type
Transfer Syntax Example

 Array

 -

 SEQUENCE OF
(: 1, 4, 7 :)

 String

 -

 SEQUENCE OF
(: 1, 4, 7 :)

 Powerset

 -

 SET OF
[ 1, 6, 8 ]

 Bag

 -

 SET OF
[ 1, 6, 6 ]


30 Customizing the TTCN Suite (on UNIX)

This chapter describes how to customize the TTCN suite on UNIX. You can, for example, find information about how resources are read and how to customize key and button bindings.

The chapter does not contain information about how to configure the help environment. You can read about that in "Customizing the On-Line Help" .

Note: UNIX version

It is only possible to customize the TTCN suite on UNIX with the facilities described in this chapter.


Customizing the TTCN Suite

The TTCN suite is an Xt based application (X11R5). Customizing is done by setting resources in the normal way for Xt applications. The default configuration is given in the file
$telelogic/X11/app-defaults/Itex 1. This file should be installed as part of the installation of the TTCN suite.

Most of the resources in the global resource file for the TTCN suite should never be overridden.

The resources that are most likely to be changed, will be mentioned in this chapter. For examples on how to set the resources see the file Itex.sample in the installation directory $telelogic/itex.

Note: UNIX only

Customizing the TTCN suite is only possible on UNIX.

1

$telelogic denotes the installation directory on your system.


How Resources Are Read

At start-up, resources are read from a number of files in the standard way for Xt applications. There are a number of environment variables that control the way the program looks for resource files:

  • XFILESEARCHPATH
  • XUSERFILESEARCHPATH
  • XAPPLRESDIR
  • XENVIRONMENT

When the TTCN suite is started, none of the environment variables above need to be set. The TTCN suite will automatically find the resource file under the default name $telelogic/itex/X11lib/app-defaults/Itex.

To override some of the resources in the global resource file there are several possibilities:

  • Give command line arguments to the TTCN suite (see the man page itex).
  • Set the environment variable XENVIRONMENT to a file containing resources for the TTCN suite, or create a file $HOME/.Xdefaults-<host>.
  • Set the value of the RESOURCE_MANAGER property with the program xrdb, or create a file $HOME/.Xdefaults.

The easiest way to set some personal resources is to create a file
.Xdefaults in the home directory and add these resources to it.

For a more detailed description of how resources are found in an Xt based application see some suitable book on the subject, for example the X Toolkit Intrinsics Programming Manual from O'Reilly & Associates.


Customizing Key and Button Bindings

Key bindings are accomplished by translations in the resource file of the TTCN suite. The translation tables that are relevant to add/change in are:

Itex*XmText.translations

Affect all places where text is edited in the TTCN suite, for example rename of node in Browser and editing of field in the Table Editor. It is here the Emacs-like editing keys are defined.

Itex*textWindow*XmText.translations

Affect only key bindings in log windows. This is, by default, defined to contain the same key bindings as above but with the addition of a few bindings that have to do with scrolling.

Itex.browser*node.translations

Most of the keys in the Browser are defined here.

Itex.nodeTranslations

Some keys for traversing the Browser tree are defined here.

Itex.editor.headerFields.overrideTranslations

Defines the bindings available when focus is on a header field in the Table Editor.

Itex.editor.rowFields.overrideTranslations

Defines the bindings available when focus is on a body field in the Table Editor.

Itex.editor.fieldEditor.overrideTranslations

Defines editor specific bindings when editing a field in the Table Editor.

In the resource file there are comments that describe the action functions that can be used in translation tables. Changes to these tables must be done with caution, since much of the functionality of the TTCN suite depends on these translations being set in a reasonable way.


Other Customizations

The following is a list of miscellaneous customizations. For examples, see the file Itex.sample in the installation directory $telelogic/itex.

Change of Paper Size

By default, the printout will be in A4 format. Other formats supported are Letter, Tabloid and Legal. For all formats it is possible to choose between portrait and landscape mode. The default is portrait mode.
See the file Itex.sample for an example.

Change of the Header/Footer in Printouts

By default, the header consists of the string "ITEX 3.6", the document name and the string "user name @ host name". It is possible to change the header and the footer.
See the file Itex.sample for an example.

Change of Font Size in Editor

By default, the font size used in fields in the Table Editor is 10 screen points. The same size is used in printouts. It is possible to change the size of the Table Editor on the screen, without changing the paper size.
See the file Itex.sample for an example.

Change of Font Family

By default, all text is from the Helvetica family. You can change this to another family supported by both X11 and Postscript (for example Times).
See the file Itex.sample for an example.

Changing Relative Widths of Columns in Editor

The total width of a table is divided among all columns. You can control this by specifying how wide different columns should be. It can be specified individually for each table type.
See the file Itex.sample for an example.

Hiding and Showing the Browser Toolbar

If you set the resource entry Itex*browser.enableToolBar to False, it is possible to hide the tool bar in the Browser window.

Configuring the Help Environment

The Help environment is configured via the Preference Manager, see "Customizing the On-Line Help" .


31 Editing TTCN Documents (in Windows)

In the TTCN suite, TTCN test components can be edited on table level as well as restructured on a hierarchical level. This chapter describes the editors and information managers in the TTCN suite in Windows and how to use them.

For an overview of the TTCN suite, see Introduction to the TTCN Suite (in Windows).

Note: Windows version

This chapter is Windows only. The corresponding UNIX chapters are 25 The TTCN Browser (on UNIX) and 26 The TTCN Table Editor (on UNIX).


Introduction to the TTCN Suite

The TTCN suite can be used for development, specification and compilation of test system components in the TTCN language. The functionality included will be described below.

The TTCN suite supports all of the standardized, non-compact tables that are defined in ISO/IEC 9646-3. The compact test case dynamic behaviour table (ISO/IEC 9646-3, clause C.3) and concurrent TTCN tables are also supported. The compact tables for constraints (also in Annex C of ISO/IEC 9646-3) are not supported.

The general user interface concepts and common menu choices in Telelogic Tau are described in 1 User Interface and Basic Operations.

Different Views of the TTCN Document

The contents of a TTCN test suite can be viewed in the Browser, the Finder and the Table Editor:

  • The Browser presents an overview of the TTCN tables. In the Browser it is possible to edit the TTCN table structure, to determine which parts of the test system component to view and to apply a number of operations on it. See "Using the Browser" .
  • The Table Editor presents TTCN tables for editing, referencing, and a number of table-specific operations. See "Editing Tables" .
  • The Finder presents a non-hierarchical view of the TTCN tables. Subsets of the total set of tables can be extracted, sorted according to various rules, and a number of operations can be performed on the resulting set of tables. See "Finding and Sorting Tables" .

The Log Manager gives another view of the test suite. It presents log outputs from the currently loaded test system components. Information from various operations, such as analysis and simulation, will appear in the test component log in the Log Manager. See "Viewing Log Information" .

Functionality to Apply on the TTCN Document

Building Test Components and Tables

  • The Data Dictionary is used in conjunction with the Table Editor, and offers an easy way to build TTCN behavior statements from the declared test system components. For more information, see "Creating Behaviour Lines" .
  • SDL to TTCN Link is similar in use and appearance to the Data Dictionary. It utilizes a Link executable for an SDL system to interactively build the behavior of a TTCN test for that particular system. For more information, see 36 TTCN Test Suite Generation.
  • Autolink supports semi-automatic generation of TTCN test suites based on SDL specifications. For more information, see 36 TTCN Test Suite Generation. The menu choice Autolink Merge in the File menu may be used for merging Autolink generated MP files into an opened test suite.

Analyzing, Verifying and Executing a Test

  • The Analyzer verifies syntactic correctness of test components. For more information, see 32 Analyzing TTCN Documents (in Windows).
  • The TTCN to C compiler generates C code from TTCN. For more information, see 33 The TTCN to C Compiler (in Windows).
    The Generic Compiler Interpreter interface is an interface for the adaption of the generated code to a specific target environment. For more information, see 37 Adaptation of Generated Code.
  • The Simulator allows execution and interactive debugging of test systems. For more information, see 34 The TTCN-SDL Co-Simulator (in Windows).

Starting the TTCN Suite

You can start the TTCN suite from the Organizer in the following ways:

  • Select Tools > Editors > TTCN Browser in the Organizer. This will also add an untitled TTCN document in the Organizer.
  • Double-click on a TTCN document icon already included and connected in the Organizer (or select Edit from the Edit menu).
  • Add a new TTCN document to the Organizer and make sure that the option Show in editor is checked in the Add New dialog.
  • Add an existing TTCN document to the Organizer.

Figure 218 :The TTCN suite is started and the Browser displays a modular test suite


Using the Browser

When you open a TTCN document it will be displayed in the Browser. As the structure of TTCN is tree oriented, the Browser presents an overview of the test system component in tree form.

Multiple Browser views can be opened on a document and all editing performed in a Browser will be simultaneously reflected in the other opened Browser windows.

In addition to this, you may create sub Browsers. This means that you restrict the view to only display a few nodes. In combination with the possibility to have multiple Browsers open on the same test document, this enables you to keep just the interesting bits of information in a couple of small Browser windows.

By using the edit operations, such as Add In and Delete, you can manipulate the Browser structure to build a complete TTCN system component. You can control the amount of information actually displayed in a Browser, by collapsing and expanding sub trees.

Opening the Browser and a TTCN Document

You open the Browser and a TTCN document by selecting New or Open from the File menu. From the File menu, you can also select the four most recently used files.

Hint:

If you try to open very large test suites, for example containing extensive constraint declarations, you may get an error message about "scanner buffer overflow". You can solve this by setting the environment variable ITEX_SCANNER_BUFFER_SIZE to a high value, for example 75 000 000.

To open additional Browsers for the same component:

  • Make sure the Browser is active and select File > New Window.

The Browser is also opened automatically when the TTCN suite is started from the Organizer, as described in "Starting the TTCN Suite" .

The Browser User Interface

The initial structure of a TTCN tree contains place holders for the static parts of the system component. These static nodes are automatically created by the TTCN suite whenever you create a new test system component. What you usually do when you build a test system component is to add dynamic child nodes to the static nodes, and fill them with test specification data. Examples of static nodes are the Declarations Part and the Constraints Part. Examples of dynamic nodes include tables, groups or objects in a table (e.g. test case variables).

The Browser displays all the static nodes in the order defined in the TTCN standard. This ordering cannot be changed. For example, it is not possible to have the Constraints Part coming before the Declarations Part. Only the dynamic items - the tables - may be added and deleted.

Static nodes are the only nodes that can become the root of a sub Browser.

Static Nodes in the Browser

Static nodes can take on four different appearances depending on the parse status of dynamic nodes below. Whenever you analyze a sub-tree, or parts of it, or edit it in a way such that the parse status of one or more dynamic nodes is altered, an abnormal parse status is indicated by the appearance of the static parent nodes.

This is an ordinary static node. All children to this node have been analyzed with status OK.

This is a static node where at least one of the dynamic nodes in the sub tree below has not yet been analyzed or is in need of analysis. There are no erroneous dynamic nodes.

This is a static node where at least one of the dynamic nodes in the sub tree below has been analyzed with an error or warning as result. In the actual view, the arrow is red for errors and purple for warnings.

To find a table that has to be corrected, you follow the marked nodes through the tree. Note that erroneous nodes have precedence over non-parsed ones, so even a single erroneous child to a static node will make it red no matter how many non-analyzed nodes there are in the sub-tree.

It may be that some of the static nodes will remain unused. A TTCN test system component is allowed to leave out the use of for example Test Case Variables. However, although this empty node will be displayed in the Browser, it will not be printed or output in the TTCN-MP format.

Dynamic Nodes in the Browser

A dynamic node is always associated with a table and can be accessed by the Table Editor. Two kinds of dynamic nodes can have children, namely multiple tables and group tables. Multiple tables look just like ordinary table icons, with the added feature of possible children, whereas group tables (referred to as group nodes in the Browser) have a different look to distinguish them somewhat from the others.

This is a group node with all dynamic nodes in its sub tree analyzed with status OK.

This is a group node with a sub-tree containing at least one non-analyzed dynamic node, but no erroneous ones.

This is a group node with a sub-tree containing at least one dynamic node analyzed with an erroneous status or a warning. In the actual view, the color is red for errors and purple for warnings.

This is a dynamic node (or multi-table) that is analyzed with status OK.

This is a dynamic node that needs to be analyzed.

This is a dynamic node that has been analyzed and contains one error. In the actual view, the cross is red for errors and purple for warnings.

Figure 219 : Different node types in a Browser

Controlling the Nodes in the Browser

As the Browser displays the information in a TTCN document in a tree oriented way, it is very simple to control the amount of information that the you want to see at a specific moment.

Expanding and Collapsing a Node

Nodes with sub-trees are possible to expand and collapse to show or hide the branch below it. This works in the same way that you expand and collapse directory levels in the Windows Explorer by double-clicking.1

  • The shortcut for collapse is <Left arrow> when an expanded node is selected.
  • The shortcut for expand is <Right arrow> when a collapsed node is selected.

Selecting Nodes

Click a node to select it. <Ctrl>-click a node to extend the current selection.

Instead of using the mouse for navigation, you can use the following shortcuts:

  • To move the selection to the next node, use <Down Arrow>.
  • To move the selection to the previous node, use <Up Arrow>.

Renaming Dynamic Nodes

To rename a dynamic node:

  • Click the name of a selected node, then type the new name and press <Enter>.
    • You can also change the name in the table itself.

Creating a Sub Browser

To create a sub Browser:
  • Select Make Sub Browser from the View menu. This replaces the contents of the active Browser with the selected node and its sub tree.

To get a Browser with the full TTCN document tree, select New Window from the Window menu.

Editing the Browser Structure

The static structure is automatically generated when a TTCN document is first created and cannot be edited. To build an individual TTCN system component, you need to add named tables - such as PDUs, constraints and behavior tables - and named objects to the multi-object tables - such as test case variables, PCOs and timers.

Use the Edit menu choices for adding, deleting, copying, pasting, etc, editable nodes - also called dynamic nodes - (that is, groups, tables or objects in a multiple object table) in the Browser.

Generating the Test Suite Overview

The test suite overview is a collection of tables that contain test suite structure, test case index and default index. These are used for reference in a printed copy of the system component, as described in the TTCN standard. The overview will be generated the first time you print the test suite, export it or open the overview tables. The generation may take a little while, but it is only needed once for each session, as the tables are automatically updated when you edit the test suite.

Adding Nodes

To add a new dynamic node as the last child of the selected node:
  • Select Add In from the Edit menu.
    • The shortcut is <Ctrl+Shift+A>.

In the case of multiple-object tables, select the node that represents the multiple-table. When you select Add In, a new node will be added as the last child node.

To add a new dynamic node before the selected node:

  • Select Add from the Edit menu. As with Add In, the new table will be unnamed.
    • The shortcut is <Ctrl+A>.

Adding Groups

It is possible to add a new test case group, a new test step group or a new default group in the Dynamic Part.

To add a new group as the last child to the selected node:
  • Select Add Group In from the Edit menu.

To add a new group before the selected node:

  • Select Add Group from the Edit menu.

To add a table to a group, select the group and Add In.

Adding Compact Tables

It is possible to specify that all the test cases in a given group are displayed in the compact format (see Annex C, clause C.3 of ISO/IEC 9646-3). The following commands allow the insertion of compact groups in the test suite hierarchy:

To add a compact group before the selected node:

  • Select Add Compact Group from the Edit menu.

To add a compact group as the last child of the selected node:

  • Select Add Compact Group In from the Edit menu.

Cutting, Copying and Pasting Nodes

You may cut or copy dynamic nodes. Dynamic nodes may also be pasted according to compatible classes, for example:

  • Test suite parameters, test suite constants, test suite variables and test case variables may be pasted into each other.
  • TTCN ASP, PDU, structured type and CM definitions may be pasted into each other and into TTCN ASP, PDU, structured type and CM constraints (and vice versa).
  • ASN.1 ASP, PDU, structured type and CM definitions may be pasted into each other and into ASN.1 ASP, PDU, structured type and CM constraints (and vice versa).
  • Test case, test step and default behaviors may be pasted into each other.

However, it is not possible to paste a constraint, for example, as a test case behaviour.

Paste is not available if the clipboard contains an object of an incompatible type to the selected object.

To cut the selected node and its sub tree:
  • Select Edit > Cut.
    • The shortcut is <Ctrl+X>.

To copy the selected node and its sub tree:
  • Select Edit > Copy.
    • The shortcut is <Ctrl+C>.

To paste a node before the selected node:
  • Select Edit > Paste.

To paste a node as the last child to the selected node:
  • Select Edit > Paste In.
    • The shortcut is <Ctrl+V>.

Creating Constraints

The most convenient way of creating a constraint is to copy the corresponding type and paste it as a constraint. Do this by copying the chosen type (ASP, PDU, CM or structured type), and then pasting it among the corresponding constraints. This works for both tabular constraints and for ASN.1 constraints.

The pasted table will have all its local names filled in. All that remains is to give the constraint a name and fill in the values.

Deleting Nodes

Dynamic nodes may be removed from the test document.

To delete the selected node and its sub tree:
  • Select Delete from the Edit menu.

Undoing/Redoing Operations

All editing commands can be undone, and undone actions can be redone.

  • To revert the last edit step, select Undo from the Edit menu.
    • The shortcut is <Ctrl+Z>.

  • To revert the last Undo, select Redo from the Edit menu.
    • The shortcut is <Ctrl+Y>.

Opening a Table

To open a table, either:

  • Double-click a table node in the Browser.
  • Select a table node and then press <Enter>
  • Select a table node and then Open Table Editor from the View menu.

It is possible to open several tables at the same time, but if it is more than ten, you will be asked to confirm it.

Printing a TTCN Document

To print a TTCN document:
  • Select Print from the File menu.
    • The shortcut is <Ctrl+P>.

For more information, see "The Print Dialogs in the TTCN Suite" .

1

Note that test group nodes differ. Double-clicking a group node that is expanded always opens its associated table instead of collapsing it. Click on the minus sign to the left of the group icon instead.


Editing Tables

The Table Editor is used for editing various TTCN tables. It displays the tables in three different parts: the header, the body and the footer. Each part, as well as many fields, can be resized.

You can edit tables by using the mouse and/or the keyboard. Rows in a table can easily be added, copied (both within a table and between other tables) and removed. The Table Editor shows the analysis status of the table contents, by use of colored text, and provides for immediate visual feedback during test simulation.

Figure 220 : A Table Editor for a test case

Resizing Cells and Table Parts

The three parts of a table - header, body and footer - are separated by horizontal bars, which you can drag to change the relative size and to hide parts of the table from view.

You can change the individual height of rows by dragging the leftmost row separator. In the body part, you may also change the individual width of columns by dragging the separators of the header fields.

Note that changing the column width may have effect on the row height, as the row will change to display all information it contains.

Renaming a Table

To change the name of a table, you can either rename its node in the Browser or edit the table name in the table itself.

Setting the Input Focus

To set the input focus in another part of a table, either:

  • Click in a cell in that part.
  • Use <left arrow> and <right arrow> to move between the last field of one part and the first field of another part.

To set the input focus within a part, either point and click or use the arrow keys. There are also some shortcuts:

To Move to: | Use This Key Combination
Next field in same row | <Tab>
Previous field in same row | <Shift+Tab>
Last field in same column | <Ctrl+Down arrow>
First field in same column | <Ctrl+Up arrow>
First field | <Ctrl+Home>
Last field | <Ctrl+End>

Editing Text in a Table

When you have used the keyboard to move the input focus to a field, the contents of the field will be replaced with the new text when you start typing. To edit the existing text, you have to press <Home> or <End> first.

If you use the mouse to explicitly set the input focus in a field, you can start editing the existing text directly with the keyboard.

The table fields will expand automatically to accommodate the text. You can also add a line break in the text by using <Return>.

To cut, copy and paste text in the fields, you use the corresponding commands in the popup menu, the Edit menu or the standard Windows shortcuts. However, note that it is only possible to paste text into a table field when the field contains a text pointer.

Note:

The paste buffer for text is not the same as the one used for entire rows in the body of a table.

Editing Rows in the Body of a Table

You can add, delete, cut and copy rows in the body of all TTCN tables that contain more than one column. This is not possible in the headers and footers, since the formats of these parts of a table are defined by the TTCN standard.

The ASN.1 tables only have a single column with a single row and therefore adding, deleting, cutting and copying rows is not applicable. However, the contents of ASN.1 tables can still be copied, pasted, etc, as text.

Selecting and Deselecting Rows

  • Select rows in the body of a table by clicking in the leftmost cell of a row (the "row button"). This deselects other selected rows.
  • Select range of rows in the body by first selecting one row and then <Shift>-clicking another.
  • Toggle the selection of a row by <Ctrl>-clicking the leftmost cell of the row.

Note:

Setting the input focus will also deselect all selected rows.

Cutting, Copying and Pasting Rows

Rows in the body of a table may be cut, copied and pasted. Copy and Paste work across all the different tables although the Paste command is mainly intended for use among tables of the same or similar types.

To cut selected row or rows from the table:
  • Select Edit > Cut.
    • The shortcut is <Ctrl+X>.

To copy selected row or rows:
  • Select Edit > Copy.
    • The shortcut is <Ctrl+C>.

To paste a row or rows:
  • Select Edit > Paste.
    • The shortcut is <Ctrl+V>.

To paste a row or rows before the current row:

  • Select Paste In from the Edit menu.

It is possible to paste a row when a body row or field is selected.

Note:

The paste buffer for entire rows in the body of a table, is not the same as the one used for text.

Deleting rows

To delete the selected row or rows, select Delete from the Edit menu.

Inserting Rows

To insert a new row before a selected row:
  • Select Insert New Row Before from the Edit menu.
    Only one row may be selected. If no row is selected, the new row will be created first in the table.
    • The shortcut is <Ctrl+Ins>.

To insert a new row after a selected row:
  • Select Insert New Row After from the Edit menu.
    Only one row may be selected. If no row is selected, the new row will be created last in the table.
    • The shortcut is <Ins>.

To insert a new tree header row before a selected row:

  • Select Insert Local Tree Before from the Edit menu.
    Only one row may be selected. This command only works in dynamic behaviour tables. If no row is selected, the new row will be created first in the table.

To insert a new tree header row after a selected row:

  • Select Insert Local Tree After from the Edit menu.
    Only one row may be selected. This command only works in dynamic behaviour tables. If no row is selected, the new row will be created last in the table.

You may also use <Ins> to insert rows. Where the row will be inserted depends on the input focus:

  • If input focus is in the header or footer of a table, a new row is added after the last row in the body of the table.
  • If input focus is set on a field in the body of the table, a new row is added after the field that has the input focus. The input focus will be transferred to the corresponding field in the new row.
  • <Ctrl+Ins> gives the same effect as above but the new row is inserted before the row/field.

Indenting Behaviour Lines

The indention of behaviour lines can be increased and decreased:

To increase the indentation of a row in focus, or selected rows, by one position:
  • Select Increase Indention Level from the Edit menu.

To decrease the indentation of row in focus, or the selected rows, by one position:
  • Select Decrease Indention Level from the Edit menu.

Browsing in the Table Editor

If you right-click a table field containing an identifier, you may open the table representing the identifier from the pop-up menu:

  • To save the current table in the history and display the definition of the selected identifier in the current Table Editor:
    • Select Open <Identifier> from the pop-up menu.
  • To display a pop-up menu containing the header rows of the identified table:
    • <Control>-right-click the identifier.
  • If the identifier is associated with a one-line table, the whole table is displayed in the pop-up. To select the identifier in the popup will have the same effect as Open <Identifier> (described above).
  • To open the table associated with the identifier in a new Table Editor window:
    • Select Open <Identifier> in New Window from the popup menu.
      The new window gets a new (empty) history buffer and is completely independent of the table from which it was opened.

The Table Editor maintains a history of tables displayed with Open <Identifier> described above. This is similar to going back and forward in a web browser:

To go forward in the history of the Table Editor:
  • Select Go Forward from the popup menu or the View menu.

To go back in the history of the Table Editor:
  • Select Go Back from the popup menu or the View menu.


Creating Behaviour Lines

The Data Dictionary gives you an alternative way of writing behaviour lines, by providing easy access to lists of PCOs, types, constraints, timers, etc, that you have already defined

Before you can use the Data Dictionary, the TTCN document has to be analyzed, because PCOs, types and constraints with major reference problems or missing type references will not be presented in the lists in the dialog.

Opening the Data Dictionary

To open the Data Dictionary:

  1. Select a body row in a behaviour table.
    • If you have not inserted a behaviour line yet, the input focus should be somewhere in the header of the table.
  2. Select Data Dictionary from the View menu.

It is only possible to have one Data Dictionary dialog opened.

The Data Dictionary dialog contains:

  • Three different tabs: Send/Receive, Timer and Attachment, from which you can select different statements to generate.
  • Three fields: Behaviour Line, Constraint and Verdict, whose contents will be inserted as a TTCN line in the table. It is also possible to edit the fields manually.
  • Three buttons: Apply, Clear and Close (the first two only enabled when a body row of a behaviour table is selected):
    • Click the Apply button to add a new row - containing the contents of the Behaviour Line, Constraint and Verdict fields - to the table.
    • Click the Clear button to reset the dialog and deselect all selections in the current tab.

Generating a Send or Receive Statement

Generate a send or receive statement by selecting a PCO, a type and a constraint. You can also add a timer, assignment and qualifier.

Figure 221 : The Send/Receive tab in the Data Dictionary dialog

To add a send or receive statement:

  1. Select the Send/Receive tab.
  2. Select a PCO.
    The Type and Constraints list will be updated and only show the entries that are valid for the currently selected PCO.
  3. Select the ! radio button for a send statement or the ? radio button for a receive statement.
  4. Select an ASP or a PDU in the Types list.
    The PCO and Constraints lists will be updated accordingly.
  5. Select a constraint.
    The Type and Constraints list will be updated.
    • If the constraint is a parametric constraint, a choice for each parameter will be displayed in the Constraints Parameter area, which you can select.
  6. Optionally you can add a timer statement by selecting the Start or Cancel radio button.
    To insert a start statement, you also have to select a timer.
    It is not possible to select timeout or to specify a timeout value here. You have to do that in the Timer tab of the dialog.
  7. Optionally, add assignments separated by commas and without parenthesis.
  8. Optionally, add qualifier statements, without brackets.
  9. Optionally, add a verdict.
  10. Click Apply
    A new row - containing the contents of the Behaviour Line, Constraint and Verdict fields in the dialog - will be added after the currently selected row and the new row will be selected.

Adding a Timer Statement

In the Timer tab, you may generate a StartTimer, CancelTimer or a Timeout statement. As described above, you can also add timer statements from the Send/Receive tab. The difference is that from this tab you can also add Timeout value to the timer and you can add a timeout statement.

Figure 222 : The Timer tab in the Data Dictionary dialog

To add a timer statement:

  1. Select the Timer tab in the dialog.
  2. Select a timer.
  3. Select the Start, Cancel or Timeout radio button.
  4. If you selected Start or Timeout, you also have to specify a timer duration in the Timeout field.
  5. Click Apply.
    A new row - containing the contents of the Behaviour Line, Constraint and Verdict fields in the dialog - will be added after the currently selected row and the new row will be selected.

Adding an Attachment Statement

Generate an Attachment statement by selecting a test step and specifying an actual parameter list (if the test step has a formal parameter list).

Figure 223 : The Attachment tab in the Data Dictionary dialog

To add an attachment statement:

  1. Select the Attachment tab.
  2. Select an attachment.
  3. If the selected test step has a formal parameter list, specify the parameter values in the Attachment Parameters area.


Viewing Log Information

The Log Manager is a collection of log outputs, where each test system component can report information. The Log Manager contains one log per test component, and one common pane that is used for general information.

Examples of actions that can result in log information:

  • Analysis of one or more tables: The resulting errors (if any).
  • Opening an MP file: Result of the operation.
  • Simulation: Simulator traces are reported on both the component log, and the general log.

The Log Manager can be configured to behave in various ways. The default setting is for the Log Manager to be hidden, but appear whenever log output is present. Only one instance of the Log Manager is available.

The contents of each log can be saved as a text file.

You can open tables by clicking and then <Ctrl>-right-clicking the name of the table in the log.

Figure 224 : The Log Manager window

Automatic Appearance

The Log Manager can be made to automatically become visible whenever new information is available in a log. This can be handy to reduce the amount of windows open at a given time as the Log Manager can be closed when it is not needed.

To allow the Log Manager to automatically open whenever new information is available:

  • Select Auto-Raise Log from the Log menu.

Changing the Appearance of the Log

The log font can be made smaller or larger, allowing more information to be viewed or increased readability.

To make the log text larger:

  • Select Increase Log Font Size in the Log menu.
    • The shortcut is <Ctrl+Alt+L>

To make the log text smaller:

  • Select Decrease Log Font Size in the Log menu.
    • The shortcut is <Ctrl+Shift+L>

Exporting Information from the Log

The information contained in a log can be copied to the clipboard, or saved to disk as an ordinary text file. In addition to normal text-selection, all text can also be selected with one operation.

To select all text:

  • Select Select All In Log in the Log menu.

To copy the selection to the clipboard:

  • Select Copy Log in the Log menu.

To save all text in a log to a file:

  • Select Save Log in the Log menu.

Clearing the Log

To clear the displayed log:

  • Select Clear Log in the Log menu


Finding and Sorting Tables

As an alternative to the Browser, you can use the Finder for displaying TTCN tables in a list, without the ordering restrictions imposed by the TTCN tree structure.

You can search for and display tables in the Finder. The search may for example be based on name, type and content. You can either use the entire TTCN document (the Browser contents) or the Finder list as search source, and extend or restrict the number of tables displayed in any number of steps.

Another way of searching is relationally. This means that you search for tables that reference or are referenced by tables selected in the Finder. The relational search cannot be combined with the ordinary.

The tables that will be displayed after a search, can be sorted by a number of criteria:

  • Name
  • Type
  • Path in the test tree
  • Parse status
  • Latest analyze time stamp
  • Latest modification time

Reversed sorting is also possible.

In addition, it is possible to for example open, analyze, rename and delete tables from the Finder, but not cut, copy, paste and insert since that require a tree context.

Opening the Finder

To open the Finder:
  • Select Open Finder from the View menu.
    • The shortcut is <Ctrl+F>

Figure 225 : The Finder

The Finder consists of three areas:

  • The Find/Relational Find area, where you specify criteria for the tables to be found and inserted in the Results List.
  • The Search In area, where you can select to search for tables in the entire document or only in the Results List.
  • The Results List, where the sorted list of TTCN tables are kept.

About Search Criteria

Search criteria are used for restricting a search. This means that if you do not specify any search criteria - all fields are empty and no buttons are clicked - before you click the Find button, all dynamic TTCN tables of the test system component will be displayed.

Consequently, if you specify one or more search criteria, TTCN tables that match at least one of the criteria, will be displayed in the Finder. Additionally, this means that specifying all possible search criteria has the same effect as specifying none. This is merely as a convenience for quickly adding all tables of the test system component, as the closed search criteria is not meaningful.

Note:

The search criteria are used for an OR-style search.

Finding Tables

Figure 226 : The Find tab in the Finder

To search for tables:

  1. Select the Find tab.
  2. Select Document in the Search in area to search for tables in the entire TTCN document.
    • If you select Results List, the search criteria will be used to restrict the set of TTCN tables already present in the Results List.
  3. Select one or several table types in the Of type list.
    This list contains all existing TTCN and ASN.1 table types supported.
  4. Click a Search mode radio button.
    This selection affects the text you type in the Name and Contains fields. If you are not going to use those fields in the search, the search mode does not affect the search at all.
    • Wildcard
      The Name and Contains fields can contain wildcards. This means that "a*body" will match "anybody" and "antibody", while "a??body" only will match "anybody".
    • Regular expression
      The Name and Contains fields contain regular expression, with its more advanced syntax and matching possibilities. This means that "any[bt]" will match "anybody" and "anything" but not "anyone".
    • Literal
      The Name and Contains fields contain the exact text. This means that "any?" only will match "any?".
  5. Optionally, type some text in the Name field.
    The tables with names that match will be found.
  6. Optionally, type some text in the Contains field.
    The tables with contents that match will be found.
  7. Optionally, click one or several Status buttons to sort out tables of a different parse status.
    For example, if you select the error button, only tables with erroneous parse status will be found.
  8. Click Find.
    Tables that match at least one of the search criteria you have specified will be displayed in the Results List.

Finding Tables Relationally

Figure 227 : The Relational Find tab in the Finder

You can search for tables that are referenced by and that reference tables that are displayed and selected in the Results list. To do this:

  1. Select the Relational Find tab.
  2. Select one or several tables in the Results List.
  3. Select one of the following radio buttons:
    • All nodes directly referenced by the selected node(s)
      Replaces the contents of the Results List with all nodes that are directly referenced by the tables currently selected in the list.
    • All nodes directly and indirectly referenced by the selected node(s)
      Same as above, but expands the search to include tables that are referenced by the referenced tables, and so forth.
    • All nodes that reference the selected node(s)
      Replaces the contents of the Results List with all nodes that reference the tables selected in the list.
  4. Click Find.
    The Results List will be updated in accordance with your settings.

Editing and Sorting the Results List

The Results List contains a subset of all dynamic TTCN tables in the TTCN document. You can perform most standard operation on the tables. However, it is not possible to cut, copy, paste or insert tables, since this requires the structural context of the Browser.

Caution!

Even if the elements of the Results List are presented without structural ordering, they still follow the TTCN hierarchy. This means that if you delete a group node, the group and its entire sub tree will be removed.

Sorting the Results List

The contents of the Results List can be sorted if you click on the header of the information column. The available information is:

  • Name
    The name of the table.
  • Type
    The TTCN or ASN.1 type of the table.
  • Path
    The path of the tree leading to this table on the form root/..../parent/node.
  • Analyze status
    The parse status of the table.
  • Analyze time
    The last time the table was analyzed.
  • Modify time
    The last time the table was modified.

Click a second time on the header to sort the list in reverse order.

Clearing the Results List

Click Clear to clear the contents of the Results List.


Converting to TTCN-MP

TTCN-GR - the graphical notation - is the format used when you edit or print a test suite in the TTCN suite. TTCN-MP - the textual notation (machine processable) - can be used when you want to import a TTCN document into a non-TTCN suite tool or make backups.

To convert a TTCN document to TTCN-MP, either:

  • Select Save As from the File menu.
    This opens a dialog where you can save the current document as TTCN-MP.
  • Click the Export to MP button.
    This opens a dialog where you can export the current document to TTCN-MP. The MP file will be written to disk, but not opened.

Both TTCN-MP and TTCN-GR can be opened in TTCN Suite.

For a full supported EBNF, see "The TTCN-MP Syntax Productions in BNF" .

The Standard MP Format

When you convert to MP, the TTCN document does not have to be analyzed or correct. TTCN-MP will be generated even for documents that are neither complete nor error-free. This implies that the generated MP file may be, but is not necessarily, conformant to the standardized TTCN-MP format

However, to ensure that the TTCN-MP document can be read by a non-TTCN suite tool, you should analyze the document and correct any errors.

The Telelogic MP Format

An optional but non-standard TTCN-MP for compact tables and ASN.1 references is supported. Additional fields in dynamic tables (fields which are transferred to test suite overview tables) are also supported. You are recommended to use this format for transferring TTCN document between the TTCN suite instances and for making backups of the TTCN documents. Otherwise it works just as the standard MP format.

MP File Format Problem when Opening

When you open certain TTCN-MP documents, a problem with transferring the information (e.g. description) in the overview tables to the tables in Dynamic Part, may occur.

The TTCN standard allow path specifications to optionally include the document name first. This has the unfortunate effect that if the TTCN document contains a top level group with the same name as the TTCN document, there is, in general, no way of knowing if the first part of the paths is a group identifier or the TTCN document identifier.

TTCN Suite assumes that if the first part of the path is equal to the document name, it is the optional document name and, when converting, strips it away. When the document is saved as or exported to MP, the document name is always added to the front of all paths. That way, TTCN Suite is always able to open the MP files it exports.

If the TTCN document contains top level group identifiers equal to the document name, and TTCN Suite is unable to resolve the paths, temporarily change the document name in the MP file and change it back once inside TTCN Suite.

Note that ITEX 2.0 did not add the document name at export, and therefore the problem described may apply when open MP files exported by ITEX 2.0.

Fields Containing the `$' Character

The contents of table fields in a TTCN-MP file are usually ignored. However, to make it possible to open non-bounded free text fields (for example TS_VarValue field) with embedded dollar characters (`$'), those fields will be syntax checked. This means that it is not possible to convert TTCN documents containing unmatched single or double quotes in non-bounded freetext fields, that is, when you open a TTCN-MP file, syntax errors in those fields will not be tolerated.

Revision Control

There is no integrated revision control system in the TTCN suite. Since normal visible files are used to store the TTCN documents, it is easy to integrate the TTCN suite in a revision control system. However, since the.itex file format is binary, it is better to use the TTCN-MP format.


Converting to HTML

It is possible to export a TTCN document, or only a part of it, to HTML. The result will be one HTML-file containing what you selected to export, and - when applicable - hypertext links as well as information about the structure of the test suite will also be generated.

To convert a TTCN document to HTML:

  1. Select the top node in the Browser.
    • You may also select only a part of the test suite, but multiple-selection is not possible.
  2. Select Save As from the File menu.
    A dialog will be opened where you can save the document as HTML.

It is also possible to convert a currently opened table to HTML. To do this:

  • Select Generate HTML from the pop-up menu in the Table Editor.


Shortcuts

Common Shortcuts

Shortcut | Action
Ctrl+N | Creates a new test suite.
Ctrl+O | Opens an existing test suite.
Ctrl+S | Saves the test suite to file.
Ctrl+P | Prints the test suite.
Ctrl+Z | Undoes latest editing action(s).
Ctrl+Y | Redoes latest undone editing action(s).
Ctrl+L | Shows/Hides Log Manager.
Ctrl+F | Opens a new Finder.
F7 | Analyzes the selected node and its sub-tree.
F8 | Generates code for the current test suite.
Alt+F8 | Displays an options dialog to allow the user to set options for tools working on the Browser.
F5 | Runs/continues current simulation.
Pause | Pauses current simulation.
Ctrl+Break | Aborts current simulation.
F11 | Steps current simulation.

Browser Shortcuts

Shortcut | Action
<Up arrow> | Sets the focus to the above node in the Browser.
<Down arrow> | Sets the focus to the below node in the Browser.
<Right arrow> | If the selected node is collapsed and has children, it will be expanded. If the selected node is expanded and has children the selection will move to the first child.
<Left arrow> | If the selected node is the root of an expanded sub-tree, the sub-tree will be collapsed. If the selected node is the root of a collapsed sub-tree the selection will move to the parent of the current node (if any).
<Ctrl+X> | Cuts the selected non-static node in the Browser.
<Ctrl+C> | Copies the selected non-static node in the Browser.
<Ctrl+V> | Pastes the contents of the cut/copy buffer after the selected node.
<Ctrl+Shift+V> | Pastes the contents of the cut/copy buffer as a child to the selected node.
<Delete> | Deletes selected node(s).
<Enter> | Opens a Table Editor for each selected node.
<Ctrl+A> | Adds a new table after the selected node.
<Ctrl+Shift+A> | Adds a new table as a child to the selected node.
Click | Sets selection on a node in the Browser.
Right-click | If the mouse pointer is above a node, sets selection on that node and display node specific pop-up menu. If no node is selected, displays background pop-up menu.
Double-click | If the selected node is a static node, the sub-tree will either be collapsed or expanded. If the selected node is a collapsed group, its sub-tree will be expanded. Otherwise the associated group table is opened. Finally, if the node is a non-static table a Table Editor for that node will be opened.
<Shift>-click | Selects/deselects all nodes between this selected node and the previously selected nodes.
<Ctrl>-click | Selects/deselects a node without affecting already selected nodes.

Table Editor Shortcuts

Shortcut | Action
<Tab> | Moves to the next editable field.
<Shift+Tab> | Moves to the previous editable field.
<Ctrl+Up arrow> | Moves to the previous line.
<Ctrl+Left arrow> | Moves to the next editable field.
<Ctrl+Down arrow> | Moves to the next line.
<Ctrl+Right arrow> | Moves to the previous editable field.
<Ctrl+Space> | Toggles selection of current row in a table body.
<Alt+Left arrow> | Moves forward in history.
<Alt+Right arrow> | Move back in history.
<Page Up>/<Page Down> | Scroll stable one page.
<F7> | Analyzes the current table.
<Ctrl+X> | Cuts selected rows.
<Ctrl+V> | Pastes rows after the selected row, or last if no selection exist.
<Ctrl+C> | Copies selected rows.
<F9> | Toggles breakpoint on selected row(s)
Right-click | Context sensitive popup.
<Ctrl>-right-click | Displays the definition of the currently selected identifier.
Click | Sets text selection and clear row selection.
<Ctrl>-click | Toggles row selection.

Log Manager Shortcuts

Shortcut | Action
<Ctrl+Alt+L> | Increases font size.
<Ctrl+Shift+L> | Decreases font size.

Finder Shortcuts

Shortcut | Action
<Up arrow> | Sets the focus to the above node in the Results List.
<Down arrow> | Sets the focus to the below node in the Results List.
<Ctrl+C> | Copies the selected non-static node in the Results List.
<Delete> | Deletes selected node(s).
<Enter> | Opens a Table Editor for each selected node.
Click | Sets selection on a node in the Results List.
Right-click | If the mouse pointer is above a node, sets selection on that node and display node specific pop-up menu. If no node is selected, displays background pop-up menu.
Double-click | Opens a Table Editor for the selected node.
<Shift>-click | Selects/deselects all nodes between this selected node and the previously selected nodes.
<Ctrl>-click | Selects/deselects a node without affecting already selected nodes.


32 Analyzing TTCN Documents (in Windows)

This chapter contains a reference manual to the Analyzer in the TTCN suite. You can also find information about how to find erroneous tables displayed in the Analyzer log.

The TTCN Browser and TTCN Table Editor are described in 31 Editing TTCN Documents (in Windows).

See Introduction to the TTCN Suite (in Windows) for an overview of the TTCN suite tool-set.

Note: Windows version

This is the Windows version of the chapter. The UNIX version is 27 Analyzing TTCN Documents (on UNIX).


Analyzing TTCN Documents

The Analyzer in the TTCN suite does a complete syntax check on both TTCN and ASN.1 (as it is used in TTCN). The Analyzer also performs a number of static semantic checks, mainly the uniqueness and existence of identifiers.

For implementation reasons, the Analyzer does not exactly follow the TTCN standard - some syntax restrictions and relaxations apply. These differences will not affect the vast majority of users, but for reference they are documented together with the standard syntax in 39 Languages Supported in the TTCN Suite. This chapter also includes the static semantics supported by the TTCN suite.

During analysis, the TTCN suite compiles an extensive symbol table containing all named objects in the TTCN document and the references between them.

Using the Analyzer

In the TTCN suite, the Analyzer works on the currently active TTCN document. It is also possible to analyze a TTCN document from the Organizer, see "Analyze TTCN" .

  • To analyze a subtree of a TTCN document in the TTCN suite, select a node in the view and then select Analyze from the Build menu. The selected node and all nodes in its subtree will be analyzed. If the root node is selected, the entire suite will be analyzed.
    • The shortcut is <F7>.

  • To analyze the entire test suite, regardless of any selections in the test suite, select Analyze Suite from the Build menu.
    • The shortcut is <Ctrl+F7>.

  • To analyze an entire modular TTCN system - containing the currently active suite or module - starting from the root suite, select Analyze System from the Build menu. This is equivalent to analyzing the root node in the Organizer.
    Note that it may take a while before this operation is completed, depending on the size and complexity of the system.

If an item is analyzed incorrectly, this will be recorded as an error message in the log. Items that have been found to be incorrect will be marked in red in all views of the document.

The Analyzer Dialog

When you analyze a document for the first time, the Analyzer dialog will be opened and you may change the options. Once this has been done, the same options will be used and the dialog will not be opened the next time you start the analysis from a quick-button or a keyboard shortcut. However, the dialog will always be opened when you select an analyzer menu choice. You can also open the dialog by the menu choice Build > Options or by the shortcut <Alt+F8>.

Note that every active TTCN document has its own analysis settings, so in practice, two or more TTCN documents can be edited and/or viewed at the same time in the TTCN suite, and yet have individual settings. But multiple views of the same TTCN document do of course share the same settings.

Figure 228 : Analyzer dialog

The Analyzer reports all analysis results to the Log Manager. For each different test suite, a new tab will be created to allow the user to easily access the analysis information for different TTCN documents.

Note:

The output of the analysis will not be available if the Log Manager is closed and the option Auto-Raise Log is unchecked.

Forced Analysis

Indicates that all selected items are going to be analyzed and no item will be skipped. An item is normally skipped if it is OK.

Retrieve ASN.1 Definitions

Indicates that the definitions of encountered ASN.1 references should be retrieved. An ASN.1 definition is retrieved if this option is set or if the definition has not been fetched before.

Enable Restriction Control

Enables a set of extra controls done on the TTCN code to find even more semantic errors in the analyzed item.

Warnings

Gives more information.

Stop After n Errors

Stops the analysis when the number of errors is reached.

Error Messages

Errors detected during analysis are recorded in the log. For the fields in the header of a table, the error messages have the general format:

==================================
Table name and table type
Field type 1
Error message
Field type 2
Error message
:
:
Field type n
Error message
==================================

Example 202

An error found in the default name (identifier) field of the default dynamic behaviour called UT_DEFAULT:

=============================================
Analysis messages in table: UT_DEFAULT of type: Default Dynamic Behaviour
Default Name:
The referenced identifier UPPER_PCO is not declared.
UT_DEFAULT (p : UPPER_PCO)
----------------^
=============================================

In the body of a table (where the field type name does not uniquely define a field) the row number is also included:

  • Row number
  • Body type
  • Error message

Example 203

Errors found in a test step table header (the default field) and in the body (rows 1 and 2 of the behaviour description):

=============================================
Analysis messages in table: ESTABLISH_CONNECTION of type: Test Step Dynamic Behaviour
Default:
Mismatched number of parameters: is 1, should be 0.
Row: (#1)
Behaviour Description:
The referenced identifier CR is of wrong type.
UPPER_PCO ! CR
------------^
Row: (#2)
Behaviour Description:
The referenced identifier CC is of wrong type.
UPPER_PCO ? CC
------------^
=============================================

Resolving Forward References

During analysis, the TTCN suite does two main tasks:

  • It checks the syntax of the abstract TTCN document.
  • It checks some of the static semantics of the TTCN document.

The syntax of TTCN is defined in ISO/IEC 9646-3 Annex A as a list of BNF productions or rules. See also "The TTCN-MP Syntax Productions in BNF" . The TTCN suite checks all these rules except for a very few minor deviations; for more information, see "The Restrictions in the TTCN Suite" . If a rule is not followed in the TTCN document then this will be reported as an error by the Analyzer.

The static semantic rules of TTCN are also defined in Annex A of ISO/IEC 9646. These are in the form of text statements which limit the use of some of the syntax rules, usually in a specific context. "TTCN Static Semantics" and "ASN.1 Static Semantics" describe the static semantics which are controlled by the Analyzer. The static semantics currently supported are mainly of the following types:

  • Identifiers (names) are checked for uniqueness with respect to the scoping rules defined in ISO/IEC 9646-3
  • The existence of referenced TTCN objects (e.g. a test step) from another TTCN object (e.g. test case) is verified
  • Type control and type restriction control

In order to achieve this, the Analyzer constructs a symbol table of all the named TTCN objects that it finds during analysis, e.g. variable names, type identifiers, tables, etc.

It is important to note that TTCN allows forward references. For example a test step may attach another test step that is declared later on in the TTCN document, that is, the referenced (i.e. attached) test step, appears after the test step that has done the attach.

The Analyzer has a feature called back-pass designed to resolve forward references. The back-pass is automatically invoked at certain points in the analysis process.

Forward references usually appear in the context of ASP/PDU definitions, constraints and as the result of attachment statements in behaviour trees. The reason for this is that the Analyzer does not traverse the selected items in exactly the listed order. The Analyzer order deviates from the listed order in three places:

  • Items in the PDU type definitions sub-tree are analyzed before items in the ASP type definitions sub-tree.
  • Items in the PDU constraint declarations sub-tree are analyzed before items in the ASP constraint declarations sub-tree.
  • Items in the defaults library sub-tree are analyzed before items in the test step library sub-tree and those are analyzed before items in the test cases sub-tree.

ASN.1 External Type/Value References

References to ASN.1 definitions in external ASN.1 modules can occur in the following four TTCN tables:

  • Test suite constant declarations by reference
  • ASN.1 type definitions by reference
  • ASN.1 ASP type definitions by reference
  • ASN.1 PDU type definitions by reference

In these tables there are three important fields to consider:

  • Module Identifier (set by user)
    The name of the ASN.1 module. This should be the real name of the model, i.e. the name stated inside the module itself.
  • Type Reference/Value Reference (set by user)
    This is the name of the desired type (or value).
  • Type Definition/Value (set automatically when fetched)
    This is the field where the fetched type definition/value is copied into.

The term definition is used below both to denote an ASN.1 type definition and an ASN.1 value.

When an ASN.1 reference is analyzed, the referred definition must be available to the Analyzer. In the pro formas for this kind of reference in the TTCN suite, there is an external column where both the definition and the parse tree is stored.

If the Analyzer encounters any reference to a type/value, the definition is fetched, given the type/value name and the module identifier, and copied into the external field before the field is analyzed. The operation of fetching the definition of the reference is controlled by an option in the Analyzer dialog. Important to note is that the fields Module Identifier and Type/Value Reference are not parsed. This means that if a change is made in either of these two fields, the row will not be analyzed and thus no fetching will be made. The solution to this is to set the Enable Forced Analysis in the Analyzer dialog when altering a reference. See "The Analyzer Dialog" .

Analyzing ASN.1 References

This is the general algorithm when encountering an ASN.1 in the analysis phase.

  1. First of all, an attempted fetch is only made if no current definition exists or the Analyzer fetching-option is selected.
  2. The actual fetching is made, see "Retrieving external ASN.1 Definitions" .
  3. If the definition is successfully fetched, the identifiers in the definition is converted to TTCN compatible syntax, see "Syntactic Conversion" .
  4. Finally a possible update of the definition is made and the analysis is continued.

Retrieving external ASN.1 Definitions

From the ASN.1 module a simple parse tree is built to access its contents. The parse tree is (re-)built when either it has not been built before or the ASN.1 module has been modified since last access. The parse tree for an ASN.1 module "lives" for the duration of the whole analysis phase.

Syntactic Conversion

The received definition must be manipulated in the following sense. All identifiers must be syntactically checked and altered if they include any characters that is disallowed in TTCN. The rule is that all `-' (dash) characters in an ASN.1 name are replaced by a `_' (underscore).

No special care has to be considered to ASN.1 comments since they are ignored when the parse tree is built from the module.

External type references in the type definition (e.g "... Module.Type...") will only be converted like above and left for the Analyzer to deal with (see also "Restrictions" ).

Restrictions

The following features are not supported in TTCN:

  • External type reference identifiers on the form ModuleIdentifier.Type/Valuereference are not supported.
  • Type/value references within the same ASN.1 module are not supported.

Furthermore, there are restrictions in the ASN Utilities when it is used to extract the external types and values. These restrictions are introduced in translating ASN.1 to SDL but since the same algorithm is used for extracting types and values, the restrictions are also relevant for the TTCN suite (see "Translation of ASN.1 to SDL" ).

Error Handling

Any error that occurs while finding, parsing or accessing the ASN.1 module will cause the old definition to remain. Only when a completely successful fetching has been made, the definition will be updated. Possible errors could be:

  • The ASN.1 module not found among the dependencies.
  • The ASN.1 module file could not be found or was not readable.
  • The ASN.1 module file was not syntactically correct.
  • The referred type/value could not be found in the module.

See 14 The ASN.1 Utilities for a more general view on ASN.1 usage.

TTCN Static Type Restriction Control

The TTCN standard defines a set of semantic rules for type definitions. In particular it defines simple types as types which might contain a true subset of the values which the parent type might contain. The Analyzer now analyzes the TTCN type system and also reports violations of these rules. This analysis is implemented as a post-pass over the related tables, and is only applied when the previous passes have been successful.

Furthermore, restriction control is performed on a number of other constructs in the TTCN language, thus facilitating the task of writing semantically correct TTCN documents. Most of the TTCN types and values are checked and thereby reducing the chance of programming errors slipping through to other tools which depends upon the correctness of the TTCN document.

Application of Static Type Restriction Control

Static type restriction control is applied to at least the following TTCN tables and fields:

  • Simple type definitions.
  • TTCN structured type / ASP / PDU / CM definitions.
  • Test suite constant declarations.
  • Test suite variable declarations.
  • TTCN structured type / ASP / PDU / CM constraint declarations.
  • Actual constraint reference parameter lists.
  • Actual parameter lists.

The static type restriction control also evaluates expressions in advance, where possible, and checks that the result does not violate the type restrictions of the field where the value is found. It operates on both types and values, regarding specific values as special cases of types.


Finding Tables from the Analyzer Log

When you are debugging a TTCN document, it may be useful to search for and display named tables. The search will include the entire current TTCN document - no selections are required.

To find an erroneous table identified in the Analyzer log:

  1. Place the cursor on the name of the table in the log and then <Ctrl>-right-click the name of the table.
  2. In the popup menu that will be opened, select the table name (at the top of the menu), and the table will be opened.

You can also use the Finder to find a table. See "Finding and Sorting Tables" .


33 The TTCN to C Compiler (in Windows)

This chapter describes what the TTCN to C compiler is used for, how to run it and the structure of the generated code.

When the TTCN to C compiler has translated TTCN into C code, the code must be adapted with the system that is to be tested. The adaption process is described in 37 Adaptation of Generated Code.

Note: ASN.1 support

The TTCN to C compiler supports only a limited subset of ASN.1. See "Support for External ASN.1 in the TTCN Suite for further details on the restrictions that apply.

Note: Windows version

This is the Windows version of the chapter. The UNIX version is 28 The TTCN to C Compiler (on UNIX).


Introduction to the TTCN to C Compiler

When developing new systems or implementations of any kind, the developing process is divided into well defined phases. Most commonly, the first phases involve some kind of specification and abstract design of the new system. After a while the implementation phase is entered and finally, when all parts are joined together, the test phase is activated.

In any case when a system is tested, we want to make sure that its behavior conforms to a set of well defined rules. TTCN was developed for the specification of test sequences. Unfortunately, as very few systems interpret or compile pure TTCN, we need to translate the TTCN notation into a language which can be compiled and executed. In the case of the TTCN suite, the TTCN to C compiler translates TTCN to ANSI-C.

Even after the TTCN code has been translated, there are a couple of things that need to be taken care of. In this case, we must adapt the generated code with the system it intends to test. This chapter describes how the TTCN to C compiler is used. The adaption process is described in "Adaptation of Generated Code" .


Getting Started

Unfortunately, a test sequence description expressed in TTCN cannot easily be executed as it is. This, because the test notation is not executable and only few test environments interpret pure TTCN. A different approach to create an executable test suite (ETS), is to translate the formal test description into a language which can be compiled into an executable format.

The TTCN to C compiler translates TTCN into ANSI-C which can be compiled by an ANSI-C compiler. Figure 229 depicts the first step in the process of creating an ETS using the TTCN to C compiler.

The generated code, called the TTCN runtime behavior, is only one of the two major modules of an ETS.

The second module which is needed includes test support functions which are dependent on the protocol used, the host machine, test equipment, etc. For this reason, it is up to the user to write this second module and in such way adapt the TTCN runtime behavior to the system he/she wants to test.

Figure 229 : Translating TTCN to ANSI-C

The adaption process is described in "Adaptation of Generated Code" . Figure 230 displays the anatomy of the final result.

Figure 230 : The anatomy of an ETS

Running the TTCN to C Compiler

To generate C code for the currently selected test document:
  • Select Generate Code from the Build menu.
    • The shortcut is <F8>.
      This will open a dialog where you may change settings for code generation (see Figure 231).
      You can also open this dialog by the menu choice Build > Options or by the shortcut <Alt+F8>.

Note:

Observe that the TTCN to C compiler is unable to function correctly if the test suite is not fully verified correct. This verification is accomplished by running the Analyzer tool on all the parts of the test suite.

Note that every active TTCN document has its own code generation settings, so in practice, two or more TTCN documents can be edited and/or viewed at the same time in the TTCN suite, and yet have individual settings. (Multiple views on the same TTCN document does of course share the same settings.)

Figure 231 : Options dialog for code generation

Options

  • If the Ignore bodies of test suite operations option is checked, the compiler will ignore to generate code for test suite operations. This is useful if you already have a file with your own test suite operations that only need to be linked to the rest of the code. If the option is not checked, the test suite operators will be generated and included in the file tsop_gen.c.

Encoders/Decoders

  • By selecting one of the alternatives None, Generate BER encoders/decoders or Generate PER encoders/decoders in the drop down list the compiler will either omit generation of encoders/decoders or generate extra code for BER or PER encoding and decoding support, see 37 Adaptation of Generated Code.

Kernel

  • To build a TTCN Exerciser, select the option Target/Stand-alone simulator. For more information about the TTCN Exerciser, see 35 The TTCN Exerciser.
  • Select Co-simulator if you want to execute a test suite together with a simulated SDL system.
  • To build a user-defined adaptor, select User-defined adaptor.

MSC Trace

  • Enable MSC/PR file tracing
    Generates MSC/PR format files that are saved in the current working directory. By default, the MSC file names will be on the form log_<TestCaseId>_<SequenceNo>.mpr, where <TestCaseId> is substituted by the test case name of the logged test case. <SequenceNo> is an integer that is started by 0000 and increased by one if there is already a version n in the working directory.
    The preprocessor constant MSC_FILE_MODE should be defined at compile-time of mscgen.c to get this mode. The constant GENMSC should be defined for compiling globalvar.c to activate appropriate calls.
    If the file cannot be created, a new attempt will be done at the start of the next test case. No file log will be created.
    The function MscSetPrefix can be used to change the path and prefix of generated files at runtime.
  • Enable MSC Editor tracing
    Creates a new diagram in the MSC Editor when a new test case is started and then appends and displays the events as they are executed. This mode assumes that an MSC Editor license is available and that Telelogic Tau is running at the host where the ETS is running and provides run-time MSC logging.
    The preprocessor constant MSC_MSCE_MODE should be defined at compile-time of genmsc.c to get this mode. The constant GENMSC should be defined for compiling globalvar.c for activation of the appropriate calls.
    If the creation of events in the MSC Editor fails, it will be retried at the next event, possibly creating an inconsistent MSC.
    This mode may also require access to the Telelogic Tau Public Interface libraries and include files that can be found in the installation of Telelogic Tau.

For more information, see "TTCN Test Logs in MSC Format" .

Output Directory

The final thing you have to do is to set the output directory.

OK

When you have set the options, click OK to start the generation of code. When the generation phase is started, information about the code generation will be displayed in the Log Manager. You will receive information about what parts that were generated and also some statistics about the amount of tables traversed during the generation phase.

If code is being generated for a large test suite, the status bar will show the progress.

Running the TTCN to C Compiler from the Command Line

You can start the TTCN to C compiler by executing ttcn2c with command line switches. The usage is ttcn2c [switches] filename.

Example 204

To generate C code for example.itex in the current directory, with hard values and in silent mode, use the command:

ttcn2c -ms example.itex

C Code Generator Parameters

Switch
Explanation

 -a <objs>
Link with objs as adaptor

 -A <ASN1files>
File containing filenames of ASN.1 module files.

 -b <dir>
Search in <dir> for static files

 -B
Generate BER encoding/decoding interface

 -d
Debug information in C code

 -D
Step through ETS execution

 -e <file>
Use file to be included in the make file

 -f
Forced mode - always overwrite files

 -g
Ignore bodies of test suite operations
See also "Options" .

 -h
Help

 -j <file>
User file name for types

 -k <file>
Use file name for constraints

 -l <file>
Specify log file

 -M file
Enable MSC/PR file tracing

 -M msce
Enable MSC Editor tracing

 -o <dir>
Specify output directory

 -p <file>
Use file name for behavior

 -P
Generate PER encoding/decoding interface

 -r <file>
Use file name to generate a makefile

 -R
Disable makefile generation

 -s
Silent mode - do not display messages

 -t
Generate simulator
See also "Kernel" .

 -T
Generate targe/stand-alone kernel

 -u bc
Generate code for Borland compiler

 -u vc
Generate code for Microsoft Visual compiler

 -v
Verbose

 -w
No warning mode

 -z <lines>
Aim at splitting generated file at <lines> number of lines

Generating C Code for Modular Test Suites

Generating C code for modular test suites from the command line, may be a bit tricky. Please see the example below for an explanation of how to proceed.

Example 205

You want to generate C code for the modular test suite mts.itex, which depends on module1.itex, module2.itex, module3.itex and module4.itex. To do this:

ttcn2c '"mts.itex""module1.itex""module2.itex""module3.itex""module4.itex"'

This will generate code for the entire modular test suite.

It is also possible to use MP documents in the same manner.

For a description of file naming, see "Files in the TTCN Suite.


What Is Generated?

Figure 229 shows how ANSI-C code is generated from a TTCN test suite. The generated code alone is not executable as it needs the test support functions module (see Figure 230).

In the case of the code generated from the compiler we also need a set of static functions which handle TTCN basics and other internal events. Even if these functions are vital for the successful compilation and execution of the generated code, the user should not have to worry about this part. These functions are gathered in a small set of static files which are compiled by the generated makefile and linked with the rest of the code.

The Code Files

The generated makefile is the file containing a definition of how the code should be compiled and linked. This will not be needed if you are compiling the generated code in a separate development environment.

The adaptor.h and adaptor.c files are the files that contain the adaptation code. If code is generated for the first time, these files will be generated by the compiler with empty function templates for the user to implement. On the other hand, if these files are present in the target directory the user does not have to worry about getting them overwritten.

The *_gen.{c,h} files contains the generated code from the TTCN test suite.

The asn1ende.h file contains the encode and decode functions for the ASN.1 Types. See ASN.1 Encoding and De-coding in the SDL Suite. (Only if ASN.1 support has been selected)

The Adaptation

We are now ready to deal in greater detail with the adaptation phase which is the final phase to create an executable test suite. The adaptation process is described in "Adaptation of Generated Code" .


TTCN Test Logs in MSC Format

The TTCN standard conformance log, though it is a relatively complete logging format, has a few drawbacks for some purposes:

  • The conformance log is very detailed.
  • The conformance log requires knowledge of TTCN and its semantics.
  • The conformance log is not always particularly easy to read.

In order to get a more high-level view, the log must either be filtered or another approach needs to be taken - in this case the MSC log format. The current version of the TTCN suite has support for an additional logging mode, to generate MSC/PR standard conformant logs - automatically saved in files and also directly to the MSC Editor.

For limitations in the MSC logging, see "MSC Logging.

MSC Logging Applications

There are several applications of MSC logging. Here are some:

  • Test reviews
    The MSC log format is very readable and can be used for reviewing test progress and for evaluating test results with requirements specifications.
  • Test result recreation
    If an SDL model has been used to specify the system behavior, a composed MSC log can be used to re-create the test result by using the SDL Validator's Verify-MSC feature. This will allow a particular test behavior to be handed to system designers who can recreate the result on a workstation level.
  • Test re-engineering
    If MSC traces are being used to generate test cases, the tests can be modified at the MSC level. A modified MSC can be used to generate a new tests. For instance - a test written in TTCN generates an MSC. At a review of the MSC logs a new scenario may be identified. The MSC can be changed to reflect the new scenario, and the MSC can be translated back to TTCN.

MSC Logging Modes

There are three major modes of logging, which can be toggled between the test cases. It is not possible to change the logging mode in a running test case since that would cause an inconsistency in the MSC file. The modes are:

  • None
    No MSC logs are generated at all. This mode improves performance somewhat compared to the other modes. For best performance, the MSC generation code can be entirely disabled. For more information see "Compiling an ETS with MSC Generation" .
  • Composed
    MSC generation of externally visible events of the ETS. This is suitable for test regeneration and for re-viewing test results. The performance is better than Decomposed mode. The generated MSC views the ETS as a set of PCOs that interact with a IUT. The ETS is not visible as one particular instance. Some relative timing information may be lost in this mode.
  • Decomposed
    MSC generation of externally visible and internal events of the ETS. This is the most detailed mode and it produces MSC events for almost all actions of the ETS. The purpose of the MSCs that are generated is to visualize the internal events and configuration of the ETS, and for test case debugging purposes.

MSC Instances Generated

Entity | Composed | Decomposed | Comment
SUT | Yes | No |
PCO | Yes | Yes |
MTC | No | Yes |
PTC | No | Yes | Dynamic

Events Logged

Event | Composed | Decomposed | Comment
Final Verdict | Yes | Yes | MSC Text
Preliminary Verdict | No | Yes | MSC Condition
Create | No | Yes |
Done | No | Yes |
Send to PCO | Yes | Yes |
Send to CP | No | Yes |
Receive from PCO | Yes | Yes |
Receive from CP | No | Yes |
Implicit send | No | Yes |
Start Timer | No | Yes |
Cancel Timer | No | Yes |
Timeout Timer | No | Yes |
Implicit Cancel | No | Yes | End of TC
Implicit Receive | No | Yes | End of TC
Message Values | Yes | Yes |

Compiling an ETS with MSC Generation

The ETS Generator can be compiled for a workstation or an embedded environment. Some modifications need to be done for applying it in the embedded environment if it lacks a file system. By default the tool will allow for any of these combinations at code generation time. For more information see "MSC Generation Modifications" .

Definitions that may be changed to customize the MSC generation:

Definitions | Explanation
MSC_DEFAULT_SYSTEM_NAME | Name of IUT instance in composed mode.
MSC_MAX_VALUE_LEN | Maximum length of an encoded message value.
MSC_NO_VALUE_LOGGING | If defined, no message values are displayed - this may make the ETS more efficient and the MSC logs more readable when using complex messages.

MSC Generation Modifications

Modifications to the MSC generation for running on an embedded environment include:

  • The MscAppendPREvent function can be modified to transfer the PR events via any type of uni-directional communications device. It is recommended to create another definition similar to the MSC_MSCE_MODE or MSC_FILE_MODE and complement the mscgen.c file with these.
  • Any place where MSC_FILE_MODE or MSC_MSCE_MODE is used should be having a new definition for the new logging mode.


34 The TTCN-SDL Co-Simulator (in Windows)

This chapter describes the TTCN-SDL Co-simulator in the Windows version of the TTCN suite. It gives an introduction to the concept of the TTCN-SDL Co-simulator, as well as a guide to its functionality.

Note: Windows version

This is the Windows version of the chapter. The UNIX version is 29 The TTCN-SDL Co-Simulator (on UNIX)


The TTCN-SDL Co-Simulator

The TTCN-SDL Co-simulator allows you to generate executable test suites (ETS) for testing of simulated SDL systems. This allows the testing of the system design early in the design process.

These ETSs allow you to execute test cases and/or test groups (hereafter referred to as tests) at full speed or by single stepping through the selected tests. There is also the possibility to set breakpoints in the tables of the tests.

It should be noted that there is no separate TTCN-SDL Co-simulator GUI. The TTCN-SDL Co-simulator will use the Table Editor to present the current line during execution.

More information about the SDL Simulator can be found in 49 The SDL Simulator.


Performing a Co-Simulation with the SDL Suite

Given a test suite containing a set of tests you want to execute together with a simulated SDL system, the following steps are to be performed:

  1. In the TTCN suite, analyze the test suite and make sure it contains no errors.
  2. In the TTCN suite TTCN to C Compiler Settings dialog, generate an executable test suite.
    The following TTCN to C Compiler Options should be set:
    • Co-simulator
    • Ignore bodies of test suite operations
      In the Build Options tab:
    • You should set Run Make.
    • You may have to change the Makefile Type.
      For more information about the TTCN to C compiler and the options, see 33 The TTCN to C Compiler (in Windows).

  3. Start the TTCN-SDL Co-simulator by selecting Invoke Co-Simulator from the Co-Simulate menu.
    In the file dialog that will be issued, select the simulator ETS - that is, the executable produced in step 2. After that, the TTCN-SDL Cosimulator toolbar will appear.

  4. Generate and start the SDL Simulator, if not already done. In the SDL Simulator UI, load the SDL suite generated simulator executable.
  5. In the SDL Simulator, give the command start-itex.
  6. In the TTCN Browser, select the tests you wish to execute.
  7. Click the Run/Continue or Step button, to start the actual co-simulation in the TTCN suite.
  8. In the SDL Simulator, give the command go-forever.


The TTCN-SDL Co-Simulator Operations

To abort the test in progress:
  • Select Co-Simulate > Abort.
    The SDL Simulator may have to be restarted after this step. A new co-simulation can be started now.

To temporarily pause the test simulation:
  • Select Co-Simulate > Pause.
    The co-simulation can be continued by doing a "run" or "step" operation.

To step one line of TTCN code:
  • Select Co-Simulate > Step.

To run/continue a test at full speed until it is finished or until a breakpoint is reached:
  • Select Co-Simulate > Run/Continue.

To toggle breakpoint status at currently selected lines in the Table Editor:
  • Select Co-Simulate > Toggle Breakpoint.


Information Messages

The TTCN-SDL Co-simulator can present messages to the user in three forms:

  • Informative messages
  • Warning messages
  • Error messages

Informative Messages

Informative messages are normally presented at the status bar. These might be for instance progress reports or other simple messages, which are only of a temporary interest (such as the tool tips).

Warning Messages

Warnings, also known as "non-critical errors", are events that indicate a problem during the preparation for a co-simulation, or during the actual co-simulation run. These are presented in standard warning dialogs.

Error Messages

Critical errors will halt the co-simulation. They are presented by an error dialog that appears in front of the application. The error dialog can often appear large and intimidating, but it simply gives a more verbose reason to why the error occurred, and what steps should be taken to avoid it.


Troubleshooting

The Simulators Stop Communicating

The SDL Simulator and the TTCN-SDL Co-simulator may stop communicating. This can occur if there are "old" instances of the TTCN-SDL Co-simulator ETS process still alive. They will then "steal" messages from the intended recipient. There are some ways to make the Simulators communicate again:

  • Exit the TTCN-SDL Co-simulator and start it again.
  • Exit the TTCN-SDL Co-simulator. Restart the SDL Simulator. Start the TTCN-SDL Co-simulator again.
  • Exit the Simulators and the Organizer. Check that no Postmaster process and no TTCN-SDL Co-simulator ETS process remains. If they do, kill them. Start the Organizer, the SDL Simulator and the TTCN-SDL Co-simulator.

Test Execution Stops

The execution of tests may stop at a certain point during execution for no reason. If the problem is reproducible, you should check the supported types. There is a possibility that a type has been used in a message between the simulators that is not supported.

The Simulators Get Out of Sync

The simulators may get out of sync. One way of doing this is when an execution in the TTCN-SDL Co-simulator has been aborted and the SDL Simulator has not been restarted.

  • Press the abort button in the TTCN-SDL Co-simulator. Restart the SDL Simulator.


Type Mappings in Co-Simulation

The data type mapping used by the co-simulation of the SDL simulator and the TTCN-SDL Co-simulator in Windows is the same as for the co-simulation on UNIX. See "Type Mappings in Co-Simulation" .


35 The TTCN Exerciser

A TTCN Exerciser is built from the TTCN to C compiler. For more information, see 28 The TTCN to C Compiler (on UNIX) and 33 The TTCN to C Compiler (in Windows).

For information about TTCN Exerciser limitations, see "TTCN Exerciser.


Introduction

Though the GCI interface is generic and may be used for executing tests in an almost arbitrary environment, there is often a significant effort required to get an adaptation up and running. This has prompted the development of a pre-built kernel which can be used to test executable test suites without requiring them to have complete adaptation layers for some platforms.

The TTCN Exerciser contains functionality for simulation of test suites without the requirement of having an SDL system or IUT to test. Furthermore it allows for one or several PCOs to communicate with a real IUT through a subset of the GCI interface. It is also prepared for adaptation with C++ and object oriented implementations under test by providing an "External C interface".


Functionality Overview

The TTCN Exerciser provides several features that may come in handy for test development, execution and also adaptor production. The main features of the TTCN Exerciser are as follows:

  • Simulated PCO communication
    Allows for a PCO not to be connected to an IUT. A message can be input in a PCO input queue at any time.
  • Discrete time simulation
    Test the tester with user-defined timing. An explicit "timeout" command is available to allow for the next pending timer to expire at will. This mechanism has a timer resolution down to individual nanoseconds.
  • Realtime simulation
    This mode uses real time as provided by the system clock of the host where the tester is executed. Practical limitations to the time resolution yields an accuracy of approximately 1 millisecond. The theoretical limit of the kernel is 1 nanosecond.
  • TTCN test case validation
    Runs "random walks" of test cases in order to detect paths where no verdict is assigned, or where some input causes a deadlock, as well as several other dynamic error conditions. This can be very useful for getting a degree confidence in the correctness and completeness of the test suites.
  • Custom PCO definition
    Provides the ability to define custom PCOs for connection to real IUTs while still having access to all the TTCN Exerciser features.
  • Source-level debugging of TTCN
    This includes setting breakpoints, highlighting lines in the TTCN Table Editor as it is running, and more.
  • Concurrent TTCN implementation
    The kernel internally implements concurrent TTCN, meaning that there is no extra effort in running concurrent test cases.
  • Dynamic MSC generation with the MSC generator
    For more information, see 33 The TTCN to C Compiler (in Windows) and 28 The TTCN to C Compiler (on UNIX).
  • Command scripting and logging
    Providing repeatability of simulated scenarios, as well as shortcuts for doing common operations.
  • Dynamic error detection
    The TTCN Exerciser helps detect a number of dynamic error conditions that a static syntax and semantics analyzer will not detect.


Kernel Operation Modes

In order to appreciate the way the TTCN Exerciser operates, it is important to get an insight in the different global modes it may be in. Each of these modes are outlined in this section. The full global kernel state and behavior is a combination of these modes, and to get the desired behavior, it is good to know how to toggle between the modes at will.

Execution Modes

These are the three major modes of operation of the TTCN Exerciser:

  • Simulation mode
    This mode has all PCOs simulated, and input is required from the test operator or user-defined scripts. In essence, there is no IUT and all messages that are sent are only indicated in the various test logs. All messages that are received must be specified by the test operator or a test execution script.
  • Target execution mode
    This mode has all the PCOs defined by an adaptor writer (implemented in an adaptation effort). This mode provides source-level debugging of TTCN test suites and an option of discrete time simulation.
  • Mixed mode
    This mode is available when some of the PCOs are connected to an actual implementation under test. It enables the features of both the simulation mode and the features of the target execution mode.

Timer Modes

These are the two timer modes:

  • Realtime
    This mode uses the system clock to provide timing information. This is the normal mode to run in for target testers. In the case a tester is paused or a breakpoint is reached, the timer mode will be toggled to discrete time simulation. You can resume it by setting the timer mode to realtime. See "Realtime" for more information. The realtime mode is recognized by all log messages being prefixed with an asterisk (*).
  • Discrete time simulation
    This mode only increments time when a timeout command is received. It is the default mode for simulations. In effect, the mode keeps track of running timers and their expiration time. This mode is automatically toggled to when the execution is stopped or paused, as well as for many of the kernel commands. See "Discrete" for more information. The discrete time simulation mode is recognized by all log messages being prefixed with a hyphen (-).

Control Modes

There are two control modes:

  • Simulator UI control
    This mode is for using the TTCN-SDL Co-simulator user interface protocol in communications with the operator. The mode appends a set of tags to all messages that are emitted. It is assumed that the tester is started by the TTCN-SDL Co-simulator user interface, but the mode is also useful if logs are to be processed by other tools.
  • Command line control
    This mode is for running in a command-line environment. An ETS built with the TTCN Exerciser can be run directly from a command-line, thereby providing means for automated, batch style testing.


PCOs

You can operate PCOs by either implicitly enqueueing messages in the PCO by using the receive command, or by customizing the PCO providing your own definition of the PCO behavior.

Customizing the Behavior of PCOs

The behavior of PCOs can be customized for achieving communications with "real" implementations under test. This is similar to the adaptation process. For more information, see 37 Adaptation of Generated Code. The difference is that only the GciSend function and a polling/decoding function need to be implemented. Some familiarity with the GCI interface is required in order to successfully add a custom PCO implementation to the TTCN Exerciser - in particular, the use of the GciValue type should be known. Also, knowledge of the protocol and APIs for the implementation of the PCO is required.

Files

The TTCN Exerciser is interfacing to the code generator output in a manner that is conformant to the GCI interface recommendation. The adaptor.c file which is supplied with the TTCN Exerciser interface, is pretty much a plain adaptor that calls GCI equivalent functions in the TTCN Exerciser. It is possible to edit the adaptor.c file while still retaining functionality of the TTCN Exerciser.

Custom PCO Registration

PCOs may be registered in the main function, before the IsmMain function is called. The PCO registration is done by calling the IsmRegisterPCOImplementation function. This functions arguments are described in detail in the ism.h file. Conceptually, each registered PCO is polled at a maximum interval supplied when the PCO is registered. The PCO has an associated polling function that should be used to check if a message is completely received on the PCO, and in that case decode it and use the GciReceive function to notify the TTCN runtime behavior of the newly arrived message. For sending, the PCO, registration function also requires a Send function argument. This function should send a message to the implementation under test.

It should be noted that these functions should all be possible to call from multiple threads, since the TTCN Exerciser may use multithreading to implement concurrent TTCN.


Timers

For both the realtime and the discrete time simulation, the implementation of the TTCN Exerciser has 64 bit timers. Time is kept as the difference from the timers expiration time and the last time the current time was updated. In realtime mode, the time is updated in the snapshot function. With discrete time simulation, the time is updated at the timeout command. With the 64 bit implementation and the constraint that the resolution is 1 ns, the consequences are that:

  • No period of less than 1 ns can be measured.
  • The maximum period that can be measured is more than 2 billion seconds, or some 65 years.

Hopefully, this resolution is sufficient for most applications. There are some aspects of discrete simulation that are well worth a special note:

  • Discrete time simulation assumes that no processing time is required for executing TTCN and that there is no delay due to messaging and scheduling overhead in concurrent TTCN. This is not entirely true. Apart from this, it is in many cases sufficient for testing a test script in a non-realtime environment.
  • Discrete time simulation also expires timers at the exact right time (from the testers aspect, not in a realtime aspect). In many cases, a test process cannot be scheduled at exactly the time when a timer expires, and consequently there is normally a lag in a real-time tester. This lag should normally be accounted for by the test designer in determining timer durations.

Runtime Timer Errors and Warnings

With the timer implementation, there are also some conditions that may be reported in the conformance log:

  • READTIMER of a timer that is not currently running. This condition will make the readtimer call return 0 and also produce a message in the conformance log.
  • START of a timer with a ps resolution will result in the timer to get an approximate expiration time. This expiration time is the duration of the timer / 1000 ns. In effect this is too early. If the unit of a timer cannot be determined, it is assumed to be seconds. This condition should normally not appear, but will result in a message in the log and possibly also test case termination.


Test Suite Parameters

The test suite parameters are read at startup of the TTCN Exerciser. There are two locations where they are searched for:

  • If the test suite parameters pics/pixit reference field contains the literal substring .ttp, the whole fields content will be treated as a file name, naming a file in which the parameter should be searched for. The file format is defined below.
  • In a file named pixit.ttp.

The file format is defined as:

File ::= {Line};
Line ::= Comment | ParameterNameAndValue;
Comment ::= <Non alpha Character> <Any text> | <empty line>;
ParameterNameAndValue ::= ParameterName ISMValueEncoding;

The ISMValueEncoding is defined in a separate section. An example would be:

#
# This is my parameter file, named pixit.ttp, located in the
# working directory of the ETS with the TTCN Exerciser.
#

TspFoo 3
TspUsePDU PDUA ( INTEGER 1, BOOLEAN TRUE )

# End of this example file.


Test Case Validation

The TTCN Exerciser has a rudimentary automatic test validation feature in that it supports running tests with random inputs and timeouts. This feature may be used to attempt to detect missing alternatives and some runtime error conditions without having to manually step through all these alternatives.

Detected conditions include:

  • Test incompleteness
  • Tests failing to terminate
  • Concurrent TTCN dynamic errors:
    • Failure to terminate a PTC
    • Creation of already started PTC
  • Tests with paths missing a verdict
  • A number of other conditions such as timer errors etc.

The random walk does not provide a guaranteed detection of these conditions, but it will run thousands of test tests in the time it normally takes to run one test.

The random walk has no feature for message generation, and hence requires messages to be imported or defined in the tool. All the messages are stored in a list of eligible messages. This list is referred to as the message list.

The random walk selects random messages from this list, and also timeouts if in a given state, any timers are running. This is repeated until a verdict is reached, an deadlock is detected, or until a defined maximum depth is reached.

Reports are stored in a report list and can be saved or reviewed.

Also, test statistics are stored while running the random walk. These test statistics can be used to determine how many tests were run in total, and which verdicts were reached.


TTCN Exerciser Commands

The TTCN Exerciser operates through a command line interface (which can be encapsulated by for instance the TTCN-SDL Co-simulator user interface).

Example 206 : General syntax of the command input

CommandInput::= {CommandLine} EOF
CommandLine::= Comment|Command
Comment::= <Non Alpha Character> <Free Text>
Command::= <Recognized command or '+'> <Parameters> <NewLine>

It is permitted to have any amount of spaces or tabs before the command start. In general, the assembler code modes of some editors works quite well for composing command files.

Example 207 : A command file

;;;
;;; File Name: example
;;; This is an example command file, uses ; for command delim.
;;;

;; Initialisation (see command descriptions below)
cl ; Set command line log mode
loglevel 2 ; Set log level to 2
nomsc ; Disable MSC generation
nopoll ; Disable command polling
discrete ; Use discrete time sim

;; Now run a test case
step TestCase1 ; Will create context
receive Lower ConnectInd { Address 3 }
run ; Will actually run till idle
timeout ; Do a timeout when idle

;;; End of this file...

These are the available commands when a tester built with the TTCN Exerciser is run from the command line or with a batch script. The commands may be abbreviated, as long as the abbreviation yields one unique command name. For instance, the command cancel may be abbreviated with ca but not with c, since that would also match the cmdlog command.

The command listing below has the following information:

  • Command name
    The formal name of the command, as defined in the ETS/SIMUI protocol document, available on request from Telelogic.
  • Aliases
    Alternative command names that may be handy if running from a command line interface. These are often common names for similar operations in debuggers. A hyphen indicates that the command has no aliases apart from any possible abbreviations. Aliases may also be abbreviated, for instance, the alias rts for the realtime command can be abbreviated rt.
  • Synopsis
    The command with "symbolic" parameters. If a parameter is surrounded by square brackets "[ ]", it is optional. If a parameter is surrounded by curly brackets "{ }", it indicates that a list may be accepted. If the parameter is surrounded by angle brackets "< >", it means that the name should be substituted by an identifier of an object of an appropriate type.
  • Description
    An informal textual description of the command and some of its possible side-effects.
  • Example
    An example of the command used in some context. The examples frequently use other commands than the described one in order to explain the use of the command.

General Commands

Help

  • Command name: help
  • Aliases: -
  • Synopsis: help
  • Description:
    List the available commands with a brief note on each commands purpose. The general format is:
    help [SR *] Display a brief help on commands
    The printed records are:
<command-name> [<states> <debug>] <description>

 <command-name>
The unique name of the command.

 <states>
The set of states where the command is applicable:
  • S - Stopped, no test case is running.
  • R - Running, as test case is in progress.
 <debug>
Denotes if the tester needs to be generated with the line information for the command to be running correctly:
  • D - Requires line-number information.
  • * - Available with or without line-number information.
 <description>
A brief summary of the command functionality.

The help command will automatically transition the tester to a Paused state if it is in running state.

Example 208

- Command?
help

Quit

  • Command name: quit
  • Aliases: -
  • Synopsis: quit
  • Description:
    Terminate the current test case and also terminate the tester program.

Example 209

- Command?
quit

Include

  • Command name: include
  • Aliases: -
  • Synopsis: include <filepath>
    +filepath
  • Description:
    Enqueue all the commands from the file named by file path. The file path can be relative to the current working directory of the tester, or it may be absolute. Also, the shortcut + may be used for simpler access to common scripts. It is recommended but not required that scripts have a file extension of .ics (ISM Command Script).
    It is sometimes desirable to use the command nopoll in conjunction with script reading, in particular when running test cases from scripts. The nopoll command gives a more synchronous behavior.

Example 210

- Command?
include setup.ics
- Command?
+setup.ics

Test Management Commands

List

  • Command name: list
  • Aliases: -
  • Synopsis: list
  • Description:
    List all available test cases. Test cases whose selection expression evaluates to false, get the tag [N/S] appended to their name to show that the case is not selected.

Example 211

Command?
list
MyTest1
MyTest2
MyTest3[N/S]

Glist

  • Command name: glist
  • Aliases: -
  • Synopsis: glist
  • Description:
    List all available test case groups.

Example 212

- Command?
glist
MyGroup1
MyGroup2

Run

  • Command name: run
  • Aliases: go, start
  • Synopsis: run {<TestCaseOrGroupNames>}
  • Description:
    Start the execution of the named test cases or groups. The test cases will run until a breakpoint is reached, the test case terminates, or until another command is entered.
    If a test is already in progress, this command will continue the test execution until one of the above conditions are met.

Example 213

- Command?
run MyTest1
-
- Line: MyTest1 1
- Line: MyTest1 2
- Line: MyTest1 3
- Line: MyTest1 4
- At breakpoint MyTest1 5
- Line: MyTest1 5
- Command?
run

Step

  • Command name: step
  • Aliases: line
  • Synopsis: step {<TestCaseOrGroupNames>}
  • Description:
    Start the execution of the named test cases or groups. The test cases will run until a breakpoint is reached, the test case terminates, or until another command is entered.
    As opposed to the run command, the test execution will also stop if a line is matched, or if a snapshot (idle) state is reached. This command requires that the tester has been built with line debug information for correct operation.
    If a test is already in progress, this command will continue the test execution until one of the above conditions are met.
    This command will toggle the timer mode to Discrete, since it is not possible to use real-time and line stepping in conjunction.

Example 214

- Command?
step MyTest1
-
- Line: MyTest1 1
- Command?
step
- Line: MyTest1 2
- Command?
step
- Line: MyTest1 3
- Command?

Stop

  • Command name: stop
  • Aliases: pause, break
  • Synopsis: stop
  • Description:
    Pause the execution. This will toggle the time mode to discrete and halt the test case without discarding any context information. This command requires line debug information to be included when the ETS is built to function correctly.

Example 215

- Command?
run MyTest1
- Line: MyTest1 1
- Line: MyTest1 2
stop
- Command?
step
- Line: MyTest1 3
- Command?

Cancel

  • Command name: cancel
  • Aliases: abort
  • Synopsis: cancel
  • Description:
    Cancel the current test run and reset the tester. This leaves the IUT in an undefined state. It is not recommended to use this command unless a test has lost contact with the IUT or is incomplete.

Example 216

- run test1

Loglevel

  • Command name: loglevel
  • Aliases: ll
  • Synopsis: loglevel [0-3]
  • Description:
    This command defines how much conformance logging should be performed. The levels are:

 0
Only verdicts

 1
Level 0 + PTCs, PCOs and TIMERS (default level)

 2
Level 1 + matched lines and test trees

 3
Level 2 + non-matched lines and defaults

If no level is supplied, the default level will be used.

Example 217

- Command?
loglevel 3
- Set conformance log level = 3
- Command?

Savestats

  • Command name: savestats
  • Aliases: ss
  • Synopsis: savestats [<file path>]
  • Description:
    Save a simple tabulated file with a list of what tests have been executed and what their verdicts were. This is useful for tracking test results over time, typically by loading the result file in some type of information management program. If the file path is omitted, the default file path results.txt will be used.

Example 218

- Command?
savestats testresults.txt
- Command?
# Just list the contents of the file
system cat testresults.txt
Test Verdict
MyTest1 PASS
MyTest2 FAIL
MyTest1 INCONCLUSIVE

Liststats

  • Command name: liststats
  • Aliases: ls
  • Synopsis: liststats
  • Description:
    List the test results of all test cases that have been run since the TTCN Exerciser was started, or since the last clearstats command.

Example 219

- Command?
liststats
- Listing test statistics:
- MyTest1 PASS
- MyTest2 FAIL
- MyTest1 INCONCLUSIVE
- Command?

Clearstats

  • Command name: clearstats
  • Aliases: cs
  • Synopsis: clearstats
  • Description:
    Clear the list of test results

Example 220

- Command?
clearstats
- Clearing test statistics.
- Command?

Test Debugging Commands

Most of these test debugging commands require the tester to be built with line debugging information for correct operation.

Breakpoints

  • Command Name: breakpoints
  • Aliases: bps
  • Synopsis: breakpoints
  • Description:
    List all currently set breakpoints.

Example 221

- Command?
breakpoints
MyTest1 5
- Command?

Breakpoint

  • Command name: breakpoint
  • Aliases: bp
  • Synopsis: breakpoint [table] [line]
  • Description:
    Set a breakpoint at line in table. If either is omitted, the last matched line or table will be used respectively.

Example 222

- Command?
breakpoints
- Command?
step MyTest1
- Line: MyTest1 1
- Command?
breakpoint
- Breakpoint set at MyTest1 1
- Command?
breakpoint 4
- Breakpoint set at MyTest1 4
- Command?
breakpoint MyTest2 2
- Breakpoint set at MyTest2 2
breakpoints
- MyTest1 1
- MyTest1 4
- MyTest2 2
- Command?

Delete

  • Command name: delete
  • Aliases: -
  • Synopsis: delete [table] [line]
  • Description:
    Delete the breakpoint at table and line. If either or both is omitted, the last matched line will be used.

Example 223

- Command?
breakpoint MyTest1 3
- Breakpoint set at MyTest1 3
- Command?
breakpoint MyTest1 5
- Breakpoint set at MyTest1 5
run
- Line: MyTest1 1
- Line: MyTest1 2
- Breakpoint reached: MyTest1 3
- Line: MyTest1 3
- Command?
delete
- Breakpoint deleted: MyTest1 3
- Command?
delete MyTest1 5
- Breakpoint deleted: MyTest1 5
- Command?
breakpoints
- Command?

Disable

  • Command name: disable
  • Aliases: -
  • Synopsis: disable
  • Description:
    Temporarily disable all breakpoints.

Example 224

- Command?
disable
- Breakpoints disabled
- Command?

Enable

  • Command name: enable
  • Aliases: -
  • Synopsis: enable
  • Description:
    Re-enable breakpoints after a disable command.

Example 225

- Command?
disable
- Breakpoints disabled
- Command?
enable
- Breakpoints enabled
- Command?

Timers

  • Command name: timers
  • Aliases: -
  • Synopsis: timers
  • Description:
    List all currently running timers. The output format contains the following information columns:

PTC | The PTC to which the timer belongs
Timer Name | The TTCN name of the timer
Id | The GCI timer identifier
Remaining (s) | The remaining time to timeout in seconds

Example 226

- Command?
timers
- PTC Timer Name Id Remaining (s)
- MTC Tms 210 0.400000000
- MTC TWatchDog 211 59.600000000
- PTC1 Tms 214 0.400000000
-
- Command?

Pcos

  • Command name: pcos
  • Aliases: -
  • Synopsis: pcos
  • Description:
    List all PCOs and the contents of their associated queues.

Example 227

- Command?
step MyTest1
- Line: MyTest1 1
- Command?
receive LowerPCO ConnectReq { 6 "Peer1" }
- Command?
receive LowerPCO ConnectReq { 7 "Peer2" }
- Command?
pcos
- PCO UpperPCO
- <empty input queue>
- PCO LowerPCO
- 1: ConnectReq { 6 "Peer1" }
- 2: ConnectReq { 7 "Peer2" }
-
- Command?

Ptcs

  • Command name: ptcs
  • Aliases: -
  • Synopsis: ptcs
  • Description:
    List all the currently active test components. The output columns include the following information:

Name | The name of the test component
Id | The GCI id of the test component
Thr | The host operating system thread id of the component
Table | The table name of the last matched TTCN line
Line | The last matched line number

Also, the currently active test component will be indicated with an arrow (->) in the output of this command.

Example 228

- Command?
ptcs
- Name Id Thr Table Line
- MTC 124 0 MyTest1 5
- -> PTC1 125 13 MyStep1 3
-
- Command?

Gett

  • Command name: gett
  • Aliases: print
  • Synopsis: gett [<ptc>] <variablename>
  • Description:
    Print the value of the named variable in the named test componentscontext. If the component name is omitted, the current component will be used.

Example 229

- Command?
gett MTC TsvFoo
- TsvFoo: 4711
- Command?
gett PTC1 TsvFoo
- TsvFoo: 1234
- Command?

Test Simulation Commands

Discrete

  • Command name: discrete
  • Aliases: dts
  • Synopsis: discrete
  • Description:
    Toggle to discrete time simulation mode. The command has no effect if already in discrete time simulation mode.
    The log prefix will be switched to '-'.

Example 230

* Line: Table1 3
* Line: Table1 4
* Line: Table1 5
discrete
* Discrete time simulation is now used.
- Command?

Realtime

  • Command name: realtime
  • Aliases: rts
  • Synopsis: realtime
  • Description:
    Toggle to realtime simulation mode. The command has no effect if already in realtime simulation mode.
    The log prefix will be switched to '*'. A running test will immediately resume execution.

Example 231

- Line: Table1 1
- Command?
step
- Line: Table1 2
realtime
- Realtime simulation is now used
* Line: Table1 3
* MTC SEND ASP1
* MTC START Tms(200)
* Line: Table1 4
* MTC TIMEOUT Tms
* Line: Table1 5
* FINAL VERDICT: PASS
* Command?

Timeout

  • Command name: timeout
  • Aliases: to
  • Synopsis: timeout
  • Description:
    Switch to discrete time simulation. Force the shortest pending timer to expire.

Example 232

- Command?
realtime
* Command?
run Test1
* Line: Test1 1
* MTC START TWatchDog(60)
timeout
- Discrete time simulation is now used
- Command?
run
- Line: Default1 1
- MTC TIMEOUT TWatchDog
- FINAL VERDICT: FAIL
- Command?

Receive

  • Command name: receive
  • Aliases: input
  • Synopsis: receive <PCOId> <ISMValueEncoding>
  • Description:
    Enqueue the message defined by ISMValueEncoding in the PCO input queue connected to the named PCO.
    For an alternative form, see "Messageinput" .

Example 233

- Command?
pcos
- PCO UpperPCO
- <empty input queue>
- PCO LowerPCO
- <empty input queue>
-
- Command?
receive UpperPCO AcceptCall { 1, TRUE, { 34, 13, 99, '5'B } }
- Command?
pcos
- PCO UpperPCO
- 1: AcceptCall { 1, TRUE, { 34, 13, 99, '5'B } }
- PCO LowerPCO
- <empty input queue>
- Command?

MSC Generation Commands

Nomsc

  • Command name: nomsc
  • Aliases: -
  • Synopsis: nomsc
  • Description:
    Disable MSC generation.
    The command is only available when the tester is stopped.

Example 234

- Command?
nomsc
- MSC generation disabled
- Command?

Decomposed

  • Command name: decomposed
  • Aliases: -
  • Synopsis: decomposed
  • Description:
    Enable MSC generation with decomposed MSCs. For more information, see 33 The TTCN to C Compiler (in Windows) and 28 The TTCN to C Compiler (on UNIX).
    The command is only available when the tester is stopped.

Example 235

- Command?
decomposed
- Decomposed MSC generation enabled
- Command?

Composed

  • Command name: composed
  • Aliases: -
  • Synopsis: composed
  • Description:
    Enable MSC generation with composed MSCs. For more information, see 33 The TTCN to C Compiler (in Windows) and 28 The TTCN to C Compiler (on UNIX).
    The command is only available when the tester is stopped.

Example 236

- Command?
composed
- Composed MSC generation enabled
- Command?

Mscsystem

  • Command name: mscsystem
  • Aliases: -
  • Synopsis: mscsystem [<system-name>]
  • Description:
    Define the name of the IUT instance in the composed MSC generation. This is for making it easier to generate MSCs which should later be reused in a system verification with an MSC verification tool such as the SDL Validator, as well as for test re-generation with a tool such as Autolink.
    If the system-name parameter is omitted, a default system name will be used (by default IUT).

Example 237

- Command?
mscsystem env_0
- IUT Name for composed MSC generation defined.
- Command?

Mscprefix

  • Command name: mscprefix
  • Aliases: -
  • Synopsis: mscprefix <path/prefix>
  • Description:
    Set a prefix for file names used when generating MSCs. This prefix is prepended to the file name and can be both a path or a file prefix.
    The default is log_.

Example 238

- Command?
mscprefix /tmp/traces/trace_
- Path/file prefix defined for MSC generation.
- Command?
#
# All test traces will be saved in the named directory
#

Test Validation Commands

Clearreports

  • Command name: clearreports
  • Aliases: cr
  • Synopsis: clearreports
  • Description:
    Clear the list of reports of dynamic errors encountered so far in test runs.

Example 239

- Command?
clearreports
- Reports cleared.
- Command?

Listreports

  • Command name: listreports
  • Aliases: lr
  • Synopsis: listreports
  • Description:
    List all the reports of dynamic errors encountered so far in test runs. The reports are in the following general format:
Report <index>: [<table>] <line>: <description>

The <table> field is optional. If it is not present, it implies that the report was not detected in the context of a running test component. If the <line> field is 0, there is a context available, but the context is not executing.
Also, if no line debug information is available, the table and line will be omitted and 0 respectively.

Example 240

- Command?
listreports
- Listing reports:
- Report 1: TestCase1 7: Missing ?DONE in MTC
- Report 2: TestCase2 3: Incomplete test case
- Command?

Savereports

  • Command name: savereports
  • Aliases: sr
  • Synopsis: savereports [<filename>]
  • Description:
    Save the reports to named file, or to the file reports.txt if no file name is supplied. The file format is the same as for the listreports command output.

Example 241

- Command?
listreports
- Listing reports:
- report 1: TestCase1 7: Missing ?DONE in MTC
- report 2: TestCase2 3: Incomplete test case
- Command?

Messagefile

  • Command name: messagefile
  • Aliases: mf
  • Synopsis: messagefile <filename>
  • Description:
    Append the message definitions in the messagefile to the list of input messages that can be used with the messageinput command, and also for selection of messages with the randomwalk command.
    The syntax of the file named by filename is:
MessageFile ::= MessageLine | CommentLine;
MessageLine ::= PcoId ISMValueEncoding NL;
CommentLine ::= NonAlphaChar Any NL;

Example message file:

# This is an example message file named file1.msg

PCO1 ASP1 { 1 2 FALSE '1234'O }
PCO2 ASP3 { 4 2 TRUE '3123'H }

# end of example file

Also note that messages can be added with the command messageadd. The messagefile is mainly intended for message lists generated by other means than with this tool.

Example 242

- Command?
messagefile file1.msg
- Adding message definitions:
- PCO1 ASP1 { 1 2 FALSE '1234'O }
- PCO2 ASP3 { 4 2 TRUE '3123'H }
- Command?

Messageadd

  • Command name: messageadd
  • Aliases: ma
  • Synopsis: messageadd <pconame> ISMValueEncoding
  • Description:
    Add the named message on the named PCO to the inputs that can be sent with the messageinput command and from which inputs are selected with the random walk.

Example 243

- Command?
messagelist
- Listing message definitions
- 1 : PCO1 ASP1 { 1 2 FALSE '1234'O }
- 2 : PCO2 ASP3 { 4 2 TRUE '3123'H }
- Command?
messageadd PCO1 ASP2 ( FALSE TRUE )
- Command?
messagelist
- Listing message definitions
- 1 : PCO1 ASP1 { 1 2 FALSE '1234'O }
- 2 : PCO2 ASP3 { 4 2 TRUE '3123'H }
- 3 : PCO1 ASP2 ( FALSE TRUE )
- Command?

Messagelist

  • Command name: messagelist
  • Aliases: ml
  • Synopsis: messagelist
  • Description:
    List all messages defined in the message list.

Example 244

messagelist
- Listing message definitions
- 1 : PCO1 ASP1 { 1 2 FALSE '1234'O }
- 2 : PCO2 ASP3 { 4 2 TRUE '3123'H }
- 3 : PCO1 ASP2 ( FALSE TRUE )
- Command?

Messageclear

  • Command name: messageclear
  • Aliases: mc
  • Synopsis: messageclear [<index>]
  • Description:
    Clear the message at index <index> in the message list. If no index is provided, all messages are cleared. The messagelist command prints indices for each message definition.
    Also note that the messageclear command may change the ordering and indices of messages at higher indices.

Example 245

- Command?
messagelist
- Listing message definitions
- 1 : PCO1 ASP1 { 1 2 FALSE '1234'O }
- 2 : PCO2 ASP3 { 4 2 TRUE '3123'H }
- 3 : PCO1 ASP2 ( FALSE TRUE )
- Command?
messageclear 1
- Cleared message definition.
- Command?
messagelist
- Listing message definitions
- 1 : PCO2 ASP3 { 4 2 TRUE '3123'H }
- 2 : PCO1 ASP2 ( FALSE TRUE )
- Command?
messageclear
- Clearing all message definitions
- Command?
messagelist
messagelist
- Listing message definitions
- Command?

Messageinput

  • Command name: messageinput
  • Aliases: mi
  • Synopsis: messageinput [<index>]
  • Description:
    Provide the message at index <index> in the message list as input to the Tester. This is a short form of the receive command, appropriate for frequently used messages, and it may also be used to test contents of message files.
    The message is decoded and added at the end of the named PCO queue.

Example 246

- Command?
messagelist
- Listing message definitions
- 1 : PCO2 ASP3 { 4 2 TRUE '3123'H }
- 2 : PCO1 ASP2 ( FALSE TRUE )
- Command?
messageinput 2
- Command?
step
- MTC RECEIVE PCO1 ? ASP2
- MTC STARTTIMER Timer1

Randomwalk

  • Command name: randomwalk
  • Aliases: rw
  • Synopsis: randomwalk [<repetitions>] {<testcaselist>}
  • Description:
    Will run the test cases of <testcaselist> <repetitions> times, providing random inputs and timeouts as they go. Reports are collected while running the test cases. Test logging is disabled, but can be re-enabled if a breakpoint is reached while doing the random walk.

Example 247

- Command?

# This is a command for running the test case MyTestCase 100
# times while providing random inputs from the message list
# and also timeouts.

randomwalk 100 MyTestCase

- Starting random walk...

[some logging of verdicts and selected path]

- Random walk completed
- Command?
listreports
- Listing reports:
- report 1: MyTestCase 4: READTIMER: Timer not running
- Command?

Maxdepth

  • Command name: maxdepth
  • Aliases: -
  • Synopsis: maxdepth <depth>
  • Description:
    Define how many messages and timeouts a test case may receive, until a test case run not producing a verdict should be abandoned. If the maxdepth is exceeded, a report will be produced.

Example 248

- Command?
maxdepth 10
- Defined max depth for random walk
- Command?

Kernel Management Commands

Cl

  • Command name: cl
  • Aliases: -
  • Synopsis: cl
  • Description:
    Turn off the TTCN-SDL Co-simulator user interface tagging. This makes the outputs of the tester more human-readable. By default, this tagging is enabled, so the first command you enter when running from the command line is typically a cl command.

Example 249

<VERDICT>
- FINAL VERDICT: PASS
</VERDICT>
<MESSAGE UI::READY>
- Command?
</MESSAGE UI::READY>
cl
- Output tagging disabled
- Command?
list
- TestCase1
- TestCase2
- Command?

Ui

  • Command name: ui
  • Aliases: -
  • Synopsis: ui
  • Description:
    Enable the TTCN-SDL Co-simulator user interface tagging. This makes the output less readable for a human, but easier to parse by computer programs (such as the TTCN-SDL Co-simulator user interface).

Example 250

cl
- Output tagging disabled
- Command?
list
- TestCase1
- TestCase2
- Command?
ui
<LOG>
- Using simulator ui output tagging
</LOG>
<MESSAGE UI::READY>
- Command?
</MESSAGE UI::READY>

Poll

  • Command name: poll
  • Aliases: -
  • Synopsis: poll
  • Description:
    Enable command polling and dispatch on each matched TTCN line. This slows down the execution somewhat, but makes it possible to interrupt a tester in other states than an idle state. The command requires that the tester was built with line debugging enabled.

Example 251

- Command?
poll
- Command?

Nopoll

  • Command name: nopoll
  • Aliases: -
  • Synopsis: nopoll
  • Description:
    Disable command polling in other states than stopped or snapshot (idle). This increases the execution speed, and also facilitates script writing by ensuring that a tester is in one of these two known states before it processes its next command.

Example 252

- Command?
nopoll
- Command?

Cmdlog

  • Command name: cmdlog
  • Aliases: -
  • Synopsis: cmdlog [<filepath>]
  • Description:
    Start or stop a command log. If the <filepath> argument is supplied, the named file will be opened for writing and all commands from the command line or included scripts will be written to the file. If no file name is supplied, the file will be closed and command logging disabled.

Example 253

- Command?
cmdlog asp1
- Command?
receive pco1 asp1 { '10'B FALSE '11'B }
- Command?
run
- Command?
cmdlog
- Command?
+asp1
- Command?
+asp1
- Command?
pcos
- PCO pco1
- 1: asp1 { '10'B FALSE '11'B }
- 2: asp1 { '10'B FALSE '11'B }
- 3: asp1 { '10'B FALSE '11'B }

Status

  • Command name: status
  • Aliases: -
  • Synopsis: status
  • Description:
    Display current TTCN Exerciser status and mode information overview.

Example 254

- Command?
status
- Tester status: STOPPED
- Time Mode: Discrete Time Simulation
- Logging level: 2
- Breakpoints: Disabled
- Command Log: Disabled
- Logging Mode: Command Line
-
- Command?

System

  • Command name: system
  • Aliases: -
  • Synopsis: system <commandline>
  • Description:
    Execute the <commandline> using the command line interpreter of the platform. Uses the C stdlib function system(<commandline>). Use this with care for reviewing, deleting and creating files.

Example 255

- Command?
system mkdir ./msctraces
- Command?
mscprefix ./msctraces/trace_
- Command?
composed
- Command?
run tc1 tc2 tc3 tc4

[snip]

- Command?
system ls ./msctraces
trace_tc1.mpr trace_tc2.mpr trace_tc3.mpr trace_tc4.mpr
- Command?


ISM Value Encoding

The ISM Value Encoding defines how values are encoded when sent, or decoded when received. It also defines the format for values when printed or read as test suite parameters. The format is not 100% compatible with the SDL Simulator format, or the MSC generation format, though in most cases it will be able to read those values as well.

The general syntax for the value notation is as follows. Rules named with all capital letters are tokens.

ISMValueEncoding ::= OptionalTypeAndValue ;
OptionalTypeAndValue ::= [TYPE] Value ;
TYPE ::= <Name of type defined in TTCN test suite> ;
Value ::= Composite | Atomic | OMIT;
Atomic ::= CSTRING | OSTRING | HSTRING | BSTRING | INTEGER | BOOLEAN ;
Composite ::= LPAR {OptionalTypeAndValue OPTCOMMA } RPAR;
CSTRING ::= '"' .* '"' ;
OSTRING ::= ''' ([09afAF][09afAF])* ''O' ;
HSTRING ::= ''' [09afAF]* ''H' ;
BSTRING ::= ''' [01]* ''B' ;
INTEGER ::= '-' [09]* | [09]* ;
BOOLEAN ::= 'TRUE' | 'FALSE' | 'true' | 'false' ;
LPAR ::= '{' | '(' ;
RPAR ::= '}' | ')' ;
OPTCOMMA ::= ',' | ;
OMIT ::= '-';

The CSTRING type is by default IA5String, use TYPE to override with a different character string type. Note also that in TTCN, the character string types are compatible and it may not be necessary to make the distinction.

Examples of this encoding include:

Encoding
Description

 1
The INTEGER value 1

 FALSE
The BOOLEAN value FALSE

 MyINTEGER 23
The INTEGER derivate MyINTEGER value 23

 BIT4 '1001'B
The BITSTRING derivate BIT4 value `1001'B

 { 1 , 2 , 3 }
A composite type with field values 1, 2 and 3

 ASP1 { 711,
TRUE }
An ASP1 with field 1 = 711 and field 2 = TRUE

 ASP2(BIT4
'1001'B PDU1(1
2))
An ASP2 with second field being a PDU1


36 TTCN Test Suite Generation

This chapter describes two ways for generating TTCN test suites based on SDL specifications. The first one is to use TTCN Link, which assists you in manual specification of test suites. The other one is to use the Autolink feature of the SDL Validator, which allows automatic generation of test suites.

For more information about the SDL Validator, see 52 The SDL Validator.

Tutorials for TTCN Link and Autolink can be found in 8 Tutorial: The TTCN Link and Tutorial: The Autolink Tool.


Introduction

Testing is one of the most important steps in the development of a new product. Often, it is also very time consuming and costly. As part of the Conformance Testing Methodology and Framework, the Tree and Tabular Combined Notation (TTCN) has been defined as a formal language for test suite specification. A test suite consists of four basic parts: The test suite overview, the declarations, the constraints and the dynamic behavior description.

In Telelogic Tau, TTCN test suite generation is supported by TTCN Link and Autolink. They both use an SDL specification as the basis for test generation, but they differ in their functionality.

TTCN Link generates the TTCN declarations part automatically and you use it for interactive building of test cases in the dynamic part.

Autolink is embedded in the SDL Validator. In addition to the SDL specification, it uses MSCs for test purpose descriptions. With this input, Autolink generates the declarations, constraints and dynamic behavior description parts of a TTCN test suite automatically.

In comparison, the test generation features of Autolink are superior to the ones of TTCN Link. If for some reason the test purpose description with MSCs is not applicable, then you should use TTCN Link. In any case, test cases built with TTCN Link can be merged with test cases generated by Autolink.

Figure 232 : Overview of TTCN Link and Autolink

TTCN Link - Generation of Declarations

TTCN Link automatically generates the TTCN declarations part based on an SDL specification. The default dynamic behavior table is also generated. It contains timeout and otherwise statements for each PCO, which will ensure that any incorrect response from the implementation under test always will give a FAIL verdict as a result from the test case. After the default and constraints tables have been generated, you can interactively build test cases.

When you use TTCN Link, there are four (five) phases involved:

  1. In the SDL Editor, you prepare an SDL specification.
  2. In the Organizer, you generate a TTCN Link application.
  3. In the TTCN suite, you use TTCN Link for generating the declarations part.
  4. In the TTCN suite, you interactively build test cases.
  5. Optionally, you may also merge the test suite with a TTCN-MP file, possibly generated by Autolink.

For more information about TTCN Link, see "Using TTCN Link" .

Autolink - Generation of a Test Suite

Autolink can be used for automatic generation of TTCN test suites based on an SDL specification and a number of MSCs. The steps involved when you use Autolink are:

  1. In the SDL Editor, you specify the SDL system to be used.
  2. In the Organizer, you generate a Validator.
  3. In the Validator, you define a number of traces through the SDL system for which you want to derive test cases. Each trace is stored as an MSC. Alternatively, you may create the MSCs manually in the MSC Editor or generate them with the help of the SDL Simulator.
  4. In a text editor, you define an Autolink configuration. The configuration tells Autolink how to map SDL signals and signal parameters onto TTCN constraint names, and how to group test cases and test steps.
  5. In the Validator, you generate intermediate representations of the test cases and constraints from the MSCs. This can either be done by state space exploration or by direct translation to TTCN.
  6. In the Validator, you may modify the generated constraints. Afterwards, the result is saved in a TTCN-MP file.
  7. The TTCN-MP file can be opened in the TTCN suite, and to complete the test suite, the test suite overview has to be generated. On UNIX, you have to generate it explicitly. In Windows, the overview is generated automatically, for example before you print.

For more information about Autolink, see "Using Autolink" .

Figure 233 : Generation of a TTCN test suite with the TTCN suite and Autolink


Using TTCN Link

The phases involved when you are using TTCN Link - "Preparing for the Generation of Declarations" , "Generating the Declarations" and "Creating Test Cases" - will be described below. You can also read about "Showing SDL System Information" and "Merging TTCN Test Suites in the TTCN Suite" .

Preparing for the Generation of Declarations

Before it is possible to generate the declarations, you have to do two things:

  1. Adapt the SDL system to the requirements of test generation and TTCN Link.
  2. Generate a Link executable for the SDL specification.

Adapting the SDL System

The major adaptation of the SDL system that you have to do, is to modify it to properly describe the test architecture that is to be used. Basically, the requirement is that the channels from/to the environment of the system must correspond to the points of control and observation in the test suite. For example, the SDL system might be a specification of a communication protocol where the lower side of the protocol in practise can only be accessed through a network. To be able to create correct test cases, you also have to include the communication media in the SDL specification. Note however, that the specification of the media does not have to be a detailed specification of the functionality, only a specification of the aspects relevant to the current testing situation.

Generating a Link Executable

Once the SDL specification describing the system to be tested and the test architecture are finished, you can generate a Link executable. (A Link executable is sometimes also referred to as state space generator.) You do this in the same way as when you generate an SDL Simulator or Validator.

To generate a Link executable:

  1. Select Make from the Generate menu in the Organizer.
    The Make dialog will be opened.
  2. Select Analyze & generate code.
  3. Select Generate Makefile.
  4. Select Use Standard Kernel and TTCN Link.
  5. If necessary, change other options.
  6. Click Full Make.
    The Link executable will now be generated. It includes the information about the SDL specification that is needed for generation of the TTCN declarations. The name of the executable will be
    <sdl system name>_xxx.link    , where xxx is depending on the compiler used.

Note:

You should not change the SDL system after you have generated the Link executable. Such changes will not affect the generated Link executable and therefore not affect the generation of declarations.

Generating the Declarations

There are two steps involved in generation of the declarations (and the default table):

  1. You select the Link Executable.
  2. You start the generation.

Specifying the Link Executable

Before the actual generation of the TTCN declarations, you have to specify the Link executable - and thereby the SDL system - to use. There are two methods for doing this: associating the SDL and TTCN systems in the Organizer and explicitly selecting the Link executable in the TTCN suite. In case a Link executable has been specified both in the Organizer and in the TTCN suite, the one selected in the TTCN suite is the executable that will be used.

Also note that the TTCN test suite that you are going to generate the declarations in, have to be created and added to the Organizer (and the same system file as the SDL system is included in).

Associating the SDL System with the TTCN Test Suite in the Organizer

  1. In the Organizer, select the SDL system (the top node).
  2. Select Associate from the Edit menu.
    The Associate dialog will be opened.
  3. In the dialog, select the TTCN test suite and click OK.
    The association will be indicated by a new icon placed under the test suite icon.

Selecting the Link Executable in the TTCN Suite

  1. Make sure that the test suite is opened and that the Browser is active.
  2. Select Select Link Executable from the SDT Link menu. On UNIX, it is the menu in the Browser.
    The Select Link Executable dialog will be opened.
  3. In the dialog, select the Link executable and click OK.

Note: External synonyms

The SDL system from which the Link executable is generated may contain external synonyms that do not have a corresponding macro definition (see "External Synonyms" ). Such an SDL system cannot be used with TTCN Link and you will get an error message when trying to select the Link executable.

However, if you set the environment variable SDTEXTSYNFILE to a synonym definition file before starting Telelogic Tau, this file will automatically be used to define the external synonyms. If SDTEXTSYNFILE is set to "[[" all synonyms are given "null" values.
The syntax of a synonym file is described in "Reading Values at Program Start up" .

Generating the TTCN Declarations

When you have specified the Link executable, you can generate the declarations in the TTCN suite:

  1. Select Generate Declarations from the SDT Link menu. On UNIX, it is the menu in the Browser.
    This will generate the declarations and a default table.
  2. Expand the Declarations Part and take a look:
    • One or more PCO type declarations have been generated.
    • For each channel to/from the environment in the SDL system, one PCO declaration has been generated.
    • For each signal on these channels, one ASN.1 ASP/PDU declaration has been generated.
    • For each data type that is used as a parameter on the signals to/from environment, a TTCN/ASN.1 data type definition has been generated if the data type cannot be mapped to a standard TTCN data type.
  3. Expand the Dynamic Part. You should see that a default behavior tree called Otherwise Fail is generated. This contains otherwise statements with verdict FAIL for all generated PCOs.

PCO Mapping

There are two alternatives available for generation of the PCO types: either one PCO type is generated for each channel in the SDL system or only one PCO type is generated. This is defined by the configuration command define-pco-type-mapping (see "PCO Type Generation Strategy" ). The default is that only one PCO type is generated.

If more than one PCO type is generated, they are named <ChannelName>_TypeId. If only one PCO type is generated it is called PCO_Type.

ASP/PDU Mapping

The generated ASPs/PDUs are given the same name as the corresponding SDL signal with one exception: If there are multiple PCO types and there is one signal that can be transported on more than one channel to the environment, this signal is divided into two ASPs, since an ASP may only be associated with one PCO type. The ASPs are then given names like <SDLSignalName>_<PCOName>.

By default, ASPs are generated from the SDL signals. However, you can change it to PDUs by using the define-signal-mapping command (see "SDL Signal Mapping Strategy" ).

Data Type Mapping

The data type mapping from SDL to TTCN/ASN.1 is defined in the following table. In most cases a table containing an ASN.1 type definition is generated for each data type. In the table below, this is indicated by a "<TTCN name> -> <ASN.1 definition>" clause. The <TTCN name> is the name used to denote the type in the test suite and the <ASN.1 definition> is the ASN.1 type definition that is the contents of the generated table. If the TTCN name is omitted, the name is given by the name of the corresponding SDL data type.

SDL data type | TTCN/ASN.1 data type
structure | -> SEQUENCE
array (with finite index sort) | -> SEQUENCE OF
string | -> SEQUENCE OF
bag | -> SET OF
enumerated type | -> ENUMERATED
boolean | BOOLEAN
character | Character -> IA5String (SIZE (1))
charstring | CharString -> IA5String
integer | INTEGER
real | Real -> REAL
natural | Natural -> INTEGER (0 .. MAX)
syntype | -> subtype
choice | -> CHOICE
bit | Bit -> BIT STRING (SIZE (1))
bit_string | BIT_STRING -> BIT STRING
octet | Octet -> OCTET STRING (SIZE (1))
octet_string | OCTET_STRING -> OCTET STRING
ObjectIdentifier | OBJECT_IDENTIFIER -> OBJECT IDENTIFIER
IA5String | IA5String
NumericString | NumericString
PrintableString | PrintableString
VisibleString | VisibleString
Null | NULL

In addition to the data types above, data types defined in external ASN.1 modules can also be used. These data types are mapped to definitions in the table named "ASN.1 Type Definitions by Reference" in the test suite. For each data type in the external ASN.1 module that is used on signals to/from the environment, one line defining the data type will be generated in this table. Note that the Generate Declarations command in the SDT Link menu assumes that the external ASN.1 module is setup as a dependency of the TTCN document.

No other data types than the ones mentioned above may occur on signals to/from the environment in the system.

Note that SDL is not case sensitive whereas TTCN is case sensitive. The spelling of the names generated by TTCN Link is given by the defining occurrence of the corresponding SDL name. Also note that no transformation of names is performed during generation of the TTCN names. This may in some cases lead to incorrect TTCN names if for example a reserved word from TTCN is used in the SDL system. To fix this problem, you have to change the name in the SDL system to a legal TTCN name.

Note that the SDL character NUL is mapped to NUL. Unfortunately, NUL is not an IA5String allowed character. So this must manually be changed to a legal character, e.g. "". The NUL character is especially interesting since uninitialized SDL characters are set to NUL.

Modifying the Generated Declarations

In some cases, you may find it useful to manually modify the declarations that have been generated by TTCN Link before continuing with the development of the test cases. There are in particular two interesting cases:

  • ASPs vs. PDUs.
    TTCN Link automatically generates ASPs for all signals visible on the border of the SDL system unless defined otherwise by the define-signal-mapping option (see "SDL Signal Mapping Strategy" ). If PDU definitions are more suitable for some of the signals, this is the time to change them. The simplest way is to copy the generated ASPs from the section ASN.1 ASP Type Definitions and paste them as PDUs in the section ASN.1 PDU Type Definitions.
  • ASP field names.
    The ASPs are generated based on the SDL signals, and since the signals in SDL have no parameter names (only types), TTCN Link automatically generates names for the ASP fields. The fields are given the name "<type name><no>" where the <type name> is the name of the type of this parameter (but always starting with a non-capital letter to follow ASN.1 rules). It is however possible to change these names in the generated definitions, and if you do it before the test cases are developed, the new manually defined names will also be used in the test cases.

Regeneration of Declarations

It is possible to regenerate the declarations from an SDL system to incorporate new signals, channels and/or data type into the test suite. If you select Generate Declarations from the SDT Link menu again, only declarations with a name different from the existing test suite declarations will be inserted into the test suite.

Creating Test Cases

To create test cases with TTCN Link, you use the Table Editor in the TTCN suite. When TTCN Link is used, the test cases are synchronized, that is, verified against the SDL specification.

In synchronized mode, the test case is guaranteed to be consistent with the specification. Each action you perform during the development of the test case will be incrementally verified by the state space exploration part of TTCN Link. When a table is in synchronized mode, the SDT Link menu of the UNIX Table Editor will contain new menu choices for editing of the test case. In Windows, you can find the corresponding commands in the Link dialog:

  • Send will add a send statement to the test case. This is a manual step where you define the constraint to be associated with the send statement.
  • Receive automatically generates all valid responses from the system under test. This implies that you do not need to check with the specification which possible signals the system can send in the state it is driven to by the proceeding lines in the test case.
  • Start timer and Cancel timer are also manual commands where TTCN timers are started and cancelled. However, note that the timeout event corresponding to the timer will be automatically generated as a result of a Receive command.
  • Attach test step will attach a previously defined test step, while still keeping the editor in synchronized mode.

If you modify the contents of the test case by using other menu choices, the editor will leave the synchronized mode.

The verdict for the generated test case lines, will always be either PASS or INCONCLUSIVE since the generated receive lines will always correspond to valid behaviors of the implementation under test.

A default test step, which consists of an otherwise fail for each PCO, will ensure that an incorrect response from the implementation under test always will give a FAIL verdict as a result from the test case.

Constraint Restrictions

The constraints that are used in send and receive statements in the test cases, are subject to certain restrictions:

  • They may not use test suite or test case variables or test suite parameters.
  • They must be "exactly" defined without any omits, any values, ranges, wildcards, etc.

The following is however allowed in send and receive constraints a test case is resynchronized, even though it is not generated automatically for receive constraints:

  • The constraints can be structured/chained, that is, the constraints can reference and use other constraints defined in the test suite.
  • The constraints can use test suite constants.
  • The constraints can be parametrized.

Creating Test Steps

It is often useful to structure the test case into test steps. To do this by using TTCN Link:

  1. Create the TTCN statements that should be in the test step directly in the test case table. This should of course be done in synchronized mode.
  2. Cut the lines that should form the test step from the test case.
  3. Create a test step table.
  4. Paste the lines into the new test step table and adjust the indentation level.
  5. Add an attach statement to the test case.

Showing SDL System Information

When you use TTCN Link for creating a test case, it is possible to access the SDL specification from the Table Editor.

To do this you first select a line in the test case. Then you have three alternatives:

  • Select Show SDL from the SDT Link menu.
    The SDL Editor will be opened and display the executed SDL symbols that correspond to the selected test case line.
  • Select Show Coverage from the SDT Link menu.
    This will display the Coverage Viewer and coverage information for the current test case.
  • Select Show MSC from the SDT Link menu.
    The MSC Editor will be opened with a generated MSC diagram showing the execution path from the start of the SDL system to the state corresponding to the selected line in the test case. This may be particularly useful if you need to find out how unexpected receive statements are possible.

Merging TTCN Test Suites in the TTCN Suite

By using TTCN Link, you can only generate the declarations and create the dynamic tables. Either you could add the constraints and dynamic tables manually or merge the TTCN Link generated test suite with one generated by Autolink. A test suite generated by Autolink is in TTCN-MP format and contains constraints, declarations and dynamic tables.

To merge the test suites:

  1. Make sure that the test suite that you want to merge the MP file into - that is, the destination document - is opened and active.
  2. In Windows, select Autolink Merge from the File menu.
    On UNIX, select Autolink Merge from the SDT Link menu in the Browser.
    A dialog will be opened.
  3. Find and select the MP file that you want to merge with the currently opened test suite.
  4. Click OK (in Windows) or Merge (on UNIX).
    The MP file you selected will be merged into the currently opened test suite.
    To complete the test suite on UNIX, you also have to generate the test suite overview. In Windows, the overview is generated automatically, for example before you print, and after that it is kept updated.

The merge will only work if the two test suites do not conflict. A conflict occurs if any TTCN object in the MP file has the same name as any TTCN object in the destination document. However, if such a conflict is detected, the merge will continue but the conflicting object in the MP file will be skipped.

Constraints will be merged in a special way. For example, the MP file may contain a TTCN ASP constraint called constraint1 that refers to the type type1 which is of the incompatible type TTCN PDU TypeDef. Because of this, a copy of constraint1 will be inserted as a TTCN PDU constraint instead. However, this "type conversion" is limited. An ASN.1 constraint will not be converted to a TTCN constraint or vice versa.

Summary of TTCN Link

TTCN Link supports test case development and there are two major objectives:

  • To help solving the consistency problem that arises as soon as there are two different descriptions of the same system, in this case the SDL specification and the TTCN test suite.
  • To supply an environment that, based on the SDL specification, supports test suite development during the TTCN design. Both by directly using the SDL specification, for example to generate the declarations, and by providing access to the SDL specification directly from the TTCN suite.

Overview of the TTCN Link Algorithm

This section will give a brief introduction to the algorithm used by TTCN Link to synchronize a test case with an SDL system.

The Composed System

The system that TTCN Link analyzes is the composed system that consists of both the SDL specification and the TTCN test case that is interactively created.

Figure 234 : A composed SDL/TTCN system

The connection between the SDL system and the TTCN test case is created by connection of the channels to/from environment in the SDL system to the PCOs in the test suite.

State Space Exploration

The technique used by TTCN Link is based on state space exploration (sometimes referred to as reachability analysis) of the system composed of the SDL system together with the test case that is being created. The state space of this system can be viewed as a graph, where the nodes represent system states and the edges represent actions that can be performed by the system.

Figure 235 : A state space fragment

Each system state represents the combined system in one moment in time. It contains information of for example:

  • What SDL process instances exist
  • The variable values of all the process instances
  • The control flow state of the instances
  • Any procedure calls, including local variables in the procedures
  • The current line number of the test case
  • Any started timers, both SDL and TTCN timers

The actions represented by the edges are either SDL actions like input, output, tasks, etc., or TTCN actions like send, receive or start timer.

Essentially, the algorithm to generate the state space of the combined system is the following, where two global variables - StateSpace (a graph that will contain the state space of the system) and TreatList (a list of states that is yet to be treated by the algorithm) - are used:

  1. Create the start system state and add it to StateSpace and TreatList.
  2. Remove one state (in step 3-4 called the current state) from TreatList.
  3. Compute all possible actions that can be performed in the current state and the resulting system state that will be reached when the respective action has been performed.
  4. For each action/resulting state:
    • If the resulting state was not already in StateSpace, add it to TreatList.
    • Add the action/resulting state to StateSpace.
  5. If TreatList is empty: Terminate algorithm, the state space of the system is now represented by the graph in StateSpace.
    If TreatList is not empty: Go to step 2.

Incremental State Space Exploration

Since you interactively create the test case that describes the TTCN part of the combined SDL/TTCN system, it is not possible for TTCN Link to compute the entire state space at once. Instead, the state space exploration is performed in an incremental fashion in the following way:

  1. You compute the state space that can be reached without any action by the test case.
  2. When you TTCN Link to add a TTCN statement to a leaf in the test tree, you add the corresponding TTCN action(s)/resulting system state(s) to the state space.
  3. Generate the state space that can be reached from the newly created system state(s) without any further action by the test case.
  4. Go to step 2.

The consequence of this algorithm is that the state space of the combined SDL/TTCN system is explored in an incremental fashion, where each increment corresponds to a command you have given. Also the structure of the state space is influenced by the incremental way that it is generated. The state space can be visualized as a tree structure, where each node represents one line in the test case and a subpart of the state space, to be more precise, the subpart of the state space where the test case has executed this particular line but not the next one.

Figure 236 : A structured state space

Since each line in the test case is created by a command from you, each node with its associated part of the state space can also be viewed as the state space increment that was created by a specific command.

Random Walk Exploration

The default state space exploration algorithm used by TTCN Link is the algorithm described in the previous sections. This is usually referred to as exhaustive exploration since it exhaustively explores the state space until all reachable states has been generated. The benefit of this algorithm is that when the exploration is finished, you can be sure that all possible combinations and alternatives are explored, that is, if TTCN Link generates two alternatives in a receive statement, the algorithm guarantees that there are no more valid alternatives. However, the drawback is that the algorithm requires all states in the state space to be kept in primary memory. For large SDL systems this may not always be possible with the computers available. The response time may also be unacceptable for interactive work with large systems.

To be able to use TTCN Link even in these cases, a second exploration algorithm is also provided. This is the random walk algorithm that, instead of exploring the entire state space, explores random paths in the state space using the algorithm described below. The input to the algorithm is a set of start states called StartList and a maximum depth of the exploration (MaxDepth) and the number of repetitions (Rep):

  1. Select one state (in step 2-4 called the current state) from StartList.
  2. Compute all possible actions that can be performed in the current state and the resulting system states that will be reached when the respective action has been performed.
  3. If no actions could be performed from the current state or if the depth of the current random walk is MaxDepth, the current random walk is pruned. If the number of random walks performed so far is less than Rep, go to step 1, otherwise terminate the algorithm.
  4. If actions could be performed and the depth is less than MaxDepth, select one of the generated states as a new current state and go to step 2.

The benefit with the random walk algorithm is that not more than a few system states (the current state and its successors) need to be kept in the memory at the time. The drawback is that there is no guarantee that the entire state space is explored, so, for example, even if TTCN Link generates only one receive alternative, it is possible that there are more alternatives.

To accomplish the best, both from exhaustive exploration and random walk, a two-step approach can be used when you use TTCN Link for large SDL systems:

  1. Develop the test cases interactively by using the random walk algorithm with a small number of repetitions (1-3).
  2. Verify that no more receive alternatives were possible by resynchronizing the test cases and using the exhaustive exploration algorithm. Or, if this is not possible due to lack of memory, use random walk with a high number of repetitions (at least 10, preferably 50-100).

This strategy gives both good performance when you interactively create the test cases and a good verification of the correctness of the test case during the automatic resynchronize. The execution time of the random walk algorithm is proportional to the number of repetitions.

You select which algorithm to use in the .linkinit file (on UNIX) or the linkinit.com file (in Windows) by using the
define-algorithm command as described in section "Configuring the TTCN Link Executable" .

Summary of the TTCN Link Algorithm

The algorithm used by TTCN Link to resynchronize a TTCN test case with an SDL system, is based on an incremental state space exploration of the state space of the composed system. The system consists of the SDL specification, together with the test case under construction. In the state space exploration, each command that you give will cause a new part of the state space to be explored, that is, the part that corresponds to the TTCN statement line that is inserted by the command. Two different exploration algorithms are available: exhaustive exploration and random walk. Exhaustive exploration is used for interactive development of test cases for a small SDL system and for verification of test cases for large systems. Random walk is used for interactive development of test cases for large SDL systems.

Configuring the TTCN Link Executable

This section describes the various options that can be used to configure the Link executable. You can change the options by giving the corresponding commands in a file called .linkinit (on UNIX) or linkinit.com (in Windows) in the target directory. The options that can be set are:

  • Exploration Algorithm
  • Random Walk Depth
  • Random Walk Repetitions
  • PCO Type Generation Strategy
  • SDL Signal Mapping Strategy
  • Stable State
  • Timer Mode
  • Transition
  • Scheduling
  • MSC Trace

These options will be described below.

It is also possible to add user-defined rules to the .linkinit file (on UNIX) or the linkinit.com file (in Windows) in order to prune the state space that is explored by Link. The user-defined rules are described in "User-Defined Rules" .

Exploration Algorithm

What exploration algorithm is used, is defined by the command

define-algorithm [exhaustive|randomwalk]

and has the default value exhaustive. The differences between the different algorithms are described in section "Overview of the TTCN Link Algorithm" .

Random Walk Depth

The maximum depth of each random walk is defined by the command

define-randomwalk-depth <integer>

and has the default value 500.

Random Walk Repetitions

The number of times a random walk is performed when a state space is explored by using this algorithm is defined by the command

define-randomwalk-repetitions <integer>

with a default value of 3.

PCO Type Generation Strategy

The PCO Type generation strategy is defined by the command

define-pco-type-mapping [system|channel]

and has default value system.

  • If the parameter given is system then only one PCO type is generated for the entire system.
  • If the parameter is channel then one PCO type is generated for each channel to/from the environment.

The choice also has an impact on the ASPs that are generated from SDL signals. Usually the name of the ASP is the same as the name of the SDL signal. However, if one PCO type is generated for each channel to/from the environment and one SDL signal can appear on more than one of these channels, then one ASP is generated for each channel it appears on. This is needed since an ASP can only be associated with one PCO type. The names of the signals are in this case defined as <signal name>_<channel name>.

SDL Signal Mapping Strategy

The SDL signals that appear on channels to/from the environment in the SDL system are either mapped to ASN.1 PDU or ASN.1 ASP definitions in the test suite. The mapping is defined by the command

define-signal-mapping [asp|pdu]

and has default value asp.

Stable State

The stable state option is defined by the command

define-stable [on|off]

and has the default value on.

It works like this:

Consider the situation when an empty test case has been resynchronized. The Link executable will now have computed the state space that can be reached without any input from or output to the tester. Usually, the state space looks something like this:

Figure 237 : Original state space

where 0 is the start state, 1-4 are intermediate states and 5 is a stable state where all internal queues in the SDL system are empty and nothing more can happen without any input from the tester.

Let us now give a send command. This implies that new states are created as send transitions are added to the state space.

If the stable state assumption is off then we add one send transition to each state in the original state space, the new state space looks something like this:

Figure 238 : The new state space with stable state assumption "off"

where all states called something with `a' are new. Now the states space that contains states that can be reached from the `a' states without any input from or output to the tester is explored.

On the other hand, if the stable state assumption is on then we only add a send transition to the stable state, giving a new state space looking like:

Figure 239 : The new state space with stable state assumption "on"

Now, only the states that can be reached from "5a" without any input from or output to the tester are explored. This state space is of course a lot smaller that the one above.

Timer Mode

This is an option that in most cases will not have to be changed. The option defines how to interpret timeout actions compared with all other actions in the system. The option is changed by the command:

define-timer-mode [long|short]

The default is long.

If the timer mode is long, timeout actions will never occur if there is an internal event possible in the system. Essentially, the assumption is that the performance of the test system and IUT is good enough to ensure that the execution time for the actions are very small compared to the timeout times. Consider a system with the following state space when the long timer mode is used:

Figure 240 : State space with timer mode "long"

In this system, the timeout event does not occur until no other event can happen. The transition leading to states 1-3 are all usual transitions - for example. inputs and outputs - so the timeout will only occur in state 3, where no other event is possible.

If the timer mode would have been short, the state space would have looked differently:

Figure 241 : State space with timer mode "short"

The reason is that the timeout event now is possible in all the states 0-3.

Transition

The transition option defines what is considered to be an atomic transition in the state space and is defined by the command:

define-transition [`sdl'|'symbol']

The default value is symbol.

If the transition option is set to sdl, then SDL process graph transitions are considered atomic. This means that there will be no states in the state space where SDL processes are in the middle of a process graph transition. In all system states in the state space, the processes will always be in a process graph state.

If the transition option is set to symbol, the SDL process graph transitions are not considered to be atomic. In theory, this would imply that the processes could be interrupted anywhere during the execution of a transition. However, it turns out that for test generation purposes it is enough if the process graph transitions are divided at the points where one process communicates with another process, for example after an output or a create. A sequence of tasks or decisions is still viewed as atomic.

The consequence of this is that there will be more transitions in the state space if the transition option is symbol than if it is sdl. Consider a simple system with only one process. Let this process have a transition like:

state xx;
input st1;
output sig2;
output sig3;
output sig4
nextstate st2;

If the transition option is sdl, there will only be one transition in the state space that corresponds to the process graph transition above:

X : process is in state st1
|
Y : process is in state st2

If the transition option is symbol, there will be a sequence of transitions in the state space:

X : process is in state st1
| input st1; output sig2;
X1
| output sig2;
X2
| output sig3;
X3
| output sig4; nextstate st2;
Y : process is in state st2

This will of course give a lot bigger state space.

Scheduling

The scheduling option is defined by the command

define-scheduling [`first'|'all']

This option controls how many processes are allowed to execute in a given system state. If the option is set to first, only one process (the first in the ready queue) is allowed to execute. If the option is set to all, all processes that can execute are allowed to do it. The default value is all.

Consider an SDL system with two static processes. If the scheduling option is all, the initial part of the state space for this system will probably look like:

Figure 242 : State space with scheduling as "all"

where

  • 0 is the initial state (both processes are in the start symbol).
  • 1 is the state where the first process has executed its start transition while the second process is still in its start symbol.
  • 2 is the state where the second process has executed its start transition while the first process is still in its start symbol.
  • 3 is the state where both processes have executed their start transitions.

On the other hand, if the scheduling option is first, it will look like:

Figure 243 : State space with scheduling as "first"

where

  • 0 is the initial state (both processes are in the start symbol).
  • 1 is the state where the first process has executed its start transition while the second process is still in its start symbol.
  • 2 is the state where both processes have executed their start transitions.

If there are lots of processes, there will be a significant difference in the size of the state space depending on how the scheduling option is set!

MSC Trace

The MSC trace options control what is displayed in the MSCs generated by TTCN Link. There are two different MSC trace options controlling if states and actions in the SDL system are showed as MSC condition symbols and MSC action symbols. The options are set by the following commands:

define-MSC-trace-actions [ `on' | `off' ]

define-MSC-trace-states [ `on' | `off' ]

The default value for both options is `off'.

An Example of a .linkinit / linkinit.com File

This following .linkinit file (on UNIX) or linkinit.com file (in Windows) will change the exploration algorithm to random walk and set the number of repetitions to 2:

define-algorithm random
define-random-rep 2

This is a useful configuration when you work interactively with TTCN Link, since the random walk algorithm is quicker and requires less memory than the exhaustive algorithm. But, since the random walk in some cases can miss some alternative receive statement, a useful strategy is the following: Use the configuration above when you work interactively with TTCN Link. However, when you have finished with a test case or a number of test cases, check that the assumptions are valid by resynchronizing with the exhaustive algorithm or a larger number of repetitions.

Note that in the commands in the .linkinit file (on UNIX) and the linkinit.com file (in Windows) can be abbreviated as long as they are unique.

User-Defined Rules

User-defined rules can be used during state space exploration to prune the search performed by the TTCN Link. Whenever a system state is found that matches the defined rule, the search is pruned at this particular state. This can be useful in order to remove specific exceptional behavior from the test cases that are designed and instead handle these in a special default test step.

Consider an SDL specification that contains a clock process that has a timer intervaltimeout. Every time the intervaltimeout expires, a signal DisplayTime is sent to the environment of the SDL system. Since this can happen at any time during the execution, there will be an alternative at all receive statements corresponding to the reception of this signal. To avoid this, it is better to add a receive statement in the default dynamic behaviour that skips this signal.

To achieve this with TTCN Link, you have to do two things:

  • Define a rule that prunes the state space at appropriate places.
  • Modify the default dynamic behaviour that is generated by TTCN Link.

A rule that prunes the state space whenever the intervaltimer expires is the following:

def-rule sitype(signal(clock:1))=intervaltimeout;

The statements that need to be added to the default behaviour are:

PCO?DisplayTime DisplayTime_Match_All
RETURN

These lines will cause the tester to ignore DisplayTime signals sent from the system.

A rule essentially gives the possibility to define predicates which describe properties of one particular system state. As soon as this predicate matches a system state, TTCN Link will prune the search. A rule consists of a predicate (as described below) followed by a semicolon (`;'). In a rule, all identifiers and reserved words can be abbreviated as long as they are unique.

Note:

Only one rule can be used at any moment. If more than one rule is needed, reformulate the rules as one rule, by using the boolean operators described below.

Predicates

The following types of predicates exist:

  • Quantifiers over process instances and signals in input ports
  • Boolean operator predicates such as "and", "not" and "or"
  • Relational operator predicates such as "=" and ">"

Parenthesis are allowed to group predicates.

Quantifiers

The quantifiers listed below are used to define rule variables denoting process instances or signals. The rule variables can be used in process or signal functions described later in this section.

exists <RULE VARIABLE> [: <PROCESS TYPE>]
[ | <PREDICATE>]

This predicate is true if there exists a process instance (of the specified type) for which the specified predicate is true. Both the process type and the predicate can be excluded. If the process type is excluded, all process instances are checked. If the predicate is excluded, it is considered to be true.

all <RULE VARIABLE> [ : <PROCESS TYPE>]
[ | <PREDICATE>]

This predicate is true for all process instances (of the specified type) for which the specified predicate is true. Both the process type and the predicate can be excluded. If the process type is excluded, all process instances are checked. If the predicate is excluded, it is considered to be true.

siexists <RULE VARIABLE> [ : <SIGNAL TYPE>]
[ - <PROCESS INSTANCE>] [ | <PREDICATE>]

This predicate is true if a signal (of the specified type) exists in the input port of the specified process for which the specified predicate is true. If no signal type is specified, all signals are considered. If no process instance is specified, the input ports of all process instances are considered. If no predicate is specified, it is considered to be true. The specified process can be either a rule variable that has previously been defined in an exists or all predicate, or a process instance identifier (<PROCESS TYPE>:<INSTANCE NO>).

siall <RULE VARIABLE> [ : <SIGNAL TYPE>]
[ - <PROCESS INSTANCE>] [ | <PREDICATE>]

This predicate is true for all signals (of the specified type) in the input port of the specified process for which the specified predicate is true. If no signal type is specified, all signals are considered. If no process is specified, the input ports of all process instances are considered. If no predicate is specified, it is considered to be true. The specified process can be either a rule variable that has previously been defined in an exists or all predicate, or a process instance identifier (<PROCESS TYPE>:<INSTANCE NO>).

Boolean Operator Predicates

The following boolean operators are included (with the conventional interpretation):

not <PREDICATE>
<PREDICATE> and <PREDICATE>
<PREDICATE> or <PREDICATE>

The operators are listed in priority order, but the priority can be changed by parenthesis.

Relational Operator Predicates

The following relational operator predicates exist:

<EXPRESSION> = <EXPRESSION>
<EXPRESSION> != <EXPRESSION>
<EXPRESSION> < <EXPRESSION>
<EXPRESSION> > <EXPRESSION>
<EXPRESSION> <= <EXPRESSION>
<EXPRESSION> >= <EXPRESSION>

The interpretation of these predicates is conventional. The operators are only applicable to data types for which they are defined.

Expressions

The expressions that are possible to use in relational operator predicates are of the following categories:

  • Process functions: Extract values from process instances
  • Signal functions: Extract values from signals
  • Global functions: Examine global aspects of the system state
  • SDL literals: Conventional SDL constant values

Process Functions

Most of the process functions must have a process instance as a parameter. This process instance can be either a rule variable that has previously been defined in an exists or all predicate, a process instance identifier (<PROCESS TYPE>:<INSTANCE NO>) or a function that returns a process instance, e.g. sender or from.

state( <PROCESS INSTANCE> )

Returns the current SDL state of the process instance.

type( <PROCESS INSTANCE> )

Returns the type of the process instance.

iplen( <PROCESS INSTANCE> )

Returns the length of the input port queue of the process instance.

sender( <PROCESS INSTANCE> )

Returns the value of the imperative operator sender (a process instance) for the process instance.

parent( <PROCESS INSTANCE> )

Returns the value of the imperative operator parent (a process instance) for the process instance.

offspring( <PROCESS INSTANCE> )

Returns the value of the imperative operator offspring (a process instance) for the process instance.

self( <PROCESS INSTANCE> )

Returns the value of the imperative operator self (a process instance) for the process instance.

signal( <PROCESS INSTANCE> )

Returns the signal that is to be consumed if the process instance is in an SDL state. Otherwise, if the process instance is in the middle of an SDL process graph transition, it returns the signal that was consumed in the last input statement.

<PROCESS INSTANCE> -> <VARIABLE NAME>

Returns the value of the specified variable. If <PROCESS INSTANCE> is a previously defined rule variable, the exists or all predicate that defined the rule variable must also include a process type specification.

<RULE VARIABLE>

Returns the process instance value of <RULE VARIABLE>, which must be a rule variable bound to a process instance in an exists or all predicate.

Signal Functions

Most of the signal functions must have a signal as a parameter. This signal can be either a rule variable that has previously been defined in an siexists or siall predicate, or a function that returns a signal, e.g. signal.

sitype( <SIGNAL> )

Returns the type of the signal.

to( <SIGNAL> )

Returns the process instance value of the receiver of the signal.

from( <SIGNAL> )

Gives the process instance value of the sender of the signal.

<RULE VARIABLE> -> <PARAMETER NUMBER>

Returns the value of the specified signal parameter. The siexists or siall predicate that defined the rule variable must also include a signal type specification.

<RULE VARIABLE>

Returns the signal value of <RULE VARIABLE>, which must be a rule variable bound to a signal in a siexists or siall predicate.

Global Functions

maxlen( )

Gives the length of the longest input port queue in the system.

instno( [<PROCESS TYPE>] )

Returns the number of instances of type <PROCESS TYPE>. If <PROCESS TYPE> is excluded the total number of process instances is returned.

depth( )

Gives the depth of the current system state in the behavior tree/state space.

SDL Literals

<STATE ID>

The name of an SDL state.

<PROCESS TYPE>

The name of a process type.

<PROCESS INSTANCE>

A process instance identifier of the format <PROCESS TYPE>:<INSTANCE NO>, e.g. Initiator:1.

<SIGNAL TYPE>

The name of a signal type.

null

SDL null process instance value

env

Returns the value of the process instance in the environment that is the sender of all signals sent from the environment of the SDL system.

<INTEGER LITERAL>
true
false
<REAL LITERAL>
<CHARACTER LITERAL>
<CHARSTRING LITERAL>

SDL Restrictions

The restrictions imposed on the SDL specification by TTCN Link are basically of four different kinds:

  • General SDL restrictions
  • State space exploration restrictions
  • Data type mapping restrictions
  • TTCN name restrictions

General SDL Restrictions

TTCN Link is based on the SDL to C compiler and has thus the same restrictions as the Simulator and Validator which are also based on the SDL to C compiler. The major restrictions are:

  • No context parameters
  • No channel substructures
  • No signal refinements
  • No axioms, literal mappings, inheritance or name class literals in abstract data types

For more information about the general SDL restrictions see "SDL Restrictions.

State Space Exploration Restrictions

TTCN Link is based on state space exploration of the combined state space of the SDL system and the TTCN test case. Since there is only a finite amount of memory available in computers, this means that there will be restrictions on the size of the state space that can be handled. It is not possible to give a numeric value on this restriction since it depends both on the SDL system and on the computer, but TTCN Link has been successfully used on SDL systems with more than 10 processes on a SPARCstation 10 computer. Also see "Overview of the TTCN Link Algorithm" .

Data Type Mapping Restrictions

Only the data types described in section "Generating the Declarations" are allowed on the channels to/from the system.

TTCN Name Restrictions

The mapping of concepts from SDL to TTCN generates a lot of names in TTCN. For example, the signals in SDL will become ASPs/PDUs in TTCN and SDL data types will become TTCN data types. The names of the generated entities are taken directly from the names on the corresponding SDL entity. This will lead to problems if, for example, the names are reserved words in TTCN. In this case, the names in the SDL system have to be changed.


TTCN Link Commands in the TTCN suite

TTCN Link Commands in the TTCN Suite on UNIX

This section describes the extra menu choices that are available in the TTCN suite when TTCN Link is used on UNIX.

Browser Commands in the SDT Link Menu

The following menu choices are available in the Browser SDT Link menu:

  • Select Link Executable
  • Generate Declarations

Select Link Executable

Makes a connection between a test suite and the corresponding SDL system. In the file dialog that opens, a Link executable should be selected. If the file is not a legal Link executable, the selection will fail.

When a Link executable is selected, a place holder for it is stored in the test suite. It is possible to change the Link executable if, and only if, there is no test case which uses the current SDL system (i.e. there is no synchronized test case).

It is also possible to select a Link executable by associating the SDL system with the TTCN system in the Organizer. However, a Link executable selected in the TTCN suite will override an executable selected in the Organizer.

See also "External synonyms" .

Generate Declarations

Generates TTCN versions of the relevant type declarations in the SDL system. The menu choice is only available if a Link executable has been selected.

The generated objects use the ASN.1 syntax. They are automatically analyzed after they have been generated. This is necessary for later operations and usage of these types. If there is no other declarations (types) in the test suite (e.g. the test suite is empty), the analysis will not fail. On the contrary if other declarations (types) already exist, the analysis may fail due to name conflicts and incorrect references. The error messages of this analyzing will not be displayed. To check if the generated declarations are analyzed, use the Selector and the Show Error Message command on the incorrect tables.

At the same time that the declarations are generated, a Default table will be generated. It consists of an otherwise statement for each PCO and a timeout statement.

No timer will be generated from the SDL system. If the design of the test suite requires any timers they must be defined manually.

More details about the generated tables etc. can be found in "Generating the Declarations" .

Table Editor Commands in the SDT Link Menu

To generate a test case (the behaviour description of a test case), the test case table must be in synchronized mode. In synchronized mode, the test case is synchronized (has an established connection) with the selected Link executable.

Once in synchronized mode, the test case editor will stay in this mode as long as only commands from the SDT Link menu are used. As soon as any field in the table (besides the comment fields) is edited, the synchronized mode will be terminated. It is however possible to analyze the test case without leaving the synchronized mode.

The following commands are available from a Table Editor for test cases or test steps. They are applied on a behaviour line (they insert a new behaviour line below/after the behaviour line with the input focus) hence it is required that the test case or the test step either is empty or has the input focus on a leaf row.

When each of these commands is performed the input focus is moved to the new generated behaviour line.

  • Send
  • Receive
  • Start Timer
  • Cancel Timer
  • Attach
  • Resynchronize
  • Show SDL
  • Show MSC
  • Show Coverage
  • Show Options

Send

Adds a send statement below/after the behaviour line with the input focus. The new behaviour line will have an increased indent level compared with the previous one.

Figure 244 : Send dialog

The send statement with the selected PCO, ASP/PDU and constraint will be verified by the selected SDL system. If the verification does not fail, a send statement is generated and inserted below/after the row with the input focus. For a more detailed description of this dialog, see "Add Send Statement" .

Receive

Adds appropriated receive and/or timeout statement(s) below/after the behaviour line with the input focus. The new row(s) will have the same indent level. This indent level will be increased compared with the previous one.

For each retrieved receive statement from the SDL system, a new Constraint is generated if there is no appropriate Constraint (a Constraint with a similar value). The new Constraint will be named with a unique name and will be analyzed. This new name is used in the Constraints Ref column.

Start Timer

Adds a start timer statement below/after the behaviour line with the input focus. The new behaviour line will have an increased indent level compared to the previous one.

Figure 245 : Start Timer dialog

The start timer statement with the selected timer will be verified with the selected SDL system. If the verification does not fail, a start timer statement is generated and inserted below/after the behaviour line with the input focus. For a more detailed description of this dialog see "Add Send Statement" .

Cancel Timer

Analogous to Start Timer.

Attach

Adds an attachment statement below/after the row with the input focus. The new behaviour line will have an increased indent level compared to the previous one.

The test step dialog used by this command is similar to the dialog in the Table Editor. The selected test step (the behaviour lines in the behaviour description) will be verified with the SDL system. The test step must have passed analysis before this operation.

Resynchronize

Verifies the test case in a Table Editor using the previously chosen Link executable. The table will change mode to the synchronized mode. This command is available from Table Editors for test cases and only if an SDL system is selected.

If the test case does not have any default reference and there is more than one default in the test suite, a selection dialog pops up and a default must be selected. If the test suite contains only one default, it will be selected automatically. If the test case already has a default, no change will be made.

If the test case (or the test step) contains behaviour lines, they will be verified with the current SDL system. If the verification of any line fails, the table will keep the normal mode.

Show SDL

Opens the SDL Editor with the symbols selected which were executed in the SDL system and are associated with the behaviour line which has the input focus. More precisely, the SDL symbols which were executed after the current test case line but before the next test case line, are selected exactly.

Show MSC

Opens the MSC Editor with a process level MSC that illustrates the execution path from the start of the SDL system to the state corresponding to the behaviour line with input focus.

Show Coverage

Opens the Coverage Viewer that displays test coverage information for the current test case. The test coverage displays how many times each symbol in the SDL system has been executed during the generation of the test case. Note that the important information is not the exact number of times a particular symbol has been executed (since this is dependent upon the particular algorithm used by the Link executable). The important information is whether a symbol has been executed or not. If a symbol in the SDL system has not been executed when generating the test case, the requirement defined by this symbol is not tested by the test case.

Show Options

Shows the current settings of the configuration parameters that control the way the Link executable explores the state space of the combined SDL/TTCN system.

TTCN Link Commands in the TTCN Suite in Windows

In Windows, different TTCN Link commands are included in the SDT Link menu and the Link dialog. The menu choices in the SDT Link menu are used for selecting the Link executable, generating declarations and for showing execution information. By using the Link dialog, you can generate various statements.

The SDT Link menu and the Link dialog will be explained below.

The SDT Link Menu

The following menu choices are included in the SDT Link menu:

  • Select Link Executable
  • Generate Declarations
  • Show SDL
  • Show MSC
  • Show Coverage
  • Show Options

Select Link Executable

Makes a connection between a test suite and the corresponding SDL system. Opens a dialog in which you may select the Link executable.

It is also possible to specify the Link executable in the Organizer by associating the SDL system with the TTCN system. However, a Link executable selected in the TTCN suite will override an executable selected in the Organizer.

See also "External synonyms" .

Generate Declarations

Generates TTCN versions of the relevant type declarations in the SDL system. The menu choice is only available if a Link executable has been selected.

The generated objects use the ASN.1 syntax. They are automatically analyzed after they have been generated. This is necessary for later operations and usage of these types.

At the same time as the declarations are generated, a Default table will be generated. It consists of an otherwise statement for each PCO and a timeout statement.

Timers will not be generated from the SDL system. If the design of the test suite requires any timers, they must be defined manually.

Show SDL

Opens an SDL Editor with the symbols selected which were executed in the SDL system and are associated with the selected behaviour line. More precisely, the SDL symbols which were executed after the current test case line but before the next test case line, are selected exactly.

Show MSC

Opens an MSC Editor with a process level MSC that illustrates the execution path from the start of the SDL system to the state corresponding to selected the behaviour line.

Show Coverage

Opens an SDL Coverage Viewer that displays test coverage information for the current test case. The test coverage displays how many times each symbol in the SDL system has been executed during the generation of the test case. Note that the important information is not the exact number of times a particular symbol has been executed (since this is dependent upon the particular algorithm used by the Link executable). The important information is whether a symbol has been executed or not. If a symbol in the SDL system has not been executed when the test case was generated, the requirement defined by this symbol is not tested by the test case.

Show Options

Shows the current settings of the configuration parameters that control the way the Link executable explores the state space of the combined SDL/TTCN system.

The Link Dialog

The Link dialog can be opened from the SDT Link menu. The Link dialog can only be used when a behaviour line is selected in the table or if the table does not yet contain a behaviour line. When the Link dialog is opened, the current table automatically becomes synchronized with the Link executable, that is, the table is read-only. The only time synchronization is lost for the current table, is when TTCN Link is activated in another table or when you insert a behaviour line from the Data Dictionary dialog in the current table.

The Link dialog has almost the same appearance as the Data Dictionary dialog. A list in the lower left corner of the dialog makes it possible to switch between the Link and Data Dictionary dialog. For more information about the Data Dictionary, see "Creating Behaviour Lines" .

The operations available in the Link dialog will be described below. The operations are applied on a selected behaviour line and the result is that a new behaviour line is inserted below/after. The test case or the test step must be empty or a leaf row must be selected.

The Send/Receive Tab

Generate a send statement by selecting a PCO, ASP/PDU, constraint, etc. When you press the Apply button, the statement will be verified by the selected SDL system. If the verification succeeds, a new send statement will be inserted below the selected behaviour line.

Figure 246 : Generating send statements

Generate receives and/or timeout statement(s) below the selected behaviour line by clicking the Generate Receives button. The new row(s) will all have the same indent level. This indent level will be increased compared with the previous one.

This operation is only valid when the current selected behaviour line is a leaf row.

For each retrieved receive statement from the SDL system, a new Constraint is generated if there is no appropriate constraint (a constraint with a similar value). The new constraint will be named with a unique name and will be analyzed. This new name is used in the Constraints Ref column.

The Timer Tab

Generate a timer statement by selecting Start or Cancel and a timer from the listbox (optional for Cancel). When you click the Apply button, the timer statement will be verified against the SDL system. If the verification succeeds, a timer statement will be generated and inserted below the selected behaviour line. The new behaviour line will have an increased indent level compared to the previous one.

Figure 247 : Generating timer statements

The Attachment Tab

When you select an attachment and click Apply, an attachment statement will be generated below the selected behaviour line. The new line will have an increased indent level compared to the previous one.

The selected test step (the behaviour lines in the behaviour description) will be verified with the SDL system. The test step must have passed analysis before this operation.

Note:

TTCN Link does not support attachment parameters.


Using Autolink

The generation of a TTCN test suite with Autolink proceeds in several steps.

Figure 248 : Test suite generation with Autolink

You start by specifying an SDL system, see "Specifying the SDL System and Performing Other Preparations" . Based on this SDL specification, you generate a Validator application which includes Autolink.

Next, you define MSC test cases, see "Defining MSC Test Cases" , which describe the purpose of the test cases of your test suite. They are stored on disk as system level MSCs, that is, MSCs with only one instance axis for the SDL system and one or more instance axis for the environment. Test cases may contain test steps which are stored as separate system level MSCs on disk.

You may also want to define an Autolink configuration, see "Defining an Autolink Configuration" , in order to guide the naming and parameterization of constraints. Autolink can also be configured to store test cases into a hierarchy of test groups.

The next step is to generate test cases, see "Translating MSCs into Test Cases" . This can be done either by a state space exploration of the SDL system or by directly translating system level MSCs into test cases. In any case, the result is an internal representation for each test case. At the same time, a list of constraints is generated. These constraints can be renamed and merged, see "Modifying Constraints" . You can also add new constraints manually.

Finally, you generate a TTCN test suite, see "Generating a TTCN Test Suite" , based on the test case representations and the list of constraints. The test suite is stored on disk in TTCN-MP format. On UNIX, you can import this file in the TTCN suite; in Windows, you can simply open it in the TTCN suite. On both platforms, you can convert the TTCN-MP file to the graphical TTCN format in the Organizer.

On the following pages, the steps will be described in more detail.

Specifying the SDL System and Performing Other Preparations

Before you start the Validator, directories must be created where you will store test case and test step representations. If there are no appropriate directories:

  • Create one directory for test cases and one directory for test steps in your working directory.

Specifying the SDL System

You have to specify an SDL system in order to create a Validator. At minimum, you must specify all channels to the environment of your system and all signals sent via these channels. With such a minimal specification, you can use Autolink to translate MSCs directly into TTCN by using the Translate-MSC-Into-Test-Case command. The advantages and disadvantages of using this command are described in "Translating MSCs into Test Cases" .

Generating and Starting a Validator

When you have specified the SDL system, you can generate and start the Validator. How to do this is described in "Generating and Starting a Validator" .

Specifying Directories

Before you start defining test cases and test steps, you have to specify where they are to be saved:

  1. In the Validator, select Autolink: Test Cases Directory from the Options2 menu.
    • This corresponds to the command Define-MSC-Test-Cases-Directory.
  2. In the dialog that will be displayed, select the test case directory that you previously created and click OK.
  3. Select Autolink: Test Steps Directory from the Options2 menu.
    • This corresponds to the command Define-MSC-Test-Steps-Directory.
  4. In the dialog that will be displayed, select the test step directory that you previously created and click OK.

When you later leave the Validator, you can save these values.

Defining MSC Test Cases

In Autolink, an MSC test case is derived from a path. A path is a sequence of events that have to be performed in order to go from a start state to an end state. There are two ways to define MSC test cases:

  1. Interactive simulation and manual specification
  2. Automatic computation by Autolink (see "Defining MSC Test Cases Automatically - Coverage Based Test Generation" )

Defining MSC Test Cases Interactively

The creation of MSC test cases by interactive simulation proceeds in several steps:

  1. Specify the start state of the test case.
    If this state is identical to the root of the behavior tree, nothing has to be done. Otherwise, you must navigate to the desired state, for example by using the Navigator, selecting a previously defined report or verifying an MSC. Then you set the root to the current state with the Define-Root Current command.

Note:

Autolink always considers the current root of the behavior tree to be the start state of a path.
Also note that when a test case is generated, the root has to be the same as it was at the moment of the test case definition. You have to keep track of the start state with Print-Path and Goto-Path, for example if you want to leave the Validator temporarily.

  2. Navigate through the system to the desired end state.
  3. Select MSC: Save Test Case from the Autolink1 menu.
    • This corresponds to the Save-MSC-Test-Case command.

An MSC test case consists of one instance axis for the SDL system and a separate instance axis for each channel to/from the environment. In TTCN terms, the single SDL system instance represents the System Under Test (SUT). The environment instances represent the Points of Control and Observation (PCO); PCOs are the interface between the test system and the SUT.

The system level MSC that will be saved contains the observable events of the path between the start and the end state. Observable events represent the external interaction that takes place between the SDL system and its environment. (During conformance testing, external interaction takes place between the implementation and the test system.)

Figure 249 shows an MSC test case.

Figure 249 : An MSC test case

Incorporating Test Steps in Test Cases

Typically, test cases are structured logically into several parts, for example a preamble, a test body and a postamble. These parts are called test steps. You may incorporate test steps in a test case by using MSC references.

Figure 250 shows an MSC with two MSC references. Each of the referenced MSCs represents a separate test step; they are called Preamble and Postamble.

Figure 250 : An MSC with a preamble and a postamble

Test steps are stored with the same file extension as test cases (.mpr). They are created in analogy to test cases with Save-MSC-Test-Step.

If you want to create a test case with a preamble and a postamble, several steps are necessary:

  1. Make sure that you have specified the directories for test cases and test steps as described in "Specifying Directories" .
  2. Set the root of the state space to the start state of the test case by using the command Define-Root Current.
  3. Navigate to the end of the path of the preamble.
  4. Use Save-MSC-Test-Step to save the preamble.
  5. Set the root of the state space to the current state by using the command Define-Root Current.
  6. Navigate to the end of the path of the test body.
  7. Use Save-MSC-Test-Case to save the test case/test body.
  8. Set the root of the space to the current state.
  9. Navigate to the end state of the test case.
  10. Use Save-MSC-Test-Step to save the postamble.
  11. Add two MSC references manually to the MSC test case with the MSC Editor.

Alternatively, you may create a single MSC test case and split the file into preamble, test body and postamble afterwards.

Test steps may refer to other test steps, but not to test cases. During test case generation, Autolink keeps track of the nested structure of test cases and test steps.

Note:

When Autolink generates test cases (see Generate-Test-Case and Translate-MSC-Into-Test-Case), the semantics of MSC references and MSC reference expressions are different from the semantics given in the ITU-T Recommendation Z.120!
Autolink requires that a test step is completely evaluated before the next test step starts, i.e. it synchronizes among references, whereas Z.120 considers MSC references as macros which do not have to be evaluated as a unit.
With regard to Figure 250, this means that all signals of the test body in mi_inres2 have to be evaluated before the postamble starts.

Using Timers

Autolink supports test suite timers. There are three types of timers which are commonly needed in test sequences:

  1. A global timer is specified to guarantee that test cases end even if they are blocked during execution due to an error. By default, Autolink generates a global timer T_Global automatically and starts it at the beginning of each test case. At the end of each test sequence, T_Global is cancelled. The automatic generation of timers can be enabled and disabled with the Define-Global-Timer command.
  2. A delaying timer is used to delay the sending of a signal from the tester to the SUT. This may be done for several reasons; for example, the sending is delayed on purpose to specify an invalid behavior of the environment.
  3. A guarding timer is used to check that the SUT sends a signal within a predefined amount of time.

Delaying and guarding timers have to be specified manually on the environment instances in test case MSCs. As an example, the MSC in Figure 251 contains a guarding timer T_Guard on instance ISAP1 and a delaying timer T_Wait on instance MSAP2.

T_Guard is set prior to sending a signal to the SUT and reset after the corresponding response from the SUT. If message ICONconf is received in time, test execution proceeds normally. Otherwise, a timeout of T_Guard will be caught in the Default Dynamic Behavior description and lead to a fail verdict.

The setting of timer T_Wait is followed immediately by a timeout event, causing the tester to delay the sending of message MDATreq.

.

Note:

Test suite timers are part of the environment of the SUT. Correspondingly, there is no explicit relation between these timers and any timers which might be used within the system. Autolink simply translates timer set events on environment instances into TTCN START operations, timer reset events into TTCN CANCEL operations and timeout events into TTCN TIMEOUT events. However, timer events on any MSC instance belonging to the SUT are not translated into TTCN statements.

Figure 251 : Test case MSC with guarding and delaying timer

Autolink creates timer declarations automatically from the information which it finds in the test case MSCs. From the MSC in Figure 251, Autolink generates a declaration for timer T_Guard with the default duration set to 10 and ms as unit. Correspondingly, the default duration for T_Wait is set to the test suite parameter PIX_Wait and its unit is set to ms as well. Autolink also generates a declaration for PIX_Wait.

This implicit declaration mechanism is convenient if the test suite consists of only one test case. If there are more test cases using timers, declaration conflicts may arise since timers are declared globally for the test suite. In order to solve this problem, Autolink provides the Define-Timer-Declaration command to explicitly declare test suite timers. Explicit timer declarations can not be modified by implicit declarations. It is therefore recommended to define all timer declarations explicate before test case computation starts. In that case, only the timer name must be provided for timer set events in the test case MSCs. The duration is optional (Autolink uses the duration value if it is not empty and different from the default duration specified in the declaration). Finally, the unit can be omitted from the test case MSCs if an explicit declaration exists.

The use of test suite timers and their declaration is explained in more detail in "Test Suite Timers" . With respect to timers, the TTCN output generated by Autolink depends on the test architecture. This is also discussed in "Test Suite Timers" .

Defining Multiple Test Cases by HMSC Diagrams

HMSC diagrams can be used to illustrate the relationship between various test cases. For example, even though test cases normally have different test purposes, they might share the same preamble and postamble. This commonness can be graphically expressed by the use of an HMSC diagram such as the one in Figure 252.

Note:

HMSCs are not supported by Generate-Test-Case but only by Translate-MSC-Into-Test-Case.

Figure 252 : Three test cases described by one HMSC diagram

When the HMSC Test is taken as input, Autolink will create three test cases which consist of the test steps Preamble/Valid/Postamble, Preamble/Invalid/Postamble and Preamble/Inopportune/Postamble.

The general interpretation of HMSCs can be described by a simple rule: Autolink generates a separate test case for each possible path through an HMSC. Of course, HMSCs may have more than one node with several outgoing edges, resulting in a potentially large number of test cases.

Note:

Autolink does not translate loops directly into equivalent constructs in TTCN. Instead it handles loops by unrolling. Therefore, you should not introduce loops in HMSC diagrams.

All test cases need to have unique names. With regard to the HMSC Test in Figure 252, the resulting test cases will be named Test_Valid, Test_Invalid and Test_Inopportune. Whenever there is a branch in the HMSC, the name of the succeeding MSC reference is postfixed to the name of the top-level MSC (separated by `_').

Describing Indeterministic Behaviour by Inline and Reference Expressions

Sometimes, a system under test may not behave deterministically. For example, there may be unpredictable failures. A tester should be able to handle such situations. By the use of inline expressions and MSC reference expressions, it is possible to describe test cases where the tester reacts flexibly depending on the system behaviour.

If some of your test cases only differ slightly at some point in the test case, you may also use inline and reference expressions to describe different behaviour of the tester. In that case, Autolink generates separate test cases.

Autolink supports the following operators in MSC expressions:

  • The alternative operator (alt) is suitable for the description of situations where the continuation of a test case depends on the former output of the system. If both alternatives start with a signal sent from the system to the tester (i.e. the environment), Autolink will generate two branches within a single test case.
    On the other hand, the operator may also be used to specify two alternative test sequences. If both alternatives start with a signal sent from the tester (environment) to the system, Autolink will generate two distinct test cases.
  • The optional operator (opt) can be used, e.g., to accept signals which may or may not be sent by the system or to react to unexpected signals in a way that the test case can be continued normally afterwards.
  • The exception operator (exc) is intended to be used for error handling. An exception expression may contain signals which prevent the test system from continuing the regular test execution. In MSC ConnectionRequest (Figure 253), the reception of signal IDISind immediately stops the test case. Optionally, an exception includes a sequence of signals which bring the system under test back into a stable testing state. An exception always results in an "INCONC" verdict.
  • The loop operator (loop) can be used to describe the iterative execution of a (portion of a) test case. As in HMSCs, Autolink does not translate loop expressions directly into equivalent constructs in TTCN. Instead, it handles loops by unrolling. If no upper loop boundary is given, the loop is evaluated up to three times.
  • Finally, the sequence operator (seq) can be used within reference expressions in order to state that one test step follows another.

Note:

Autolink does not support the parallel (par) and substitution (subst) operator within inline and reference expressions.

Figure 253 : Test case with exception handling

Of course, the usage of the different operators is not restricted to the applications described above. On the other hand, not all MSCs containing inline or reference expressions may describe sensible test cases.

Synchronization among MSC expressions

As mentioned before, Autolink synchronizes at the beginning and the end of MSC references. This modification of the semantics given in the MSC standard is motivated by the ability to consider separate MSCs as different test steps. If we cannot guarantee that all events in one MSC are evaluated before the next MSC is entered, we cannot draw a line between two subsequent test steps.

MSC reference expressions are a generalization of plain MSC references. Autolink generates distinct TTCN test steps for each of the MSCs involved in the expression. For that reason, it makes sense to synchronize at MSC references, too.

When it comes to inline expressions it is not really necessary to synchronize at their beginning and their end. However, for consistency Autolink synchronize at inline expressions, as well.

There are situations where synchronization among inline expressions is preferable, whereas in other cases the TTCN output and Autolink's error messages may be confusing.

In Figure 254, two examples are given. For MSC Sync1, Autolink will generate a test case where either ReceiveB or ReceiveC is anticipated before the test execution proceeds with SendD. If Autolink did not synchronize at the end of the alternative expression, SendD would be sent before ReceiveB (please note that Autolink prioritizes send events). Moreover, since both alternatives are combined in a single behaviour tree, SendD would erroneously become an alternative to ReceiveC!

Unfortunately, there are also cases where synchronization results in unexpected TTCN test cases. For the second MSC in Figure 254, Autolink will try to generate the following event tree:

Env1 ! SendA
  Env2 ? OptReceiveB
    Env1 ! SendC
      Env2 ? ReceiveD
  Env1 ! SendC
    Env2 ? ReceiveD

Of course, Autolink detects that there is a conflict among the two alternatives OptReceiveB and SendC and will print a warning.

Whenever Autolink issues a warning, you should carefully inspect your MSC test case definition. For example, when MSC Sync2 is interpreted as a test case, it is unclear how long a tester shall wait until it outputs SendC. On the other hand, if OptReceiveB is not logically caused by SendA or may received at any time, a possible solution would be to move SendC above the optional expression. In this case, no conflict arises.

Figure 254 : Synchronization among inline expression

Synchronizing Test Events with Conditions

The messages in MSCs are only partially ordered. If a test generation tool would generate all possible test sequences, then send events could appear as alternatives to receive events in TTCN test cases, making them indeterministic. To solve this problem, three solutions are possible:

  1. Events received by the tester are prioritized over events sent to the SUT.
  2. Events sent to the SUT are prioritized over events received by the tester.
  3. All messages in the MSC are evaluated from top to bottom. In that case, only one sequence of test events is generated.

The first alternative may lead to deadlocks and therefore it is not supported by Autolink. Alternative three may be selected with the Define-Autolink-Generation-Mode command.

By default, Autolink uses the second alternative and prioritizes events which are sent from the test system to the SUT over events which are received by the tester from the SUT.

Figure 255 : Synchronization example 1

However, there are situations where this "send immediately" strategy leads to incorrect test cases. Consider the following small example: A calls B, B accepts the call, then C tries to call B and gets a busy signal. A corresponding MSC test purpose description would look similar to the one in Figure 255. What test sequence will Autolink generate? First, the tester will send Request(B) to the SUT through PCO A. Next, Request(B) will be sent to the SUT through PCO C, since this is the next send event on any of the tester instances.

Figure 256 : Synchronization example 2

Most likely, this is not what you have anticipated intuitively; the tester should send the second Request(B) only after it has received Confirmation through PCO A. This is where explicit synchronization with conditions comes in. Figure 256 contains the same MSC as Figure 255, with a global condition added between the reception of Confirmation at PCO A and the sending of Request(B) through PCO C. If the Autolink synchronization option is turned on (with Define-Condition-Check), then events below the condition can only be executed if all events above the condition have been executed as well. The condition effectively becomes a synchronization point. In the example, the sending of Request(B) through C will be delayed until Confirmation has been received at PCO A. The name in the condition is required by the ITU Recommendation Z.120, however it is only considered as a comment and does not have any semantics.

.

Note:

The condition check option also applies to the MSC verification function of the Validator.

Listing and Clearing Test Cases and Test Steps

  • Use List-MSC-Test-Cases-And-Test-Steps for listing all MSC test cases and test steps that are defined in the current test cases and test steps directories.
  • Use Clear-MSC-Test-Case to delete an MSC test case.
  • Use Clear-MSC-Test-Step to delete an MSC test step.

Note:

Autolink distinguishes between the MSC test case name (which is the name of the system level MSC) and the name of the file on disk that contains the MSC test case. Usually, these names are identical except for the file extension.
When accessing the test cases and the test steps directory, Autolink always refers to the file names, meaning that you also have to specify the file extension (either .mpr or .msc)

Defining MSC Test Cases Automatically - Coverage Based Test Generation

One common method to generate a test suite is to select a number of test cases which, taken together, obtain a high coverage of the SDL specification. Ideally, this coverage should be 100%. In that case, every SDL symbol in the specification is executed at least once during test generation.

Autolink provides a special state space exploration technique, called Tree Walk, which is optimized for finding paths through the state space of the SDL specification that result in a high SDL symbol coverage. Tree Walk combines the advantages of both the depth-first and breadth-first search strategy - it is able to visit states located deep in the reachability graph and to find a short path to a particular state at the same time.

  • To use Tree Walk, apply the Tree-Walk command.

The execution of Tree Walk is controlled by two options:

  1. The maximum computation time (specified in minutes)
  2. The targeted coverage (specified in percent)

When Tree Walk is used, it generates a report for each sequence of transitions in the state space that increases the number of visited SDL symbols. These reports can be converted into system level MSCs with the command Save-Reports-as-MSC-Test-Cases.

Defining an Autolink Configuration

Autolink offers a special language for defining rules for the naming and parameterization of constraints, the introduction of test suite parameters and constants, and the distribution of test cases and test steps into test groups.

  • To specify Autolink configuration rules, use the command Define-Autolink-Configuration.

While it is possible to define an Autolink configuration on the fly at the Validator command prompt, it is better to write a command file which includes the configuration.

  • To load this file, use the Include-File command.
    The command corresponds to the menu choice Configuration: Load in the Autolink2 menu.
  • To remove a loaded configuration, use the Clear-Autolink-Configuration command.
  • To display the current configuration, use the Print-Autolink-Configuration command.
  • To save a configuration, use the Save-Autolink-Configuration command.

See also:

  • "Translation Rules" for an introduction to translation rules.
  • "Test Suite Structure Rules" for the methodology for test suite structure rules.
  • "Syntax and Semantics of the Autolink Configuration" for a detailed description of the configuration language.

Computing Test Cases

Once you have defined a set of MSC test cases, you can compute internal test case representations for each MSC test case.

  • To compute MSC test cases, use the Generate-Test-Case command.
    A bit-state exploration will be started which aims at finding all possible sequences of observable events that conform to the MSC. In addition, Autolink searches for inconclusive events. These are events that represent deviations from the behavior specified in the MSC test case, but which are valid alternatives according to the SDL specification.

Either a single test case or a set of test cases in the current test cases directory may be generated at the same time, depending on the parameter of Generate-Test-Case. If an already generated test case is regenerated, its former internal representation and its corresponding constraint definitions are replaced.

Note:

If the SDL specification is not detailed enough in the sense that it does not model the signal flow in a given MSC, the generation of the test case fails. MSCs which cannot be verified can still be converted into test cases with the Translate-MSC-Into-Test-Case command, which is described in "Translating MSCs into Test Cases" .
Inline expressions, MSC reference expressions and HMSC diagrams are not supported by Generate-Test-Case. (However, you can use these structural concepts for Translate-MSC-Into-Test-Case.) If you want to generate test cases based on HMSCs, you have to transform your HMSC diagrams into basic MSCs first. You can do this by verifying the HMSCs and saving all MSC Verification reports as MSC test cases (command Save-Reports-as-MSC-Test-Cases).

With complex systems, test generation may take a while. To avoid time-consuming test generation failures, you should verify all MSCs first.

  • To verify all MSC, use the Verify-MSC command.
    In most cases, MSC verification takes only a fraction of the time needed for test generation.

Listing and Clearing Generated Test Cases

  • You can list all generated test cases with the List-Generated-Test-Cases command.
  • You can clear all generated test cases with the Clear-Generated-Test-Case command.

Displaying and Saving the Internal Representation

  • You can display the internal representation of a generated test case - without having to save the test suite and start the TTCN suite - with the Print-Generated-Test-Case command.
  • You can save an internal test case representation with the Save-Generated-Test-Case command.
  • You can load an internal test case representation back into memory with the Load-Generated-Test-Cases command.

This makes it possible to distribute the generation of a set of test cases to several computers. When all test cases have been generated and saved in individual files, they can be reloaded on a single machine and saved as a complete test suite.

State Space Exploration Parameters

There are several parameters which influence the state space exploration:

  • You can set the maximum search depth with the Define-Autolink-Depth command (default value is 1000).
    If the search depth is set too low, this may result in incomplete pass paths. Since the maximum search depth normally has no impact on the performance of the state space search, it is recommended that you always use a large value (> 1000).
  • You can resize the hash table with the Define-Autolink-Hash-Table-Size command (default size is 1,000,000 bytes).
    Increasing the hash table size may be necessary if the SDL system is rather complex.
  • Normally, Autolink changes the regular Validator state space options, because the default values of the Validator are not sufficient for generating correct test cases.
    For example, for the Inres protocol specification, the following commands are issued:
Define-Scheduling All
Define-Transition Symbol-Sequence
Define-Symbol-Time Zero
Define-Priorities 2 1 3 2 2
Define-Channel-Queue ISAP1 On
Define-Channel-Queue MSAP2 On
Define-Max-Input-Port-Length 10

Other SDL systems require different Define-Channel-Queue commands.
Autolink automatically resets the original options when a test case generation is finished. Therefore, previously defined reports are still valid (unless they were generated by verifying an MSC).
If you do not want to use the default settings for any reason, use the Define-Autolink-State-Space-Options Off command. This disables the automatic setting of Autolink's default options.

Test Case Generation Messages

After the generation of a test case, some warnings or error messages may be displayed:

  • Error: Autolink did not find any complete pass paths. No test case is generated.
    This message appears if no final TTCN pass verdict has been assigned to any event in the internal test case representation.
    The most common reason for test generation failure is that the MSC does not describe a valid trace of the SDL system. Hence, before running Autolink, you should check that the MSC test case can indeed be verified using command Verify-MSC.
    The error message above may also appear if the maximum search depth is set too low. Check the state space exploration statistics which are displayed by Autolink at the end of the test case generation. If the number of truncated paths is greater than zero, you should increase the maximum search depth. The required value for the search depth depends both on the length of the test case and on the selected state space options of the Validator.
    Autolink may also fail if you do not specify the signal parameters in the MSC test cases, but instead use global test values. Make sure that at least all signals sent into the system are fully specified in the MSC.
  • Warning: Incomplete pass path found. The first event X on the incomplete branch
    gets an 'INCONC' verdict.
    This message is displayed if a path in the state space is pruned before a final TTCN pass verdict has been assigned to an observable event. (Note that in this context a pass path refers to the internal test case representation whereas otherwise, a path refers to the state space of the SDL system.) If this happens, the first event X of the incomplete subtree is reassigned as a TTCN inconc verdict, and the rest of the subtree is discarded.
    The reasons for a pass path being pruned are numerous. The system level MSC may not be verifiable, for example if the state space is too restricted, or there may be a path in the state space of the SDL system that only partially verifies the MSC. A common problem is the maximum search depth being too low (see above).
  • Warning: Alternative events found for send event.
    Inconclusive events are deleted.
    For test generation, it is assumed that signals which can be sent to the system are sent instantaneously. Therefore, alternatives to send events are not desired.
    With the default options of Autolink, this message should not appear. If you use your own Autolink options, check whether Input from ENV has the highest priority. To correct the problem, you should use the Define-Priorities command with parameters X1 1 X2 X3 X4, where X i > 1.
  • Warning: No translation rule can be applied to the following signal: <Signal Name>
    If you define an Autolink configuration containing translation rules, Autolink assumes that you want to map all SDL signals onto constraints with the help of user-defined rules. Hence, you will be warned if there is a signal in a test case to which no translation rule can be applied.
  • Warning: There are events following an event with final `PASS' verdict.
    When the MSC test case has been simulated completely, the SDL system was not yet in a stable state. Instead, it sent out one or more additional signals which were not specified in the MSC test case. You should carefully review your test specification, since during a test campaign you may not be able to successfully execute another test case after the execution of the faulty test case.

Translating MSCs into Test Cases

If an SDL system is not fully specified, some or all MSCs may not be converted into test cases if you use the Generate-Test-Case command. Instead, you can use the Translate-MSC-Into-Test-Case command to translate MSCs directly into the same internal test case format which is used for test cases generated by state space exploration. Therefore, you can use all commands related to listing, displaying, removing, saving and loading of test cases (introduced in "Computing Test Cases" ) with directly translated test cases as well.

Furthermore, all rules for constraint naming (see "Translation Rules" ) and test grouping (see "Test Suite Structure Rules" ) apply to translated test cases, too.

Note:

Since the translation of MSCs into test cases does not perform a state space exploration, there is no guarantee that the MSCs and hence the test cases describe valid traces of the specification or the implementation, respectively. Instead, the validity of the test cases has to be assured by the developer. Furthermore, no inconclusive events can be computed during MSC translation. Therefore, the resulting test cases return a fail verdict for any deviation from the behavior described in the MSC.

Either a set of test cases in the current test cases directory or just a single one may be translated at the same time, depending on the parameter of Translate-MSC-Into-Test-Case. If an already translated test case is retranslated, its former internal representation and its constraint definitions are replaced.

Two different algorithms are available for MSC translation: With the Define-Autolink-Generation-Mode command, you can choose the semantics used to interpret MSCs during translation. By default, Autolink uses the standard semantics of MSC. If the generation mode is set to "total ordering", then the sequence of input and output events in the MSC is determined straight from top to bottom. If there are two events on different environment instances, Autolink evaluates the event which is closest to the top of the MSC first.

Note:

For test generation with state space exploration (using the Generate-Test-Case command), total ordering is not supported.

MSC into TTCN Translation Messages

After the generation of a test case, some warnings or error messages may be displayed:

  • Error: No test case could be generated.
    Please check whether the MSC contains separate instance axes for each channel to the environment.
    The Translate-MSC-Into-Test-Case command does not support the translation of MSCs with only one instance axis for the environment. Use MSCs with a separate instance axis for each channels to the environment (i.e. for each PCO).
  • Warning: No translation rule can be applied to the following signal: <Signal Name>
    If you define an Autolink configuration containing translation rules, Autolink assumes that you want to map all SDL signals onto constraints with the help of user-defined rules. Hence, you will be warned if there is a signal in a test case to which no translation rule can be applied.

Modifying Constraints

It is highly recommended that you specify constraints naming and parameterization rules in an Autolink configuration file. Otherwise, a generic name of the form <Test case name>_<three digit number> is assigned to each constraint during test case generation. However in the latter case, you will probably find it useful to modify the constraints generated by Autolink.

  • Use the Rename-Constraint command to change the name of a constraint.
    Besides renaming a constraint, it is also possible to merge two constraints. Do this by giving a constraint the same name as another one. Then you will have to select which of the two signal definitions should be kept (unless they are identical). There is one restriction: Constraints with formal parameters cannot be overwritten by other constraints.
    See also "Translation Rules" .
  • Use the Merge-Constraints command to merge two constraints by potentially introducing formal parameters.
    If the original constraints are used in test cases, their constraint references will be updated. This means that the concrete signal parameters (which were replaced by formal parameters) will be moved to the constraint references.

Note:

If you rename a constraint or merge two constraints, the internal test case descriptions are updated, too. The links between the events in the test cases and their corresponding constraints remain consistent.

  • Use the Define-Constraint command to add new constraints to the current list of constraints.
    If a constraint with the same name but a different signal definition already exists, you will have to choose what to do - rename the new constraint, overwrite the old constraint or remove the new definition.
  • Use the Parameterize-Constraint command to replace concrete signal parameter values in a constraint by formal (symbolic) parameters. If the parameterized constraint is used in a test case, the parameter value is not lost, but maintained in the constraint references of the referring test cases instead.
  • Use the Clear-Constraint command to delete a constraint.
  • Use the List-Constraints command to list all currently defined constraints.
  • Use the Save-Constraint command to save one or all constraints.
  • Use the Load-Constraints command to reload saved constraints.

Generating a TTCN Test Suite

  • Use the Save-Test-Suite command to save a test suite in a TTCN-MP file.
    The internal representations of the test cases will be kept in memory in order to allow you to save test suites in different formats.
  • There are two fundamentally different formats to save test suites: "Traditional" TTCN and concurrent TTCN. To switch between these formats, use the Define-Concurrent-TTCN command. For a detailed description of the concurrent TTCN format, see "Concurrent TTCN" .
  • By default, constraints are stored as ASN.1 ASP constraints, but before you generate a test suite, you may change an option to have them stored as ASN.1 PDU constraints instead. To do this, use the Define-TTCN-Signal-Mapping command. You are also allowed to select the correct type of constraint for each signal individually by adding rules to an Autolink configuration (see "Defining ASP and PDU Types" ).
  • There are three possible output formats for test steps. Use the Define-TTCN-Test-Steps-Format command to select an output format:
    • One possibility is to store the test steps of a single test case as local trees. If a test step is used several times, only one behavior description is generated.
    • Test steps can also be stored globally in the test step library. If a test step is used several times in different test cases, only one behavior description is generated.
    • A third alternative is to generate "flat" test cases by including the events of the test steps directly in the test case dynamic behavior descriptions. In this case, no information about test steps is put into the TTCN test suite.

Note:

A test step that is used in several places may lead to trees with different inconclusive events or different verdicts. In this case, they will be given new, unique names.

Preliminary Pass Verdicts

Test cases that are structured into preamble, test body and postamble will automatically be assigned preliminary pass verdicts at the end of the test body. However, test cases can contain an arbitrary number of MSC references (and hence test steps). Therefore, preliminary pass verdicts will be assigned to all events that are directly followed by the last top-level MSC reference in the test case. The preliminary pass verdicts will only be assigned if no event follows the last MSC reference. The event to which a preliminary pass verdict is assigned may appear within the test body as well as within a test step.

Test Suite Generation Messages

During the saving of a test suite, some warnings or error messages may be displayed:

  • Warning: Test step <TS> resulted in different trees.
    The trees are renamed to `<TS>_1', `<TS>_2', etc. in the test suite.
    If an MSC test step is reused in several test cases, the resulting TTCN test steps may be different. Typically, this warning appears if a test step is used as a preamble in one test case and then again as a complete test case by itself. In the latter case, a final pass verdict is assigned to the test case, while in the former one it is not.
  • Warning: No test suite structure rule defined for test case/step `<TestCaseName/TestStepName>'.
    If you define an Autolink configuration containing test suite structure rules, Autolink assumes that you want to place all test cases/steps in test groups defined by the test suite structure rules. Hence, you will be warned if there exists a test case/step to which no rule can be applied.
  • Warning: Test suite parameter/constant `<Name>' is not unique.
    It is renamed to `<Name>_1', `<Name>_2', etc. in the test suite.
    By using translation rules (see "Translation Rules" ) you can introduce test suite parameters and constants. These parameters and constants are checked for consistency in a similar way as test suites. With the warning above, Autolink informs you that it had to rename test suite parameters/constants in order to resolve naming conflicts.

Translation Rules

In "Modifying Constraints" , you have learned how to change constraints. However, assigning sensible names to automatically generated constraints is a tedious task. Especially if you have to refine the SDL specification and then to repeat the test generation process, there is a lot of manual work. Moreover, the number of generated constraints may become very large if you do not use constraint parameterization.

In order to address these problems and some additional issues, you can specify so-called translation rules. These rules control the look of a test suite with regard to the following items:

  1. Naming of constraints
  2. Parameterization of constraints
  3. Replacement of signal parameter values by wildcards in a constraint declaration table
  4. Introduction and naming of test suite parameters and test suite constants

Translation rules build one integral part of an Autolink configuration (see also "Test Suite Structure Rules" ). Before you start the test generation, you can develop an Autolink configuration file that contains a Define-Autolink-Configuration command. The set of translation rules which tell Autolink how to construct constraints and treat parameters for particular signals, are provided as a kind of long parameter to this command.

For some examples, see "Examples of Translation Rules" . More information can be found in "Defining an Autolink Configuration" and "Syntax and Semantics of the Autolink Configuration" .

Examples of Translation Rules

A typical translation rule may look like this:

Example 256

TRANSLATE MDATind
CONSTRAINT NAME "C_" + $0
PARS $1="Type"
END

Example 256 explains how signal MDATind is translated into an suitable TTCN constraint. The rule above states that the name of a constraint for signal MDATind consists of the concatenation of text "C_" and the "nullth" parameter - which is the name of the signal itself. Therefore, signal MDATind is translated into a constraint called C_MDATind.

Additionally, the first parameter of the signal (referred to by $1) becomes a parameter of the constraint. The name of the formal parameter is Type. It is printed both in the Constraint Name line and the Constraint Value section of the constraint declaration table. The actual parameter of the constraint is printed in the dynamic behavior table of each test case that uses this constraint.

A constraint declaration table for signal MDATind is shown in Figure 257.

Figure 257 : A constraint declaration with a formal parameter

It is also possible to define a single translation rule for more than one signal. This is especially useful if similar signals exist which can be treated in the same way.

Example 257

TRANSLATE MDATind | MDATreq
CONSTRAINT NAME "C_" + $0
PARS $1="Type"
END

If either MDATind or MDATreq is identical to the signal for which a constraint is to be created during test generation, the rule in Example 257 is applied. The value of $0 depends on the name of the actual signal investigated at run-time. Since the first signal parameter is always to be replaced by the formal parameter Type, the rule is only valid if each of the alternative signals, i.e. MDATind, and MDATreq, has at least one parameter. When parsing an Autolink configuration, all translation rules are checked automatically for validity.

Constraint names may not only be based on texts and signal names. They can also depend on signal parameters. In a translation rule, a signal parameter is referred to by its number, prefixed with a dollar character ($). (Note that Autolink only supports parameters on the top level - it is not possible to refer to a component of a nested parameter.)

In some cases, it is not desirable to use the value of a signal parameter directly as part of a constraint name. For example, a protocol engineer might encode complicated signal information with abbreviations or numbers. But for the TTCN output, parameter values should be mapped onto more meaningful expressions.

Therefore, you may define functions which take an arbitrary number of parameters and map them onto text. In Example 258, the value of the first parameter of signal MDATind is passed to function PDUType. Depending on the concrete parameter value, which occurs during test case generation, the function returns a text. This text forms the second part of the constraint name.

Example 258

TRANSLATE MDATind
CONSTRAINT NAME "Medium_" + PDUType($1)
END

FUNCTION PDUType
$1 == "CR" : "Ind_Connection_Request"
| $1 == "AK" : "Ind_Acknowledge"
| $1 == "DR" : "Ind_Disconnection_Request"
| TRUE : "Indication"
END

Note:

In a translation rule, $i refers to the i-th parameter of the signal for which a constraint is created. However in a function, $i denotes the i-th parameter which was passed to the function.

You may define complex rules whose evaluation is guarded by conditions. This is illustrated in Example 259.

Example 259

TRANSLATE "MDATind"
IF $1 == "CR" THEN
CONSTRAINT NAME "Medium_Connection_Request"
END
IF $1 == "AK" AND $2 == "zero" THEN
CONSTRAINT NAME "Medium_Acknowledge_Zero"
END
CONSTRAINT NAME "Medium_Indication"
PARS $1="Type"
END

Conditional translations can be defined by IF-statements. Only if the condition(s) following the IF keyword is/are satisfied, the constraint is built according to the subsequent specification. A translation rule can contain several IF-clauses. The first clause which condition is satisfied (or which does not have an IF statement at all) is chosen for translation.

In the example above, signal MDATind is translated into a constraint called Medium_Connection_Request if the first signal parameter equals CR, and to a constraint called Medium_Acknowledge if the first two signal parameters equal AK and zero respectively. If neither condition is satisfied, the unconditioned section is evaluated. In this case, a constraint with name Medium_Indication and formal parameter Type is created. Note that the parameter definition is not taken into account if any of the former IF-conditions is satisfied!

Sometimes, it is useful to indicate that a specific signal parameter is irrelevant. For example, assume that if the first parameter of signal MDATind is CR, the values of the second and third parameter can be ignored. Hence, you can replace them by wildcards in a constraint table. In Example 260, a MATCH statement is added that tells Autolink to replace the values of the signal parameters 2 and 3 by asterisks. The resulting constraint table is displayed in Figure 258.

Example 260

TRANSLATE "MDATind"
IF $1 == "CR" THEN
CONSTRAINT NAME "Medium_Connection_Request"
MATCH $2="*", $3="*"
END
CONSTRAINT NAME "Medium_Indication"
PARS $1="Type"
END

Note:

The application of TTCN matching mechanisms is only valid for receive events. Hence, you are not allowed to apply the MATCH statement to signals that become send events in TTCN.

Figure 258 : A constraint table with TTCN matching expressions

Translation rules also allow to introduce test suite parameters and constants. Test suite constants are useful if a concrete parameter value does not give any clues about its meaning and hence should be replaced globally by a more meaningful name. Test suite parameters should be introduced if signal parameter values are implementation dependent. By defining a test suite constant/parameter, a concrete signal parameter value in a constraint table is replaced by a symbolic constant. The assignment of concrete values to symbolic test suite constants/parameters is made in additional TTCN tables which are created automatically by Autolink.

Example 261 illustrates the use of test suite parameters and constants. If the condition is satisfied, the second signal parameter is replaced globally by SeqNo in the TTCN test suite. The third signal parameter is replaced by a test suite parameter called DataValue. This parameter refers to PICS/PIXIT proforma entry PICS_Data.

If signal MDATreq has not been used for data transfer, the value of the first signal parameter is replaced by a test suite constant which name is based on the concrete signal parameter value. A constraint table and an according constant table for this case is shown in Figure 259 and Figure 260.

Example 261

TRANSLATE "MDATreq"
IF $1 == "DT" THEN
CONSTRAINT NAME "Medium_Req_Data_Transfer"
TESTSUITE CONSTS $2="SeqNo"
PARS $3="DataValue" / "PICS_Data"
END
CONSTRAINT NAME "Medium_Req_" + PDUType($1)
MATCH $3="*"
TESTSUITE CONSTS $1=PDUType($1)
END

FUNCTION PDUType
$1 == "CC" : "ConConf"
| $1 == "AK" : "Acknowledge"
| $1 == "DR" : "DisconRequest"
| $1 == "DT" : "DataTransfer"
| $1 == "CR" : "ConRequest"
END

Figure 259 : A constraint table with a test suite constant

Figure 260 : A TTCN table for test suite constant declarations

An Autolink configuration typically consists of a large number of translation rules which are evaluated from top to bottom. If a constraint cannot be constructed based on the given rules, a generic name will be assigned to the constraint, in the same way as when no translation rules are defined.

Test Suite Structure Rules

In TTCN, test cases can be combined in test groups. Each test group aims at testing the system under test for one particular aspect. Test groups again can be part of other higher level test groups, resulting in a hierarchy of test groups.

Test steps can be put into test groups as well. In the following, test cases and test steps will not be distinguished, as test structure rules apply to both.

When you start designing a test suite, you should have a clear notion of what the structure of the test suite will be. In fact, for successful test suite development, it is important to first determine what should be tested and how the tests can be classified, before individual test cases are specified.

If you use Autolink for test generation, the test cases are described by MSCs. Ideally, the names of the MSCs should give information about the structure of the resulting test suite. Because of this, you may specify rules for the automatic placing of test cases in different test groups, depending on the names of the corresponding MSCs. These test suite structure rules prevent you from repeating a lot of manual work if you regenerate the test suite due to a modification of the underlying SDL specification. Moreover, test suite structure rules (TSS rules) also save you a lot of work if you create a test suite only once, since a single rule can be applied to several test cases. As will be shown in the example below, one rule may be enough to describe the structure of a complete test suite.

Test suite structure rules are part of an Autolink configuration. Before the test generation starts, you can write an Autolink configuration file which contains a Define-Autolink-Configuration command. The TSS rules are provided as a kind of long parameter to this command.

For details on the Autolink configuration commands see "Defining an Autolink Configuration" . A precise description of the Autolink configuration language is given in "Syntax and Semantics of the Autolink Configuration" .

Examples of Test Suite Structure Rules

In the following, it is assumed that you want to create a test suite in which test cases can be classified according to three different criteria. On the top level, tests can be distinguished by whether they are related to mandatory or optional capabilities. On the next level, tests may focus on particular protocol phases, for example connection establishment, data transfer and disconnection. Finally, valid, invalid or inopportune behavior may be displayed. A resulting test suite should have the following structure:

Mandatory
Connection
Valid
Invalid
Inopportune
DataTransfer
Valid
...
Disconnection
...
Optional
...

It is further assumed that having this structure in mind, you have created MSC test cases with the following names:

V_Con_Man_01
V_Dis_Man_01
IV_Data_Man_01
IO_Data_Opt_01
IO_Data_Opt_02

MSC test cases that belong to the same test group are numbered sequentially.

Now, a simple TSS rule for the scenario above may look like this:

Example 262

PLACE V_Con_Man_01
IN "Mandatory" / "Connection" / "Valid"
END

Example 262 states that test case V_Con_Man_01 is intended to be placed in the test group Valid. Since this test group is placed in another test group (Connection), you have to specify the complete path, composed of all groups in hierarchical order. The names of the test groups are separated by a slash (`/') in analogy to the notation of test group references in the TTCN standard.

If you want to place several test cases in the same test group, you can use the alternative operator (`|') in the header of a TSS rule:

Example 263

PLACE IO_Data_Opt_01 | IO_Data_Opt_02
IN "Optional" / "DataTransfer" / "Inopportune"
END

Example 263 places both IO_Data_Opt_01 and IO_Data_Opt_02 in test group Optional/DataTransfer/Inopportune.

Rules like the one shown in Example 262 and Example 263 can be applied to MSC test cases with arbitrary names. In the best case, you have to write one TSS rule for each test group.

However, there is a direct relation between the MSC names and the test groups. For example, the two characters IO at the beginning of an MSC name indicate that the corresponding test case has to be placed in a test group called Inopportune. Using this information, the number of TSS rules can be further reduced as explained below.

You are allowed to use patterns in the header of a test suite structure rule. The following characters have a special meaning when used in the header:

  • `*' matches zero or more arbitrary characters.
  • `?' matches exactly one arbitrary character.
  • "[...]" matches any single character in the enclosed lists. In order to represent characters ranges, you can type two characters separated by a dash (`-'). For example, "[a-z]" denotes an arbitrary lowercase letter. If the first character is a `!', any character not enclosed is matched.

Note:

Patterns can also be used in a similar way in the header of translation rules. This is useful if signals with similar names are to be treated equally.

Now consider the following complex rule and its auxiliary functions:

Example 264

PLACE "*" + "_" + "*" + "_" + "???" + "_" + "*"
IN OptMan( @5 ) / Phase( @3 ) / Behavior( @1 )
END

FUNCTION OptMan
$1 == "Opt" : "Optional"
| $1 == "Man" : "Manual"
END

FUNCTION Phase
$1 == "Con" : "Connection"
| $1 == "Data" : "DataTransfer"
| $1 == "Dis" : "Disconnection"
END

FUNCTION Behavior
$1 == "V" : "Valid"
| $1 == "IV" : "Invalid"
| $1 == "IO" : "Inopportune"
END

With the rule in Example 264, all test cases can be placed in their appropriate test groups.

When a test suite structure rule is evaluated, it is first checked whether one of the terms following the keyword PLACE (which are separated by `|') equals the name of the investigated test case. In the rule above, there is only one term consisting of 7 parts, called atoms. These atoms are concatenated by the `+' operator.

While Autolink simply has to compare strings in Example 262 and Example 263, it has to find out whether a concrete test case name matches the pattern in Example 264. If the test case name matches the pattern, the atoms in the header of the TSS rule are instantiated.

If, for example, the rule is applied to test case IO_Data_Opt_01 at run-time, the first atom (originally `*') is set to "IO". The value of the third atom becomes "Data", the value of the fifth atom becomes "Opt" and the value of the seventh atom becomes "01". The second, fourth and sixth atom remain unchanged as they do not contain any special characters.

In order to refer to the value of an atom in the rule header, you can use the "at" operator (`@'). For example, "@5" refers to the value of the fifth atom.

Additionally, you may define functions which map parameters onto texts. In Example 264, "@5" is passed to function OptMan. Depending on the concrete parameter value which is passed at run-time, the function returns either the text "Optional" or "Manual" (or an error message if the first function parameter is neither "Opt" nor "Man").

An Autolink configuration typically consists of a number of TSS rules which are evaluated from top to bottom. If a test case or a test step cannot be placed in a test group based on the given rules, Autolink places it on top-level and prints an error message. In this case, you can modify your rules, reload them and apply the Save-Test-Suite command again.

Defining ASP and PDU Types

When Autolink produces a TTCN test suite it creates several tables in the declarations part. These tables store information about sorts, ASN.1 data types and signal definitions used in the SDL system. By default, Autolink applies the following rules:

  1. SDL sort definitions are mapped onto ASN.1 type definitions.
  2. ASN.1 data types defined externally in an ASN.1 module are listed as ASN.1 type definitions by reference in TTCN.
  3. SDL signal definitions become ASN.1 ASP type definitions. As a consequence, if a signal is used in a test case, its corresponding TTCN constraint is stored in an ASN.1 ASP constraint table.

Very often, this mapping is too strict. For example, during test execution a tester may exchange both Abstract Service Primitives (ASPs) and Protocol Data Units (PDUs) with the system under test. If you want to store constraints as ASN.1 PDU constraints, you may use Define-TTCN-Signal-Mapping with parameter PDU. However, in this case all signals are considered to be PDUs. Moreover, this command does not apply to SDL sorts and ASN.1 data types.

In order to specify the correct for each different type of information, Autolink provides two commands in its configuration language. These commands start with either the keyword ASP-TYPES or PDU-TYPES. You can use them to declare single signals and sorts as ASPs and PDUs.

Example 265

ASP-TYPES
"ICONreq" , "ICONconf", "IDATreq"
END

PDU-TYPES
"pdu*"
END

In Example 264, three SDL signals, namely ICONreq, ICONconf and IDATreq are specified as ASPs. The second rule states that all signals and sorts whose name starts with "pdu" shall be considered to be PDUs. If constraints with corresponding types are used, they are stored as PDU constraints as well.

Stripping signal definitions

When it comes to the automatic generation of TTCN test suites, one of the drawbacks of SDL is that any data which is exchanged between a system and its environment has to be encapsulated in signals. Especially, if your SDL specification makes use of ASN.1 data types, this restriction imposes a redundant embedding. On the other hand, the concept of signals does not exist in TTCN. Instead, common data values can be sent and received directly. For that reason, Autolink allows to strip signals.

Consider a signal type defined as MDATreq( PDUType ). If a signal of this type is used in a test case, say MDATreq( { CC } ), then Autolink will generate a constraint of type MDATreq. However, what you may want to generate is a constraint of type PDUType, i.e. the signal should be stripped from its parameter.

Example 266

STRIP-SIGNALS
"MDATreq"
END

PDU-TYPES
"PDUType"
END

Example 266 presents a short Autolink configuration statement that tells Autolink to unwrap the signal parameter when generating constraints that are related to signal MDATreq in the SDL specification.

Please note that signal stripping can only be applied to signals that have exactly one parameter! Moreover, the embedded parameter must be declared either as PDU or as ASP. If these conditions do not hold, Autolink refuses to strip the signal and issues a warning. If a signal can be stripped successfully, no declaration is generated for it in the TTCN declaration part, since it is not used in the constraints part.

Syntax and Semantics of the Autolink Configuration

Autolink Configuration

The definition of an Autolink configuration is started with the keyword Define-Autolink-Configuration and is terminated with End. It consists of an arbitrary sequence of five different kinds of statements: Translation rules, test suite structure rules, ASP/PDU type rules, signal stripping rules and functions.

Example 267 : Syntax of Autolink configuration

<Start> ::= "Define-Autolink-Configuration"
<Configuration>
"End"
<Configuration> ::= { <TransRule> | <TSStructureRule> |
<ASPTypesRule> | <PDUTypesRule> |
<StripSignalsRule> | <Function> }*

Note:

If you want to define both translation rules and test suite structure rules, you have to place them in the same configuration definition.

Rules and functions can be arbitrarily mixed in a configuration. There is no need to place rules on top of a file, nor do you have to write forward declarations for functions.

Note:

Autolink analyzes translation rules and test suite structure rules in the order they have been defined. As a consequence, the order of the definitions is crucial if several rules can be applied.

Translation Rules

Translation rules are evaluated whenever a constraint is created during test case generation.

A translation rule starts with the specification of the names of the signals to which it shall apply (denoted by <AlternativeListOfTerms>).

Example 268 : Syntax of translation rules

<TransRule> ::= "TRANSLATE"
[ "SIGNAL" ] <AlternativeListOfTerms>
<TransRuleIf>* [ <TransRuleNoIf> ]
"END"
<TransRuleIf> ::= "IF" <Conditions> "THEN"
<TransRuleNoIf> "END"
<TransRuleNoIf> ::= { "CONSTRAINT" <TransRuleConstraint> |
"TESTSUITE" <TransRuleTestSuite> }*
<TransRuleConstraint> ::= { "NAME" <Term> |
"PARS" <ParameterList1> |
"MATCH" <ParameterList1> }*
<TransRuleTestSuite> ::= { "CONSTS" <ParameterList1> |
"PARS" <ParameterList2> }*
<ParameterList1> ::= <Parameter1> { "," <Parameter1> }*
<Parameter1> ::= "$" <Number> [ "=" <Term> ]
<ParameterList2> ::= <Parameter2> { "," <Parameter2> }*
<Parameter2> ::= "$" <Number> [ "=" <Term> ]
[ "/" <Term> ]

As sketched in the example section, translations can be made dependent on one or more conditions. Hence, the body of a translation rule may consist of one or more statements embedded by IF ... THEN ... END constructs. The first group of statements whose preceding conditions are satisfied (or which do not have an IF statement at all) is evaluated. All subsequent definitions are ignored. If no conditions hold for a given signal, Autolink looks for another translation rule which fits the signal.

There are two groups of directives starting with either the keyword CONSTRAINT or TESTSUITE.

In the CONSTRAINT part you can specify the name (keyword NAME) and the formal parameters of a constraint (keyword PARS) for one or more given signals. Additionally, you can tell Autolink to replace signal parameter values by a TTCN matching mechanism (keyword MATCH). Please note that Autolink does not perform any checks concerning matching mechanisms at run-time. It simply handles it as a textual replacement.

In the TESTSUITE part, you can specify that parameter values of a signal are replaced by test suite parameters and constants. The declaration of constants is preceded by the keyword CONSTS, test suite parameter are introduced with PARS.

It is possible to declare a constraint parameter and a test suite constant/parameter for the same signal parameter. However, Autolink ensures that a signal parameter is not mapped onto a test suite constant and parameter at the same time.

There exist several default values that are used when an optional parameter is not specified:

  • The default name of a constraint is defined by the term 'c' + $0, i.e. the signal name is prefixed by a 'c'.
  • The default name of a constraint parameter is constructed by "Par" + <SignalNumber> (e.g. Par3 for the third parameter).
  • If a signal parameter is specified after MATCH, but no term is given, its values is replaced by `*' in the constraint table.
  • The default name of a test suite constant is "TestSuiteConst".
  • The default name of a test suite parameter is "TestSuitePar".
  • By default, there is no PICS/PIXIT reference.

If there are name clashes, test suite constants and parameters are treated similar to constraints and test steps. That means, if there are two constants with the same name but different values, they are distinguished by a sequence number.

Test Suite Structure Rules

Test suite structure rules are similar to translation rules. They share most of the basic concepts, for example terms, functions and conditions. However, while translation rules are applied during test case generation, TSS rules are evaluated when you save a test suite with the Save-Test-Suite command.

A test suite structure rule starts with the specification of the names of the test cases to which it shall apply (denoted by <AlternativeListOfTerms>).

Conditions can be used in the same way as in translation rules: The first IN statement whose preceding conditions are satisfied (or which is not embedded in an IF ... THEN ... END statement at all), is taken into account. All subsequent statements are ignored. If no conditions hold for a given test case/step, Autolink looks for another TSS rule that fits the test case/step.

Example 269 : Syntax of test suite structure rules

<TSStructureRule> ::= "PLACE" <AlternativeListOfTerms>
<TSStructureRuleIf>*
[ <TSStructureRuleNoIf> ]
"END"
<TSStructureRuleIf> ::= "IF" <Conditions> "THEN"
<TSStructureRuleNoIf> "END"
<TSStructureRuleNoIf> ::= "IN" <Term> { "/" <Term> }*

Declaring ASP and PDU Types

The rules to declare ASP and PDU types are evaluated when a TTCN test suite is saved on disk with the Save-Test-Suite command. Please note that each of the rules can only be defined once in an Autolink configuration. However, this is no restriction as you can specify an arbitrary number of signals and sorts in both rules.

Example 270 : Syntax for declaring ASP and PDU types

<ASPTypesRule> ::= "ASP-TYPES" <SequentialListOfTerms> "END"
<PDUTypesRule> ::= "PDU-TYPES" <SequentialListOfTerms> "END"

Stripping Signals

Rules for stripping signals are evaluated closely coupled with the rules above for declaring ASP and PDU types. Autolink only strips a signal if its only parameter is declared as ASP or PDU. Autolink only accepts one stripping rule in a configuration.

Example 271 : Syntax for stripping signals

<StripSignalsRule> ::= "STRIP-SIGNALS" <SequentialListOfTerms>
"END"

Functions

Functions are identified uniquely by their names. If there are two functions with exactly the same name, the one defined first is always evaluated.

Functions are visible globally, that is, they can be called by any constraint or test suite structure rule and other functions. References to functions are resolved at run-time. If there is a call to an unknown function, the text "FunctionXXXNotFound" is returned.

Example 272 : Syntax of functions

<Function> ::= "FUNCTION" <Identifier> <Mappings> "END"
<Mappings> ::= <Mapping> { "|" <Mapping> }*
<Mapping> ::= <Conditions> ":" <Term>

A function body consists of a number of mapping rules separated by `|'. Mapping rules specify the possible return values of a function. A mapping is performed if its corresponding condition(s) hold. Mappings are evaluated from top to bottom. If the conditions of all mappings fail, a function returns the text "NoConditionHoldsInFunctionXXX".

Function parameters can be accessed in the same way as signal parameters in a translation rule. For example, $2 refers to the second parameter. In the context of functions, the reference $0 denotes the name of the function. Since parameters do not have a name, but are referred to by their position instead, there is no need to declare them in the function header. If you try to access a parameter that has not been passed to the function, the missing parameter is replaced by the text "ParOutOfRange".

Note:

In conditions, the existence of a particular parameter can be checked. For example, condition
$4 == "ParOutOfRange"
checks if four parameters have been passed to the function.

Basic Expressions

The only data type defined in the Autolink configuration language is text. Whether you refer to a signal parameter or call a function, the result of the operation is always a text.

Example 273 : Syntax of basic expressions

 <Term>                   ::= <Atom> { "+" <Atom> }*
 <Atom>                   ::= "$" <Number> | "@" <Number> |
                              <Text> | <Identifier> |
                                   <FunctionCall>
 <FunctionCall>           ::= <Identifier>
                              "(" <SequentialListOfTerms> ")"
 <SequentialListOfTerms>  ::= <Term> { "," <Term> }*
 <AlternativeListOfTerms> ::= <Term> { "|" <Term> }*
 <Conditions>             ::= <Condition> { "AND" <Condition> }*
 <Condition>              ::= <Term> { "==" | "!=" } <Term> |
                              "TRUE"

Texts are constructed by atoms and terms. A single atom can be one of the following expressions, depending on the context in which the atom is used:

  • A simple text (e.g. "Request").
  • An identifier (e.g. Request).
    Identifiers are treated as simple texts.
  • A pattern (e.g. "Sig*").
    Patterns can only be used in the header of constraint or test suite structure rules (for details see "Test Suite Structure Rules" ).
  • A function call (e.g. OpName($3)).
    Function calls are not allowed in the header of constraint or test suite structure rules.
  • A reference to a signal parameter (e.g. $2).
    References to signal parameters can only be used in the body of translation rules.
  • A reference to a function parameter (e.g. $2).
    References to function parameters can only be used in the body of functions.
  • A reference to an atom in the header of a constraint or test suite structure rule (e.g. @2).
    References to atoms can only be used in the body of constraint and test suite structure rules. Their application in combination with patterns is illustrated in "Test Suite Structure Rules" .

Since an atom always evaluates to a text and a term is a concatenation of single atoms, you are allowed to use term expressions for the specification of:

  • Constraint names
  • Constraint formal parameter names
  • Test suite parameter names
  • Test suite constant names
  • Test case/test step/test group names
  • ...

Note:

The text obtained by referring to a signal parameter is identical to the output of the signal parameter value in ASN.1 format.

A condition checks whether two texts are equal (==) or unequal (!=). There is also a special condition TRUE that always evaluates to true.

Conditions can be combined by AND. Only if all conditions in a conjunction hold, the expression as a whole is true.

There is no OR operator for combination of conditions. However, due to the consecutive evaluation of rules (from top to bottom), this is not a restriction. For example, in a function body, simply place both OR-operands in two subsequent mappings.

Concurrent TTCN

In the 1996 version of ISO IS 9646-3, TTCN has been extended with mechanisms to specify test suites for distributed test systems. These extensions are known as concurrent TTCN. This section explains what will happen when you save your test suite in the concurrent TTCN format.

Declarations

In a distributed test environment, the test system is composed of a set of Parallel Test Components (PTC) which each handle one or more PCOs. The test system also includes one Main Test Component (MTC) which starts the PTCs and computes the final test verdict. The MTC may or may not control PCOs. The main and parallel test components exchange Coordination Messages (CM) through Coordination Points (CP).

The collection of a number of test components and their connection through coordination points is called a test configuration. A test suite may contain more than one test configuration, and each test case has to be associated with a specific test configuration individually.

Coordination messages and corresponding constraints have to be declared similar to messages exchanged with the system under test, but in separate tables.

Dynamic behavior description

In concurrent TTCN, the Test Case Dynamic Behaviour table only describes the behavior of the main test component. The behavior of parallel test components is stored in Test Step Dynamic Behaviour tables. Obviously, the behavior tables of every test component contain only events observed at the PCOs and CPs attached to that test component.

Parallel test components are dynamically created by the main test component. This is done by the inclusion of CREATE statements in the test case behavior description. Similarly, the DONE event can be used in the test case description to check the termination of parallel test components. The final test case verdict is computed by the MTC from the verdicts returned implicitly by all PTCs before their termination.

Synchronization of test components

With concurrent TTCN, synchronization among test components becomes a necessity. Each test component only gets a partial view of the system under test and has no inherent knowledge of the state of the other test components. Therefore, the correct order of test events can only be established through the use of coordination messages. Consider the example shown in "Synchronizing Test Events with Conditions" . If there are separate test components to control A, B and C, then C definitely has to wait for a coordination message before sending its Request(B) message to the SUT. If it does not, the test verdict entirely depends on the relative transmission time of the messages and the order of their handling by the SUT.

The Autolink implementation of concurrent TTCN

Autolink generates concurrent TTCN specific information only during the saving of a test suite. Therefore, it does not matter if concurrent TTCN is enabled during the generation or translation of test cases. You may generate your test cases, save the test suite in non-concurrent form, then turn on concurrence and save the test suite again.

Figure 261 : Test configuration for the inres system

Declarations

Autolink supports one kind of test architecture. From this generic architecture and the SDL specification of the system, a concrete test architecture is derived. The following declarations are generated automatically:

  • One main test component called Master. The MTC does not control any PCOs.
  • One parallel test component for each PCO. The name of the test component is PTC_ + Name of the PCO.
  • One coordination point between the MTC and each PTC. The name of the coordination point is CP_ + Name of the PCO.
  • One test configuration called Default_Configuration, which contains all test components and their connections with PCOs and CPs.

Figure 261 shows the test configuration which is generated for the inres System. In addition, the following declarations are generated:

  • One ASN.1 CM Type Definition. The name of the coordination message is CM and its definition is SEQUENCE {message PrintableString}.
  • Two ASN.1 CM Constraint Declarations, called Proceed_Indication and Ready_Indication. Both constraints define values for the coordination message CM.

CM, Proceed_Indication and Ready_Indication are used for coordination messages between the main and parallel test components. These messages are generated automatically (see Synchronization below).

Note:

The test architecture and resulting default test configuration can not be changed within Autolink. The coordination message and corresponding constraints are not changeable neither.

Figure 262 : Sample test case description for a main test component

Dynamic behavior description

Autolink splits the internal test case description into separate trees for every test component. The Test Case Dynamic Behaviour table describes the behavior of the main test component; its name is equal to the name of the original MSC test description. Since the MTC does not control any PCOs, it only contains CREATE statements for every PTC at the beginning and a DONE event at the end. It may also contain attached synchronization test steps in between. Figure 262 shows a sample test case description. The (PASS) verdict on line 1 initializes the result variable R. At the end of the test case, R contains the final test verdict.

Each parallel test component gets a Test Step Dynamic Behaviour table of its own. The name of the test step is Test case name + _ + Test component name.

Synchronization

Coordination messages are automatically generated by Autolink wherever a condition appears in the MSC test description. As a consequence of the test architecture used by Autolink, synchronization is done via the main test component. Here is a description of the algorithm:

  1. For each MSC environment instance connected to a condition: Send a coordination message CM with constraint Ready_Indication to the MTC.
  2. For each MSC environment instance connected to a condition which has a send event immediately following the condition: Receive a coordination message CM with constraint Proceed_Indication from the MTC.

Figure 263 : Synchronization test step for a main test component

From the viewpoint of a parallel test component, this means that whenever it reaches a synchronization point, it sends a Ready_Indication message to the MTC. If the event immediately following the synchronization point is a send event, then the PTC first waits for a Proceed_Indication message, which it receives from the MTC. All coordination events are directly included in the dynamic behavior description of the PTC.

When it reaches a synchronization point, the main test component waits for Ready_Indication messages from every PTC involved in the synchronization. Afterwards, it sends Proceed_Indication messages to all PTCs which are about to send a message to the system under test. Since the reception of coordination messages from different PTCs can create a lot of alternative paths, all synchronization events for the MTC are put into test steps. Figure 263 shows an example of a synchronization test step for an MTC.

Note:

Coordination messages can not be specified manually in the MSC test description. There are two reasons for this: First, the Validator and Autolink can not handle messages drawn between environment instances. Second, all instances in the MSC have to relate to a channel in the SDL specification. Since the main test component has no connection with the system under test, it is not possible to add an MTC instance to the MSC.

Caveats

In order to streamline test suites and enhance their readability, Autolink automatically merges test steps which contain identical behavior descriptions. Furthermore, empty test steps are removed.

If your MSC test descriptions contain MSC references and concurrent TTCN is used to save the test suite, then the test step streamlining of Autolink may lead to unexpected results: For example, test steps for parallel test components may be renamed unexpectedly. Within test case and test step behavior descriptions, expected attachments of test steps may be missing. Nevertheless, these test suites are still correct and correspond to the original test descriptions.

Test Suite Timers

In this section, details regarding the declaration and use of test suite timers in test case MSCs is discussed.

Timer declarations

As explained in "Using Timers" , the recommended method for using test suite timers with Autolink is to explicitly declare all timers which appear in the test suite with Define-Timer-Declaration before test generation is started. Nevertheless, it is possible to have a mixture of implicit and explicit declaration. Below, the rules are listed which Autolink applies when creating or updating timer declarations. In any case, the syntactical correctness of the timer name is not checked.

Creation of a new explicit timer declaration

  • Autolink checks if the duration is an integer value or a syntactically correct test suite parameter. If it is neither, then a warning is displayed and the duration field remains empty. If it is a test suite parameter, a test suite parameter declaration is created in addition to the timer declaration.
  • No declaration is created if the unit is not valid.

Note:

The only possibility to specify an empty duration field on purpose is to use an invalid string, e.g. a digit followed by a character.

Creation of a new implicit timer declaration

  • Autolink checks if the parameter field of the timer set symbol ends with a valid unit, which means that there must be a whitespace character followed by either ps, ns, us, ms, s or min. If this is the case, then the value of the unit field is set and the rest of the string is considered to be the duration. If no valid unit can be found, then the whole parameter field is considered to be the duration.
  • Autolink checks if the duration is an integer value or a syntactically correct test suite parameter. If it is neither, then a warning is displayed and the duration field remains empty. If it is a test suite parameter, a test suite parameter declaration is created in addition to the timer declaration.

Note:

It is the responsibility of the test designer to make sure that either an explicit timer declaration exists or that an implicit declaration is correct. Autolink does not guarantee that a test suite which contains implicit timer declarations passes a TTCN syntax check.

Update of an explicit declaration with an explicit one

An existing explicit declaration can not be updated. A warning is displayed and the new declaration is ignored.

The only way to remove existing timer declarations is to use the Reset command.

Update of an explicit declaration with an implicit one

An existing explicit declaration can not be updated. However, Autolink checks if the unit of the implicit declaration matches the unit of the existing explicit declaration. If it does not match, a warning is displayed.

Update of an implicit declaration with an explicit one

Autolink checks if the unit of the new declaration is valid. If it is not, the existing implicit declaration is kept. If the unit is valid, the implicit declaration is replaced by the explicit one.

Update of an implicit declaration with an implicit one

  • Autolink compares the unit of the existing declaration with the unit of the new declaration:
    • if the existing unit is valid and the new one is invalid, then the existing one is kept;
    • if the existing and the new unit are identical, then the unit is not changed;
    • in all other cases, the unit field is cleared; this will result in a syntactically incorrect TTCN test suite.
  • If the duration field of the existing declaration is empty or an integer value and the new duration is a test suite parameter, then the test suite parameter replaces the existing value.

Timer pitfalls

Timers in a test suite are declared globally. During test execution, each participating test component receives a complete set of timers which it can use independently. With respect to the readability of a test suite, the number of timer declarations should be minimized. This can be accomplished by declaring a minimal set of timers and reusing them in different test case MSCs.

If concurrent TTCN is enabled, identically named timers may also be used on different instances in the same MSC, because in the resulting TTCN test case, each MSC instance is handled by a different test component. However, if such an MSC is used in a non-concurrent context, then Autolink may produce unexpected test sequences and care should be taken.

Timer optimization

If concurrent TTCN output is enabled with Define-Concurrent-TTCN, then the dynamic behavior descriptions are optimized with regard to the placement of timer operations. If a timer START operation is followed immediately by a send event, then the START operation is placed on the same line as the send event. Correspondingly, if a timer CANCEL operation follows a receive event, then the CANCEL is moved up to the line with the receive event. As an example, if the test sequence according to the test case MSC is

START T1
A ! someSignal
A ? anotherSignal
CANCEL T1

then Autolink optimizes this and generates the following test sequence:

A ! someSignal START T1
A ? anotherSignal CANCEL T1


37 Adaptation of Generated Code

This chapter contains information about making an adaptation of the generated code to make it communicate with the generated code.

The first part of this chapter describes the interface to be used when writing the adaptation, the GCI Interface. The different parts of the interface are explained in detail with recommendations and examples of use.

The second part of this chapter is a C implementation of GCI, this can be used as a reference documentation.

The third part describes the EGci (extended GCI) value construction and functions.

The fourth section introduces the Adaptation Framework that can be used to implement GCI functions in a straightforward way with ready-made low-level protocol implementations such as TCP/IP.

The fifth and final section describes the means and measures to complete the adaptation. It describes the requirements on the adaptation in terms of the necessary functions to implement.


The GCI Interface

The Generic Compiler Interpreter (GCI) interface standardizes the communication between a TTCN component supplied by a vendor and other test system components supplied by the customer, together forming a MOT, Method Of Test.

The GCI interface focuses on what an ATS needs in order to execute in term of functionality, and on what is needed in order to integrate TTCN into a larger system. This chapter contains a natural language description of the interface and a GCI C Reference.

The GCI Interface Model

The main purpose of the GCI interface is to separate TTCN behavior from protocol and test equipment specific code. The GCI interface shall be a standardized set of functions. Communication shall be done by calling functions, passing arguments to the functions and return values from the functions, and in no other way. The interface is bidirectional which means that both parties (the TTCN Runtime Behavior and the Test Adaptation) must provide services to each other. The TTCN Runtime Behavior shall at least provide services for handling values and managing tests (evaluating test cases etc.) and the Test Adaptation shall provide the protocol/test equipment specific parts of an executable (send, snapshot, timer functions etc.). The implementation of the functions in the TTCN Runtime Behavior may only depend on the ATS and 9646-3, no extra information shall be needed to implement them.

Figure 264 : The GCI model

Informal Description of the Test Run Model

This section contains an informal description of how a test run might look like using the GCI interface. A test run is defined as a complete test session, where a selection of test cases are run to ensure a specific behavior of the IUT.

A test run begins when the user decides to run a test case or a collection of test cases. He will then use the Supervisory functions to start test cases and monitor their verdicts. The TTCN Runtime Behavior then executes TTCN, occasionally using the operational interface (send, snapshot, etc.) to gather information or to request some service. The TTCN Runtime Behavior handles verdicts internally during a test case and returns the verdict at the end of a test case.

Before using the TTCN Runtime Behavior, it must be initialized. After that the user chooses which test case to run using the supervisory functions. The test case returns a verdict which the user can use to form reports or stop test runs. The TTCN Runtime Behavior or the GCI interface does not impose any restrictions on this part. Any number of test cases can be run and each is commanded using the Supervisory functions.

Figure 265 : Start of test run

The test case at some point will try to send a message on some PCO. The TTCN Runtime Behavior then passes information to the Test Adaptation about the message to send and on which PCO to send it on. It is the responsibility of the Test Adaptation to properly encode the message and actually send it on some media (e.g. sockets, screen, printer port, pipe). Note that control is in the Test Adaptation until it returns to the TTCN Runtime Behavior. When control returns to the TTCN Runtime Behavior it assumes that the message was sent correctly and continues execution of the test case.

Eventually the test case will have emptied its possibilities to act and needs input from the environment. It therefore passes control to the Test Adaptation in order to take a snapshot of the IUT. Within the snapshot, the Test Adaptation then checks all PCO's for incoming messages and all timers for time-outs. If a message has arrived on a PCO, the Test Adaptation must decode the message and translate it into a proper GCI value. If a timer has timed out, the Test Adaptation must record which timer. The Test Adaptation acts as a filter between the IUT and the TTCN Runtime Behavior. Note that the actual reception of a message or timeout could be handled somewhere else (e.g. in an interrupt routine), only the official communication that the event has taken place must be done in SNAPSHOT.

Figure 266 : Send and Snapshot

Preliminary verdicts may be set during the test execution and when a final verdict is set, the test case returns to the Test Adaptation immediately. The Test Adaptation then has freedom to decide to continue the test run or not. A final verdict has meaning only in the context of the current test purpose. The meaning of a final verdict is not specified in the context of an entire collection of test cases. For example, when doing regression tests, all test cases should be run regardless of how many failed in order to get a complete picture of the status of the IUT.

Which Does What?

The table below summarizes the responsibilities of the two GCI parties, the TTCN Runtime Behavior and the Test Adaptation. It is meant to describe the model and basic assumptions being made.

TTCN Runtime Behavior | Test Adaptation
SEND: Builds the object to be sent and requests the actual sending from the Test Adaptation. | SEND: Receives the object that shall be sent and transfers this to the IUT. This might include encoding in some form.
RECEIVE: When a value is put on a PCO queue by the Test Adaptation, it remains there until a matching receive line is found in TTCN. | RECEIVE: Builds the received object (from the IUT) into a GCI value, which may include some form of decoding, and notifies the TTCN Runtime Behavior that the message has arrived.
Sets the verdict (based on the test case). | Treats the verdict (i.e. decides if the test run should continue or not).
Impl. of value representation. | Encoders/decoders.
Uses the value repr. | Uses the value repr.
Provides test cases. The test cases are sensitive to test case selection references. | Determines which test cases to run and in which order.
Uses send on messages. | Provides the send functionality.
Uses SNAPSHOT to fix a view of the status of the IUT. Expects all changes in system status to be recorded in SNAPSHOT. | Reads system status in SNAPSHOT and records this through GCI interface for the TTCN Runtime Behavior.
Uses the LOG function to log TTCN Runtime Behavior. | Provides the LOG functionality, and also decides on what level logging should be done.

Case Studies

This section contains case studies of a send and a receive. For the case studies, we use an example PDU shown in Figure 267.

Figure 267 : Example table

Case Study: SEND

Nr
Lbl
Statement Line
Cref
Comment

 L ! CR

 CR_c

The semantic of the TTCN send statement is as follows:

  1. Build the SendObject using the constraint reference.
  2. Execute the assignments.
  3. Send the SendObject on the PCO.
  4. Execute the timer operations.
  5. LOG, at least the PCO and the SendObject must be logged.

The SendObject above is a temporary object containing the object to be sent. All steps above are initiated by the TTCN Runtime Behavior. Steps 3 to 5 require communication with the environment (IUT). The TTCN Runtime Behavior will build a SendObject using the constraint CR_c above. Then it will call the Test Adaptation function Send. By doing this, the TTCN Runtime Behavior has ensured that the message gets sent on whatever PCO was stated. The Test Adaptation function Send then encodes the message using the transfer syntax of the protocol and then sends the message on the medium that represents the PCO. The arguments passed to Send is the PCO and the message in the GCI representation, and the side effect of Send is to send the message in protocol representation on the PCO in test system representation. Note that the encoding and sending on a PCO might very well be represented as a function call.

Figure 268 : The send event

Case Study: RECEIVE

Nr
Lbl
Statement Line
Cref
Comment

 L ? CC

 CC_c

The receive is a little more complicated than the send. Send is initiated by the TTCN Runtime Behavior while receive is an internal event in the TTCN Runtime Behavior. The actual reception of messages is done in the Test Adaptation and these actions are communicated to the TTCN Runtime Behavior in SNAPSHOT. Note that there may be a difference between the reception of a message and the notification to the TTCN Runtime Behavior that the message has arrived. The TTCN Runtime Behavior calls the function SNAPSHOT and when it returns, the TTCN Runtime Behavior expects all time-outs to have been recorded and all received messages to be put on the correct PCO queues in the correct format. In this case we study the message event only and not the timeout.

A message has been received from the IUT (not necessarily in SNAPSHOT) and the TTCN Runtime Behavior must be told that the message has been received. This shall be done in SNAPSHOT using the GCI function provided. The message and the PCO must be presented in a representation understood by the TTCN Runtime Behavior. Note that the message probably needs to be translated into the GCI value representation somewhere but again not necessarily in SNAPSHOT.

If SNAPSHOT does what is stated above, the TTCN Runtime Behavior will do the following on the receive line in the test case:

The PCO queue is checked and if there is a message there, that message is matched against the constraint reference. If the message matches, it is removed from the PCO queue and the receive statement is considered to be TRUE, otherwise, the next alternative is checked.

In Figure 269, we assume that decoding is done in SNAPSHOT. The message is decoded using the value manipulating primitives of the GCI interface. When the message has been decoded into something known to the TTCN Runtime Behavior, it is easy to assign it to a PCO using the GCI function receive.

Figure 269 : The receive event

Methods Used

This section contains general thoughts on methods used for designing the GCI interface. Choices have been made such as to provide reasonable trade-offs between speed and ease of use. An efficient implementation in C should be possible with the choices made.

Identifying Global Objects in TTCN/ASN.1

One problem is how to identify global objects in TTCN, PCOs, CPs, ASPs etc. There are a number of requirements that should be met:

  1. Execution time:
    The TTCN behavior, operational and value interface functions are likely to be called many times in a time sensitive context which requires them to be fast. The management functions does not have this requirement.
  2. Compilation time:
    The Test Adaptation and the TTCN Runtime Behavior are likely to be used together with a graphical interface (GUI) or integrated into a larger system. This integration should be possible without re-compiling the GUI or the larger system every time a change has been made in the ATS. This requires that dependencies between the ATS and the management interface implementation must be kept to a minimum.

There are at least three alternative solutions to be considered:

  1. Straight name reference using target language semantics, i.e start test case "TC1" by writing the function call "TC1()" in C, and the value of the variable "TCVAR1" is expressed simply as TCVAR1
  2. Assign an integer to each object. Symbolic names could then be used. The examples from above would then be:
#define TC1 192
#define TCVAR1 1211
Verdict = GciStartTestCase( TC1 );
Display( GciGetValue( TCVAR1 ));
  3. Use string references.
Verdict = GciStartTestCase( TC1 );
Display( GciGetValue( TCVAR1 ));

Solution 1 gives the fastest execution but is very unsuitable for integration into a larger application. Solution 2 is at least possible to integrate into a GUI, and almost as fast as solution 1. Solution 3 is excellent for integration but gives slow execution.

In the GCI interface, we choose to use solution 3 (string references) in the management functions and solution 2 in the TTCN behavior functions. It would then be very easy to integrate an ETS into an already existing test system since the interface is string based while we still maintain speed in the execution of test cases.

A similar problem is how to identify fields in structured types. The simplest solution is to address them using integers field 0, field 1, etc., but then the Test Adaptation writer would get very little support from the compiler. From the Test Adaptation writers point of view, he might want to address the fields using names and also get type checking aid from the compiler. The Test Adaptation writer also wants to write generic functions for encode/decode. The GCI interface supports both views, one view where substructures are identified by numbers, and one which in effect use name addressing.

Test Suite Operation Definitions

The TTCN Runtime Behavior requires that all test suite operations are defined as functions at run-time. Arguments to and return values from the test suite operation functions shall use the GciValue* format. The name of the test suite operation function shall be the same as the name of the test suite operation in TTCN.

Logging

The log will provide a view of a test run. Most things happening in the system will need to be logged. We have identified a number of requirements on the log functionality:

  1. It should be possible to only log every event visible to the TTCN Runtime Behavior. I.e. the sending of a message should leave a note in the log while the internal behavior of the TTCN Runtime Behavior should not.
  2. For debug purposes, it must be possible to report every event in the system.
  3. The granularity of the log must be easy to change by the Test Adaptation writer. It should be possible to be quite specific when logging, i.e. log only sends and receives.

The method that the GCI interface suggests is massive logging. Everything is logged at any time and every type of event (send, receive etc.) is assigned a number. That way it is easy for the Test Adaptation writer to write a log function that only logs interesting log messages.

Value Representation

The GCI interface must provide a stable way of manipulating values. This is most important for the Test Adaptation writer to be able to access and build values in his encode and decode functions. The GCI interface proposes not to specify the value representation but rather the methods which can be used on it. The GCI interface specifies what the Test Adaptation writer is able to do with values. The reason for this is that most vendors supporting the GCI interface would like to have their own value representation within their TTCN Runtime Behavior, and the representation used within TTCN has different requirements than the representation needed for the Test Adaptation.

Introduction to the GCI Interface

This section contains the description of the GCI interface in natural language. The interface functionality is sorted by responsibility. The management, behavior and value interfaces are interfaces to the TTCN Runtime Behavior. The operational interface is the interface to the Test Adaptation.

Management Interface

The management interface consists of those functions necessary for initiating and managing test runs. They provide an API to the ATS. These functions are used by the Supervisory functions to govern test runs.

Initiation of the TTCN Runtime Behavior

Must be called before the TTCN Runtime Behavior is used in any way. It will read test suite variables (using primitives in the operational i/f), set up test case selection references, test suite constants and any other initialization necessary. It should only be called once.

Start Test Case

Shall run a test case according to the dynamic behavior in 9646-3. Input shall be a test case name or test case group name. The test case or all the test cases in the test group shall then be run in the order which they were listed in the ATS. If the selection reference of a test case or test case group is false, that test case or test case group shall not be executed. Verdict shall be set and communicated back to the caller. In case several test cases have been run, the verdict shall be the most negative of the verdicts from each test case (if one test case is FAIL, the verdict would be FAIL, if all are PASS, the verdict would be PASS).

Start Test Component

This function works just line the function to start test cases, but starts test components for example when concurrent TTCN is used.

Test Case List

A list of names of test cases.

Test Case Group List

A list of names of test case groups.

Number of Timers and PCOs

Two functions are needed to return information about the amount of timers and PCOs in the system.

Information About Timers and PCOs

Help functions are needed to get some extra information about timers and PCOs. (For example name and type.)

Configuration Information

A set of functions is needed to retrieve information about configurations when running concurrent TTCN.

Accessing TTCN Values

Values of TTCN (and ASN.1) objects must be accessible from the Test Adaptation. A general access function will be provided. Information passed shall be an object name and the information passed back shall be the value of the object. Valid objects shall be test suite parameters, test case selection expressions, test suite constants, test suite variables and test case variables.

Behavior Interface

The behavior interface consists of functions used to notify the TTCN Runtime Behavior of events in the IUT. The functions are a formalism of what the TTCN Runtime Behavior needs to know about the status of the IUT. The functions are implemented in the TTCN Runtime Behavior and must be used in Snapshot.

Receive

Whenever a message has been received and decoded it must be passed to the TTCN Runtime Behavior in SNAPSHOT in order for it to match it with the constraint. The information passed shall be the PCO descriptor and the value. Note that the value passed in receive must be a GciValue*.

Time Out

Whenever a timer has timed out the TTCN Runtime Behavior must be notified of it in SNAPSHOT. The information passed shall be the timer descriptor.

Done

Whenever a test component has terminated its execution the TTCN Runtime Behavior needs to know about this. The information passed is the descriptor for the given test component.

Operational Interface

The operational interface consists of those primitives necessary for the TTCN Runtime Behavior to implement TTCN, i.e. Send, Snapshot, StartTimer etc. This part of GCI can be compared to POSIX. TTCN Runtime Behavior requires that the functions are defined.

Test Suite Parameters

The TTCN Runtime Behavior shall call the Test Adaptation once for each test suite parameter during the initialization of the TTCN Runtime Behavior. Information passed shall be a handle for the value, the parameter name and the PICS/PIXIT reference.

Test Suite Operations

Each test suite operation must be defined in the Test Adaptation. The name of the test suite operation function shall be the same as in the ATS, and the order of the parameters shall also be the same.

Create

When a test component needs to be created this function will be called from the TTCN Runtime Behavior.

Configuration

When different tests are run, different configurations might be needed. This function is called from the TTCN Runtime behavior to set up a configuration before the test goes on.

Snapshot

The status of the IUT must be read. Events in the IUT must be translated for the TTCN Runtime Behavior to be aware of them. The communicating interface between the TTCN Runtime Behavior and the IUT (environment) is made up of messages that has arrived and timers that have timed out. Therefore there are only two requirements on SNAPSHOT: 1) any received messages shall be recorded and 2) any timers that have timed out shall be recorded. The recording shall be done by using the provided GCI functions described in the Behavior i/f.

Send

This function is used by the TTCN Runtime Behavior to ensure that messages get sent. Send probably involves encoding and physical sending but might as well translate to encoding of some parts of the message and use of a lower layer service. The information passed to the function shall be a PCO descriptor and the value to be sent.

Start Timer

When the TTCN Runtime Behavior needs to start a timer. Information passed shall be the timer descriptor, the integer timeout duration and the timer unit.

Read Timer

Shall pass the current timer value back to the caller. Information passed to the function shall be a timer descriptor.

Cancel Timer

Shall stop a timer identified by a timer descriptor.

Log

Shall log events on an appropriate format. An integer specifying log message type and a log string shall be passed as parameters.

Value Interface

The interface to values is a simple API in which the user is allowed to build and access GciValues in an ordered way. The actual values used are not specified, only the methods that can be used on them are included. This way will allow vendors to have their own value representation within their TTCN Runtime Behavior and still conform to GCI.

Three types of value primitives are needed. Primitives to access structured values:

  • Primitives to build and access components of structured values
  • Primitives to find and set the type of values
  • Primitives to convert base values to and from the value domain of the target language

Value primitives can be further divided in the groups:

  • SEQUENCE values, which include SET values and also TTCN ASP, PDU and Struct types
  • SEQUENCE OF values, which include SET OF values
  • CHOICE values
  • OBJECT IDENTIFIER values
  • BASE values, integers, booleans, strings and reals

Please note that SET and SET OF values are treated as SEQUENCE and SEQUENCE OF values because there is no semantic difference at this level of abstraction. The unordered behavior of SETs is considered a decoder problem and left to the decoder writer.


GCI C Code Reference

This section is a code description of GCI. It describes what each function does and why it is used. Some of the functions must be implemented by you in your adaptation. See section "Completing the Adaptation" .

Predefined Types

These are the GCI value types with their respective value set:

GciStatus = { GciNotOk, GciOk }

GciVerdict = { GciFail, GciInConc, GciPass, GciNone}

GciTimeUnit ={ Gcips, Gcins, Gcius, Gcims, Gcis, Gcimin }

GciTimerStatus = { GCIRUNNING, GCISTOPPED, GCIEXPIRED }

GciPCOID = INTEGER

GciTimerID = INTEGER

GciPosition = <internal position value>

These are structured GCI value types with their respective members:

The general communication address type

typedef struct GciAddress {
int type; /* Address type 0 - 100 is                           reserved by Telelogic */
char* buffer; /* The address stored in a                           buffer */
} GciAddress;

The general time value

typedef struct GciTime {
unsigned long time_val;
GciTimeUnit unit;
} GciTime;

Management Interface

The management interface consists of the functions necessary for initiating and managing test runs. They provide an API to the TTCN runtime behavior.

GciStatus GciInit()

Initiates the TTCN Runtime Behavior. Must be called before any test cases are started.

GciStatus GciExit()

Shuts down the TTCN Runtime Behavior system. Usually called last before closing a test session.

GciVerdict GciStartTestCase( const char* TCorTGName )

Calling this function with a test case name will start and run the given test case. The verdict returned is the verdict set by the test case.
If the function is called with a test group name, it will start and run the given test group. The verdict returned is the product of the verdicts set in the test cases or test groups contained in the given test group. The individual verdicts from the different test cases or test groups have to be extracted from the log. The verdict algorithm for test groups is defined as follows:
  1. The verdict is PASS if the verdict of every test case is PASS.
  2. The verdict is INCONC if the verdict of at least one test case is INCONC and all others are PASS.
  3. The verdict is FAIL if the verdict of at least one test case is FAIL.
    If the given name is not a valid test case nor test group, the function will return GciNotOk and log the following message:
No such Test Case or Test Group as <name> to run!

GciVerdict GciStartTestComponent( char* TSName,
GciValue* args )

This function works just like GciStartTestCase but is used to start a parallel test component (PTC) when using concurrent TTCN. TSName is the name of the Test Step to run in the PTC.

GciTCList* GciGetTestCaseList()

This function returns a list of all test case names (including test cases in test groups).

GciTCList GciGetTestCaseGroupList()

This function returns a list of all test group names (including test groups in test groups). List of character strings.

GciValue* GciGetValue(char* TTCNObjectName)

This function returns the TTCN value object given the object's name. If the object name does not exist, the function will return NULL and log the following message:
GciGetValue: Could not find <name>! NULL returned

If the object name is a TTCN name, but not an object (variable, constant, etc...) the function will return NULL and log the following message:
GciGetValue: <name> not an instance! NULL returned

int GciGetNoOfTimers( )

Returns the number of timers in the system.

int GciGetTimer( int index )

Returns the identifier of the given timer index.

char* GciGetTimerName( int timer )

Returns the name of the given timer.

int GciGetTimerIndex( int desc )

Returns the index of the given timer descriptor.

int GciGetNoOfPCOs( )

Returns the number of PCOs in the system.

int GciGetPCO( int index )

Returns the descriptor of the given PCO index.

char* GciGetPCOName( int pco )

Returns the name of the given PCO.

int GciGetPCOIndex( int desc )

Returns the index of the given PCO descriptor.

int GciGetPCOType( pco )

Returns the type of a given PCO.

int GciGetNoOfComponents( GciConf conf )

Returns the number of components in the given configuration.

GciComponent* GciGetComponent( GciConf conf, int index )

Returns the indexed component in the given configuration.

char* GciGetComponentName( GciComponent* conp )

Returns the name of the given component.

int GciGetComponentType( GciComponent* conp )

Returns the type of the given component (GciMTC or GciPTC).

int GciGetComponentDescriptor( GciComponent* conp )

Returns the descriptor of the given component.

char** GciGetComponentCPs( GciComponent* conp )

Returns the CPs used by the given component.

char** GciGetComponentPCOs( GciComponent* conp )

Returns the PCOs used by the given component.

Behavior Interface

The behavior interface consists of the functions used to notify the TTCN Runtime Behavior of events in the IUT. The functions are a formalism of what the TTCN Runtime Behavior needs to know about the status of the IUT. The functions are implemented in the TTCN Runtime Behavior and must be used in Snapshot.

GciStatus GciTimeout( int timerd )

This function will change the status of the internal timer indexed by the timer descriptor timerd. The timer will be marked as timed out.

GciStatus GciReceive( int pcod, GciValue* value )

This function will insert the received object into the internal PCO queue indexed by the PCO descriptor pcod.

GciStatus GciDone( int ptc )

This function will mark the given PTC as done with its execution.

Operational Interface

The operational interface consists of the functions necessary for the TTCN Runtime Behavior to communicate with the IUT, i.e. the dependencies on the protocol and test environment. It implements functionality for Send, Snapshot, StartTimer, etc. The TTCN Runtime Behavior requires that the functions are defined in the adaptation.

GciValue* GciReadTSPar( char* name, char* pRef )

The user has to implement how to read the test suite parameters. This code will be called one time for each test suite parameter in the system. Here name is the name of the test suite parameter and pRef is the PICS/PIXIT field (ex. file). The value returned by this function must be a pointer to a valid GciValue structure which can be successfully used by the TTCN runtime behavior. If for any reason this could not be done, NULL should be returned.

GciStatus GciConfig( GciConf conf )

When using concurrent TTCN the user is responsible for creating the configurations to be used for a given test. The creation of those configurations is done in this function using a set of help functions in the management interface to traverse the information.

GciStatus GciSnapshot()

This is a very important function that the user has to implement. This function is called from the run-time behavior when it needs input from the test environment (timers and/or PCO's).
  • Communication lines (PCOs) must be checked. If something has been received, we must decode the message, build a receive object and insert the object into the correct, internal PCO queue by using the GciReceive function with appropriate PCO descriptor. The GCI Value Interface is used to build the object(s).
  • Timers must be checked and their status must be reported to the TTCN run-time system. If the user uses the simple adaptation template he/she must self keep track of time and use GciTimeout to mark a timer as timed out. If the user uses the timers adaptation template he/she can use the AdSetTime function (see below) to have this work done automatically.

GciStatus GciSend(int pcod, GciValue* value)

The user is responsible for implementing the send functionality. This involves identifying a given PCO and encoding the value before sending the message on that PCO.

GciStatus GciStartTimer(int timerd, long duration,
int unit)

To start a timer the TTCN runtime behavior will call this function. Note that timer duration value is optional in TTCN but is always present here.

GciStatus GciCancelTimer(int timerd)

This function is called to stop the given timer. It should have the effect that the appropriate timer representation in the adaptation is stopped.

long GciReadTimer(int timerd)

This function is called when a timer is read. It must return the current timer value.

GciStatus GciCreate(int ptc, char* tree, GciValue* args)

This functions is called when a PTC is to be created to run a given dynamic behavior with the given arguments (concurrent TTCN).

GciValue* <TS_Op>( <Arguments> )

Every test suite operation must have this function defined. The name shall be the same as in the ATS and arguments must match the parameters in the ATS.

GciStatus GciImplicitSend( GciValue* value )

This function is called by the run-time behavior when an Implicit Send Event occurs in the test suite. It is up to the adaptation writer to define its exact implementation.

GciStatus GciLog(int logId, char* LogString)

The user has to implement parts of the logging facility. As the GCI document describes, some log identifiers are already implemented. The log identifiers (identifies the type of log message) in this function should NOT be changed as they follow the values listed in the GCI document. The TTCN Runtime Behavior uses this function for logging.

logId
Description
The logString must contain:

 Msg
General message

 StartTC
Start test case
The name of the test case

 StopTC
Stop test case
The name of the test case

 StartTS
Start test step
The test step name

 StopTS
Stop test step
The test step name

 StartDEF
Start default
The default name

 StopDEF
Stop default
The default name

 Verdict
Final verdict set
The verdict set

 PVerdict
Prel. verdict set
The verdict set

 Match
Line tried matches
Line number

 NoMatch
Line tried does not match
Line number

 SendE
Send Event
The PCO name
The type of message sent
Constraint name

 RecE
Receive Event1
The PCO name
The type of message received
Constraint name

 OtherE
Otherwise Event
The PCO name

 TimeoutE
Timeout Event
The timer name

 Assign
Assignment
The Left hand side
The right hand side (textually)

 StartT
Start timer
The timer name
The timer duration

 StopT
Stop timer
The timer name

 CancelT
Cancel timer
The timer name

 ReadT
Read timer
The timer name
The timer value

 Attach
Attachment
The name of the attached test step

 ImplSend
Implicit send
The PCO name
The message type

 Goto
Goto
The line number to which the jump will be made

 Rec
Receive2
The PCO descriptor number

 Timeout
Timeout3
The timer descriptor number
1

Logging that a receive line matches.

2

Note this is low level logging done when the Test Adaptation writer calls GciReceive (or GciTimeout)

3

Note this is low level logging done when the Test Adaptation writer calls GciReceive (or GciTimeout)

Value Interface

The interface to values is a simple API in which the user is allowed to build and access GciValues in an ordered way. The actual values used are not specified, only the methods that can be used on them are included. This way will allow vendors to have their own value representation within their TTCN Runtime Behavior and still conform to GCI.

Base Types/Values

These functions are used to transform actual values into the GCI representation. The interface is on base types only, so TTCN simple types are not visible in the interface.

GciValue* GciMkINTEGER( int num )
int GciGetINTEGER( GciValue* value )

Used for integer values, and simple type values with base type integer.

GciValue* GciMkBOOLEAN( int bool )
int GciGetBOOLEAN( GciValue* value)

Used for Boolean values, and simple type values with base type Boolean.

GciValue* GciMkREAL(int mantissa, int base, int exponent)
GciReal GciGetREAL( GciValue* value)

Used for Real values, and simple type values with base type Real.

GciValue* GciMkBIT_STRING( const char* str )
char* GciGetBIT_STRING( GciValue* value)

Used for bit string values, and simple type values with base type bit string.

GciValue* GciMkHEXSTRING( const char* str )
char* GciGetHEXSTRING( GciValue* value)

Used for hex string values, and simple type values with base type hex string.

GciValue* GciMkOCTET_STRING( const char* str )
char* GciGetOCTET_STRING( GciValue* value)

Used for octet string values, and simple type values with base type octet string.

GciValue* GciMkNumericString( const char* str )
char* GciGetNumericString( GciValue* value)

Used for values numerical strings, and simple type values with base type numerical string.

GciValue* GciMkPrintableString( const char* str )
char* GciGetPrintableString( GciValue* value)

Used for Printable string values, and simple type values with base type Printable string.

GciValue* GciMkTeletexString( const char* str )
char* GciGetTeletexString( GciValue* value)

Used for Teletex string values, and simple type values with base type Teletex string.

GciValue* GciMkVideotexString( const char* str )
char* GciGetVideotexString( GciValue* value)

Used for Videotex string values, and simple type values with base type Videotex string.

GciValue* GciMkVisibleString( const char* str )
char* GciGetVisibleString( GciValue* value)

Used for Visible string values, and simple type values with base type Visible string.

GciValue* GciMkIA5String( const char* str )
char* GciGetIA5String( GciValue* value)

Used for IA5string values, and simple type values with base type IA5string.

GciValue* GciMkT61String( const char* str )
char* GciGetT61String( GciValue* value)

Used for T61string values, and simple type values with base type T61string.

GciValue* GciMkISO646String( const char* str )
char* GciGetISO646String( GciValue* value)

Used for ISO646string values, and simple type values with base type ISO646string.

GciValue* GciMkGraphicalString( const char* str )
char* GciGetGraphicalString( GciValue* value)

Used for Graphical string values, and simple type values with base type Graphical string.

GciValue* GciMkGeneralString( const char* str )
char* GciGetGeneralString( GciValue* value)

Used for General string values, and simple type values with base type General string.

GciValue* GciMkENUMERATED( int value )
int GciGetENUMERATED( GciValue* value)

Used for Enumerated values, and simple type values with base type Enumerated.

GciValue* GciMkCHOICE(const char* name, GciValue* value)
GciValue* GciGetCHOICE( GciValue* value)
char* GciGetCHOICEName( GciValue* value)

Used for Choice values, and simple type values with base type Choice.

GciValue* GciMkOBJECT_IDENTIFIER()
int GciOBJECT_IDENTIFIERSize( GciValue* value)
GciValue* GciAddOBJECT_IDENTIFIERComponent(
GciValue* value, int comp)
int GciGetOBJECT_IDENTIFIERComponent( GciValue* value,
int index)

Used for Object identifier values, and simple type values with base type Object identifier.

GciValue* GciMkObjectDescriptor( const char* str )
char* GciGetObjectDescriptor( GciValue* value)

Used for ObjectDescriptor values, and simple type values with base type ObjectDescriptor.

GciValue* GciMkNULL( )
int GciGetNULL( GciValue* value)

Used for Null type values, and simple type values with base type Null type.

GciValue* GciMkANY( GciValue* value )
GciValue* GciGetANY( GciValue* value)

Used for ANY values, and simple type values with base type ANY.

GciValue* GciMkR_TYPE( int value )
int GciGetR_TYPE( GciValue* value)

Used for R_Type values, and simple type values with base type R_Type.

GciValue* GciMkPDU( GciValue* value )
GciValue* GciGetPDU( GciValue* value)

Used for PDU values, and simple type values with base type PDU.

Base Functions

int GciGetType( GciValue* val )

Shall return the type of a value. The type is represented as the number used to identify global objects, see "Identifying Global Objects in TTCN/ASN.1" . The function is valid for all values, but some values may be untyped in which case the function returns 0.

GciValue* GciSetType( int type, GciValue* val )

Shall set the type of a value. Uses the same number as above. Valid for all values. Returns the input value with type set.

Value Management

The functions are divided into two meta sets derived from ASN.1: The sequence, and the sequence of, corresponding to struct and array in C. The choice type of ASN.1 is not represented as a meta class because all values in the GCI value representation can be typed and therefore is the choice value implicit in GCI.

The functions only works within their intended set (e.g. GciSetField(GciMkSEQUENCE(2), 1, GciMkINTEGER()) is well defined but GciSetField(GciMkSEQUENCEOF(), 0, GciMkINTEGER()) is not defined and certainly is unpredictable.

Sequence and Set Types/Values

GciValue* GciMkSEQUENCE( int size )

Creates a sequence value with size children.

GciValue* GciSetField( GciValue* seq, int index,
GciValue* fld )

Sets the field identified by index to the given value. Indices start at 1. The function is undefined for indices greater than the size of the sequence.

GciValue* GciGetField( GciValue* seq, int index )

Returns the field identified by index. Indices start at 1. The function is undefined for indices greater than the size of the sequence.

int GciSeqSize( GciValue* seq )

Returns the number of fields declared in the sequence seq.

Sequence of and Set of Types/Values

GciValue* GciMkSEQUENCEOF()

Creates a sequence of value.

GciValue* GciAddElem( GciValue* seqOf, GciValue* elem )

Adds the element elem to the end of sequence of seqOf.

GciValue* GciGetElem( GciValue* seqOf, int index )

Returns the element number index of the sequence of seqOf. Indices start at 0. The function is undefined for indices greater than current size.

int GciSeqOfSize( GciValue* seqOf )

Returns the current number of elements in seqOf.

Examples

This section contains examples of how the mapping between TTCN/ASN.1 and their GCI representation could be done. The examples use a conceptual model for encoding/decoding, no error handling is done and no attention is paid to the fact that some functions would use pointers because of allocation issues.

Global objects (PCOs and types) are identified with an unique number. This number is given a symbolic reference which is its TTCN name with a D for Descriptor appended to the end of it. The number for the PCO L is therefore referenced as LD.

Encoding/Decoding Examples

Each example consists of a table and the corresponding encode (and/or decode) functions. The examples focus on the value representation so the transfer syntax is simple: Each value is preceded by a header. The header contains the type of the value (as a number) and in some cases its length (element count, not size in bytes), in real ASN.1, the header would be built using tags. The header is written/read using primitives BufWriteType, BufWriteSeqOfSize, etc. They are not encode/decode primitives but rather buffer primitives.

An encode function is a function that translates the GCI value onto a buffer, and a decode function is one that reads a value from a buffer and builds a value in the GCI representation. Encoding functions are called from SEND and decoding functions are called from SNAPSHOT. The buffer has type Buffer and could be anything behaving as a sequence of bytes. The primitives BufReadInt, BufReadBool are used to read and write GCI basic values.

ASN.1 SEQUENCE Type

Figure 270 : Example

Encode

void EncodeT1( Buffer buf, GciValue* v)
{
  BufWriteType( buf, T1d );
  BufWriteInt( buf, GciGetField( v, 1 ));
  BufWriteBool( buf, GciGetField( v, 2 ));
}

Decode

void DecodeT1( Buffer buf, GciValue* v)
{
  int i;

  v = GciMkSEQUENCE( 2 );
  if ( BufReadType( buf ) != T1d )
    Error();
  GciSetType( T1d, v );

  i = BufReadInt( buf );
  GciSetField( v, 1 , GciMkINTEGER( i ) );

  i = BufReadBool( buf );
  GciSetField( v, 2 , GciMkBool( i ) );
}

ASN.1 SEQUENCE OF Type

Figure 271 : Example

Encode

void EncodeT2( Buffer buf, GciValue* v )
{
  int i;

  BufWriteType( buf, T2d );
  BufWriteSeqOfSize( buf, GciSize( v ) );
  for (i = 1 ; i <= GciSize( v ) ; i++ )
    {
      EncodeT1( buf, GciGetElem( v, i ) );
    }
}

Decode

void DecodeT2( Buffer buf, GciValue* v )
{
  int i, seqOfSize;
  GciValue* elem;

  if ( BufReadType( buf ) != T2d )
    Error();

  GciSetType( T2d, v );

  seqOfSize = BufReadSeqOfSize( buf );
  for ( i = 1 ; i <= seqOfSize ; i++ )
    {
      DecodeT1( buf, elem );
      GciAddElem( v, elem );
    }
}

ASN.1 CHOICE

Figure 272 : Example

Encode

void EncodeT3( Buffer buf, GciValue* v )
{
  switch ( GciGetType( v ))
    {
    case T1d:
      EncodeT1( buf, v );
      break;
    case T2d:
      EncodeT2( buf, v );
      break;
    default:
      Error();
    }
}

Decode

void DecodeT3( Buffer buf, GciValue* v )
{
  switch ( BufGetType( v ))
    {
    case T1d:
      DecodeT1( buf, v );
      break;
    case T2d:
      DecodeT2( buf, v );
      break;
    default:
      Error();
    }
}

In-Line ASN.1 Type

Figure 273 : Example

Encode

void EncodeT4( Buffer buf, GciValue* v )
{
  GciValue* tmp;

  BufWriteType( T4d );
  /* Encode first field */
  EncodeT1( GciGetField( v, 1 ));
  /* Now encode inline type definition */
  tmp = GciGetField( v, 2 );
  BufWriteInt( buf, GciGetField( tmp, 0 ));
  EncodeT2( buf, GciGetField( tmp, 1 ));
}

Decode

void DecodeT4( Buffer buf, GciValue* v)
{
  int i;
  GciValue* tmp;

  v = GciMkSEQUENCE( 2 );
  if ( BufReadType( buf ) != T4d )
    Error();
  GciSetType( T4d, v );
  DecodeT1( buf, tmp );
  GciSetField( v, 1, tmp );
  tmpseq = GciMkSEQUENCE( 2 );
  i = BufReadInt( buf );
  GciSetField( tmpseq, 1, GciMkINTEGER( i ) );
  DecodeT2( buf, tmp );
  GciSetField( tmpseq, 2, tmp );
}

TTCN Examples

myQueue below is the Test Adaptation writers own representation of the PCO queue(s). In this example there is only one PCO, called L (Ld for its number). Note that the number Ld can be any number (most certainly not zero).

Snapshot Example

Snapshot must read the status of the IUT and tell this to the TTCN Runtime Behavior.

void GciSnapshot()
{
  GciValue* v;

  /* Check if anything has arrived,  */
  /* This would be a while statement */
  /* in a blocking context           */
  if ( ! myQueue[ 0 ].empty )
    {
      switch ( BufPeekType( myQueue[0].buf ))
        {
        case T1d:
          DecodeT1( myQueue[0].buf, v );
          break;
        case T2d:
          DecodeT2( myQueue[0].buf, v );
          break;
        default:
          Error();
        }

      GciReceive( Ld, v );
    }

  /* Nothing has happened. */
}

Send Example

For the send example the following ASP table is used to show an API view of encode.

Figure 274 : Example

/* Two examples of send functionality */
GciStatus GciSend( int pcoDescr, GciValue* msg )
{
  if ( pcoDescr == PcoToSocket )
    {
      /* Encode first */
      if ( GciGetType( msg ) == T1d )
        {
          EncodeT1( buf, msg );
          BufSocketSend( buf );
        }
    }
  else if ( pcoDescr == PcoToAPI )
    {
      if ( GciGetType( msg ) == TCONreqd )
        {
          Buffer pdu;
          EncodeT1( pdu, GciGetField( msg, 1 ));
          /* Call to lower layer */
          T_CONreq( GciGetField( msg, 0 ), pdu );
       }
    }
}


EGci Value Construction and Functions

The GCI interface has been defined as a base for executable test suite adaptation. One part of this interface covers values, how to build them, access them, etc. While this interface was not enough, a set of functions has been added with the EGci prefix so that the GCI functions (a set defined by a standard) was not changed. The purpose of this section is to describe this paradigm of value construction and the current EGci functions available.

Value Construction

The major difference in value handling is how values are constructed. Values are either created by the GciMk-prefixed functions, followed by a GciSetType call, or value are created by a call to the EGciMkValue function. The run time system is compatible with both alternatives but the latter is preferred. The difference is that the GciMk-function creates untyped values of a given predefined type (SEQUENCE, SET, INTEGER, etc.) while the EGciMkValue takes the type descriptor of the user-defined type and creates the complete value structure with correct types throughout the whole value structure. Values of type SEQUENCE OF, SET OF and CHOICE cannot be fully instatiated since the size/choice of the value is not known at code generation time. Elements of the SEQUENCE/SET type are appended explicitly and CHOICE values are also selected explicitly.

The procedure is to create the value structure (with uninitialized leaf values) and then extract the proper value (container) through ordinary field access and extraction functions. Then the value is assigned using the EGciAssign function. When available, for simple non-structured values, EGciSet/GciSet-functions can also be used on the extracted values.

Below you will find two alternatives for creating a value given the following type:

T ::= SEQUENCE
{
a SEQUENCE {
b MyINTEGER
},
c MyINTEGER
}

MyINTEGER ::= INTEGER

v T := { a { b 17 }, c 42 }

Alternative 1 - Using GciMkSEQUENCE and GciSetType

The individual values through out the structured value have to be created and the correct type set. It is also impossible to set the correct type for the inlined types since they are unknown.

...
value = GciMkSEQUENCE(1);
GciSetType(value, GcTD);

inner_seq = GciMkSEQUENCE(1);
/* GciSetType(inner_seq, ?); This is not possible since the inlined type is not available to the user. A generated no-name type exists but is not known. So the SEQUENCE will be untyped (only a SEQUENCE). This is not a problem with alternative 2. */

b = GciMkINTEGER(17);
GciSetType(b, GcMyINTEGERD);
GciSetField(inner_sequence, 1, b);
c = GciMkINTEGER(42);
GciSetType(c, GcMyINTEGERD);
GciSetField(value, 1, inner_seq);
GciSetField(value, 2, c);
...

Alternative 2 - Using EGciMkValue (Recommended Approach)

Using the EGciMkValue function makes it somewhat more readable, but what is more important is that the final value has the correct type throughout the structure (all done by the generated type information used in the call to EGciMkValue). All field names are also correct.

...
value = EGciMkValue(GcTD);
/* With this call the whole structure is created and the basic leaf values are only extracted and set ("filled in"). */

tmp = GciGetField(value, 1);
tmp = GciGetField(tmp, 1);
EGciSetINTEGER(tmp, 17);

tmp = GciGetField(value, 2);
EGciSetINTEGER(tmp, 42);
...

Available Functions

GciValue * EGciMkValue(int)

Takes the generated type identifier constant Gc<type>D and creates a proper value using all available type information generated. This function is faster than the EGciMkValueFromTypeName but the type identifier constants can potentially change their numeric value if new types are added to the test suite. Any depending encoder/decoders have to be recompiled if the generated type information changes. If generation dependent information is required, the EGciMkValueFromTypeName should be used.

Example 274

Given the type MyType, the call for constructing a value would be EGciMkValue(GcMyTypeD).

GciValue * EGciMkValueFromTypeName(const char* tname)

Same as EGciMkValue but it takes the (bare) name of the type.

Example 275

Given the type MyType the call for constructing a value would be EGciMkValueFromTypeName("MyType").

void EGciRmValue(GciValue *value)

This function deletes a constructed value.

GciStatus EGciAssign(GciValue *destination, GciValue *source)

Given the two values, which must be instantiated values of the same type, the source is assigned to the destination value.

GciStatus EGciSetMemberByName(GciValue *val, const char* name, GciValue *mem_val)

Sets the named member of a SEQUENCE, SET or CHOICE value to the given value (mem_value). This is the same as doing an extraction followed by an assignment.

GciStatus EGciSetEmptySET_OF(GciValue *value)

Sets the value to the defined state. That is, it is an empty SET OF value.

GciStatus EGciSetEmptySEQUENCE_OF(GciValue *value)

Sets the value to the defined state. That is, it is an empty SEQUENCE OF value.

GciStatus EGciSetOMIT(GciValue *value)

Sets the given optional value as omitted.

GciStatus EGciSetBOOLEAN(GciValue *value, Bool v)

Sets a constructed value of (base) type BOOLEAN to the given boolean value.

GciStatus EGciSetSTRING(GciValue *value, const char *)

Sets a constructed value of any string base type (BITSTRING, OCTETSTRING, IA5String, etc.) to the given string value.

GciStatus EGciSetINTEGER(GciValue *value, int number)

Sets a constructed value of (base) type INTEGER to the given integer value.

GciStatus EGciSetNULL(GciValue *value)

Sets a constructed value of (base type) NULL to the NULL value.

GciValue * EGciSetENUMERATEDByName(GciValue *val, const char* enum_name)

Sets the actual value of the ENUMERATED value to one of its declared named numbers. For example, EGciSetENUMERATEDByName(gcivalue, "foo"), where "foo" is one of the named numbers in the type.

Example 276

EType ::= ENUMERATED { first, second, third }

GciValue *eval = EGciMkValue(GcETypeD);
EGciSetENUMERATEDByName(eval, "second");

const char * EGciGetENUMERATEDName(GciValue *value)

Retrieves the name of the current value.

Example 277

Continuing Example 276, a call to EGciGetENUMERATEDName(eval) would return the string "second".

GciValue * EGciGetChoiceMemberByName(GciValue *value, const char *name)

CHOICE values are not constructed all the way down to its leaf value since the information about the selected field is not available in the type information. When this function is called, the value construction is continued and proper value will be constructed for the selected CHOICE field (name) and the value can then be assigned properly.

GciValue * EGciGetChoiceMemberByTag(GciValue *value, GciTagClass tag_class, int tag)

Equivalent to EGciGetChoiceMemberByName but the unique tag of the choice element instead of the name is used.

GciValue * EGciGetSEQUENCE_OFElement(GciValue *value)

Constructs a new value given the underlying/contained type of the SEQUENCE_OF type. The newly constructed value must be appended using the GciAddElem function.

GciValue * EGciGetSET_OFElement(GciValue *value)

Constructs a new value given the underlying/contained type of the SET_OF type. The newly constructed value must be appended using the GciAddElem function.

Bool EGciGetAnyValue(GciValue *value)

Predicate to check if the value is ANY value attribute. Note that this has nothing to do with the GciGetANY function since that function operates on values of the type ANY.

Bool EGciGetAnyOrOmit(GciValue *value)

Predicate to check if the value is ANYOROMIT value attribute.

Bool EGciGetIfPresent(GciValue *value)

Predicate to check if the IF_PRESENT value attribute is specified for this value.

Bool EGciGetDefault(GciValue *value)

Predicate to check if the instatiated value comes from the default value of the type or not.

Error Handling

If an error occurs during execution, the error state is propagated up through the call stack and error information is added. An error has occurred when either the EGciGetErrorCount function returns a number greater than zero or a Gci/EGci-function call has returned GciNotOk. The error message is retrieved by EGciGetLastErrorMessage and reset by EGciClearError.

unsigned int EGciGetErrorCount()

Retrieve the current number of errors detected by the run time system.

const char* EGciGetLastErrorMessage(void)

Retrieve the last error message in text form.

void EGciClearError()

Clear the error state of the run time system.

Miscellaneous

void EGciDumpValue(FILE *stream, const char *prefix, GciValue *value, const char *suffix)

Prints the given value on stream. The prefix and suffix are printed before and after the value dump respectively.

void EGciSetDebugStream(FILE *stream)

Set the debug stream where logging will be made. It is set to stderr by default.

Examples

MyString ::= IA5String
EmailAddress ::= MyString
SnailmailAddress ::= SET { street MyString, number INTEGER }
AddressKind ::= ENUMERATED { email, snailmail }

-- This represents a contact with name and an address.

Contact ::= SEQUENCE {
name MyString,
address_kind AddressKind
address CHOICE {
email EmailAddress,
snailmail SnailmailAddress
}
}

A value would be constructed in the following way:

GciValue *tmp;
GciValue *address;
CciValue *contact;

contact = EGciMkValue( GcContactD);

tmp = EGciGetFieldByName(contact, "name");
EGciSetSTRING(tmp, "Elvis");

tmp = EGciGetFieldByName(contact, "address_kind");
EGciSetENUMERATEDByName(tmp, "snailmail");

address = EGciGetFieldByName(contact, "address");
address = EGciGetChoiceMemberByName(address, "snailmail");
tmp = EGciGetFieldByName(address, "street");
EGciSetSTRING(tmp, "High road");
tmp = EGciGetFieldByName(address, "number");
EGciSetINTEGER(tmp, 42);


The Adaptation Framework

Introduction to the Adaptation Framework

The Adaptation Framework, technically referred to as "ACM", is a collection of the functions that are needed to write a full-fledged adaptation implemented by plug-in libraries that can be used "as is". Currently, the following plug-in modules are included in the TTCN suite distribution:

  • TCP/IP socket communication implementation.
  • Standard system-time timer implementation.

This means that if the target system uses TCP/IP to communicate, the adaptation writer can simply use the Adaptation Framework right from the box to get the IUT connected to generated code with minimal amount of work.

Note that the Adaptation Framework is provided as a standardized way to implement the GCI interface. This means that the Adaptation Framework does not replace GCI, but rather complements it. To build the adaptation, simply implement the needed GCI functions by calling the counterpart framework functions that use the compiled-in implementations for the low level code; in this distribution this would be the TCP/IP protocol for communication and a standard system time timer implementation. On the other hand, this means that one can continue to implement adaptations without using the framework altogether, the old way, and old adaptations will continue to work as before.

Examples of usage

The included adaptation residing under the ACM/ subdirectory contains an implementation of the GCI layer by framework functions and is instructive in displaying the way to work with framework functions.

Function reference

Communication data types

Defined constant | Meaning
ACM_ADDRESS_TCPIP | The address type specifier used with the TCP/IP implementation of the Adaptation Framework for the GciAddress type.
Defined constant values

More values will be defined in the file acm.h once more plug-in packages are available. The user can also specify new values for his/her own communication modules.

Note:

Values 0-100 are reserved for use by Telelogic.

Communication role of the executable test suite

typedef enum
{
ACMClient,
ACMServer
} ACMConnectionType;

The enumerated type ACMConnectionType is used when calling
ACMConnect() to select whether the generated code should act as a server or client to the IUT.

Communication primitives

These functions are used to implement the GCI communication functions.

Initializing the communication and timer package

GciStatus ACMInit(const GciTime* max_timeout,
GciTimeUnit time_tick_unit)

Must be called after GCIInit() but prior to any use of the ACM communication or timer primitives. The first argument, max_timeout defines the maximum amount of time the system will wait in blocked state for any timer. Setting this to a low value enables the possibility to write a polling snapshot function. A defined constant exists by the name of ACM_ONE_YEAR_IN_MINUTES that can be used as a default "big enough" number argument.

The second argument, time_tick_unit, depicts the unit of time (in GCI time units) used internally in the run-time system. Since all internal timer data is converted to and from this unit, it is important to set this to a value that encompasses approximately the value range of the time-out values used in the test suite. This parameter also restricts the maximum time that is available for a time-out value, as depicted below.

Internal unit | Maximum length of time before timer wraps
Gcips | 4.3 seconds
Gcins | 71 minutes
Gcius | 49 days
Gcims | 136 years
... | ...

Resetting the Run-time System

GciStatus ACMReset()

This function cancels all timers, and resets all timer queues and PCO buffers. It is typically called before starting a new test case to ensure that all old data is removed, and to put the run-time system into an initial mode.

Registering the GciTimeout Function

GciStatus ACMRegisterTimeoutHandler(ACMTimeoutHandler
timeouthandler)

This function needs to be supplied with a pointer to the GciTimeout() function before using the ACMSnapshot() function, since ACMSnapshot() calls the timeout function automatically for every timer that has expired.

Registering the GciReceive Function

GciStatus ACMRegisterReceiveHandler(GciReceiveHandler
receive_callback)

This function needs to be supplied with a pointer to the GciReceive() function before using the ACMSnapshot() function, since ACMSnapshot() calls the receive function automatically for every data packet that has arrived.

Registering the Active Decode Function

GciStatus ACMRegisterDefaultDecodeHandler(ACMDecodeHandler
decode_handler)

The function ACMSnapshot() calls GciReceive() automatically for every data packet that are ready to be received. In order to do this, however, a decode function needs to be registered that can decode the incoming data from its transfer syntax to the internal GCI value representation. This is easily done by the above call. Note that this opens the possibility to switch decoding during runtime, since any decode function that fulfills the requirements are eligible to be registered as the default decoder at any time. See "Encoding, and in Particular Decoding within ACM and GCI" for details on how to construct the decode function(s).

Registering a Specific Decode Function for a PCO

GciStatus ACMRegisterDecodeHandler(ACMDecodeHandler
decode_handler,
GciPCOID pco_id)

This function is similar to the previous function, but it enables a certain decode function to be connected with a certain PCO. This means that the function ACMSnapshot() will be able to use different decoding mechanisms depending on which PCO the message was received from. See "Encoding, and in Particular Decoding within ACM and GCI" for details on how to construct the decode functions.

Connecting to a Communication Port

GciStatus ACMConnect( GciPCOID pco_id,
GciAddress* address,
ACMConnectionType type,
unsigned int buffer_size)

This function maps the PCO identifier value internally to an external communication port and makes the connection. This makes it possible to use the PCO identifier in all subsequent calls, which makes the code quite clear.

In addition, we need to supply what type of role the ETS will have in the communication with the IUT - as a server (ACMServer) or as a client (ACMClient).

The buffer_size argument defines the largest possible buffer (in bytes) that can be received in one chunk. This should usually be set to the largest buffer needed to encode a value in the current value representation.

Disconnecting a Communication Port

void ACMDisconnect(GciPCOID pco_id)

This function disconnects a previously opened communication link.

Sending a Message

GciStatus ACMSend(GciPCOID pco_id, GciBuffer* buffer)

This function sends an encoded buffer on the designated PCO. When sending, the function will block until the entire buffer have been sent, or an error has occurred. This is simply because it is preferred to see the send operation as an atomic operation without possible race conditions.

Receiving a Message

GciStatus ACMReceive(GciPcoID pco_id, GciBuffer* buffer)

This function tries to receive a message from the designated PCO. If successful, the received encoded byte stream is inserted to the provided buffer, which is allocated inside the function.

Retrieving the Position of the First PCO with Received Data

GciPosition ACMGetReceivedPCOPos()

This function returns the position of the first PCO to have data ready for receiving. The return value is simply meant to be used as an iterator argument to the ACMGetNextReceivedPCO() function. If the returned value is zero, there are at this time no PCO that has received data.

Retrieving the position of the next PCO with received data

GciPCOID ACMGetNextReceivedPCO(GciPosition* position)

This function returns the numeric identifier of the PCO that has data ready to receive, and updates the position variable to point to the next PCO with data to receive. If the position is zero, no further PCO has data to receive.

A simple loop that checks all PCO's for receive can be written in a similar manner to the timer iteration described below in "A Loop That Fetches All Expired Timers and Prints Their ID Numbers" .

Timer Primitives

Timer handling can be implemented in various ways. The package makes it easy for the adaptation writer to use timers, by encapsulating functionality that used to be implemented in a fairly standard way in GciSnapshot() implementations over and over again. Instead of using cryptic timer structures the user can now use the GCI identifier for the needed timer in a number of timer access functions. Time itself is fetched from the system clock, normalized to zero at the time of starting the execution.

Starting a Timer

GciStatus ACMStartTimer(GciTimerID timer_id,
GciTime timeout)

This function starts the designated timer with the given expiration time. If the timer has not yet been created, this call will create it. If the timer was running or expired it is simply restarted.

Cancelling a Timer

GciStatus ACMCancelTimer(GciTimerID timer_id)

This function transfers the designated timer from the active list to the list of stopped timers. This call needs to be performed once a timer has been noted as expired (via GciTimeout() in GciSnapshot() for instance)

Cancelling All Timers

GciStatus ACMCancelAllTimers()

This function cancels all timers, even if they are already expired.

Reading the Value of a Timer

GciStatus ACMReadTimer( GciTimerID timer_id,
GciTime* timer_before_timeout)

This function places the current time of a given timer in the provided GciTime object.

Checking the Current Status of a Timer

GciStatus ACMTimerStatus(GciTimerID timer_id, GciTimerStatus* timer_status)

This function places the current status of the given timer in the status variable. Please refer to the declaration of GciTimerStatus for the various states of a timer.

Retrieving the Key to the First Timer That Has Expired

GciPosition ACMGetTimedOutPos()

This function retrieves the position to the first timer that has expired from a chronological list of expired timers. The return value is simply meant to be used as an iterator argument to the ACMGetNextTimedOut() function. If the returned value is zero, there are no currently expired timers.

Getting the Next Expired Timer

GciTimerID ACMGetNextTimedOut(GciPosition* position)

Given a position index (the index to the first timer is fetched with the ACMGetTimedOutPos() function), this function returns an expired timer and updates the position variable to point to the next timer in the list of expired timers. If the position value is equal to zero after this call, no more expired timers exist in the list.

Example 278 A Loop That Fetches All Expired Timers and Prints Their ID Numbers

. . .
GciPosition pos = ACMGetTimedOutPos()

while (pos != NULL) {
printf("Timer %d has expired!\n",          ACMGetNextTimedOut(&pos) );
}

Time Left Before the Next Timer Expires

GciStatus ACMTimeLeft(GciTime *time_before_timeout)

This function retrieves the actual time left before the next timer is due to expire. If one or more timers have already expired, the function returns zero as the time left. If no timers exist, or all timers have been stopped, the function returns GciNotOk.

Timer and PCO Handling with a Single Call

GciStatus ACMSnapshot()

For the hardened writer of many adaptations, this function offers a relief. Calling this function will wrap most GciSnapshot functionality into one call. Briefly, what the function performs internally is the following:

  1. Check all PCO/CP channels for received data.
  2. For each queue that contains fresh data, receive, decode it and call GciReceive() with the result.
  3. For each expired timer, call GciTimeout() with the expired timer's ID number, and move the timer to the list of stopped timers.
  4. Return status of the operations.

In effect, the simplest snapshot implementation can now look like this:

Example 279 The Simplest Snapshot in the World!

GciStatus GciSnapshot()
{
return ACMSnapshot();
}

Somewhere in the code, before calling ACMSnapshot() for the first time, it is also necessary to register three functions with ACM:

  • GciReceive()
  • GciTimeout()
  • A decode function.

This is due to the fact that ACMSnapshot() will possibly try to call these functions depending on the internal state. A good place to register these functions is close to the ACMInit() call:

.
.
ACMInit(max_timeout, ... );
.
.
ACMRegisterTimeoutHandler(&GciTimeout);
ACMRegisterReceiveHandler(&GciReceive);
ACMRegisterDefaultDecodeHandler(&DecoderFunction);

Waiting for the Next Event

GciStatus ACMWaitForEvent()

If more functionality is needed in the snapshot function, a mechanism for waiting for the correct amount of time is needed. This function sleeps until the next timer is due, or until data arrives on a PCO, whichever comes first, and returns with status GciOk, at which point the snapshot function can simply poll the input queues for data, and/or take the now arrived timeout. If no timers are running, the function returns after the maximum time to wait as defined in ACMInit( ... ). If this time is set to a small amount, we have a polling snapshot in effect.

Example 280 : The Same Snapshot but with Written Out Code

GciStatus GciSnapshot()
{
GciPosition expired_pos;
GciTimerID expired_timer;
GciPosition received_pos;
GciPCOID received_pco;
GciBuffer buffer;
GciValue* value;

/* Sleep until either a timer has expired
* or data is received. For a polling
* snapshot, remove this. */
if (ACMWaitForEvent() != GciOk) {
return GciNotOk;
}

/* First, check all timers. */
if (ACMSynchronizeTimers() != GciNotOk) {
return GciNotOk;
}
expired_pos = ACMGetTimedOutPos();

while(expired_pos != NULL) {
expired_timer =        ACMGetNextTimedOut(&expired_pos);
GciTimeout(expired_timer);
if (ACMCancelTimer(expired_timer) != GciOk) {
return GciNotOk;
}
}
/* Next, take care of the PCO's */

buffer.buffer =
(char *)malloc(sizeof(char) *                   MAX_ENCODING_BUFFER+1);
buffer.current_length = 0;
buffer.max_length = MAX_ENCODING_BUFFER;

received_pos = ACMGetReceivedPCOPos();

while(received_pos != NULL) {
received_pco =
ACMGetNextReceivedPCO(&received_pos);
if (ACMReceive(received_pco, &buffer) != GciOk)
{
return GciNotOk;
}
value = GeneralDecode(&buffer);
if (value != NULL) {
if (GciReceive(received_pco, value)!= GciOk) {
return GciNotOk;
}
}
else {
fprintf(stderr,
"Transfer syntax error on PCO %s\n",
GciGetPCOName(received_pco) );
return GciNotOk;
}
}
return GciOk;
}

Retrieving the Current System Time

GciStatus ACMCurrentTime(GciTime* current_time)

This function retrieves the time of the system clock in the instance of the function call.

Error Handling

The error handling of the Adaptation Framework will be straightforward to those familiar with the err_no paradigm of C. Every time an error occurs, the function sets an internal error code and returns
GciNotOk. The error code can then be retrieved either as an enumerated value, or as a descriptive string.

The error codes can be found in the file acm.h.

Setting the Error Code

ACMSetLastError(ACM_Error_Number errornumber)

Sets the error number to the given value.

Retrieving the Error Code of the Last ACM Error

ACM_Error_Number ACMGetLastError()

Returns the last error code as an enumerated value.

Retrieving the Error String of the Last ACM Error

const char* ACMGetLastErrorMessage()

Returns the last error code as a printable string.


Completing the Adaptation

The generated code has to be extended before it is complete in order to test the intended implementation. This section describes how to make these extensions.

Figure 275 displays in a simple way the anatomy of an executable test suite.

Figure 275 : The anatomy of an executable test suite

When code is generated by the code generator, it does not know anything about the system it is about to test. It assumes that it will have access to certain functions, implemented by the user. This is the "Test Support Functions" module in Figure 275.

One important thing to remember is that the previously defined interface called GCI, is a standardized set of functions.See "The GCI Interface" . Adaptation should be made using the functions and data types defined by that interface.

The Test Support Functions

This is the "glue" between the TTCN Runtime Behavior and the IUT. It is a set of functionality (functions) that is adaptation specific and should be provided by the user.

The following areas have to be covered and they are described in more detail in the sections they refer to.

Implementation and Handling of Timers

The timers defined in the Test Suite must have a real representation in the test environment. The TTCN Runtime Behavior will, when necessary, ask the adaptation about the status of a timer. See "Representation and Handling of PCO and CP Queues" .

Representation and Handling of PCOs [and CPs]

Messages are communicated through Points of Control and Observation and Connection Points. The actual buffering of incoming IUT messages must be supplied by the adaptation. See "Representation and Handling of PCO and CP Queues" .

Communication with Test Equipment [and PTCs]

To be able to test the IUT at all, there must be actual communication channels to and from it. The actual communication is of course totally depending on the system environment. See "IUT Communication" .

Encoding and Decoding

Values in the test suite (constraints, variables, constants, etc.) must be properly encoded and decoded for sending them to the IUT. The actual protocol for encoding decoding is up to the user. See "Encoding and Decoding" and "Encoding and Decoding Using BER" for more details.

Implementing the Adaptor the Efficient Way - the Adaptation Framework

The implementation of timer handling and communication primitives can be made by calls to the Adaptation Framework API, which permits the underlying "hard" protocol and timer implementation to change without having to change the high-level adaptation code. See "The Adaptation Framework" for a thorough explanation.

Timers

Timers need some special attention. As timers are implemented differently on different systems the implementation of the timers might differ. See the timers adaptation template in the installation for ideas.

Timers are simply a number of constructions to keep track of each of the test suite timers. In the generated code a timer is represented by an integer descriptor which uniquely identifies it. The timer implementation supplied with the Adaptation Framework implements the timeout functionality by maintaining an ordered list of the running timers, which means that retrieving the time left to timeout and the next timer to expire are quick operations.

To refresh the current status of timers, the timer lists need to be synchronized to the system time. This is made automatically by the snapshot function ACMWaitForEvent() (more on this function later) or can be made explicitly by a call to the function ACMSynchronizeTimers(). This function simply checks all running timers with the system clock, moving timers that are due to the list of expired timers.

There are four functions to consider regarding timers:

GciStartTimer

GciCancelTimer

GciReadTimer

GciSnaphot

The interfaces to timers that can (and should) be called in the TTCN Runtime Behavior are:

GciTimeout

GciGetNoOfTimers

GetTimer

GciGetTimerName

GetTimerIndex

For details concerning these functions, see "GCI C Code Reference" .

The Adaptation Framework interfaces to timer functionality that can be used to implement the GCI functions are:

ACMStartTimer

ACMCancelTimer

ACMCurrentTime

ACMGetTimedOutPos

ACMGetNextTimedOut

ACMReadTimer

ACMTimeLeft

ACMTimerStatus

ACMWaitForEvent

These functions map to a real-time timer implementation that is provided with the installation of TTCN suite and can be used "as-is". See Release Notes for details on which platforms are supported by this timer package.

Timer Adaptation Example

The timers adaptation template is the simple adaptation template with timers implemented. It demonstrates in general how to use the Adaptation Framework to implement timer functionality, and in particular the use of the call ACMSynchronizeTimers() that must be used in snapshot when ACMWaitForEvent() can't be used.

IUT Communication

From an abstract point of view, sending and receiving is done over PCOs (Points of Control and Observation). The physical representation of these PCOs has to be defined by the user. It can be shared memory, serial communication, sockets, etc. This, of course, is only done on the controlling side. The PCOs have to be connected somewhere to the test equipment and the responsibility for this is put upon the user.

The GCI functions that must perform the communication is (at least):

GciSend

GciReceive

For details concerning these functions, see "GCI C Code Reference" .

Representation and Handling of PCO and CP Queues

PCOs are constructions to handle the PCO queues. Each PCO should have buffers for sending and receiving, a method for retrieving the status of the receive buffer and additional information such as channels and ports must be provided for the physical channels.

If the ETS is to run within the test equipment, i.e. the communication between the ETS and the IUT resides within the test equipment, the ETS has to be moved (cross compiling or if possible compiling within the test equipment).

This queue initialization should of course be made before any test case are run. The function that concerns the PCO's and CPs are:

GciSnapshot

GciSend

GciSnapshot() can be implemented using for instance ACMWaitForEvent(), and GciSend() can be implemented using ACMSend(). Today, the ACM layer builds upon a TCP/IP socket implementation but other protocol implementations can be easily added.

The interface that should be used when a message has been received (after proper decoding) in the TTCN Runtime Behavior is:

GciReceive

Note that if the ACM layer function ACMWaitForEvent() is used in the snapshot function, the user never has to call GciReceive() since this is done automatically from within ACMWaitForEvent()!

For details concerning these functions, see "GCI C Code Reference" .

Encoding and Decoding

tBuffer is the subsystem of UCF that is used to represent values of ASN.1 types in the transmitted bit pattern. This section describes the interface for tBuffer.

Functions

To invoke functions of tBuffer, the following macros are to be called:

Initialization of buffer

You should initialize tBuffer before using it.
void BufInitBuf(tBuffer buf, tDirectionType dirtype, UCFStatus status)

tBuffer buf | Buffer for data storage
tDirectionType dirtype | Data writing order (DIRECT or REVERSE).
UCFStatus status | Status of initialization. Variable "status" is equal to UCF_Ok if no errors were encountered during initialization or an error code otherwise.

Note: Buffer direction mode

REVERSE modes is not supported in the buffers anymore, although the prototype of the BufInitBuf function still includes the dirtype parameter for backwards compatibility. The direction mode parameter is always ignored when calling the BufInitBuf function.

Closing of buffer

You should close tBuffer after working with it.
void BufCloseBuf(tBuffer buf)

tBuffer buf
Buffer

Initialization in write mode

This function initializes tBuffer in write mode. You can write data to the buffer after calling this function.
UCFStatus BufInitWriteMode(tBuffer buf)

Initialization in read mode

This function initializes tBuffer in read data. You can read data from the buffer after calling this function.
UCFStatus BufInitReadMode(tBuffer buf)

Closing write mode

This function closes write mode of tBuffer. You should call this function after the `write to buffer' operation is completed.
void BufCloseWriteMode(tBuffer buf)

Closing read mode

This function closes read mode of tBuffer. You should call this function after reading from the buffer is finished.
void BufCloseReadMode(tBuffer buf)

Getting direction type of the buffer

This function returns the direction type of tBuffer.
tDirectionType BufGetDirType(tBuffer buf)

Note: No REVERSE mode

REVERSE mode is not supported in the buffers anymore, although the BufGetDirType function is still present in the buffer interface for backwards compatibility. It will always return DIRECT mode.

Creating copy of buffer

This function makes a copy of the buffer.
UCFStatus BufCopyBuf(tBuffer dst, tBuffer srs)

tBuffer dst | destination buffer
tBuffer src | source buffer

Getting the data byte length

This function returns the buffer's data length in bytes.
tLength BufGetDataLen(tBuffer buf)

Getting the data bit length

This function returns the buffer's data length in bits.
tLength BufGetDataBitLen(tBuffer buf)

Getting the available length

This function returns the maximal data length you can write into the buffer in one piece (in bytes).
tLength BufGetAvailableLen(tBuffer buf)

Getting byte

This function reads one byte from the buffer. The buffer should be initialized in read mode.
unsigned char BufGetByte(tBuffer buf)

Getting data segment

This function reads a data segment from the buffer. The buffer should be initialized in read mode.
unsigned char* BufGetSeg(tBuffer buf, tLength seglen)

tBuffer buf | Buffer to read from
tLength seglen | Requested data length

Peeking byte

This function peeks (reads, but does not remove) one byte from the buffer. The buffer should be initialized in read mode.
unsigned char BufPeekByte(tBuffer buf)

Peeking data segment

This function peeks (reads, but does not remove) a data segment from the buffer. The buffer should be initialized in read mode.
unsigned char* BufPeekSeg(tBuffer buf, tLength seglen)

tBuffer buf | Buffer to read from
tLength seglen | Requested data length

Putting byte

This function writes one byte into the buffer. The buffer should be initialized in write mode.
void BufPutByte(tBuffer buf, unsigned char byte)

tBuffer buf | Buffer to write into
unsigned char byte | Byte to write into buffer

Putting data segment

This function writes a data segment into the buffer. The buffer should be initialized in write mode.
void BufPutSeg(tBuffer buf, unsigned char* data, tLength seglen)

Putting bit

This function writes one bit into the buffer. The buffer should be initialized in write mode.
void BufPutBit(tBuffer bud, unsigned char bit)

tBuffer buf | Buffer to write into
unsigned char bit | Value of bit (0 or 1)

Getting bit

This function reads one bit from the buffer. The buffer should be initialized in read mode.
unsigned char BufGetBit(tBuffer buf)

Putting bits

This function writes bits into the buffer. The buffer should be initialized in write mode.
void BufPutBits(tBuffer buf, unsigned char bits, unsigned char num)

tBuffer buf | Buffer to write into
unsigned char bits | Sequence of bits
unsigned char num | Number of bits in sequence (num <= 8)

Getting bits

This function reads bits from the buffer. The buffer should be initialized in read mode.
unsigned char BufGetBits(tBuffer buf, unsigned char num)

tBuffer buf | Buffer to read from
unsigned char | Number of bits (num <= 8)

Putting padding bits

This function writes padding bits in PER ALIGN variant of encoding. The buffer should be initialized in write mode.
void BufPutAlign(tBuffer buf)

Getting padding bits

This function reads padding bits in PER ALIGN variant of encoding. The buffer should be initialized in read mode.
void BufGetAlign(tBuffer buf)

Set encoding variant (PER only)

This function sets the encoding variant.
void BufSetEncVar(tBuffer buf, UCFEncVariant encVar)

UCFEncVariant encVar
Encoding variant ( UCF_Align, UCF_Unalign or UCF_NoEndPad )

Get encoding variant (PER Only)

This function returns the encoding variant.
UCFEncVariant BufGetEncVar(tBuffer buf)

Setting up error catcher

This function sets up error catcher. Returns 0 or code of error if any.
unsigned int BufSetCatcher(tBuffer buf)

Getting error mode

This function gets error mode (bem_Off or bem_On).
tBufferErrorMode BufGetErrorMode(tBuffer buf)

Supported ASN.1 Types

  • BOOLEAN
  • INTEGER
  • ENUMERATED
  • REAL
  • OBJECT IDENTIFIER
  • NULL
  • BIT STRING
  • OCTET STRING
  • IA5String
  • NumericString
  • PrintableString
  • VisibleString
  • UTCTime
  • GeneralizedTime
  • SEQUENCE
  • SET
  • SEQUENCE OF
  • SET OF
  • CHOICE
  • Tagged types
  • Open types

Encoding, and in Particular Decoding within ACM and GCI

The standard way to implement the encoder and decoder functions are to put at least one function of each in the file encoder.c and declare them in the file encoder.h. With every adaptation that is provided with the TTCN suite installation are those files included, often with empty encode/decode functions where the user is supposed to enter the appropriate functionality. The functions should be of the following structure:

The Encoding Function

GciStatus Encoder_<name>(const GciValue*,
GciBuffer** )

If encoding was successful, the GciBuffer should be loaded with the encoded data and GciOk returned by the function. Otherwise, the function should return GciNotOk.

The Decoding Function

GciStatus Decoder_<name>(const GciBuffer*,
int*,
GciValue**)

If decoding was successful, the GciValue should be loaded with the decoded GCI value, the integer should contain the number of bytes that were consumed in the decoding process and the return status GciOk. Upon failure, the function should simply return GciNotOk.

Note that several encode/decode functions can exist, and the user can switch between them at will, either by calling different functions from GciSnapshot() or by registering different functions prior to calling ACMSnapshot(). See "Registering the Active Decode Function" for details.

General

A test suite has no knowledge of the encoding and decoding rules of the actual application protocol. The definition of signal components and the description of the signal flows are done in an abstract and high-level manner. The physical representation of the signal components and the definition of the actual transfer syntax is not defined within the test suite.

The encoding and decoding rules (functions) simply define a common transfer syntax between the test equipment and the executable test suite.

It is up to the user to write his/her own encoding and decoding rules using the GCI value representation. Even if the TTCN to C Compiler comes with an adaptation template that includes a general encoder and decoder, these rules can not be used at all times.

For test applications that need to send the same type of messages back and forth through a communication channel, the encoding and decoding functions must be related to each other in such way that the decoding function is the inverse function of the encoding function. This gives the following simple rule:

Message = Decode( Encode ( Message ) )

This simply states, that if you decode an encoded message, you will get the original message back.

For applications that send and receive messages of different types (for example an application sending commands to an interface one way and receiving command results the other way), the encoding and decoding rules might not be related at all.

It is up to the user to identify how he/she needs to encode and decode messages to successfully be able to communicate with his/her test equipment.

Encoding and Decoding Using BER

TTCN Suite can generate encode/decode function definitions, that give an opportunity for representing values of each ASN.1 type as a string of eight-bits octets and transfer them between the environment and the ETS. TTCN Suite now have support for BER (Basic Encoding Rules) standard, defined in X.690 for the subset of ASN.1 that is defined by TTCN.

BER Encoder/Decoder Support Library

The BER support comes in the form of a static library that supports encoding/decoding functionality of ASN.1. Profiles of all the functions that a user can use are located in the ucf.h in the static files directory. This file should be included in the adaptation and the library should be linked together with the adaptation.

The library contains two basic functions that provide functions for encoding/decoding types, computing length of values and buffer handling procedures: BEREncode(...) and BERDecode(...).

How to Use BER Support in the TTCN Suite?

First, select Generate BER encoders/decoders in the Make options dialog. A file will be generated called asn1ende.h in your target directory. This file defines the encoding and decoding functions for the ASN.1 definitions in the test suite.

Second, you should implement the usage of the encoding functions in your adaptor.c. This is done in the GciSend and GciSnapshot functions. Also, you should define buffers and initialize them (this can be done in main.

The generated file <ModuleName_of_ASN.1-specification>_asn1icoder.h contains the encoding/decoding function definitions for ASN.1 objects in the Test Suite. For example, if you have ASN.1 ASP Type definition by name of ASPType1, two functions will be generated:

UCFStatus Encode_ASPType1(tBuffer, GciValue*);

UCFStatus Decode_ASPType1(tBuffer, tLength*, GciValue**);

The first parameter of the encode function is the buffer where the encoded data is placed. The decoding is made from the buffer to a GCI value.

The encoding/decoding functions are specific for the ASP/PDU types in question so when calling them in GciSend and GciSnapshot, you need to make sure that they are called with a value of the correct ASP/PDU type. One way to get around this problem is to define a single ASP/PDU type that is a CHOICE of all types that you are sending or receiving in your test suite.

Example

For example, we have a test suite with ASN.1 ASP Type

ASPType1 ::= INTEGER

And ASN.1 ASP constraint of ASPType1 named

ASPCon1 ::= 5

We have PCO named PCO1 and dynamic behavior like this:

PCO1 ! ASPType1 | Constraint: ASPCon1
PCO1 ? ASPType1 | Constraint: ASPCon1

And we want to use BER for encoding/decoding. After code generation we have a <ModuleName_of_ASN.1-specification>_asn1icoder.h file with the following definitions:

tLength Encode_ASPType1(tBuffer, GciValue*);

tLength Decode_ASPType1(tBuffer, GciValue**);

So in our adaptation file we need to declare, initialize and close BER buffers:

tBuffer InBuffer;
tBuffer OutBuffer;
.
. (rest of the adaptation)
.
int main(int argc, char* argv[])
{
BufInitBuf(InBuffer, DIRECT, status);
BufInitBuf(OutBuffer, DIRECT, status);
.
. (ETS control)
.
BufCloseBuf(InBuffer);
BufCloseBuf(OutBuffer);
return 0;
}

In GciSend() we should initialize buffer in WriteMode and encode value:

GciStatus GciSend( int pcod, GciValue* object )
{
UCFStatus status;
BufInitWriteMode(OutBuffer);
.
.
Encode_ASPType1(OutBuffer, object);
status = Encode_ASPType1(OutBuffer, object);
if(status != UCF_Ok)
{
UCFPrintErrorMessage(stderr,status);
/* warning or exit */
}
.
.
BufCloseWriteMode(OutBuffer);
return GciOK;
}

In GciSnapshot() we should initialize buffer in ReadMode and decode value:

GciStatus GciSnapshot( )
{
UCFStatus status;
tLength DecLength;
BufInitReadMode(InBuffer);
.
.
Decode_ASPType1(InBuffer, &result);
status = Decode_ASPType1(InBuffer, &DecLength, &result);
if(status != UCF_Ok)
{
UCFPrintErrorMessage(stderr,status);
/* warning or exit */
}
.
.
BufCloseReadMode(InBuffer);
return GciOK;
}

How to Use the PER Support in the TTCN Suite

The PER support is used almost exactly like the BER support, so read above first to learn how to use the BER support. The PER Encoding/Decoding functions have been changed and now return a UCFStatus value:

UCFStatus Encode_ASPType1(tBuffer, GciValue*)

UCFStatus Decode_ASPType1(tBuffer, tLength*, GciValue**)

The primary difference to the BER support is that the PER support includes supporting different variants of PER. The variants supported are Unalign, Align and NoEndPad with the Unalign variant being the default. The Unalign and Align variants are, just like BER, eight-bit octet-oriented, but the NoEndPad variant is bit oriented which necessitates use of the bit-oriented access to the buffer instead of the byte-oriented access.

The mechanism to select PER encoding variants is based on the use of pre-processor symbols. By defining the symbol UCF_PER_DEFAULT_ENCODING_VARIANT to the value associated with the selected encoding variant before including the asn1ende.h file, all types will get the selected encoding variant unless explicitly overridden.

Overriding the default encoding variant can be done on a per type basis by defining the pre-processor symbol EncodingVariant_<type name> to the selected variant value before including the asn1ende.h file.

The following example shows a snippet of the adaptor.c file in a situation where all types but the type Type1 is to be encoded/decoded with the Align variant and Type1 is to use the Unalign variant.

Example 281 : Selecting PER encoding variant

#define UCF_PER_DEFAULT_ENCODING_VARIANT UCF_Align
#define EncodingVariant_Type1 UCF_Unalign
#include <asn1ende.h>

The Adaptation Framework

To make it even easier to connect the generated code to "the real world", the Adaptation Framework (ACM) is introduced, a platform-independent API that encapsulates communication and timer handling provided by plug-in components. These components can be communication protocol implementations, simulated timer modules, etc. and can easily be replaced without having to rewrite the adaptation - provided the Adaptation Framework has been used to implement the GCI functions in the adaptor.

Currently, the TTCN suite is delivered with the following plug-in modules for the framework:

  • A TCP/IP socket communication implementation.
  • A system-time timer package.

This means that if the adaptation is written using the Adaptation Framework, the generated code can instantly be used with TCP/IP communication. As the framework also hides all internal mechanisms of the run-time system, the resulting adaptation will be easier to maintain, more general and much smaller in size.

Example 282 : An Implementation of GciSend with ACM

GciStatus GciSend (int pcod, GciValue* msg)
{
GciBuffer encoded_value;
GciStatus status;

encoded_value.buffer = (char *) malloc( sizeof(char) * MAX_ENCODING_BUFFER + 1);
encoded_value.current_length = 0;
encoded_value.max_length = MAX_ENCODING_BUFFER;

status = Encode(&encoded_value, msg);
if (status != GciOk) {
fprintf(stderr, "%s\n",
ACMGetErrorMessage(ACMGetLastError()));
return GciNotOk;
}
status = ACMSend(pcod, &encoded_value);
free(&encoded_value);

if (status != GciOk) {
fprintf(stderr, "%s\n",
ACMGetErrorMessage(ACMGetLastError()));
return GciNotOk;
}
return status;
}

Adaptation Templates

An empty adaptation is copied to the code directory if the user has no prior adaptation.

It is up to the user to implement the functions in the GCI operational interface. These functions are called from the TTCN runtime behavior and should not be removed even if they are empty.

The function bodies and declarations are found in the empty adaptation files, but the function bodies are empty. They only contain a print statement about the function not being implemented.

The ACM adaptor also uses the Adaptation Framework for communication and timer handling and is a good example to study on how to use the Adaptation Framework to implement GCI functions.

Auxiliary Adaptation Functionality

This section describes some extra functionality which is included in the adaptation templates.

FILE* logStream;

This is the stream to where log messages are written. The default value is stdout and is set in the main function, but can be set to whatever stream the user wishes to use.

extern const int Gc<tablename>D = {int}

Constant numbers for all tables (test case table, PCO table, timer table, etc...) in TTCN. Used to search in the IcSymTab array (see symbol table below). An example is for GcTestCaseD = 517.

The simple adaptation template (in the installation) includes all empty functions for the previously described GCI operational functions to be defined by the user.


38 Error Messages in the TTCN Suite

This chapter contains a general description of how error messages in the TTCN suite are structured, information about why some error messages are accompanied by a message on the standard output stream and information about how some error messages should be interpreted.

However, this chapter does not provide detailed information about specific error messages.


Error Messages

All user actions can potentially lead to an error, either because the user has made an improper action or because some system imposed limitation has been violated.

Note that all messages are not necessarily error messages, there are query and information messages as well.


The Structure of Error Messages

Error messages are based on information from three separate sources:

  1. Tools/commands
  2. TTCN Core94
  3. System

The first part is always present in an error message but the other two may be inapplicable to some error messages.

Example 283

Open: Operation failure
Can not open the file /home/users/user/suite.itex-lock
Permission denied

The example above notifies you about a failed attempt to open a test suite due to you insufficient privileges to create the lock file that should automatically be created when a test suite is opened or created. Observe that as the lock file is created before any attempt is done to open the test suite, the error messages often refer to that file instead of the test suite files.

The following are examples of when the second and third parts are missing and when the third part is missing respectively.

Example 284

Replace: Illegal search pattern: \(foo

Example 285

Find table: Can not open foo
No such object


Additional Error Messages on Standard Error

The reason for additional messages on standard error in some situations, is that some functionality is accomplished by calling shell commands. If any of those shell commands fail, they write a short message to the standard error output stream. Those messages can sometimes provide additional information about why the error occurred.

Messages When Starting the TTCN Suite

When starting the TTCN suite some error messages referring to OSF (e.g. osfBeginLine etc.) may be displayed. These messages indicate a problem in the installation related to the file XKeysymDB.


The Meaning of Error Messages

Sometimes the error messages may be a bit difficult to understand. The following list is an attempt to give some additional clues to why some errors occur and what the error messages mean:

  • Unable to display the error message directly
    Please check the end of the log
    This message signifies that the system kernel do not support shared memory. The remedy is to rebuild the kernel with System V IPC support and reboot the machine. Until that is done the work-around is to look in the log for the error message.
  • Messages containing may not or can not usually signifies that something is not allowed by the TTCN language. See the examples below.

Example 286

Copy: Operation failure
May not COPY

Note:

The reason for a failed cut or copy operation may be that the selection contains items that cannot sensibly be pasted together.

Example 287

Rename: Can not rename Declarations Part

Example 288

May not edit name
Insert TreeHeader: Can not create tree header

Example 289

This table may not contain treeheaders


39 Languages Supported in the TTCN Suite

The the TTCN suite editing tools support TTCN and ASN.1 as defined in the TTCN standard. The TTCN to C compiler on the other hand has limitations on its ASN.1 coverage. See "TTCN ASN.1 BER Encoding/Decoding for further details on the restrictions that apply.

The language supported by the TTCN suite covers the whole of TTCN and the whole of ASN.1 as it is used in TTCN.

This chapter describes the TTCN and ASN.1 EBNF grammar supported by the TTCN suite and the additional static semantics supported by the TTCN suite.


The Restrictions in the TTCN Suite

The TTCN suite editing tools support TTCN and ASN.1 as defined in the TTCN standard. The TTCN To C compiler on the other hand has limitations on its ASN.1 coverage. See "TTCN ASN.1 BER Encoding/Decoding for further details on the restrictions that apply. In a few other cases, the TTCN suite has introduced syntactical restrictions, but in all such cases there are simple work-around solutions.

This section describes the modifications in the TTCN and ASN.1 grammar, e.g. the differences between the TTCN/ASN.1 standards and the language supported by the TTCN suite. Modifications meaning that some constructs will not be analyzed correctly even though they have legal syntax according to the TTCN/ASN.1 standards.

External ASN.1 Types

The analysis of an ASN.1 Value requires access to its Type. In TTCN it is possible to refer to an external ASN.1 Type and define an ASN.1 Value of that type.

Therefore an extra field is included in the ASN.1 type by reference tables. The user provides the definition of an external ASN.1 type in this field. The allowed syntax/semantic for this field is the same as for regular ASN.1 type definition. ASN.1 values of such a reference type will be analyzed according to the provided type definition.

The extra field is exported if the option Telelogic MP format is chosen. It is, though, not printed together with the ASN.1 type by reference table.

Another solution to this problem is to open the referred ASN.1 module in the Organizer and define an dependencies link to it (see "Dependencies" for more information). The type definition is fetched from the referred ASN.1 module before it is analyzed. For more information, see "ASN.1 External Type/Value References" .

ValueList

The problem is that a ValueList constraint (in MatchingSymbol) with only one element has the same construction as a parenthesized Expression in the top level. In addition, a ConstraintValue and an Expression may appear in the same places (since Expression is allowed in the ConstraintValue).

The Analyzer assumes that a ValueList with only one element is a parenthesized Expression wherever it appears.

Example 290

Assuming the Test Suite Constant C1 (of type integer) with value (2 - X), C2 (also of type integer) with value 3 * (M - K) and C3 (also of type integer) with value (3, X). Both C1 and C2 are correct both syntactically and semantically, but C3 has an illegal value because value lists are not allowed in constants.

Example 291

Assume a TTCN ASP Constraint C with parameters P1 and P2 (both of type integer). The parameter P1 has the value (2 + X) and P2 has the value (2 + Y, X). Both P1 and P2 have a correct value but the value of P1 is considered to be an Expression by the Analyzer.

ASN.1 AnyValue

This ASN.1 construct introduces ambiguities into the language. This is because it is hard to find the place where the Type ends and the Value starts.

A restricted form of AnyValue is supported where the Type in the AnyValue must be a reference to a user defined type. This form covers all cases for ASN.1 AnyValue.

Example 292

Assume the ASN.1 Type definition T:
SEQUENCE {f1 INTEGER, f2 LT1 DEFAULT {s1 2, s2 LT2 FALSE}}
LT1 ::= SEQUENCE {s1 INTEGER, s2 ANY}
LT2 ::= BOOLEAN

ASN.1 NamedType & NamedValue

According to the ASN.1 standard (12.5), in some notation within which a type is referenced, the type may be named. In such cases, the ASN.1 standard specifies the use of the notation NamedType which is defined as:

NamedType ::= identifier Type | Type | SelectionType

The value of a type referenced using the NamedType notation shall be defined by the notation NamedValue which is defined as:

NamedValue ::= identifier Value | Value

According to the Information Technology -OSI- ASN.1 (UDC 681.3:621.39) the identifier in the NamedType definition shall be mandatory. The same modification is suggested for the NamedValue.

The TTCN Analyzer do not allow use of the second alternative of either of these constructs, i.e. the naming identifiers are not optional.

Example 293

Assume that the ASN.1 type T is defined as:
SEQUENCE { x INTEGER, y < Element }
Element ::= CHOICE { x BOOLEAN, y INTEGER }
This type definition is legal. The ASN.1 NamedType in T (x & y) shall be unique (y is considered as a NamedType in this case).
A legal value for T is: {x 2, y 4}

Example 294

Assume another ASN.1 type, T', defined as:
SEQUENCE { x INTEGER, y x < Element }
Element ::= CHOICE { x INTEGER, y BOOLEAN }
This type definition is also legal. The ASN.1 NamedType in T' (x & y) shall be unique (x is not considered as a NamedType in this case).
The value {x 2, y 4} is not considered to be a legal value for T' even though it is allowed according to the ASN.1 standard. A legal value (which will be accepted by the Analyzer) is {x 2, y x 4}

An important point to be noticed is that the TTCN standard does not allow the usage of an ASN.1 NamedValue within arithmetic expressions: (TTCN standard, 10.3.2.2).

Data Object Reference

A consequence of the above described restriction is that the TTCN suite does not permit the ComponentPosition mechanism for a DataObjectReference.

Another restriction for DataObjectReference is that the TTCN suite only permits Record referencing via ComponentIdentifiers. The mixed use of ComponentIdentifier, PDU_Identifier, and StructIdentifier for Record Reference is very vaguely described in the Standard. Almost any interpretation of the usage leads to possible ambiguities in the language.

The corresponding grammar for RecordRef (production 311) will in the TTCN suite be:

RecordRef ::= Dot ComponentIdentifier

The "path" leading down to the data object must be fully specified, i.e. all the component identifiers from the top to the bottom must be present.

Macro Value

The wildcard values "?", "*", or "-" may not in the TTCN suite be used in a Constraint where the identifier for the ASP Parameter, PDU Field, CM Element, or Structured Type Element is replaced by the macro symbol.

The Standard does not explicitly permit this nor does it allow this. The interpretation of using the wildcards for macros would however be very ambiguous. Rather than imposing one of the possible interpretations the TTCN suite will not allow the wildcards as macro values at all.

If wildcards are to be used as values for the elements that are inserted via macro expansion they must be written in the elements of a Structured Type Constraint that is referenced as macro value.


The TTCN-MP Syntax Productions in BNF

TTCN Specification

  1. TTCN_Specification ::= TTCN_Module | Package | Suite

TTCN Module

  2. TTCN_Module ::= $TTCN_Module TTCN_ModuleId TTCN_ModuleOverviewPart [TTCN_ModuleImportPart] [DeclarationsPart] [ConstraintsPart] [DynamicPart] $End_TTCN_Module
  3. TTCN_ModuleId ::= $TTCN_ModuleId TTCN_ModuleIdentifier
  4. TTCN_ModuleIdentifier ::= Identifier

The Module Overview

  5. TTCN_ModuleOverviewPart ::= $TTCN_ModuleOverviewPart TTCN_ModuleExports [TTCN_ModuleStructure] [TestCaseIndex] [TestStepIndex] [DefaultIndex] $End_TTCN_ModuleOverviewPart

Module Exports

  6. TTCN_ModuleExports ::= $Begin_TTCN_ModuleExports TTCN_ModuleId [TTCN_ModuleRef] [TTCN_ModuleObjective] [StandardsRef] [PICSref] [PIXITref] [TestMethods] [Comment] ExportedObjects [Comment] $End_ModuleExports
  7. TTCN_ModuleRef ::= $TTCN_ModuleRef BoundedFreeText
  8. TTCN_ModuleObjective ::= $TTCN_ModuleObjective BoundedFreeText
  9. ExportedObjects ::= $ExportedObjects {ExportedObject} $End_ExportedObjects
  10. ExportedObject ::= $ExportedObject ObjectId ObjectType [SourceInfo] [Comment] $End_ExportedObject
  11. ObjectId ::= $ObjectId ObjectIdentifier
  12. ObjectIdentifier ::= Identifier | ObjectTypeReference
  13. ObjectTypeReference ::= Identifier '[' Identifier ']'
  14. ObjectType ::= $ObjectType ObjectPredefinedType
  15. ObjectPredefinedType ::= SimpleType_Object | StructType_Object | ASN1_Type_Object | TS_Op_Object | TS_Proc_Object | TS_Par_Object | SelectExpr_Object | TS_Const_Object | TS_Var_Object | TC_Var_Object | PCO_Type_Object | PCO_Object | CP_Object | Timer_Object | TComp_Object | TCompConfig_Object | TTCN_ASP_Type_Object | ASN1_ASP_Type_Object | TTCN_PDU_Type_Object | ASN1_PDU_Type_Object | TTCN_CM_Type_Object | ASN1_CM_Type_Object | EncodingRule_Object | EncodingVariation_Object | InvalidFieldEncoding_Object | Alias_Object | StructTypeConstraint_Object | ASN1TypeConstraint_Object | TTCN_ASP_Constraint_Object | ASN1_ASP_Constraint_Object | TTCN_PDU_Constraint_Object | ASN1_PDU_Constraint_Object | TTCN_CM_Constraint_Object | ASN1_CM_Constraint_Object | TestCase_Object | TestStep_Object | Default_Object | NamedNumber_Object | Enumeration_Object
  16. SourceInfo ::= $SourceInfo (SourceIdentifier | ObjectDirective)
  17. SourceIdentifier ::= SuiteIdentifier | TTCN_ModuleIdentifier | PackageIdentifier
  18. ObjectDirective ::= '-' | OMIT | EXTERNAL

TTCN Module Structure

  19. TTCN_ModuleStructure ::= $Begin_TTCN_ModuleStructure Structure&Objectives [Comment] $End_TTCN_ModuleStructure

TTCN Module Import Part

  20. TTCN_ModuleImportPart ::= $TTCN_ModuleImportPart [ExternalObjects] [ImportDeclarations] $End_TTCN_ModuleImportPart

External Objects

  21. ExternalObjects ::= $Begin_ExternalObjects {ExternalObject}+ [Comment] $End_ExternalObjects
  22. ExternalObject ::= $ExternalObject ExternalObjectId ObjectType [Comment] $End_ExternalObject
  23. ExternalObjectId ::= $ExternalObjectId ExternalObjectIdentifier
  24. ExternalObjectIdentifier ::= ObjectIdentifier | TS_OpId&ParList | ConsId&ParList | TestStepId&ParList

Import Declarations

  25. ImportDeclarations ::= $ImportDeclarations {Imports}+ $End_ImportDeclarations
  26. Imports ::= $Begin_Imports SourceId [SourceRef] [StandardsRef] [Comment] ImportedObjects [Comment] $End_Imports
  27. SourceId ::= $SourceId SourceIdentifier
  28. SourceRef ::= $SourceRef BoundedFreeText
  29. ImportedObjects ::= $ImportedObjects {ImportedObject}+ $End_ImportedObjects
  30. ImportedObject ::= $ImportedObject ObjectId ObjectType [SourceInfo] [Comment] $End_ImportedObject

Source Package

  31. Package ::= $Package PackageId PackageExports PackageImports $End_Package
  32. PackageId ::= $PackageId PackageIdentifier
  33. PackageIdentifier ::= Identifier

Package exports

  34. PackageExports ::= $Begin_PackageExports PackageId [Comment] PackageExportedObjects [Comment] $End_PackageExports
  35. PackageExportedObjects ::= $PackageExportedObjects {PackageExportedObject}+ $End_PackageExportedObjects
  36. PackageExportedObject ::= $PackageExportedObject ObjectId ObjectType [SourceInfo] [Comment] $End_PackageExportedObject

Package imports and renames

  37. PackageImports ::= $PackageImports {PackageImport} $End_PackageImports

Package Import

  38. PackageImport ::= $Begin_PackageImport SourceId [Comment] PackageImportedObjects [Comment] $End_PackageImport
  39. PackageImportedObjects ::= $PackageImportedObjects {PackageImportedObject}+ $End_PackageImportedObjects
  40. PackageImportObject ::= $PackageImportObject ObjectId ObjectType [NewObjectDef] [NewObjectId] [Comment] $End_PackageImportObject
  41. NewObjectDef ::= $NewObjectDef (NewObjectIdentifier | ObjectDirective)
  42. NewObjectId ::= $NewObjectId NewObjectIdentifier
  43. NewObjectIdentifier ::= ObjectIdentifier

Test suite

  44. Suite ::= $Suite SuiteId SuiteOverviewPart [ImportPart] DeclarationsPart ConstraintsPart DynamicPart $End_Suite
  45. SuiteId ::= $SuiteId SuiteIdentifier
  46. SuiteIdentifier ::= Identifier

The Test Suite Overview

  47. SuiteOverviewPart ::= $SuiteOverviewPart [TestSuiteIndex] SuiteStructure [TestCaseIndex] [TestStepIndex] [DefaultIndex] $End_SuiteOverviewPart

Test Suite Index

  48. TestSuiteIndex ::= $Begin_TestSuiteIndex {ObjectInfo} [Comment] $End_TestSuiteIndex

The Imported Object Info

  49. ObjectInfo ::= $ObjectInfo ObjectId ObjectType SourceId OrigObjectId [PageNum] [Comment] $End_ObjectInfo
  50. PageNum ::= $PageNum PageNumber
  51. PageNumber ::= Number
  52. OrigObjectId ::= $OrigObjectId ObjectIdentifier

Test Suite Structure

  53. SuiteStructure ::= $Begin_SuiteStructure SuiteId StandardsRef PICSref PIXITref TestMethods [Comment] Structure&Objectives [Comment] $End_SuiteStructure
  54. StandardsRef ::= $StandardsRef BoundedFreeText
  55. PICSref ::= $PICSref BoundedFreeText
  56. PIXITref ::= $PIXITref BoundedFreeText
  57. TestMethods ::= $TestMethods BoundedFreeText
  58. Comment ::= $Comment [BoundedFreeText]
  59. Structure&Objectives ::= $Structure&Objectives {Structure&Objective} $End_Structure&Objectives
  60. Structure&Objective ::= $Structure&Objective TestGroupRef SelExprId Objective $End_Structure&Objective
  61. SelExprId ::= $SelectExprId [SelectExprIdentifier]

Test Case Index

  62. TestCaseIndex ::= $Begin_TestCaseIndex {CaseIndex} [Comment] $End_TestCaseIndex
  63. CaseIndex ::= $CaseIndex TestGroupRef TestCaseId SelExprId Description $End_CaseIndex
  64. Description ::= $Description BoundedFreeText

Test Step Index

  65. TestStepIndex ::= $Begin_TestStepIndex {StepIndex} [Comment] $End_TestStepIndex
  66. StepIndex ::= $StepIndex TestStepRef TestStepId Description $End_StepIndex

Default Index

  67. DefaultIndex ::= $Begin_DefaultIndex {DefIndex} [Comment] $End_DefaultIndex
  68. DefIndex ::= $DefIndex DefaultRef DefaultId Description $End_DefIndex

The Import Part

  69. ImportPart ::= $ImportPart ImportDeclarations $End_ImportPart

The Declarations Part

  70. DeclarationsPart ::= $DeclarationsPart Definitions Parameterization&Selection Declarations ComplexDefinitions $End_DeclarationsPart

Definitions

  71. Definitions ::= [TS_TypeDefs] [EncodingDefs] [TS_OpDefs] [TS_ProcDefs]

Test Suite Type Definitions

  72. TS_TypeDefs ::= $TS_TypeDefs [SimpleTypeDefs] [StructTypeDefs] [ASN1_TypeDefs] [ASN1_TypeRefs] $End_TS_TypeDefs

Simple Type Definitions

  73. SimpleTypeDefs ::= $Begin_SimpleTypeDefs {SimpleTypeDef}+ [Comment] $End_SimpleTypeDefs
  74. SimpleTypeDef ::= $SimpleTypeDef SimpleTypeId SimpleTypeDefinition [PDU_FieldEncoding] [Comment] $End_SimpleTypeDef
  75. SimpleTypeId ::= $SimpleTypeId SimpleTypeIdentifier
  76. SimpleTypeIdentifier ::= Identifier
  77. SimpleTypeDefinition ::= $SimpleTypeDefinition Type&Restriction
  78. Type&Restriction ::= Type [Restriction]
  79. Restriction ::= LengthRestriction | IntegerRange | SimpleValueList
  80. LengthRestriction ::= SingleTypeLength | RangeTypeLength
  81. SingleTypeLength ::= "["Number "]"
  82. RangeTypeLength ::= "[" LowerTypeBound To UpperTypeBound "]"
  83. IntegerRange ::= "(" LowerTypeBound To UpperTypeBound ")"
  84. LowerTypeBound ::= [Minus] Number | Minus INFINITY
  85. UpperTypeBound ::= [Minus] Number | INFINITY
  86. To ::= TO | ".."
  87. SimpleValueList ::= "(" [Minus] LiteralValue {Comma [Minus] LiteralValue} ")"

Structured Type Definitions

  88. StructTypeDefs ::= $StructTypeDefs {StructTypeDef}+ $End_StructTypeDefs
  89. StructTypeDef ::= $Begin_StructTypeDef StructId [EncVariationId] [Comment] ElemDcls [Comment] $End_StructTypeDef
  90. StructId ::= $StructId StructId&FullId
  91. StructId&FullId ::= StructIdentifier [FullIdentifier]
  92. FullIdentifier ::= "(" BoundedFreeText ")"
  93. StructIdentifier ::= Identifier
  94. ElemDcls ::= $ElemDcls {ElemDcl}+ $End_ElemDcls
  95. ElemDcl ::= $ElemDcl ElemId ElemType [PDU_FieldEncoding] [Comment] $End_ElemDcl
  96. ElemId ::= $ElemId ElemId&FullId
  97. ElemId&FullId ::= ElemIdentifier [FullIdentifier]
  98. ElemIdentifier ::= Identifier
  99. ElemType ::= $ElemType Type&Attributes

ASN.1 Type Definitions

  100. ASN1_TypeDefs ::= $ASN1_TypeDefs {ASN1_TypeDef}+ $End_ASN1_TypeDefs
  101. ASN1_TypeDef ::= $Begin_ASN1_TypeDef ASN1_TypeId [EncVariationId] [Comment] ASN1_TypeDefinition [Comment] $End_ASN1_TypeDef
  102. ASN1_TypeId ::= $ASN1_TypeId ASN1_TypeId&FullId
  103. ASN1_TypeId&FullId ::= ASN1_TypeIdentifier [FullIdentifier]
  104. ASN1_TypeIdentifier ::= Identifier
  105. ASN1_TypeDefinition ::= $ASN1_TypeDefinition ASN1_Type&LocalTypes $End_ASN1_TypeDefinition
  106. ASN1_Type&LocalTypes ::= ASN1_Type {ASN1_LocalType}
  107. ASN1_Type ::= ASN1_main_Type [ASN1_Encoding]
  108. ASN1_LocalType ::= TypeAssignment

ASN.1 Type Definitions by Reference

  109. ASN1_TypeRefs ::= $Begin_ASN1_TypeRefs {ASN1_TypeRef}+ [Comment] $End_ASN1_TypeRefs
  110. ASN1_TypeRef ::= $ASN1_TypeRef ASN1_TypeId ASN1_TypeReference ASN1_ModuleId [EncVariationId] [Comment] [ASN1_TypeDefinition] $End_ASN1_TypeRef
  111. ASN1_TypeReference ::= $ASN1_TypeReference TypeReference
  112. TypeReference ::= typereference
  113. ASN1_ModuleId ::= $ASN1_ModuleId ModuleIdentifier
  114. ModuleIdentifier ::= moduleidentifier

Test Suite Operation Definitions

  115. TS_OpDefs ::= $TS_OpDefs {TS_OpDef}+ $End_TS_OpDefs
  116. TS_OpDef ::= $Begin_TS_OpDef TS_OpId TS_OpResult [Comment] TS_OpDescription [Comment] $End_TS_OpDef
  117. TS_OpId ::= $TS_OpId TS_OpId&ParList
  118. TS_OpId&ParList ::= TS_OpIdentifier [FormalParList]
  119. TS_OpIdentifier ::= Identifier
  120. TS_OpResult ::= $TS_OpResult TypeOrPDU
  121. TS_OpDescription ::= $TS_OpDescription BoundedFreeText

Test Suite Operation Procedural Definitions

  122. TS_ProcDefs ::= $TS_ProcDefs {TS_ProcDef}+ $End_TS_ProcDefs
  123. TS_ProcDef ::= $Begin_TS_ProcDef TS_ProcId TS_ProcResult [Comment] TS_ProcDescription [Comment] $End_TS_ProcDef
  124. TS_ProcId ::= $TS_ProcId TS_ProcId&ParList
  125. TS_ProcId&ParList ::= TS_ProcIdentifier [FormalParList]
  126. TS_ProcIdentifier ::= Identifier
  127. TS_ProcResult ::= $TS_ProcResult TypeOrPDU
  128. TS_ProcDescription ::= $TS_ProcDescription TS_OpProcDef $End_TS_ProcDescription
  129. TS_OpProcDef ::= [VarBlock] ProcStatement
  130. VarBlock ::= VAR VarDcls ENDVAR
  131. VarDcls ::= {VarDcl SemiColon}
  132. VarDcl ::= [STATIC] VarIdentifiers Colon TypeOrPDU [Colon Value]
  133. VarIdentifiers ::= VarIdentifier {Comma VarIdentifier}
  134. VarIdentifier ::= Identifier
  135. ProcStatement ::= ReturnValueStatement | Assignment | IfStatement | WhileLoop | CaseStatement | ProcBlock
  136. ReturnValueStatement ::= RETURNVALUE Expression
  137. IfStatement ::= IF Expression THEN {ProcStatement SemiColon}+ [ELSE {ProcStatement SemiColon}+] ENDIF
  138. WhileLoop ::= WHILE Expression DO {ProcStatement SemiColon}+ ENDWHILE
  139. CaseStatement ::= CASE Expression OF {CaseClause SemiColon}+ [ELSE {ProcStatement SemiColon}+] ENDCASE
  140. CaseClause ::= IntegerLabel Colon ProcStatement
  141. IntegerLabel ::= Number | TS_ParIdentifier | TS_ConstIdentifier
  142. ProcBlock ::= BEGIN {ProcStatement SemiColon}+ END

Parameterization and Selection

  143. Parameterization&Selection ::= [TS_ParDcls] [SelectExprDefs]

Test Suite Parameter Declarations

  144. TS_ParDcls ::= $Begin_TS_ParDcls {TS_ParDcl}+ [Comment] $End_TS_ParDcls
  145. TS_ParDcl ::= $TS_ParDcl TS_ParId TS_ParType PICS_PIXITref [Comment] $End_TS_ParDcl
  146. TS_ParId ::= $TS_ParId TS_ParIdentifier
  147. TS_ParIdentifier ::= Identifier
  148. TS_ParType ::= $TS_ParType TypeOrPDU
  149. PICS_PIXITref ::= $PICS_PIXITref BoundedFreeText

Test Case Selection Expression Definitions

  150. SelectExprDefs ::= $Begin_SelectExprDefs {SelectExprDef}+ [Comment] $End_SelectExprDefs
  151. SelectExprDef ::= $SelectExprDef SelectExprId SelectExpr [Comment] $End_SelectExprDef
  152. SelectExprId ::= $SelectExprId SelectExprIdentifier
  153. SelectExprIdentifier ::= Identifier
  154. SelectExpr ::= $SelectExpr SelectionExpression
  155. SelectionExpression ::= Expression

Declarations

  156. Declarations ::= [TS_ConstDcls] [TS_ConstRefs] [TS_VarDcls] [TC_VarDcls] [PCO_TypeDcls] [PCO_Dcls] [CP_Dcls] [TimerDcls] [TCompDcls TCompConfigDcls]

Test Suite Constant Declarations

  157. TS_ConstDcls ::= $Begin_TS_ConstDcls {TS_ConstDcl}+ [Comment] $End_TS_ConstDcls
  158. TS_ConstDcl ::= $TS_ConstDcl TS_ConstId TS_ConstType TS_ConstValue [Comment] $End_TS_ConstDcl
  159. TS_ConstId ::= $TS_ConstId TS_ConstIdentifier
  160. TS_ConstIdentifier ::= Identifier
  161. TS_ConstType ::= $TS_ConstType Type
  162. TS_ConstValue ::= $TS_ConstValue DeclarationValue
  163. DeclarationValue ::= Expression

Test Suite Constant Declarations by Reference

  164. TS_ConstRefs ::= $Begin_TS_ConstRefs {TS_ConstRef}+ [Comment] $End_TS_ConstRefs
  165. TS_ConstRef ::= $TS_ConstRef TS_ConstId TS_ConstType ASN1_ValueReference ASN1_ModuleId [Comment] [ASN1_Value] $End_TS_ConstRef
  166. ASN1_ValueReference ::= $ASN1_ValueReference ValueReference
  167. ValueReference ::= valuereference

Test Suite Variable Declarations

  168. TS_VarDcls ::= $Begin_TS_VarDcls {TS_VarDcl}+ [Comment] $End_TS_VarDcls
  169. TS_VarDcl ::= $TS_VarDcl TS_VarId TS_VarType TS_VarValue [Comment] $End_TS_VarDcl
  170. TS_VarId ::= $TS_VarId TS_VarIdentifier
  171. TS_VarIdentifier ::= Identifier
  172. TS_VarType ::= $TS_VarType TypeOrPDU
  173. TS_VarValue ::= $TS_VarValue [DeclarationValue]

Test Case Variable Declarations

  174. TC_VarDcls ::= $Begin_TC_VarDcls {TC_VarDcl}+ [Comment] $End_TC_VarDcls
  175. TC_VarDcl ::= $TC_VarDcl TC_VarId TC_VarType TC_VarValue [Comment] $End_TC_VarDcl
  176. TC_VarId ::= $TC_VarId TC_VarIdentifier
  177. TC_VarIdentifier ::= Identifier
  178. TC_VarType ::= $TC_VarType TypeOrPDU
  179. TC_VarValue ::= $TC_VarValue [DeclarationValue]

PCO Type Declarations

  180. PCO_TypeDcls ::= $Begin_PCO_TypeDcls {PCO_TypeDcl}+ [Comment] $End_PCO_TypeDcls
  181. PCO_TypeDcl ::= $PCO_TypeDcl PCO_TypeId P_Role [Comment] $End_PCO_TypeDcl
  182. PCO_TypeId ::= $PCO_TypeId PCO_TypeIdentifier
  183. PCO_TypeIdentifier ::= Identifier

PCO Declarations

  184. PCO_Dcls ::= $Begin_PCO_Dcls {PCO_Dcl}+ [Comment] $End_PCO_Dcls
  185. PCO_Dcl ::= $PCO_Dcl PCO_Id PCO_TypeId&MuxValue P_Role [Comment] $End_PCO_Dcl
  186. PCO_Id ::= $PCO_Id PCO_Identifier
  187. PCO_Identifier ::= Identifier
  188. PCO_TypeId&MuxValue ::= $PCO_TypeId PCO_TypeIdentifier ["(" MuxValue ")"]
  189. MuxValue ::= TS_ParIdentifier
  190. P_Role ::= $PCO_Role PCO_Role
  191. PCO_Role ::= UT | LT

Coordination Points Declaration

  192. CP_Dcls ::= $Begin_CP_Dcls {CP_Dcl}+ [Comment] $End_CP_Dcls
  193. CP_Dcl ::= $CP_Dcl CP_Id [Comment] $End_CP_Dcl
  194. CP_Id ::= $CP_Id CP_Identifier
  195. CP_Identifier ::= Identifier

Timer Declarations

  196. TimerDcls ::= $Begin_TimerDcls {TimerDcl}+ [Comment] $End_TimerDcls
  197. TimerDcl ::= $TimerDcl TimerId Duration Unit [Comment] $End_TimerDcl
  198. TimerId ::= $TimerId TimerIdentifier
  199. TimerIdentifier ::= Identifier
  200. Duration ::= $Duration [DeclarationValue]
  201. Unit ::= $Unit TimeUnit
  202. TimeUnit ::= ps | ns | us | ms | s | min

Test Component Declarations

  203. TCompDcls ::= $Begin_TCompDcls {TCompDcl}+ [Comment] $End_TCompDcls
  204. TCompDcl ::= $TCompDcl TCompId TCompRole NumOf PCOs NumOf CPs [Comment] $EndTCompDcl
  205. TCompId ::= $TCompId TCompIdentifier
  206. TCompIdentifier ::= Identifier
  207. TCompRole ::= $TCompRole TC_Role
  208. TC_Role ::= MTC | PTC
  209. NumOf_PCOs ::= $NumOf_PCOs Num_PCOs
  210. Num_PCOs ::= Number
  211. NumOf_Cps ::= $NumOf_CPs Num_CPs
  212. Num_CPs ::= Number

Test Component Configuration Declarations

  213. TCompConfigDcls ::= $TCompConfigDcls {TCompConfigDcl}+ $End_TCompConfigDcls
  214. TCompConfigDcl ::= $Begin_TCompConfigDcl TCompConfigId [Comment] TCompConfigInfos [Comment] $EndTCompConfigDcl
  215. TCompConfigId ::= $TCompConfigId TCompConfigIdentifier
  216. TCompConfigIdentifier ::= Identifier
  217. TCompConfigInfos ::= $TCompConfigInfos {TCompConfigInfo}+ $End_TCompConfigInfos
  218. TCompConfigInfo ::= $TCompConfigInfo TCompUsed PCOs_Used CPs_Used [Comment] $End_TCompConfigInfo
  219. TCompUsed ::= $TCompUsed TCompIdentifier
  220. PCOs_Used ::= $PCOs_Used [PCO_List]
  221. PCO_List ::= PCO_Identifier {Comma PCO_Identifier}
  222. CPs_Used ::= $CPs_Used [CP_List]
  223. CP_List ::= CP_Identifier {Comma CP_Identifier}

ASP, PDU and CM Type Definitions

  224. ComplexDefinitions ::= [ASP_TypeDefs] [PDU_TypeDefs] [CM_TypeDefs] [AliasDefs]

ASP Type Definitions

  225. ASP_TypeDefs ::= $ASP_TypeDefs [TTCN_ASP_TypeDefs] [ASN1_ASP_TypeDefs] [ASN1_ASP_TypeDefsByRef] $End_ASP_TypeDefs

Tabular ASP Type Definitions

  226. TTCN_ASP_TypeDefs ::= $TTCN_ASP_TypeDefs {TTCN_ASP_TypeDef}+ $End_TTCN_ASP_TypeDefs
  227. TTCN_ASP_TypeDef ::= $Begin_TTCN_ASP_TypeDef ASP_Id PCO_Type [Comment] [ASP_ParDcls] [Comment] $End_TTCN_ASP_TypeDef
  228. PCO_Type ::= $PCO_Type [PCO_TypeIdentifier]
  229. ASP_Id ::= $ASP_Id ASP_Id&FullId
  230. ASP_Id&FullId ::= ASP_Identifier [FullIdentifier]
  231. ASP_Identifier ::= Identifier
  232. ASP_ParDcls ::= $ASP_ParDcls {ASP_ParDcl} $End_ASP_ParDcls
  233. ASP_ParDcl ::= $ASP_ParDcl ASP_ParId ASP_ParType [Comment] $End_ASP_ParDcl
  234. ASP_ParId ::= $ASP_ParId ASP_ParIdOrMacro
  235. ASP_ParIdOrMacro ::= ASP_ParId&FullId | MacroSymbol
  236. ASP_ParId&FullId ::= ASP_ParIdentifier [FullIdentifier]
  237. ASP_ParIdentifier ::= Identifier
  238. ASP_ParType ::= $ASP_ParType Type&Attributes

ASN.1 ASP Type Definitions

  239. ASN1_ASP_TypeDefs ::= $ASN1_ASP_TypeDefs {ASN1_ASP_TypeDef} $End_ASN1_ASP_TypeDefs
  240. ASN1_ASP_TypeDef ::= $Begin_ASN1_ASP_TypeDef ASP_Id PCO_Type [Comment] [ASN1_TypeDefinition] [Comment] $End_ASN1_ASP_TypeDef

ASN.1 ASP Type Definitions by Reference

  1. ASN1_ASP_TypeDefsByRef ::= $Begin_ASN1_ASP_TypeDefsByRef {ASN1_ASP_TypeDefByRef}+ [Comment] $End_ASN1_ASP_TypeDefsByRef
  2. ASN1_ASP_TypeDefByRef ::= $ASN1_ASP_TypeDefByRef ASP_Id PCO_Type ASN1_TypeReference ASN1_ModuleId [Comment] [ASN1_TypeDefinition] $End_ASN1_ASP_TypeDefByRef

PDU Type Definitions

  1. PDU_TypeDefs ::= $PDU_TypeDefs [TTCN_PDU_TypeDefs] [ASN1_PDU_TypeDefs] [ASN1_PDU_TypeDefsByRef] $End_PDU_TypeDefs

Tabular PDU Type Definitions

  1. TTCN_PDU_TypeDefs ::= $TTCN_PDU_TypeDefs {TTCN_PDU_TypeDef}+ $End_TTCN_PDU_TypeDefs
  2. TTCN_PDU_TypeDef ::= $Begin_TTCN_PDU_TypeDef PDU_Id PCO_Type [PDU_EncodingId] [EncVariationId] [Comment] [PDU_FieldDcls] [Comment] $End_TTCN_PDU_TypeDef
  3. PDU_Id ::= $PDU_Id PDU_Id&FullId
  4. PDU_Id&FullId ::= PDU_Identifier [FullIdentifier]
  5. PDU_Identifier ::= Identifier
  6. PDU_EncodingId ::= $PDU_EncodingId [EncodingRuleIdentifier]
  7. PDU_FieldDcls ::= $PDU_FieldDcls {PDU_FieldDcl} $End_PDU_FieldDcls
  8. PDU_FieldDcl ::= $PDU_FieldDcl PDU_FieldId PDU_FieldType [PDU_FieldEncoding] [Comment] $End_PDU_FieldDcl
  9. PDU_FieldId ::= $PDU_FieldId PDU_FieldIdOrMacro
  10. PDU_FieldIdOrMacro ::= PDU_FieldId&FullId | MacroSymbol
  11. MacroSymbol ::= "<-"
  12. PDU_FieldId&FullId ::= PDU_FieldIdentifier [FullIdentifier]
  13. PDU_FieldIdentifier ::= Identifier
  14. PDU_FieldType ::= $PDU_FieldType Type&Attributes
  15. Type&Attributes ::= (Type [LengthAttribute]) | PDU
  16. LengthAttribute ::= SingleLength | RangeLength
  17. SingleLength ::= "[" Bound "]"
  18. Bound ::= Number | TS_ParIdentifier | TS_ConstIdentifier
  19. RangeLength ::= "[" LowerBound To UpperBound "]"
  20. LowerBound ::= Bound
  21. UpperBound ::= Bound | INFINITY

ASN.1 PDU Type Definitions

  1. ASN1_PDU_TypeDefs ::= $ASN1_PDU_TypeDefs {ASN1_PDU_TypeDef} $End_ASN1_PDU_TypeDefs
  2. ASN1_PDU_TypeDef ::= $Begin_ASN1_PDU_TypeDef PDU_Id PCO_Type [PDU_EncodingId] [EncVariationId] [Comment] [ASN1_TypeDefinition] [Comment] $End_ASN1_PDU_TypeDef

ASN.1 PDU Type Definitions by Reference

  1. ASN1_PDU_TypeDefsByRef ::= $Begin_ASN1_PDU_TypeDefsByRef {ASN1_PDU_TypeDefByRef}+ [Comment] $End_ASN1_PDU_TypeDefsByRef
  2. ASN1_PDU_TypeDefByRef ::= $ASN1_PDU_TypeDefByRef PDU_Id PCO_Type ASN1_TypeReference ASN1_ModuleId [PDU_EncodingId] [EncVariationId] [Comment] [ASN1_TypeDefinition] $End_ASN1_PDU_TypeDefByRef

CM Type Definitions

  1. CM_TypeDefs ::= $CM_TypeDefs [TTCN_CM_TypeDefs] [ASN1_CM_TypeDefs] $End_CM_TypeDefs

Tabular CM Type Definitions

  1. TTCN_CM_TypeDefs ::= $TTCN_CM_TypeDefs {TTCN_CM_TypeDefs}+ $End_TTCN_CM_TypeDefs
  2. TTCN_CM_TypeDef ::= $Begin_TTCN_CM_TypeDef CM_Id [Comment] [CM_ParDcls] [Comment] $End_TTCN_CM_TypeDef
  3. CM_Id ::= $CM_Id CM_Identifier
  4. CM_Identifier ::= Identifier
  5. CM_ParDcls ::= $CM_ParDcls {CM_ParDcl} $End_CM_ParDcls
  6. CM_ParDcl ::= $CM_ParDcl CM_ParId CM_ParType [Comment] $End_CM_ParDcl
  7. CM_ParId ::= $CM_ParId CM_ParIdOrMacro
  8. CM_ParIdOrMacro ::= CM_ParIdentifier | MacroSymbol
  9. CM_ParIdentifier ::= Identifier
  10. CM_ParType ::= $CM_ParType Type&Attributes

ASN1 CM Type Definitions

  1. ASN1_CM_TypeDefs ::= $ASN1_CM_TypeDefs {ASN1_CM_TypeDefs}+ $End_ASN1_CM_TypeDefs
  2. ASN1_CM_TypeDef ::= $Begin_ASN1_CM_TypeDef CM_Id [Comment] [ASN1_TypeDefinition] [Comment] $End_ASN1_CM_TypeDef

Varieties of Encoding Definition

  1. EncodingDefs ::= $EncodingDefs [EncodingDefinitions] [EncodingVariations] [InvalidFieldEncodingDefs] $End_EncodingDefs

Encoding Definitions

  1. EncodingDefinitions ::= $Begin_EncodingDefinitions {EncodingDefinition}+ [Comment] $End_EncodingDefinitions
  2. EncodingDefinition ::= $EncodingDefinition EncodingRuleId EncodingRef EncodingDefault [Comment] $End_EncodingDefinition
  3. EncodingRuleId ::= $EncodingRuleId EncodingRuleIdentifier
  4. EncodingRuleIdentifier ::= Identifier
  5. EncodingRef ::= $EncodingRef EncodingReference
  6. EncodingReference ::= BoundedFreeText
  7. EncodingDefault ::= $EncodingDefault [DefaultExpression]
  8. DefaultExpression ::= Expression

Encoding Variations

  1. EncodingVariations ::= $EncodingVariations {EncodingVariationSet}+ $End_EncodingVariations
  2. EncodingVariationSet ::= $Begin_EncodingVariationSet EncodingRuleId Encoding_TypeList [Comment] {EncodingVariation}+ [Comment] $End_EncodingVariationSet
  3. Encoding_TypeList ::= $Encoding_TypeList [TypeList]
  4. TypeList ::= Type {Comma Type}
  5. EncodingVariation ::= $EncodingVariation EncodingVariationId VariationRef VariationDefault [Comment] $End_EncodingVariation
  6. EncodingVariationId ::= $EncodingVariationId EncVariationId&ParList
  7. EncVariationId&ParList ::= EncVariationIdentifier [FormalParList]
  8. EncVariationIdentifier ::= Identifier
  9. VariationRef ::= $VariationRef VariationReference
  10. VariationReference ::= BoundedFreeText
  11. VariationDefault ::= $VariationDefault [DefaultExpression]

Invalid Encoding Definitions

  1. InvalidFieldEncodingDefs ::= $InvalidFieldEncodingDefs {InvalidFieldEncodingDef}+ $End_InvalidFieldEncodingDefs
  2. InvalidFieldEncodingDef ::= $Begin_InvalidFieldEncodingDef InvalidFieldEncodingId Encoding_TypeList [Comment] InvalidFieldEncodingDefinition [Comment] $End_InvalidFieldEncodingDef
  3. InvalidFieldEncodingId ::= $InvalidFieldEncodingId InvalidFieldEncodingId&ParList
  4. InvalidFieldEncodingId&ParList ::= InvalidFieldEncodingIdentifier [FormalParList]
  5. InvalidFieldEncodingIdentifier ::= Identifier
  6. InvalidFieldEncodingDefinition ::= $InvalidFieldEncodingDefinition TS_OpProcDef $End_InvalidFieldEncodingDefinition

Alias Definitions

  1. AliasDefs ::= $Begin_AliasDefs {AliasDef}+ [Comment] $End_AliasDefs
  2. AliasDef ::= $AliasDef AliasId ExpandedId [Comment] $End_AliasDef
  3. AliasId ::= $AliasId AliasIdentifier
  4. AliasIdentifier ::= Identifier
  5. ExpandedId ::= $ExpandedId Expansion
  6. Expansion ::= ASP_Identifier | PDU_Identifier

The Constraints Part

  1. ConstraintsPart ::= $ConstraintsPart [TS_TypeConstraints] [ASP_Constraints] [PDU_Constraints] [CM_Constraints] $End_ConstraintsPart

Test Suite Type Constraint Declarations

  1. TS_TypeConstraints ::= $TS_TypeConstraints [StructTypeConstraints] [ASN1_TypeConstraints] $End_TS_TypeConstraints

Structured Type Constraint Declarations

  1. StructTypeConstraints ::= $StructTypeConstraints {StructTypeConstraint}+ $End_StructTypeConstraints
  2. StructTypeConstraint ::= $Begin_StructTypeConstraint ConsId StructId DerivPath [EncVariationId] [Comment] ElemValues [Comment] $End_StructTypeConstraint
  3. EncVariationId ::= $EncVariationId [EncVariationCall]
  4. EncVariationCall ::= EncVariationIdentifier [ActualParList]
  5. ElemValues ::= $ElemValues {ElemValue}+ $End_ElemValues
  6. ElemValue ::= $ElemValue ElemId ConsValue [PDU_FieldEncoding] [Comment] $End_ElemValue
  7. PDU_FieldEncoding ::= $PDU_FieldEncoding [PDU_FieldEncodingCall]
  8. PDU_FieldEncodingCall ::= EncVariationCall | InvalidFieldEncodingCall
  9. InvalidFieldEncodingCall ::= InvalidFieldEncodingIdentifier ( ActualParList | "(" ")" )

ASN.1 Type Constraint Declarations

  1. ASN1_TypeConstraints ::= $ASN1_TypeConstraints {ASN1_TypeConstraint}+ $End_ASN1_TypeConstraints
  2. ASN1_TypeConstraint ::= $Begin_ASN1_TypeConstraint ConsId ASN1_TypeId DerivPath [EncVariationId] [Comment] ASN1_ConsValue [Comment] $End_ASN1_TypeConstraint

ASP Constraint Declarations

  1. ASP_Constraints ::= $ASP_Constraints [TTCN_ASP_Constraints] [ASN1_ASP_Constraints] $End_ASP_Constraints

Tabular ASP Constraint Declarations

  1. TTCN_ASP_Constraints ::= $TTCN_ASP_Constraints {TTCN_ASP_Constraint}+ $End_TTCN_ASP_Constraints
  2. TTCN_ASP_Constraint ::= $Begin_TTCN_ASP_Constraint ConsId ASP_Id DerivPath [Comment] [ASP_ParValues] [Comment] $End_TTCN_ASP_Constraint
  3. ASP_ParValues ::= $ASP_ParValues {ASP_ParValue}+ $End_ASP_ParValues
  4. ASP_ParValue ::= $ASP_ParValue ASP_ParId ConsValue [Comment] $End_ASP_ParValue

ASN.1 ASP Constraint Declarations

  1. ASN1_ASP_Constraints ::= $ASN1_ASP_Constraints {ASN1_ASP_Constraint}+ $End_ASN1_ASP_Constraints
  2. ASN1_ASP_Constraint ::= $Begin_ASN1_ASP_Constraint ConsId ASP_Id DerivPath [Comment] [ASN1_ConsValue] [Comment] $End_ASN1_ASP_Constraint

PDU Constraint Declarations

  1. PDU_Constraints ::= $PDU_Constraints [TTCN_PDU_Constraints] [ASN1_PDU_Constraints] $End_PDU_Constraints

Tabular PDU Constraint Declarations

  1. TTCN_PDU_Constraints ::= $TTCN_PDU_Constraints {TTCN_PDU_Constraint}+ $End_TTCN_PDU_Constraints
  2. TTCN_PDU_Constraint ::= $Begin_TTCN_PDU_Constraint ConsId PDU_Id DerivPath [EncRuleId] [EncVariationId] [Comment] [PDU_FieldValues] [Comment] $End_TTCN_PDU_Constraint
  3. EncRuleId ::= $EncRuleId [EncodingRuleIdentifier]
  4. ConsId ::= $ConsId ConsId&ParList
  5. ConsId&ParList ::= ConstraintIdentifier [FormalParList]
  6. ConstraintIdentifier ::= Identifier
  7. DerivPath ::= $DerivPath [DerivationPath]
  8. DerivationPath ::= {ConstraintIdentifier Dot}+
  9. PDU_FieldValues ::= $PDU_FieldValues {PDU_FieldValue}+ $End_PDU_FieldValues
  10. PDU_FieldValue ::= $PDU_FieldValue PDU_FieldId ConsValue [PDU_FieldEncoding] [Comment] $End_PDU_FieldValue
  11. ConsValue ::= $ConsValue ConstraintValue&Attributes
  12. ConstraintValue&Attributes ::= ConstraintValue ValueAttributes
  13. ConstraintValue ::= ConstraintExpression | MatchingSymbol | ConsRef
  14. ConstraintExpression ::= Expression
  15. MatchingSymbol ::= Complement | Omit | AnyValue | AnyOrOmit | ValueList | ValueRange | SuperSet | SubSet | Permutation
  16. Complement ::= COMPLEMENT ValueList
  17. Omit ::= Dash | OMIT
  18. AnyValue ::= "?"
  19. AnyOrOmit ::= "*"
  20. ValueList ::= "(" ConstraintValue&Attributes { Comma ConstraintValue&Attributes }")"
  21. ValueRange ::= "(" ValRange ")"
  22. ValRange ::= (LowerRangeBound To UpperRangeBound)
  23. LowerRangeBound ::= ConstraintExpression | Minus INFINITY
  24. UpperRangeBound ::= ConstraintExpression | INFINITY
  25. SuperSet ::= SUPERSET "(" ConstraintValue&Attributes ")"
  26. SubSet ::= SUBSET "(" ConstraintValue&Attributes ")"
  27. Permutation ::= PERMUTATION ValueList
  28. ValueAttributes ::= [ValueLength] [IF_PRESENT] [ASN1_Encoding]
  29. ASN1_Encoding ::= ENC PDU_FieldEncodingCall
  30. ValueLength ::= SingleValueLength | RangeValueLength
  31. SingleValueLength ::= "[" ValueBound "]"
  32. ValueBound ::= Number | TS_ParIdentifier | TS_ConstIdentifier | FormalParIdentifier
  33. RangeValueLength ::= "[" LowerValueBound To UpperValueBound "]"
  34. LowerValueBound ::= ValueBound
  35. UpperValueBound ::= ValueBound | INFINITY

ASN.1 PDU Constraint Declarations

  1. ASN1_PDU_Constraints ::= $ASN1_PDU_Constraints {ASN1_PDU_Constraint}+ $End_ASN1_PDU_Constraints
  2. ASN1_PDU_Constraint ::= $Begin_ASN1_PDU_Constraint ConsId PDU_Id DerivPath [EncRuleId] [EncVariationId] [Comment] [ASN1_ConsValue] [Comment] $End_ASN1_PDU_Constraint
  3. ASN1_ConsValue ::= $ASN1_ConsValue ConstraintValue&AttributesOrReplace $End_ASN1_ConsValue
  4. ConstraintValue&AttributesOrReplace ::= ConstraintValue&Attributes | Replacement {Comma Replacement}
  5. Replacement ::= (REPLACE ReferenceList BY ConstraintValue&Attributes) | (OMIT ReferenceList)
  6. ReferenceList ::= (ArrayRef | ComponentIdentifier | ComponentPosition) {ComponentReference}

CM Constraint Declarations

  1. CM_Constraints ::= $CM_Constraints [TTCN_CM_Constraints] [ASN1_CM_Constraints] $End_CM_Constraints

Tabular CM Constraint Declaration

  1. TTCN_CM_Constraints ::= $TTCN_CM_Constraints {TTCN_CM_Constraint}+ $End_TTCN_CM_Constraints
  2. TTCN_CM_Constraint ::= $Begin_TTCN_CM_Constraint ConsId CM_Id DerivPath [Comment] [CM_ParValues] [Comment] $End_TTCN_CM_Constraint
  3. CM_ParValues ::= $CM_ParValues {CM_ParValue} $End_CM_ParValues
  4. CM_ParValue ::= $CM_ParValue CM_ParId ConsValue [Comment] $End_CM_ParValue

ASN.1 CM Constraint Declaration

  1. ASN1_CM_Constraints ::= $ASN1_CM_Constraints {ASN1_CM_Constraint}+ $End_ASN1_CM_Constraints
  2. ASN1_CM_Constraint ::= $Begin_ASN1_CM_Constraint ConsId CM_Id DerivPath [Comment] [ASN1_ConsValue] [Comment] $End_ASN1_CM_Constraint

The Dynamic Part

  1. DynamicPart ::= $DynamicPart [TestCases] [TestStepLibrary] [DefaultsLibrary] $End_DynamicPart

Test Cases

  1. TestCases ::= $TestCases {TestGroup | TestCase | CompactTestGroup}+ $End_TestCases
  2. TestGroup ::= $TestGroup TestGroupId [SelExprId] [Objective] {TestGroup | TestCase}+ $End_TestGroup
  3. TestGroupId ::= $TestGroupId TestGroupIdentifier
  4. TestGroupIdentifier ::= Identifier
  5. TestCase ::= $Begin_TestCase TestCaseId TestGroupRef TestPurpose [Configuration] DefaultsRef [Comment] [SelExprId] [Description] BehaviourDescription [Comment] $End_TestCase
  6. TestCaseId ::= $TestCaseId TestCaseIdentifier
  7. TestCaseIdentifier ::= Identifier
  8. TestGroupRef ::= $TestGroupRef TestGroupReference
  9. TestGroupReference ::= [SuiteIdentifier "/"] {TestGroupIdentifier "/"}
  10. TestPurpose ::= $TestPurpose BoundedFreeText
  11. Configuration ::= $Configuration TCompConfigIdentifier
  12. DefaultsRef ::= $DefaultsRef [DefaultRefList]
  13. DefaultRefList ::= DefaultReference {Comma DefaultReference}
  14. DefaultReference ::= DefaultIdentifier [ActualParList]
    1. CompactTestGroup ::= $Begin_CompactTestGroup TestGroupId DefaultsRef [SelExprId] [Objective] {CompactTestCase} $End_CompactTestGroup
    2. CompactTestCase ::= $CompactTestCase TestCaseId TestPurpose TestStepAttachment [Comment] [SelExprId] [Description] $End_CompactTestCase
    3. TestStepAttachment ::= $TestStepAttachment Attach

Test Step Library

  1. TestStepLibrary ::= $TestStepLibrary {TestStepGroup | TestStep}+ $End_TestStepLibrary
  2. TestStepGroup ::= $TestStepGroup TestStepGroupId {TestStepGroup | TestStep}+ $End_TestStepGroup
  3. TestStepGroupId ::= $TestStepGroupId TestStepGroupIdentifier
  4. TestStepGroupIdentifier ::= Identifier
  5. TestStep ::= $Begin_TestStep TestStepId TestStepRef Objective DefaultsRef [Comment] [Description] BehaviourDescription [Comment] $End_TestStep
  6. TestStepId ::= $TestStepId TestStepId&ParList
  7. TestStepId&ParList ::= TestStepIdentifier [FormalParList]
  8. TestStepIdentifier ::= Identifier
  9. TestStepRef ::= $TestStepRef TestStepGroupReference
  10. TestStepGroupReference ::= [SuiteIdentifier "/"] {TestStepGroupIdentifier "/"}
  11. Objective ::= $Objective BoundedFreeText

Default Library

  1. DefaultsLibrary ::= $DefaultsLibrary {DefaultGroup | Default}+ $End_DefaultsLibrary
  2. DefaultGroup ::= $DefaultGroup DefaultGroupId {DefaultGroup | Default}+ $End_DefaultGroup
  3. DefaultGroupId ::= $DefaultGroupId DefaultGroupIdentifier
  4. Default ::= $Begin_Default DefaultId DefaultRef Objective [Comment] [Description] BehaviourDescription [Comment] $End_Default
  5. DefaultRef ::= $DefaultRef DefaultGroupReference
  6. DefaultId ::= $DefaultId DefaultId&ParList
  7. DefaultId&ParList ::= DefaultIdentifier [FormalParList]
  8. DefaultIdentifier ::= Identifier
  9. DefaultGroupReference ::= [SuiteIdentifier "/"] {DefaultGroupIdentifier "/"}
  10. DefaultGroupIdentifier ::= Identifier

Behaviour descriptions

  1. BehaviourDescription ::= $BehaviourDescription RootTree {LocalTree} $End_BehaviourDescription
  2. RootTree ::= {BehaviourLine}+
  3. LocalTree ::= Header {BehaviourLine}+
  4. Header ::= $Header TreeHeader
  5. TreeHeader ::= TreeIdentifier [FormalParList]
  6. TreeIdentifier ::= Identifier
  7. FormalParList ::= "(" FormalPar&Type {SemiColon FormalPar&Type} ")"
  8. FormalPar&Type ::= FormalParIdentifier {Comma FormalParIdentifier} Colon FormalParType
  9. FormalParIdentifier ::= Identifier
  10. FormalParType ::= Type | PCO_TypeIdentifier | PDU | CP | TIMER

Behaviour lines

  1. BehaviourLine ::= $BehaviourLine LabelId Line Cref VerdictId [Comment] $End_BehaviourLine
  2. Line ::= $Line Indentation StatementLine
  3. Indentation ::= "[" Number "]"
  4. LabelId ::= $LabelId [Label]
  5. Label ::= Identifier
  6. Cref ::= $Cref [ConstraintReference]
  7. ConstraintReference ::= ConsRef | FormalParIdentifier | AnyValue
  8. ConsRef ::= ConstraintIdentifier [ActualCrefParList]
  9. ActualCrefParList ::= "(" ActualCrefPar {Comma ActualCrefPar} ")"
  10. ActualCrefPar ::= Value
  11. VerdictId ::= $VerdictId [Verdict]
  12. Verdict ::= Pass | Fail | Inconclusive | Result
  13. Pass ::= PASS | P | "(" PASS ")" | "(" P ")"
  14. Fail ::= FAIL | F | "(" FAIL ")" | "(" F ")"
  15. Inconclusive ::= INCONC | I | "(" INCONC ")" | "(" I ")"
  16. Result ::= R

TTCN statements

  1. StatementLine ::= (Event [Qualifier] [AssignmentList] [TimerOps]) | (Qualifier [AssignmentList] [TimerOps]) | (AssignmentList [TimerOps]) | TimerOps | Construct | ImplicitSend
  2. Event ::= Send | Receive | Otherwise | Timeout | Done
  3. Qualifier ::= "[" Expression "]"
  4. Send ::= [PCO_Identifier | CP_Identifier | FormalParIdentifier] "!" (ASP_Identifier | PDU_Identifier | CM_Identifier)
  5. ImplicitSend ::= "<" IUT "!" (ASP_Identifier | PDU_Identifier) ">"
  6. Receive ::= [PCO_Identifier | CP_Identifier | FormalParIdentifier] "?" (ASP_Identifier | PDU_Identifier | CM_Identifier)
  7. Otherwise ::= [PCO_Identifier | FormalParIdentifier] "?" OTHERWISE
  8. Timeout ::= "?" TIMEOUT [TimerIdentifier | FormalParIdentifier]
  9. Done ::= "?" DONE "(" [TCompIdList] ")"
  10. TCompIdList ::= TCompIdentifier {Comma TCompIdentifier}
  11. Construct ::= GoTo | Attach | Repeat | Return | Activate | Create
  12. Activate ::= ACTIVATE "(" [DefaultRefList] ")"
  13. Return ::= RETURN
  14. Create ::= CREATE "(" CreateList ")"
  15. CreateList ::= CreateTComp {Comma CreateTComp}
  16. CreateTComp ::= TCompIdentifier Colon TreeReference [ActualParList]
  17. GoTo ::= ("->" | GOTO) Label
  18. Attach ::= "+" TreeReference [ActualParList]
  19. Repeat ::= REPEAT TreeReference [ActualParList] UNTIL Qualifier
  20. TreeReference ::= TestStepIdentifier | TreeIdentifier
  21. ActualParList ::= "(" ActualPar {Comma ActualPar} ")"
  22. ActualPar ::= Value | PCO_Identifier | CP_Identifier | TimerIdentifier

Expressions

  1. AssignmentList ::= "(" Assignment {Comma Assignment} ")"
  2. Assignment ::= DataObjectReference ":=" Expression
  3. Expression ::= SimpleExpression [RelOp SimpleExpression]
  4. SimpleExpression ::= Term {AddOp Term}
  5. Term ::= Factor {MultiplyOp Factor}
  6. Factor ::= [UnaryOp] Primary
  7. Primary ::= Value | DataObjectReference | OpCall | SelectExprIdentifier | "(" Expression ")"
  8. DataObjectReference ::= DataObjectIdentifier {ComponentReference}
  9. DataObjectIdentifier ::= TS_ParIdentifier | TS_ConstIdentifier | TS_VarIdentifier | TC_VarIdentifier | FormalParIdentifier | ASP_Identifier | PDU_Identifier | CM_Identifier
  10. ComponentReference ::= RecordRef | ArrayRef | BitRef
  11. RecordRef ::= Dot (ComponentIdentifier | PDU_Identifier | StructIdentifier | ComponentPosition)
  12. ComponentIdentifier ::= ASP_ParIdentifier | PDU_FieldIdentifier | CM_ParIdentifier | ElemIdentifier | ASN1_Identifier
  13. ASN1_Identifier ::= Identifier
  14. ComponentPosition ::= "("Number")"
  15. ArrayRef ::= Dot "[" ComponentNumber "]"
  16. ComponentNumber ::= Expression
  17. BitRef ::= Dot (BitIdentifier | "[" BitNumber "]")
  18. BitIdentifier ::= Identifier
  19. BitNumber ::= Expression
  20. OpCall ::= OpIdentifier ( ActualParList | "(" ")" )
  21. OpIdentifier ::= TS_OpIdentifier | PredefinedOpIdentifier
  22. PredefinedOpIdentifier ::= BIT_TO_INT | HEX_TO_INT | INT_TO_BIT | INT_TO_HEX | IS_CHOSEN | IS_PRESENT | LENGTH_OF | NUMBER_OF_ELEMENT
  23. AddOp ::= "+" | "-" | OR
  24. MultiplyOp ::= "*" | "/" | MOD | AND
  25. UnaryOp ::= "+" | "-" | NOT
  26. RelOp ::= "=" | "<" | ">" | "<>" | ">=" | "<="

Timer operations

  1. TimerOps ::= TimerOp {Comma TimerOp}
  2. TimerOp ::= StartTimer | CancelTimer | ReadTimer
  3. StartTimer ::= START TimerIdentifier [ "(" TimerValue ")"]
  4. CancelTimer ::= CANCEL [TimerIdentifier]
  5. TimerValue ::= Expression
  6. ReadTimer ::= READTIMER TimerIdentifier "(" DataObjectReference")"

Types

  1. TypeOrPDU ::= Type | PDU
  2. Type ::= PredefinedType | ReferenceType

Predefined types

  1. PredefinedType ::= INTEGER | BOOLEAN | BITSTRING | HEXSTRING | OCTETSTRING | R_Type | CharacterString
  2. CharacterString ::= NumericString | PrintableString | TeletexString | VideotexString | VisibleString | IA5String | GraphicString | GeneralString | T61String | ISO646String

Referenced types

  1. ReferenceType ::= TS_TypeIdentifier | ASP_Identifier | PDU_Identifier | CM_Identifier
  2. TS_TypeIdentifier ::= SimpleTypeIdentifier | StructIdentifier | ASN1_TypeIdentifier

Values

  1. Value ::= LiteralValue | ASN1_Value [ASN1_Encoding]
  2. LiteralValue ::= Number | BooleanValue | Bstring | Hstring | Ostring | Cstring | R_Value
  3. Number ::= (NonZeroNum {Num} ) | 0
  4. NonZeroNum ::= 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
  5. Num ::= 0 | NonZeroNum
  6. BooleanValue ::= TRUE | FALSE
  7. Bstring ::= "'" {Bin | Wildcard} "'" B
  8. Bin ::= 0 | 1
  9. Hstring ::= "'" {Hex | Wildcard} "'" H
  10. Hex ::= Num | A | B | C | D | E | F
  11. Ostring ::= "'" {Oct | Wildcard} "'" O
  12. Oct ::= Hex Hex
  13. Cstring ::= """ {Char | Wildcard | "\"} """
  14. Char ::= /* REFERENCE - A character defined by the relevant character string type */
  15. Wildcard ::= AnyOne | AnyOrNone
  16. AnyOne ::= "?"
  17. AnyOrNone ::= "*"
  18. R_Value ::= pass | fail | inconc | none
  19. Identifier ::= Alpha{AlphaNum | Underscore}
  20. Alpha ::= UpperAlpha | LowerAlpha
  21. AlphaNum ::= Alpha | Num
  22. UpperAlpha ::= A | B| C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z
  23. LowerAlpha ::= a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z
  24. ExtendedAlphaNum ::= /* REFERENCE - A character from any character set defined in ISO/IEC 10646 */
  25. BoundedFreeText ::= "/*" FreeText "*/"
  26. FreeText ::= {ExtendedAlphaNum}

Miscellaneous productions

  1. Comma ::= ","
  2. Dot ::= "."
  3. Dash ::= "-"
  4. Minus ::= "-"
  5. SemiColon ::= ";"
  6. Colon ::= ":"
  7. Underscore ::= "_"


The ASN1 Syntax Productions in BNF

  1. moduleidentifier ::= BoundedFreeText
  2. typereference ::= Identifier
  3. valuereference ::= Identifier
  4. TypeAssignment ::= typereference "::=" ASN1_main_Type
  5. ASN1_main_Type ::= BuiltinType | DefinedType | SubType
  6. BuiltinType ::= BooleanType | IntegerType | BitStringType | OctetStringType
    | NullType | SequenceType | SequenceOfType | SetType | SetOfType | ChoiceType | SelectionType | TaggedType | AnyType | ObjectIdentifierType
    | CharacterStringType | UsefulType | EnumeratedType | RealType
  7. NamedType ::= Identifier ASN1_main_Type | ASN1_main_Type | SelectionType
  8. ASN1_Value ::= BuiltinValue | DefinedValue
  9. BuiltinValue ::= BooleanValue | IntegerValue | BitStringValue | OctetStringValue | NullValue | SequenceValue | SequenceOfValue | SetValue | SetOfValue
    | ChoiceValue | SelectionValue | TaggedValue | ASN1_AnyValue
    | ObjectIdentifierValue | CharacterStringValue | EnumeratedValue | RealValue
  10. NamedValue ::= Identifier ASN1_Value | ASN1_Value
  11. BooleanType ::= BOOLEAN
  12. IntegerType ::= INTEGER | INTEGER "{" NamedNumberList "}"
  13. NamedNumberList ::= NamedNumber | NamedNumberList Comma
    NamedNumber
  14. NamedNumber ::= Identifier "(" Minus Number ")" | Identifier "(" Number ")"
    | Identifier "(" DefinedValue ")"
  15. IntegerValue ::= Minus Number | Number | Identifier
  16. EnumeratedType ::= ENUMERATED "{" Enumeration "}"
  17. Enumeration ::= NamedNumber | Enumeration Comma NamedNumber
  18. EnumeratedValue ::= Identifier
  19. RealType ::= REAL
  20. RealValue ::= NumericalRealValue | SpecialRealValue
  21. NumericalRealValue ::= "{" Mantissa Comma Base Comma Exponent "}"
  22. Mantissa ::= Minus Number | Number
  23. Base ::= Two | Ten
  24. Exponent ::= Minus Number | Number
  25. SpecialRealValue ::= PLUS_INFINITY | MINUS_INFINITY
  26. BitStringType ::= BIT STRING | BIT STRING "{" NamedBitList "}"
  27. NamedBitList ::= NamedBit | NamedBitList Comma NamedBitList
  28. NamedBit ::= Identifier "(" Number ")" | Identifier "(" DefinedValue ")"
  29. BitStringValue ::= Bstring | Hstring | "{" IdentifierList "}" | "{" "}"
  30. IdentifierList ::= Identifier | IdentifierList Comma Identifier
  31. OctetStringType ::= OCTET STRING
  32. OctetStringValue ::= Bstring | Hstring
  33. NullType ::= NULL
  34. NullValue ::= NULL
  35. SequenceType ::= SEQUENCE "{" ElementTypeList "}"
  36. ElementTypeList ::= | ElementType | ElementTypeList Comma ElementType
  37. ElementType ::= NamedType | NamedType OPTIONAL | NamedType DEFAULT ASN1_Value | COMPONENTS OF ASN1_main_Type
  38. SequenceValue ::= "{" ElementValueList "}" | "{" "}"
  39. ElementValueList ::= NamedValue | ElementValueList Comma NamedValue
  40. SequenceOfType ::= SEQUENCE OF ASN1_main_Type | SEQUENCE
  41. SequenceOfValue ::= LBRACE ASN1_ValueList RBRACE | LBRACE RBRACE
  42. ASN1_ValueList ::= ASN1_Value | ASN1_ValueList Comma ASN1_Value
  43. SetType ::= SET "{" ElementTypeList "}"
  44. SetValue ::= "{" ElementValueList "}" | "{" "}"
  45. SetOfType ::= SET OF ASN1_main_Type | SET
  46. SetOfValue ::= "{" ASN1_ValueList "}" | "{" "}"
  47. ChoiceType ::= CHOICE "{" AlternativeTypeList "}"
  48. AlternativeTypeList ::= NamedType | AlternativeTypeList Comma NamedType
  49. ChoiceValue ::= NamedValue
  50. SelectionType ::= Identifier "<" ASN1_main_Type
  51. SelectionValue ::= NamedValue
  52. TaggedType ::= Tag ASN1_main_Type | Tag IMPLICIT ASN1_main_Type
    | Tag EXPLICIT ASN1_main_Type
  53. Tag ::= "(" Class ClassNumber ")"
  54. Class ::= UNIVERSAL | APPLICATION | PRIVATE | empty
  55. ClassNumber ::= Number | DefinedValue
  56. TaggedValue ::= ASN1_Value
  57. AnyType ::= ANY | ANY DEFINED_ BY Identifier
  58. ASN1_AnyValue ::= ASN1_main_Type Colon ASN1_Value
  59. ObjectIdentifierType ::= OBJECT IDENTIFIER
  60. ObjectIdentifierValue ::= "{" ObjIdComponentList "}"
    | "{" DefinedValue ObjIdComponentList "}"
  61. ObjIdComponentList ::= ObjComponent | ObjIdComponentList ObjComponent
  62. ObjComponent ::= NameForm | NumberForm | NameAndNumberForm
  63. NameForm ::= Identifier
  64. NumberForm ::= Number | DefinedValue
  65. NameAndNumberForm ::= Identifier "{" NumberForm "}"
  66. CharacterStringType ::= Identifier
  67. CharacterStringValue ::= Cstring
  68. UsefulType ::= Identifier
  69. SubType ::= ParentType SubtypeSpec | SET SizeConstraint OF ASN1_main_Type | SEQUENCE SizeConstraint OF ASN1_main_Type
  70. ParentType ::= ASN1_main_Type
  71. SubtypeSpec ::= "(" SubtypeValueSetList ")"
  72. SubtypeValueSetList ::= SubtypeValueSet | SubtypeValueSetList `|'
    SubtypeValueSet
  73. SubtypeValueSet ::= ASN1_Value | ContainedSubtype | ASN1_ValueRange
    | PermittedAlphabet | SizeConstraint | InnerTypeConstraints
  74. ContainedSubtype ::= INCLUDES ASN1_main_Type
  75. ASN1_ValueRange ::= LowerEndpoint DotDot UpperEndpoint
  76. LowerEndpoint ::= LowerEndValue | LowerEndValue "<"
  77. LowerEndValue ::= ASN1_Value | MIN
  78. UpperEndpoint ::= UpperEndValue | "<" UpperEndValue
  79. UpperEndValue ::= ASN1_Value | MAX
  80. SizeConstraint ::= SIZE SubtypeSpec
  81. PermittedAlphabet ::= FROM SubtypeSpec
  82. InnerTypeConstraints ::= WITH COMPONENT SingleTypeConstraint
    | WITH COMPONENTS MultipleTypeConstraints
  83. SingleTypeConstraint ::= SubtypeSpec
  84. MultipleTypeConstraints ::= FullSpecification | PartialSpecification
  85. FullSpecification ::= "{" TypeConstraints "}"
  86. PartialSpecification ::= "{" DotDotDot Comma TypeConstraints "}"
  87. TypeConstraints ::= NamedConstraint | NamedConstraint Comma
    TypeConstraints
  88. NamedConstraint ::= Identifier Constraint | Constraint
  89. Constraint ::= ValueConstraint PresenceConstraint
  90. ValueConstraint ::= SubtypeSpec | empty
  91. PresenceConstraint ::= PRESENT | ABSENT | OPTIONAL | empty


TTCN Static Semantics

The following are those static semantics from the TTCN and ASN.1 standards which are checked by the Analyzer tool in the TTCN suite.

Test Suite

SuiteId shall be the same as the SuiteId declared in Test Suite Structure table (Suite Structure).

Test Case Index

Test Cases shall be listed in the order that they exist in the dynamic part.

Test Step Index

TestStepId shall not include a formal parameter list.

Test Steps shall be listed in the order that they exist in the dynamic part.

Default Index

DefaultId shall not include a formal parameter list.

Defaults shall be listed in the order that they exist in the dynamic part.

Test Suite Type Definitions

Wherever types are referenced within Test Suite Type Definitions those references shall not be recursive (neither directly or indirectly)

Simple Type Definitions

The base type1 shall be a Predefined Type or a Simple Type.

The set of values defined by a restriction must be a true subset of the values of the base type.

In specification of a particular length range, only non-negative INTEGER literals or the keyword INFINITY for the upper bound shall be used.

If Minus is used in SimpleValueList then LiteralValue shall be a number.

The restriction type shall be a list of distinguished values of the base type.

Where a range is used in a type definition either as a value range or as a length range (for strings) it shall be stated with the lower of the two values on the left.

An integer range shall be used only with a base type of INTEGER or a type derived from INTEGER.

Where a value list is used, the values shall be of the base type and shall be a true subset of the values defined by the base type.

LengthRestriction shall be provided only when the base type is a string type (i.e., BITSTRING, HEXSTRING, OCTETSTRING or CharacterString) or derived from a string type

The LiteralValues shall be of the base type

In RangeTypeLength:
LowerTypeBound shall be a non-negative number
LowerTypeBound shall be less than UpperTypeBound

In IntegerRange:
LowerTypeBound shall be less than UpperTypeBound

Structured Type Definitions

Where elements may be of a type of arbitrarily complex structure; there shall be no recursive references.

The elements of Structured Type definitions are considered to be optional, i.e., in instances of these types whole elements may not be present.

A structure element Type shall be a PredefinedType, TS_TypeIdentifier, PDU_Identifier, or PDU.

If a Structured Type is used as a macro expansion, then the names of the elements within the Structured Type shall be unique within each ASP or PDU where it will be expanded.

The optional element length restriction can be used in order to give the minimum and maximum length of an element of a string type.

The set of values defined by LengthAttribute shall be a subset of the values of the base type.

ASN1 Type Definition

Types referred to from the type definition shall be defined in other ASN.1 type definition tables, be defined by reference in the ASN.1 type reference table or be defined locally in the same table, following the first type definition. Locally defined types shall not be used in other parts of the test suite.

ASN.1 type definitions used within TTCN shall not use external type references as defined in ISO/IEC 8824.

When ASN1 is used in a TTCN test suite, ASN1 identifiers from the following list shall be unique throughout the test suite:
a) identifiers occurring in an ASN1ENUMERATED type as distinguished values
b) identifiers occurring in a NamedNumberList of an ASN1 INTEGER type

Each terminal type reference used within the Type production shall be one of the following: ASN1_LocalType type reference, TS_TypeIdentifier or PDU_Identifier.

Test Suite Operation Definition

Only predefined types and data types as defined in the Test Suite Type definitions, ASP type definitions or PDU type definitions may be used as types for formal parameters. PCO types shall not be used as formal parameter types.

When a Test Suite Operation is invoked

  1. the number of the actual parameters shall be the same as the number of the formal parameters; and
  2. each actual parameter shall evaluate to an element of its corresponding formal type of parameter's.

Type in ResultType shall be a Predefined Type, TS_TypeIdentifier, PDU_Identifier or ASP_Identifier.

Test Suite Parameters Declarations

The type shall be a Predefined Type, TS_TypeIdentifier, PDU_Identifier or ASP_Identifier.

Test Case Selection Expression Definition

The expression shall use only literal values, Test Suite Parameters, Test Suite Constants and other selection expression identifiers in its terms.

The expression shall evaluate to a BOOLEAN value.

Expression shall not recursively refer (neither directly nor indirectly) to the SelExprIdentifier being defined by that Expression.

Test Suite Constant Declarations

The type shall be a predefined type, an ASN.1 type, a Test Suite Type or a PDU type.

The terms in the value expression shall not contain: Test Suite Variables or Test Case Variables.

The value shall evaluate to an element of the type indicated in the type column.

Test Suite Variable Declarations

Type shall be a Predefined Type, TS_TypeIdentifier, PDU_Identifier or ASP_Identifier.

The terms in the value expression shall not contain: Test Suite Variables or Test Case Variables.

Specifying an initial value is optional.

If an unbound Test Suite Variable is used in the right-hand side of an assignment, then it is a test case error.

The value shall evaluate to an element of the type indicated in the type column.

Test Case Variable Declarations

Type shall be a Predefined Type, TS_TypeIdentifier, PDU_Identifier or ASP_Identifier.

The terms in the value expression shall not contain: Test Suite Variables or Test Case Variables.

Specifying an initial value is optional.

The value shall evaluate to an element of the type indicated in the type column.

PCO Declarations

It is possible to define a PCO to correspond to a set of SAPs.

Timer Declarations

The terms in the value expression shall not contain: Test Suite Variables or Test Case Variables.

The timer duration shall evaluate to an unsigned positive INTEGER value.

ASP Type Definition

ASP type definitions may include ASN1 type definitions, if appropriate.

If only a single PCO is defined within a test suite then PCO_TypeIdentifier is optional. The PCO type shall be one of the PCO types used in the PCO Type Declaration proforma.

The macro symbol shall be used only with Structured Types defined in the Structured Types definitions.

Parameters may be of a type of arbitrarily complex structure, including being specified as a Test Suite Type (either predefined, Simple Type, Structured Type or ASN.1 type).

If a parameter is to be structured as a PDU, then its type may be stated either:

  • as a PDU identifier to indicate that in the constraint for the ASP this parameter may be chained to a PDU constraint of a specific PDU type.
  • as PDU to indicate that in the constraint for the ASP this parameter may be chained to a PDU constraint of any PDU type.

The boundaries shall be specified in terms of (non-negative) INTEGER literals, Test Suite Parameters, Test Suite Constants or the keyword INFINITY.

The parameters of ASP type definitions are considered to be optional, i.e., in instances of these types whole parameters may not be present.

The names of ASP parameters shall be unique within the ASP in which they are declared.

The optional attribute is Length.

In ASPs that are sent from the tester, values for ASP parameters that are defined in the Constraints Part shall correspond to the parameter or field definition. This means:
a) the value shall be of the type specified for that ASP parameter; and
b) In the case of substructured ASPs, either using Structured Types or ASN.1, the above rules apply to the fields of the substructure(s) recursively.

ASN1 ASP Type Definitions

The PCO type shall be one of the PCO types used in the PCO declaration proforma.

If only a single PCO is defined within a test suite, specifying the PCO type in an ASP type definition is optional.

Types referred to from the ASP definition shall be defined in other ASN.1 type definition tables, be defined by reference in the ASN.1 type reference table or be defined locally in the same table, following the first type definition.

Locally defined types shall not be used in other parts of the test suite.

ASN1 ASP Type Definition By Reference

The PCO type shall be one of the PCO types used in the PCO declaration proforma.

If only a single PCO is defined within a test suite, specifying the PCO type in an ASP type definition is optional.

PDU Type Definition

The PCO type shall be one of the PCO types used in the PCO declaration proforma.

The macro symbol shall be used only with Structured Types defined in the Structured Types definitions.

Fields may be of a type of arbitrarily complex structure, including being specified as a Test Suite Type (either predefined, Simple Type, Structured Type or ASN.1 type).

If a field is to be structured as a PDU, then its type may be stated either

  • as a PDU identifier to indicate that in the constraint for the PDU this field may be chained to a PDU constraint of a specific PDU type;
    or
  • as PDU to indicate that in the constraint for the PDU this field may be chained to a PDU constraint of any PDU type.

The boundaries shall be specified in terms of non-negative INTEGER literals, Test Suite Parameters, Test Suite Constants or the keyword INFINITY.

The fields of PDU type definitions are considered to be optional, i.e., in instances of these types whole fields may not be present.

The names of PDU fields shall be unique within the PDU in which they are declared

The optional attribute is Length;

In PDUs that are sent from the tester, values for PDU fields that are defined in the Constraints Part shall correspond to the field definition. This means

  1. that the value shall be of the type specified for that PDU field;
    and
  2. in the case of substructured ASPs and/or PDUs, either using Structured Types or ASN.1, the above rules apply to the fields of the substructure(s) recursively.

The set of values defined by LengthAttribute shall be a true subset of the values of the base type.

LengthAttribute shall be provided only when the base type is a string type (i.e. BITSTRING, HEXSTRING, OCTETSTRING or CharacterString) or derived from a string type.

ASN1 PDU Type Definition

The PCO type shall be one of the PCO types used in the PCO declaration proforma.

If only a single PCO is defined within a test suite, specifying the PCO type in an PDU type definition is optional.

Types referred to from the ASP definition shall be defined in other ASN.1 type definition tables, be defined by reference in the ASN.1 type reference table or be defined locally in the same table, following the first type definition.

Locally defined types shall not be used in other parts of the test suite.

ASN1 PDU Type Definition By Reference

The PCO type shall be one of the PCO types used in the PCO declaration proforma.

If only a single PCO is defined within a test suite, specifying the PCO type in an PDU type definition is optional.

String Length Specifications

TTCN permits the specification of length restrictions on string types (i.e., BITSTRING, HEXSTRING, OCTETSTRING and all CharacterString types) in the following instances:

  1. when declaring Test Suite Types as a type restriction;
  2. when declaring simple ASP parameters, PDU fields and elements of Structured Types as an attribute of the parameter, field or element type;
    and
  3. when defining ASP/PDU or Structured Type constraints as an attribute of the constraint value. In the context of constraints, length restrictions can also be specified on values of type SEQUENCE OF or SET OF, thus limiting the number of their elements.

Alias Definitions

An Alias shall be used only to replace an ASP identifier or a PDU identifier within a single TTCN statement in a behaviour tree. It shall be used only in a behaviour description column.

Structured Type Constraint Declarations

If an ASP or PDU definition refers to a Structured Type as a substructure of a parameter or field (i.e., with a parameter name or a field name specified for it) then the corresponding constraint shall have the same parameter or field name in the corresponding position in the parameter name or field name column of the constraint and the value shall be a reference to a constraint for that parameter or field (i.e., for that substructure in accordance with the definition of the Structured Type).

ASP Constraint Declarations

If the ASP definition refers to a Structured Type by macro expansion (i.e., with <- in place of the ASP field name) then in a corresponding constraint either

  • the individual elements from the Structured Type shall be included directly within the constraints.
  • the macro symbol ( <- ) shall be placed in the corresponding position in the ASP field name column of the constraint and the value shall be a reference to a constraint for the Structured Type referenced from the ASP definition.

PDU Constraint Declarations

If the PDU definition refers to a Structured Type by macro expansion (i.e., with <- in place of the PDU field name) then in a corresponding constraint either:

  • the individual elements from the Structured Type shall be included directly within the constraints;
    or
  • the macro symbol ( <- ) shall be placed in the corresponding position in the PDU field name column of the constraint and the value shall be a reference to a constraint for the Structured Type referenced from the PDU definition.

Constraints Part

If an ASP and/or PDU is substructured, then the constraints for ASPs and/or PDUs of that type shall have the same tabular structure or a compatible ASN.1 structure (i.e., possibly with some groupings).

Structured Types expanded into an ASP or PDU definition by use of the macro symbol ( <- ) are not considered to be substructures. Constraints for such ASPs or PDUs shall either have a completely flat structure (i.e., the elements of an expanded structure are explicitly listed in the ASP or PDU constraint) or shall reference a corresponding structure constraint for macro expansion.

Whichever way the values are obtained, they shall correspond to the parameter or field entries in the ASP or PDU type definitions. This means

  1. that the value shall be of the type specified for that parameter or field.
  2. that the length shall satisfy any restriction associated with the type. (This will not be implemented.)

An expression in a constraint shall contain only literal values, Test Suite Parameters, Test Suite Constants, formal parameters and Test Suite Operations.

Neither Test Suite Variables nor Test Case Variables shall be used in constraints, unless passed as actual parameters.

Literal values, Test Suite Parameters, Test Suite Constants, Test Suite Variables, Test Case Variables and PDU or Test Suite Type constraints may be passed as actual parameters to a constraint in a constraints reference made from a behaviour description. The parameters shall not be of PCO type or ASP type.

In ASN.1 constraints, only ASP parameters and PDU fields declared as OPTIONAL may be omitted. These may be omitted either by using the Omit symbol or by simply leaving out the relevant ASP parameter or PDU field.

The constraint specification of an ASP and/or PDU shall have the same structure as that of the type definition of that ASP or PDU.

In tabular constraints, all ASP parameters and PDU fields are optional and therefore may be omitted using the Omit symbol, to indicate that the ASP parameter or PDU field is to be absent from the event sent.

An expression in a constraint shall contain only Values (including, for instance, ConstraintValue&Attributes), Test Suite Parameters, Test Suite Constraints, formal parameters, Component References and Test Suite Operations.

Matching Mechanisms

Complement: Each constraint value in the list shall be of the type declared for the ASP parameter or PDU field in which the complement mechanism is used.

ValueList: Each value in the ValueList shall be of the type declared for the ASP parameter or PDU field in which the ValueList mechanism is used.

Range: Ranges shall be used only on values of INTEGER type.

Range: A boundary value shall be either:

  • INFINITY or -INFINITY
  • a constraint expression that evaluates to a specific INTEGER value.

Range: The lower boundary shall be less than the upper boundary.

SuperSet: SuperSet is an operation for matching that shall be used on values of SET OF type. SuperSet shall be used only in ASN1 constraints.

SuperSet: The argument of SuperSet shall be of the type declared for the ASP parameter or PDU field in which the SuperSet mechanism is used.

SubSet: SubSet is an operation for matching that shall be used on values of SET OF type. SubSet shall be used only in ASN1 constraints.

SubSet: The argument of SubSet shall be of the type declared for the ASP parameter or PDU field in which the SubSet mechanism is used.

Permutation: Permutation an operation for matching that can be used only on values inside a value of SEQUENCE OF type. Permutation shall be used only in ASN1 constraints.

Permutation: Each element listed in Permutation shall be of the type declared inside the SEQUENCE OF type of the ASP parameter or PDU field.

Base Constraints and Modified Constraints

The name of the modified constraint shall be a unique identifier.

The name of the base constraint which is to be modified shall be indicated in the derivation path entry in the constraint header. This entry shall be left blank for a base constraint.

A modified constraint can itself be modified. In such a case the Derivation Path indicates the concatenation of the names of the base and previously modified constraints, separated by dots ( . ) A dot shall follow the last modified constraint name.

If a base constraint is defined to have a formal parameter list, the following rules apply to all modified constraints derived from that base constraint, whether or not they are derived in one or several modification steps:

  1. The modified constraint shall have the same parameter list as the base constraint. In particular, there shall be no parameters omitted from or added to this list
  2. The formal parameter list shall follow the constraint name for every modified constraint
  3. Parameterized ASP parameters or PDU in a base constraint fields shall not be modified or explicitly omitted in a modified constrain.

In tabular constraints Omit shall be denoted by dash ( - ). In ASN.1 constraints Omit is denoted by OMIT.

If the ASP or PDU definition refers to a parameter or field specified as being of metatype PDU then in a corresponding constraint the value for that parameter or field shall be specified as the name of a PDU constraint, or formal parameter.

The Behaviour Description

Statements in the first level of alternatives having no predecessor in the root or local tree belong to, shall have the indentation value of zero.

Statements having a predecessor shall have the indentation value of the predecessor plus one as their indentation value.

The parameters may provide PCOs, constraints, variables, or other such items for use within the tree.

Test Case root trees shall not be parameterized.

Formal parameters may be of PCO type, ASP type, PDU type, structure type or one of the other predefined or Test Suite Types.

TTCN Test Events

In the simplest form, an ASP identifier or PDU identifier follows the SEND symbol ( ! ) for events to be initiated by the LT or UT, or a RECEIVE symbol ( ? ) for events which it is possible for the LT or UT to accept.

If both a qualifier and an assignment are associated with the same event, then the qualifier shall appear first.

The tree header identifier used for local trees shall be unique within the dynamic behaviour description in which they appear, and shall not be the same as any identifier having a unique meaning throughout the test suite.

TTCN Expressions

The index notation is used to refer to elements (bits) of the ASN.1 BITSTRING type. BITSTRING is assumed to be defined as SEQUENCE OF {BOOLEAN}. If certain bits of a BITSTRING are associated with an identifier (named bit) then either the dot notation or this identifier shall be used to refer to the bit.

Where a parameter, field or element is defined to be a true substructure of a type defined in a Structured Type table, a reference to the elements in the substructure shall consist of the reference to the parameter, field or element identifier followed by a dot and the identifier of the item within that substructure.

Where a structure is used as a macro expansion, the elements in the structure shall be referred to as if it was expanded into the structure referring to it.

If a parameter, field or element is defined to be of metatype PDU no reference shall be made to fields of that substructure.

The ATTACH Construct

Tree reference may be Test Step Identifiers or tree identifiers, where

  1. A Test Step Identifier denotes the attachment of a Test Step that resides in the Test Step Library; the Test Step is referenced by its unique identifier
  2. A tree identifier shall be the name of one of the trees in the current behaviour description; this is attachment of a local tree.

Constraints may be passed as parameters to Test Steps. If the constraint has a formal parameter list then the constraint shall be passed together with an actual parameter list.

When a parameterized tree is attached:

  1. The number of the actual parameters shall be the same as the number of formal parameters
  2. Each actual parameter shall evaluate to an element of its corresponding formal parameter type

Labels and the GOTO Construct

A GOTO to a label may be specified within a behaviour tree provided that the label is associated with the first of a set of alternatives, one of which is an ancestor node of the point from which the GOTO is to be made.

A GOTO shall be used only for jumps within one tree, i.e., within a Test Case root tree, a Test Step tree a Default tree or a local tree. As a consequence, each label used in a GOTO construct shall be found within the same tree in which the GOTO is used.

Labels used within a tree shall be unique within a tree.

The Constraints Reference

The actual parameter list shall fulfil the following:

  1. the number of actual parameters shall be the same as the number of formal parameters;
    and
  2. each actual parameter shall evaluate to an element of its corresponding formal type.

Verdicts

A predefined variable called R is available in each Test Case to store any Intermediate results. R can take the values pass, fail, inconc and none. These values are predefined identifiers and as such are case sensitive.

R shall not be used on the left-hand side of an assignment statement.

PASS or P, FAIL or F and INCONC or I are keywords that are used in the verdicts column only. The predefined identifiers pass, fail, inconc and none are values that represent the possible contents of the predefined variable R. These predefined identifiers are to be used for testing the variable R in behaviour lines only.

A Verdict shall not occur in corresponding to entries in the behaviour tree which are any of the following: empty, an ATTACH construct, a GOTO construct, an IMPLICIT SEND or a RETURN.

Default References

Test Cases or Test Steps shall not be referred to as Defaults.

The actual parameter list shall fulfill the following:

  1. The number of actual parameters shall be the same as the number of formal parameters.
  2. Each actual parameter shall evaluate to an element of its corresponding formal type.
  3. All variables appearing in the parameter list shall be bound when the constraint is invoked. (This won't be implemented.)

Formal Parameters

The formal parameter names which may optionally appear as part of the following shall be unique within that formal parameter list, and shall not be the same as any identifier having a unique meaning throughout the test suite.

A formal parameter name contained in the formal parameter list of a local tree shall header shall take precedence over a formal parameter name contained in the formal parameter list of the Test Step in which it is defined, within the scope of that local formal parameter list.

DataObjectReferences

A reference to a component of one of the following types: SEQUENCE, SET and CHOICE is constructed using a dot notation; i.e., appending a dot and the name (component identifier) of the desired component to the data object identifier; the component identifier shall be used if specified.

1

By Base Type we refer to the particular type in the Type production


ASN.1 Static Semantics

IntegerType: Each identifier appearing in the NamedNumberList shall be different.

BitStringType: The DefinedValue shall be a reference to a value of type integer, or of a type derived from integer by tagging.

BitStringType: Each identifier appearing in the NamedNumberList shall be different.

BitStringValue: Each identifier in BitStringValue shall be the same as an identifier in the BitStringType sequence with which the value is associated.

SequenceType: The Type in the fourth alternative of the ElementType (COMPONENTS OF) shall be sequence type.

SequenceType: If OPTIONAL or DEFAULT are present, the corresponding value may be omitted from a value of the new type.

SequenceType: The identifiers in all NamedType sequence of the ElementTypeList shall be distinct.

SequenceType: The {} notation shall only be used if:
a) all ElementType sequences in the SequenceType are marked DEFAULT or OPTIONAL and all values are omitted
b) the type notation was SEQUENCE {}

SequenceType: There shall be one NamedValue for each NamedType in the SequenceType which is not marked OPTIONAL or DEFAULT, and the values shall be in the same order as the corresponding NamedType sequences.

SequenceOfType: Each Value sequence in the ValueList shall be the notation for a value of the Type specified in the SequenceOfType.

SequenceOfType: The {} notation is used when there are no component values in the sequence-of value.

SetType: The Type in the fourth alternative of the ElementType (COMPONENTS OF) shall be set type.

SetType: If OPTIONAL or DEFAULT are present, the corresponding value may be omitted from a value of the new type.

SetType: The identifiers in all NamedType sequence of the ElementTypeList shall be distinct.

SetType: The {} notation shall only be used if:
a) all ElementType sequences in the SetType are marked DEFAULT or OPTIONAL and all values are omitted
b) the type notation was SET {}

SetOfType: Each Value sequence in the ValueList shall be the notation for a value of the Type specified in the SetOfType.

SetOfType: The {} notation is used when there are no component values in the set-of value.

ChoiceType: The identifiers in all NamedType sequences of the AlternativeTypeList shall be distinct.

ChoiceType: If the NamedValue contains an identifier (in our case it contains always), it shall be a notation for a value of that type in the AlternativeTypeList that is named by the same identifier.

SelectionType: Type is a notation referencing the ChoiceType, and identifier is the identifier in the NamedType.

Subtype: When the SubtypeSpec notation follows the SelectionType notation, the parent type is the SelectionType, not the Type in the SelectionType notation.

Subtype: When the SubtypeSpec notation follows a set-of or sequence-of type notation, it applies to the Type in the set-of or sequence-of notation, not to the set-of or sequence-of type.


40 Using Diagram Editors

This chapter describes the diagram editors you use for creating, drawing and printing OM (Object Models), SC (State Charts), DP (Deployment), MSC (Message Sequence Charts) and HMSC (High-level Message Sequence Charts) diagrams. Another name for HMSC is "road map".

The MSC Editor is also available in a flavor called MSC Tracer where the user is not allowed to add or remove symbols. This is only possible by an API which enables custom applications to interactively produce an MSC which reflects user defined events. Some features in the MSC Editor are not available in the MSC Tracer. For further information on this API, see the header file <product install dir>/include/msctrace/msctrace.h.

This chapter contains information about the functionality, menus, dialogs and windows of the diagram editors. For a guide to how to create and edit MSCs, see 42 Editing MSC Diagrams.

Note: SDL Editor

The SDL editor is not covered in this chapter. For information regarding the SDL editor please see Using the SDL Editor.


General

The editor described in this chapter is a combined OM, SC, DP, MSC and HMSC Editor. This editor is thus capable of showing five different types of diagrams, namely the Object Model (OM) diagrams, State Chart (SC) diagrams, Deployment (DP) diagrams, Message Sequence Chart (MSC) diagrams, and High-level MSC (HMSC) diagrams.

This combined editor is called the editor throughout this chapter. If only a specific editor is applied, that editor will be explicitly mentioned.

OM, SC, DP and HMSC diagrams are handled by one editor window, whereas MSC diagrams are handled by a separate editor window. This means that two editor windows are needed to handle all five diagram types.

The editor handling SDL diagrams is described in 44 Using the SDL Editor.

How to edit MSC diagrams is described more closely in 42 Editing MSC Diagrams.

Diagrams and Pages

The handling of diagrams and pages is common to the OM, SC, DP, MSC and HMSC diagrams. The editor can handle any number of diagrams.

The pages that the editor displays are always contained within a diagram. A diagram can contain any number of pages, but, must contain at least one page. The MSC and the DP Editor are exceptions as they always contain only one page. This page is enlarged when objects are added, etc.

The pages that are contained in a diagram are listed and handled according to a fixed order. While the order of pages is initially defined by the order in which the pages are added when created, pages can be renamed and rearranged with the Edit menu choice in the Pages menu.

This order is reflected in some of the menu choices that are related to pages. Also, the structure displayed by the Organizer will adopt the same order. See "The Organizer" .


The Editor User Interface and Basic Operations

The Editor User Interface

The editor window can be used for viewing OM, SC, DP, MSC and HMSC diagrams.

The general Telelogic Tau user interface is described in 1 User Interface and Basic Operations.

These functions are provided:

  • The Entity Dictionary Window, which provides a name reuse facility as well as information for link endpoints.
  • A symbol menu where you select the symbols that are to be inserted.
  • A text window where you may edit text associated with symbols.

When you edit OM diagrams, three auxiliary windows are also provided:

  • The Browse & Edit Class Dialog which you use to browse amongst and inspect and edit OM classes distributed across page and diagram boundaries.
  • The Line Details Window which allows you to inspect and edit the various attributes of OM lines.
  • The Symbol Details Window which allows you to inspect and edit OM symbol attributes.

When you edit DP diagrams, two of the auxiliary windows are also available:

  • The Line Details Window which allows you to inspect and edit the various attributes of DP lines.
  • The Symbol Details Window which allows you to inspect and edit DP symbol attributes.

When you edit MSC diagrams this function is also available:

  • An instance ruler which allows you to view the kinds of instances, even if the instance head symbols are not currently in view.

Figure 276 : The editor window showing an OM diagram (on UNIX)

Figure 277 : The editor window showing an OM diagram (in Windows)

The Editor Drawing Area

The drawing area is the part of the window which displays the symbols, lines and text that constitute a page (a diagram can contain multiple pages) or an MSC or DP diagram.

Figure 278 : The drawing area with an OM page displayed

Figure 279 : The drawing area with an MSC Diagram displayed

Drawing Area Boundaries

The drawing area is delimited by its boundaries, which correspond to the size of the page. No objects are allowed to be placed outside these boundaries. The drawing area uses a light background color, while the area outside the drawing area uses a grey pattern.

Within a diagram, each page has an individual size.

The Frame

The frame always coincides with the drawing area size. It is selectable but not editable. The frame is automatically selected with the Select All menu choice.

It is not possible to connect any diagram symbol to the frame. The frame only affects if the page is printed with or without a frame when printing selected objects, or when selected symbols are copied to a metafile (Windows only).

The Heading

OM, SC and DP only: The heading contains the diagram name. The heading is editable but cannot be moved. The editor performs a textual syntax check on the name used in the heading, see "Diagram Name Syntax" .

MSC and HMSC only: The heading identifies the chart type and name. The type cannot be edited.

The Page Name

All editors except MSC and DP.

In the upper right corner, the page name and the total number of pages in the diagram (within parentheses) are identified. The page name cannot be moved. To rename a page, use the Edit menu choice in the Pages menu.

The Printout Page Number

If a diagram page is larger than the paper format that is defined, the diagram page will be split into several printout pages. In this case, page numbers will be created. The page numbering follows a "down first, then right" fashion.

Figure 280 : Page numbering in the editor

Grids

The editor uses two grids for an easy positioning of symbols, lines and textual elements:

  • The symbol grid has a resolution of 5 * 5 mm, except for the MSC editor where it is 2.5 * 2.5 mm. All symbols adhere to the symbol grid.
  • The line and text grid has a resolution of 2.5 * 2.5 mm. All lines and textual objects adhere to the line grid.

None of the grids can be changed.

Color on Symbols

All editors except MSC.

For each symbol type in the editor there is a preference for setting the color of the symbol. It is only the graphical part of the symbol and not the associated text(s) that will use the color setting. On UNIX, this setting is only valid on screen and all symbols will use the black color when printed on paper. In Windows, when using MSW Print the color settings will be sent to the printer as well. See "OM/SC/HMSC/MSC/DP Editor Preferences" .

The text symbol is the same in OM, SC, DP and HMSC diagrams and has thus only one preference.

Keyboard Accelerators

In addition to the standard keyboard accelerators, the editor features the following:

Accelerator | Reference to corresponding command
Ctrl+D | "Next page"
Ctrl+U | "Previous page"
Ctrl+T | "Symbol Details"
<Delete> | "Clear"
Ctrl+1 | "Show Organizer"
Ctrl+2 | "Connect to Text Editor"

Quick-Buttons

In addition to the generic quick-buttons in all Telelogic Tau tools, the editor tool bar contains the following quick-buttons. See also "General Quick-Buttons" .

Text window on / off
Toggle the text window between visible and hidden (see "Text Window" ).

Symbol menu on / off
Toggle the symbol menu between visible and hidden (see "Symbol Menu" ).

Previous page
(not valid for MSC and DP)
Open previous page in flow (similar to "<Page Name>" ). Dimmed if no previous page exists.

Next page
(not valid for MSC and DP)
Open next page in flow (similar to "<Page Name>" ). Dimmed if no next page exists.

Toggle Scale
Toggle the scale between a scale to show the complete diagram in the window (similar to Overview in "Set Scale" ) and a scale of 100%. For MSCs, the scale is adjusted to fit the diagram width in the window instead of the complete diagram.

Make space for new events
(MSC only)
Create space between two events (see "Make Space" ).

Remove space between two events
(MSC only)
Remove the unrequired space between two events.

Instance ruler on / off
(MSC only)
Toggle the instance ruler between visible and hidden (see "Instance Ruler" ).

Scrolling and Scaling

You can scroll the view vertically and horizontally by using the scrollbars. The view may also be scrolled automatically when you move the cursor beyond the current view, for example when you move an object or add a symbol.

If you move the cursor close to the edge of the current view, the automatic scrolling is slow. If you move it further beyond, the scrolling is quicker.

You can scale the view by specifying a scale or by zooming in and out.

To specify a scale:

  1. Select Set Scale from the View menu.
  2. In the dialog that will be opened, you can either:
    • Use the slider for setting the scale and then click the Scale button.

    • Click the Overview button to adjust the drawing area to the size of the window. (This has the same effect as the Scale Overview quick-button.)

To zoom in or out:

  • Click the quick-button for zoom in or zoom out.

Moving MSC Selection with Arrow Keys

You can move the selection using arrow keys in the MSC editor if there is one single symbol or line selected. The selection is moved along one instance in the vertical direction and between two instances in the horizontal direction.

In the MSC editor you are always in text editing mode, if there is a text to edit for the currently selected symbol. To move the symbol selection, press the arrow key one or several times in the direction you want to move. At first, only the text cursor position might be changed. But when the text cursor reaches the border of the text currently being edited (or if there is no text being edited), then the symbol selection will be moved.

One shortcut is available for fast-forward moving to the next/previous condition or instance head symbol attached to the current instance: Shift+up or down arrow key.

Lock Files and Read-Only Mode

When you open a diagram or document file, e.g. a.ssy, a lock file a.ssy.lck is created. If another user tries to open the same diagram or document file before you close it, a dialog will appear informing the other user that the file is in use. There are two choices in the dialog:

  • Open the file in read-only mode.
  • Reset the lock and open the file in read-write mode. (This alternative should only be used if the existing lock file is obsolete.)

The read-write mode is the normal editing mode. In read-only mode, you are not allowed to make any changes to the diagram.

You will also enter read-only mode if you open a diagram file that you do not have write permission for. The read-only mode is indicated by the words read-only in the window title.

If you want to edit a diagram that is in read-only mode, there are two alternative actions:

  • Change the file access rights in the file system to give you write permission for the diagram file. When that is done, you can change from read-only mode to read-write mode with the Revert Diagram operation.
  • Select File > Save As to save the diagram in a new file with write permission.

Symbol Menu

The symbol menu contains the symbols that you can place into the drawing area.

On UNIX, the symbol menu is a fixed-sized, non-moveable auxiliary window, associated with the drawing area and placed to the right of it. Each editor window has its own symbol menu.

In Windows, the symbol menu is a fixed-sized, moveable window that can be placed anywhere on the screen, not necessary within the limits of the editor window. A single symbol menu is shared by all instances of the editor currently running.

The symbol menu can be made invisible and visible again with a menu choice, Window Options, or a quick-button. In Windows: When visible, the symbol menu will always be placed on top of the editor window, if the two windows overlap.

Basically, when you select a symbol in the symbol menu and click it into the drawing area, it is added to the diagram. This chapter does not describe how to work with symbols. Working with MSC symbols is described in 42 Editing MSC Diagrams. See also "Working with Symbols" , as working with symbols in this editor is similar to working with symbols in the SDL Editor.

OM only: When a new class or object symbol is placed in the drawing area, it will automatically become an endpoint if the preferences AlwaysEndpointClass and AlwaysEndpointObject, respectively, are set.

The contents of the symbol menu depends upon the type of diagram that is displayed in the editor window, as can be seen in Figure 281. When you switch between diagrams of different types in the editor, the symbol menu changes accordingly.

Figure 281 : The editor symbol menus


About Symbols and Lines

The notation used for symbols and lines in the OM Editor complies with Static Structure (Class) diagrams defined in UML (Unified Modeling Language), version 1.3.

The notation used for symbols and lines in the SC Editor complies with State Chart diagrams defined in UML (Unified Modeling Language), version 1.3.

The notation used for symbols and lines in the DP Editor is based on the notation of Deployment and Component diagrams defined in UML (Unified Modeling Language), version 1.3.

The notation used for symbols and lines in the HMSC Editor complies with the ITU-T Z.120 recommendation from 1996. The comment symbol and the parallel frame symbol are not supported.

The notation used for symbols and lines in the MSC Editor complies with the ITU-T Z.120 recommendation from 1996. All MSC'96 symbols except the general ordering arrow are supported. Furthermore the MSC Editor does not support drawing of messages to the environment frame and message gates. Inline expressions are always global (i.e. they cover all instances).

For short explanations of when to use different symbols, see Symbols and Lines - Quick Reference.

Symbols

Diagrams contain different types of symbols that describe the structure of the diagram. All symbols must be placed inside the frame symbol. Figure 281 identifies these symbols in the symbol menu.

You can draw symbols in color, see "Color on Symbols" .

All symbols that are available in the symbol menu are selectable and moveable; they can be assigned arbitrary locations by you, with the exception that symbols are normally not allowed to overlap1. SC only: symbols can however be placed inside a state symbol, see "State Symbols" .

Common Symbol

A symbol common for all the editors is:

Symbol Appearance | Symbol Name | Summary
 | Text | Informal specification, global comments

Text Symbols

Text symbols contain informal text. It is not possible to connect any lines to a text symbol.

Double-clicking on a text symbol minimizes the symbol if not already minimized and maximizes the symbol if not already maximized.

Text symbols are typically used to add comments to diagrams or to convey system information (HMSC Editor: on a global level) that cannot be captured using the constructs offered by the editor.

When all of the text within a text symbol is in view, the upper right corner looks like a piece of paper that has been folded. When any portion of the text within a text symbol cannot be seen (because the text symbol is too small), the upper right corner looks like it has been clipped.

OM Symbols and Lines

See also Symbols and Lines - Quick Reference.

Symbol Appearance | Symbol Name | Summary
 | Class | Class definition
 | Object | Class instance

Text in Class and Object Symbols

OM symbols have one or more text compartments, which should be filled with a textual expression. While the OM Editor does not require that symbol text compartments should contain text, it will perform a syntactic check on text compartments as soon as they are changed and deselected.

The syntax rules of OM diagrams are detailed in "Object Model Syntax" .

Note:

The OM Editor does not enforce syntax correctness in OM class and object symbols. This means that it is possible to use any conventions you desire for the textual contents of symbols; however, some features offered by the OM Editor will not be available, notably the Browse & Edit Class dialog.

Syntax checking on text in general is described in greater detail under "Textual Syntax Checks" .

Class Symbols

A class symbol is divided into three horizontal compartments. In order from the top, the compartments are:

  • The name compartment
  • The attributes compartment
  • The operations compartment

The text in these compartments is parsed by the OM Editor and should conform to the syntax specified in "Class Symbol Syntax" .

In the name compartment two more extra text fields can appear. If adding text to the stereotype and properties fields in the Symbol Details window, these texts will also be visible inside the name compartment. These texts are not subject to syntactic checks.

Figure 282 : Class symbol with stereotype and properties texts

If you double-click a class symbol, the Browse & Edit Class dialog will be opened (see "Browse & Edit Class Dialog" ).

Object Symbols

Used to describe an OM object, or an instance of a class.

An object symbol differs from a class symbol in that it does not contain an operations compartment. In addition, the remaining compartments require a somewhat different syntax, see "Object Symbol Syntax" .

The object symbols handles stereotype and properties texts in the same way as the Class symbol.

If you double-click an object symbol whose name compartment includes a class name2, the Browse & Edit Class dialog will be opened (see "Browse & Edit Class Dialog" ).

Lines

Lines are the graphical objects that interconnect objects. Normally a line interconnects two symbols but it could also connect a symbol with another line. The following types of lines interconnecting symbols are defined in OM diagrams (see Figure 283):

  • Association
  • Aggregation
  • Generalization

The only line interconnecting a symbol and a line in OM diagrams is:

  • Link Class

Figure 283 : Lines in OM diagrams

To insert lines, select a class or object symbol, drag one of the handles that appear on the source symbol and connect it to the target symbol. There is one handle for each type of line.

Figure 284 : Handles for different line types

The Link Class line handle is placed on selected association and aggregation lines.

Figure 285 : Handle for Link Class line

When a handle is clicked, the status bar shortly describes what the handle is used for and how to draw a line. This chapter does not describe how to work with lines. However, working with lines in the OM Editor is similar to working with lines in the SDL Editor; see "Working with Lines" .

Lines are always connected to objects; they are not allowed to exist on their own. A line is allowed to overlap any other object.

Lines are selectable; they can be moved and reshaped by you. Some layout work is performed automatically by the OM Editor.

Double-clicking on a line brings up the Line Details window (see "Line Details Window" ).

See also "Line Attribute Objects" .

SC Symbols and Lines

See also Symbols and Lines - Quick Reference.

Symbol Appearance | Symbol Name | Summary
 | State | State definition.
 | Start | Starting point of the SC.
 | Termination | Termination point of the SC.

Text in State Symbols

State symbols have three text compartments which should be filled with textual expressions, but are allowed to remain empty. A syntactic check on a text compartment is performed as soon as it is changed and deselected.

State Symbols

A state symbol contains a state section which is divided into horizontal compartments. In order from the top, the compartments are:

  • The Name compartment
  • The Internal Activity compartment

The text in these compartments should conform to the syntax specified in "State Symbol Syntax" .

The state symbol may have an additional compartment with a graphic region holding a nested SC. This is called the substate compartment and states with this compartment are often called hierarchical states or superstates. The state will be extended with this compartment when a symbol is placed within it. The compartment disappears when the last symbol is removed from it.

Figure 286 : A state with its compartments

Text symbols are allowed to be placed inside the substate compartment but will not belong to the state. Thus, it will not automatically be part of the operations done on the state symbol, e.g. move, copy, etc.

Start Symbols

The start symbol is used to indicate where a SC starts.

Termination Symbols

The termination symbol is used to indicate where a SC terminates.

Lines

Lines are the graphical objects that interconnect objects. There is only one kind of line interconnecting symbols in SC diagrams, a transition line (see Figure 283):

Figure 287 : Transition line in SC diagrams

To insert lines, select a start or state symbol, drag the handle that appears on the source symbol and connect it to the target symbol.

Figure 288 : Handle for transition lines

When a handle is clicked, the status bar shortly describes what the handle is used for and how to draw a line. This chapter does not describe how to work with lines. However, working with lines in the SC Editor is similar to working with lines in the SDL Editor; see "Working with Lines" .

Lines are always connected to objects; they are not allowed to exist on their own. A line is allowed to overlap any other object.

Lines are selectable; they can be moved and reshaped by you. Some layout work is performed automatically by the SC Editor.

See also "Line Attribute Objects" .

DP Symbols and Lines

See also Symbols and Lines - Quick Reference.

.
Symbol Appearance | Symbol Name | Summary
 | Node | A run-time physical object that represents a computational resource (see [5]).
 | Component | A physical, replacable part of a system that packages implementation (see [5]).
 | Thread | An OS thread, i.e. a light-weight process. Not to be mistaken for an OS task, i.e. a heavy-weight process.
 | Object | An SDL entity, i.e. a system, block or process.

Double-clicking on a DP symbol brings up the Symbol Details window (see "Symbol Details Window" ).

Node Symbols

For node symbols the following text attributes can be edited:

  • The name text
  • The stereotype text
  • The properties text

The name text can be edited directly in the symbol and should conform with the syntax described in "Node Symbol Syntax" . The other texts can be edited in the Symbol Details window and are not subject to syntactic checks.

.

Figure 289 : Node symbol with stereotype and properties texts

Component Symbols

The text attributes of component symbols are the same and follow the same rules as those of node symbols. You can select the integration model for a component symbol from the Symbol Details dialog box. The syntax rules that apply are described in "Component Symbol Syntax" .

Figure 290 : Component symbol with properties text

Thread Symbols

For thread symbols only the name text is visual. From the Symbol Details dialog box, you can edit thread priority, stack size, queue size and max signal size for a thread. The syntax rules described in "Thread Symbol Syntax" are applied.

Object Symbols

Object symbols have the following text attributes:

  • The name text
  • The stereotype text
  • The properties text
  • The qualifier text

In the Symbol Details window the stereotype, properties and qualifier texts can be added. If the stereotype text for an object symbol is process the appearance of the symbol is changed.

.

Figure 291 : Object with stereotype "process"

The qualifier of an object symbol is displayed in the status bar when pointing the mouse at the symbol.

The syntax rules for the object symbol text attributes are described in "Object Symbol Syntax" .

Lines

Lines are graphical objects that interconnect objects. Two types of lines are defined in DP diagrams (see Figure 292):

  • Association
  • Composite Aggregation

Figure 292 : Lines in DP diagrams

To insert lines, select a symbol, drag one of the handles that appear on the source symbol and connect it to the target symbol. There is one handle for each type of line.

Figure 293 : Handles for different line types

When a handle is clicked, the status bar shortly describes what the handle is used for and how to draw a line. This chapter does not describe how to work with lines. However, working with lines in the DP Editor is similar to working with lines in the SDL Editor; see "Working with Lines" .

Lines are always connected to objects; they are not allowed to exist on their own. A line is allowed to overlap any other object.

Lines are selectable; they can be moved and reshaped by you. Some layout work is performed automatically by the DP Editor.

Double-clicking on a line brings up the Line Details window (see "Line Details Window" ).

See also "Line Attribute Objects" .

HMSC Symbols and Lines

See also Symbols and Lines - Quick Reference.

Symbol Appearance | Symbol Name | Summary
 | MSC Reference | Reference to another MSC diagram or MSC reference expression
 | Condition | Expresses alternative path in an HMSC
 | Connection Point | Expresses that lines are connected at this point
 | Start | Start of the HMSC road map.
 | End | End of the HMSC road map.

Reference Symbols

The reference symbol is used to refer to other (H)MSC's of the MSC document. The MSC references are objects of the type given by the references MSC.

MSC references may not only refer to a single MSC, but also to MSC reference expressions. MSC reference expressions are textual MSC expressions constructed from the operators alt, par, seq, loop, opt, exc and subst, and MSC references.

The text is parsed by the HMSC Editor and should conform to the syntax specified in "Reference Symbol Syntax" .

Double-clicking on a reference symbol opens the referenced MSC diagram. Note that if a reference symbol contains more than one name, you should place the cursor directly on one of the MSC names; otherwise an dialog is presented, see "Navigate" .

Condition Symbols

The condition symbol in HMSC's can be used to indicate global system states and impose restrictions on the MSC's that are referenced in the HMSC.

The text is parsed by the HMSC Editor and should conform to the syntax specified in "Condition Symbol Syntax" .

Connection Point Symbols

The connection point symbol in HMSC's is used to indicate that two (or more) crossing lines are actually connected.

Start Symbols

The start symbol in HMSC's is used to indicate where an HMSC road map starts.

End Symbols

The end symbol in HMSC's is used to indicate where and HMSC road map ends.

Lines

Lines are the graphical objects that interconnect objects. There is only one kind of line in the HMSC Editor.

To insert lines, select any3 of the symbols, drag the handle that appear on the source symbol and connect it to the target symbol.

Figure 294 : Symbol line handle

When a handle is clicked, the status bar shortly describes how to draw a line. This chapter does not describe how to work with lines. However, working with lines in the HMSC Editor is similar to working with lines in the SDL Editor; see "Working with Lines" .

Lines are always connected to objects; they are not allowed to exist on their own. A line is allowed to cross (but not overlap) another line. Since lines in HMSC's are directed, lines always starts at the bottom of a symbol and ends on the top of a symbol.

Lines are selectable; they can be moved and reshaped by you.

MSC Symbols and Lines

See also Symbols and Lines - Quick Reference.

Symbols are the graphical objects that build up the contents of an MSC. Lines are the graphical objects that interconnect symbols. Lines are available in the symbol menu and are thus handled as symbols.

Symbol
Appearance
Symbol Name
References to Z.120

Text

 Z.120  2.3

Comment

 Z.120  2.3

Instance head

 Z.120  4.2

Instance end

 Z.120  4.2

Message

 Z.120  4.3

Message-to-self

 Z.120  4.3

Found message

 Z.120  4.3

Lost message

 Z.120  4.3

Condition

 Z.120  4.6

Timer1

 Z.120  4.7

Separate timer set2

 Z.120  4.7

Separate timer reset

 Z.120  4.7

Separate timer consumed / timeout

 Z.120  4.7

Action

 Z.120  4.8

Create

 Z.120  4.9

Stop

 Z.120  4.10

Coregion

 Z.120  5.1

MSC Reference

 Z.120  5.4

Inline expression

 Z.120  5.3

Inline separator

 Z.120  5.3
1

The Z.120 symbols timer set and time-out are in this case merged into one symbol, the MSC Editor timer symbol.

2

A separate timer reset or timer consumed symbol is created by creating a separate timer set symbol, followed by changing its status to either reset or consumed.

Syntax Checking on Symbols and Lines

The MSC Editor checks that the symbols are positioned in the MSC in accordance to rules governed by Z.120. Lines are always connected to at least one symbol, they are not allowed to exist on their own. The MSC Editor checks that lines are connected to symbols in accordance to Z.120.

Graphical Properties of Symbols and Lines

All symbols that are available in the symbol menu are selectable and moveable. They can be placed automatically or you may, as long as the Z.120 syntax rules are respected, assign them arbitrary locations.

Lines are selectable; you can move them and reconnect them. Some layout work is performed automatically when a line is drawn.

Most of the symbols are not resizable; these are indicated by grayed selection squares. Other symbols may be resized; this is shown by a filled selection square.

Textual Attributes

Textual objects are the textual attributes that are related to a symbol or a line.

Some MSC symbols have one or multiple text attributes. A text attribute should be filled with an MSC/PR expression (textual expression) that is syntactically correct according to Z.120, alternatively filled with some informal text if the MSC concept is used informally.

Text attributes related to messages and timers may be moved freely by you. Textual objects are allowed to overlap any other objects.

Line Attribute Objects

This section applies to OM, SC and DP only.

Line attribute objects represent additional items of information associated with lines. It is not possible to create free line attribute objects that are not associated with any line; line attributes are always associated to, and destroyed with, their respective lines.

SC only: Each transition line has a line attribute object, the transition label, which is pre-created by the SC Editor when you create a line. You may ignore this attribute or fill in the textual contents, as appropriate. The text should conform to the syntax specified in "Transition Line Syntax" .

OM only: Each type of line has a primary line attribute object, the name (for associations and aggregations) or discriminator (for generalizations) attribute, which is pre-created by the OM Editor when you create a line. You may ignore the primary attribute or fill in the textual contents, as appropriate.

DP only: Each type of line has a primary line attribute object, the protocol (for associations) or multiplicity (for aggregations) attribute, which is pre-created by the DP Editor when you create a line. You may ignore the primary attribute or fill in the textual contents, as appropriate.

OM and DP only: A number of secondary line attribute objects can be created for each line using the Line Details window (see "Line Details Window" and "Line Details Window" respectively). The exact number and types of line attribute objects depends on the type of line and is summarized in tables below.

Line attribute objects have a number of common characteristics:

  • They are conceptually attached to the closest line segment of the associated line and will be moved and redrawn as appropriate whenever the line's layout is changed4.
  • A selected textual line attribute object is indicated by a small rectangle which shrink-wraps the actual text. If the textual attribute is editable, the text cursor will appear at the current insertion position inside the text, and the text window will contain the text of the selected attribute object.
  • Textual line attribute objects always display their entire contents; it is not possible to collapse them to avoid displaying large amounts of text, as is the case with class and object symbols.
  • OM and DP only: Syntax checks are not performed on textual line attribute objects.
  • OM and DP only: All textual line attributes except the line's primary attribute will be destroyed if their textual contents is cleared and the attribute is selected. To recreate a destroyed attribute, use the Line Details window.

OM only: While most line attributes can be moved freely and are allowed to overlap other objects, some attributes, such as the association qualifier, are restrained by graphical layout restrictions and cannot be freely moved.

OM Line Attribute Objects

Name and Graphical Appearance
Line Attribute Objects
(· Primary and - Secondary)

Association

  • Name of the association
    • Reverse Name
    • Role Name
    • Role Multiplicity
    • Qualifier
    • Sorted
    • Ordered
    • Derived Attribute
    • Constraint
Aggregation
  • Name of the aggregation
    • Reverse Name
    • Role Name
    • Role Multiplicity
    • Qualifier
    • Sorted
    • Ordered
    • Composite
Generalization
  • Discriminator of the generalization
Link Class
  • No line attributes

OM Aggregation/Association Attributes5

Attribute Appearance | Attribute Name (Properties) | Summary
 | Name (Pre-created, Editable, Optional arrow) | Names a conceptual connection between object instances. While always bidirectional, the name usually denotes traversal of the association in the "forward" direction, as defined by the optional arrow.
 | Reverse Name (Editable, Optional arrow) | Allows a separate name to be used when the link is traversed in the opposite direction.
 | Qualifier (Editable, Not moveable) | Describes an association between two objects that is defined by the identity of a third object.
 | Ordered (Not editable) | The ordered attribute puts additional constraints on a one-to-many association.
 | Sorted (Not editable) | The sorted attribute puts additional constraints on a one-to-many association.
 | Role Name (Editable) | Each end of an association is called a role. While redundant, well-named roles can sometimes facilitate analysis.
 | Role Multiplicity (Editable) | Multiplicity is used to constrain the number of related objects. Multiplicity can be fixed, a closed range, an open range, or any combination of these.
 | Derived Attribute (Not editable, Not moveable) | Indicates that the association represents redundant information, that can be calculated by following other associations.
 | Constraint (Editable) | Allows the specification of arbitrary constraints. The specified text is automatically placed between `{` and `}'.

OM Aggregation Attributes

Attribute Appearance | Attribute Name (Properties) | Summary
 | Composite (Editable) | Indicates aggregation with strong ownership.

OM Generalization Attributes

Attribute Appearance | Attribute Name (Properties) | Summary
 | Discriminator (Pre-created, Editable) | The discriminator describes which property of an object is being abstracted by a particular generalization relationship.

SC Line Attribute Objects

Name and Graphical Appearance
Line Attribute Objects

Transition

  • Transition label of the transition

SC Transition Attributes

Attribute Appearance | Attribute Name (Properties) | Summary
 | Transition label (Pre-created, Editable) | Describes the transition. For a description of the syntax, see "Transition Line Syntax" .

DP Line Attribute Objects

Name and Graphical Appearance
Line Attribute Objects
(· Primary and - Secondary)
Aggregation
  • Name of the association
    • Protocol
    • Encoding
    • Direction
Composite Aggregation
  • Multiplicity of the composite aggregation

DP Association Attributes

Attribute Appearance | Attribute Name (Properties) | Summary
 | Protocol (Pre-created, Editable) | The protocol of the communication path.
 | Name (Editable) | The name of the communication path.
 | Encoding (Editable) | The encoding of the communication path.
 | Direction (Editable) | The direction of the communication path.

DP Aggregation Attributes

Attribute Appearance | Attribute Name (Properties) | Summary
 | Multiplicity (Pre-created, Editable) | Multiplicity is used to constrain the number of related objects. Multiplicity can be fixed or an infinite number.

1

In certain situations symbols will overlap as a consequence of automatic resizing when new text is entered in the symbols. Such symbols can only be moved to areas where an overlap does not occur.

2

A class name is considered present only if the class name follows the object name after being separated by a colon `:' character.

3

This does not apply to the stop symbols, since lines can not be drawn from it, only to it.

4

While the results are normally what you would prefer, it is always possible to manually adjust the position of moveable line attributes after repositioning the line.

5

While these attributes are available both for associations and aggregations, they are much more often used for associations. The use of these attributes for aggregations depends on how sharply the analysis or design separates between association and aggregation.


Editing Text

General

The drawing area is a container for different types of objects that each may contain zero or more text compartments. In addition, the lines that connect objects also have zero or more textual attribute objects.

The editor allows these textual objects to be edited directly in the drawing area, allowing you to see directly how the textual object resizes to shrink-wrap the text.

To directly edit a textual object in the drawing area, simply position the text insertion cursor at the desired position in the text. To indicate that a textual object is being edited, a thin vertical bar designating the text insertion cursor appears at the selected text insertion point. As soon as you type some text, the keyboard input mode will change to text editing mode. This is indicated by a flashing and thicker insertion bar.

In text editing mode, all accelerator keys are interpreted as input to the text. As an example, the <Delete> key will in text editing mode delete a character, but in non-text editing mode it will remove (Clear) an entire symbol. This means that you can only use text editing keyboard accelerators like <Home>, <End>, <Ctrl+A> and <Ctrl+E> in text editing mode only.

While useful for quickly editing small texts, direct editing in the drawing area suffers from some restrictions:

  • While it is possible to position the insertion cursor in the text using the mouse or the arrow keys, it is not possible to make any selections in the text, for deletion or replacement.
  • If the text becomes large enough to cross the drawing area boundary, parts of the text will no longer be visible.

To alleviate these and other limitations, the editor offers a text window that provides a more complete set of text editing features. See "Text Window" for more information. In addition, it is possible to use an external text editor for larger amounts of texts; see "Connect to Text Editor" .

Regardless of whether editing takes place directly in the drawing area or in the text window, the editor makes sure that the contents of both displayed texts are consistent, which makes it convenient to use both text editing mechanisms in the same diagram.

Textual Syntax Checks

Some texts in the editor are subject to syntactic checks as soon as they are changed. Errors detected during syntax checks will be displayed in the textual object by underlining the first characters at the position where the first syntax error was detected.

Minimum Size of Textual Symbols

While symbols are resized automatically to fit the containing text, the editor defines a minimum size for each symbol, ensuring that even empty symbols will be recognizable:

  • The predefined minimum width of any symbol with text is 20 mm.
  • The minimum height for symbols with text is calculated based on the height of the symbol font.
  • The minimum height for text symbols is 10 mm.

Delayed Updating of the Drawing Area

When you edit the text in the text window, the updating of the drawing area is at least delayed for the value of the preference FontText*MinimumTextUpdateDelay.

If the text is large, the update delay is extended proportionally. The text window is however always updated immediately.

In addition, any attempt to enter an illegal character will always result in an audible warning.

Text Window

The text window works in the same way for OM, SC, DP, MSC and HMSC diagrams. There is one text window common for OM, SC, DP and HMSC diagrams, and a separate text window for MSC diagrams.

On UNIX, the text window is a pane of the editor window and can be resized vertically.

In Windows, the text window is a resizable and moveable window that can be placed anywhere on the screen, not necessary within the limits of the editor window. A single text window is shared by all instances of the editor currently running.

If you select one object in the editor window, the text window is updated to contain the text associated with that object, but not if you select more than one text object.

Each line (except for the last line) in the text window is terminated by a carriage return, and may consist of any number of legal characters.

The text window provides a menu bar with two menus which are described in:

  • "File Menu of the Text Window"
  • "Edit Menu"

Hiding and Showing the Text Window

You can hide and show the text window with the Window Options command from the View menu, or by using a quick-button.

In Windows: When visible, the text window will always be placed on top of the editor window.

Searching and Replacing Text in an MSC

The text window provides standardized functions for searching and replacing text in an MSC.

If all the textual objects you want to search in are not visible (i.e. instance name, instance kind, instance composition, message name and message parameters) adjust the Diagram Options.

Copying, Cutting and Pasting Text

The text window provides standardized clipboard functions for copying, cutting and pasting text between different symbols, lines and text attributes. These functions do not interfere with the clipboard functions for cutting, copying and pasting objects.

Programmable Function Keys (UNIX only)

On UNIX, it is allowed to tie a function key to a defined text string. When typing that defined function key, the programmed text string will be inserted at the current cursor location. You can customize your own programming of function keys.

Global X Resources

The function keys are set up as X resources. It is possible to set up both system default and user-defined X resources, allowing you to customize your environment. The X resources are defined in a file that is common for all users, namely

/usr/lib/X11/app-defaults/SDT

To program the function keys, insert the following lines anywhere into the SDT file:

/* Any suitable comment */
SDT*XmText.translations: #override \n\
<Key>F1: insert-string("F1Text") \n\
<Key>F2: insert-string("F2Text") \n\
<Key>F3: insert-string("F3Text") \n\
<Key>F4: insert-string("F4Text") \n\
<Key>F5: insert-string("F5Text") \n\
<Key>F6: insert-string("F6Text") \n\
<Key>F7: insert-string("F7Text") \n\
<Key>F8: insert-string("F8Text") \n\
<Key>F9: insert-string("F9Text")
/* Note the absence of \n\ on line 9 */

Note:

Omitting to define some of the function keys is permissible.

User-Defined X Resources

You can define your own function keys. This is done by defining the X-resources described above in a personal copy of the definition file and to store that file into your home directory:

~username/SDT

Alternatively, any directory designated by environment variable XAPPLRESDIR can be used.

Restrictions

  1. Only one line for each function key can be defined. Attempting to define more than one line into one function key may cause an unpredictable result when pressing that key.
    For instance, it is not certain that the following line will produce the expected result:
<Key>F1: insert-string("F1Line1\nLine2") \n\

  2. Only the keys F1-F9 can be defined.

Changing Fonts on Text Objects

You may change the font faces and font sizes used in the textual objects displayed by the editor. All textual objects use the same font faces and font sizes, meaning that they cannot be changed individually and cannot be changed during an editor session.

The font faces which are available depend on the target system on which you are running the SDL suite.

Defining What Font to Use

To modify the desired font size and font face, you must use the Preference Manager. See 4 Managing Preferences.

Textual Objects Preferences

When the setting is in effect, the SDL suite diagram editors will use the font face names given by the preference settings

OME*ScreenFontFamily
OME*PrintFontFamily

to select font face names. Note that in this way you can select different font names for screen and for print.

On UNIX, if you leave the Editor*FontText*ScreenFontFamily preference setting empty, you will edit your documents using the SDT Draft font, but print them using the font you specified with the Editor*FontText*PrintFontFamily setting.

Supported Font Faces

On UNIX, the availability of font faces is determined by the version of the X Windows server which is running. With revision 5 or higher (X11 R5), scalable fonts are supported. In that case, the available list of predefined font faces would be:

  • Times
  • Helvetica
  • Courier
  • SDT Draft (mapped to the Schumacher font)
  • Other (mapped to a user-defined font)

In Windows, the availability of font faces is determined by the TrueType fonts that are currently installed on the computer (use for instance the Windows Control Panel to determine what is available).

Default Font Face

The default font face is Helvetica (see the preferences ScreenFontFamily and PrintFontFamily described in "OM/SC/HMSC/MSC/DP Editor Preferences" ).

On UNIX, if scalable fonts are not supported, the font face will be replaced by a Schumacher font which may be used in all circumstances (MSC only).

Default Font Size

Font sizes are described in "NameTextHeight" and "TextHeight" .

They are used as follows:

Common Font Sizes

Text Object | Font Size | Other
Heading symbol | NameTextHeight |
Text symbol | TextHeight |

OM Font Sizes

Text Object | Font Size | Other
Class symbol name | NameTextHeight | Bold
Object symbol name | NameTextHeight | Bold
Stereotype text | TextHeight |
Properties text | TextHeight | Italic

SC Font Sizes

Text Object | Font Size | Other
State symbol name | NameTextHeight | Bold

DP Font Sizes

Text Object | Font Size | Other
Symbol name | NameTextHeight | Bold
Stereotype text | TextHeight |
Properties text | TextHeight | Italic

HMSC Font Sizes

Text Object | Font Size
Reference Symbol | TextHeight
Condition symbol | TextHeight

MSC Font Sizes

Text Object | Font Size
All MSC special symbols | TextHeight

Determining Which Scalable Fonts Your Server Can Access (UNIX only)

On UNIX, use the xlsfonts command to list installed fonts. Font names containing 0 for width and height are scalable.

Example 295 : How to determine which fonts are available

From the OS prompt, typing:

hostname% xlsfonts | grep "\-0\-0\-" | more

will return a list of accessible scalable fonts.

Scalable Fonts Under R5 Servers

To use scalable fonts under X11R5 you must normally first connect to a font server.

Example 296 : How to Start the Font Server

  1. Start the font server on any local host:
hostname% fs
  2. Connect the server to fs indicating which host the font server is running on (which can be the same host that the X server is running on):
hostname2% xset +fp tcp/<hostname>:7000

For further information see the X11R5 documentation or use man fs to read the manual page describing the font server you are running.

Disabling Font Scaling (UNIX only)

On UNIX, if the fonts look poor on the screen, a possible work-around is to disable the scaling option.

Note:

Disabling font scaling effectively disables WYSIWYG!

To do this, you should edit the SDT resource file.

  1. Open the file SDT in a text editor.
  2. Locate the line with the text: SDT*sdtUseScalableFonts
  3. Change the line to SDT*sdtUseScalableFonts: false
  4. Save the file and restart the SDL suite environment.


Menu Bars

The editor menu bar provides the following menus:

  • File Menu
  • Edit Menu
  • View Menu
  • Pages Menu
  • Diagrams Menu
  • Window Menu
  • Tools Menu
  • Help Menu

The Help menu is described in "Help Menu" .

File Menu

The File menu supports the following commands on diagrams:

  • New
  • Open
  • Save
  • Save As
  • Save a Copy As
  • Save All
  • Close Diagram
  • Revert Diagram
  • Print
  • Exit

The File menu choices are described in "File Menu" , except Print which is described in "The Print Dialogs in the SDL Suite and in the Organizer" .

Edit Menu

The Edit menu provides editing functions that you can perform on objects in a diagram, or on text in the text window. The Edit menu contains the following menu choices:

  • Undo
  • Cut, Copy and Paste
  • Paste As
  • Clear
  • Clear Objects
  • Keep Objects
  • Expand/Collapse
  • Line Details
  • Symbol Details
  • Class
  • Drawing Size
  • Select All
  • Redirect
  • Connect
  • Status
  • Make Space
  • Decompose

Undo

This command restores the content of the drawing area to its state prior to the most recently performed operation. Text editing operations cannot be undone.

Editor
Operations you can undo
OM, SC, DP, HMSC
  • Cut, Copy and Paste and Clear
  • Resizing a page
  • Adding/moving symbols
  • Drawing/reshaping/redirecting lines
OM
  • Editing a symbol (Symbol Details Window)
  • Editing a line (Line Details Window)
DP
  • Editing a symbol (Symbol Details Window)
  • Editing a line (Line Details Window)
OM
  • Editing a class (Browse & Edit Class Dialog)

Note: Undoing an Edit Class operation will undo the changes in all affected diagrams.
SC
  • Expanding/collapsing symbols
HMSC
  • Editing a symbol
  • Editing a line
MSC
  • Cut, Copy and Paste and Clear
  • Undo
  • Redirect
  • Connect
  • Moving Objects
  • Adding and Removing Objects

Cut, Copy and Paste

These commands provide standardized clipboard functions for copying, cutting and pasting objects in the drawing area or text in the text window.

You can interrupt a Paste operation by pressing <Esc>.

The MSC specific rules regarding the Paste command are described in "Pasting in MSC Diagrams" .

Paste As

Pastes the currently copied object (from the OM or Text Editor) as an OM symbol or MSC object in the drawing area. The object is transformed and a link is optionally created between the copied and pasted objects.

The Paste As dialog is opened. See "The Paste As Command" .

Clear

This command removes the selected objects from the drawing area, or the selected text from the text window.

Also see "Deleting an Object" .

Clearing an instance head symbol or its instance axis line in an MSC diagram will also remove all objects that were connected with the instance axis regardless of if they were selected or not.

  • A created instance left without "parent" is kept in the chart as static instance.
  • Clearing an instance end reconnects the instance axis to the bottom of the chart.

Clear Objects

This MSC command removes all objects similar to the selected objects. For instance, select one message A object and one message B object and invoke this command to remove all occurrences of message A and B. To remove the empty spaces after removed objects, use Rearrange.

Keep Objects

This MSC command removes all objects of the same type as the selected objects that are not similar to the selected objects. For instance, select one message C object and one message D object and invoke this command to remove all messages except C and D. To remove the empty spaces after removed objects, use Rearrange.

Expand/Collapse

If a text symbol or a comment symbol is selected, this command allows you to expand or collapse the symbol from or to its minimum size.

If an MSC diagram is selected, the Collapse command collapses the selected instance axes to give you an overview of the diagram. A complex MSC can in this way be viewed in several decomposed MSCs. Two diagrams are created; one where the instances you have selected are collapsed into a decomposed instance and one where the behavior of the instances you have selected are shown. You can Navigate from a decomposed instance to the referenced diagram.

If an OM class, OM instance or SC state symbol is selected, this command selects whether all compartments should be displayed or not. A collapsed symbol will only display the name compartment (including the stereotype and properties texts for an OM symbol), which is particularly useful when referring to a symbol that is defined elsewhere.

Line Details

This OM and DP command brings up the modeless Line Details window, that is used to inspect and edit the properties of the currently selected line. If there is none or more than one selected object, the items in the Line Details window will be dimmed.

The Line Details window and its appearance for different type of OM lines is described in "Line Details Window" . For DP lines it is described in "Line Details Window" .

Symbol Details

This OM and DP command brings up the modeless Symbol Details window, that is used to inspect and edit the stereotype and properties texts of the currently selected OM class or object symbol. If a DP node or component symbol is selected the stereotype and properties texts can be edited. For a component symbol, integration model can also be selected. For a DP thread symbol, the thread priority, stack size, queue size and max signal size texts are editable. For a DP object symbol the stereotype, properties and qualifier texts can be edited.

The Symbol Details window and its appearance are described in "Symbol Details Window" (for OM symbols) and in "Symbol Details Window" (for DP symbols).

Class

This OM command brings up the modal Browse & Edit Class dialog on the currently selected OM class or object. This dialog is used to inspect and edit OM classes and objects over page and diagram boundaries.

The Browse & Edit Class dialog is described in detail "Browse & Edit Class Dialog" .

Drawing Size

Issues a dialog where the width and height can be adjusted. The values will be saved.

Enlarging the drawing, the current page may not fit any longer into the paper that is defined with the Print preferences; the result may be a page that requires multiple sheets of paper when printed.

Select All

This operation selects all objects contained within the drawing area, or all text in the text window.

Status

This MSC command displays and possibly modifies the status of timers.

For more information see "Displaying and Modifying Status" .

Make Space

This MSC command presents the Make Space dialog, where space for events may be inserted.

  • The radio buttons Before selected object and After selected object define whether space for insertion of events should be created before or after the currently selected object.
  • The Space of text field allows to specify how many events should be possible to insert.
  • Clicking OK inserts space according to the number of events. All objects which are found after the currently selected object are pushed downwards.

Redirect

This OM command changes the orientation of the selected aggregation or generalization line.

This SC command changes the orientation of the selected SC transition line(s).

This DP command changes the orientation of the selected DP association line, if the line currently has a direction. The direction of a DP association line can be changed in the Line Details window.

This MSC command changes the orientation of a selected message. The new direction is indicated by a change in the orientation and position of the message end and of the message parameters.

Connect

This MSC command opens a dialog that is used to connect a selected condition or MSC reference symbol to one or multiple instances.

Figure 295 : The Connect dialog (for a condition)

The Name field allows you to enter or change the name of the condition or MSC reference.

The Instance List lists all possible instances that are concurrent with the condition or MSC reference.

  • Instances in the list that are selected or already connected are highlighted. Clicking an entry in the list toggles its state between highlighted and not highlighted.
  • Select Connect connects the condition or MSC reference symbol to the instances in the instance list that are currently selected.
  • Selecting Global connects the condition or MSC reference symbol globally to all instances in the list.

Decompose

This MSC command creates a new diagram of an instance axis in the original diagram. The instance axis you decompose is marked decomposed. In the new diagram you can specify the interior of the decomposed instance.

The messages to and from the decomposed instance are displayed as found and lost messages (see "MSC Symbols and Lines" ), showing the communication with other instance axes. The decomposed diagram is editable and it is displayed in the Organizer.

View Menu

The View menu provides rescaling functions and access to various options that affect the behavior of the editor. The View menu contains the following menu choices:

  • Set Scale
  • Window Options
  • Diagram Options
  • Editor Options
  • Insert Options

Set Scale

This menu choice issues a dialog where you can adjust the scale.

Window Options

This menu choice issues a dialog where you can set the options that affect the window properties.

In the dialog, you can set if you want the following items to be displayed:

  • Tool Bar
  • Status Bar
  • Symbol Menu
    On UNIX, the space allocated to the symbol menu will be reused by the drawing area when you hide the symbol menu.
  • Instance Ruler
    The space allocated to the MSC instance ruler will be reused by the drawing area when you hide the instance ruler.
  • Text Window
    On UNIX, the space allocated to the text window will be reused by the drawing area when you hide the text window.
  • Page Breaks
    This option determines whether physical page breaks, with the appearance of dashed horizontal and vertical lines, should be displayed or not in the drawing area. These page breaks are defined by the print preferences. Also, a number is shown in the bottom of each printout page, indicating the physical page number when printed.
  • Show Grid

Click OK to apply the options in the dialog to the current window only.

Click All Windows to apply the options in the dialog to all windows opened by the editor.

Diagram Options

This MSC command issues a dialog where you can set the options that determines what should be displayed in the drawing area:

  • Show Instance Name
  • Show Instance Kind
  • Show Instance Composition
  • Show Message Name
  • Show Message Parameters

Click OK to apply the options to the current MSC. The diagram options will be saved when you save the file.

Editor Options

Opens a dialog where you can customize the behavior of the editor.

The options are controlled by toggle buttons. They are:

  • Always new Window
    This option indicates whether or not a new window should be opened when a new diagram is opened or created. The default behavior is not to open a new window.
  • Sound
    This option indicates whether or not improper actions in the editor, such as attempting to append a symbol to an illegal position, should be brought to your attention by producing an alert sound. The default value for this option is on.
  • Show Link Endpoints
    This option indicates whether endpoint markers should be displayed for symbols having link endpoints. The default value is on.

Insert Options

This MSC command issues a dialog where spacing between symbols may be specified. (The dimmed parts of the dialog are for future use.)

Figure 296 : The Insert Options dialog

Spacing

This option allows to modify the space which is automatically inserted between the symbols and lines when appended to the chart.

There are two scales for setting the minimum horizontal distance between instance axes and the minimum vertical distance between messages.

Pages Menu

This section applies to all editors except MSC and DP.

The Pages menu holds commands that assist you in navigating among the pages in a diagram that are currently being edited in the editor. It also contains commands for adding, renaming and clearing pages as well as clipboard functions for copying, cutting and pasting entire pages.

The Pages menu contains the following menu choices:

  • First
  • <Page Name>
  • Last
  • Add
  • Edit

First

This menu choice opens the first page contained in the diagram. The first page is defined according to the order of appearance in the Edit Page dialog.

<Page Name>

Activating the Pages menu presents up to four menu choices that consist of the names of the two pages that are sequentially immediately before and after the page being edited. If the first page of the diagram is being edited, the next four sequential pages are shown. If the last page of the diagram is edited, the previous four pages are shown.

Selecting one of these page names opens or restores that page in the editor. To open other pages, the Edit menu choice is used.

Last

This menu choice opens the last page of a diagram.

Add

This menu choice is a shortcut for adding one page to the current diagram. The Add Page dialog is issued and after pressing the OK button the new page is shown.

Edit

This menu choice allows to Add, Rename, Clear, Cut, Copy and Paste a page. Following this menu choice, a dialog is issued:

Figure 297 : The Edit Pages dialog

The meaning of the various components is as follows:

Edit Pages List

Presents a list with all pages that are included in the diagram. Clicking on a page in this list selects it and makes it the subject of the operation to follow.

Edit Button

Clicking this button opens the selected page and displays it in an editor window. The Edit Page dialog is closed.

Cut

Clicking this button removes the selected page from the diagram and saves it in the clipboard buffer.

Copy

Clicking this button copies the selected page into the clipboard buffer.

Paste

Clicking this button pastes the page contained in the clipboard buffer into the current diagram. A new dialog is issued.

The dialog allows to specify:

  • The new name of the page. By default the page is autonumbered (the preference is described in "AutoNumberPages" ).
  • If the new page should be pasted before or after the current page.
  • Clicking the Paste button pastes the page according to the options as set up in the dialog and returns control to the Edit Page dialog.

Clear

This operation clears (removes) the selected page from the diagram.

To confirm the operation, click on Clear. The editor will automatically rename autonumbered pages.

Caution!

As stated in the dialog, Clear on a page cannot be undone.

Add

This command creates a new page which is added to the current diagram.

A new dialog is issued, in which you must insert the page name. You can insert the new page either before or after the current page.

The dialog allows to specify:

  • The page name. By default the page is autonumbered (this preference is described in "AutoNumberPages" ).
  • Before / After current page
    The new page is inserted according to the status of these radio buttons.
  • Clicking OK adds the page and returns control to the Edit Page dialog.

Rename

Click this button to open a dialog where you can rename the selected page.

Note:

Autonumbered pages cannot be renamed. The autonumbered option must first be turned off.

  • Type in the new name of the page.
  • Click OK to rename the page. Control is returned to the Edit Page dialog.

Autonumbered

When turning the Autonumbered option off, the editor first prompts to confirm the removal of autonumbering on that page.

  • Click Yes to remove autonumbering on the page and then open a dialog where you can rename the page (see "Rename" ).
  • Click No to cancel the operation. The page remains autonumbered.

Turning the Autonumbered option on applies a numeric name to the selected page (1, 2, etc...). A dialog is issued where:

  • Yes auto-numbers the selected page.
  • All Pages auto-numbers all pages contained in the diagram.
  • No closes the dialog without autonumbering the pages.

Open this page first

This toggle button designates what page to be opened first when opening a diagram in the editor, if no particular page is specified.

Diagrams Menu

The Diagrams menu records all diagrams that are opened by the editor. The menu choices are:

  • Back
  • Forward
  • <Diagram Name>
  • List All

Back

Select this menu choice to browse back to the diagram that was previously displayed in the window.

Forward

Select this menu choice to browse forward to the diagram that was displayed in the window before you selected Back.

<Diagram Name>

The last edited diagram always goes to the top of the list, and subsequently moves the other diagrams down a position. A maximum of 9 open diagrams can be shown. A tenth one will be put at the top of the list, but any subsequent opening of a diagram will only show the last 9 that have been opened.

Each item in the menu provides information about the diagram type, its name, a slash (`/') followed by a page name, a hyphen and, possibly, the file it is stored on (the file information is missing if the diagram has never been saved).

A diagram that is preceded by an asterisk (`*') denotes that it has been modified during the editor session.

Note:

OM, SC, DP and HMSC diagrams are listed in the same Diagrams menu, whereas MSC diagrams are listed only in the Diagrams menu of the MSC Editor window.

List All

This menu choice becomes available when a maximum of 9 open diagrams has been surpassed. When List All is selected, it provides a dialog containing all diagrams that are currently open in the editor. Select a diagram and click Edit to display it.

Window Menu

The Window menu contains the following menu choices:

  • New Window
  • Close Window
  • Entity Dictionary
  • Info Window
  • <Window Name>
  • List All

New Window

This command opens a new editor window containing a new view on the page, MSC or DP diagram contained in the source window from which this menu choice was operated. The page, MSC or DP diagram can be edited in any window.

Close Window

This option closes the open window, but, not necessarily the diagram.

If more than one editor window is opened, only the current window is closed and not the diagram. If the last open editor window is closed, the editor will act as if Exit has been chosen, possibly in conjunction with a save of information.

For more information, see "Close Diagram" ).

Entity Dictionary

Opens the Entity Dictionary window. See "The Entity Dictionary" .

Info Window

This MSC command issues a dialog as shown in Figure 298, displaying additional information about the currently selected MSC object.

Figure 298 : The Info dialog

The dialog presents:

  • A scrollable information window providing information about the currently selected object. What information is available depends on the selected object. See "Displaying Information About the Selected MSC Object" .
  • Show SDL Symbol
    A button that allows, if the MSC has been automatically generated, using the SDL Simulator or SDL Validator, to obtain a trace-back to the SDL source diagrams. Manually inserted symbols and lines do not, of course, contain any trace-back information. Clicking this button displays the SDL source symbol in an SDL Editor window. To behave properly, this feature requires that the SDL source diagram is consistent with the generated MSC, e.g. the SDL diagram may not have been modified so that the source symbol has been removed.

<Window Name>

If more than one editor window is open the other windows are listed here. The behavior of this list will be similar with the diagrams list in the "Diagrams Menu" . The only difference is that the menu items will not provide the diagram file information.

List All

This menu choice will be available only if more than 9 editor windows are open, and have the same functionality as the List All menu choice in the Diagrams menu.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
  • Link > Create
  • Link > Create Endpoint
  • Link > Traverse
  • Link > Link Manager
  • Link > Clear
  • Link > Clear Endpoint
  • Search
  • Spelling > Comments
  • Spelling > All Text
  • Connect to Text Editor
  • Show GR Reference
  • Create Bookmark
  • Convert SC to SDL
  • Filter
  • Tidy Up
  • Navigate
  • Rearrange
  • Generate MSC PR
  • Generate Input Script

All Link commands are described in "Link Commands in the Tools Menus" .

Search

This menu choice allows you to search for a text in the current diagram or document in an editor. The search can be restricted to a selected symbol type by using the Search In option menu.

You can search several diagrams and documents at the same time by using search from the Organizer, see "Search" .

Spelling > Comments

Check the spelling of comments in the current diagram. For more information about the spelling operation, see "Spelling > Comments" .

Spelling > All Text

Check the spelling of all text in the current diagram. For more information about the spelling operation, see "Spelling > Comments" .

Connect to Text Editor

This command issues an external text editor and creates a temporary file from the currently selected text. The text can from now on only be edited in the external editor. The editor is updated every time the external text editor saves the temporary file. When the temporary file is no longer edited, the editing control returns to the editor.

Which external text editor to use is defined by the preference SDT*TextEditor.

Show GR Reference

This command issues a message where the graphical reference for the currently selected object is displayed.

The syntax of the graphical references used in the editor is described in 19 SDT References.

Create Bookmark

This command creates a bookmark in the Organizer for the object you have currently selected.

Convert SC to SDL

This SC command transforms a State Chart to an SDL process diagram.

When the conversion is done, the SDL Editor displays the newly created process diagram. A new diagram is created for every conversion. The diagram resides in an unsaved SDL Editor buffer.

The transformation rules that are applied to the SC diagram are described in "Converting State Charts to SDL" .

Filter

This SC command allows you to hide uninteresting states, transitions or signals in a statechart. All three filters are combined, making it possible to hide stateX, transition (stateA)-signalB->(stateC) and signalZ at the same time.

Information about hidden entities is saved in a collapsed text symbol, to be able to recreate the entities when the filter is removed. The text in the text symbol starts with "HiddenTransitions:".

The dialog has the following options:

Apply filter

The current filter will be used when the dialog is closed with the OK button.

Create new editor buffer

A new statechart is created as a new editor buffer. If this option is off, the current statechart and editor buffer will be reused instead.

Always tidy up afterwards

The Tools>Tidy Up operation will be invoked after the filter has been applied. If this option is off, then the Tidy Up operation will only be invoked when needed, i.e. when states or transitions that was not visible before the operation become visible.

Create filter script text symbol

When the dialog is closed with the OK button, another dialog will appear, asking for a name for the filter. A text symbol, containing information about the current filter, will be created, starting with the text "Filter:<newline><filter name>". To reuse a filter saved in this way, select the text symbol before invoking the filter operation.

Tidy Up

This SC command rearranges the graphical layout of states and transitions in the State Chart. State hierarchies are flattened out, i.e. states in states are replaced with other constructs. Positions and sizes are determined by a default layout algorithm.

Navigate

The Navigate menu choice displays a (H)MSC diagram referenced by the reference symbol or a decomposed MSC.

Since a reference symbol may contain more than one reference name the HMSC Editor presents a dialog where you can choose reference name.

Goto

Pressing this button will show the diagram selected in the Navigation names list. If an (H)MSC diagram with that name is not present in the Organizer, a dialog will be shown. If more than one (H)MSC with the same name is present in the Organizer, an error message will be issued.

There are a number of situations when the dialog is not presented and the referenced diagram is shown immediately:

  1. There is only one reference name in the symbol.
  2. The caret is positioned in a reference name. This name will be automatically selected for navigation.

For reference navigation to work correctly it is required that the expression in the symbol is syntactically correct so that the names in the symbol can be extracted. Check out "Syntax rules in Symbols" . If you try to navigate from a symbol with incorrect syntax you will be notified with a dialog that points out the location of the error in the reference symbol text.

If you select a symbol that is not present in the Organizer you will be presented with a dialog where you can create either an MSC or an HMSC diagram.

Rearrange

This MSC command rearranges the symbols and lines in the MSC diagram to get a compact version of the same diagram. This command might for instance be useful after having removed several signals from the diagram.

Generate MSC PR

With this MSC and HMSC command you can save an MSC using the Z.120 MSC/PR format. (MSC/PR can also be read by the MSC Editor, see "Managing MSCs" ). The MSC Editor normally stores the MSCs using a binary storage format.

To generate MSC/PR:

  1. Display the MSC you want to generate MSC/PR from.
  2. Select Generate MSC PR from the Tools menu. A dialog is issued.
  3. Specify a file where to store the generated MSC/PR. The default file that the MSC Editor suggests consists of the name of the MSC, with the .mpr file extension, i.e. <diagramname>.mpr
  4. Make sure the Generate GR references1 radio button is turned on.
  5. Click Generate.

Comment Symbols and MSC/PR

Since free comment symbols, i.e. comment symbols that are not connected to any other symbol, are not permitted in MSC/PR but can be defined using the MSC Editor, free comment symbols are converted to text symbols in the generated MSC/PR.

Generate Input Script

This MSC command makes it possible to convert an MSC expressed in a certain, restricted way to an input script that can be used as a script in the SDL Simulator UI. In the Simulator UI, use the Execute>Input Script menu choice or the execute-input-script command to execute an input script.

How MSCs should be expressed to be able to use them as test scripts for the SDL Simulator is described in "Simulator Test > New Simulator" .

Note that normally, you do not manually convert MSCs to input scripts using this menu choice. Instead, the Organizer Tools menu choice Simulator Test > New Simulator auto-converts MSCs to input scripts when they are needed as test cases. Manual conversion is only needed if you want to stop working on the MSC level and start working on the textual Simulator UI command level instead.

File Menu of the Text Window

The File menu provides functions that transfer text from a file to the text window and vice-versa. The basic intention is to provide you a means to edit larger portions of text with a more suitable text editor. Another possibility to edit text externally is to use the Connect to Text Editor command in the Tools menu. The available menu choices are:

  • Import
  • Export

Import

Import imports the contents of a file into the text window and inserts the contents of the file at the current I-beam cursor position, possibly replacing selected text in the text window. A file selection dialog is issued, where the file to import text from is to be specified. The file name filter is set to *.txt by default.

Export

Export exports the text window contents to a file. A file selection dialog is issued, where the file to export the text to is to be specified. The file name filter is set to *.txt by default.

1

Event oriented MSC/PR describes the MSC using the order in which the events occur, i.e. starting with the top of the diagram and downwards, providing the feeling of a global event order.


OM Editor Specific Information

Browse & Edit Class Dialog

The Browse & Edit Class dialog is opened when you select Class from the Edit menu. The dialog allows inspection of OM diagram classes and objects across page and diagram borders.

An object model class is defined as the union of the attributes and operations in the class and object symbols, see "Class Definition Summary" , and the purpose of the Browse & Edit Class dialog is to display and ensure consistency when editing this combined information.

The Browse & Edit Class dialog is a modal dialog which is divided in two parts. The browsing functionality is placed at the top part of the dialog, where all classes in the scope, and all occurrences of each class are listed in two option menus. Below, in the editing part, the name of the class, all attributes and all operations are available.

The Browse & Edit Class dialog is available when a single class or object symbol has been selected:

  • If a class symbol is selected, the Browse & Edit Class dialog will operate on the class defined by that symbol. If the class name is empty or contains incorrect syntax, the Browse & Edit Class dialog will not be available.
  • If an object symbol is selected, the Browse & Edit Class dialog will operate on the class that the object symbol instantiates. If the object symbol does not include the name of the class it instantiates, the Browse & Edit Class dialog will not be available.

Browse

By using the topmost part of the Browse & Edit Class dialog it is possible to browse amongst all class and object symbols within the scope. The scope is either the entire Organizer module where the diagram is contained, or the diagram itself if it is not contained in an Organizer module. The module concept is described in "Module" and in "Module" .

Edit

By using the lower part of the Browse & Edit Class dialog it is possible to edit the name, attributes and operations of a class. The change will propagate into all class symbols of this class in OM diagrams within the module where the diagram is contained. The attributes and operations will be presented in a list. This list is parsed information from the texts in the class symbols. If a particular text contains syntax errors, it may lead to that attributes and operations contained in the same text do not appear in this list.

Figure 299 : The Browse & Edit Class dialog

The Scope Label

The scope label is a non-editable text field that describes the scope that the Browse & Edit Class dialog is operating in. The scope can be either a single OM diagram or all OM diagrams within an Organizer module.

  • If the diagram containing the object from which the Browse & Edit Class dialog was invoked is not part of a module in the Organizer, the scope label contains the text "Scope: diagram <diagram name>".
  • If the diagram containing the object from which the Browse & Edit Class dialog was invoked is part of a module in the Organizer, the scope label contains the text "Scope: module <module name>".

The Classes in Scope Option Menu

The Classes in Scope option menu contains a list of all classes within the scope. By selecting one of the classes in this menu the corresponding symbol will be shown and selected in the drawing area.

The Show Symbol in Option Menu

One class can be represented by several class symbols. The Show Symbol in option menu lists all occurrences of the class currently selected in the Classes in Scope option menu. The notation in the menu is <diagram-name>/<page-name>. By selecting an occurrence in this menu the corresponding symbol will be shown and selected in the drawing area.

The Class Name Field

The name field is an editable text field that initially contains the name of the class that is being edited.

By editing the class name field, it is possible to update all occurrences of that class name in class and object symbols in the current scope when the OK button is clicked.

The Attributes/Operations Buttons

The Attributes and Operations buttons select whether the attributes/operations list will contain a list of all attributes or all operations defined for the selected class. Only one of the attributes and operations buttons will be selected at any time.

The Attribute/Operations List

The attributes/operations list contains an alphabetically sorted list of the attributes or operations defined for the currently selected class.

The Clear Button

The clear button removes the currently selected operation or attribute from the Attribute/Operations list.

By clearing an attribute or operation using the clear button, that attribute or operation will be removed from all relevant class and object symbols using the current class name in the current scope when the OK button is clicked.

The Visibility Option Menu

The visibility option menu contains the visibility of the currently selected attribute or operation in the Attribute/Operations list, if any.

By selecting one of the predefined values in this menu and later clicking the OK button, the visibility of the selected attribute or operation will be updated in all relevant class symbols using the current class name in the current scope.

The Name Field

The name field contains the name of the currently selected attribute or operation in the Attribute/Operations list, if any.

Editing this field will change the definition of that attribute or operation in all relevant class and object symbols using the current class name in the current scope when the OK button is clicked.

The Parameters Field

The parameters field is an editable text field that contains the parameters of a class operation. It is only editable when an operation is selected in the Attribute/Operations list.

Editing this field will change the definition of the selected operation in all relevant class and object symbols using the current class name in the current scope when the OK button is clicked.

The Type Field

The type field is an editable text field that is only editable when an attribute or an operation is selected in the Attribute/Operations list.

Depending on the current selection, the type field contains:

  • If an attribute is selected, the type of that attribute, if any.
  • If an operation is selected, the return type of that operation.

By editing this field, the type of the selected attribute or the return type of the selected operation and later clicking the OK button, the type of the selected attribute or operation will be updated in all relevant class and object symbols using the current class name in the current scope.

Note that default values for attributes cannot be inspected or changed in the Browse & Edit Class dialog.

The OK Button

The OK button will close the Browse & Edit Class dialog and update all appropriate class and object symbols in the diagrams in the current scope as described for the scope label.

Note that no changes are made in the diagrams until the OK button is clicked. This makes it possible to specify several changes in the dialog and later disregard them by clicking the Cancel button.

The values are syntactically checked, so it is not possible to add syntax errors to your classes by using the Browse & Edit Class dialog. Also, it may be impossible to delete syntactically incorrect text from symbols using the Browse & Edit Class dialog, since the Browse & Edit Class dialog relies on information obtained by parsing the relevant symbol text compartments.

It is possible to undo the changes made by the Browse & Edit Class operation. Note that this undo operation may affect more than one diagram.

The Cancel Button

The Cancel button will close the Browse & Edit Class dialog and discard any changes specified in the dialog. However, if the selection has changed in the drawing area after using any of the browsing functionality, this selection will not be canceled.

All changes made in the Browse & Edit Class dialog will be lost.

Line Details Window

The Line Details window is opened when you select Line Details from the Edit menu. It is used to inspect, and edit the properties of the currently selected line. In particular, most of the line attribute objects that are available for the different line types can only be created from the Line Details window1.

Some line attribute objects contain editable text, and clearing that text, whether by editing in the Line Details window or directly in the diagram, will remove the attribute.

Changes made in the Line Details window will take immediate effect and will be shown in the drawing area. These changes can be undone with the Undo menu command.

Unlike the Browse & Edit Class dialog, the Line Details window is modeless and can remain open while you continue to work with the diagrams. The contents of the window will be updated to reflect the current selection. If there is none or more than one selected line, the fields in the Line Details window will be dimmed.

The OM Editor supports four different types of lines and the contents of the Line Details window depends on the type of the currently selected line:

  • If an Association line is selected, all items except the Composite button in the Line Details window will be active. See Figure 300.
  • If an Aggregation line is selected, all items in the Line Details window will be active. See Figure 301.
  • If a Generalization line is selected, only a single editable text field, containing the generalization's discriminator, will be available. See Figure 302.
  • If a Link Class line is selected, all items in the Line Details window will be dimmed.
  • If none or more than one line is selected, all items in the Line Details window will be dimmed.

Figure 300 : The Line Details window when an association line is selected

Figure 301 : The Line Details window when an aggregation line is selected

Figure 302 : The Line Details window when a generalization line is selected

The Name Field

The Name field is an editable text field that contains the name of the selected aggregation or association.

Unlike the other text fields in the Line Details window, the line attribute object defined by the name field is permanent and is not destroyed even if the name field is cleared.

This field is only available when an aggregation or association line is selected.

The Discriminator Field

The Discriminator field is an editable text field that changes the discriminator text attribute of the generalization.

This field is only available when a generalization line is selected.

The Reversed Name Field

The Reversed Name field is an editable text field that allows the specification of a reversed name for an aggregation or association.

This field is only available when an aggregation or association line is selected.

The Arrow Buttons

Each of these two buttons toggle an option that shows or hides the optional arrow defining the direction of the name attribute or the reversed name attribute, respectively.

The direction and position of the arrow will be automatically calculated from the position and size of the associated name attribute as well as the direction of the line.

Typically it is desirable to use arrows to enhance clarity when defining both name and reversed name fields.

These buttons are only available when an aggregation or association line is selected.

The Role Name Fields

The Role Name fields are editable text fields that allow you to create and edit the role attributes belonging to each end of the association or aggregation.

These fields are only available when an aggregation or association line is selected.

The Role Multiplicity Fields

The Role Multiplicity fields are editable text fields that allow you to create and edit the multiplicity attributes of each end of an association or aggregation.

The name field is only available when an aggregation or association line is selected.

The Ordered Buttons

Selecting the Ordered toggle creates an uneditable text attribute containing the text "{ordered}". Deselecting the Ordered toggle removes this text attribute.

The ordered text attribute can be specified both in the primary and the reverse direction.

These buttons are only available when an aggregation or association line is selected.

The Sorted Buttons

Selecting the Sorted toggle creates an uneditable text attribute containing the text "{sorted}". Deselecting the Sorted toggle removes this text attribute.

The sorted text attribute can be specified both in the primary and the reverse direction.

These buttons are only available when an aggregation or association line is selected.

The Qualifiers Fields

The Qualifiers fields are editable text fields that allow you to create and edit the qualifier fields in the forward and reverse direction respectively.

These fields are only available when an aggregation or association line is selected.

The Derived Button

The Derived button is a toggle option that indicates whether the selected association or aggregation should be marked as derived, i.e. crossed by a small slanting line.

This button is only available when an association line is selected.

The Composite Button

The Composite button is a toggle option that indicates whether the selected aggregation should be marked as composite, i.e. the diamond shape of the aggregation line should be filled.

This button is only available when an aggregation line is selected.

The Constraint Field

The Constraint field is an editable text field that allows you to create and edit the constraint line attribute object.

This field is only available when an association or aggregation line is selected.

The Close Button

The Close button closes the Line Details window.

Symbol Details Window

The Symbol Details window is opened when you select Symbol Details from the Edit menu. It is used to inspect, and edit the stereotype and properties fields of the currently selected class or object symbol. These two symbol attribute types can only be created from the Symbol Details window. However, when created they can be edited directly in the diagram.

Figure 303 : The Symbol Details dialog

Changes made in the Symbol Details window will take immediate effect and will be shown in the drawing area. These changes can be undone with the Undo menu command.

Unlike the Browse & Edit Class dialog, the Symbol Details window is modeless and can remain open while you continue to work with the diagrams. The contents of the window will be updated to reflect the current selection. If multiple class or object symbols or any other symbol or line is selected the Symbol Details window will be dimmed.

The placement of the stereotype and properties texts in the class and object symbol is described in "Class Symbols" .

1

Once created, however, all editable textual line attribute objects can be selected and edited directly in the diagram, without the use of the Line Details window.


SC Editor Specific Information

Converting State Charts to SDL

To convert state charts to SDL, you select Convert SC to SDL from the Tools Menu.

Following are the transformation rules that are applied to the SC diagram:

Transformation Rules for Diagrams and Symbols

SC
SDL
SC diagram
Process diagram
"Heading"
Process "Heading"
Text symbol
Text symbol
Start symbol

Note:
This rule does not apply if the start symbol belongs to a hierarchical state.
Start symbol
If an event is defined on the transition from this state
or
if more than one transition from this state:
Start symbol connected to `initial' state symbol named SDLInit.
Termination symbol

Note:
  1. This rule does not apply if the termination symbol belongs to a hierarchical state.
  2. If more than one transition to the termination symbol, the stop symbol is duplicated.
Stop symbol
State symbol
State symbol
Hierarchical state symbol
Nothing
Substate symbol
State symbol with a comment symbol

Transformation Rules for State Internal Activities

SC | SDL
For all transitions from A to B | Add action symbol * See "Transformation Rules for Actions"
For all transitions from A to B | Add action symbol * See "Transformation Rules for Actions"
 | Comment symbol
 | * See "Transformation Rules for Transitions"

Transformation Rules for Transitions

If actions are specified in the transition labels, insert actions last in the generated transition.

SC | SDL
 | Spontaneous transition
 | Continuous signal Note: Priority is required if more than one continuous signal exist from the same state. This must be manually added.
 | Enabling condition
 | Timer with the name "<A>_T<counter>", where <counter> is an integer. For all transitions to <A> add: For this transition from <A>: For all other transitions from <A> add:
 | As above, but add an enabling condition:
 | Continuous signal Note: Priority is required if more than one continuous signal exist from the same state. This must be manually added.
 | Continuous signal Note: Priority is required if more than one continuous signal exist from the same state. This must be manually added.

Transformation Rules for State Internal Activities on Hierarchical States

  • An Entry action of a hierarchical state is always performed when one of its substates is entered from the outside. This is applied for any number of state boundaries crossed.
  • An Exit action of a hierarchical state is always performed when one of its substates takes a transition to a state outside the substate region. This is applied for any number of state boundaries crossed.
  • An Event action of a hierarchical state is applied to all of its substates, at any nesting depth, unless a transition with the same event exists on the substate.
  • A Do action of a hierarchical state is applied to all of its substates, at any nesting depth.

Transformation Rules for Transitions on Hierarchical States

SC
SDL

Note:
Exactly one start state, with an unlabeled transition, should exist in the hierarchical state.

* See "Transformation Rules for Transitions"

Note:
An unlabeled transition should exist out from the hierarchical state.

* See "Transformation Rules for Transitions"

Note:
  1. This rule applies for every substate at any nesting depth.
  2. Exception: This rule does not apply if a transition with the same trigger (event[guard]) exists on the substate.

* See "Transformation Rules for Transitions"

Transformation Rules for Actions

Depending of text contents:

SC | SDL
If text starts with `call': call proc(params) | Procedure call
If text starts with `output': output sig | Output
If quoted text: "action" | Informal task
Otherwise: a := 1 | Task


DP Editor Specific Information

Line Details Window

The Line Details window is opened when you select Line Details from the Edit menu. It is used to inspect, and edit the properties of the currently selected line. In particular, most of the line attribute objects that are available for the different line types can only be created from the Line Details window1.

Some line attribute objects contain editable text, and clearing that text, whether by editing in the Line Details window or directly in the diagram, will remove the attribute.

Changes made in the Line Details window will take immediate effect and will be shown in the drawing area. These changes can be undone with the Undo menu command.

The Line Details window is modeless and can remain open while you continue to work with the diagrams. The contents of the window will be updated to reflect the current selection.

The DP Editor supports two different types of lines and the contents of the Line Details window depends on the type of the currently selected line:

  • If an Association line is selected, the text fields for the name, protocol and encoding as well as the direction option menu in the Line Details window will be active. See Figure 304.
  • If an Composite Aggregation line is selected, only the multiplicity text field in the Line Details window will be active. See Figure 305.
  • If none or more than one line is selected, all items in the Line Details window will be dimmed.

Figure 304 : The Line Details window when an association line is selected

Figure 305 : The Line Details window when an aggregation line is selected

The Name Field

The Name field is an editable text field that contains the name of the selected association.

This field is only available when an association line is selected.

The Direction Option Menu

By selecting one of the predefined values in the direction option menu the direction attribute of the currently selected association can be set. If any other value than None is selected an arrow will appear at one of the ends of the association line.

This option menu is only available when an association line is selected.

The Protocol Field

The Protocol field is an editable text field that allows you to create and edit the protocol attribute of an association.

The protocol field is only available when an association line is selected.

For an association line the line attribute object defined by the protocol field is permanent and is not destroyed even if the protocol field is cleared. In this respect it differs from most of the other text fields in the Line Details window.

The Encoding Field

The Encoding field is an editable text field that allows you to create and edit the encoding attribute of an association.

The encoding field is only available when an association line is selected.

The Multiplicity Field

The Multiplicity field is an editable text field that allows you to create and edit the multiplicity attribute of an aggregation.

The multiplicity field is only available when an aggregation line is selected.

For an aggregation line the line attribute object defined by the multiplicity field is permanent and is not destroyed even if the multiplicity field is cleared. In this respect it differs from most of the other text fields in the Line Details window.

The Composite aggregate Button

The Composite aggregate button is a toggle option that indicates that the selected aggregation is a composite aggregation, i.e. the diamond shape of the aggregation line is filled.

This button is set automatically depending on the current selection and is therefore never available.

The Close Button

The Close button closes the Line Details window.

Symbol Details Window

The Symbol Details window is opened when you select Symbol Details from the Edit menu. It is used to inspect, and edit the stereotype and properties fields of the currently selected node, component, thread or object symbol. For the component symbol the integration model can be selected. For the thread symbol you can edit thread priority, stack size, queue size and max signal size. For the object symbol you can enter a qualifier. These symbol attribute types can only be created from the Symbol Details window. However, when created the stereotype and properties texts can be edited directly in the diagram. All other settings can only be inspected and edited in the Symbol Details window.

Figure 306 : The Symbol Details dialog

Changes made in the Symbol Details window will take immediate effect and will be shown in the drawing area. These changes can be undone with the Undo menu command.

The Symbol Details window is modeless and can remain open while you continue to work with the diagrams. The contents of the window will be updated to reflect the current selection. If multiple symbols or a line is selected the Symbol Details window will be dimmed.

Generating a Partitioning Diagram Model

The Partitioning Diagram Model is used by the Targeting Expert as an hierarchical overview of the entities that are to be built. Partitioning Diagram Models can be generated from Deployment Diagrams. More information about this can be found in The Deployment Editor. That chapter contains guidelines for modeling Deployment Diagrams that can be used for targeting, as well as information on the available integration models.

You generate Partitioning Diagram Models from the Organizer by selecting a Deployment diagram and then selecting "Targeting Expert" in the pop-up menu. You can also select "Targeting Expert" from the Generate menu. If the generation is successful the Targeting Expert is launched with the Partitioning Diagram Model as input.

Mapping Rules

Associations are ignored in Partitioning Diagram Model generation.

The stereotype "external" on a component or node symbol means that the symbol and its sub-tree are not included when the Partitioning Diagram Model is generated. This makes it possible to model the environment that surrounds an SDL system in a deployment diagram.

Graphical Syntax Rules

In order to generate a valid Partitioning Diagram Model that can be used by the Targeting Expert the rules listed below have to be followed:

  • A valid diagram contains at least one node, one component and one object, which are connected.
  • at least one component must belong to each node
  • at least one thread or one object must belong to each component
  • at least one object must belong to each thread
  • every symbol must have a name
  • names of nodes must be unique within the diagram
  • names of components must be unique within their node
  • names of threads must be unique within their component
  • each thread must be connected to exactly one component
  • each object must be connect to one component or one thread

Object symbols

For object symbols several text attributes have to be correct in order to result in valid Partitioning Diagram Models.

The name of each object symbol in the diagram should be the name of the corresponding SDL entity. Whether it is a system, block or process should be specified by the stereotype and the qualifier text should describe how the SDL entity fits into the tree structure of the SDL system.

Figure 307 : The tree structure of the system Demongame

Figure 307 shows the system Demongame. An object representing the process Main in a deployment diagram should have the following text attributes:

  • qualifier: Demongame/GameBlock/Main
  • stereotype: process
  • name: Main

In the same way an object representing the system Demongame should have Demongame as qualifier text, the stereotype system and the name Demongame.

1

Once created, however, all editable textual line attribute objects can be selected and edited directly in the diagram, without the use of the Line Details window.


MSC Editor Specific Information

Pasting in MSC Diagrams

To paste, you select Paste from the Edit Menu. The rules for Paste will be described below.

When pasting the selection, the MSC Editor will process each individual object contained in the selection, adjust it to the grids if required and connect it, if feasible, to the "closest" object(s) in the drawing area.

If the MSC Editor fails in pasting some of the objects contained in the selection, the rest of the objects will nevertheless be pasted but without an error message being displayed.

Pasting of Multiple Objects

When pasting a selection that consists of multiple objects, the MSC Editor attempts, as long as feasible, to preserve the original appearance of the selection.

Pasting of Individual Objects

When pasting individual objects, the MSC Editor processes the objects as follows:

  • Text
    A text symbol may be pasted anywhere.
  • Comment
    A comment symbol may be pasted anywhere. The line connecting the comment symbol to another symbol is however lost when pasting.
  • Instance head / Instance axis
    The instance head and its axis may be pasted anywhere.
  • Instance end and Stop
    An instance end or stop may only be pasted at a location where it overlaps an instance axis.
  • Message
    A message is connected to the instance axes which are closest to the message's base and end point, preserving the direction and "height" of the message.
  • Message-to-self
    A message-to-self is connected to the closest instance axis. The "height" of the message is preserved.
  • Condition and MSC Reference
    A condition or an MSC reference is connected to the instance it was previously connected to (before copying it to the clipboard).
  • Timer
    A timer is connected to the closest instance axis. The "height" of the timer is preserved (see Message above).
  • Action
    An action is pasted on the closest instance axis.
  • Create
    The create symbol may be pasted anywhere, but only together with the instance it is creating.
  • Coregion
    A coregion is connected to the closest instance axis, to the left or right. The "height" of the coregion is preserved (see Message above).

Adding Symbols

Adding an Instance Head Symbol

When you add an instance head symbol, an instance axis line is drawn that connects the symbol to the bottom of the drawing area. The instance axis line cannot be drawn manually. It will be truncated or elongated when you add or move an instance end or stop symbol upwards or downwards. See "Adding an Instance End Symbol" and "Adding a Stop Symbol" .

The instance head symbol has three text fields:

    • The instance name field
    • The instance kind field
    • The decomposition field. See Figure 308.

Figure 308 : The meaning of the instance head text fields

The ITU recommendation Z.120 discusses several ways of using the instance name and instance kind text fields. In the MSC Editor, the text fields are used as follows:
  • Basically, the instance kind reflects what kind of instance is represented. That is, an identifier which reflects the name of the corresponding SDL block/service/process/procedure; and an optional identifier which identifies if it is a block, a service or a process (the kind denominator).
  • The instance name reflects the current function of the instance.
  • The instance decomposition shows if the instance is in turn decomposed as a sub MSC. This text field is by default empty, but can contain the text decomposed or decomposed as <diagram name> to indicate that the instance is in turn decomposed. To decompose an instance, you select Decompose from the Edit menu.

Adding a Condition, MSC Reference or Inline Expression Symbol

A condition or MSC reference describes either a global system state referring to all instances contained in the MSC or a state referring to a subset of instances (a non-global condition or MSC reference). The minimum subset is a single instance.

For two MSCs, the second is a continuation of the first if its initial global condition is identical to the final global condition of the first. Identifying an intermediate global condition can be used when breaking down an MSC into two parts.

By means of non-global conditions, combinations of MSCs with different sets of instances can also be defined. The continuation then refers only to the common subset of instances.

The following general rule applies to the continuation of two MSCs (MSC1 and MSC2, with a non-empty common set of instances).

MSC2 is a continuation of MSC1 if, for each instance which both MSCs have in common:

  • MSC1 ends with a (non)global condition
  • MSC2 begins with a corresponding1 (non)global condition
  • Each (non)global condition of MSC2 has a corresponding (non)global condition in MSC1.

An inline expression symbol is always global and connected to all instances. The inline expression symbol is created from two inline expression symbol parts:

  • The inline expression symbol starts a new inline expression symbol. The inline expression text in this symbol determines the inline expression type:
    • The keyword loop identifies a loop. Example: "LOOP <1, 5>" means that the contents of the inline expression symbol will be executed between one and five times.
    • The keyword opt identifies an optional part. The contents of the inline expression symbol will either not be executed or executed once.
    • The keyword exc identifies an exceptional part. The contents of the inline expression symbol will either not be executed or executed once. If it is executed, then the rest of the MSC is skipped.
    • The keyword par identifies parts that are executed in parallel.
    • The keyword alt identifies alternative parts. Only one part will be executed.
  • The inline expression separator symbol starts a new part in a parallel or alternative inline expression.

Displaying and Modifying Status

To display and modify status, you select Status from the Edit menu.

Timer Status

Z.120 specifies two appearances for the timer symbol, depending on whether the timer has expired (i.e. timeout) or whether the timer is reset. The appearance of the timer is illustrated in Figure 309.

  • Timeout - A timer expires.
  • Reset - The timer is stopped.
  • Implicit reset - Assigned a new value while active.

Figure 309 : Timer status

Separate Timer Status

Separate timer symbols has no need for an implicit reset. The timer can be set two times in a row without an implicit reset in-between.

Figure 310 : Separate Timer status

Displaying Information About the Selected MSC Object

To display information about a selected MSC object, you select Info Window from the Window menu.

This opens a dialog displaying additional information about the currently selected MSC object. The information that is available depends on what object is selected, and this is described in the table below.

Selected Object
Information Available
Instance head
  • Instance name
  • Instance kind
  • Composition
  • Creating instance
Instance end
  • Instance kind
Stop
  • Instance kind
Process create
  • Creating instance
  • Created instance
  • When the instance was created1
  • SDL Referencea
Message output
(the message output is selected by clicking close to the message base)
  • Message name
  • Sending instance
  • Receiving instance
  • Message status =
    • Sent2
    • Consumed3
  • When the message was sent (now)a
  • Message parameters
  • SDL Referencea
Message input
(the message input is selected by clicking close to the message end)
  • Message name
  • Sending instance
  • Receiving instance
  • Message status=
    • Sentb
    • Consumedc
  • When the message was consumed
  • Message parameters
  • SDL Referencea
Timer
  • Timer name
  • Instance kind
  • Timer status=
    • Reset (stopped)
    • Implicit reset
    • Timeout
  • When the message was sent (now)a
  • Timer value (Set)
  • Timer parameters
  • SDL Referencea
Separate timer
  • Timer name
  • Instance kind
  • Timer status=
    • Set
    • Reset (stopped)
    • Timeout
  • When the message was consumed (now)a
  • Timer parameters
  • SDL Referencea
Action symbol
  • Instance kind
  • Action text
  • SDL Referencea
Condition
  • Condition or MSC reference name
  • Instances connected to the condition
  • SDL Referencea
MSC Reference symbol
  • Condition or MSC reference name
  • Instances connected to the condition
Text symbol
  • Symbol text
Comment symbol
  • Symbol text
Inline symbol
  • Instances connected
  • Operator (inline expression)
1

Only for diagrams created through a simulation.

2

A message is sent when it has been sent and received, but has not yet been consumed by the receiving instance. Typically, it is waiting in the receiving process input queue.

3

A message is consumed when it has been processed by the receiving instance.

Instance Ruler

When managing working on a long (vertically extended) MSC, the kind of instance in the instance head may not be visible in the drawing area.

The instance ruler (illustrated in Figure 311) shows the kind of the instance heads that are not currently visible in the drawing area. It reduces the amount of scrolling up or down when working on an MSC. The instance ruler may be shown or hidden with an option (see "Instance Ruler" ).

Figure 311 : The instance ruler

Tracing a Simulation in a Message Sequence Chart

This section describes the functionality behind tracing a simulation in an MSC.

General

The MSC Editor may be used as a graphical trace tool, which features the automatic generation of an MSC from a simulation.

  • The results of the simulation may be presented on line in an MSC Editor window, in which each event of interest will be appended to the chart in order to build up an MSC which reflects the history of the simulation.
  • It is also possible to run the simulation, save the results on a simulator MSC log file and open the file from the MSC Editor.
  • The commands that start up the logging of MSC events, set up the scope of trace, stop the logging of events, and so on, are given to the simulator monitor. See 50 Simulating a System.

Defining the Scope of Trace

First, the scope of trace should, if necessary, be set to the unit which is currently of interest. This is done with the command Set-MSC-Trace.

The graphical trace is then started with a dedicated command from the simulator monitor. See "Start-Interactive-MSC-Log" . In response to this command, the following happens:

  1. In the Organizer, a reference to an MSC is added. The diagram is assigned an unique name.
  2. An instance of the MSC Editor window is activated on the newly created MSC.
  3. The current status for the simulation is presented by displaying all SDL process instances that exist at the time when ordering the command Start-Interactive-MSC-Log.

Mapping Between SDL and MSC

The mapping rules which govern how SDL events are transformed into MSC symbols, lines and textual elements are summarized in the following table:

SDL concept
MSC Concept
Signal
  • Output
  • Input
Message
  • Sending
  • Consumption
Signal to self
  • Output
  • Input
Message to self
  • Sending
  • Consumption
Timer
  • Set
  • Reset
  • Implicit Reset
  • Input
Timer
  • Set
  • Reset
  • Implicit reset1
  • Time-out
Create a process
Process Create
Stop a process
Stop
Environment
Environment2
System
<system name>
Instance
<instance kind>
Substructure
<system name>
Instance
<instance kind>
Block
<block name>
Instance
<instance kind>
Process
<process name>
<instance number>
Instance
<instance kind>
<instance name>
State
Condition3
Task
Action4
Comment
Comment
1

See "Implicit reset" .

2

The system's environment is denoted by env_1

3

The mapping is only completely valid for a condition connected to only one instance. A condition connected to several instances expresses a logical AND-combination of the states of the processes corresponding to those instances.

4

The action symbol corresponds to a task symbol containing informal text. This translation is, however, not supported when generating an MSC from a simulation.

Generating the MSC

When running the simulation, each SDL event of interest (in the scope of MSC Trace) that takes place will cause the corresponding MSC symbol to be drawn in the drawing area of the MSC Editor.

Drawing Conventions

Layout

Default layouting algorithms are used. Each event causes the insertion point to be translated downwards with one vertical spacing unit, keeping the intuitive feeling of absolute order between events. An event could be, for instance, the output or the input of an SDL signal. However, if an output event is immediately followed by an input event, no translation will take place.

Auto-Resizing of MSC

The MSC Editor will automatically enlarge the MSC size when the MSC has grown so that it reaches the bottom or right of the drawing area. The MSC is enlarged according to a preference parameter.

Messages

A distinction is made between the reception and the consumption of messages:

  • Reception of a message: Once an SDL signal is output in the simulator, it is immediately placed into the input port of the receiving process instance. There may, however, be other pending SDL signals in this queue, which means that the signal might not be input immediately. Therefore, when a signal is output, it is illustrated as a lost message, marked at its end with the name of the receiving instance, from the sending instance to the receiving instance.
  • Consumption of a message: When an SDL signal is input, the vertical position for the next event may have moved down in comparison to the position of the signal output. An input of a signal is illustrated by redrawing the line representing the message with its end point connected to the new vertical position. (If an output event is immediately followed by an input, there is no change in vertical position.)
  • In the case messages remain lost for a "long" time, this may be interpreted as some kind of erroneous behavior which requires special attention. Messages that are never consumed indicate that some design error might have been introduced in the SDL system. It is up to you to decide whether the time which has elapsed since a message was sent should be considered as exceeding a reasonable value.

Create of Process

Each time an SDL process is dynamically created, a process create will be drawn from the source instance axis, and the created instance will be positioned according to the insert and grouping modes that is set. This guarantees that no overlapping instance axes will take place.

The MSC Editor will automatically enlarge the MSC size when the MSC has grown so that it reaches the bottom or right of the drawing area. The drawing area is enlarged according to the value of a preference parameter.

Process Stop

If an instance is stopped (by a stop symbol), the space which becomes available beneath the instance end symbol will not be reused for new instance axes.

Timers

  • The MSC Editor can handle four different timer statuses resulting from a simulation:
    • Set
    • Reset (stopped)
    • Implicit reset
    • Timeout
      On the MSC they are shown according the figure below:

Figure 312 : Timer status as shown on the MSC

    • Implicit reset
      The implicit reset timer status is a non-Z.120 addition to the MSC Editor. An implicitly reset timer is immediately set again to its original parameters after reset. It is illustrated in the same way as a reset timer, but the status information is reflected in the Info dialog (see "Requesting Detailed Information on an Object" ).

Instances

  • The Environment Instance
    All interchange of information between the SDL system and its environment is displayed by sending / receiving messages to or from an instance with the name env_1. This instance is normally placed at the left of the drawing area.
  • The Void Instance
    Graphically, in the Message Chart Editor, the concept conditional trace (see "Scope of Trace for Generation of Message Sequence Charts" ) is illustrated as sending or receiving messages to / from an instance with the name Void. The purpose of the Void instance is to document that a message exchange actually took place without focusing on the sending / receiving instance.
  • The Instance Name and Instance Kind Text Fields
    The ITU recommendation Z.120 allows several ways of using the two text fields Instance Name and Instance Kind. This was discussed earlier in "Adding an Instance Head Symbol" .
    When generating an MSC, the SDL Process Name and the internal instance number managed by the simulator monitor are concatenated to build up one (MSC) Instance Name. The SDL diagram type and diagram name are concatenated to build one Instance Kind.

Example 297 Instance Name and Instance Kind in Simulation Trace

Assume the simulation program contains an instance of the SDL diagram type = process with the diagram name = Demon and monitor instance number = 2 This would be displayed as the following instance:

Figure 313 : The use of the instance text fields in a simulation

Terminating the Trace

Having terminated the trace (either by stopping the simulation or turning the MSC trace off), you are responsible for saving the MSC(s) that are the results of the simulation.

1

Corresponding in this context means that both conditions refer to the same subset of instances and both conditions agree with respect to name.


Syntax Summary

Object Model Syntax

While the intent of Object Model diagrams is to give as large flexibility as possible to analysis and specification activities, the different editing support facilities provided by the OM Editor requires textual data to follow certain syntactic conventions.

This section details the syntax rules that are imposed by the OM Editor on textual data only. Graphical syntax rules are enforced automatically by the OM Editor and are not described here.

Summary of Lexical Rules

In general, a somewhat restricted version of the lexical rules of SDL apply for names. These rules have the following noteworthy properties:

  • It is possible to break a name over more than one line by using the underscore at the end of the line to escape the newline.
  • It is possible to have identifiers consisting entirely of numeric characters; e.g. "223" is a valid identifier.
  • Identifiers are not case sensitive.
  • Comments can be used anywhere in the texts. A comment is defined as an SDL comment, i.e. /* this is a comment */

For more information on the SDL lexical rules, see the Z.100 recommendation.

The primary restriction is that identifiers containing spaces are not considered legal.

<name> ::= identifier as described above.
<c-string> ::= string as bounded by " characters.
<sdl-string> ::= string delimited by ` (apostrophes).

Class Definition Summary

When interpreting OM diagrams, all class and object symbols within all pages within all diagrams in a single module must be considered. A class definition is considered to be the conceptual union of the information contained in all class symbols with the same name, as well as all object symbols declared as instances of that class.

This means that the definition of a class can be distributed over several symbols, pages and even diagrams. The definitions in class symbols with the same name are then merged to obtain the complete definition of the class; support for this is provided by the Browse & Edit Class dialog.

Thus, when defining classes, it is acceptable to have identical attributes or operations defined several times, either in the same or different class or object symbols. The identical definitions are simply redundant, and do not affect the correctness of the complete class definition.

Note, however, that each unnamed class objects is considered distinct, so that each unnamed class symbol defines its own class.

Diagram Name Syntax

Diagram names must follow certain restrictions since they are used to identify the diagram with respect to other tools.

Diagramname ::= <name>

Page Name Syntax

Pagename ::= <name>

Each page name must be unique within its containing diagram.

Class Symbol Syntax

The textual information in class symbols is divided into five compartments of which three have their own syntax. The stereotype and properties compartments are not checked for syntax.

In the attributes and operation compartments the stereotype concept as described in "Object Model Literature References" can be used. The syntax chosen supports the single characters left/right guillemot («») but it can also be written as two angle brackets. To type the left/right guillemot in the text window, press <Ctrl> when you type the left/right angle bracket.

Class Name Compartment Syntax

Classname ::= <name> |
<name> `:' `:' <name> |
<empty>

Class Attributes Compartment Syntax

ClassAttributesCompartment ::=
{ <stereotype> <classattribute> <note> }*
<stereotype> ::= `<' `<' <name> `>' `>' |
`«' <name> `»' |
<empty>
<classattribute> ::=
<visibility> <attribute>
<visibility> ::=
`+' |
`-' |
`#' |
<empty>
<attribute> ::=
<name> <value> |
<name> `:' <type> <value>
<type> ::= <name>
<value> ::= `=' <valueitem> | <empty>

<valueitem> ::=
<name> |
`-' <name> |
`+' <name> |
<c-string> |
<sdl-string> |
`(` <valueitemlist> `)' |
`{` <valueitemlist> `}'
<valueitemlist> ::=
<valueitem> |
<valueitemlist> `,' <valueitem>
<note> ::=
`{` <name> `}' |
`{` <name> `=' <name> `}' |
<empty>

Two attributes are considered identical if they have the same name and type. Note that attributes defining different values are still considered identical.

Class Operations Compartment Syntax

ClassOperationsCompartment ::=
{ <stereotype> <classoperation> <note> }*
<classoperation> ::=
<visibility> <operation>
<operation> ::=
<name> <return> |
<name> `(` `)' <return> |
<name> `(` <parameterlist> `)' <return>
<parameterlist> ::=
parameter |
parameterlist `,' parameter
<parameter> ::=
<type> |
<name> `:' <type>
<return> ::=
`:' <name> |
<empty>

Two operations are considered identical only if the name, parameter list and the return fields are all the same. Thus "op", "op(a)" and "op:t" are all unequal, while "op(a)", "OP(A)" define the same operation.

Note however that "op" and "op()" are not considered equal, since the OM Editor does not interpret an omitted parameter list as an empty parameter list.

Object Symbol Syntax

The textual information in object symbols is divided into four compartments of which two have their own syntax. The stereotype and properties compartments are not checked for syntax.

Object Name Compartment Syntax

Objectname ::=
<name> `:' <classname> |
<name> |
<empty>

Object Attributes Compartment Syntax

ObjectAttributesCompartment ::=
{ <stereotype> <attribute> <note> }*

Text Symbol Syntax

Text symbols are not subject to any syntax rules.

Line Syntax

The current version of the OM Editor does not implement any syntax checks on the contents of the textual attribute objects of lines.

State Chart Syntax

While the intent of State Chart diagrams is to give as large flexibility as possible to analysis and specification activities, the different editing support facilities provided by the SC Editor requires textual data to follow certain syntactic conventions.

This section details the syntax rules that are imposed by the SC Editor on textual data only. Graphical syntax rules are enforced automatically by the SC Editor and are not described here.

Summary of Lexical Rules

In general, a somewhat restricted version of the lexical rules of SDL apply for names. These rules have the following noteworthy properties:

  • It is possible to break a name over more than one line by using the underscore at the end of the line to escape the new line.
  • It is possible to have identifiers consisting entirely of numeric characters; e.g. "223" is a valid identifier.
  • Identifiers are not case sensitive.
  • Comments can be used anywhere in the texts. A comment is defined as an SDL comment, i.e. /* this is a comment */

For more information on the SDL lexical rules, see the Z.100 recommendation.

The primary restriction is that identifiers containing spaces are not considered legal.

<name> ::= identifier as described above.

State Definition Summary

UML allows some expressions in text segments to be defined by the tool vendors. For State Charts such expressions should follow SDL/PR syntax, but this is not checked by the SC Editor.

When interpreting SC diagrams, all state symbols within all pages within all diagrams in a single module must be considered. A state definition is considered to be the conceptual union of the information contained in all state symbols with the same name.

This means that the definition of a state can be distributed over several symbols, pages and even diagrams. The definitions in state symbols with the same name are then merged to obtain the complete definition of the state.

Thus, when defining states, it is acceptable to have identical activities defined several times, either in the same or different state symbols. The identical definitions are simply redundant, and do not affect the correctness of the complete state definition.

Note, however, that each unnamed state object is considered distinct, so that each unnamed state symbol defines its own state.

Diagram Name Syntax

The diagram name identifies the diagram.

<DiagramName> ::= <name>

Page Name Syntax

The page name identifies the page within a diagram.

<PageName> ::= <name>

Each page name must be unique within its containing diagram.

State Symbol Syntax

The textual information in state symbols' state sections is divided into three compartments with different syntax.

Name Compartment Syntax

The name identifies the state.

<NameCompartment> ::=
[<name>]

Internal Activity Compartment Syntax

Internal activities' syntax is defined by the following grammar:

<InternalActivityCompartment> ::=
{<internal-activity>}*

<internal-activity> ::=
<event-signature>
[<guard-condition>]
[`/' <action-expr>]
|
<reserved-action-label> `/' <action-expr>

<reserved-action-label> ::=
`entry' | `exit' | `do'

<event-signature> ::=
<name> [<argument-list>] |
<predefined-event> `(' <argument> `)'

<predefined-event> ::=
`when' | `after'

<argument-list> ::=
`(' [<argument> {`,' <argument>}*] `)'

<argument> ::=
<expression>

<guard-condition> ::=
`[` <expression> `]'

<action-expr> ::=
<expression>

<expression> ::=
SDL/PR expression

Two events are considered identical only if the name and the argument list are all the same. Thus "op" and "op(a)" are unequal, while "op(a)", "OP(A)" define the same event.

Note however that "op" and "op()" are not considered equal, since the SC Editor does not interpret an omitted parameter list as an empty parameter list.

Text Symbol Syntax

Text symbols are not subject to any syntax rules.

Transition Line Syntax

The textual information in the transition label attribute of transition lines is defined by the following grammar:

<TransitionLabel> ::=
[<event-signature>]
[<guard-condition>]
[<action-list>]

<action-list> ::=
`/' <action-expr> {`;' <action-expr>}*

DP Syntax

While the intent of Deployment diagrams is to give as large flexibility as possible to analysis and specification activities, the different editing support facilities provided by the DP Editor require textual data to follow certain syntactic conventions.

This section details the syntax rules that are imposed by the DP Editor on textual data only. Graphical syntax rules are enforced automatically by the DP Editor and are not described here.

Summary of Lexical Rules

In general, a somewhat restricted version of the lexical rules of SDL apply for names. These rules have the following noteworthy properties:

  • It is possible to break a name over more than one line by using the underscore at the end of the line to escape the newline.
  • It is possible to have identifiers consisting entirely of numeric characters; e.g. "223" is a valid identifier.
  • Identifiers are not case sensitive.
  • Comments can be used anywhere in the texts. A comment is defined as an SDL comment, i.e. /* this is a comment */

For more information on the SDL lexical rules, see the Z.100 recommendation.

The primary restriction is that identifiers containing spaces are not considered legal.

<name> ::= identifier as described above.

Diagram Name Syntax

The diagram name identifies the diagram.

<DiagramName> ::= <name>

Node Symbol Syntax

The name identifies the node.

<NodeName> ::= <name> |
<empty>

There are no syntax checks on the stereotype and properties texts.

Component Symbol Syntax

The name identifies the component.

<ComponentName> ::= <name> |
<empty>

There are no syntax checks on the stereotype and properties texts.

Thread Symbol Syntax

The name identifies the thread.

<ThreadName> ::= <name> |
<empty>

Object Symbol Syntax

The name identifies the object.

<ObjectName> ::= <name> |
<empty>

There are no syntax checks on the stereotype, properties and qualifier texts.

Text Symbol Syntax

Text symbols are not subject to any syntax rules.

Line Syntax

The DP Editor does not implement any syntax checks on the contents of the textual attribute objects of lines.

HMSC Syntax

While the intent of High level MSC diagrams is to give as large flexibility as possible to analysis and specification activities, the different editing support facilities provided by the HMSC Editor requires textual data to follow certain syntactic conventions as specified in MSC'96.

This section details the syntax rules that are imposed by the HMSC Editor on textual data only. Graphical syntax rules1 are enforced automatically by the HMSC Editor and are not described here.

Summary of Lexical Rules

The lexical elements follow MSC'96. These rules have the following noteworthy properties:

  • An underscore followed by on or more spaces is ignored completely, e.g. A_ B denotes the same <name> as AB. This use of underline makes it possible to split keywords over multiple lines since control characters (e.g. newline) is treated as a space.
  • It is possible to have identifiers consisting entirely of numeric characters; e.g. "223" is a valid identifier.
  • Identifiers are not case sensitive.
  • Comments (<note> in Z.120) can be used anywhere between lexical units. A <note> is started by the characters /* outside a <note> and terminated by the characters */ inside a <note>.

For more information on the MSC lexical rules, see the Z.120 recommendation.

Syntax rules in Symbols

The descriptions below describes what text is allowed in the different symbols, it is not a description of the grammar in PR-form.

The grammar below informally describes the lexical units used as terminal symbols. Refer to Z.120 for a complete description.

<name> ::= identifier as described above.
<text> ::= approximately the ASCII character set.

In the sections below each symbol will be described in the following manner:

  1. A short description of the symbol and/or its contents and purpose.
  2. The symbols textual grammar
  3. Possibly any semantic restriction and/or notes. Refer to Z.120 for a complete description of the semantics that apply.

Diagram Name Syntax

The diagram name identifies the MSC to the outside world.

Diagramname ::= <name>

Diagram names must follow certain restrictions since they are used to identify the diagram with respect to other tools.

Page Name Syntax

The page name identifies the page within a document.

<page name> ::= <name>

Each page name must be unique within its containing diagram.

Text Symbol Syntax

The text in a text symbol is an informal explanatory text.

<text text> ::= <text>

The text has no (formal) semantic and no restrictions.

Condition Symbol Syntax

Global conditions can be used to restrict how MSC's can be composed in High level MSC's.

<condition name list> ::=
<condition name> { `,' <condition name> }*

<condition name> ::= name

Global conditions indicate possible continuations of Message sequence charts containing the same the same set of instances by means of condition name identification.

Reference Symbol Syntax

MSC References are used to refer to other MSC's of the MSC document.

<msc ref expr> ::=
<msc ref par expr> { `alt' <msc ref par expr> }*

<msc ref par expr> ::=
<msc ref seq expr> { `par' <msc ref seq expr> }*

<msc ref seq expr> ::=
<msc ref exc expr> { `seq' <msc ref exc expr> }*

<msc ref exc expr> ::=
[ `exc' ] <msc ref opt expr>

<msc ref opt expr> ::=
[ `opt' ] <msc ref loop expr>

<msc ref loop expr> ::=
[ `loop' [ <loop boundary> ] ]
{
`empty' |
<msc name> [ <parameter substitution> ] |
( <msc ref expr> )
}

<parameter substitution> ::=
`subst' <substitution list> `end'

<substitution list> ::=
<substitution> [ `;' <substitution list> ]

<substitution> ::=
<replace message> |
<replace instance> |
<replace msc>

<replace message> ::=
[ `msg' ] <message name> `by' <message name>

<replace instance> ::=
[ `inst' ] <instance name> `by' <instance name>

<replace msc> ::=
[ `msc' ]
{ `empty' | <msc name> } `by'
{ `empty' | <msc name> }

<msc name> ::= <name>

<message name> ::= <name>

<instance name> ::= <name>

MSC Syntax

While MSC diagrams allows the user to specify the analysis and specification activities in great detail with graphical symbols, there are also fields that get their meaning from textual information only. The different editing support facilities provided by the MSC Editor checks textual data to follow certain syntactic conventions as specified in MSC'96.

This section details the syntax rules that are imposed by the MSC Editor on textual data only. Graphical syntax rules2 are enforced automatically by the MSC Editor and are not described here.

Summary of Lexical Rules

The lexical elements follow MSC'96. They are identical to the lexical rules for HMSC, see "Summary of Lexical Rules" for further information.

Syntax Rules in Symbols

The descriptions below describes what text is allowed in the different symbols, i.e. it is not a description of the grammar in PR-form.

The grammar below informally describes the lexical units used as terminal symbols. Refer to Z.120 for a complete description.

<name> ::= identifier as described above.
<text> ::= approximately the ASCII character set.

In the sections below each symbol will be described in the following manner:

  1. A short description of the symbol and/or its contents and purpose.
  2. The symbols textual grammar
  3. Possibly any semantic restriction and/or notes. Refer to Z.120 for a complete description of the semantics that apply.

Syntax Common with HMSC

All symbols that can take textual input in the HMSC are also present (and the same) as those found in the MSC. See "Syntax rules in Symbols" for further information.

Syntax Specific for MSC

In addition to the symbols that are common HMSC symbols, the MSC Editor supports the following symbols that contains text.

Comment Symbol Syntax

The text in a comment symbol is an informal explanatory text.

<comment text> ::= <text>

The text has no (formal) semantic and no restrictions.

Instance, Message and Timer Name syntax

The text identifies the entity

<instance name> ::= name
<message name> ::= name
<timer name> ::= name

Parameter Syntax

Both on messages and instance creations have parameters. In addition the MSC also supports parameters on timers (currently nonstandard). The Z.120 grammar for parameters is defined as follows:

<parameter list> ::=
<parameter name> [ `,' <parameter list> ]

This grammar is neither able to allow empty parameter lists, nor to take parameters that are generated from SDL. Furthermore, the grammar does not allow string literals. The MSC Editor (and associated tools) supports the following, more relaxed, grammar:

<parameter list> ::=
[ <relaxed name> { `,' <relaxed name> } * ]
<relaxed name> ::=
<parameter name> [ `(` <relaxed name> `)' }
<parameter name> ::=
<name> |
<character string> |
<character string 2>

The grammar of <character string 2> is the same as the grammar for the Z.120 <character string> except that the apostrophe is regarded as the Z.120 <other character> and the double quote `"' is regarded as an <apostrophe>.

Instance Kind Syntax

The instance kind describes the type of the instance

<instance kind>::=
[ <kind denominator> ] <identifier>
<kind denominator> ::=
`system' | `block' | `process' | `service'
| <name>
<identifier> ::= [ <qualifier> ] <name>
<qualifier> ::= `<<' <text> `>>'

Decomposition Syntax

This text is present if the instance is decomposed and describes the name of the diagram that explains the decomposed instance in greater detail.

<decomposition> ::=
`decomposed' [ <substructure reference> ]
<substructure referrence> ::=
`as' <message sequence chart name>

Inline Heading Syntax

This is the syntax for the text area in the inline expressions symbols.

<inline heading> ::=
`alt' |
`par' |
`exc' |
`opt' |
`loop' [<loop boundary>]
<loop boundary> ::=
`<' <inf natural> [ `,' <inf natural> ] `>'
<inf natural> ::= `inf' | <natural name>
<natural name> ::= {0|1|2|3|4|5|6|7|8|9}+
1

No checks are made on completeness, however.

2

No checks are made on completeness, however.


Literature References

Object Model Literature References

There is a growing number of publications devoted to object modeling techniques. The following two sources have been selected as defining the Object Model supported by the OM Editor:

  5. OMG Unified Modeling Language, version 1.3, June 1999
    (document ad/99-06-08) Final Draft
    Object Management Group
    ftp://ftp.omg.org/pub/docs/ad/
  6. Object Oriented Modeling and Design
    Rumbaugh, Blaha, Premerlani, Eddy, Lorensen
    Prentice-Hall (1991)
    ISBN 0-13-630054-5

State Chart Literature References

There is a growing number of publications devoted to state chart techniques. The following source has been selected as defining the State Chart supported by the SC Editor:

  7. Unified Modeling Language, version 1.1, Sept. 1997
    UML Semantics (document ad/97-08-04)
    UML Notation Guide (document ad/97-08-05)
    Object Management Group
    ftp://ftp.omg.org/pub/docs/ad/
  8. Unified Modeling Language, version 1.0, January 1997
    UML Semantics (document ad/97-01-03)
    UML Notation Guide (document ad/97-01-09)
    Object Management Group
    ftp://ftp.omg.org/pub/docs/ad/

MSC`96 Literature References

  9. Z.120 (1996).
    Message Sequence Chart (MSC).
    ITU-T, Geneva, April 1996
  10. Message Sequence Chart
    Syntax and Sematics
    M.A. Reniers, Eindhoven University of Technology, 1999
    IPA Dissertation Series 1999 - 7
  11. Object-Oriented Software Engineering
    - A Use Case Driven Approach.
    I. Jacobson.
    Addison-Wesley, 1992
  12. Tutorial on Message Sequence Charts (MSC'96)
    Ekkart Rudolph, Jens Grabowski, and Peter Graubman

UML Literature References

  13. The Unified Modeling Language User Guide
    Grady Booch, Ivar Jacobson, James Rumbaugh.
    Addison-Wesley, 1998
  14. The Unified Modeling Language Reference Manual
    James Rumbaugh, Ivar Jacobson, Grady Booch.
    Addison-Wesley, 1998
  15. The Unified Software Development Process
    Ivar Jacobson, James Rumbaugh, Grady Booch.
    Addison-Wesley, 1999


41 The Deployment Editor

The Deployment Editor is a tool for graphical partitioning of SDL systems, which allows you to model how SDL systems execute in their target environment. See also 64 Integration with Operating Systems.

Diagrams in the editor, deployment diagrams, use notation from UML. Information from a deployment diagram can be used when targeting one or several SDL systems. See 59 The Targeting Expert.

This chapter contains a description of the deployment diagram as well as guidelines for modeling different deployment scenarios. The connection with the Targeting Expert is also described.


Introduction

The Deployment Editor allows you to graphically deploy one or several SDL systems. SDL systems can be partitioned into components, i.e. executable files, which in turn are partitioned into threads of execution. Finally, SDL entities, i.e. objects, are mapped to the threads, showing the execution architecture at compile-time.

The information in a deployment diagram can be used by the Targeting Expert through the Partitioning Diagram Model. In the Targeting Expert, you can set build parameters on each component and build an application from this model.

Applications

You can use the Deployment Editor in two ways:

  • As an editor for graphical partitioning of SDL systems.
  • As a pure modeling tool.

The Deployment Editor gives you freedom in modeling partitioning and communication. There are few restrictions in drawing rules and no syntax checking is performed. There are, however, restrictions how to use deployment diagrams for generating partitioning data for the Targeting Expert. This chapter describes the requirements for using the Deployment Editor for partitioning. The diagram symbols are described as they are interpreted when used for partitioning.

Starting the Deployment Editor

You start the Deployment Editor the same way as the other editors in the SDL suite. There are four alternatives:

  • Select Tools -> Editors -> Deployment Editor in the Organizer to start with an empty diagram.
  • Select Edit -> Add New... in the Organizer and UML -> Deployment in the Add New dialog to add a new diagram.
  • Select Edit -> Add Existing... in the Organizer to add an existing diagram.
  • Right-click on an existing deployment diagram symbol in the Organizer and select Edit -> Edit in the pop-up menu.

The Graphical User Interface

The graphical user interface in the Deployment Editor is similar to that used in the other SDL suite editors. For a description of the user interface in general, see User Interface and Basic Operations.

Connection to the Targeting Expert

The Deployment Editor generates data that can be used by the Targeting Expert. Deployment diagrams are translated to the data format Partitioning Diagram Model (PDM), which contains build-related information. See "Generating Partitioning Diagram Data for the Targeting Expert" .

To start the Targeting Expert with PDM data for a deployment diagram:

  1. Click on the deployment diagram (.sdp file) in the Organizer
  2. Select Targeting Expert from the Generate menu.

See The Targeting Expert for information on how to build using the Targeting Expert.

Using Information from SDL System(s)

The Deployment Editor has no automatic access to information about SDL systems in the Organizer. You must enter information about SDL objects manually in a deployment diagram.

For SDL objects, the following information is mandatory to enter:

  • Name
    It is recommended that the name of the object in the Organizer is used.
  • Qualifier
    This is the path to the SDL object in the Organizer. The qualifier should include the name of the object in the Organizer.
  • Stereotype
    This shows the type of SDL object and should have one of the following values: system, block or process.

See "Object" for more information about SDL objects.

Note:

It is possible to deploy objects from many SDL systems in one deployment diagram. The only requirement is that the SDL systems must be contained within the same .sdt file. This .sdt file must be loaded in the Organizer when working with the deployment diagram.


The Deployment Diagram

In this section, the deployment diagram is described. The view and the symbols as well as drawing rules for the different integration models are explained.

Note:

Following the naming convention in the SDL suite, diagrams edited in the Deployment Editor are named deployment diagrams. This notion must not be mistaken for the UML deployment diagram. In this chapter, "deployment diagram" implicitly means the SDL suite diagram.

Note:

In the Deployment Editor, it is only possible to use one page per diagram. This differs from the OM Editor, where an arbitrary number of pages can be used. See "OM Editor Specific Information.

The View

The deployment diagram uses a view that is similar to the UML component view. The most important similarities are:

  • Both views are type-based, i.e. no instance-specific information can be modeled. This implicates that the thread and object symbols in the Deployment Editor diagram can be regarded as stereotyped UML class symbols.
  • Both views are static, i.e. partitioning at compile-time is modeled.

There are some important differences between the Deployment Editor view and the component view:

  • The Deployment Editor view uses the node symbol, which is not used in the UML component view. In UML, the node symbol is only used in the deployment view.
  • The Deployment Editor view does not support the interface notion, which is used for modeling communication between components in the UML component view.

The Deployment Editor diagram shows a static view of the partitioning, i.e. you can deploy SDL systems by how they look at compile-time.

The Symbols

The deployment diagram contains four symbols that can be used for modeling partitioning: Node, Component, Thread and Object. Each symbol is described in the following subsections. See "About Symbols and Lines.

.

Note:

The deployment diagram terminology must not be mixed up with the syntax used in buildscripts, i.e. scripts containing SDL Analyzer commands. Some terms, such as thread, are similar, while other, such as component, represent completely different things.

All symbols, except the thread symbol, contain information that can be edited in the Symbol Details dialog box. Properties and stereotype information are graphically visible on the symbols.

Node

A node symbolizes a computational resource, i.e. something with processing power and possibly some memory and other peripherals. A node should be seen as a platform on which software execute. Only components can be attached to nodes.

A typical stereotype for a node is a description of the processor and a common property is the operating system that is being used. Figure 314 shows a node called My_Computer with the stereotype PC and the property Windows NT 4.0.

Figure 314 A node with name, stereotype and properties

For a node, you can set the stereotype to external, indicating that the node does not execute any code from your SDL system(s). This makes it possible to model external non-SDL parts that communicate with your SDL system(s). Setting the stereotype to external implicates that the node is ignored when building a Partitioning Diagram Model from the deployment diagram.

.

Note:

Stereotype and property information for a node is ignored when generating partitioning diagram data. The only exception is when stereotype is set to external.

Component

A component symbolizes an executable file, i.e. a sort of container for software entities. Components contain objects, i.e. SDL systems, blocks or processes, that are organized in threads of execution. You can attach either objects or threads to a component.

Figure 315 A component symbol named "My_Comp"

As for nodes, you can set external as stereotype on a component, which means that the component does not contain any SDL object from the system(s) that are deployed.

.

Note:

Stereotype and property information for a component is ignored when generating partitioning diagram data. The only exception is when stereotype is set to external.

For a component, you can select an integration model in the Symbol Details dialog box. The integration model reflects how the code that is generated is integrated with your target operating system. Three integration models are available:

  • Light Integration. This is the default selection.
  • Tight Integration.
  • Threaded Integration.

See "Integration Models" for more information.

Thread

The thread symbol symbolizes a static thread of execution at compile-time. Threads can only be attached to components. Only objects, i.e. SDL entities, can be attached to a thread.

Figure 316 A thread symbol named "My_thread"

The thread symbol can only be used for modeling threaded integrations, i.e. for a Deployment Diagram with threads. Partitioning Diagram Data can only be generated if the component has "Threaded" as integration model.

You can make four settings for a thread through the "Symbol Details" dialog box. These are:

  • Thread Priority
  • Stack Size
  • Queue Size
  • Max Signal Size

The settings are available to the Targeting Expert through the Partitioning Diagram Model. The settings are common among real-time operating systems.

The values that are entered are platform-specific and are used when compiling the system for your target environment. You are free to enter any value, e.g. a number or a macro, that makes sense in your target environment.

You can choose to either explicitly set a value, or leave it empty. Any setting that is not filled in is considered undefined. In that case, a default value is used.

Note:

Your target operating system may have thread settings that do not exactly match the available thread settings in the Deployment Editor. If you know that a setting is not available in your Operating System, leave the text box empty.

Object

The object symbol is a general notion of an SDL system, block or process. The stereotype field is used to state the type of SDL symbol. This information is mandatory and has three possible values:

  • system
  • block
  • process

The stereotype value is shown within the object symbol. Figure 317 shows an object with process as stereotype.

Figure 317 An object symbol with name and stereotype

Note:

It is recommended that the object name in the deployment diagram correspond to the name of the SDL object which is deployed. However, it is not required that the names are identical. For instance, if you add two SDL objects with identical SDL names to the same namespace, you might want to separate them by changing the object name of one the SDL objects. You can freely change the object name, as the object is uniquely identified by its qualifier.

For an object, it is mandatory to enter information in the Qualifier field in the Symbol Details dialog box. The qualifier consists of the path for an SDL object in the Organizer tree structure. `/' is used as a separator. The path must include the object name itself.

Some examples of object qualifiers for the AccessControl system are shown in the table below. You can verify the qualifiers by opening the AccessControl system in the Organizer (<SDL suite installation directory>/examples/AccessControl/Accesscontrol.sdt) and comparing them with the entries in the table.

Object Name | Qualifier
CodeReader | AccessControl/Local/CodeReader
Controller | AccessControl/Local/Controller
Central | AccessControl/Central
Display | AccessControl/Local/Display
Doors | AccessControl/Local/Doors

An example of an object with all mandatory information entered is given in Example 298.

Example 298 : Object Name, Qualifier and Stereotype

In the AccessControl system, the process Central in block CentralUnit has AccessControl/CentralUnit/Central as qualifier. For readability, the object is given the name Central. The stereotype is set to process.

Associations and Aggregations

The Deployment Editor diagram uses associations for modeling relations between nodes. Composite aggregation is used for the following relations:

  • Node - Component
  • Component - Thread
  • Component - Object
  • Thread - Object

There is a Line Details dialog box, which is common for all sorts of relations. For an association, you can model protocol, encoding and direction data. For a composite aggregation, only multiplicity data can be edited. For a more detailed description of the dialog box, see "DP Editor Specific Information.

.

Note:

Associations between nodes are ignored when partitioning diagram data is generated.

Integration Models

The Deployment Editor supports three different integration models. The choice of integration model is set at component level.

Light Integration

In the light integration model, one or many SDL objects execute within one single task. The integration model is called Light in the Symbol Details dialog box.

The thread symbol is not used when modeling a light integration. All objects that should execute in a component with a light integration should be attached directly to the component. See Example 299 for an example of a light integration.

Example 299 : A Light Integration

This example (see Figure 318) shows a light integration containing two objects from the AccessControl system. All process instances run in one single task in one executable file. The objects are connected directly to the component, which has Light as integration model. The Control block has AccessControl/LocalStation/Control as qualifier and the DoorControl block has AccessControl/LocalStation/DoorControl as qualifier. Both objects have block as stereotype.

Figure 318 A light integration

Tight Integration

In a tight integration, each SDL process instance is put in a task of its own. The number of tasks varies at run-time, as process instances are created and terminated dynamically.

As described in "The View" , the deployment diagram shows a static view of SDL systems at compile-time. The thread symbol symbolizes one static thread of execution, which makes it inappropriate for modeling tight integrations. Therefore, the thread symbol is not used for modeling tight integrations. Always attach objects directly to a component when you model a tight integration.

Note:

The Deployment Editor does not prevent you from attaching threads to a component with Light or Tight as integration model. The check is performed when partitioning diagram data is generated for the Targeting Expert. If you have an invalid diagram, you will get error messages in the Organizer Log.

An example of a typical tight integration is shown in Example 300.

Example 300 : A Tight Integration

This example (see Figure 319) shows a tight integration where two processes from the AccessControl system are executing in one component. The component is deployed on a node.

Each process instance of the two SDL processes will execute in an OS task of its own on the target operating system.

The component has Tight as integration model (not visible in the figure). DoorController has AccessControl/LocalStation/DoorControl/DoorController as qualifier and process as stereotype. Controller has AccessControl/LocalStation/Control/Controller as qualifier and block as stereotype.

Figure 319 A tight integration

Threaded Integration

Using the threaded integration model, you can map an arbitrary number of SDL objects to an arbitrary number of threads. Each thread symbolizes a light-weight process in the executable file that is generated.

All objects that are connected directly to a component, having a threaded integration, are considered executing together in one implicit thread. Only default values for thread priority, stack size, etc. are available for an implicit thread.

The most common deployment case is that the smallest, indivisible entity is the process instance set. This is the smallest entity that can be graphically represented in a Deployment Diagram. However, it is possible to make each single instance of an object execute in a separate thread in the threaded integration model. This is modeled using multiplicity on the aggregation between a component and the thread that contains the SDL object. Set the multiplicity of the aggregation between the component and the thread to `*' to model this scenario. For a thread with `*' as multiplicity, the values of thread priority, stack size and queue size, etc. will apply to all threads that are created in the target environment.

A complete example of a threaded integration that illustrates the concepts is shown in Example 301.

Example 301 : A Threaded Integration

Figure 320 shows a component with many threads attached. The thread T has two objects (CentralUnit and PanelControl) attached to it. All process instances in these two blocks will execute within one thread. The component should execute on Windows 2000. Thus, Windows-specific thread settings are given. The following values are set: Thread Priority: THREAD_PRIORITY_ABOVE_NORMAL, Stack Size: 2048. The other fields are left empty, as default values should be used.

Figure 320 A threaded integration

The Controller object is attached directly to the component and will thus execute in an implicit thread. If there were more objects attached directly to the component, they would execute in the same thread as Controller. As the thread is implicit, default values are used in the thread settings.

The thread T1 has `*' as multiplicity in the aggregation between itself and the component. This indicates that all process instances in objects attached to T1 will execute in a thread of its own. The thread settings for T1 are: Priority: THREAD_PRIORITY_BELOW_NORMAL, Stack Size: 1024. These settings will apply to all threads that are created.

All objects have stereotype and qualifier values set as shown in the previous examples.


Deployment Workflow

Drawing a Deployment Diagram

One or many SDL systems can be deployed in the same deployment diagram. However, it is necessary that all the deployed SDL systems reside in the same .sdt file.

Perform the following steps to draw a complete diagram:

  1. Start the Deployment Editor with a new diagram. See "Starting the Deployment Editor" for instructions.
  2. Name the diagram. As the diagram name is used for naming the target directory root, it is important to select a descriptive name.
  3. Identify the nodes on which your system(s) will execute. Draw the nodes in the deployment diagram.
  4. Name each node and edit stereotype and properties values in the Symbol Details dialog box, if desired.
  5. For each node, identify the executables. Each executable is symbolized by a component.
  6. Draw the components in the deployment diagram and draw aggregations from the node symbols to the components that should execute on them.
  7. Set name and edit the integration model for each component.
  8. Draw the threads that you wish to use and enter thread settings for each thread.
  9. Draw the objects that you wish to deploy. Collect name, qualifier and stereotype information from the Organizer view of your SDL systems and enter this information in each object.
  10. Connect each object to a component or thread, depending on the integration model chosen.

Tip:
Let the Organizer window be visible when you edit the diagrams for easy access to SDL object information.

Example 302 shows a deployment scenario where components with different integration models are combined.

Example 302 : AccessControl Deployment

This example shows a Deployment Diagram for the AccessControl system. The complete system is deployed on two nodes, as shown in Figure 321. On each node there is a component. The component Prog1 has Threaded as integration model and uses threads. See Example 301 for a more detailed description of threaded concepts.

The node named Ethernet_Hub is contained in the diagram to show how the nodes are physically connected to its external environment in a network. As this node has external as stereotype, it is ignored when partitioning diagram data is generated. The associations between the nodes are also ignored.

Figure 321 Deployment of the AccessControl system

The component Prog2 has Tight as integration model. The SDL objects are attached directly to the component. Note that the integration model is not visible in the diagram. It is set in the "Symbol Details" dialog box.

Tip:
Draw several Deployment Diagrams to experiment with different deployment situations for your SDL systems. This can be useful when you experiment with different thread configurations.

Generating Partitioning Diagram Data for the Targeting Expert

The Targeting Expert uses the Partitioning Diagram Model (PDM) to structure an application that should be built. It uses the node and component concepts from the Deployment Diagram.

PDM files can be generated from Deployment Diagrams using the Organizer. In order to start the Targeting Expert with partitioning diagram data from a deployment diagram, perform the following tasks:

  1. Right-click the deployment diagram symbol (.sdp file) in the Organizer.
  2. Select Targeting Expert from the pop-up menu.

A partitioning diagram model is now generated. If there are errors or information messages, the Organizer Log is opened. If the generation passes, the Targeting Expert is started in interactive mode with the partitioning diagram.

The PDM file is saved in the same directory as the .sdp file and has the name as the .sdp file except for the extension, which is .pdm. As the PDM data is saved on file, it can be used by the Targeting Expert both in interactive mode and batch mode.

Note:

When the Targeting Expert is started in interactive mode with a deployment diagram, the .sdt file that contains the referenced SDL objects must be loaded into the Organizer. The Targeting Expert cannot be started from a deployment diagram without an .sdt file which has been saved.

PDM in Targeting Expert Interactive Mode

To start the Targeting Expert in interactive mode with data from a deployment diagram, you must right-click the .sdp file symbol in the Organizer and select Targeting Expert. The Partitioning Diagram Model is not visible from the Organizer.

The Partitioning Diagram Model for the deployment diagram is shown in the upper-left corner in the Targeting Expert window. The application is seen on node and component level. For each component, you make build settings. Depending on the integration model selected in the deployment diagram, specific predefined integration settings are available.

For more information on the Targeting Expert batch mode, see "Interactive Mode" .

PDM in Targeting Expert Batch Mode

The Targeting Expert can use PDM files in batch mode by either setting the flag -pdm or by giving the command Open-PDM as a batch mode command. A PDM file from a Deployment Diagram must be generated using the Organizer. After that, the PDM file can be used in either interactive or batch mode.

For more information on the Targeting Expert batch mode, see "Batch Mode" .


42 Editing MSC Diagrams

This chapter describes how to create and edit MSCs (Message Sequence Charts).

If you only have a MSC Trace license this chapter is still applicable since you are allowed to move symbols in a generated trace. Adding and removing symbols is however blocked.

For a reference to the MSC Editor, see 40 Using Diagram Editors.


General

Editing Functions

The MSC Editor is the graphical tool that you use to create, edit, print and store Message Sequence Charts. The MSC Editor provides, among other things, the facility of including MSCs into SDL systems.

The basic editing functionality that the MSC Editor provides can be summarized as:

  • Creating and managing MSCs
  • Appending, moving, resizing symbols
  • Interconnecting symbols with lines
  • Editing text
  • Printing MSCs

Tracing a Simulation

You can also use the MSC Editor as a graphical trace tool, which enables the automatic generation of an MSC from a simulation. The results of the simulation will be presented in an MSC Editor window, in which each event of interest will be appended to the chart in order to build up a chart which reflects the history of the simulation. The results of a simulation can be saved in MSC/PR form and re-read by the MSC Editor.

The commands that start up the logging of MSC events, set up the scope of trace, stop the logging of events, and so on, are given to the Simulator. See 50 Simulating a System.

Validating a System

An MSC can be used as a means to express the requirements on an SDL system. With the MSC Editor and the Validator, a powerful validation environment is provided. The basic idea is to draw an MSC using the MSC Editor and then use the Validator to check if there is a possible execution path for the SDL system that satisfies the MSC.

The commands that validate a system are given to the Validator. See 53 Validating a System.

Tracing user-defined events

The MSC editor also contains an API that enables any user or tool vendor to make interactive traces of events of their own choice (custom trace). Please see the header file <product install dir>/include/msctrace/msctrace.h for further details on this API.

Supported MSC Formats

The MSC Editor supports reading MSCs stored in either:

  • The MSC/GR format used by the MSC Editor (in which case the default file extension is .msc)
  • The MSC/PR format (stored on MSC/PR files, where the default file extension is .mpr)

By default, the MSC Editor stores diagrams in the MSC/GR format, but it can also generate MSC/PR for a diagram.

MSC/PR files can be expressed in two forms, event-oriented1 or instance-oriented2. See the Z.120 recommendation for more information on these two alternative formats.

1

Event oriented MSC/PR describes the MSC using the order in which the events occur, i.e. starting with the top of the diagram and downwards, providing the feeling of a global event order.

2

Instance oriented MSC/PR describes the MSC on an instance by instance basis. The feeling of a global event order within the MSC is lost.


Compliance with ITU Z.120

MSC Diagrams

The MSC Editor supports virtually all of the ITU Z.120 language definition for MSCs, including most of the MSC'96 additions.

For information on the MSC support compared to Z.120, see "Compatibility with ITU MSC.

Pagination

MSCs cannot be split into multiple pages in the same way as SDL diagrams. However, if your MSC requires more than one sheet of paper when printing, the MSC Editor takes care of splitting the chart into multiple parts to print on separate sheets of the paper size you have specified. You set up the printer pages with the Preference Manager. You can use the Window Options menu choice from the View menu to show the page boundaries on the screen.

Each part of a multiple-part chart can be printed with adjacent page markers to assist you in making up the complete chart. This feature is by default disabled and must be set as a preference or specified in the Print dialog.

Syntax Rules at Editing Time

Some of the MSC syntax rules are enforced during edit when you append symbols and lines to your MSC. These rules determine:

  • Which symbols and lines are allowed to be interconnected
  • Where symbols can be placed

This syntax checking cannot be disabled. All text is checked during editing.


Basic Operations

Starting the MSC Editor

In the Organizer, MSCs are handled as references, which you can add and remove from any of the Organizer chapters. There are several ways you can start the MSC Editor:

  • Starting the MSC Editor Stand-alone
  • Starting on an Existing MSC Icon
  • Starting on an Existing MSC, not Managed by the Organizer
  • Starting on an Unconnected MSC Icon
  • Starting on a New MSC Icon

Starting the MSC Editor Stand-alone

You have the possibility to start the MSC Editor stand-alone. This is however only recommended if you are using the MSC Editor for viewing a generated trace since you will not be connected to the Organizer and you will loose e.g. MSC reference navigation capabilities. If you have bought the MSC as a trace tool only (i.e. only at trace license) this will be your only option.

Note:

If you are making a custom interactive trace, you should not start the MSC Editor/Tracer yourself, since in that case the editor will not be able to connect with the tracing application. You need only start the MSC Editor manually when viewing saved MSC diagrams or generated MSC/PR files.

On Windows you start the MSC Editor by writing sdtmsce.exe [ <filename> ] at the command prompt. It is also possible to set up a shortcut. Please refer to your operating system documentation for further information.

On UNIX you start the MSC Editor by writing sdtmsc [ <filename> ] at the command prompt.

The optional <filename> may either refer to a GR file (usual suffix .msc) or an MSC/PR file (usual suffix .mpr). If you enter an incorrect filename the MSC Editor will terminate without giving any notice.

Starting on an Existing MSC

To start the MSC Editor on an existing MSC, you either use an MSC icon connected to an MSC diagram file, or add a new MSC icon for an MSC diagram.

Starting on an Existing MSC Icon

To start the MSC Editor on an existing MSC managed by the Organizer:

  1. In the Organizer select the icon that represents an MSC. (The MSC icon must be connected to a file.)
    • Alternatively, if the MSC is associated with an SDL diagram, you can select the associated MSC link icon (looking like an MSC icon displayed in dashed form).

Figure 322 : An MSC icon and an associated MSC icon

  2. Start the MSC Editor by the Edit menu choice on the Organizer's Edit menu or by double-clicking the MSC icon.
    The MSC Editor window is displayed, the current MSC data is read from file and the upper left portion of the chart is displayed.

Starting on an Existing MSC, not Managed by the Organizer

To start the MSC Editor on an existing diagram that is not managed by the Organizer (i.e. not contained in the Organizer structure) you must first include it into the Organizer, before the MSC Editor can be started.

To include an existing MSC into the Organizer:

  1. Select the place in the Organizer where you want to add the MSC. The MSC will be added as a new root diagram after a selected document or chapter, or at the top level of a selected module.
  2. Select Add Existing from the Organizer's Edit menu.
  3. In the dialog that is opened, find and select an MSC diagram file. Set the filename filter to *.msc to only list MSCs. The MSC is added to the Organizer structure, and is opened in the MSC Editor.
    If an SDL diagram was selected in the Organizer, an association link to the MSC is also added to the SDL diagram.

Starting on a New (Nonexisting) MSC

To start the MSC Editor on a new MSC, you either use an unconnected MSC icon, or add a new MSC icon.

Starting on an Unconnected MSC Icon

To start the MSC Editor on an existing but unconnected MSC icon:

  1. Select an unconnected MSC icon in the Organizer.
  2. Open the unconnected MSC by the Edit menu choice on the Organizer's Edit menu or by double-clicking the MSC icon. A dialog is opened:

Figure 323 : The Edit dialog

  3. Make sure the Show in editor option is set. Then click OK to open the MSC Editor on the new, empty diagram.
    • You can also change the name of the MSC diagram before it is opened.
    • To copy the contents of an existing MSC diagram file before opening the new diagram in the MSC Editor, select the option Copy existing file and enter a filename.

Starting on a New MSC Icon

To add a new MSC icon to the Organizer and start the MSC Editor on that icon:

  1. Select the place in the Organizer where you want to add the MSC. The MSC will be added as a new root diagram after a selected document or chapter, or at the top level of a selected module.
  2. Select Editors > MSC Editor from the Organizer Tools menu. A new MSC diagram icon is added to the Organizer structure, and the new diagram is opened in the MSC Editor. If an SDL diagram was selected in the Organizer, an association link to the MSC is also added to the SDL diagram.
    • Alternatively, select Add New from the Organizer Edit menu. A dialog is opened. Select an MSC diagram type, enter a name in the New document name field and click OK.

Exiting the MSC Editor

  1. Select Exit from the File menu. If the MSC Editor holds any MSC that you have modified but not saved, a dialog is issued, prompting you to save the changes before the application terminates.
  2. The dialog informs you about the name of the diagram in turn to be saved. Depending on if you want to save the changes or not:
    • Click Save to save changes made to the current diagram. The MSC Editor prompts you to save the next modified diagram, alternatively exits if there are no more diagrams to save.
    • Click No Save to close the current diagram without saving it. The MSC Editor then prompts you to save the next modified diagram, alternatively exits if there are no more diagrams to save.
    • Click Save All to save all changes made to all diagrams. Once all diagrams are saved, the MSC Editor will exit.
    • Click Quit All to exit the MSC Editor without saving any MSCs.
    • Click Cancel if you want to continue the MSC Editor session.


Managing MSCs

You create MSCs in the MSC Editor. Once an MSC has been created, you may include it into the structure that is managed by the Organizer, in order to take full advantage of the functionality that Telelogic Tau provides. MSCs can however be handled as separate entities.

The following operations are described in this section:

  • Creating an MSC
  • Renaming an MSC
  • Opening an MSC
  • Saving an MSC
  • Saving a Copy of an MSC
  • Displaying an Opened MSC.

Creating an MSC

You can create MSCs in two ways.

Creating an MSC from the MSC Editor

  1. Select New from the File menu. A dialog is displayed.
  2. Enter the diagram name and type and click New.
    The MSC is saved as a separate entity that is not automatically appended to the Organizer structure. You may want to add the MSC to the Organizer in order to provide an instant access to it from the Organizer. See "Starting on a New MSC Icon" .

Creating an MSC from the Organizer

The procedure is identical to starting the MSC Editor with no existing MSC icon. See "Starting on an Existing MSC" .

Renaming an MSC

You can change the name of an MSC. The name of an MSC is reflected in the MSC heading.

To change the name, simply edit the heading.

Opening an MSC

You can open an MSC from the MSC Editor or from the Organizer.

Opening an MSC File from the MSC Editor

  1. Select Open from the File menu. A File Selection Dialog is issued.
  2. Select a file and click OK.

You can open binary GR files (*.msc) or textual PR files (*.mpr).

Opening an MSC from the Organizer

  1. Select an MSC in the Organizer.
    • Alternatively, if the MSC is associated with an SDL diagram, you can select the associated MSC link icon (looking like an MSC icon displayed in dashed form, see Figure 322).
  2. Double-click the MSC icon.

Saving an MSC

There are several ways to save an MSC. Either you can save changes made to one specific MSC or all MSCs modified during the current session.

Saving an MSC in the MSC Editor

  • Select Save from the File menu or click the quick-button for Save.
    If the diagram is newly created, a file selection dialog is issued where you can specify the file to save the diagram on.

Saving All MSCs

You can make a global save of all the MSCs that are open in the current session, and that are modified:

  • Select Save All from the File menu. (You will be prompted to specify a file for new diagrams that have never been saved on file.)

Saving an MSC in MSC/PR Format

You can save an MSC in the MSC/PR format. See "Generate MSC PR" .

Saving a Copy of an MSC

You can save the MSC you are working on into another file. You may either continue working with the original file or with the newly created copy.

Continuing Working with the New Copy

  1. Select Save As from the File menu. A file selection dialog is issued.
    The default file name which is suggested is the same file as the original was stored on, appended with an integer suffix (1, 2,..., N) in order to build up a unique file name.
  2. Click OK. The MSC is copied to the specified file, the file containing the original is closed, and the window from where the save was made remains open for editing the newly created file.

Continuing Working with the Original

  1. Select Save a Copy as from the File menu. A file selection dialog is issued.
    The default file name which is suggested is the same file as the original was stored on, appended with an integer suffix (1, 2,...,N) that guarantees a unique file name.
  2. Click OK. The MSC is saved on the specified file, and the window with the file from where the save was made remains open for editing.

Displaying an Opened MSC

You can display an MSC that is currently opened by the MSC Editor. (The MSC that you would like to see may reside in a window which is not on top of the screen.)

The Diagrams menu shows all MSCs (up to a maximum of the last nine to have been opened). If more than nine MSCs are open, a tenth menu choice, List All, provides access to a list dialog where all MSCs currently opened are listed.


Rearranging an MSC

The following topics are discussed:

  • Resizing an MSC
  • Changing the Spacing

Resizing an MSC

Resizing Automatically

When you append objects by double-clicking, the MSC Editor will automatically enlarge the MSC size when the MSC has grown so that it reaches the bottom or right of the drawing area. The drawing area is enlarged according to the value of a preference parameter.

Resizing Manually

  1. Display the MSC you want to resize.
  2. From the Edit menu, select Drawing Size. A dialog appears.
  3. Type in the new width and height for the MSC within the allowed range.
  4. Click OK. The MSC is resized accordingly.

Changing the Spacing

When the MSC Editor layouts an MSC, it makes use of a horizontal and vertical spacing parameter that affect the total height and width of the MSC. All instances and events on instances are positioned with an integer multiple of the spacing parameters.

  1. From the View menu, select Insert Options (see "Insert Options" ). A dialog appears.
  2. Drag the sliders for a coarse adjustment. Click left or right on the slider bar for a fine adjustment.
    • Smaller values will give the chart a compact appearance that may possibly make it more difficult to read. Text associated to symbols may overlap other symbols and text. Symbols may overlap each other.
    • Larger values will give the chart a less cramped appearance and makes it easier to read to the price of a larger size.
  3. Click OK.


Managing Windows

Each MSC Editor window shows one MSC, but you may open new windows on a diagram and close windows that are no longer needed.

A newly opened window is a mirror image of the window from which the selection to open a window was made. Multiple windows may be opened and are all identical to the first. Any subsequent modifications made will reflect the same in either the original window, or any of the newly opened window(s). This option affords the possibility of viewing in more than one window, and can ideally be used in conjunction with the scaling factor when looking at a detailed MSC.

Opening and Closing Windows

You open and close windows with the New Window and Close Window menu choices in the Windows menu. If you close the last opened window, the editor will exit.

Hiding and Showing Parts of the Window

The component parts of the MSC Editor window can be shown or hidden as required. On UNIX, if they are hidden, it increases the drawing area available to be used in the creation or modification of a diagram.

To change the options for hiding and showing parts of the window, select Window Options from the View menu. These options can also be set as preferences, and some of them are available from quick-buttons:

  • The quick buttons for text window on / off or symbol menu on / off.

  • The quick button for instance ruler on / off.


Selecting Objects

To select an object, you click it. The object will be marked with selection squares that indicates that it is selected. A filled selection square (not a grey) means that you can resize or move the object by dragging the square.

Related topics are:

  • Selecting an Object That Has Associated Objects
  • Extending, Reducing or Cancelling a Selection
  • Requesting Detailed Information on an Object.

Selecting an Object That Has Associated Objects

An object may have other objects associated to it. When you select an object, all of the object's attributes are also selected:

  • A symbol may have associated lines and text attributes.
  • A line may have associated text attributes.
  • A text object has no associated attributes.

Associated text, for example symbol text, symbol names and timer names, will be displayed in the text window.

When you open a condition or MSC reference symbol, the Connect dialog is also opened.

Extending, Reducing or Cancelling a Selection

The editor provides standard functions for extending, reducing and cancelling selection of objects.

Requesting Detailed Information on an Object

The info window is an auxiliary window that provides additional information about the object you have selected.

To open an info window:

  1. Display the diagram on which you want additional information.
  2. Select Info Window from the Window menu. The info window is displayed.


Adding and Removing Objects

The topics discussed in this section are:

  • Adding and Placing Symbols
  • Adjusting Objects to the Grid
  • Inserting Space for Events
  • Inserting Space for Events Automatically
  • Removing Space between Events
  • Removing Objects
  • Adding a Text Symbol
  • Adding a Comment Symbol
  • Adding an Instance Head Symbol
  • Adding an Instance End Symbol
  • Adding a Stop Symbol
  • Adding a Condition, MSC Reference or Inline Expression Symbol
  • Adding an Action Symbol
  • Adding a Coregion Symbol
  • Drawing a Message
  • Drawing a Message-to-self
  • Drawing a Timer
  • Drawing a Process Create

Adding and Placing Symbols

  1. You can add a symbol from the symbol menu to a chart in two ways:
    • Automatically, by double-clicking the symbol in the symbol menu. The symbol will be placed at a location defined according to the type of symbol and in relation to the current selection. This will be further described for each symbol type.
    • Manually, by first selecting it in the symbol menu and then clicking at the desired location in the drawing area. To cancel the operation before the symbol is added, press <Esc>.
  2. Enter the symbol's text attributes.

Adjusting Objects to the Grid

The MSC Editor positions symbols and lines automatically. When you draw and move symbols and lines, each object is positioned on the closest intersection in the grid.

Inserting Space for Events

When you work on an MSC, the space available between two events on an instance axis may not be sufficient for inserting new objects on the instance axis. The MSC Editor can reorganize the MSC in order to provide the required space.

  1. Select the object before or after where to insert space.

  2. From the Edit menu, select Make Space. Alternatively click the quick-button for Make space for new events. The Make Space dialog is issued.

  3. Turn the appropriate radio button on, depending on if you have selected the object before or after where to insert space.
  4. Type in the required number of events to insert (the default is 1 event). A negative number implies removal of space.
  5. Click OK. The MSC is rearranged and space is created on the instance axis/axes.

Inserting Space for Events Automatically

Space is made on the instance axis when you select and add new symbols from the symbol menu or when you move symbols in the diagram.

  1. Select a symbol in the symbol menu and move the cursor to the place on the instance axis where you want to insert the symbol.
  2. Click the mouse. The MSC is rearranged and space is created on the instance axis/axes.

Removing Space between Events

  1. Select the object before where to remove space.

  2. Click the quick-button for Remove space between events.

Removing Objects

You can remove any selected object(s) this way:

  1. Select the objects to remove.
  2. Choose Clear from the Edit menu. The objects are removed.

Note:

Selecting an object to clear may implicitly select other objects. The Clear command will delete them all. See Figure 324.

Figure 324 : Selecting an object that has associated objects

Clearing the instance Instance_1 will also remove the messages Message 1 and Message 2.

Adding a Text Symbol

To add a text symbol automatically, double-click the text symbol in the symbol menu. The text symbol will be placed at the first available position at the top of the drawing area, starting from the left of the diagram.

Adding a Comment Symbol

The following conditions apply to comment symbols in the MSC Editor:

  • A comment symbol can only be connected to one symbol or event.
  • Only one comment symbol may be connected to an object.
  • A comment symbol cannot be connected to another comment symbol or a text symbol.

To add a comment symbol automatically:

  1. Select the object to which you wish to connect the comment.
  2. Double-click the comment symbol in the symbol menu. The comment symbol will be placed to the right of the selected object and be connected to it. (If no object was selected, the comment symbol will be placed at an empty position, and you will have to connect the symbol to an object manually, as described next.)

To add a comment symbol manually:

  1. Select the comment symbol in the symbol menu and place it in the drawing area.
  2. Click the handle on the comment symbol, and then click on the object you wish to comment. A dashed line is drawn between the objects.

Adding an Instance Head Symbol

You can add a new instance either directly by using the instance head symbol, or you can visualize an instance that is started dynamically by using the process create line. The latter approach is described in "Drawing a Process Create" .

To add an instance head symbol automatically:

  1. Select, if you wish, an object to use as reference point when positioning the instance head.
  2. Double-click the instance head symbol in the symbol menu.
    • If an object was selected in the drawing area, the instance head symbol will be placed to the right of the selected object.
    • If no object was selected, the instance head symbol will be placed on top of the MSC, at the first available location starting from the left.
  3. Fill in the instance head text fields. See Figure 325.

Figure 325 : The instance head text fields

Adding an Instance End Symbol

The instance end symbol determines the end of the description of an instance within an MSC. It does not describe the actual termination of the instance. That is done with the stop symbol, see "Adding a Stop Symbol" .

If you position the instance end symbol above (before) a symbol or line on the instance axis, all symbols and lines below (after) that object will be deleted. This is also true when you add a stop symbol:

.

Figure 326 : Placing an Instance End

The placement of the instance end symbol deletes message Message2 but not Message1.

To add an instance end symbol automatically:

  1. Select an object on the instance axis immediately above (before) the desired endpoint.
  2. Double-click the instance end symbol in the symbol menu.
    All symbols and lines on the instance axis below it are deleted. The instance axis line is truncated and connected to the instance end symbol.

Adding a Stop Symbol

The stop symbol at the end of an instance body indicates the termination of that instance, as opposed to the instance end symbol, which only determines the end of the description of the instance within the MSC.

If you position the stop symbol above ("before") a symbol or line on the instance axis, all symbols and lines below ("after") that object will be deleted. See Figure 326.

To add a stop symbol automatically:

  1. Select an object on the instance axis immediately above (before) the desired endpoint.
  2. Double-click the stop symbol in the symbol menu.
  3. The instance axis line is truncated and is connected to the stop symbol.

Drawing a Message

To draw a message you need to know from which instance it should be issued (the source instance) and to which instance it should be sent (the target instance).

Drawing a Message Automatically

  1. Select the object on the source instance axis immediately above (before) the place where you wish to draw the line.
  2. Double-click the message symbol in the symbol menu. The MSC Editor inserts the base end of the message on the instance axis, with the target end of the message (the arrow) marked as unconnected (lost) and facing right. (Figure 327)

Figure 327 : A lost message

  3. Drag the target end to (or close to) the target instance axis and release the mouse button to connect the line. If you do not connect the end of the message, it will remain unconnected (lost), indicated by the filled circle.
  4. Enter the message name and its parameters.

Drawing a Message Manually

  1. Click the message symbol in the symbol menu.
  2. To create a message or lost message:
    Point at the source instance axis and click once (the circle indicating a found message disappears when you are close enough to an instance axis). From now on, the base of the message is fixed to the source instance. The message is displayed as lost, following the mouse motion. (See Figure 327.)
    Or
    To create a found message:
    Point between two instance axes and click once. The base of the message is fixed at this position.

Figure 328 : A found message with a connected end

  3. Point at or close to the target instance axis, and click to connect the message end to the target instance. The line is connected pushing down subsequent symbols on the instance axis when necessary.
    If you do not connect the end of the message to an instance axis, it will remain unconnected (lost), indicated by the filled circle.
  4. Enter the message name and message parameters.

Inserting the Message Name and Message Parameters

  1. The message name can be entered immediately.
  2. Click the parameter selection rectangle (the lower one) so that it is the only selected object. Type the parameter list. The parenthesis around the parameter list are not displayed on the screen until you have entered a parameter.

Figure 329 : The message text fields

Drawing a Message-to-self

Drawing a message-to-self is done similarly to drawing a message. (See "Drawing a Message" .) The source instance is however always the same as the target instance.

Adding a Condition, MSC Reference or Inline Expression Symbol

Adding a Condition, MSC Reference or Inline Expression Symbol Automatically

  1. Select the object immediately above (before) the place on the instance axis where you wish to insert the symbol.
  2. Double-click the condition, MSC reference or inline expression symbol in the symbol menu.
  3. Type the condition or MSC reference name, or fill in the inline expression text.
  4. Connect the condition to the instances. See "Connecting the Condition or MSC Reference Symbol" .

Adding a Condition, MSC Reference or Inline Expression Symbol Manually

  1. Select the condition, MSC reference or inline expression symbol in the symbol menu.
  2. Position the symbol at the desired point of the instance axis. The symbol is placed on the instance axis, pushing down subsequent symbols on the instance axis when necessary.
  3. Type the condition or MSC reference name.
  4. Connect the symbol to the instances. See "Connecting the Condition or MSC Reference Symbol" .

Connecting the Condition or MSC Reference Symbol

In the MSC Editor you can connect the condition or MSC reference symbol to individual instances or perform a global connection.

Figure 330 : A condition symbol

When a symbol straddles an instance axis to which it is not connected, the axis line is drawn through the symbol. In Figure 330 the condition symbol with name Condition_name is connected to the instances a and c, but not to the instance b.

To connect a condition or MSC reference to a number of instance axes:

  1. Select the symbol to connect.
  2. Select Connect from the Edit menu. The Connect dialog is opened:

Figure 331 : Connecting an instance

  3. Select the instances to be connected in the instance list. The instances that will be connected are highlighted.
    • Click Connect to connect the condition or MSC reference symbol to the instances you have selected.
    • Click Global to connect the condition or MSC reference symbol globally to all instances in the list.

Drawing a Timer

Drawing a timer is done similarly to drawing a message line. The source instance is always the same as the target instance.

Drawing a Timer Automatically

  1. Select the object on the instance axis immediately above (before) the place where you wish to draw the timer.
  2. Double-click the timer symbol in the symbol menu. The MSC Editor inserts the timer.
  3. Drag the target end and release the mouse when you have reached the point where the timer should expire.
  4. If required, change the status of the timer by selecting Status from the Edit menu (see "Changing the Status of a Timer" ).
  5. Enter the timer name and its parameters.

Drawing a Timer Manually

  1. Click the timer symbol in the symbol menu.
  2. Point at or close to the instance axis. Click once. The base of the timer is fixed and the timer is displayed as a vertical line, following the mouse motion.
  3. Point at or close to the point on the axis where the timer should expire and click to connect the timer end. The timer end is connected and the timer is assigned the status timeout.
  4. Enter the timer name and parameters.

Drawing a Separate Timer Manually

  1. Draw a timer.
  2. Select one of the outermost selection squares (i.e. the selection squares not on the instance axis) and drag it so that the vertical extension of the timer disappears.
  3. Enter the timer name and parameters.

Changing Between Timer and Separate Timer

  • Change a timer to a separate timer by selecting one of the outermost selection squares (i.e. the selection squares not on the instance axis) and dragging it so that the vertical extension of the timer disappears.
  • Change a separate timer to a timer by selecting a selection square and dragging it vertically.

Inserting the Timer Name and Timer Parameters

  1. The timer name can be entered immediately.
  2. Click the parameter selection rectangle (the lower one) so that it is the only selected object. Type the timer parameters. The parenthesis around the timer parameters are not displayed on the screen until you have entered a parameter.

Figure 332 : The timer text fields

Changing the Status of a Timer

Z.120 specifies two appearances for the timer symbol, depending on whether the timer has expired (i.e. timeout) or whether the timer is reset.

  • Timeout - A timer expires.
  • Reset - A timer is stopped.
  • Implicit reset - A timer is assigned a new value while active.To change the status of a timer:
  • Select the timer.
  • From the Edit menu, select Status. The Timer status dialog is issued.

Figure 333 : Setting the timer status

  3. Click a radio button and then click OK. The status of the timer is changed accordingly.

Changing the Status of a Separate Timer

The status of a separate timer:

  • Set - A timer is activated but has not yet expired.
  • Timeout - A timer expires.
  • Reset - A timer is stopped.

To change the status of a timer:

  1. Select the timer.
  2. From the Edit menu, select Status. The Timer status dialog is issued.

Figure 334 : Separate Timer status

  3. Click a radio button and then click OK. The status of the timer is changed accordingly.

Adding an Action Symbol

An action symbol corresponds to the SDL task symbol. You may choose to fill it with formal or informal expressions.

To add an action symbol automatically:

  1. Select the object on the desired instance axis immediately above (before) the place where you wish to insert the symbol.
  2. Double-click the action symbol in the symbol menu. The symbol is placed on the instance axis, pushing down subsequent symbols when necessary.
  3. Fill in the action text.

Drawing a Process Create

Drawing a Process Create Automatically

  1. Select the object on the source instance axis immediately above (before) the place where you wish to draw the process create.
  2. Double-click the create process line in the symbol menu. The editor draws the create process line and places the instance head to the right of the source instance axis.
  3. Enter the create parameters and the created instance head text fields (see Figure 325).

Drawing a Process Create Line Manually

  1. Click the process create symbol in the symbol menu.
  2. Click once on the source instance axis. The base of the process create line is fixed to the source instance. The line is displayed as a dashed line.
  3. Click at the location where you wish to place the head of the created instance. The instance head and instance axis are automatically drawn.
  4. Enter the create parameters and the created instance head text fields.

Adding a Coregion Symbol

The coregion allows you to specify unordered events on an instance. A coregion covers for instance the practically important case of two or more incoming messages where the ordering of consumption may be interchanged.

  1. Select the coregion symbol in the symbol menu.
  2. Click once to designate the start point of the symbol at the instance axis.
  3. Click a second time on the same instance axis to designate the end point.


Collapsing and Decomposing Diagrams

You can create new high level and low level diagrams of your original diagrams. The topics discussed are:

  • Collapsing a Diagram
  • Decomposing a Diagram

Collapsing a Diagram

You can collapse the selected instance axes in a diagram to get an overview of the diagram.

  1. Select two or more instance axes.
  2. Select Collapse from the Edit menu.
    Two diagrams are created from the original diagram. One displaying the collapsed instances and one displaying the collapsed diagram.

See "Expand/Collapse" for more information.

Decomposing a Diagram

You can create a new diagram of a segment of the original diagram.

  1. Select an instance axis.
  2. Select Decompose from the Edit menu. A dialog is opened.
  3. Enter or change the name of the decomposed instance and click OK.
    The instance in the original diagram will be marked as decomposed. A decomposed diagram is created and it is displayed in the Organizer.

See "Decompose" for more information.


Moving Objects

You can move one or several objects on the chart. Move several objects by first selecting them by framing or by using the shift buttons. The various procedures are described below:

  • Moving a Text Symbol
  • Moving a Comment Symbol
  • Moving an Instance Head Symbol
  • Moving an Instance End Symbol and a Stop Symbol
  • Moving an Instance Axis
  • Moving a Message
  • Moving a Message-to-self
  • Moving a Timer
  • Moving a Process Create
  • Moving a Condition or MSC Reference
  • Moving an Inline Expression Symbol
  • Moving an Action Symbol
  • Moving a Coregion Symbol.

Moving a Text Symbol

You can move the text symbol freely across the drawing area.

  • Drag the symbol to the new location.

Moving a Comment Symbol

You can move the comment symbol freely across the drawing area.

  • Drag the symbol to the new location. The symbol and the line are redrawn accordingly.
    The orientation of the symbol may change and the connecting line is redrawn as required:

Figure 335 : Moving the comment symbol.

Moving the comment symbol as shown in Figure 335 mirror flips the symbol in order to provide the shortest possible connection line.

If you move the object that the comment symbol is connected to, the comment symbol moves with it.

Moving an Instance Head Symbol

The instance head symbol can be moved horizontally or vertically.

  • Drag the instance head to the new location.
    • If you induce a horizontal movement, the entire instance axis and the connected objects are redrawn accordingly.
    • If you induce a vertical movement, only the instance head is moved. The objects on the instance axis are not affected.

Restrictions

The following restrictions apply when moving an instance head vertically:

  • You can move the instance head symbol upwards until it reaches the limit of the drawing area. See (1) in Figure 336. No other symbols or lines are affected by this operation.
    • An instance head symbol that belongs to a process create line cannot, however, be moved above the head of its parent instance axis.
  • You can move the instance head symbol downwards until it reaches the instance end symbol or until it reaches the first event (condition, action, message, timer, stop or process create) that is connected to its instance axis. No other symbols or lines are affected by this operation. See (2) in Figure 336

Figure 336 : Moving the instance head and the instance end symbols

The bold arrows show the limitations applied on the leftmost instance head and instance end.

Moving an Instance End Symbol and a Stop Symbol

You can move the instance end symbol and stop symbol vertically but not horizontally. The instance end is moved horizontally when you move the instance head or the instance axis horizontally.

You can move the symbol vertically:

  • Down until it reaches the bottom of the drawing area. See (3) in Figure 336.
  • Up until it reaches the last event (action, condition, message, timer or process create) that is connected to the instance axis (or reaches the instance head symbol). See (4) in Figure 336.

Moving an Instance Axis

You can move the instance axis line left or right by dragging it with the mouse. All connected messages and process create lines remain connected as they were initially. The instance head and instance end or stop symbols will be moved accordingly. See (1) and (2) in Figure 337.

Figure 337 : Moving lines

To move an instance axis:

  • Drag the instance to the new location. The entire instance axis and the connected objects are redrawn accordingly.

Moving a Message

You can move a message vertically to any position within the limits set by the instance head symbol and the instance end or stop symbol of the source and target instances.

Moving the Entire Message

The base and the end of the message remain connected to the original source and target instances. The related message name and message parameters will be moved accordingly. See (3) and (4) in Figure 337.

You can also move the entire message to another pair of instance axes.

To move a message:

  • Drag the message to the desired position. The message and its text attributes are redrawn accordingly.

Moving the Base or End of a Message

You can move the base or end of a message up or down along the axis that it is connected to by pointing to and dragging the appropriate (base or end) selection square to the new position. The opposite selection square will remain fixed.

The end (message input) cannot be moved above the base (message output).

Moving a Message-to-self

You can move a message-to-self up or down along its instance axis or between instance axes by dragging it as you would move a message. See "Moving a Message" .

Moving the Base or End of a Message-to-Self

Use the same procedure as for a message to move the end (message input) or base point (message output) of a message-to-self (see "Moving the Base or End of a Message" ).

Moving a Condition or MSC Reference

You can move the condition and MSC reference symbol vertically along an instance axis to which it is connected; between the instance head and instance end, stop, or the bottom of the drawing area. To connect or disconnect instances to the symbol, use the Connect dialog on the Edit menu.

To move the condition and MSC reference symbol:

  • Drag the symbol to the new location on the instance axis. The symbol is redrawn at its new location.

Moving an Inline Expression Symbol

You can move the inline expression symbol vertically along the instance axis.

  • Click the left or right side of the inline expression and move it.

If the inline expression contains an involved axis, the inline expression cannot be moved below the instance end or stop symbol of that axis.

Moving a Timer

You can move a timer up or down along its instance axis or between instance axes by dragging it as you would move a message. The related timer name and parameters will be moved accordingly. See "Moving a Message" .

Use the same procedure as for a message to move the end (the time-out or reset (stopped) arrow) or base point (the set symbol) of a timer (see "Moving the Base or End of a Message" ).

Moving an Action Symbol

You can move the action symbol vertically along the instance axis between the instance head and instance end, stop or the bottom of the drawing area or to another instance axis.

Moving a Process Create

To move a process create line along its source instance axis, either move the process create line or its associated instance head symbol upwards or downwards. See "Moving an Instance Head Symbol" .

Moving a Coregion Symbol

You can move a coregion up or down along its instance axis by dragging it as you would move a message. See "Moving a Message" .

If you point close to the start or end point of the coregion and start dragging the mouse, the coregion will be resized accordingly.


Reconnecting Objects

Some of the objects that are managed by the MSC Editor can be reconnected:

  • Reconnecting a Comment Symbol
  • Reconnecting a Condition or MSC Reference Symbol
  • Reconnecting a Message
  • Reconnecting a Message-to-self
  • Redirecting a Message.
  • Reconnecting a Process Create

Reconnecting a Comment Symbol

A comment symbol can be reconnected to a different object or disconnected completely from all objects.

  1. Drag the comment symbol connection handle towards the new connection point. The existing connection line is erased and a new line that follows the position of the mouse pointer is drawn.
  2. Click the connection point on the new object. The connection line is fixed to the new object.

Disconnecting the Comment Symbol

  • Select the dashed line to the comment symbol and delete it.

Reconnecting a Message

You can reconnect the base or the end of a message to another instance axis:

  1. Drag the base or end of the message towards the desired instance axis. As soon as you move the mouse the message is unconnected.
  2. When the mouse pointer is close to the new instance axis, release the mouse button. The message is now reconnected.

Reconnecting a Message-to-self

You can reconnect the base or end of a message-to-self to another instance axis. This changes the message-to-self to an ordinary message.

  • Drag the end (or the base) of the message-to-self away from the instance axis. As soon as you move the mouse, the line is displayed as an ordinary message line. Continue dragging the end of the line up or down to the new connection point and release the mouse button.

Redirecting a Message

When you draw a message, the message goes from the source instance to the target instance. It is possible to redirect a message (i.e. change its direction):

  1. Select the message to redirect.
  2. Select the Redirect command on the Edit menu. The message is redrawn in the opposite direction, and the text attributes are positioned accordingly.

Messages-to-self and overtaken messages cannot be redirected.

In Figure 338 two messages are shown. The message sent first is consumed after the message sent last, i.e. it is overtaken.

Figure 338 : An overtaken message

Reconnecting a Condition or MSC Reference Symbol

To connect or disconnect instances to the symbol:

  • Use the Connect dialog on the Edit menu, see "Connect" . (Remember, at least one instance must be left connected.)

Reconnecting a Process Create

You can reconnect the base of a process create from one instance axis to another in a similar way as when reconnecting a message (see "Reconnecting a Message" ).


Resizing Objects

All objects that are managed by the MSC Editor are automatically resized according to the size of the text. However, you can manually resize a text or comment symbol.

Resizing a Text or Comment Symbol

There are two methods of resizing the text and the comment symbol:

  • Select the Expand/Collapse command on the Edit menu to toggle between maximum and minimum size.
  • Double-click the symbol, which causes the symbol to toggle between its minimal and maximal size.


Printing Objects

It is possible to print only selected parts of an MSC.

  1. Select the objects to be printed.
  2. Select Print from the File menu.
  3. Click the Setup button.
  4. Select the option Print only selected symbols.

Figure 339 : Printing only selected objects

  5. Adjust, if necessary other Print options and click the OK and Print buttons.

See also "Printing from the MSC Editor" .


43 The UML2SDL Utility

The UML2SDL utility converts a model described in UML to an SDL system. This includes conversion of UML Static Structure diagrams to corresponding SDL concepts, as well as translation of UML (Harel) State Chart diagrams to SDL process diagrams.

This chapter includes setup instructions and a description of the functionality of the tool. In the end of the chapter, the mapping rules are described.

This guide assumes that you are familiar with the concepts of UML - static structure diagrams - as well as SDL.


Setting Up the UML2SDL Utility

To efficiently run the UML2SDL utility, you will need to set up a specialized Organizer menu bar containing the menu UML To SDL. This modified Organizer menu is defined in the file org-menus.ini that is located in /orca/uml2sdl/examples/ in the installation directory. How to add the UML2SDL menu to the Organizer is described in "Defining Menus in the SDL Suite" .


Converting UML Diagrams

When UML diagrams are to be converted into SDL diagrams, the UML diagrams need to be placed within a module in the Organizer. The diagrams may be either static structure diagrams or state charts. If multiple diagrams exist within the module, all diagrams will be converted at the same time.

To convert UML diagrams in a module:

  1. Select a diagram within the module.
  2. Select the desired conversion alternative from the UML To SDL menu (see below).

The UML2SDL converter will create a new module with the same name as the converted module, but with the prefix "SDL_" added. The new module will contain all the resulting SDL diagrams.

The UML To SDL Menu

The UML To SDL menu in the Organizer contains four alternatives:

  • Generate SDL System - generates a system using the default transformation options.
  • Generate SDL Package - generates a package using the default transformation options.
  • Generate SDL System - allows you to configure the generation of an SDL system using transformation options.
  • Generate SDL Package - allows you to configure the generation of an SDL package using transformation options.

Transformation Options

The UML2SDL utility is run as a command-line tool, but is started from the Organizer. If you select an alternative in the UML To SDL menu that allows you to change the transformation options, a dialog is opened in which you may specify the transformation options to UML2SDL:

Figure 340 : Setting transformation options for a package generation

If you select an alternative in the UML To SDL menu that uses the default transformation options, the dialog is not opened and none of the options described below are used.

The UML2SDL utility accepts a set of flags which allow you to configure the transformation:

uml2sdl [ -a | -d | -l | -o | -p | -s ] <module>
  • -a
    Avoid types: All «process» and «block» classes that can have a type property, will automatically have this type set to "false".
  • -d <directory>
    The name of the sub directory that will contain the generated SDL files. A suggestion is given in the dialog, which you can alter. If the directory name does not match an existing sub directory, a new one will be created inside the current working directory.
  • -l
    Local types: Push all type definitions as low as possible in SDL block hierarchies.
  • -o
    Output SDL/PR to stdout, that is, the generated SDL/PR will be output in the Organizer log. No SDL diagram is created in the Organizer.
  • -p
    If used, the UML package will be translated to an SDL package; otherwise it will be translated to an SDL system. This option is preset on the command line if you selected Generate SDL Package from the UML To SDL menu.
  • -s
    Signal default: All operations with no return values are considered to be signals and not remote procedures. If not used, only operations following the «signal» stereotype or operations with a property "{async}" will be mapped to signals.
  • <module>
    The name of the package or system that will be created. A suggestion is given in the dialog, which you can alter.


Transformation Rules

The transformation rules for UML static structure diagrams are described below. For information about the transformation rules applied when converting state charts, please refer to "Converting State Charts to SDL" .

General

To ensure traceability between the UML model and the SDL model, all mapped entities keep their name throughout the models.

An Organizer module is considered to represent a UML package. A module may contain several UML static structure diagrams. The module, including all UML static structure diagrams, is transformed into an SDL package or system.

Each SDL system or package will also contain a block type representing the architecture of the UML model.

Classes

The UML2SDL utility makes some basic assumptions about how a class should be interpreted in the SDL context. The basic approach is however to instruct the tool by using stereotypes. A stereotype is a meta classification of a class. The tool relies on the following stereotypes:

  • A class with the stereotype «newtype» becomes an SDL newtype.
  • A class with the stereotype «process» becomes an SDL process.
  • A class with the stereotype «block» becomes an SDL block.

Figure 341 : A class with the stereotype « process »

A class may have attributes and operations. Depending on how the class is interpreted, attributes become variables in a process, or fields in a struct. An attribute have a name and a type; the type may be omitted. The notation for the attribute is:

< name > [ `:' < type >]

An operation has a name. It may also contain parameters and return values. An operation with a return value is translated to a remote procedure; otherwise it is translated to a signal. The notation of an operation is:

< name > [`(` { < parameter > [`:' < type > ] }* `)' ] [`:' < return value >]

A UML static structure diagram may contain references to classes defined in other packages. Such classes are given the name according to the following notation:

< Name of external package > `::' < class name >

Each externally defined class will generate a use clause, referring to the external package, in the generated SDL system or package.

Figure 342 : The notation for a process

Relations

Inheritance

Two classes connected with an inheritance relationship will generate an inheritance clause in the subtype. If two «process» classes are related by the inheritance relationship, there will be an inheritance clause in the process type representing the subclass.

Inheritance relationships between two «newtype» classes are not allowed due to limitations in SDL.

Figure 343 : An inheritance relationship in the UML model will result in an inheritance relationship in the SDL model

Aggregation

Two classes may be related by an aggregation. Depending on the context the following translations will be made:

An aggregation between a «block» class and a «process» class will place the process inside the generated block type:

Figure 344 : Aggregation expressed in UML and the generated
SDL diagrams in the Organizer view

An aggregation between a «process» class and a «newtype» class will place a variable of the newtype in the process. The newtype definition will be placed in the block containing the process.

Association

Two classes connected with an association will be transformed as two classes and connected with a signal-route and/or a channel depending on the context.

Figure 345 : Communicating classes

In Figure 345 above, two classes "Partner" and "otherProc" are connected by an association. In the generated SDL the two processes "otherProc" and "Partner" will exist in two separate blocks and they will be able to communicate through a channel and two signal routes.

State Charts

State Charts placed inside the module will be converted together with the other diagrams inside that module. The converter assumes that if a state chart has the same name as a process then the converter will try to merge the resulting SDL process behavior into the diagram of that process.


A Small Example

This example is intended to show how the UML2SDL utility can be used. The example contains a small analysis model of a game - the Demon game - which is intended to be implemented in SDL through a design model. The Demon game is used as an example in other parts of the Telelogic Tau documentation. For example, see "The Demon Game.

Model Relationships

The purpose of an analysis model is to identify the problem: what is to be done? The following model is the design model which identifies the solution. The design model answers the question how it is to be done. Good practice is to have clear dependencies between the two models, that is, traceability. Traceability is one of the key factors in a successful project.

Very often, the analysis model can be reused when the design model is created. The information provided by the problem statement is needed in the design model. The purpose of the UML2SDL utility is to automate this reuse as much as possible.

The Analysis Model

The Class Diagram

The analysis model is presented in Figure 346. It contains a set of classes which describes an overview of the Demon game. A pure analysis model might not be as detailed as the one given in the example, but the level of detail in the example is chosen to highlight the functionality of the UML2SDL utility.

Figure 346 : The Analysis Object Model

All operations of the classes in the Analysis Object Model will be mapped to signals since no operation contains a return value. Aggregate classes containing «process» classes, or marked with the stereotype «block», like GameBlock and DemonBlock, will become SDL blocks. The aggregations also tell the UML2SDL utility where to place the «process» classes. For example, the process Demon will be placed inside the block DemonBlock and the other processes will be placed inside the GameBlock.

Associations between classes are mapped to channels and signal routes. The association between the two classes GameBlock and DemonBlock will become a channel between the corresponding blocks. The association between the classes Main and the ProcessDemon will result in a path of communication between the resulting processes.

The inheritance relationship between the Game class and its sub-classes will become inheritance relationships between the corresponding processes as well. Since associations are inherited in UML but signal routes or channels are not inherited in SDL, the UML2SDL utility creates signal routes/channels for inherited associations. This results in signal routes between the process Main and Game, as well as between Main and the sub-processes of Game.

Classes with the stereotype «actor» is mapped as communication with the environment. In our example the class Player will become a channel to the environment. The operations of the class Player will be signals to the environment.

The State Charts

There exist two state charts named Main and Game in the module that will be converted, see Figure 347. The intention of using state charts in the analysis is to get an overview of the behavior of important classes, see Figure 348. The state charts will be transformed together with the class diagram. Since two «process» classes Main and Game exist the result of the UML to SDL conversion will be two complete process descriptions.

Figure 347 : The module that will be converted.

Figure 348 : The behavior of Game.

The Design Model

The nature of software engineering always requires design information to be added to the analysis at some stage, because we can never solve a problem without providing a solution. This is also true when the UML2SDL utility is used.

Typically, information that needs to be added is behavior that is not described at the UML level. For instance, there is no good way of describing behavior that is redefined in a sub-class at the UML level. For example, such behavior is added to the sub-processes of process Game. Also, there was no need of modeling the simple behavior of ProcessDemon at the stage of analysis, but we have to do that in the design.

Besides adding the basic behavior, we also need to provide a full design. This includes actions like introducing variables, timers, etc. For example, in the process Main we need to describe how the process is responsible for the creation of Game processes, see Figure 349.

Figure 349 : The complete process Main

When these steps are taken, the Demon game should be complete and possible to simulate like other SDL systems.

Summary

The intention with the UML2SDL utility is to automate the transfer from the analysis model to the design model as much as possible. The transfer will most likely include manual steps, but in theory it is possible to generate an SDL model which is detailed enough to simulate.


44 Using the SDL Editor

This chapter describes the functionality, menus, dialogs and windows of the SDL Editor. You can also find information about how to use the editor for creating and drawing SDL (Specification and Description Language) diagrams.


General

Editor Information

The editor described in this chapter handles SDL diagrams.

Another editor is capable of handling four different types of diagrams, namely the Object Model (OM) diagrams, State Chart (SC) diagrams, Message Sequence Chart (MSC) diagrams, and High-level MSC (HMSC). That editor is described in 40 Using Diagram Editors.

SDL Diagrams

The SDL Editor can handle any number of SDL diagrams of any type. Virtually all of the Z.100 recommendation is supported.

The SDL Editor supports three kinds of SDL diagrams:

  • Interaction Diagrams
  • Flow Diagrams
  • Overview Diagrams

The editing functionality that is available depends on what type of diagram the SDL Editor is handling.

This chapter describes the functionality the SDL Editor provides when you edit interaction and flow diagrams.

In Figure 350-Figure 352, you can find an example of interaction diagrams (in the example there is one system diagram and two block diagrams) and the resulting overview diagram.

Figure 350 : System diagram

Figure 351 : Block diagrams

Figure 352 : Resulting overview diagram

Interaction and Flow Diagrams

The SDL Editor works with SDL diagrams in graphical form, SDL/GR, and allows graphical editing of symbols, lines and text.

You may open multiple windows in an SDL Editor to be shown at the same time; each window will hold an SDL page. This can be useful if you want to edit different diagrams and pages and refer between them, or if you want to see the interface between two processes on different hierarchical levels. This is the normal mode in which diagrams are edited.

Interaction diagrams are: system, system type, block, block type, substructure, package diagrams.

Flow diagrams are: process, process type, service, service type, procedure, operator, macro diagrams.

Overview Diagrams

You can also use the SDL Editor to view SDL overview diagrams. An SDL overview diagram consists of a number of diagrams that are built up into a diagram subtree in which the symbols are drawn in a nested fashion, giving a more comprehensive overview of a required set of diagrams. You may have multiple SDL overview pages associated to one SDL system, at different SDL levels, and thus presenting different views of the system. You generate overview diagrams in the Organizer (using the SDL Overview command), and you can open the overview diagrams for display in the SDL Editor. Various parameters allow you to generate overview diagrams to meet your requirements.

Once an SDL overview diagram is generated, you cannot modify it in the same way that you would normally edit interaction and flow diagrams (unless you regenerate it). However, you can do limited editing on the text of overview diagrams in the SDL Editor.

Essentially, the editor works in read-only mode with regard to graphical operations. General restrictions in editing Overview diagrams are:

  • There is no symbol menu.
  • Only textual elements can be modified, not symbols and lines.

SDL Pages

The pages that the SDL Editor displays are always contained within an SDL diagram. An SDL diagram can contain any number of pages, but, must contain at least one page, and can be any of the following types.

  • Block interaction, process interaction, service interaction, package (the interaction pages)
  • Graph, service, procedure, macro, operator (the flow pages)
  • Overview

Relationship between Diagrams and Pages

Pages and diagrams must be associated with each other according to the rules of SDL. There follows a list of what type of pages can be added to different diagrams and what type of pages can be pasted into those diagrams.

Diagram type | Page types that can be added to the diagram | Page types that can be pasted to the diagram
system | block interaction | block interaction package
block | block interaction process interaction | block interaction process interaction package
substructure | block interaction | block interaction package
service | service | service graph procedure macro operator
process | graph service interaction | graph service interaction service procedure macro operator
procedure | procedure | procedure service graph macro operator
system type | block interaction | block interaction package
block type | block interaction process interaction | block interaction process interaction package
service type | service | graph procedure macro operator
process type | graph service interaction | graph service interaction service procedure macro operator
macro | macro | macro service graph procedure operator
operator | operator | operator service graph procedure macro
package | package | package block interaction
overview | overview (one page only) | -

SDL Page Order

The SDL pages that are contained in an SDL diagram are listed and handled according to the order they were added when they were created.

This order is reflected in some of the menu choices that are related to SDL pages. Also, the structure displayed by the Organizer will adopt the same order. See "Chapters" .

SDL pages can be renamed and rearranged by the Edit menu choice in the Pages menu.

Tracing Simulations (Graphical Trace)

Graphical trace, GR trace, is a method to follow the execution of transitions in SDL/GR source diagrams. It is mainly intended to be utilized together with the simulator's Step-Symbol command and should normally only be used for a small number of processes to limit the amount of information displayed. The GR trace facility will always show the next SDL symbol within the transition to be executed. After a nextstate or stop operation (e.g. between two transitions), the nextstate or stop symbol is still selected.

The GR tracing is activated from the SDL Simulator. The SDL Editor selects the symbol currently being executed. The Simulator automatically highlights the symbol and displays it. You can use either SDL to see what is being traced, or MSC to see the interaction between processes.

If you use an MSC to trace the simulation, the instances concept of MSC is mapped to the instances concept of SDL processes. The mapping rules which govern how SDL events are transformed into MSC symbols, lines and textual elements are described in "Mapping Between SDL and MSC" .

GR trace will take place in an SDL Editor window containing the appropriate diagram. If the SDL Editor does not hold the current page, but if the diagram can be found in the Organizer, then the page will be opened by the SDL Editor.

If the Organizer cannot find the diagram, or the SDL Editor cannot find an appropriate symbol to select, due to, for example, modifying the diagrams after the generation of the simulator, error messages will be issued by the Organizer or SDL Editor, but the simulation program will continue to execute without tracing graphically.

Setting Breakpoints in Simulations

During simulations, the SDL Editor can show all breakpoints that have been set in the Simulator. It is also possible to set and remove breakpoints directly in the SDL Editor by using the special Breakpoints menu that will be shown while this function is operating. The functionality is activated by the Connect-To-Editor command in the Simulator.


Compliance with ITU Z.100

The SDL Editor complies with the SDL rules as defined in the ITU Z.100 recommendation. Virtually all parts of the recommendation are supported by the SDL Editor. More information on the SDL support compared to Z.100, see "Application Programmers Interface.

Syntax Rules when Editing

Some of the SDL syntax rules are enforced during editing when you create diagrams, add pages to these diagrams, add symbols and lines to your pages and edit the text inside the symbols and lines.

Next follow the syntax checks that are performed by the SDL Editor:

  • The SDL Editor checks that names on diagrams and pages adhere to the SDL definition.
  • The type of a page that you add to a diagram must comply with the diagram type.
  • The set of the symbols you are allowed to add to a page is in accordance to the page type. Also, the SDL Editor ensures that symbols are interconnected in a way that is syntactically correct.
  • The text that is entered into a symbol or a line is instantly checked for syntax errors. When an error is located a red bar will underline the text where the error occurs.

Turning Syntax Checking On and Off

The syntax checking for entered texts, for what symbols you are allowed to use, and how you can interconnect symbols can be disabled and enabled again.

To disable or enable syntax checking:

  1. The operation applies on one diagram at the time. Therefore, make sure you are editing the correct diagram.
  2. Select the Diagram Options menu choice from the View menu. In the dialog which is issued, toggle the Layout Syntax Check and/or Textual Syntax Check button on or off and click OK.

Note: No Retroactive Syntax Checking

Turning the switch from off to on will not perform a retroactive syntax check for not allowed interconnection of symbols. Only the objects that you insert while syntax checking is enabled are checked. However, the syntax check on texts will be performed on all the texts when syntax check is set to on.

Syntax checking in Kernel Heading and Reference symbol

The syntax check for texts in the kernel heading or any reference symbol is always on independent of the diagram options setting.

Pasting and Syntax Checking

Only symbols that are valid according to what is displayed within the symbol menu may be pasted into a page. Non-valid symbols will be omitted whether or not syntax checking is enabled.

Identical Symbols - Different Syntax

SDL contains some symbols which appear identical, but are distinguished by their syntax. The symbols are:
  • The in connector and the out connector
  • The continuous signal and the enabling condition.

When layout syntax checking is on, the SDL Editor automatically determines from the context what kind of symbol it is. If syntax checking is off, the symbols are always treated as in connector and enabling condition, respectively.

Note: No Layout Check means Syntax errors

When disabling the layout syntax check and using connectors in the diagram mean that it will not be possible to analyze the diagram without errors as all connectors are treated as in connectors. Thus never turn off this switch if you want to analyze the diagram.

SDL Grammar Help

The SDL Editor provides a versatile context-sensitive support function - the Grammar Help window. The grammar help window is available to assist you when entering and editing the syntax of SDL text elements that are correct according to Z.100 definition. It simplifies writing statements with the correct SDL syntax.

The SDL Grammar Help facility is described in "Using Grammar Help" .

Signal Dictionary Support

The SDL Editor also provides a means of access to a signal dictionary where the signals that are already defined can be accessed. The Signal Dictionary window provides functions for listing SDL signals that are available when looking up or down in the SDL hierarchy or by looking at the current diagram. Also, you can ask the tool to list signals that are used in the current diagram or defined and visible according to the SDL scope rules.

Furthermore, the signal dictionary has the ability to import messages from a Message Sequence Chart (each MSC message will be mapped to an SDL signal) and to import an external signal dictionary.

For more information on this topic, see "Using the Signal Dictionary" .


The SDL Editor User Interface and Basic Operations

The SDL Editor User Interface

The SDL Editor consists of a main window and three auxiliary windows:

  • The Grammar Help window where SDL textual grammar support helps you entering correct textual expressions.
  • The Signal Dictionary window which gives you access to signals already defined in the SDL hierarchy.
  • The Entity Dictionary Window which provides you a name reuse facility as well as information for link endpoints.

The SDL Editor also contains the symbol menu, where you select the symbols (objects) that are to be inserted into the page, and the text window, where you may edit textual objects.

The general Telelogic Tau user interface is described in 1 User Interface and Basic Operations.

Figure 353 : The SDL Editor window (in Windows)

Figure 354 : The SDL Editor window (on UNIX)

Drawing Area

Figure 355 : The Drawing Area

The drawing area (see Figure 355) is the part of the window that displays the symbols, lines and text that constitute an SDL page (an SDL diagram can contain multiple pages). Most of the graphical notation that is used in the SDL Editor is inherited from the Z.100 definition. In addition, some tool specific notations have been added to facilitate the work with the SDL suite tool set in general, and the SDL Editor in particular.

The Drawing Area Boundaries

The drawing area is delimited by its boundaries, which correspond to the size of the SDL page. Within a diagram, each page has an individual size. No objects are allowed to be placed outside these boundaries. The drawing area uses a light background color, while the area outside the drawing area uses a grey pattern.

The Frame

You can select and resize the frame. All objects, except the package reference symbol, gates and printout page number must reside entirely within the frame.

The Kernel Heading

The kernel heading identifies the diagram type and its name. Alternatively, an SDL qualifier expression can be used. You can edit but not move the kernel heading. The SDL Editor performs a textual syntax check based on the grammar used in this heading.

The SDL suite supports the following syntaxes for the kernel heading:

Case
Syntax

 SYSTEM <name> [: <type expression>]

 BLOCK <identifier>

 PROCESS <identifier> [<number of instances>]

 SERVICE <identifier>

 <procedure preamble> PROCEDURE <identifier>

 SUBSTRUCTURE <identifier>

 MACRODEFINITION <name>

 SYSTEM TYPE <identifier>

 [<virtuality>] BLOCK TYPE

 [<virtuality>] PROCESS TYPE

 [<virtuality>] SERVICE TYPE

 OPERATOR <operator identifier>

 PACKAGE <name>

For an explanation and reference to the notation used in the table above, see the Z.100 recommendation.

The kernel heading is repeated trough all pages contained in an SDL diagram.

The Page Name

The page name identifies the name of the SDL page and, within parentheses, the total number of SDL pages contained in the current SDL diagram.

The contents of the page name are assigned by the tool. You can not select, move, or edit the page name.

Printout Page Number

This object is created by the SDL Editor to inform you about the physical page numbering that will be the result of an SDL page which is larger than the paper format that is defined. You can neither select nor edit it. Page numbering follows a "down first, then right" fashion.

Figure 356 : The page numbering in the SDL Editor

Grids

The SDL Editor uses two grids for an easy positioning of symbols, lines and textual elements.

  • The symbol grid, that can be set by an SDL Editor preference, has a minimum resolution of 5 * 5 mm. All symbols adhere to the symbol grid.
  • The line and text grid has a resolution of 2.5 * 2.5 mm, i.e. half the symbol grid. All lines and textual objects adhere to the line grid.

Default Size of Symbols

The symbols are assigned default sizes when added to the drawing area:

  • For interaction pages, the predefined size of a symbol is by default 30 * 20 mm.
  • For flow pages, the predefined size of a symbol is by default 20 * 10 mm. The width / size relationship is always 2:1.

You can change the default symbol size in the SDL Editor preferences.

Note:

The size of a class symbol is automatically calculated by the SDL Editor, and may thus differ from the default size.

Color on Symbols

For each symbol type there is a preference for setting the color of the symbol. It is only the graphical part of the symbol and not the associated text(s) that will use the color setting. On UNIX, the setting is only valid on screen and all symbols will use the black color when printed on paper. In Windows, when using MSW Print the colors will be sent to the printer as well. For more information, see "The SDL Suite Specific Preferences" .

Keyboard Accelerators

In addition to the standard keyboard accelerators, described in "Keyboard Accelerators" , the SDL Editor features the following:

Accelerator | Reference to corresponding command
Ctrl+D | Opens the next page in the diagram, similar to "<Page Name>"
Ctrl+G | "Split Text"
Ctrl+I | "Insert Paste"
Ctrl+U | Opens the previous page in the diagram, similar to "<Page Name>"
<Delete> | "Clear" (i.e. remove, delete)
Ctrl+1 | "Show Organizer"
Ctrl+2 | "Connect to Text Editor"

Quick-Buttons

In addition to the generic quick-buttons described in "General Quick-Buttons" , the SDL Editor tool bar contains the following quick-buttons:

Text window on / off
Toggle the text window between visible and hidden, as described in "Window Options" .

Symbol menu on / off
Toggle the symbol menu between visible and hidden, as described in "Window Options" .

Reference page
Open the page where this diagram is referenced, similar to "Edit Reference Page" .

Log Window
Pop up the Organizer Log window.

Previous page
Open the previous page in the diagram, similar to "<Page Name>" .

Next page
Open the next page in the diagram, similar to "<Page Name>" .

Toggle scale
Toggle the scale between a scale to show the complete page in the window and a scale of 100%.

Scrolling and Scaling

You can scroll the view vertically and horizontally by using the scrollbars. The view may also be scrolled automatically when you move the cursor beyond the current view, for example when you move an object or add a symbol.

If you move the cursor close to the edge of the current view, the automatic scrolling is slow. If you move it further beyond, the scrolling is quicker.

You can scale the view by specifying a scale or by zooming in and out.

To specify a scale:

  1. Select Set Scale from the View menu.
  2. In the dialog that will be opened, you can either:
    • Use the slider for setting the scale and then click the Scale button.

    • Click the Overview button to adjust the drawing area to the size of the window. (This has the same effect as the Scale Overview quick-button.) The smallest scale is 20%.

To zoom in or out:

  • Click the quick-button for zoom in or zoom out.

Moving Selection with Arrow Keys

You can move the selection using arrow keys in the SDL editor if there is one single symbol or line selected. (In this context, we regard a flow symbol together with its attached flow lines to be one symbol.)

Note that you can only move the selection when in symbol editing mode. In text editing mode, the arrow keys will move the cursor position within the text. To get into symbol editing mode, click on the symbol outside of a text area. If you are in text editing mode, you can go to symbol editing mode by pressing the escape key. If you are in symbol editing mode, you can go to text editing mode by pressing the tab key. Pressing the tab key immediately after that will either select another text for the same symbol to edit or go back to symbol editing mode.

You can move to the next page by moving forward from the last symbol on the current page. You can move to the previous page by moving backward from the first symbol on the current page.

Two shortcuts are available for fast-forward moving to colored symbols (symbols not using black as a border color and white as a background color) on pages in the current diagram:

  • Shift+arrow key to move to the next/previous colored symbol.
  • Shift+alt+arrow key to move to the next/previous colored symbol on another page than the current page.

Symbol Menu

The symbol menu contains the SDL symbols that you can place into the drawing area.

On UNIX, the symbol menu is a fixed-sized, non-moveable auxiliary window, associated with the drawing area and placed to the right of it. Each editor window has its own symbol menu.

In Windows, the symbol menu is a fixed-sized, moveable window that can be placed anywhere on the screen, not necessary within the limits of the editor window. A single symbol menu is shared by all instances of the editor currently running.

The symbol menu can be made invisible and visible again with a menu choice, Window Options, or a quick-button In Windows: When visible, the symbol menu will always be placed on top of the editor window.

Basically, when you select a symbol in the symbol menu and click it into the drawing area it is added to the diagram. How to work with symbols is described in "Working with Symbols" .

The contents of the symbol menu depends upon the type of diagram that is displayed in the SDL Editor window and the settings of the SDL Editor preferences depends upon whether the symbols should be used or not.

  • For process, process type, procedure, macro definition and operator diagrams (the flow diagrams), the default symbol menu looks like the left picture in Figure 357.
  • For interaction diagrams (system, block, substructure, service, package, system type, block type and service type), the default symbol menu looks like the right picture in Figure 357.

For a reference to these symbols, see "Symbols on Interaction Pages" and "Symbols on Flow Pages" .

Figure 357 : The Symbol menu

Syntax Checking on SDL Symbols

If layout syntax checking is enabled, some of the symbols displayed in the symbol menu may be dimmed. This indicates that those symbols are not valid within the current context, and that you cannot select them.

  • When layout syntax checking is disabled, you can select all symbols.
  • When layout syntax checking is enabled, the following rules apply:

Type of page |
System / System type | process reference service reference block substructure reference system type reference gate
Block diagram / Block interaction page | process reference service reference block substructure reference system type reference gate
Block diagram / Process interaction page | block reference service reference system type reference gate
Service | procedure start procedure return macro inlet macro outlet gate
Process diagram / Graph page | procedure start procedure return macro inlet macro outlet gate
Process diagram / Service interaction page | block reference process reference block substructure reference system type reference block type reference process type reference gate
Procedure | start stop macro inlet macro outlet gate
Block type diagram / Block interaction page | process reference service reference block substructure reference system type reference
Block type diagram / Process interaction page | block reference service reference system type reference
Macro | gate
Service type | procedure start procedure return macro inlet macro outlet
Process type diagram / Graph page | procedure start procedure return macro inlet macro outlet
Process type diagram / Service interaction page | block reference process reference block substructure reference system type reference block type reference process type reference
Operator | state input save output procedure call enabling condition / continuous signal create request priority input procedure reference start stop macro inlet macro outlet gate
Package | block reference process reference block substructure reference service reference gate


Working with Diagrams

This section describes the methods you use when performing the following tasks on SDL diagrams:

  • Creating a Diagram
  • Including a Diagram
  • Opening a Diagram
  • Saving a Diagram
  • Saving a Copy of an SDL Diagram
  • Closing a Diagram
  • Printing a Diagram
  • Displaying an Opened Diagram
  • Reorganizing a Diagram.
  • Transforming the Type of a Diagram

Creating a Diagram

You can create diagrams from within other diagrams. When created, they form part of the current active system in the SDL Editor, and their presence is instantly reflected in the Organizer. This is achieved by inserting SDL diagram reference symbols.

You can also create diagrams as separate unrelated new entities. They will however not be incorporated in the Organizer.

Creating a Related Diagram from Another Diagram

  1. Open the SDL diagram from where to start.
  2. Insert the SDL reference symbol.
  3. Assign the symbol a name.
  4. Deselect the reference symbol. The Organizer's diagram structure is updated accordingly.
  5. Double-click the newly added reference symbol. You should specify what action to perform, either:
    • Create a new diagram in the SDL Editor from scratch.
    • Copy an existing file.
      Select an option and click OK.
      The SDL Editor will now create a new diagram, possibly a new window, and display the newly created diagram.
  6. Save both the parent and the child diagram later on in your editing session, to make changes permanent.

Example in an Organizer Structure

As an example, in the Organizer structure in Figure 358, a system is shown with only one block diagram.

Figure 358 : A basic system shown in the Organizer

Suppose the system diagram is being edited. We now add a new block reference symbol, name it Block_B and deselect it. The Organizer diagram structure becomes:

Figure 359 : Having added a reference symbol

The SDL suite shows, with the [unconnected] identifier, that the newly added reference symbol is not yet connected to any physical file.

Now, double-click the Block_B symbol. Specify whether you want to create a new file or to connect the newly created block to an existing file.

Make sure the Show in Editor radio button is on and click OK. In some cases a new dialog appears, where you are to specify the name and type of the first SDL page to add to the diagram (an SDL diagram must contain at least one SDL page).

Assign a page name (see "Adding a Page" ) and click OK.

A new block diagram with the name Block_B is created. The SDL Editor responds by issuing a window showing this diagram. Also, the Organizer's diagram structure is updated, showing the new diagram icon, inserted at the corresponding place in the SDL hierarchy.

Figure 360 shows the result:

  • A newly created diagram, empty except for the diagram heading
  • The resulting diagram structure
    • The parent diagram needs to be saved (marked with a gray pattern)
    • The child diagram needs to be saved.

Figure 360 : The newly created diagram and the resulting diagram structure

Creating an Unrelated New Diagram

  1. Select New from the File menu of the SDL Editor. A dialog will be opened.
  2. Enter the name of the new diagram in the Diagram Name field. The name should be in keeping with SDL naming conventions.
  3. Choose the type of diagram from the diagram type menu.
  4. Click New. In some cases a new dialog box is shown where you can add a page, as each diagram must have at least one page. See the section "Adding a Page" for this.
    A window on the newly created diagram is opened.

Including a Diagram

Including a Diagram into the SDL Hierarchy

When you have created a diagram, it needs to be brought into the SDL hierarchy to be available for future selection in the Organizer. Otherwise, you will only be able to open it from the SDL Editor.

  1. Create the diagram using the New command from the SDL Editor. Save the diagram on file.
  2. Open the diagram that will have a reference to the newly created diagram.
  3. In the diagram you just opened, add a diagram reference symbol with a type and name that matches the newly created diagram. A new icon appears in the Organizer structure.
  4. With the Organizer Connect command, connect the new icon with the file on which the diagram is stored. See "Connect" .

Once a reference symbol is placed in the newly created page of the new diagram in the SDL Editor, the Organizer is updated to reflect this. This indicates that the SDL hierarchy is updated.

Including a Diagram into the Organizer

If a diagram is not managed by the Organizer (i.e. not contained in the Organizer structure) you must first include it into the Organizer, before you can start the SDL Editor.

  1. Select the place in the Organizer where you want to add the SDL diagram. It will be added as a new root diagram after a selected document or chapter, or at the top level of a selected module.
  2. Select the Organizer's Add Existing command from the Edit menu. A file selection dialog will be opened.
  3. Select a SDL diagram file.
    The SDL diagram is added to the Organizer structure, and opened in the SDL Editor.

Opening a Diagram

There are several ways you can open a diagram for editing, depending on where you are and what you need to access.

Lock Files and Read-Only Mode

When you open a diagram or document file, i.e. a.ssy, a lock file a.ssy.lck is created. If another user tries to open the same diagram or document file before you close it, a dialog will appear informing the other user that the file is in use.

There are two choices in the dialog:

  • Open the file in read-only mode.
  • Reset the lock and open the file in read-write mode. (This alternative should only be used if the existing lock file is obsolete.)

The read-write mode is the normal editing mode. In read-only mode, you are not allowed to make any changes to the diagram.

You will also enter read-only mode if you open a diagram file that you do not have write permission for. The read-only mode is indicated by the words read-only in the window title.

If you want to edit a diagram that is in read-only mode, here are two alternative actions:

  • Change the file access rights in the file system to give you write permission for the diagram file. Then change from read-only mode to read-write mode with the Revert Diagram operation.
  • Use File >Save As to save the diagram in a new file with write permission.

Opening a Diagram File from the SDL Editor

  1. Select Open from the File menu or click the quick-button for Open. A file selection dialog is opened.
  2. Select a file in the files list and click OK. If the file is already opened by the SDL Editor, a message is issued.

Note:

The status bar at the bottom the SDL Editor provides information about the diagram type and name stored on the file which is selected in the file list.

Opening a Diagram from the Organizer

You can open a diagram in different ways:

  • Select an SDL diagram icon or the text line next to it in the Organizer. Select Edit from the Organizer's Edit menu.
  • Double-click on an SDL diagram icon in the Organizer.

Opening a Diagram - via Organizer - to Show Analyzer Reports

When analysis has been performed, you can show the source of Analyzer error reports in an SDL Editor.

  • Select Show Error from the View menu in the Organizer Log Window. An SDL Editor window is opened with the source of error (i.e. an SDL symbol) selected.

Opening a Diagram via a Reference Symbol

You can open a diagram from the SDL Editor by double-clicking on a reference symbol, or by using the Navigate command.

  1. Locate the SDL reference symbol referring to the diagram you want to open.
  2. Double-click the symbol or select it and choose the Navigate command from the Tools menu. The diagram is opened.

Opening a Diagram from the Simulator

If you have performed a GR trace in the SDL Simulator, invoking the Show-Next-Symbol or Show-Previous-Symbol simulator commands will display either the next symbol to be executed or the previously executed symbol in a diagram in an SDL Editor window.

Opening a New (Nonexisting) SDL Diagram

To open a new SDL diagram, you either use an unconnected SDL diagram icon or add a new SDL diagram icon.

Opening an Unconnected SDL Diagram Icon

To open an existing but unconnected SDL diagram icon:

  1. Select an unconnected SDL diagram icon in the Organizer.
  2. Double-click the SDL diagram icon. A dialog is opened.
  3. Make sure the Show in editor option is set. Click OK. A new, empty diagram is opened.
    • To copy the contents of an existing SDL diagram file before opening the new diagram, select the option Copy existing file and enter a filename.

Opening a New SDL Diagram Icon

To add a new SDL diagram icon to the Organizer and opening that icon:

  1. Select the place in the Organizer where you want to add the SDL diagram. The diagram will be added as a new root diagram after a selected document or chapter, or at the top level of a selected module.
  2. From the Organizer's Tools menu, select the Editors > SDL Editor command. A new SDL diagram icon is added to the Organizer structure, and the new diagram is opened in the SDL Editor.
    • Alternatively, select the Organizer's Add New command from the Edit menu. A dialog is opened. Select a SDL diagram type, enter a name in the New document name field and click OK. The Add Page dialog is displayed, see "Adding a Page" .

Opening an Existing SDL Page

To open a specific page, the SDL pages must be visible in the Organizer diagram structure.

  1. To display page icons in the Organizer, select the Organizer's View Options command from the View menu. In the dialog, make sure Page symbols is highlighted and click Apply.
  2. Select the icon representing the SDL page in the Organizer.
  3. Double-click the SDL page icon. The SDL diagram page is displayed.

Saving a Diagram

There are several ways to save a diagram. The effect is saving any changes made to either one specific diagram, or all diagrams modified during the current session.

Saving a Diagram in the SDL Editor

  • Select Save from the File menu or click the quick-button for Save.
    If the diagram is newly created, a file selection dialog is issued where you can specify the file to save the diagram on.

Saving All Diagrams in the SDL Editor

You can make a global save of all the diagrams that are open in the current session and have been modified.

  • Select Save All from the File menu. All diagrams which are modified are saved.

Saving a Copy of an SDL Diagram

You can save the diagram being edited into another file. You may either continue working with the original file or with the newly created copy.

Continue Working with the New Copy

  1. Select Save As from the File menu. A file selection dialog is issued.
    • The file name which is suggested is the same file as the original was stored on, appended with an integer suffix (1, ..., N) in order to build up a unique file name.
  2. Click OK. The SDL diagram is copied to the specified file, the file containing the original is closed, and the window where you made the save remains open for editing the newly created file.

Continue Working with the Original

  1. Select Save a Copy As from the File menu. A file selection dialog is issued.
    • The file name which is suggested is the same file as the original was stored on, appended with an integer suffix (1, ...,N) that guarantees a unique file name.
  2. Click OK. The SDL diagram is saved on the specified file, and the window where you made the save remains open for editing.

Closing a Diagram

Closing a diagram also means closing all instances of all windows displaying any page contained in that diagram.

  • Select Close Diagram from the File menu.
    If you have modified the diagram, a Close dialog is shown where you can save the modifications before closing the diagram.

Printing a Diagram

You can print an entire SDL diagram or a selection of pages or objects contained in the diagram. You print multiple SDL diagrams from the Organizer.

See "The Print Dialogs in the SDL Suite and in the Organizer" .

Displaying an Opened Diagram

You can open the diagram that is currently read by the SDL Editor. (The diagram that you would like to see may reside in a window which is not on top of the screen.)

The Diagrams menu shows all SDL diagrams and pages (up to a maximum of the last nine to have been used). If more than nine pages are open, a tenth menu choice, List All, provides access to a list dialog where all diagrams and pages are listed.

Reorganizing a Diagram

The SDL Editor can reorganize the layout of an SDL diagram, for instance if you run out of space on any of the pages that build up the diagram.

To reorganize an SDL diagram:

  1. Display the diagram you want to reorganize.
  2. Select Tidy Up from the Tools menu. A dialog is opened.
  3. Click Tidy Up. The SDL Editor reorganizes the diagram (this may take some time, depending on how complex your diagram is).
  4. Check the diagram before continuing working with it (you can undo the operation from the Edit menu).

Transforming the Type of a Diagram

A useful operation when e.g. transforming to a more object-oriented version of the SDL system is to change the SDL88 diagrams into type diagrams and make instantiations of these types. The following shows some examples how to perform such an operation and similar ones where you want to change the type of a diagram or want to work with an SDL structure that is almost a copy of an already existing hierarchy.

Example 1

Assume that the system S consists of block B, which contains process P. The exercise to solve is to transform the block into a block type BT and put this into a package P and instantiate the block B from BT.

There is no direct command to accomplish this task in the SDL suite; instead there are many solutions, more or less complicated and time consuming. The proposed one is easy to use and will take advantage of the possibility to cut and paste complete sub-hierarchies, thereby eliminating loosing file connections and the need for making manual connections to existing files.

Solution: Open the system S, add a new block type symbol and name it BT. Open the block B and change the kernel heading from "block B" to "block type BT". Note that the sub-hierarchy in the Organizer, previously below B, has now been moved to BT. In system S, change the text in the block symbol to "B:BT" to make it an instance of BT and cut the block type symbol to the clipboard. Create a package diagram named P and paste the block type into this diagram.

Figure 361 : The Organizer view

To make the new system complete you need to add the text "use P;" in the package reference symbol in system S, define the gates inside the block type BT and use these gates to connect the existing channels for the block B. If needed, you can change the filename of the block type with the Save As command in the SDL Editor to use a filename that resembles the block type name and also use the file name extension that conforms to the SDL suite conventions.

Example 2

This is a variant of example 1. Assume we want to keep the original diagram but want to have a new block type BT in package P that is a copy of the existing B.

Solution: In package P place a new block type symbol and name it BT. Double click on it and in the appearing Edit dialog tick the Copy existing file option and use the file connected to the existing block diagram B. Click Continue in the warning about recommended file name extension. In the opened diagram, change the kernel heading to "block type BT".

For all diagram references in BT (in the example there is only one), use the Connect command in the Organizer to connect them to the existing files. In the Connect dialog be sure to use the Expand Substructure option to get automatic connections for possible sub-hierarchies.

As an alternative to connecting the diagram references you can copy the reference symbols from block B and paste them into block type BT, then you will get automatically all the connections for sub-hierarchies below the pasted references.

Note that in either case you will use the same file connection for process P in our example for both the original process and also for the process P referenced in the block type, meaning that if you change the contents of this file you will change both the behavior of the block B and the block type BT, which might lead to unexpected results. If you want unique file connections you should take a copy of the existing file, for example copy P.spr to P1.spr, and reconnect one of the processes to this new file instead.

Example 3

The SDL system consists of system S, block B, process P and procedure subPr inside P. You want to transform most of the process including its procedure subPr into a new procedure Pr defined in the system S.

Figure 362 : The Organizer view

Solution: This solution is similar to the solution to example 2. Open the system diagram S and place a procedure reference symbol named Pr. Double click it and open a copy of the existing file connected to process P. Edit the kernel heading to contain the text "procedure Pr". Save the procedure as a new file. Connect all referenced procedures inside Pr or copy the procedure references from the process P to get all the sub-hierarchy file connections. Finally edit process P and procedure Pr to make them useful in their new context.

The symbol is dashed and the change is immediately reflected in the Diagram Structure (this is only true if the Dashed Diagram option is on in the Organizer's View Options).

  • You may at any time undash a dashed symbol. Select the symbol and select Undash from the Edit menu.
  • If the symbol (prior to the dash operation) was connected in the Organizer the following dialog will appear:

Figure 363 : Removing substructure by dashing

  • If you click OK, the substructure will be removed. However, you may undo this.


About Symbols and Lines

Following is a description of the components in the drawing area. See also Symbols and Lines - Quick Reference.

The Additional Heading Symbol

Symbol Appearance
Symbol Name
References to Z.100

Additional heading

 Z100: 2.2.5    Additional heading
Z100: 6.1.1.3  Process type
               heading
Z100: 2.4.4    Formal
               parameters,
               Signalset
Z100: 6.3      Specialization
Z100: 6.3.1    Inherits
Z100: 6.3.2    Virtual,
               Redefined,
               Finalized
Z100: 6.3.2    Virtuality
               constraint
               (atleast)
Z100: 6.2      Actual context
               parameters
Z100: 6.2      Formal context
               parameters
Z100: 6.2.1 - 6.2.9
               Formal context
             para

The additional heading symbol is not defined further according to Z.100. In the SDL Editor, it looks like a dashed text symbol or it is shown without any border; this is controlled by the Editor preference ScreenZ100Symbols. The symbol is editable and resizeable, but cannot be moved. Its intended use is to define:

  • Inheritance and specialization, using the following keywords:
    • INHERITS
    • ADDING
    • ATLEAST
  • Formal parameters for a process / procedure, using the keyword FPAR
  • Directives to the SDL to C Compiler. A directive uses the SDL comment notation and a hash character, such as:
    /#INCLUDE file.pr */
  • SIGNALSET and instance information.

The additional heading symbol is either repeated through all pages contained in an SDL diagram or it is only shown on the first page. This is controlled by the editor preference AdditionalHeadingOnlyOnFirstPage and can also be specified with the SDL Editor command Diagram Options.

Note that the combined text in the Kernel Heading and the Additional Heading symbol must use the syntax as specified for a heading in SDL/PR to be accepted in the SDL Analyzer.

The Package Reference Symbol

Symbol Appearance
Symbol Name
References to Z.100

Package reference

 Z100: 2.4.1.2  Reference in
Package
Z100: 2.4.2    Reference in
System

The package reference symbol is available on system and package diagrams only. It is located outside the frame, on top and to its left. It contains references to package(s) containing definitions that are to be included in the SDL system.

You can select and resize, but not move the package reference symbol.

Other SDL Symbols

These are the symbols that describe the structure or behavior of the SDL diagram. They must be placed inside the frame.

You can draw symbols in color, see "Color on Symbols" .

Syntax Checking on Symbols

The SDL Editor checks that the symbols you add to a diagram are in accordance with the syntactic rules imposed by SDL. Symbols that are not allowed in a diagram / page of a specific type are dimmed in the symbol menu. Also the text entered is checked for syntax errors. See "Layout syntax check" .

Symbols on both Interaction Pages and Flow Pages

Symbol Appearance
Symbol Name
References to Z.100

Class

 Not included (Z100 11/99)

Symbols on Interaction Pages

Symbol Appearance
Symbol Name
References to Z.100

Text

 Z100: 2.5.4      Signal
Z100: 2.5.5      Signal list
Z100: 5.2.1      Newtype
Z100: 5.3.1.9    Syntype
Z100: 5.3.1.13   Synonym
Z100: 5.3.1.12.1 Generator
Z100: 4.13       Remote
variable
Z100: 4.14       Remote
                 procedure

Comment

 Z100: 2.2.6

Text extension

 Z100: 2.2.7
(depends on the symbol connected to)

Text Reference

 None

Block reference

 Z100: 2.4.2    Block definition
Z100: 6.1.3.2  Block def based
               on block type
Z100: 6.1.2    Type expression
Z100: 6.2      Actual context
               parameters

Process reference

 Z100: 2.4.3    Process
               definition
Z100: 2.4.4    Number of
               instances
Z100: 6.1.3.3  Process def
based
               on block type
Z100: 6.1.2    Type expression
Z100: 6.2      Actual context
               parameters

Block substructure reference

 Z100: 3.2.2

Service reference

 Z100: 2.4.4

System type

 Z100: 6.1.1.1

Block type

 Z100: 6.1.1.2

Process type

 Z100: 6.1.1.3

Service type

 Z100: 6.1.1.4

Operator reference
(an SDL/GR extension defined in the SDL suite)

 Z100: 5.3.2  Referenced
operator
             in SDL/PR

Gate

 Z100: 6.1.4  Gate
Z100: 2.5.5  Signal list

Symbols on Flow Pages

Symbol Appearance
Symbol Name
References to Z.100

State or nextstate

 Z100: 2.6.3     State
Z100: 4.4       Asterisk state
Z100: 4.5       Multiple
                appearence of
                state
Z100: 2.6.8.2.1 Nextstate
Z100: 4.9       Dash nextstate

Text

 Z100: 2.5.4      Signal
Z100: 2.5.5      Signal list
Z100: 5.2.1      Newtype
Z100: 5.3.1.9    Syntype
Z100: 5.3.1.13   Synonym
Z100: 5.3.1.12.1 Generator
Z100: 2.6.1.1    Variable
Z100: 2.6.1.2    View
Z100: 2.8        Timer
Z100: 4.13       Remote
variable
Z100: 4.13       Imported
                 variable
Z100: 4.14       Remote
                 procedure
Z100: 4.14       Imported
                 procedure

Input

 Z100: 2.6.4    Input
Z100: 4.6      Asterisk input
Z100: 4.14     Remote procedure
               input
Z100: 6.3.3    Virtual
               transition
z100: 5.4.3    Variable
z100: 5.4.3.1  Indexed variable
z100: 5.4.3.2  Field Variable

Comment

 Z100: 2.2.6

Save

 Z100: 2.6.5   Save
Z100: 4.7     Asterisk save
Z100: 6.3.3   Virtual save

Text extension

 Z100: 2.2.7
(depends on the symbol connected to)

Output

 Z100: 2.7.4

Decision

 Z100: 2.7.5      Decision
Z100: 5.3.1.9.1  Range
condition
Z100: 2.2.3      Informal text

In-connector or out-connector

 Z100: 2.6.7       In-connector
Z100: 2.6.8.2.2   Out-connector

Task, set, reset or export

 Z100: 2.7.1   Task
Z100: 5.4.3   Assignment
Z100: 2.8     Set, Reset
Z100: 4.13    Export

Procedure call

 Z100: 2.7.3   Call
Z100: 2.7.2   Actual parameters

Macro call

 Z100: 4.2.3

Create request

 Z100: 2.7.2

Transition option

 Z100: 4.3.4      Transition
option
Z100: 5.3.1.9.1  Range
condition

Continuous signal or enabling condition

 Z100: 4.11 Continuous signal
Z100: 4.12 Enabling condition

Start

 Z100: 2.6.2  Start
Z100: 6.3.3  Virtual transition

Priority input

 Z100: 4.10     Priority input
Z100: 2.6.4    Stimulus
Z100: 6.3.3    Virtual
               transition
z100: 5.4.3    Variable
z100: 5.4.3.1  Indexed variable
z100: 5.4.3.2  Field variable

Stop

 Z100: 2.5.8.2.3

Procedure start

 Z100: 2.4.6

Inlet

 Z100: 4.2.2

Return

 Z100: 2.6.8.2.8

Outlet

 Z100: 4.2.2

Procedure reference

 Z100: 2.4.6    Procedure
               definition

Operator reference
(an SDL/GR extension defined in the SDL suite)

 Z100: 5.3.2  Referenced
operator
             in SDL/PR

Gate

 Z100: 6.1.4  Gate
Z100: 2.5.5  Signal list

Note:

The operator reference symbol is not part of the current Z.100 recommendation. It has been added to the SDL Editor as a convenience for the user. It makes operators visible in the SDL structure which is handled by the Organizer and facilitates thus navigating.
The operator reference symbol does not, however, refer to the operator diagram implicitly. References to operator diagrams must be explicitly entered in SDL/PR, as stated in Z.100.

Graphical Properties of Symbols

You can select and move all symbols that are available in the symbol menu, and you can assign the symbols arbitrary locations.

You can resize certain symbols; these are indicated by filled selection squares. Other symbols can only be partially resized or cannot be resized at all1; this is shown by grayed selection squares.

Figure 364 : Resizeable and non-resizeable symbol

No symbol is allowed to overlap any other symbol except the text symbol and the additional heading symbol.

Text / Additional Heading / Package Reference Symbols

The text, additional heading and package reference symbols look like a piece of paper. When all of the text within a text symbol is in view, the upper right corner is "folded" down. When any portion of the text within a text symbol cannot be seen (because the text symbol is too small), the upper right corner is clipped or diagonally cut off. See Figure 364.

Clipped text symbols are printed in their whole on a separate sheet of paper.

Comment / Text Extension Symbols

The comment and text extension symbols can be shown either in full size enclosing the complete text or clipped (collapsed) where the symbol is in the minimum size and only the first part of the text is visible. The clipped symbol is visualized as if the lower right corner has been cut off. See Figure 364.

Block Substructure Symbol

The appearance of this symbol differ from the drawing rules in Z.100. The non editable text "substructure" is drawn inside the symbol. Without this extra text it is impossible to distinguish the block symbol and the block substructure symbol by their visual appearance.

The appearance can be set to be according to Z.100 by the Editor preferences ScreenZ100Symbols and PrintZ100Symbols. Setting these to on means that the extra text will not be drawn or printed.

Symbol Text Attributes

Most SDL symbols have one or multiple text attributes. A text attribute should be filled with an SDL/PR expression (textual expression) that is syntactically correct according to Z.100. Depending on the correctness of the text, the SDL suite tool set has the ability to perform the following operations:

  • Syntactic Analysis
  • Semantic Analysis
  • Pretty-printing
  • Generation of reports
  • Generation of code.

Syntax Checking on Text Attributes

You are not forced by the SDL Editor to fill text attributes with text. However, a context sensitive syntax check is performed for each text attribute. The first located syntax error is indicated by a red bar underlining the text where the error occurs.

A global syntax check for the complete diagram is performed by the SDL Analyzer.

Reference Symbols

Diagram reference symbols allow to build an entire SDL system by referring to diagrams that are structurally related. Reference symbols are the following:

  • Block reference
  • Process reference
  • Block substructure reference
  • Service reference
  • System type
  • Block type
  • Process type
  • Service type
  • Operator reference
  • Procedure reference
  • Text Reference

These symbols are handled by the SDL Editor in order to ensure consistency between the SDL diagrams and the SDL structure that is handled by the Organizer. Because of that, the SDL Editor imposes the restriction that a reference symbol must be unique within an SDL diagram (this restriction is not in conflict with Z.100).

You are permitted to have diagram reference symbols that are not assigned any name.

The SDL Editor performs a number of checks when you edit an SDL reference symbol. Furthermore, when you double-click a reference symbol, the SDL diagram that the symbol refers to will be opened.

See also "Working with Diagram Reference Symbols" .

Instantiation Symbols

You may use any of the following reference symbols for the instantiation of a type:

  • Block reference
  • Process reference
  • Service reference.

An instantiation symbol differs from a "normal" reference symbol in the sense that the syntax of the symbol's text differs. The syntax is:

a:a_type

where a_type is the name of the SDL type diagram (block type, process type or service type diagram) that is instantiated into the diagram with the name a.

Instantiation symbols are visualized in the Organizer structure. The Organizer structure is updated to reflect the nature of the changes applied to the SDL diagram, in a similar fashion as for diagram reference symbols (see "Reference Symbols" ).

The names of instantiation symbols must be unique within an SDL diagram.

See also "Working with Diagram Instantiation Symbols" .

Dashed Reference Symbols

Any of the following reference symbols may be dashed:

  • Block reference
  • Process reference
  • Service reference.

Dashed symbols are visualized in the Organizer structure. The Organizer structure is updated to reflect the nature of the changes applied to the SDL diagram, in a similar fashion as for diagram reference symbols (see "Reference Symbols" ).

The names of dashed reference symbols must be unique within an SDL diagram.

See also "Working with Dashed Symbols" .

Lines

Lines are the graphical objects that interconnect symbols. One line only is available in the symbol box, namely the gate, which is handled as a symbol. You can insert it by selecting it and placing it into the drawing area.

You insert the other lines by selecting a symbol and dragging the handle that appears on the source symbol and connecting it to the target symbol. (Some symbols have multiple handles).

Lines are always connected to symbols, they are not allowed to exist on their own.

Figure 365 : A handle

You can select, move and reshape lines. Some layout work is performed automatically by the SDL Editor.

A line is allowed to overlap any other object.

Lines in Interaction Diagrams

Figure 366 : Lines (1)

Figure 367 : Lines (2)

The following lines are defined in interaction diagrams (see Figure 366 and Figure 367):

  • channels
  • channel substructures
  • signal routes
  • create requests
  • text extension lines
  • comment lines

You can reshape each of these lines and you can also move the connection points.

Lines in Flow Diagrams

Figure 368 : Lines (3)

On flow diagrams, the following lines are defined (see Figure 368):

  • flow lines
  • comment lines
  • text extension lines

Line segments on flow pages always use a 90-degree angle. You can add segments on a line, but connection points are fixed.

Syntax Checking on Lines

The SDL Editor checks that the target symbol is in accordance with the syntactic rules imposed by SDL. If not, the SDL Editor will refuse to connect the symbol. When you edit the text attributes are instantly checked for syntactical errors.

Textual Objects

Textual objects are the textual attributes that are related to a symbol or a line. Each of these attributes is prepared by the SDL Editor - you need of course to fill in their textual contents.

Textual attributes are indicated by a small rectangle which appears upon selection of the symbol or line the attribute belongs to.

You can select and edit textual objects. You can move them freely, as long as their location does not violate the rules defined by Z.100.

Textual objects are allowed to overlap any other objects.

Textual Objects in Interaction Diagrams

The following textual objects are defined in interaction diagrams:

Graphical Appearance
Textual objects

  • Name of a diagram reference symbol
    • Includes the number of instances for a process reference symbol

  • Name of a diagram type reference symbol

  • Name of a diagram instantiation symbol (e.g. inst:blk_type)
    • Names of graphical connection points in diagram instantiation symbol (e.g. CON1)

  • Name of a channel or signal route (e.g. CH)
    • Signal list on a channel / signal route (there are 2 signal lists if the line is bidirectional, e.g. Sig1 and (Siglist))
    • Connection point for channel / signal route to / from environment, e.g. CON

  • Name of a gate, e.g. GA
    • Signal lists on a gate (there are 2 signal lists when the gate is bidirectional, e.g. Sig1 and Sig2)

Textual Objects in Flow Diagrams

In flow pages, the following textual attributes are defined:

Graphical Appearance
Textual objects

  • Decision expressions connected to a decision symbol or transition option, e.g. Expr1 and Expr2.

  • Name of a gate, e.g. GA
    • Signal lists on a gate (there are 2 signal lists when the gate is bidirectional, e.g. Sig1 and Sig2

Graphical Connection Points

Connection points are text objects which are created automatically by the SDL Editor when you draw a channel or signal route to the frame or to an instantiation symbol.

They are handled in a similar way as other text attributes. You are free to fill connection points on the frame or not. The alternative is to define textual connection statements between channels and signal routes in a text symbol.

Change Bars

A change bar is a vertical line to the left of a text in an SDL diagram. It visually identifies changes in the SDL system.

A solid change bar indicates that the text has been changed. A dotted change bar indicates that a text or its associated symbol has been moved.

The change bars associated with the diagram name and the page name act as change bars for the complete page. As soon as a change has been made to a page, change bars for the diagram name and the page name are added.

You can turn change bars on and off and also clear them from the Organizer. See "Change Bars" .

1

The size of non-resizeable symbols is computed by the SDL Editor to fit the text contained in the symbol.


Working with Symbols

The main operations provided by the SDL Editor on symbols is described in this section.

  • Working with Diagram Reference Symbols
  • Working with Diagram Instantiation Symbols
  • Working with Dashed Symbols
  • Selecting Symbols
  • Adding Symbols
  • Inserting a Symbol into a Flow Branch
  • Navigating in Flow Diagrams
  • Navigating from Symbols
  • Cutting, Copying and Pasting Symbols
  • Moving Symbols
  • Resizing Symbols
  • Mirror Flipping Symbols
  • Adjusting Symbols to the Grid
  • Editing the Diagram Kernel Heading.

In addition, text editing functions are provided for the text associated with the symbols.

Working with Diagram Reference Symbols

When you perform certain modifications to the diagram reference symbols listed in the left margin (system type, block, block type, substructure, service, service type, process, process type, procedure and text reference symbols), the SDL Editor checks with the Organizer to verify that the modifications are valid. This occurs in the following situations:

  • Adding a Diagram Reference Symbol
  • Adding an Operator Diagram Reference Symbol
  • Renaming a Diagram Reference Symbol
  • Removing Symbols

Working with Diagram Instantiation Symbols

Instantiating a Diagram Type

The implication of an instantiation symbol is that the description of the type diagram is actually instantiated, i.e. a physical copy is created. This copy may then be given additional properties using SDL's inheritance and specialization mechanisms.

When a diagram type is to be instantiated, do as follows:

  1. Make sure the type diagram is visible according to the SDL scope rules.
  2. Insert a diagram reference symbol. When specifying the name of the symbol, use the syntax <instance_name>:<type_name>.
  3. When the symbol is deselected, the diagram structure is immediately updated to show the instantiation (this is only true if the Instance Diagram option is on in the Organizer's View Options).

Working with Dashed Symbols

Dashing and Undashing a Reference Symbol

Dashed reference symbols are used to refer to an object that is defined elsewhere in one of the supertypes of the current subtype.

To dash a reference symbol:

  1. Select the reference symbol.
  2. Select Dash from the Edit menu.

Selecting Symbols

With the SDL Editor, you often perform actions that apply on a selection. This section discusses topics related to selection of symbols.

Selecting a Flow of Symbols

You often want to select a flow of subsequent symbols in a flow page, including all branches - the tail of the flow. To select a flow of symbols:

  1. Click on the symbol where the flow starts.
  2. Select Select Tail from the Edit menu. The tail of the flow is selected. See Figure 369, where the left picture shows only one selected object and its associated connections, whereas the right picture shows the selected symbol and its connections plus the selected rest of the flow diagram - the Selected Tail.

Figure 369 : Selecting the tail of a subtree

Selecting a Symbol That Has Associated Objects

Consider the following when you select a symbol which has lines or text associated with it:

  • When you select a symbol, you implicitly select the associated objects as well. A text cursor is inserted directly in the text associated with a symbol, and the text window will be updated to contain the text.
  • If you point to a line associated with a symbol, you will select the line, not the symbol. The process of selecting lines is described in "Selecting Lines" .
  • If you point to the text associated with a symbol, the resulting selection depends upon the type of the symbol.

Displaying Selected Symbol Attributes

Selected symbol attributes are displayed as follows:

  • When you select a symbol from which you can draw lines, it is displayed with a handle which you use when drawing lines from that symbol. Handles are shown in Figure 370.

Figure 370 : A selected symbol's handles

  • Text attributes associated with a selected symbol are marked by a rectangle around the text, as shown in Figure 371. For class symbols, this only applies when text attributes contain no text.

Figure 371 : A selected symbol's text attributes

  • In an interaction page, a line is marked by drawing filled selection squares at the line's starting point, ending point, and each breakpoint. In the middle of each line segment is a tiny selection square that provides an easy way to create new breakpoints. See Figure 372.

Figure 372 : The selection squares of a line in interaction pages

  • In a flow page, a selected flow line is marked by drawing filled selection squares in the middle of each line segment. This indicates that you can move the individual line segments (but not the flow line as a whole). See Figure 373.

Figure 373 : The selection squares of a line in flow pages

Adding Symbols

You may place symbols into the drawing area in either manual mode or in automatic mode.

Adding Symbols in Manual Mode

This section describes how to do this in manual mode. The automatic mode is described in "Adding Symbols in Automatic Mode" .

Selecting and Placing a Symbol

  1. Click the symbol in the symbol menu.
  2. Click at the desired location in the drawing area. Overlap of symbols is not allowed.
    The symbol is drawn and adjusted to the symbol grid.

Entering Symbol Text Attributes

Once a symbol has been added, you can enter the text into the symbol's text attributes. The symbol remains selected. Enter the text required directly using the keyboard or edit the text inside the text window.

Connecting the Symbol to Another Symbol

Once the symbol is at the desired location it can be connected to another symbol as required.

To connect two symbols:

Note:

The line will be drawn only when the SDL syntax rules allow the symbols to be interconnected.

  1. Add the source symbol, i.e. the symbol from where you want to draw the line.
  2. Point the mouse onto the handle of the source symbol, and start dragging the handle. As soon as mouse motion has begun, you can release the mouse button. Point to the target symbol and click the mouse button. The line is drawn to the symbol and required text attributes are added to the connecting line. The box without brackets is reserved for the name of the channel, while the box with brackets [ ] is for the signal list.

Figure 374 : Having connected two symbols

  3. Fill in the text attributes.

Conversely, once you have placed a symbol in the drawing area, you can follow the same procedure from a symbol resident in the drawing area to the new symbol.

Connecting the Symbol to the Environment

  1. Hold the mouse pointer on the handle of the symbol, drag it to the frame (environment) and release the mouse button.
  2. Enter text in the channel or signal route and connection point boxes.

    Figure 375 : Having connected the symbol to the environment

Adding Symbols in Automatic Mode

The automatic mode is particularly useful when you want to add symbols sequentially or in parallel in a symbol flow. Both situations are described below.

Adding in Sequence

To add symbols sequentially within a flow page, proceed as follows:

  1. Select the source symbol in the drawing area.
  2. Double-click the target symbol in the symbol menu.
    The target symbol is added to the source symbol, and a flow line is drawn between the two symbols if the syntax rules allow it.
  3. Fill in the text in the target symbol.

The target symbol is positioned directly beneath the source symbol if possible. Otherwise, the added symbol is placed in the first available location to the right.

After this operation, the target symbol is automatically selected and the source symbol is de-selected.

Figure 376 : Adding in sequence

Adding in Parallel

To add symbols in parallel in a flow page:

  1. Select the source symbol in the drawing area.
  2. Press <Shift> and double-click the target symbol in the symbol menu.
    The target symbol is added to the selected symbol. The source symbol remains selected.

You can repeat this procedure in order to add additional symbols to the selected symbol. The target is positioned immediately below the source symbol, if possible. Otherwise, the target symbol is placed in the first available location to the right.

Figure 377 : Adding in parallel

Using Default Placement

You can also take advantage of the auto-placement by double-clicking a symbol without having to connect it to other symbols.

Insufficient Space Left

When you insert a symbol using the double-click facility, there may not be any space left to perform the operation, The SDL Editor informs you of this with a message.

You have the following options:

  • Click OK to increase the page. The Drawing Size dialog will be opened, where you can specify the new size of the SDL Page.
    If you select this method, the SDL page may not fit any longer into the paper that you have set up with the Print preferences. The result may be an SDL page that requires multiple sheets of paper when printing it (unless you rescale it).
  • To Cancel the operation. Try to find a more suitable location for the new symbol and use manual placement (see "Adding Symbols in Manual Mode" ).

Adding a Gate Symbol

The gate symbol differs slightly from other symbols when you add it.

Adding a Gate in Manual Mode

  1. Select the gate symbol.
  2. Move the pointer into the drawing area. The gate is immediately displayed and connected in a 90-degree angle to the frame and the environment.
  3. Move the mouse to a suitable location. The gate symbol follows the mouse motion and is automatically reconnected.
  4. Click the mouse.
  5. Enter the name of the gate and the signals it conveys.

Note: Coalesced Gates and Connection Points

See "Connecting a Gate Symbol with a Channel or Signal Route" if you get a message with the text "A Gate has coalesced with a connection point...".

Adding a Gate in Automatic Mode

You may add and connect a gate to a channel or signal route with a double-click. The channel or signal route must not be already connected to a gate or connection point.

  1. Select the channel or the signal route.
  2. Double-click the gate symbol in the symbol menu.
  3. If required, redirect or bidirect the gate so that it matches the direction of the channel or signal route.
  4. Enter the name of the gate and the signals it conveys.

Adding a Diagram Reference Symbol

When you add a diagram reference symbol, the SDL Editor checks that the name and type are unique within the SDL diagram. The SDL Editor will refuse any duplicates. The newly added reference symbol is then inserted into the Organizer's diagram structure.

  1. Select the symbol to be added from the symbol menu and add it to the diagram.
  2. Type in the name of the symbol.
  3. Deselect the symbol. The SDL Editor checks that the name and type are unique within the SDL diagram being edited.
    If the new reference symbol is accepted, it is inserted into the diagram structure, located beneath the referring diagram.

Adding an Operator Diagram Reference Symbol

In a data type construct it can be stated that an operator diagram is referenced elsewhere. This means that the operator will not be described in the current place, but in an operator diagram.

The SDL Editor does not know that the operator is referenced in a data type. The operator reference symbol is available for this situation. It is a convenience that has been added to the SDL suite tool set to facilitate navigating within an SDL system. Its presence in an SDL diagram does not modify the meaning of the diagram.

You add an operator reference symbol in a similar manner as when adding any other reference symbol. See "Adding a Diagram Reference Symbol" .

Adding a Text Reference Symbol

The Text reference symbol is used to include SDL PR into the SDL system.

You add an operator reference symbol in a similar manner as when adding any other reference symbol. See "Adding a Diagram Reference Symbol" .

Inserting a Symbol into a Flow Branch

The SDL Editor allows you to insert symbols into a flow branch. When inserting symbols, the SDL Editor will rearrange the page in order to prepare the required space for inserting the symbol. This can be done in different ways:

  • By pushing the tail of the branch downwards. This is the preferred method.
  • By increasing the size of the SDL page.

Inserting a Symbol into a Flow Branch

  1. Select the symbol in the symbol menu.
  2. Point to the line interconnecting the symbols where the new symbol is to be inserted.
  3. Click the mouse.

Figure 378 : Inserting a symbol into a flow branch

Inserting a Symbol by Double-Click

To insert a symbol into a flow branch by double-clicking it:

  1. Select the line that interconnects the two symbols. Alternatively you can select the symbol preceding the line, see "Insert Paste" .
  2. In the symbol menu, double-click the symbol to be inserted.

Figure 379 : Inserting a symbol with double-click

Navigating in Flow Diagrams

For certain symbols you can use the Navigate command in the Tools menu or double click on the symbol to navigate around in the diagrams. These symbols are:

  • Create request, procedure call and macro call
  • State and nextstate
  • Inconnector and outconnector
  • Reference symbols; see further "Navigating from a Diagram Reference Symbol"

Note: Navigating from a Class Symbol

Navigating from a class symbol is possible only by using Tools>Navigate. See further "Navigating from Class Symbols"

Navigating from Create Request and Procedure/Macro Call

For a create request, procedure call or macro call the Navigate command will show the corresponding process, procedure or macro diagram. The diagram is found by searching in the Organizer structure for all relevant diagram types matching the name used in the symbol. If one and only one match is found this diagram will be shown in the editor. If there exists more than one diagram a dialog is issued.

Navigate to the desired diagram by selecting it in the dialog.

Navigating from State/Nextstate

For a state or nextstate the Navigate command will show other occurrences of the same name(s) in other state or nextstate symbols within the same diagram. If only one symbol matches the name search this symbol will be shown. If more than one symbol have the same name, a dialog is shown.

Navigating from Connectors

For an outconnector, the Navigate command will show the corresponding inconnector in the same diagram having the same name as the outconnector.

Similarly for an inconnector; you can navigate to all occurrences of outconnectors within the same diagram having the same name as the inconnector.

Navigating from Symbols

Navigating from a Diagram Reference Symbol

When you double-click or choose the Navigate command on a diagram reference symbol, the SDL diagram that the reference symbol refers to is opened, provided that the diagram is included in the Organizer structure.

This feature allows easy navigation down an SDL hierarchy.

See also "Navigating from an Instantiation Symbol" and "Navigating from a Dashed Symbol" .

Navigating from an Instantiation Symbol

You may use instantiation symbols to navigate in the diagram structure.

When you choose Navigate in the Tools menu or double-click on an instantiation symbol, the SDL Editor matches the name of the type referred to in the instantiation symbol against the existing type diagrams in the Organizer structure. The following happens depending on how many type diagrams that match the given diagram name.

  • One and only one diagram is found: This diagram will be shown.
  • No diagram matches the name: A dialog will appear which offers the possibility to open the Type Viewer window which can be used to navigate among the inheritance and redefinition trees extracted from the SDL system:
  • More than one diagram is found: A dialog will appear showing the file names of all the found diagrams. Additionally the possibility to show the Type Viewer window is available.

Navigating from a Dashed Symbol

When you select Navigate in the Tools menu or double-click a dashed symbol, a scenario similar to the action of navigating from an instantiation symbol takes place. See "Navigating from an Instantiation Symbol"

Navigating from Class Symbols

For a class symbol, the Navigate command will show other occurrences of the same name(s) in other class symbols within the same diagram. If only one symbol matches the name search, this symbol will be shown. If several symbols have the same name, a select dialog is shown.

Cutting, Copying and Pasting Symbols

The clipboard of the SDL Editor allows you to cut or copy a selection of symbols. The selection may then be pasted to:

  • The same page
  • Pages of the same diagram, provided the page types match
  • Other diagrams, provided the diagram types match

See also "Cutting, Copying and Pasting Reference Symbols" .

Cutting and Pasting Symbol(s)

A dialog may appear when cutting or pasting an object with link endpoints. See "Deleting an Object" or "Pasting an Object" .

Limitations when Pasting

Note: Effect of Syntax Check when Pasting

Some symbols may not be pasted if the syntax check is on. The clipboard buffer content must comply with the SDL syntax rules. Any symbols which do not comply will be omitted. (The clipboard buffer content may have been copied from a page edited with syntax checking turned off.)

Pasting is not always possible. Note the following cases, and refer to "Relationship between Diagrams and Pages" .

  • The selection cannot be pasted if the page is too small. In this case, you need to enlarge the page. See "Resizing a Page" .
  • You are not allowed to paste symbols so that they overlap existing symbols in the drawing area. If you attempt to do this, the Paste operation is cancelled. Try another suitable location.
  • You are not allowed to paste flow symbols into an interaction page and vice versa. In this situation, the Paste menu choice is dimmed.

Pasting on Flow Pages

On a flow page, symbols are pasted along with the flow lines that interconnect them.

Pasting on Interaction Pages

On an interaction page, symbols are pasted along with the lines that interconnect them. Any lines that connect the pasted symbols to the environment will also be drawn.

Pasting Symbols into a Flow Branch

On a flow page, symbols can be pasted into a flow branch in a similar manner as "Inserting a Symbol into a Flow Branch" .

  1. Copy or Cut one or more symbols in a flow page. The symbols must be connected and placed below each other.
  2. Go to the page where you want to insert the symbols and select a symbol or a flowline.
  3. Select Insert Paste from the Edit menu.
  4. The pasted symbols will be placed below the selected symbol and inserted into the flow branch. Any previously following symbols will be automatically shifted downwards to make place for the inserted symbols.

Cutting, Copying and Pasting Reference Symbols

When you cut or copy a reference symbol, the possible sub-hierarchy shown in the Organizer below this reference symbol is also placed in the clipboard. When pasted in the same diagram or in another diagram this sub-hierarchy will be restored at the new position.

Note:

When a reference symbol is cut, the sub-hierarchy that is shown in the Organizer will be removed. However, the hierarchy will be restored if you select Paste or Undo.

When you copy or paste a diagram reference, it is assigned a new name that consists of the original name, preceded with the prefix CopyOf. The prefix is repeated as many times as necessary in order to build a name / type combination that is unique within the SDL diagram being edited. If the cut/copied symbol had an underlying structure this structure is restored after the paste.

Cutting, Copying and Pasting Class Symbols

When cutting, copying or pasting a class symbol, one or more operators with a defined body code may be completely removed, i.e. there is no longer any class symbol that refers to a specific operator. If so, the following dialog is shown:

Figure 380 : Checking with user if OK to remove operators

You have the following options:

  • Accept the deletion of the listed operators and their defined body code by pressing OK.
  • Cancel the issued operation by pressing Cancel and try to correct the error.

Caution!

By confirming the deletion of the operators, you accept that the listed operators, and possibly defined body codes, will be permanently removed. No Undo option is available.

Moving Symbols

You may move one or more symbols in a single operation. The lines and text objects that are related to the symbol will be moved accordingly in order to preserve as much as possible of the original appearance. When you move a symbol, its position is automatically adjusted to fit exactly into the symbol grid.

Symbols are not allowed to be moved to positions where they would overlap other symbols.

Moving Symbols and Text Attributes

You can move symbols and text attributes by pointing and dragging to the desired position. To grab the text attribute the pointer must be at the border of the text extent.

You cannot move text within flow symbols and class symbols.

Connecting a Gate Symbol with a Channel or Signal Route

When you move a gate symbol in order to reconnect it to a line or vice versa (channel or signal route that is connected to a connection point), the following takes place:

  • If the connection point is not assigned any name, the SDL Editor connects the gate symbol and the line.
  • If the connection point is assigned a name, a conflict occurs, since the line cannot be connected to the connection point and the gate simultaneously. The following dialog is issued:

Figure 381 : Prompting to solve connection conflict

You have the following options:
  • To keep the gate G1 and to connect the line to it. The connection point Conn is removed.
  • To keep the connection point Conn and to connect the line to it. The gate G1 is removed.
  • Click OK to reconnect the line and symbol accordingly.

Note:

The situation above also occurs if you add a new gate symbol and place it on a connection point.

Resizing Symbols

The procedure for resizing a symbol differs slightly depending on whether the symbol is a flow page symbol or an interaction page symbol. When you resize a symbol, its size is automatically adjusted to fit exactly into the symbol grid. Any lines connected to the symbol are similarly adjusted to preserve as much as possible of the original appearance.

The text, the additional heading, the package reference, comment, class, and text extension symbols are handled differently. Their size is determined by the SDL Editor to fit the text they contain.

Specifying Default Size of Symbols

You define the default sizes for symbols in the Preference Manager:

  • For interaction pages, the predefined size of a symbol is 30 * 20 mm.
  • For flow pages, the predefined size of a symbol is 20 * 10 mm. The width / size relationship is always 2:1.

Resizing Interaction Page Symbols

  1. Point to a corner of the rectangle that delimits the symbol. From this point on, the corner that you are pointing to is movable, while the opposite corner is fixed.
  2. Drag the corner until the symbol has the desired size. An interaction symbol cannot be adjusted to a size less than 15*10 mm.
  3. Release the mouse button. The symbol is redrawn with its size adjusted to fit exactly into the symbol grid. The lines connected to a resized interaction symbol are automatically adjusted to preserve a nice appearance.

Resizing Flow Page Symbols.

  1. Point to a corner of the rectangle that delimits the symbol. From this point on, if you pointed to any of the lower corners, the top of the symbol is fixed (and in a similar way, if you were pointing to any of the upper corners, the bottom of the symbol is fixed).
  2. Drag the corner until the symbol has the desired size. The symbol shrinks or swells both horizontally and vertically, the proportions remaining 2:1. A flow page symbol cannot be adjusted to a size less than 20*10 mm.
  3. Release the mouse button. The symbol is redrawn.

Resizing the Class Symbol

The class symbol contains three text boxes. Whenever the text in any of the boxes grows bigger than the symbol, the class symbol is automatically re-sized.

Resizing Text / Additional Heading / Package Reference /
Comment / Text extension Symbols

The text, additional heading and package reference symbol look like a piece of paper. When all of the text within a text symbol is in view, the upper right corner is "folded" down. When any portion of the text within a text symbol cannot be seen (because the text symbol is too small), the upper right corner is clipped or diagonally cut off. See Figure 382.

Clipped text symbols are printed in their whole on a separate sheet of paper.

These symbols react in the same way for resizing. There are several ways you can resize these symbols:

Adjusting to a Specific Size
(only for Text / Additional Heading / Package Reference)

  1. Place the mouse pointer on the filled selection square at the bottom right corner of the symbol.
  2. Holding the left mouse button down, make the symbol smaller by pushing to the left or larger by pulling the corner to the right.

Toggling Between Minimum and Maximum Size

You may rapidly toggle between a text symbol's maximum and minimum size. This can be accomplished in two ways:

  • Select the symbol and choose the Collapse/Expand command in the Edit menu.
  • Double-click on any part of the symbol.

Figure 382 : Minimizing and maximizing a symbol

Mirror Flipping Symbols

The input, priority input, output, comment and text extension symbols are drawn by default as displayed in the symbol menu. In some cases, the layout of the connecting lines would be nicer if the symbols were drawn flipped L/R.

  1. Select the symbol.
  2. Choose Flip from the Edit menu. The symbol is flipped L/R.

Figure 383 : Flipping a symbol

Note:

By using the Preference Manager you can specify whether the output symbol in the symbol menu should point to the left or to the right, or you can have both. The same applies for the input and priority input symbols.

Adjusting Symbols to the Grid

The drawing area of the SDL Editor provides two grids for easier positioning of objects. These are the symbol grid and the line grid, which are invisible.

After you move or resize symbols, the position of the upper left corner of each symbol is positioned on the closest intersection in the symbol grid. In addition, resizing a symbol will adjust the size so that it matches the resolution of the grid, horizontally as well as vertically. The resolution of the symbol grid is variable and can be set with the Preference Manager. The default is 5 * 5 mm for interaction pages, and 25 mm * 15 mm for flow pages.

You can temporarily disable the grid by toggling the Use Grid to off in the Diagrams Options dialog.

Handling Symbols of Different Sizes

Since symbols adhere to the symbol grid, mixing symbols of different sizes may imply that symbols cannot be aligned symmetrically, and that enlarging symbols becomes impossible due to overlap of symbols already laid out.

You can align symbols of different sizes by disabling the symbol grid.

Editing the Diagram Kernel Heading

You can rename, retype and re-qualify a diagram with the SDL Editor, by modifying the diagram's kernel heading.

Figure 384 : The kernel heading

See also "Transforming the Type of a Diagram" for more complicated transformation of diagram types.

The SDL suite accepts a number of syntaxes for kernel headings, 13 in all. See "The Kernel Heading" .

Note:

Changing the kernel heading of a diagram may have a large impact on the diagram's meaning. Also, the SDL diagram structure where the diagram is included may be affected to a large extent. You may, however, want to change the kernel heading in order to create a new diagram that you will use in a different context than the SDL structure it originally is tied to, or in order to perform a simple rename of diagrams.

Changing the Name of a Diagram

This is the bottom-up method you would use when renaming diagrams in an SDL structure.

  1. Select the kernel heading.
  2. In the text window, edit the kernel heading text.
  3. Deselect the kernel heading. The SDL Editor checks that the name is still valid according to SDL rules. Any syntax error will cause a dialog with the following alternatives to be issued:
    • Clicking OK, you are returned to the text window where you should correct the error.
    • Clicking Revert, the kernel heading is reverted to its original contents.
    • Clicking Ignore, the erroneous kernel heading is accepted. The error will probably lead to other kind of error reports, typically when verifying the diagram with the Analyzer tool.
      The Organizer detects that the name of the diagram no longer matches the name that is expected in the diagram structure, and marks the diagram icon as mismatch. (A warning is also added to the Organizer Log window.)
  4. To correct the mismatch, you have to update the name of the reference symbol accordingly. Use the command Edit Reference Page to bring the page with the reference symbol into view. Locate the reference symbol and rename it accordingly.

For renaming diagrams in a top-down fashion., see "Renaming a Diagram Reference Symbol" .

Changing the Type of a Diagram

It is possible to re-type a diagram, provided the old and the new types are "compatible" from the SDL Editor's point of view. The basic compatibility criteria is that the old and new type of diagram must both be interaction diagrams or both be flow diagrams. Also checks are made on the pages that are contained in a diagram (some diagram types are allowed to have different types of pages in the same diagram, see "Relationship between Diagrams and Pages" . The table below summarizes the type changes that are allowed.

case
A diagram of type...
...can be changed to any of:

 SYSTEM

 SYSTEM TYPE
 BLOCK
 SUBSTRUCTURE
 BLOCK TYPE
 PACKAGE

 BLOCK

 BLOCK TYPE
 SYSTEM
 SUBSTRUCTURE
 SYSTEM TYPE
 PACKAGE

 PROCESS

 PROCESS TYPE
 SERVICE
 PROCEDURE
 SERVICE TYPE
MACRODEFINITION
 OPERATOR

 SERVICE

 SERVICE TYPE
 PROCESS
 PROCEDURE
 PROCESS TYPE
MACRODEFINITION
 OPERATOR

 PROCEDURE

 PROCESS
 SERVICE
 PROCESS TYPE
 SERVICE TYPE
MACRODEFINITION
 OPERATOR

 SUBSTRUCTURE

 SYSTEM
 BLOCK
 SYSTEM TYPE
 BLOCK TYPE
 PACKAGE

 MACRODEFINITION

 PROCESS
 SERVICE
 PROCEDURE
 PROCESS TYPE
 SERVICE TYPE
 OPERATOR

 SYSTEM TYPE

 SYSTEM
 BLOCK
 SUBSTRUCTURE
 BLOCK TYPE
 PACKAGE

 BLOCK TYPE

 SYSTEM
 BLOCK
 SUBSTRUCTURE
 SYSTEM TYPE
 PACKAGE

 PROCESS TYPE

 PROCESS
 SERVICE
 PROCEDURE
 SERVICE TYPE
MACRODEFINITION
 OPERATOR

 SERVICE TYPE

 SERVICE
 PROCESS
 PROCEDURE
 SERVICE TYPE
MACRODEFINITION

 OPERATOR

 PROCESS
 SERVICE
 PROCEDURE
 PROCESS TYPE
 SERVICE TYPE
MACRODEFINITION

 PACKAGE

 SYSTEM
 BLOCK
 SUBSTRUCTURE
 SYSTEM TYPE
 BLOCK TYPE

To change the type of a diagram:

  1. Select the kernel heading.
  2. In the text window, edit the kernel heading text to apply a new type. See the table above for allowed transformations.
  3. Deselect the kernel heading. The SDL Editor checks that the type is still valid according to the table above. Any violation of these rules will cause a dialog with the following alternatives to be issued:
    • Clicking OK, you are returned to the text window where you should correct the error.
    • Clicking Revert, the kernel heading is reverted to its original contents.
    • Clicking Ignore, the erroneous kernel heading is accepted. The error will probably lead to other kind of error reports, typically when verifying the diagram with the SDL Analyzer.

Changing the Qualifier of a Diagram

By changing the qualifier that appears in the kernel heading, you can change the context of the diagram.

The SDL suite accepts the two Z.100 notations for a qualifier, namely with and without the surrounding "<< >>".

Example 303 : An SDL Qualifier

PROCESS TYPE <<SYSTEM MYSYS/BLOCK MYBLOCK>> Myproc

Alternatively:

PROCESS TYPE SYSTEM MYSYS/BLOCK MYBLOCK Myproc

To change the qualifier:

  1. Select the kernel heading.
  2. In the text window, edit the kernel heading text to apply the new qualifier.
  3. Deselect the kernel heading. The SDL Editor checks that the new qualifier is syntactically correct. Any syntax error will cause a dialog with the following alternatives to be issued.
    • Clicking OK, you are returned to the text window where you should correct the error.
    • Clicking Revert, the kernel heading is reverted to its original contents.
    • Clicking Ignore, the erroneous kernel heading is accepted. The error will probably lead to other kind of error reports, typically when verifying the diagram with the SDL Analyzer.

Renaming a Diagram Reference Symbol

When you change the name of a diagram reference symbol, the SDL Editor checks that the new name is not in conflict with existing symbols. If the reference symbol passes this check, the Organizer structure is updated accordingly.

When renaming diagrams in a top-down fashion, you start by changing the name of a reference symbol. After the reference symbol is renamed, you should also update the referenced diagram's kernel heading accordingly to maintain consistency in the diagram structure.

To rename a diagram reference symbol and the referred diagrams:

  1. Select the symbol to be renamed.
  2. Change the name of the reference symbol.
  3. Deselect the symbol. The SDL Editor checks that the name and type are still unique within the diagram.
    If the new name of the reference symbol is accepted, the diagram structure is updated to reflect the nature of the change.
  4. To ensure that the change also applies to the referred diagram, you should use the Organizer command Update Headings (see "Update Headings" ). This command verifies and possibly changes the name in the diagram kernel heading against the expected name (which is the one that now is shown in the reference symbol). The mismatch between the name of the diagram is reported in a dialog:

Figure 385 : The mismatch in headings is reported

    • Correct the mismatch by clicking Update.
      Note that if you select not to update the kernel heading, you simply postpone the problem.

For renaming in a bottom-up way, see "Changing the Name of a Diagram" .

Removing Symbols

When you remove a diagram reference symbol, the underlying structure is also removed from the Organizer structure. However, the hierarchy will be restored if the remove operation is restored by doing Undo.

  1. Select the symbol(s) to be removed.
  2. Select Clear from the Edit menu. The symbol(s) are removed, as well as the lines that were connected to these symbols.

Printing Symbols

A selection of symbols can be printed. This allows for instance to print only the portion of a diagram which is of interest.

  1. Select the symbols to be printed.
  2. Select Print from the File menu.
  3. In the Print Dialog, click the Setup button. The Print Setup dialog will be issued. In the dialog, select the Print only selected symbols option.
  4. Adjust, if necessary, other Print options and click the OK and Print buttons. See "Printing a Diagram" for more information.


Working with Lines

The main operations provided by the SDL Editor on lines, and their associated text attributes are:

  • Selecting Lines
  • Drawing Lines
  • Re-Routing and Reshaping Lines
  • Redirecting and Bidirecting Lines
  • Adjusting Lines to the Grid

In addition, text editing functions are provided for the text associated with the lines.

Operations on lines are performed slightly different depending if you are editing

  • flow pages
  • interaction pages

The main difference between the two is that flow pages may only allow vertical and horizontal lines.

Some restrictions also apply when connecting symbols in flow pages, depending upon whether or not the syntax checking is enabled

Selecting Lines

You select lines and extend and reduce selections of lines with standardized selection commands.

Selecting a Line That Has Associated Objects

When you select a line, you implicitly select the associated attributes as well. To be able to edit a text attribute you must click on the text attribute and a text cursor will be inserted directly in the text, at the same time the text window will be updated to contain the text.

Displaying Selected Line Attributes

Selected line attributes are displayed as follows:

  • Each text attribute is displayed inside a text selection rectangle.
  • The following attributes are displayed with a filled selection square:
    • Each arrow (on interaction pages only)
    • Each line breakpoint (on interaction pages only)
    • The middle of each line segment (on interaction pages only a tiny selection square marks the handle to create a new breakpoint)
    • The middle of each line segment (on flow pages only)

Selecting Overlapping Objects

On a page, objects may overlap each other. A layer order is defined so that it is possible to determine how overlapping objects are stacked.

Drawing Lines

This section describes how to interconnect symbols with lines. Two modes are supported in the SDL Editor.

Drawing a Line with Layout Syntax Checking Enabled

The way that you draw a line differs somewhat depending upon whether you are working on an interaction page or a flow page. The differences will be pointed out later in this section.

When syntax checking is enabled, you are only allowed to draw lines that are correct according to the SDL rules. When syntax checking is disabled, the rules are less strict.

Designating the Start Point

  1. Select the symbol from which the line will originate.
  2. Point to the handle and drag it to begin forming the line. The line that is formed ends where the mouse pointer is located. Note that the mouse button can be released as soon as you have moved the mouse pointer.

Designating the End Point

  1. Designate the start point. See previous section.
  2. You can route the line and specify where it will end either automatically or manually.
  3. To route the line automatically:
    • Click any valid target symbol to specify where the line should end.
      A symbol is valid if the syntax rules enforced by the SDL Editor at edit-time allows the drawing of a line from the first symbol to the second symbol.
  4. To route the line manually, indicating where line breakpoints are to be inserted, follow the steps below.
  5. To enter manual mode, click any location in the drawing area other than a valid destination symbol.
  6. Click each location where you want to insert a line breakpoint.
  7. Click on a valid destination symbol.
    As long as you do not point to a valid destination symbol, the line will be routed from the selected symbol to the current mouse position. The automatic line drawing facility will determine the layout of the line until you have inserted the first breakpoint.

Figure 386 : Drawing a line in manual mode

Drawing Multiple Lines

When you draw lines between symbols and keep the <Control> key pressed, the start point for the next line to draw is automatically transferred to the target symbol.

This feature provides the easiest way to draw multiple lines in rapid succession.

Differences between Flow and Interaction in Line Drawing

The way that you draw a line differs somewhat depending upon whether you are working on an interaction page or a flow page:

  • On an interaction page, you can draw lines in all possible directions.
  • On a flow page, you can only draw lines horizontally or vertically. The last line breakpoint, even if determined manually, will be adjusted so that the destination symbol is connected correctly, normally in the middle of the upper edge of the symbol. Exceptions are made for comment and text extension symbols, which are connected to the center of the right or left edge of the symbol.

Cancelling the Line Drawing Operation

You can cancel a line drawing operation in either of the following ways:

  • Press <ESC>.
  • Double-click any part of the drawing area that is not a valid destination symbol.

Drawing a Line with Layout Syntax Checking Disabled

The process of drawing a line is the same regardless of whether or not syntax checking is enabled. To enable and disable syntax checking, see "Turning Syntax Checking On and Off" .

When drawing lines with syntax checking disabled, you may interconnect symbols in any way you want.

Re-Routing and Reshaping Lines

Reshaping a line refers to changing the path that the line follows. This operation does not affect the endpoints of the line. The flow lines only move in either a horizontal or vertical way.

Re-routing a line denotes changing the ending point of the line from one symbol to another symbol.

Reshaping a Flow Line

  1. Point to one of the segments of the line.
  2. Press the mouse and, holding down the mouse button, drag the segment to the required position.
  3. Release the mouse button.

Re-Routing a Flow Line

You can move the ending point of a flow line, and reconnect it to any valid destination symbol. You can redraw the line either manually or automatically.

To move a line's ending point:

  1. Point at the ending point that you want to reconnect.
  2. Press the mouse. Start dragging the ending point. As soon as you move the mouse, the line's last segment follows the mouse motion and you can release the mouse button.
  3. You can click additional line breakpoints where you like.
  4. Click the destination symbol to complete the operation. If it is a valid symbol, the line will be re-routed automatically.

Re-Routing an Interaction Line

You can move any starting or endpoint to and from a symbol and the environment.

  1. Point to the starting or ending point of the line.
  2. Press the mouse and, holding the mouse down, drag it to the desired symbol.
  3. If required, click to add line breakpoints at desired positions.
  4. Terminate by clicking on the new symbol. The line is redrawn accordingly.

Moving an Interaction Line Breakpoint

To move a line breakpoint in an interaction page:

  1. Point to the breakpoint that you want to move.
  2. Press the mouse and drag the breakpoint to the desired location.
  3. Release the mouse button to redraw the line.

Figure 387 : Moving an interaction line breakpoint

Inserting Breakpoints in an Interaction Line

  1. Point at the middle of a line segment. When the line is selected a tiny selection square will be displayed at this point.
  2. Press the mouse and drag it to shape the breakpoint.

An alternative way to insert breakpoints on an interaction line:

  1. Press <Ctrl>
  2. Point in a line segment where you want to insert a new breakpoint.
  3. Press the mouse and drag it to shape the breakpoint.
  4. Release the <Ctrl> key.

Moving an Interaction Line Segment

You can move a line segment in an interaction page as long as it is not a starting segment or ending segment.

  1. Point to the line segment to be moved.
  2. Press the mouse and drag the line segment to the desired location.
  3. Release the mouse button. The line segment and the adjacent line segments are redrawn accordingly.

Moving Arrows

Arrows on channels, gates and signal routes denote the orientation of flow on that line. They are assigned default locations when creating the line.

You can manually move arrows on channels along the line.

  1. Point to the arrow.
  2. Press the mouse. Still holding the mouse down, drag it until the arrow reaches the new place.
  3. Release the mouse. The arrow and the signal list are redrawn accordingly.

To create a non-delay channel you simply drag the arrow to the starting or ending breakpoint.

Moving a Line and Its Connection Point

A channel or a signal route may be connected to a connection point (usually located close to the line, immediately outside the frame).

Figure 388 : A signal route connected to a connection point.

Moving the line's ending point with the connection point unselected will move the line only and create a new connection point. The old connection point is removed.

To move the line and the connection point:

  1. Click on the ending point of the line. Make sure the connection point is selected (i.e. the selection rectangle appears).
  2. Drag the line's ending point to the new location. The connection point follows the mouse motion as well.
    • If the line's new ending point coincides with a gate symbol and the connection point has a name, a dialog is issued. The meaning of this message is described in "Connecting a Gate Symbol with a Channel or Signal Route" .

Moving a Line Text Attribute

A line text attribute is a textual element that is related to a line. The following lines have associated text attributes:

  • Gates
  • Channels
  • Signal routes
  • Flow lines after decision, transition option and macro call symbols.

When drawing a line, the SDL Editor positions the text attribute close to the source symbol and originating line, so that it is easy to identify what line the text attribute is related to. You are however free to move the text attribute to any location in the drawing area within the frame.

To move a line text attribute:

  1. Point to the border of the text attribute.
  2. Press the mouse, and, still holding the mouse down, drag the text attribute to its new location.
  3. Release the mouse button.

Redirecting and Bidirecting Lines

When you add a channel or signal route to an interaction diagram, the line is initially drawn in a uni-directional manner, originating from the source symbol and pointing to the target symbol.

The only way to draw a line from the environment to a symbol is to first draw it from the symbol and then redirect it.

Redirecting a Line

  1. Select the line
  2. Choose Redirect from the Edit menu. The line is redirected.

Figure 389 : Redirecting a line

Bidirecting a Line

  1. Select the line.
  2. Choose Bidirect from the Edit menu. The line is bidirected.
  3. Fill in the second signal list.

Figure 390 : Bidirecting a line

Uni-Directing a Bidirected Line

  1. Select the bidirected line.
  2. Choose Unidirect from the Edit menu. A dialog will appear asking what arrow to keep.

Adjusting Lines to the Grid

When you move or reshape interaction lines, the line breakpoints are adjusted to the line grid, which cannot be disabled and has a fixed resolution of 2.5 mm.

Flow line segments and line text attributes are always placed so that they match the resolution of the line grid.


Working with Classes

This section describes how Classes are handled graphically.

The class symbol is a graphical syntax for defining SDL data structures, instead of writing textual newtype definitions. It is allowed in every diagram where textual data definitions are allowed.

When analyzing the SDL specification, class symbols are translated to standard textual newtype definitions, that are used as input to the analyzer.

It is important to notice that, in a diagram, all class symbols with the same class name are treated as if they were a single, merged class. Thus two classes, both named "a_class" but defining two separate operators, would be the same as a single class named "a_class", defining both operators.

While attributes and operators may be defined and edited in the SDL Editor directly, they may also be edited in the Browse&Edit Class dialog, see "Browse & Edit Class Dialog" .

The complete definition of all classes may be viewed in the Browse&Edit Class dialog, but also, in SDL/PR form, in the Class information dialog. The Class Information dialog may also be used for traversing among the classes that define the SDL/PR code, see "Class Information" .

Note:

Both the Browse&Edit Class dialog and the Class Information dialog present the aggregate of all graphical class symbols with the same class name.

Class Information

The complete class may be presented in textual (SDL/PR) form. This is done in the read-only Class information dialog.

The dialog can be started from the Windows menu, and will also be started automatically in response to a Show symbol request concerning a class, e.g Show Error from the Organizer Log. Since the sum of all class symbols with the same name is a single class, some information may be duplicated. The PR-representation of an error is shown in the class information dialog, and it will be possible to navigate to the symbol(s) that generated the PR-code.

Figure 391 Class Information window

Buttons:

  • Show Next Symbol shows the next symbol described by the PR code line on which the cursor is placed. The number within brackets shows the total number symbols in the current SDL diagram that that are described by this line. If a line does not refer to any particular symbol, Show Next Symbol shows the next symbol belonging to the current class. Each time Show Next Symbol is clicked, the next symbol that is described by the current line is shown.
  • Edit Class will show the Browse & Edit Class dialog for the current class.

If the cursor is moved to another line in the text area, the Show Next Symbol button is updated.

Browse & Edit Class Dialog

The Browse & Edit Class dialog is opened when you select Class... from the Edit menu. The dialog allows inspection of classes in the SDL diagram.

A class is defined as the union of attributes and operators in the class symbols, and the purpose of the Browse & Edit Class dialog is to display this union and ensure consistency when editing this combined information.

The Browse & Edit Class dialog is a modal dialog, which is divided into two parts. The browsing functionality is placed at the top part of the dialog, where all classes in the diagram, and all occurrences of each class, are listed in two drop-down menus. Below, in the editing part, the name of the class, its attributes and all its operators are listed.

The Browse & Edit Class dialog is available when a single class symbol is selected, unless the class name contains incorrect syntax.

Browse

In the topmost part of the Browse & Edit Class dialog, you can browse all class symbols within the current diagram.

Edit

In the lower part of the Browse & Edit Class dialog, you can edit the name, attributes and operators of a class. Any changes will propagate into all class symbols of this class within the SDL diagram. The attributes and operators will be presented in a list. This list contains parsed information, derived from the texts in the class symbols. If a particular text contains syntax errors, attributes and operators contained in the same text might be missing from this list.

Figure 392 : The Browse & Edit Class dialog

The Scope Label

The Scope label is a non-editable text field, indicating which SDL diagram the Browse & Edit Class dialog operates on.

The Classes Drop-Down Menu

The Classes drop-down menu lists all classes within the current SDL diagram. When a class is selected from this menu, its attributes and operators are displayed in the editing part of the dialog.

The Show Symbol in Option Menu

A class can be represented by several class symbols. The Show Symbol in drop-down menu lists the name of all pages with occurrences of the current class (the current class is displayed in the Classes drop-down menu). By selecting a page name in this menu, the corresponding page will be shown in the work area.

The Class Name Field

The Class Name field is an editable text field, containing the name of the class being edited.

When the OK button is clicked, changes to the Class Name field update all occurrences of the class name in all class symbols, within the current SDL diagram.

The External Check Box

The External check box is checked when a class is externally defined. This means that no PR code will be generated for this class.

When the OK button is clicked, changes to the External check box update all occurrences of the external flag, in all relevant class symbols using the current class name, within the current SDL diagram.

The Attributes and Operators Buttons

The Attributes and Operators buttons are used to select the contents of the attributes/operators list. Clicking Attributes will list all attributes defined for the selected class, while clicking Operators will list all operators.

The Attributes/Operators List

The Attributes/Operators list lists all attributes or all operators defined for the selected class.

The Clear Button

The Clear button is used to remove the attribute or operator currently selected in the Attributes/Operators list.

When the `OK' button is clicked, the selected attribute or operator is removed from all relevant class symbols with the current class name, within the current SDL diagram.

The Name Field

The Name text field contains the name of the attribute or operator currently selected in the Attributes/Operators list, if any.

When the OK button is clicked, changes to the definition of the attribute or operator are applied to all relevant class symbols with the current class name, within the current SDL diagram

The Parameters Field

The Parameters field is an editable text field, containing the parameters of a class operator. It is only editable when an operator is selected in the Attributes/Operators list.

When the OK button is clicked, changes to the parameter list are applied to the definition of that operator in all relevant class symbols with the current class name, within the current SDL diagram.

The Sort/Returnsort Field

The Sort/Returnsort field is an editable text field that is editable only when an attribute or an operator is selected in the Attributes/Operators list.

Depending on the selection, the field contains:

  • the sort of the selected attribute,
  • or the return sort of the selected operator.

When the OK button is clicked, the sort of the selected attribute, or the return sort of the selected operator, is updated in all relevant class symbols with the current class name, within the current SDL diagram.

The Body Code Text

The Body Code field is a text field, containing the body code of a class operator. It is only editable when an operator is selected in the Attributes/Operators list.

The declaration part of the body code is automatically generated, and all code should be added between the two comments indicating start and end of the user defined part, respectively. The comments themselves should never be edited. For example, the operator myOp:Boolean; will have the following default declaration:

operator myOp returns Boolean {
/* Start of user defined body code */
/* End of user defined body code */
}

When the OK button is clicked, changes to the body code definition are applied to the operator in the class with the current class name, within the current SDL diagram.

The OK Button

The OK button closes the Browse & Edit Class dialog, and updates all appropriate class symbols in the current SDL diagram.

No changes are made in the diagram until the OK button is clicked. This makes it possible to specify several changes in the dialog and disregard them later, by clicking the Cancel button.

All values are syntactically checked, so it is not possible to add syntax errors to your classes by using the Browse & Edit Class dialog. This might make it impossible to delete syntactically incorrect text from class symbols using the Browse & Edit Class dialog, since the dialog relies on information obtained by parsing the relevant symbol text compartments. A syntactically incorrect text must then be corrected by editing individual symbols.

Once the OK button is clicked, changes cannot be undone.

The Cancel Button

The Cancel button will close the Browse & Edit Class dialog and discard any changes specified in the dialog.

Syntax and Definition of Class Symbols

Name

Figure 393 Class symbol

The syntax for the name field is <SDL_name>, where <SDL_name> is a name in accordance with the SDL lexical rules.

The above class symbol will generate the following newtype definition.

newtype Person
endnewtype;
newtype Ref_Person Ref(Person); endnewtype;
newtype Own_Person Own(Person); endnewtype;
newtype Oref_Person Oref(Person); endnewtype;

The three pointertypes, Ref_Person, Own_Person and Oref_Person, are generated for use when creating associations and aggregations.

Attributes

Figure 394 Class symbol with attribute

The syntax for the attribute field is <name><sort><end>, where <name> and <sort> are names in accordance with the SDL lexical rules.

The above class symbol will generate the following newtype definition.

newtype Person struct
i Integer;
endnewtype;
newtype Ref_Person Ref(Person); endnewtype;
newtype Own_Person Own(Person); endnewtype;
newtype Oref_Person Oref(Person); endnewtype;

Operators

Figure 395 Class symbol with operator

The syntax for the operator field is <name>[`(`<par>{`,'<par>*')'][<returns><sort>]<end>

where <par> is defined as

[<kind>]<name>[<colon>]<sort>

and <kind> is defined as

`in'|'in/out'

The above class symbol will generate the following newtype definition.

newtype Person
operators
op: Integer -> Integer;
endnewtype;
newtype Ref_Person Ref(Person); endnewtype;
newtype Own_Person Own(Person); endnewtype;
newtype Oref_Person Oref(Person); endnewtype;

Syntax and Definition of Association Lines

Figure 396 Association line

The syntax for the role name of an association is [<name>][<constraint>], where <constraint> is in the format `{`name'}'.

Associations can be of a number of types, depending on the constraint:

  • if there is no constraint, the type is Ref_<opposite_class_name>
  • if the constraint is "own", the type is Own_<opposite_class_name>
  • if the constraint is "oref", the type is Oref_<opposite_class_name>
  • if there is a constraint, but not "own" or "oref", the type is <constraint_name>.

The above association will generate the following newtype definition.

newtype Company struct
e Ref_Employee;
endnewtype;
newtype Ref_Company Ref(Company); endnewtype;
newtype Own_Company Own(Company); endnewtype;
newtype Oref_Company Oref(Company); endnewtype;
newtype Employee
endnewtype;
newtype Ref_Employee Ref(Employee); endnewtype;
newtype Own_Employee Own(Employee); endnewtype;
newtype Oref_Employee Oref(Employee); endnewtype;

Syntax and Definition of Aggregation Lines

Figure 397 Aggregation line

The above aggregation will generate the following PR code.

newtype Company
a Ref_Division;
endnewtype;
newtype Ref_Company Ref(Company); endnewtype;
newtype Own_Company Own(Company); endnewtype;
newtype Oref_Company Oref(Company); endnewtype;
newtype Division
endnewtype;
newtype Ref_Division Ref(Division); endnewtype;
newtype Own_Division Own(Division); endnewtype;
newtype Oref_Division Oref(Division); endnewtype;


Working with Pages

This section describes the more important aspects of page handling.

Each diagram page must have a unique name for identification purposes. This name must be correct in accordance with the naming convention for pages in SDL. Each diagram must contain at least one page, and there is no maximum amount of pages that a diagram may contain.

The autonumbering facility available for pages relates to automatically updating the sequential numbering when pages are added or deleted.

When diagrams are opened, the default way of presentation is that the first page of the requested diagram is shown (first in accordance to the order in which pages have been added). This default can be overruled, and you can go directly to a specific page that has been predetermined.

Most of the page managing functions are available through the menu choices on the Pages menu.

A number of functions are available through the Edit menu choice in this menu:

  • Ordering Pages
  • Naming Pages
  • Adding a Page
  • Renaming a Page
  • Clearing (Deleting) a Page
  • Pasting a Page
  • Transferring to a Page
  • Printing a Page
  • Resizing a Page

Other page functions are also available in the SDL Editor:

  • Applying Autonumbering on Page Names
  • Removing Autonumbering on Page Names
  • Designating the Page to Open
  • Transferring to a Specific Page
  • Transferring to the Referring Page
  • Transferring to the Next or the Previous Page
  • Transferring to the First Page
  • Transferring to the Last Page

Ordering Pages

Within an SDL diagram, page locations are set according to the order in which they are added (see "Adding a Page" ). This order is reflected in:

  • The Organizer structure
  • The listing order for pages in the Edit Pages dialog

To re-order pages, you use the Cut and Paste button.

Naming Pages

Whenever you name a page, the names that you use must strictly adhere to SDL naming conventions. If you use unacceptable notation (e.g. blank spaces or a semi-colon), you receive a message.

Applying Autonumbering on Page Names

If autonumbering is required, a feature can assign numeric names to the pages in the diagram. The page names will be assigned 1, 2, 3 and so forth.

  1. Select Edit.
  2. Select the page to autonumber in the page list.
  3. Toggle the Autonumbered toggle button to on in the Edit Pages dialog. You are then prompted if you want to autonumber the selected page only or all pages in the dialog which is issued.

    • If you click Yes, the SDL Editor assigns the page name the highest assigned numeric value + 1. You are then returned to the Edit Pages dialog.
    • If you click All Pages, all pages will be assigned numeric names, starting with 1. The numbering will follow the listing order in the page list. You are then returned to the Edit Pages dialog.

Removing Autonumbering on Page Names

The autonumbering feature can be turned off. This must for instance be done if you want to assign a specific name to a page.

  1. Select Edit.
  2. In the page list, select the page to remove autonumbering on.
  3. Toggle the Autonumbered toggle button to off in the Edit Pages dialog. You are then prompted to confirm the operation in the dialog which is issued.
    • Clicking Yes transfers you to a Rename Page dialog where you assign the page a new name. Autonumbering is removed.

Adding a Page

To add a page to an existing diagram:

  1. Select Edit.
  2. In the list of existing pages, select the page to precede or succeed the new page to be added.
  3. Click the Add button. The Add Page dialog is issued.

A faster way to add a page before or after the current page is to select the Add menu choice directly. In this case, the Add Page dialog is issued directly.

In the Add Page dialog:

  1. Enter the required page name in keeping with SDL conventions (the name must be unique within the diagram). Otherwise, select Auto-numbered if you want the pages to be automatically renumbered to incorporate the new page.
  2. Select the position of the new page - before or after the current page.
  3. Select the type of page required. The dialog box automatically shows the page options that are available to you under SDL rules.
  4. Click OK. Control is returned to the Edit Pages dialog.
  5. Click Done.

Designating the Page to Open

When a diagram is opened without specifying a particular page, the default is that it is opened at the first page that has been added to the diagram, showing the upper left part of the page.

You can however open a diagram at a specific page in the SDL Editor.

To specify the page to be opened first:

  1. Bring up the Edit Pages dialog.
    The Open this page first field, below the toggle button, reflects the page to be opened first (page 1 in Figure 398).

Figure 398 : Specifying what page to open first

  2. To specify another page, select the page to be opened first in the Edit pages dialog.
  3. Turn the Open this page first button on. The identification of the page to be opened is then placed under the Open this page first button.
  4. Click Done.

Renaming a Page

  1. Select Edit.
  2. Select the page to rename.
    • To rename an auto-numbered page, first click the Autonumbered button off. Autonumbering is removed on the selected page and the Rename Page dialog is issued. Go to step 4.
  3. Click the Rename button. The Rename Page dialog is issued.
  4. Fill in the required new name in keeping with SDL naming conventions. Page names must be unique within the diagram. For block and process diagrams, an option is available to also change the page type.
  5. Click OK. Control is returned to the Edit Pages dialog.
  6. Click Done.

Clearing (Deleting) a Page

If there is only page in a diagram, you cannot remove it. A message is then shown.

Caution!

Clear pages with caution as there is no Undo option available.

  1. Select Edit.
  2. Select the page to be deleted in the page list.
  3. Click on the Clear option and then on Clear to delete the page.
  4. Click Done.

Pasting a Page

  1. Open the SDL diagram where to paste the page.
  2. Select the Edit menu choice.
  3. In the list of existing pages, select the page to precede or succeed the new page to be pasted. Click the Paste button. The Paste Page dialog is issued.
  4. Enter the required page name in keeping with SDL conventions (the name must be unique within the diagram). Otherwise, select Autonumbered if you want the pages to be automatically renumbered to incorporate the page to be pasted.
  5. Select where to paste the page - before or after the current page.
  6. Click Paste. Control is returned to the Edit Pages dialog.
    If there are reference symbols on the pasted page all the underlying substructure is also pasted. See "Cutting, Copying and Pasting Reference Symbols" .
  7. Click Done.

Transferring to a Page

There are several ways to transfer to another page of the current diagram. When you transfer to a page, it will be placed on the top of the stack in the window if you are using one window only. Otherwise, that page will be displayed in a window of its own.

Transferring to a Specific Page

  • Transfer to a page, located not further than two pages from the current page, by selecting that page in the Pages menu.
  • In the Edit Pages dialog, transfer to a page by clicking on the required page and then click on the Edit button.
    • Alternatively, double-click the page icon in the Organizer.

Transferring to the Referring Page

To transfer to the page where the current page is referenced from (i.e. where the SDL reference symbol referring to the current diagram is located):

  • Select Edit Reference Page from the Pages menu or the Reference Page quick-button.

Transferring to the Next or the Previous Page

You may transfer to the next or previous page in the diagram. The order is specified according to the listing order in the Edit Pages dialog.

To transfer to the next or previous page:

  • Use the quick-buttons for Previous Page or Next Page.

Transferring to the First Page

Select First from the Pages menu. You are transferred to the first page of the diagram.

Transferring to the Last Page

Select Last from the Pages menu. You are transferred to the last page of the diagram.

Printing a Page

The SDL suite allows to print individual pages from the SDL Editor. You can also restrict the scope of printing to a part of the page. A number of options which affect the resulting printout are possible to specify.

Resizing a Page

  1. Transfer to the page to resize.
  2. Select Drawing Size from the Edit menu. A dialog is issued, showing the current width and height.
  3. Type in the new values. Click OK.

Note:

If you enlarge a page so that the page size becomes wider or larger than the physical page size defined in the Print Options, your printouts will require more pages than before, if you use a fixed printout scale.


Working with Windows

Each SDL Editor window shows one SDL page. The SDL Editor is a multi-window tool, allowing you to open new windows on a page and close windows that are no longer needed.

A newly opened window is a mirror image of the window from which the selection to open a window was made. Multiple windows may be opened (one at a time) and they are all identical with the first one. Any subsequent modifications made will reflect the same in either the original window, or any of the newly opened window(s). This option affords the possibility of viewing in more than one window, and can ideally be used in conjunction with the scaling factor when looking at a detailed page.

For information on how you open:

  • The Grammar Help Window, see "Opening the Grammar Help Window" .
  • The Signal Dictionary Window, see "Opening the Signal Dictionary Window" .

Opening and Closing Windows

Standardized functions for opening and closing windows are provided in the Window menu: New Window and Close Window. If you close the last window opened by the SDL Editor, the editor will exit.

Hiding and Showing Parts of the SDL Editor Window

You can show and hide the various component parts of the SDL Editor window. On UNIX, if they are hidden, it increases the drawing area available to be used in the creation or modification of pages of a diagram.

You find all the available options for hiding and showing parts of the window in the dialog box accessed via the Window Options command on the View menu. You can set all of these options as preferences.

All of these options are turned on and off with a toggle button. Some of these options are available with quick-buttons:

  • The quick-button for text window on / off or symbol menu on / off.

    • If you click All Windows it applies the values to all instances of the SDL Editor windows.


Editing Text

General

There are several ways of editing text in the SDL Editor, i.e.

  • In the drawing area
  • In the text window
  • In an external text editor

Two support functions are provided, namely:

  • Grammar Help, see "Using Grammar Help" .
  • Signal Dictionary, see "Using the Signal Dictionary" .

Editing in the Drawing Area and Text Window

The SDL Editor allows you to edit textual objects directly in the drawing area.

If you select a text attribute to an object in the SDL Editor window, a text cursor is inserted directly in the text associated with the object, and the text window will be updated to contain the text. This is explained in "Selecting a Symbol That Has Associated Objects" and "Selecting a Line That Has Associated Objects" .

When you type text in the drawing area, all accelerator keys are interpreted as input to the text. As an example, the <Delete> key will in text editing mode delete a character, but in non-text editing mode it will remove (Clear) an entire symbol. This means that you can only use text editing keyboard accelerators like <Home>, <End>, <Ctrl+A> and <Ctrl+E> in text editing mode.

When editing text directly in the drawing area it is possible to select text by dragging the mouse over the text or select words by double-clicking. You can extend or reduced the selection by clicking while pressing the <shift> key.

To edit large texts it might be more convenient to use the Text Window to edit the text. If you select more than one text object, the text window is not updated. Each line (except for the last line) in the text window is terminated by a carriage return, and may consist of any number of legal characters.

Regardless of whether you edit directly in the drawing area or in the text window, the SDL Editor makes sure that the contents of both displayed texts are consistent.

A context sensitive syntax check is performed on all texts being edited. If a syntax error is found a red bar underlining the text will appear where the first error occurs in the text. See also "Syntax Rules when Editing" .

You can also edit text in an external text editor by using the Connect to Text Editor command in the Tools menu. This allows you to use the Text Editor, the Emacs text editor (on UNIX) or MS Word (in Windows) to edit large pieces of text.

The SDL Editor also supports editing text outside its context, by transferring text to / from a file.

Text Window

On UNIX, the text window is a pane of the SDL Editor window.

In Windows, the text window is a floating, resizeable and moveable window that can be placed anywhere on the screen. A single text window is shared by all instances of the SDL Editor currently running.

The text window contains two menus described in:

  • "The File Menu of the Text Window"
  • "Edit Menu"

Hiding and Showing the Text Window

You can hide or show the text window with the Window Options command from the View menu, or by using a quick-button.

In Windows: When visible, the text window will always be placed on top of the SDL Editor window.

Basic Text Editing Functions

Delayed Updating of the Drawing Area

When you edit text in the text window, both the text window and corresponding text in the drawing area will be updated. The the drawing area will be updated after a slight time delay and this can be set by an editor preference.

If you try to type an illegal character, you will be warned by a beep.

Standardized Text Editing Functions

When you edit text, you can:

  • Position the cursor by clicking or by using the arrow keys.
  • Insert characters after the current position of the text pointer.
  • Delete one character backward by pressing <backspace>.
  • Delete one character forward by pressing <delete>.
  • Replace selected text by typing.
  • Delete selected text by pressing <backspace> or <delete>.
  • Select text by dragging or by clicking and <Shift>-clicking.
  • Select a word by double-clicking it.
  • Select a line by triple-clicking it.

Searching and Replacing Text

In the SDL editor, you can search for and replace text in a page or in a diagram. In the Organizer, you can search for and replace text in a diagram or in a diagram structure that is managed by the Organizer. In both the SDL editor and the Organizer, there are two search variants:

  • Dialog search
  • Fast search

Searching for Text in a Diagram using Dialog Search

To search for text in the current page from the SDL editor:

  1. Select Search from the SDL editor's Tools menu or click the SDL editor quick-button for Search. The Search dialog is issued.

  2. Specify the text to be found in the Search for text field.
    • Click the Consider case button on to search case sensitive.
    • Click the Wildcard search button on to use wildcard matching, where an asterisk (`*') matches a sequence of zero or more characters of any kind.
    • Turn the Search all pages button on to specify that the scope of search should comprise all pages in the diagram. If you turn the button off, the scope of search will only comprise the current page.
  3. Click the Search button. The object where the next occurrence of text is found will be selected and the text window updated accordingly.
    • The diagram that the tool is currently processing is displayed to the right of the Search In field.
  4. Click Close.

Searching and Replacing Text using Dialog Search

  1. Open the Search dialog as described in "Searching for Text in a Diagram using Dialog Search" .
  2. Specify the text to be found in the Search for text field.
  3. Specify the text to be replaced with in the Replace with text field.
  4. Click the Search button to find the first occurrence.
  5. If the text is found, the object where the next occurrence of text is found will be selected and the text window updated accordingly. You may use any of the following options:
    • Search further by clicking Search repeatedly
    • Replace the text by clicking Replace
    • Replace and continue search with the Replace & Search button.
    • Replace all occurrences with the Replace All button.
  6. Close the Search dialog by clicking Close.

Fast Search

Fast search is like dialog search but without the dialog. The setting from the last dialog search is used for Wildcard search. Fast search do never consider case, and does always search all objects and all pages. To invoke Fast search, type ctrl+F when the SDL editor is not in text editing mode. If you are in text editing mode, you can click in the diagram background first to get out of text editing mode.

When Fast search is invoked, the message area displays the text that will be searched for. Initially, the text is Search for:. When you type on the keyboard with the mouse pointer over the drawing area, the characters will turn up in the message area. When you have typed the text pattern to search for, press enter or return to start the search operation.

The same search operation as for Dialog search is used. If the search operation finds a match, you can search for another match by pressing enter or return once more.

To finish the Fast search operation, click in the drawing area or select another operation.

The next time Fast search is invoked with ctrl+F, the search text that was used the last time is proposed as a search text once more. To use it, press enter or return. To use another search text, press ctrl+F once more or the delete key several times, to erase the search text.

Editing Text by Using an External Text Editor

Whenever a text object is selected and the text is visible in the text window, the command Connect to Text Editor in the Tools menu is available. This command opens an external text editor containing the text of the selected object. Which external text editor to start is defined by the preference SDT*TextEditor, which can be set either to the Text Editor or to the Emacs text editor (on UNIX).

From this point on, you can only edit the text by using the external text editor.

The text in the SDL Editor is updated every time the external text editor saves the text. When the text is no longer edited in the external text editor, the editing control returns to the SDL Editor.

Importing / Exporting Text

The SDL suite allows you to import and export text from / to a file. You can, for instance, import text from files that contain SDL/PR into text symbols and export the contents of text symbols to files.

Importing Text from a File

Caution!

Importing text from a file replaces existing text as well. There is no Undo facility.

You can import the contents of a text file into an object managed by the SDL Editor in the following way:

  1. Select the object where you want to import the contents of a file.
  2. Select Import from the text window's File menu.
  3. Specify the file to import.
  4. Click OK. This replaces the contents of the text window with the contents of the file you have specified in the file selection dialog.

Exporting Text from a File

To export the contents of the text window into a file:

  1. Select the object which text you want to export to a file.
  2. Select Export from the text window's File menu.
  3. Specify the file to export the text to.
  4. Clicking OK possibly creates a new file and replaces the contents of the file with the contents of the text window.

Copying, Cutting and Pasting Text

In the text window, you can cut, copy and paste text between different symbols, lines and text attributes. You can also transfer text between different applications.

Programmable Function Keys (UNIX only)

On UNIX, the SDL suite allows to tie a function key to a defined text string. When you type that defined function key, the programmed text string will be inserted at the current cursor location. You can customize your own programming of function keys.

Global SDL Suite Resources

The function keys are set up as X resources. It is possible to set up both system default and user-defined X resources, allowing you to customize your environment. The X resources are defined in a file that is common for all SDL suite users, namely

/usr/lib/X11/app-defaults/SDT

To program the function keys, insert following lines anywhere into the SDT file:

/* Any suitable comment */
SDT*XmText.translations: #override \n\
<Key>F1: insert-string("F1Text") \n\
<Key>F2: insert-string("F2Text") \n\
<Key>F3: insert-string("F3Text") \n\
<Key>F4: insert-string("F4Text") \n\
<Key>F5: insert-string("F5Text") \n\
<Key>F6: insert-string("F6Text") \n\
<Key>F7: insert-string("F7Text") \n\
<Key>F8: insert-string("F8Text") \n\
<Key>F9: insert-string("F9Text")
/* Note the absence of \n\ on line 9 */

Note:

Omitting to define some of the function keys is permissible.

User-Defined Resources

You can define your own function keys. You do this by defining the X resources described above in a personal copy of the definition file and to store that file it into your home directory:

~username/SDT

Alternatively, any directory designated by the environment variable XAPPLRESDIR can be used.

Restrictions

  • You can only define one line for each function key. If you attempt to define more than one line into one function key may cause an unpredictable result when you press that key.
    For instance, it is not certain that the following line will produce the expected result:
<Key>F1: insert-string("F1Line1\nLine2") \n\

  • You can define the keys F1-F9.

Changing Fonts on Text Objects

You may change the font faces and font sizes used in the textual objects displayed by the SDL Editor. All textual objects use the same font faces and font sizes, meaning that you can neither change them individually nor change them during an SDL Editor session.

There is one exception though - it is possible to use a separate font for text symbols. This is useful in process diagrams where you may want a proportional font in most symbols to save space, while you may want a non-proportional font in text symbols to be able to align words on different lines.

The font faces available depend on the target system on which you are running the SDL suite.

Defining What Font to Use

To modify the desired font size and font face, you must use the Preference Manager. See 4 Managing Preferences.

Textual Objects Preferences

When the setting is in effect, the SDL suite will use the font face names given by the preference settings

Editor*FontText*ScreenFontFamily
Editor*FontText*PrintFontFamily

to select font face names. Note that in this way you can select different font names for screen and for print.

On UNIX, if you leave the Editor*FontText*ScreenFontFamily preference setting empty, you will edit your documents using the SDT Draft font, but print them using the font you specified with the Editor*FontText*PrintFontFamily setting.

Text Symbol Preference

For text symbols, the preference Editor*FontText*TextSymbolFontFamily is used both for on-screen viewing and printing.

Supported Font Faces

On UNIX, the availability of font faces is determined by the version of the X Windows server which is running. With a revision 5 or higher (X11 R5), scalable fonts are supported. In that case, the available list of predefined font faces would be:

  • Times
  • Helvetica
  • Courier
  • SDT Draft (mapped to the Schumacher font)
  • Other (mapped to a user-defined font)

In Windows, the availability of font faces is determined by the TrueType fonts that are currently installed on the computer (use for instance the Windows Control Panel to determine what is available).

Default Font Face

The default font face is Helvetica. On UNIX, if scalable fonts are not supported, the font face will be replaced by a Schumacher font (which can be used in all circumstances).

Default Font Sizes

The default font sizes are as follows:

Text Object: | Font Size
Kernel heading, texts in reference symbols, channel names, signal route names, gate names | 12 points
Other text objects | 9 points

Text Object: | Font Size:
All texts except signal lists | 10 points
Signal list symbol | 8 points

Setting Alignment

Normally the alignment of the text inside symbols are automatically set. However, you can use the preference setting Editor*FontText*TaskSymbolLeftAligned to set the alignment for the task symbol, procedure call symbol, macro call symbol, create request symbol and the save symbol. The default value is "off", meaning that the text will be centered, but if you set it to "on" the text in these symbols will be left aligned.

Determining Which Scalable Fonts Your Server Can Access (UNIX only)

On UNIX, use the xlsfonts command to list installed fonts. Font names containing 0 for width and height are scalable.

How to Determine what Fonts are Available

From the OS prompt, typing:

hostname% xlsfonts | grep "\-0\-O\-" | more

will return a list of accessible scalable fonts.

Scalable Fonts Under R5 Servers

To use scalable fonts under X11R5 you must normally first connect to a font server.

How to Start the Font Server

  1. Start the font server on any local host:
hostname% fs
  2. Connect the server to fs indicating which host the font server is running on (which can be the same host that the X server is running on):
hostname2% xset +fp tcp/<hostname>:7000

For further information see the X11R5 documentation or use man fs to read the manual page describing the font server you are running.

Disabling Font Scaling (UNIX only)

On UNIX, if the fonts look poor on the screen, a possible work-around is to disable the scaling option.

Note:

Disabling font scaling effectively disables WYSIWYG!

To do this, you should edit the SDT resource file.

  1. Open the file SDT in a text editor.
  2. Locate the line with the text: SDT*sdtUseScalableFonts
  3. Change the line to SDT*sdtUseScalableFonts: false
  4. Save the file and restart the SDL suite environment.


Grammar Help and Signal Dictionary

General

Besides the context sensitive syntax check performed on the texts, there is a grammar help support function. It assists you in entering the correct text, according to the SDL grammar, in the selected text attribute to an object.

Designing using SDL implies to large extent defining, sending and receiving signals. A signal dictionary assists you in reducing the time it takes to find out names and parameters for a signal that you already have used somewhere in a diagram. The signal dictionary also incorporates timers.

Keyboard Accelerators (UNIX only)

In addition to the standard keyboard accelerators, described in "Keyboard Accelerators" , the Grammar Help and Signal Dictionary window features the following:

Accelerator
Command / functionality

 g
Select the Grammar section if the option is enabled and bring the separator into view

 u
Similar to g but applies on Up.

 t
Similar to g but applies on This.

 d
Similar to g but applies on Down.

 a
Similar to g but applies on All.

 m
Similar to g but applies on MSC.

 e
Similar to g but applies on External.

 Ctrl+g
Toggles the Grammar option on / off (see "Grammar" ). When the option is enabled, brings the Grammar separator into view and selects it.

 Ctrl+u
Same as Ctrl+g, but applies on the Up option.

 Ctrl+t
Same as Ctrl+g, but applies on the This option).

 Ctrl+d
Same as Ctrl+g, but applies on the Down option.

 Ctrl+a
Same as Ctrl+g, but applies on the All option.

 Ctrl+m
Same as Ctrl+g, but applies on the MSC option.

 Ctrl+e
Same as Ctrl+g, but applies on the External option.

 Ctrl+f
Finds the last occurrence of the first word in the currently selected object in the SDL Editor drawing area and selects it in the This section.
The first word is defined as the text string from the start of the object's text and until one of the following characters:
` ' (space) `,' (comma) `(` (left parenthesis) <TAB> `\n' (newline)

Using Grammar Help

The Grammar Help window is a multi-functionality window; it can also provide signal dictionary capabilities. These functions are further described in "Using the Signal Dictionary" . What functionality is provided depends on the options defined in the Select menu.

Each SDL Editor window has its associated Grammar Help window.

Opening the Grammar Help Window

  • Select the Grammar Help menu choice from the Windows menu.
    The grammar help window is issued (see Figure 399).

Requesting Grammar Help

If you select the object you need assistance on, you will see the keywords and options available for use in given situations, and the corresponding reference to sections of the ITU Z.100 SDL Definition, followed by the grammar syntax of the meta language.

To request grammar help:

  • Select the object of interest. The grammar help window contents are automatically updated to list the following:
    • The nature of the selected object
    • The grammar for that object
    • The various "use cases".

Inserting Text

This operation inserts the contents of the grammar help window into the SDL Editor text window.

To insert the text related to a given "use case":

  1. Locate the "use case" of interest. The left part of the window provides a list of situations, named using some abbreviation that associates to the situation.
    • The first item(s) in the list reads GRAMMAR, possibly with a suffix that informs you about the grammar context. You can take advantage of the GRAMMAR items either as using the references to Z.100 if you need more detailed information about the selected sort of object, or if you need to read more about the concrete grammar.

Figure 399 : The grammar for a task symbol

    • The next items contains a number of "use cases". As an example, if you select a task symbol, the first "use case" reads Assignment, while the second reads Assignment2. This is to be interpreted as:
      An assignment statement,
      Multiple assignment statements in a task symbol.

Figure 400 : The Assignment "use case"

  2. Click on the item of interest to select it.
  3. Select Insert from the Edit menu or double-click the item in the list. The contents of the right part of the window are inserted into the SDL Editor text window, at the current I-beam cursor position.
  4. Finally, replace the formal notation with the appropriate values, variables, signals, etc. used in your diagram.

Replacing Text

This operation signifies replacing the contents of the SDL Editor text window with the contents of the grammar help window.

  • Proceed as described in "Inserting Text" , but select Replace from the Edit menu.

Customizing the Grammar Help

With the SDL suite, a standard grammar help template file is provided. In addition to this, the SDL Editor allows you to use your own templates and to merge these with the standard templates.

To create grammar help definitions:

  1. Copy an existing grammar help file.
  2. Edit the file using any text editor (the grammar help file is an ASCII file). See "The Grammar Help File" for a description of the contents and syntax of the file.

To use another grammar template definitions:

  • Select Load from the File menu. In a File Selection Dialog you then specify what template definitions to load.

To merge the current grammar template definitions with another one:

  • Select Load from the File menu. In a File Selection Dialog, you then specify what template definitions to merge with the current.

The Symbol Label

The symbol label field is a non-editable text field that displays the type of symbol that is currently selected in the SDL Editor.

Figure 401 : The symbol label

The symbol label reads "No single symbol selected" in the following circumstances:

  • No symbol or line is currently selected in the SDL Editor
  • More than one symbol is selected
  • The symbol type is not defined in the Grammar Help file.

The Name Field

The name field consists of a scrollable list that contains a list of names of templates associated with the currently selected symbol.

Figure 402 : The name field

The list is updated automatically each time an object in the SDL Editor's drawing area is selected, to reflect the templates that are currently available for that object. By default, the first item in the list is selected.

The name field is empty in the following circumstances:

  • The symbol label reads "No single symbol selected"
  • The symbol type information is missing in the Grammar Help file.

When selecting an item in the list, the corresponding template definition appears in the grammar field, allowing to check its contents before inserting it into the text window (see "Insert" and "Replace" ).

The Grammar Field

The grammar field is a scrollable field from which text can be copied. Its contents are updated to reflect the definition for the currently selected item in the name field.

The grammar field is empty if no item is selected in the name field (or if the name field is empty).

Figure 403 : The grammar field

To copy and paste text from the template definition field to the text window, you can:

  • Use the Insert command, described in "Insert" .
  • Use the Replace command, described in "Replace" .
  • Copy and paste by using the graphical environment clipboard functions.

The Grammar Help File

This section is a reference for the format of the files that contain SDL Grammar Help definitions.

The template definition file format is line-oriented, and uses two separator characters chosen so as to not interfere with the possible contents of templates appearing in the file.

Note:

The characters `@' and `$' are separator characters. They are reserved for that purpose.

The template definition file is divided into sections defining templates for a particular symbol type. A section begins with a Grammar Help Declaration part and ends with a Grammar Help Definition part.

The grammar help declaration of a new section has the following syntax:

@<editortype>@<symboltype>[@[<symbolcomment>]]

<editortype>, <symboltype> and <symbolcomment> are to be replaced with the adequate text strings.

Comments in Grammar Help files are also permissible.

Example 304 : The Declaration of a Channel Template

@SDL@CHANNEL@Channel symbol

The declaration is to be interpreted as:

  • SDL
    Valid for the SDL Editor only
  • CHANNEL
    A channel line
  • Channel Symbol
    An informative text that will be displayed to you (see "The Symbol Label" ).

editortype

editortype may currently be of one of the keywords:

  • - The section contains templates relevant for the SDL Editor.
  • - The section contains templates for the Message Sequence Chart Editor.

Note:

Grammar Help is currently not supported by the MSC Editor. The MSC keyword is reserved for future functionality extensions.

symboltype

symboltype is defined per editor and the allowed names are the following:

ADDITIONAL_HEADING_BLOCK
ADDITIONAL_HEADING_BLOCK_TYPE
ADDITIONAL_HEADING_PROCEDURE
ADDITIONAL_HEADING_PROCESS
ADDITIONAL_HEADING_PROCESS_TYPE
ADDITIONAL_HEADING_P_AS_SERVICE
ADDITIONAL_HEADING_SERVICE
ADDITIONAL_HEADING_SERVICE_TYPE
ADDITIONAL_HEADING_SYSTEM
ADDITIONAL_HEADING_SYSTEM_TYPE
BLOCKSUBSTRUCTURE
BLOCK_REF
BLOCK_TYPE_REF
CALL
CHANNEL
CHANNELSUBSTRUCTURE
CONNECTION_POINT
CONNECTOR
CONTINUOUS_SIGNAL
CREATE
DECISION
ENABLING_CONDITION
GATE
INPUT
KERNEL_HEADING
KERNEL_HEADING_BLOCK
KERNEL_HEADING_BLOCK_TYPE
KERNEL_HEADING_PROCEDURE
KERNEL_HEADING_PROCESS
KERNEL_HEADING_PROCESS_TYPE
KERNEL_HEADING_SERVICE
KERNEL_HEADING_SERVICE_TYPE
KERNEL_HEADING_SYSTEM
KERNEL_HEADING_SYSTEM_TYPE
MACROCALL
OPERATOR_REF
OUTPUT
CLASS
PACKAGE_REF
PAGENUMBER
PRIORITY_INPUT
PRIORITY_OUTPUT
PROCEDURE_REF
PROCEDURE_START
PROCESS_REF
PROCESS_TYPE_REF
RETURN
SAVE
SERVICE_REF
SERVICE_TYPE_REF
SIGNALROUTE
START
STATE
STOP
TASK
TEXTSYMBOL_BLOCK_SUBSTR
TEXTSYMBOL_MACRO
TEXTSYMBOL_PROCEDURE
TEXTSYMBOL_PROCESS
TEXTSYMBOL_P_AS_SERVICE
TEXTSYMBOL_SERVICE
TEXTSYMBOL_SYSTEM
TRANSITION_OPTION

Note:

If the same section appears more than once, all template definitions under those sections will be available.

symbolcomment

symbolcomment is an optional feature, which allows specification of a text to be associated with each symboltype. The text for a specific symboltype appears in the symbol type field of the Grammar Help window whenever a symbol of that type is selected in the editor.

Comments

Also, comments may appear in the file using the following syntax:

@COMMENT@<commenttext>

Note:

Such a comment signals the end of the previous section and should only be used before another section.

Grammar Help Definition

A SDL grammar template has significance only if it is located after a valid declaration. The template will be added to the list of templates for that section.

A template definition is started with a line beginning with a `$' sign and continues until either:

  • A line beginning with a `$' sign is read.
  • A line beginning with a `@' sign is read.
  • End of file is encountered.

The syntax of a template definition is simply:

$<templatename>'Newline'
<multiple lines constituting the template definition>

Example 305 : The definition of a channel example

$GRAMMAR
Z100: 2.5.1 (p.45)
Z100: 2.5.5 (p.50) Signal list

<ChannelName> ::= <Name>
<SignalList> ::=
( <SignalName> / '(' <SignalListName> ')' )",'
$SignalList
SignalName, SignalName
$SignalList2
SignalName, SignalName, (SignalListName)

Note:

Neither leading nor trailing newlines will be added to the template definition. These can be added to the template simply by adding a leading empty line and/or a trailing empty line in the template definition.

File Handling

When a Grammar Help window is opened, the SDL Editor will try to locate a SDL grammar help file and to load it, if found. The search order is as follows:

  1. The SDL Editor starts by fetching the preference value
    Editor*TemplateFile.
  2. If no value is specified for the preference parameter, it will use the default file name sdt.tpl.
  3. The directories where the SDL Editor will search for the file are:
    • The current directory
    • Your home directory ($HOME on UNIX and %HOME% in Windows)
    • The installation directory ($sdtrelease on UNIX)
  4. If no file can be located, either with a specified name or the default name, you get the option of searching manually (i.e. from a File Selection Dialog) for files with the standard file name extension .tpl.
  5. If you decline by clicking Cancel, the Grammar Help window will appear without contents. You can now locate a grammar help file by choosing Load (or Merge, which will have the same effect in this case).

Using the Signal Dictionary

Messages from a Message Sequence Chart and signals from an external signal dictionary may be included into the SDL Editor's signal dictionary.

All functionality is provided in the signal dictionary window. Each SDL Editor window has its associated Signal Dictionary window.

Note:

The signal dictionary function requires a file with grammar help templates (sdt.tpl) in order to function properly. See "The Grammar Help File" .

Figure 404 : The Signal Dictionary window (on UNIX)

Figure 405 : The Signal Dictionary window (in Windows)

Signal Dictionary Update

The signal dictionary function stores information about signals in an information server. The information server updates its contents each time an SDL diagram is saved. When the diagram is saved by the SDL Editor, the SDL Analyzer is invoked and produces a mirrored image which is an SDL/PR description of the SDL/GR diagram. That information is then loaded into the information server which serves the SDL Editor with information upon request. All of this is done automatically.

Note:

In order to extract signal information from a diagram, the SDL suite requires the diagram to be syntactically correct in the sense that SDL/PR code can be generated from the SDL/GR diagram without encountering errors.

Opening the Signal Dictionary Window

  • Select Signal Dictionary from the SDL Editor Windows menu. The signal dictionary window is issued (see Figure 404 and Figure 405).

Setting the Mode to Graphical or Textual (UNIX only)

On UNIX, the signal dictionary window can take advantage of your computer's font capabilities to present the information in a graphical way, using SDL-like notation. This is the default mode.

If the information is presented using strange characters, your terminal does not support the font family used by the signal dictionary window. You should use the textual mode.

To turn the mode to textual:

  1. Set the environment variable SDLENOGRAPHICS
    • If you are to run several Signal Dictionary sessions in this mode, you may want to set the environment variable in a file that you will automatically source (e.g. .cshrc)
  2. Exit all SDL suite tools.
  3. Restart the SDL suite to have the environment variable affect the behavior.

Requesting Signal Dictionary Services

When you select an object where a reference or definition of a signal makes sense, the signal dictionary window is automatically updated to reflect the signals and signal conveyors1 that are available according to what options you have selected.

The signal dictionary function responds when selecting the following objects (see "Object" for more details):

  • channel
  • signal route
  • connection point
  • gate
  • signal input
  • signal output
  • priority input
  • save of signal
  • text symbol

Updating the Signal Dictionary

The signal dictionary is automatically updated each time you save an SDL diagram or an MSC that is referred to in the Organizer's SDL System Structure chapter.

When modifying an SDL diagram, you may have unintentionally introduced SDL constructs that are incomplete and thus cause the signal dictionary to fail in providing signal information for that diagram.

Where the signal dictionary fails on a diagram, a bug symbol (on UNIX), or an error message (in Windows) will appear after the diagram name in the signal list. Correct the source of error and save the diagram again. For a reference on signal dictionary errors, see "Error Notification" .

Specifying the Signal Dictionary Options

You can customize the signal dictionary to fit your needs, by restricting or extending the amount of information that is presented through a set of options that you can activate or deactivate.

Depending on the method you are following when designing with SDL, you should activate the required options.

Next follows a guide for when to use the available options.

To enable an option:

  1. Activate the Select menu.
  2. Toggle the appropriate option on by selecting it (an option which is enabled is indicated with an asterisk preceding the option name). Selecting the option once again disables it.
    • Alternatively, select the Options menu choice and toggle the buttons on or off. When satisfied, click OK.

Note:

The more options are enabled, the more information is computed by the SDL Editor and the more time it takes.

Bellow follows a few general guidelines for enabling the various options, depending on the approach you are following when designing with SDL.

Working Top-Down

This expression means starting by designing the root diagram (e.g. the system diagram) and continuing with the block diagrams, next the process diagrams and so forth.

If you follow this approach, selecting the Up option will enable access to signals used one level up in the SDL hierarchy. This option is enabled by default.

    • You may also type <Ctrl+u> to toggle the option. Typing u brings the Up option into view (if enabled).

Working Bottom-Up

Following this method means starting with the diagrams at a deeper level (e.g. procedures) and working upwardly in the SDL hierarchy.

If you work bottom-up, select the Down option to enable access to signals used one level down in the SDL hierarchy. This option is enabled by default.

    • You may also type <Ctrl+d> to toggle the option. Typing d brings the Down option into view (if enabled).

Working with Local Signals

If you look for entities that are used locally in a diagram, select the This option. Remember, a diagram needs to be saved in order to update the signal dictionary.

    • You may also type <Ctrl+t> to toggle the option. Typing t brings the This option into view (if enabled).
    • To find the definition of the signal in the This section, you may select an object in the drawing area that uses the signal and type <Ctrl+f>.

Listing all Signals

You can list all signals that are visible according to the SDL scope rules by turning the All option on. For instance, a signal that you declare on the system level will be available in all diagrams in the SDL hierarchy.

    • You may also type <Ctrl+a> to toggle the option. Typing a brings the All option into view (if enabled).

Using Packages

If you want to gain access to signals that you have declared in a package, you should enable the All option.

Using Diagram Types

If you use the diagram type concept, you should enable the All option to gain access to the signals that are defined in the diagram types.

Listing MSC Messages

If you describe the dynamic behavior of an SDL diagram using the MSC Editor, you may take advantage of this by turning the MSC option on.

Note:

Messages used in an MSC will be available in the signal dictionary only if it is associated with an SDL diagram, i.e. linked into the SDL diagram structure.

Importing an External Signal Dictionary

You may import an external signal dictionary into the SDL suite through the Postmaster interface. This is described in "Load External Signal Definitions into the Information Server" .

Locating the Source Diagram

Note: Signal Dictionary and OO

If you are looking for a source diagram that is an SDL-92 type (system type, block type, process type or service type) and that you access through an instance of the type, the following conditions must be respected in order to have the signal dictionary window list the diagram and list all of the signals and signal conveyors that are used in the diagram:
  • The type diagram must be referred in the same diagram as where it is instantiated. In the signal dictionary window, only the type will be listed, not the instance. Figure 406 shows an example of this.
    • As a consequence of this, you will not be able to look into the instance of a type that is defined in a package diagram and used in the current SDL system.
  • In the case the type is inherited from a supertype, the entities that you are looking for must be defined in the child type.
The main cause of this limitation is that channels and signal routes are connected to the instance, not to the type.

Figure 406 : The type is referred where instantiated

The process type Controller is instantiated as Cl. The process instance Cl will be visualized as the process type Controller, and you can list signals conveyed on the gates A, B, C, D and E.

To locate the source diagram (i.e. the diagram where the signal is used or where the signal conveyor is available):

  1. Locate the section (Up , This , Down , All , MSC and External) by scrolling up or down. The sections are listed in that order and the start of each section is identified with a separator with the corresponding name.
    • You may also use the keyboard accelerators <Ctrl+u>, <Ctrl+t>, <Ctrl+d>, <Ctrl+a>, <Ctrl+m> and
      <Ctrl+e>       to toggle the respective option on and off.
    • Use the keyboard accelerators u, t, d, a, m and e to bring the respective section into view.
  2. Identify the source diagram by its type and name. Diagrams are listed alphabetically by their name. The diagram type is identified either by a graphical SDL-like symbol (see Figure 414) in the left margin (UNIX only), or by a text string that consists of the diagram type.

Updating the Text in the Target Diagram

Once you have located the source diagram your next task is to insert the text belonging to the object you have selected in the target diagram (the diagram where the change is to be done).

Updating a Signal / Timer Output, Input, Priority Input or Save

This operation makes sense only on pages where the implementation is described, i.e. the flow pages.

  1. Locate the matching signal or timer in the signal list.
    • Signals are identified graphically with the SDL signal input and/or signal output symbol (UNIX only), or with the characters `I', `O' or `?' (see "Signal and Signal List" .
    • Timers are identified with the MSC timer symbol (UNIX only), or the character `T' (see "Timer" ).
  2. Make sure the signal output, input, priority input or save symbol to be updated is selected in the target diagram.
  3. Select the signal or timer item in the signal list. Use Insert or Replace from the Edit menu to update the symbol contents. The target symbol is updated with the signal name and its formal parameters.
    • Alternatively, double-click the signal or timer.

Figure 407 : Selecting the signal Display

  4. Update the signal's formal parameter type with a current parameter.

Updating a Signal Conveyor
(Channel, Signal Route, Connection Point or Gate)

  1. Locate the signal conveyor that constitutes the corresponding item that interfaces to the channel, signal route or gate that you are to update in the current diagram.
    • In graphical notation on UNIX, these entities are identified graphically by a symbol which has the appearance of the corresponding SDL concept (see Figure 415, Figure 416 and Figure 417).
    • Channels, signal routes and gates are identified textually with the abbreviations CH, SR and GA, respectively.
  2. Make sure the signal list is selected in the target diagram.
  3. Select the signal conveyor. Use the Insert or Replace from the Edit menu to update the signal list contents.
    • Alternatively, double-click the signal or timer.

Figure 408 : Selecting the Channel cPanelToControl:int:int

  4. In the case of a bidirectional conveyor, you will see lines of text in the right window, each one corresponding to a signal list (as in Figure 408, above). You should copy each line of text to the corresponding signal list. Select the signal list in the SDL Editor and a line, then use Insert or Replace to update the signal list.

Updating a Text Symbol

When updating a text symbol, you are likely to declare signals and timers that you have referred to in the current diagram or referred to in the SDL hierarchy descending from the current diagram.

  1. You should make sure the Down and This options are selected.
  2. Remember to add a SIGNAL or TIMER keyword in the text symbol, before the enumeration of signals.
  3. Locate all diagrams of interest. Look for signals / timers that you want to declare. Double-click each signal, and insert the necessary commas to create a syntactically correct declaration. Terminate the operation by inserting a semicolon.

Finding a Definition

When you select an object in the SDL Editor's drawing area and then type <Ctrl+f> the first occurrence of the first word in the object is looked for and selected in the This section.

Closing the Signal Dictionary Window

You close the signal dictionary window by selecting Close from the signal dictionary File menu.

The Symbol Label

The symbol label field is a non-editable text field that displays the type of object that is currently selected in the SDL Editor.

Figure 409 : The symbol label

The symbol label reads "No single symbol selected" in the following circumstances:

  • No object is currently selected in the SDL Editor
  • More than one object is selected.
  • The symbol type is not defined in the Grammar Help file.

The Signal List

The signal list is a selectable list where all occurrences of signals that are found according to the current selection criteria are listed.

Figure 410 : The signal list (on UNIX)

Figure 411 : The signal list (in Windows)

The signal list is empty when:

  • The symbol label reads "No single symbol selected"
  • The signal dictionary function does not make any sense on the selected object. i.e. the selected object does not refer/define a signal.

The following objects are recognized as carrying signal information:

Object | Usage
channel line channel name signal list in channel | Reference to signal
connection point | Reference to signal
gate gate name signal list in gate | Reference to signal
input | Reference to signal
output | Reference to signal
priority input | Reference to signal
save | Reference to signal
signal route line signal route name signal list in signal route | Reference to signal
text | Declaration of signal

Signal List Notation and Syntax

Each line in the signal list follows a notation that informs about the various diagrams and symbols where signals are used and also about the context.

In Windows, this notation is purely textual.

On UNIX, the notation that is adopted is an SDL-like graphical notation. It is also possible to select a textual notation if the font face used in the graphical notation is not supported by the computer. You select the textual notation by setting the environment variable SDLENOGRAPHICS before you start the SDL suite.

Each item in the signal list is one of the following:

  • Separator
  • Diagram Identifier
  • Gate
  • Channel
  • Signal Route
  • Signal and Signal List
  • Timer

Separator

The signal list is divided into several sections. The top of each section is clearly marked with a separator, having the appearance of a thick line (graphical notation on UNIX) or a number of hashes ("###...###") preceding and following a text that identifies the section.

Figure 412 : A signal list separator (graphical notation on UNIX)

Figure 413 : A signal list separator (textual notation)

Each of these sections corresponds to an option that is enabled in the Select menu (see "Select Menu" ). Their meaning and order of appearance in the signal list is as follows:

  • Grammar
    SDL Grammar Help section. See "Using Grammar Help" for more information about this topic.
  • Up
    A list of all SDL signals that are available2 by looking one level up in the SDL hierarchy. The Up section is empty when working on the top diagram (e.g. a system diagram).
  • This
    All SDL signals that are available by looking at the current diagram, i.e. this diagram.
  • Down
    All SDL signals that are available by looking at all diagrams one level down in the SDL hierarchy. The Down section is empty if the current diagram has no diagrams below it in the hierarchy.
  • All
    All defined SDL signals that are visible for the current diagram according to the SDL scope rules.
  • MSC
    Signals that have been exported from a Message Sequence Chart into the SDL Editor signal dictionary facility. An MSC must be Associated with an SDL diagram in the Organizer's diagram structure in order to include its signals into the Signal Dictionary (see "Associate" ).
  • External
    Signals that have been imported from an external signal dictionary. An external signal dictionary is imported through the public PostMaster interface of the SDL suite. See "Load Definition File" .

Diagram Identifier

In the graphical notation on UNIX, diagrams are identified with an SDL Reference symbol in the left margin which identifies the diagram type, followed by the diagram name:

Figure 414 : Diagram type symbols (graphical notation on UNIX)

The textual notation reads <diagramtype diagramname>

All information that is listed after a diagram identifier is related to that diagram, until the next diagram identifier or separator.

Gate

In the graphical notation on UNIX, gates are identified by an arrow pointing into or out from the frame, followed by the name of the gate:

Figure 415 : Gate symbols (graphical notation on UNIX)

The textual notation reads:

GA <Gatename>:<In>|<Out>|<In:Out>

Signals on a gate are the lines that appear after the gate and before the next gate, channel, signal route or diagram identifier. The lines consist of all signals or signal lists that are conveyed on the gate, the signals sent to the diagram appearing first and the signals sent from the diagram appearing last.

Signals are listed according to the order of appearance in the respective signal lists.

If you select a gate in the list, one or two lines is displayed in the signal definition list. In the case of a bidirectional gate, the first line holds the signals sent to the diagram while the second line holds the signals sent from the diagram.

Channel

In the graphical notation on UNIX, channels are identified by an arrow between the frame and a block symbol (in the case of a channel to/from the environment), alternatively with an arrow between two block symbols (an internal channel):

Figure 416 : Channel symbols (graphical notation on UNIX)

The textual notation of a channel is:

CH <Channelname>:<In>|<Out>|<In:Out>|<Int>|<Int:Int>

Channels are present on package, system, block, block substructure and system type diagrams only.

The lines of information that follow a channel consist of the signals that are conveyed on it. The appearance is similar to listing signals on a gate. See "Gate" for information about listing order.

Signal Route

In the graphical notation on UNIX, signal routes are identified by an arrow between the frame and a process symbol (a channel to/from the environment), alternatively with an arrow between two process symbols (an internal signal route).

Figure 417 : Signal route symbols (graphical notation on UNIX)

The textual notation of a signal route looks like this:

SR <Signalroutename>:\
<In>|<Out]>|<In:Out>|<Int>|<Int:Int>

Signal routes are present on block and block type diagrams only.

The lines of information that follow a signal route consist of the signals that are conveyed on it. The appearance is similar to listing signals on a gate. See "Gate" for information about listing order.

Signal and Signal List

Signals and signal lists can appear in the following contexts:

  • Signal Definitions (i.e. declarations in text symbols)
  • Signal References on Lines (i.e. references in gates, channels and signal routes)
  • Signal References in Flow Diagrams (i.e. references in flow diagrams; processes, process types and procedures).

The notation that is adopted differs slightly depending on the context.

A signal definition appears directly after the diagram identifier where the signal is declared. The signal is identified by its name and its location to distinguish it from other items.

The indentation is filled with blank space (see Figure 418).

Figure 418 : Signal definitions

Note:

Each signal appears only once within a diagram. If a signal is referenced at least once within the diagram, it is not listed in the signal definitions section for that diagram, only references are listed.

A signal reference on a line uses a similar notation as for signal definitions. The indentation consist of an arrow that identifies the direction of the signals (see Figure 419).

Figure 419 : Signal references on a line

Signal references in flow diagrams are listed along with the context the signal is used. This is indicated by the following attributes (multiple attributes can be set):

  • Input3
  • Output
  • Reference to an undefined signal.

In the graphical notation on UNIX, these attributes are shown using SDL input and SDL output symbols, and a question mark for showing that the signal is not declared:

Figure 420 : Signal symbols (graphical notation on UNIX).

The textual notation uses the characters:

[I][O][?]

These characters appear at fixed positions. Where an attribute is not set, this is indicated with a hyphen (`-'). See Figure 421.

Figure 421 : An undeclared signal which is input and output

Timer

A timer is handled identically as described in "Signal and Signal List" . To indicate that the item is a timer, the graphical notation on UNIX uses the MSC symbol for timer.

Figure 422 : Timer symbol (graphical notation on UNIX).

In the textual notation, a `T' appears as the rightmost attribute.

Timers can appear in the following contexts:

  • Definitions of timers
  • Set statements
  • Reset statements
  • Active statements.

Error Notification

If the SDL suite fails in extracting signal information from some SDL diagrams, the information contained in that diagram is not available to the signal dictionary function.

In the graphical notation on UNIX, this is indicated in the signal list by a "bug" symbol located to the right of the diagram names.

Figure 423 : Errors were detected when extracting signals
(graphical notation on UNIX)

The SDL suite failed in extracting signal information from the process type diagrams Door, DoorLock and the block type diagram Doors (one level down in the SDL hierarchy)

In the textual notation, this is indicated by an error message following the diagram name:

<diagramtype diagramname> :GrPrError

Figure 424 : Errors were detected when extracting signals

The current diagram (This diagram) is process type Door. The SDL suite could not convert this diagram to SDL/PR.

These error situations are either caused by:

  • Syntactically incorrect SDL which causes the SDL suite to fail when converting the SDL/GR diagram to SDL/PR.
  • Syntactically incorrect SDL which causes the information server to fail when parsing the contents of the SDL/PR file. When possible, the signal definition field will contain a graphical reference to the source of error. Double-clicking that graphical reference will display the source of error in an SDL Editor window.

The error reports are listed in the Organizer low window. See also "Signal Dictionary Update" .

The Signal Definition

The signal definition contains the following information:

  • If a signal or timer is selected in the signal list, the signal or timer is listed with its parameters (see Figure 425).

Figure 425 : Selection of a signal

The signal Display is selected. The signal definition shows the signal along with its parameters - one parameter of type Charstring in the example.

  • If a channel, signal route or gate is selected, the signal definition holds one or two lines of information. Each line contains a list of all signals that are conveyed (see Figure 426).
    • The first line contains the signal list to the parent diagram
    • The second line contains the signal list from the parent diagram.

Figure 426 : Selection of a gate

The gate D, which is an in/out gate is selected. The signal definition shows one line with all in-signals (Door, Display) and one line with all out-signals (OpenDoor, DoorNo) in relation to the parent diagram (Controller)

  • If a signal list4 is selected, the signal definition holds one line of information containing a list of all signals contained in the signal list. The syntax is
SignalListName = Signal1, Signal2,...,SignalN
1

The term signal conveyor denotes a communication path that conveys signals; a channel, signal route, a gate or connection point.

2

The term "available" means defined and / or referenced.

3

Save of signal is also considered as input by the Signal Dictionary function.

4

A signal list is identified with its name within parentheses, such as
(SignalListName)


Menu Bars

The SDL Editor's menu bar provides commands available in menus and menu choices for editing diagrams and pages of diagrams. Most of the functionality that the SDL Editor offers is contained within the commands from the menu bar. The menu bar provides the following menus:

  • File Menu
  • Edit Menu
  • View Menu
  • Pages Menu
  • Diagrams Menu
  • Window Menu
  • Tools Menu
  • Help Menu

The File menu is described in "File Menu" and the Help menu in "Help Menu" .

In addition, other menus may appear; one is the Simulator menu which appears when you set breakpoints in the SDL Editor (see "Connect-To-Editor" ).

Edit Menu

The Edit menu provides editing functions that you can perform on the objects in the drawing area. The Edit menu functions that are available differ depending on the type of diagram you edit, either:

  • Interaction Diagrams
  • Flow Diagrams
  • Overview Diagrams

The Edit functions are as follows:

  • Undo
  • Cut
  • Copy
  • Paste
  • Insert Paste (available on flow diagrams only)
  • Paste As
  • Clear
  • Collapse/Expand
  • Redirect
  • Bidirect/Unidirect
  • Class...
  • Flip
  • Split Text
  • Dash/Undash
  • Drawing Size
  • Select All
  • Complete Word
  • Select Tail (available on flow diagrams only)
  • Symbol Border Color > Set Color...
  • Symbol Border Color > Set Default
  • Symbol Border Color > <Color>
  • Symbol Border Color > List All Colors...
  • Symbol Fill Color > Set Color...
  • Symbol Fill Color > Set Default
  • Symbol Fill Color > <Color>
  • Symbol Fill Color > List All Colors...
  • Symbol Visibility > Hide
  • Symbol Visibility > Show
  • Include Expression

Undo

With this command you restore the content of the drawing area to its state prior to the operation you performed most recently. It is only available for operations on symbols, lines and text attributes. You can undo the following operations:

  • Cut, Paste and Clear
  • Flip, Redirect, Bidirect/Unidirect
  • Adding Symbols
  • Moving Symbols
  • Resizing Symbols
  • Drawing Lines
  • Re-Routing and Reshaping Lines
  • Resizing a Page
  • Tidy Up.

Note: Undo for text editing

You cannot undo text editing operations, but an Undo function is available for text entered via the Grammar Help or Signal Dictionary functions. See "Undo" .

Note: Undo for Class Symbols

If a class symbol is cut and thus also cleared, Undo will be enabled. If the Undo command is used, operators will be restored, including their body code.

Cut

This command removes the current selection from the drawing area or text window, and saves it in the clipboard buffer. Also see "Deleting an Object" .

In text editing mode the command will work on the current text selection.

Copy

This command makes a copy of the current selection, and saves it in the clipboard buffer.

In text editing mode the command will work on the current text selection.

Paste

This command inserts the contents of the clipboard buffer into the drawing area or text window.

No lines will be drawn between the pasted symbols and the symbols already present in the drawing area.

You can interrupt the Paste operation by pressing <Esc>.

Also see "Pasting an Object" .

In text editing mode the text contents from the clipboard buffer will be inserted at the current text insertion point.

Note: Cut, Copy and Paste for Class Symbols

When a class symbol is cut or copied, defined body codes are saved on the clipboard, along with their operators. When a class symbol is pasted, previously copied body codes are inserted as well, unless an operator already has defined another body code.
If any operator will be deleted as a result of the operation, a warning is shown, the command is canceled and a dialog similar to the one in "Cutting, Copying and Pasting Class Symbols" is shown.

Insert Paste

This function has the similar functionality as the Paste function, but is only available for flow pages. It inserts necessary space after the selected symbol before pasting the clipboard buffer and connecting the two flows.

The function requires that the clipboard is not empty and that you have selected exactly one symbol or line. Otherwise, the menu choice is dimmed. The menu choice is also dimmed if connecting the two symbol flows would violate the Z.100 syntax rules.

The functionality differs depending on if you have selected a symbol or a line. If you have selected a symbol the pasted symbols are inserted following the selected symbol. If for example you have selected a decision, the Insert Paste command will create a new branch. Also if a line following the selected symbol joins another line and the selected symbol only can have one follower, the inserted symbols will be placed following both the lines.

If you have selected only a line the pasted symbols will be inserted onto that line. For example if a line following a decision is selected, the inserted symbols will be inserted into the selected decision branch.

Before inserting the selection, the SDL Editor allocates the necessary space by pushing the required objects downwards. If this is not possible, a dialog is displayed.

  • Clicking Increase Page in the dialog transfers control to the Drawing Size dialog, where you can specify the new width and height of the SDL page. The SDL Editor then carries on the operation and inserts the selection.

Paste As

Pastes the currently copied object (from the OM or Text Editor) as an SDL object in the drawing area. The object is transformed and a link is optionally created between the copied and pasted objects.

The Paste As dialog is opened. See "The Paste As Command" for more information.

Clear

This command removes the current selection from the drawing area or text window. The content of the clipboard buffer is not affected by this menu choice.

Also see "Deleting an Object" .

In text editing mode the current text selection will be removed.

Note: Deleting Class Symbols

When deleting a class symbol, a warning dialog is shown if an operator will be deleted as a result of this operation. See "Cut, Copy and Paste for Class Symbols" .

Collapse/Expand

This command is available for symbols that can be clipped. These are the package reference symbol, additional heading symbol, text symbol, comment symbol and text extension symbol. A collapsed symbol has the minimum size and an expanded symbol will automatically adjust its size to the text.

Redirect

This command changes the direction of a selected channel, signal route or gate. The new direction is denoted by changing the orientation and position of the arrow, leaving the arrowhead pointing in the opposite direction. Subsequent redirections result in the signal list toggling between two directions.

Note:

The only way to draw a channel from the environment to a symbol is to:
  1. Draw a channel from that symbol to the environment
  2. Redirect the channel.

Bidirect/Unidirect

This command changes the selected channel, signal route or gate to be bidirectional/unidirectional. The Bidirect command will generate a new arrowhead and an empty signal list. The Unidirect command will show a dialog asking what signal list that should be kept.

Class...

This command opens up the Browse & Edit Class Dialog. The command is available only when a single class symbol has been selected. The command is not available if the class name contains incorrect syntax.

Flip

This command creates a vertically symmetrical copy of the symbol(s) you have selected. It is valid on the following symbols only:

  • Input symbol
  • Output symbol
  • Priority input symbol
  • Text extension symbol
  • Comment symbol

The flow lines connected to a mirrored text extension symbol or comment symbol are redrawn in order to reconnect them to the opposite side.

Split Text

This command splits the text from a symbol and its associated text extension symbol (if any) into two parts, where the first part is placed in the symbol itself, and the second part in an associated text extension symbol. The split is done where the text insertion marker is, in the selected symbol.

To place all text in an associated text extension symbol, place the text insertion marker first in the text for a normal symbol and invoke this operation.

To remove an existing text extension symbol associated with a normal symbol, place the text insertion marker last in the text extension symbol and invoke this operation.

Dash/Undash

A dashed reference symbol is used in an SDL subtype when referring to an object that is defined elsewhere in one of the supertypes of the current subtype.

In a similar fashion, a dashed gate indicates that the gate is already defined in one of the supertypes in the inheritance chain.

Figure 427 : A dashed process reference symbol and a dashed gate

The Dash/Undash command is available on the following diagrams:

  • System Types
  • Block Types
  • Process Types
  • Service Types

The Undash is a toggle command.

Drawing Size

This menu choice sets the size of the drawing area for the current SDL page. A dialog is issued where you can type in the width and height. The values are saved on file when you save the diagram.

Note:

Enlarging the drawing, the current SDL page may not fit any longer into the paper that is defined with the Print preferences; the result may be an SDL page that requires multiple sheets of paper when printed.

Select All

This command selects all of the text contained in the text window or all objects within the drawing area.

Complete Word

Note:

You can also complete a word by having the mouse pointer in the drawing area and pressing the tab key, provided that the preference Editor*TabEqualsCompletion is true.

Word completion helps you complete long words that have already been used in the same context. Type the beginning of the already used word and invoke word completion to get the rest of the word. If there are several ways to complete the word, the word completion operation will initially give you the common part of the possible completions. If you invoke word completion again, you will get one of the alternatives. To get another alternative, invoke word completion once more.

Word completion takes the word closest to the current cursor position and tries to complete that word by adding characters at the end of the word.

The word completion operation uses the following sources to look for already used words:

  • The current diagram page.
  • Pages in the beginning of the diagram. The number of pages that the word completion operation examines is determined by the preference Editor*CompletionMaxPages.
  • The names of entities listed in any running index viewer. This makes it possible to reuse names from other diagrams than the current diagram.
  • All words listed in the file .../sdt/include/keywords/sdl.txt in the installation. As default, this file contains SDL keywords.

Select Tail

This command selects the currently selected symbol and all objects beneath it within the tree (following the flow lines).

Symbol Border Color > Set Color...

This command calls the color dialog where it is possible to set a custom color for the selected objects.

Symbol Border Color > Set Default

This command restores the default color for the selected objects. Default color for Symbol borders are set by the Preferences.

Symbol Border Color > <Color>

This command sets <Color> for the selected objects. Default available choices are Black, Blue, Green, Cyan, Red, Magenta, Yellow, and White. Custom colors are added to the menu when they are first used. The most recently used color is moved to the top of the list.

Symbol Border Color > List All Colors...

This menu choice becomes available when a maximum of 20 used colors has been surpassed. When you select List All Colors a dialog is issued containing all colors that has been used in the current SDL Editor session and you have the possibility to set them for the selected objects.

Symbol Fill Color > Set Color...

This command calls the color dialog where it is possible to set a custom color for the selected symbols.

Symbol Fill Color > Set Default

This command restores the default color for the selected symbols. Default fill color is set by the Preferences.

Symbol Fill Color > <Color>

This command sets <Color> for the selected symbols. Default available choices are Black, Blue, Green, Cyan, Red, Magenta, Yellow, and White. Custom colors are added to the menu when they are first used. The most recently used color is moved to the top of the list.

Symbol Fill Color > List All Colors...

This menu choice becomes available when a maximum of 20 used colors has been surpassed. When you select List All Colors a dialog is issued containing all colors that has been used in the current SDL Editor session and you have the possibility to set them for the selected symbols.

Symbol Visibility > Hide

This command hides the selected symbols. The hidden symbols will be replaced with a thick vertical line. The flow line structure will not be altered. The [Screen, Print]Z100Symbol preferences makes the replacement line as this as the flow line. See also Show hidden symbols and Include Expression.

Symbol Visibility > Show

This command restores the selected symbols.

Include Expression

This command displays a dialog, where it is possible to specify the include expression that is presented above the top left corner of a symbol, for the selected symbols.

The include expression is a name of a boolean variable (or external synonym). The value of the include expression is checked before analyzing an SDL system, when SDL/GR is converted to SDL/PR. Only those symbols that...

  • have no include expression
  • have an include expression that evaluates to true

...are included in SDL/PR and are visible for the analyzer and the code generator.

As default, all boolean variables have a value of false. To change a boolean value to true, an external synonym file (a plain text file with extension *.syn) must be created and placed close to the SDL system in the Organizer. The external synonym file closest to the SDL system will be used. An external synonym file contains lines of name value pairs. For instance:

DEBUG true
VERSION1 false
VERSION2 true

Note that all lines going to a symbol that is removed, will also be removed. An exception to this rule is that flow lines going to a symbol that will be removed, are reconnected to the first following symbol that will not be removed, if there is one and only one such symbol.

It is also possible to decide if SDL/GR symbols should be included or excluded in SDL/PR by hiding symbols. See "Analyze" , Symbol Visibility > Hide and Symbol Visibility > Show.

View Menu

The View menu provides rescaling functions and access to various options that affect the behavior of the SDL Editor.

The following menu choices are available in the View menu:

  • Set Scale
  • Temporary Colors > Remove
  • Temporary Colors > Make Permanent
  • Window Options
  • Diagram Options
  • Editor Options

Set Scale

Issues a dialog where you can adjust the scale.

Temporary Colors > Remove

Temporary colors are colors that are not saved in the SDL diagram. These colors are used by certain operations, such as SDL trace from SDL simulators and Compare Diagrams in the SDL editor, to highlight symbols of interest. Before doing a new operation that relies on color, it might be useful to remove already existing temporary colors. This can either be done by using this menu choice or by closing down the SDL editor.

Temporary Colors > Make Permanent

Temporary colors are explained in Temporary Colors > Remove. This menu choice is used to convert temporary colors into permanent colors that can be saved in diagram files for future use.

Window Options

This menu choice issues a dialog where you set the options that affect the window properties.

  • OK applies the options as defined in the dialog to the current window only.
  • All Windows applies the options as defined in the dialog to all windows opened by the SDL Editor.
  • Tool Bar determines whether the tool bar should be displayed or not.
  • Status Bar determines whether the status bar should be displayed or not.
  • Symbol Menu determines whether the symbol menu should be displayed or not.
  • Text Window determines whether the text window should be visible or not.
  • Page Breaks determines whether physical page breaks, with the appearance of dashed horizontal and vertical lines, should be displayed or not in the drawing area. These page breaks are defined by the print preferences; they show where the print utility will break the diagram into multiple printout pages.
  • Show Grid determines whether the current symbol grid points are shown as small markers.

Diagram Options

This menu choice issues a dialog where you set the options that affect the editing properties applied on the current diagram.

Interaction and Flow Diagram Options

A dialog with the following options is displayed on interaction and flow diagrams.

  • Use Grid
    This option determines whether or not the symbols that are added, resized or moved should adhere to the symbol grid or not. By default the symbol grid is active.
    By disabling the symbol grid, the SDL Editor will use the minimum grid of 5 * 5 mm.
  • Layout syntax check
    This option determines whether the SDL Editor should adhere to the formal SDL syntax rules regarding symbols and the connection of symbols. Ideally the layout syntax check should always be on.
    • Turning syntax checking off allows you to insert any symbol displayed in the symbol menu into the drawing area. In this mode, symbols can be interconnected in any manner. Furthermore, the connector symbol will always be treated as an inconnector in this mode. Therefore the Analyzer will detect errors when trying to analyze the diagram. To avoid problems turn off the syntax checking only if you want to draw diagrams that never should be analyzed.

Note:

Turning the switch from off to on will not perform a retroactive syntax check for not allowed or interconnection of symbols. Only the objects that you add while syntax checking is enabled are checked.

  • Textual syntax check
    This option determines whether the SDL Editor should perform a syntax check on all the texts in the diagram. Ideally the textual syntax check should always be on.
    • Turning syntax checking off disables the textual syntax check except for the kernel heading and the reference symbols which are always checked.
  • Additional Heading only on first page
    This option determines whether the SDL Editor should present the Additional Heading symbol on each page. When the option is on, only the first page in the diagram will show the Additional Heading symbol.

The diagrams options are also saved on file when the diagram is saved.

Overview Diagram Options

A dialog with the following options is displayed on overview diagrams.

  • Show line names
    This option governs whether the names of lines (such as channels and signal routes) should be displayed or not.
  • Show signal lists
    This option governs whether the signal lists associated to channels and signal routes should be displayed or not.

The diagrams options are also saved on file when the diagram is saved.

Editor Options

This menu choice issues a dialog where you can customize the behavior of the SDL Editor.

The options are controlled by toggle buttons. They are:

  • Always new Window
    This option indicates whether or not a new window should be opened whenever you select the New or Open command or any command from the Pages menu.
    The default behavior is not to open a new window.
  • Sound
    This option indicates whether or not improper actions in the SDL Editor, such as attempting to overlap symbols, should be brought to your attention by producing an alert sound.
    The default value for this option is on.
  • Show link endpoints
    This option indicates whether endpoint markers should be displayed for symbols having link endpoints. Regardless of the setting of this option, link endpoints are never shown when printed.
  • Use tab key for word completion
    See "Complete Word" .
  • Show hidden symbols
    This option indicates whether hidden symbols should be displayed as a vertical line. If this option is selected hidden symbols will be displayed normally but filled with a grid pattern.
  • Use informal view
    This option sets the editor in Informal mode. In informal mode the content of the symbols is substituted with the content of the attached comment symbol, if any. The comment symbols are hidden. Symbols without an attached comment symbol are displayed normally.
  • Show signal declaration
    This option decides if the signal declaration including parameters should be shown in the message area when a signal name is selected by clicking on it in the drawing area. Turn this option off if you think it takes too long for the editor to find the signal declaration. There is a preference deciding the default value of this option: Editor*ShowSignalDeclaration.

Pages Menu

The Pages menu contains the following menu choices:

  • First
  • <Page Name>
  • Last
  • Add
  • Edit
  • Edit Reference Page

First

This menu choice opens the first page contained in the diagram. The first page is defined according to the order of appearance in the Edit Pages dialog. If the page is already opened, its window is displayed.

<Page Name>

Activating the Page menu presents up to four menu choices that consist of the names of the two pages that are sequentially right before and after the page you edit. If you edit the first page of the diagram, the next four sequential pages are shown. If you edit the last page of the diagram, the previous four pages are shown.

When you select one of these page names, that page is opened or restored in the SDL Editor. Use the Edit menu choice if you want open other pages.

Last

This menu choice opens the last page of a diagram. See "First" for more information.

Add

This menu choice is a shortcut for adding one page to the current diagram. The Add Page dialog is issued and when you click OK the new page is shown.

Edit

This menu choice opens a dialog where you can Add, Rename, Clear, Cut, Copy and Paste an SDL Page. See "Page Editing Functions" .

Edit Reference Page

This menu choice opens (or, if already active, simply restores) the page in the parent diagram where the name of the current page is referred.

This menu choice is dimmed when the current page is one of the pages contained in the Organizer Root Document (in which case there is no parent diagram) or the diagram being edited is not known by the Organizer.

Diagrams Menu

The Diagrams menu records all diagrams and pages that are opened by the SDL Editor.

  • Back
  • Forward
  • <Diagram Name>
  • List All

Back

This menu choice opens the diagram that was previously visible in the same window.

Forward

This menu choice opens the diagram that was displayed in the window before you pressed the back button.

<Diagram Name>

The last edited page always goes to the top of the list, and subsequently moves the other diagrams and pages down a position. A maximum of 9 open pages can be shown. A tenth one will be put at the top of the list, but any subsequent opening of a diagram or page will only show the last 9 that have been opened. Another option - List All (at the bottom of the list) - is available to list all the open diagrams in the SDL Editor.

Each item in the menu provides information about the diagram type, its name, a slash (`/') followed by a page name, a hyphen and, possibly, the file it is stored on. A diagram that is preceded by an asterisk (`*') denotes that it has been modified during the SDL Editor session.

List All

This menu choice becomes available when a maximum of 9 open pages has been surpassed. When you select List All a dialog is issued containing all diagrams and pages that are currently open in the SDL Editor and you have the possibility to display them.

Window Menu

The Window menu contains the following menu choices:

  • New Window
  • Close Window
  • Grammar Help
  • Signal Dictionary
  • Class Information
  • Entity Dictionary
  • <Window Name>
  • List All

New Window

This command opens a new window containing a new view on the SDL page contained in the source window from where you selected this menu choice. You can edit the SDL page in any window.

Close Window

This option closes the open window, but, does not close the diagram. All but the last open window can be closed, the last one you must close from the File menu, possibly in conjunction with saving information (see "Close Diagram" ).

Grammar Help

This menu choice opens the Grammar Help window, see "Grammar Help and Signal Dictionary" . Its purpose is to assist you in editing SDL textual elements that are correct according to the SDL grammar.

Each SDL Editor window has its associated Grammar Help window.

The SDL Editor tries to open a file with grammar help templates when opening the Grammar Help window (which file to open by default may be specified as an SDL Editor preference). If the file cannot be located, a dialog is issued where you can choose to select it manually. The filter in the file selection dialog will be set to *.tpl.

Signal Dictionary

This menu choice opens the Signal Dictionary window, see "Using the Signal Dictionary" . It gives access to information about what signals are defined in an SDL hierarchy. Each SDL Editor window has its associated Signal Dictionary window.

Class Information

Opens the Class Information window. See "Class Information" for more information.

Entity Dictionary

Opens the Entity Dictionary window. See "The Entity Dictionary" for more information.

<Window Name>

If more than one editor window is open the other windows are listed here. The behavior of this list will be similar with the diagrams list in the Diagrams menu. The only difference is that the menu items will not provide the diagram file information.

List All

This menu choice is available only if more than 9 editor windows are open, and has the same functionality as the List All menu command in the Diagrams menu.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
  • Link > Create
  • Link > Create Endpoint
  • Link > Traverse
  • Link > Link Manager
  • Link > Clear
  • Link > Clear Endpoint
  • Search
  • Spelling > Comments
  • Spelling > All Text
  • Tidy Up
  • Connect to Text Editor
  • Navigate
  • Show > Definition of X
  • Show > Use of X
  • Show > Definition or Use of X
  • Show > Next (Definition or Use of) X
  • Show GR Reference
  • Create Bookmark
  • Compare Diagrams
  • Merge Diagrams
  • Add Differences
  • Generate PR

Show Organizer is described in "Show Organizer" and the Link commands are described in "Link Commands in the Tools Menus" .

Search

This menu choice opens a dialog that allows you to search for a text in the current diagram or document in any editor. You can search many diagrams and documents at the same time with this menu choice.

For more information about searching, see "Search" and "Searching and Replacing Text" .

Spelling > Comments

Check the spelling of comments in the current diagram. For more information about the spelling operation, see "Spelling > Comments" .

Spelling > All Text

Check the spelling of all text in the current diagram. For more information about the spelling operation, see "Spelling > Comments" .

Tidy Up

This menu choice rearranges the graphical layout of the entire SDL diagram, using default layouting algorithms when calculating the location and size of graphical objects. Before the tidy up operation is started, a dialog appears where you can adjust parameters to the operation:

  • Start transition on new page. Decides if a state symbol representing the beginning of a new transition should be placed on the same page as already placed symbols, or on a new page.
  • Use extra space after comment and text extension. Decides if a symbol in a flow, after a symbol with an associated comment or text extension, should be moved below the associated symbol or not.
  • Format input and output text. Decides if text in input and output symbols should be reformatted or not. If the text is reformatted, the signal name is placed in the symbol, while any parameters are placed in a text extension symbol.
  • Replace textual comments with comment symbols.
  • Place comment symbols to the left.
  • No text extension for state. Decides if text extensions should be used or not if the state name does not fit in the state symbol.
  • No text extension for decision. Decides if text extensions should be used or not if the decision text does not fit in the decision symbol.
  • Sort states and transitions. Decides the order state symbols (More precise: state and input symbol combinations) will be presented in the resulting diagram.

Connect to Text Editor

This command issues an external text editor and creates a temporary file from the currently selected text. After this you can only edit the text from the external editor. The SDL Editor is updated every time the external text editor saves the temporary file. When you no longer edit the temporary file the editing control returns to the SDL Editor.

Which external text editor you are to use is defined by the preference SDT*TextEditor.

Navigate

This command navigates to another diagram or to another symbol within the current diagram, depending on the selected symbol. It is available for the following symbols:

  • For a reference symbol it will show the diagram being referenced.
  • For an instantiation symbol it will show the corresponding type diagram. If there is more than one diagram that matches the type name, a dialog will appear where you can select one of the diagrams.
  • For a create request symbol the process diagram for the created process will be shown. If the diagram is ambiguous a selection dialog appears.
  • For a procedure call symbol the procedure diagram will be shown. If the diagram is ambiguous a selection dialog appears.
  • For a macro call symbol the macro definition will be shown.
  • For a state symbol another state or nextstate symbol using the same state name in the same diagram will be shown. A selection dialog will appear if there are more than one occurrence of the name.
  • For an inconnector symbol the corresponding outconnector symbol will be shown. If more than one outconnector exists a selection dialog appears.
  • For an outconnector symbol the corresponding inconnector symbol will be shown.
  • For a class symbol, another class symbol, using the same class name in the same diagram, will be shown. If there is more than one occurrence of the name, a select dialog is shown.

Double-clicking a symbol will have the same effect as using the Navigate command. This applies to all navigable symbols, except class symbols.

The Show Sub-menu

All menu choices in the Show sub-menu require a running index viewer loaded with an up-to-date cross reference file. You can get this for all SDL systems that passes through the SDL Analyzer, by pressing the Generate Index quick-button in the Organizer.

Show > Definition of X

This command takes the name of the word closest to the current cursor position as input. If the name represents an SDL entity listed in the index viewer, the SDL Editor will navigate to one of the definitions of that entity. Usually there is only one definition to show, but for states, each state symbol is considered to be a part of the definition and one of them is shown. If you invoke this command once more for the same state name, another state symbol is shown (if there are several).

Show > Use of X

This command takes the name of the word closest to the current cursor position as input. If the name represents an SDL entity listed in the index viewer, the SDL Editor will navigate to one of the uses of that entity. If you invoke this command once more for the same word, another use of that entity is shown (if there are several uses),

Show > Definition or Use of X

This command takes the name of the word closest to the current cursor position as input. If the name represents an SDL entity listed in the index viewer, a dialog is opened, allowing you to navigate to one of the definitions or uses of that SDL entity.

Show > Next (Definition or Use of) X

This command repeats the last Show > Definition of X, Show > Use of X or Show > Definition or Use of X command using the same word as last time as input.

Show GR Reference

This command issues a message where the graphical SDT reference for the object you have currently selected is displayed.

The syntax of the graphical references used in the SDL suite environments described in 19 SDT References.

Create Bookmark

This command creates a bookmark in the Organizer for the object you have currently selected.

Compare Diagrams

With this menu choice you can compare the contents of two SDL diagrams. See "Comparing And Merging Diagrams" .

Merge Diagrams

With this menu choice you can compare the contents of two SDL diagrams and create a new diagram by merging the two SDL diagrams. See "Comparing And Merging Diagrams" .

Add Differences

With this menu choice you can merge two SDL diagram versions into one. The SDL diagram that is visible in the editor when the operation is invoked will be updated with information from the other version, for all differences. Symbols from the other diagram might be placed slightly to the left of the original place, to avoid overlapping symbols.

Differences are marked with temporary color, except for complete page differences when a complete page is missing in the other diagram. The reason for this is to support merging of a complete diagram (the SDL diagram in the editor) with diagram parts (containing a subset of all pages in the complete diagram) that might be slightly different.

In the Add Differences dialog, it is possible to specify the other diagram to compare with, either by specifying a file name or by specifying another editor buffer. The Add Differences dialog also makes it possible to specify the temporary colors to use for highlighting differences.

Generate PR

This command will generate SDL/PR/CIF for the current diagram. A dialog with the following options appears:

  • PR file
    The name of the PR/CIF file to create.
  • Generate GR references
    This option will generate GR references that can be used to trace the PR code back to the GR diagram.
  • Generate CIF
    CIF is the standard defined in ITU recommendation Z.106 to be used when transferring SDL/GR diagrams preserving the graphical layout. With this option set, CIF comments will be generated together with the PR.

The File Menu of the Text Window

The File menu provides functions that transfer text from a file to the text window and vice-versa. The basic intention is to provide you the possibility to edit larger portions of text with a more suitable text editor (for instance signal definitions in text symbols). Another possibility to edit text externally is to use the Connect to Text Editor command in the Tools menu.

Import

Import imports the contents of a file into the text window and inserts the contents of the file at the text cursor position, possibly replacing selected text in the text window. In the file selection dialog, the filter is set to *.txt by default.

Export

Export exports the selected text to a file. If no text is selected in the text window, the entire text window contents will be exported to the file. In the file selection dialog, the filter is set to *.txt by default.

Menu Bar in Grammar Help Window and Signal Dictionary Window

These menu bars contains the following menus:

  • File Menu
  • Edit Menu
  • Select Menu
  • Tools Menu

File Menu

The File menu contains menu choices that access files that contain SDL Grammar Help templates.

These commands are useful only when requesting Grammar Help support.

Load

This command opens a file selection dialog, where you can select and load the file with grammar help definitions.

Grammar template files normally have the file extension .tpl. With the SDL suite, a standard template file, sdt.tpl, is enclosed. The SDL Editor attempts to locate a .tpl file each time you invoke the Load command.

Any template definitions that are already loaded will be replaced by the contents of the selected grammar help definition file.

Merge

Merge extends the current loaded grammar definitions with the contents of a grammar help definition file.

This command issues a file selection dialog, in which you can select and add a set of custom templates to the basic set provided in the SDL suite.

Any template definitions that are already loaded will be extended with the contents of the merged template definition file.

Edit Menu

The Edit menu provides two utility functions that you can use when copying text from the Grammar window or the Signal Dictionary window to the SDL Editor's text window.

Undo

You can revert changes with the Undo command.

Insert

This menu choice copies the entire contents of the Grammar field or the signal definition and copies it into the text window at the current I-beam cursor location. Selected text will thus be overwritten.

A shortcut for Insert is to double-click on the template name in the name field.

Replace

This command replaces the contents of the text window with the contents of the grammar field. This function is a shortcut for the following sequence:

  • "Select All, Clear and Insert" (Grammar Help)
  • "Select All and Insert" (Signal Dictionary)

Select Menu

The commands on the Select menu define what functionality the Grammar Help window and the Signal Dictionary window should provide.

Each of the options can be individually turned on and off. In addition, an Options menu choice (see "Options" ) allows you to enable and disable multiple options in one command only.

The options that are currently enabled are indicated by an asterisk (`*') preceding the corresponding menu choice.

When you invoke the Grammar Help, the Grammar option is enabled, while the remaining options are disabled.

These functions restrict or extend the scope of search for signals. The Signal Dictionary functionality can be extended to provide access to MSC Messages and an external signal library.

Grammar

This toggle option, when set to on, will enable the SDL Grammar Help function.

Up

This toggle option enables the Up option provided in the Signal Dictionary window. This option displays the SDL signals that are available when looking one level up in the SDL hierarchy.

This

Turning This on lists all signals that are used in the current diagram.

Down

This option displays the SDL signals that are available when looking one level down in the SDL hierarchy.

All

This option displays all signals that are defined and are visible according to the SDL scope rules, starting from the root document (see "Root Document" ) in the SDL System Structure chapter.

MSC

This option displays all messages that are available in the Message Sequence Charts that are submitted as input to the Signal Dictionary function. Each message is mapped to an SDL signal, with its parameters mapped to SDL signal parameters.

An MSC is submitted as input to the Signal Dictionary if associated to an SDL diagram that is present in the Organizer's diagram structure.

External

This option displays all signals that have been imported from an external signal dictionary. Importing external signals is done through the Telelogic Tau Public Interface. See "Load Definition File" .

Options

Issues a dialog where you can turn on and off all options individually (see "Select Menu" for a description of the options).

The default options for the Signal Dictionary are Up and Down.

Tools Menu

The Tools menu provide various convenience functions.

Show Editor

This command displays the parent SDL Editor window.

Show Definition

An SDL Editor comes up showing the definition of the item which is selected in the signal list.


Page Editing Functions

When you select Edit from the Pages menu, the Edit Pages dialog will be opened. In this dialog, you can add, rename, clear, cut, copy and paste an SDL page. The items in the dialog will be described below:

The Page List

This list includes all SDL pages in the SDL diagram. The operations available in the dialog, are only possible to perform if a page is selected in this list.

Edit

This button opens the selected page in the SDL Editor.

Cut

This button removes the selected SDL page from the diagram and saves it in the clipboard buffer. The information in the Organizer that is dependent on this page, will also be removed.

If the page contains reference symbols and these have an underlying structure in the Organizer this structure will be restored when you paste the page in a new position. See "Cutting, Copying and Pasting Reference Symbols" .

The button is dimmed if the object you have selected is not an SDL page.

Copy

This button copies the selected page to the clipboard buffer.

The button is dimmed if the object you have selected is not an SDL page.

Paste

This button pastes a previously cut or copied page into the current diagram.

The Paste button will be dimmed if:

  • The clipboard buffer is empty.
  • The current clipboard contents would lead to a syntax violation in the target diagram.

The SDL Editor checks that the contents of the page are syntactically correct. If required a warning will be issued. Then a new dialog is displayed, where you should assign the page a new name. You can specify:

  • The new name of the page (two pages with the same name are not allowed within a diagram)
  • Possibly, an autonumbered name (see "The Autonumbered Option" )
  • If the new page should be pasted before or after the current page

Clear

This button removes the selected SDL page from the diagram. A confirmation dialog will be issued before the page is removed, and the SDL Editor will automatically rename autonumbered pages.

Caution!

As stated in the dialog, Clear on a page cannot be undone.

If the page contains reference symbols and these symbols have a substructure, this substructure will be removed from the Organizer. As there is no undo for the Clear Page command, a warning will be issued and it is possible to keep the substructure as a new hierarchy instead.

Add

This button opens a dialog where you can change some settings before new page is created:

  • If autonumbering is turned off, you may specify any pagename, which must be in keeping with SDL conventions.
  • If autonumbering is on (the default), the page is automatically named using the next available sequential number within the diagram (1, 2, etc).
  • If the page is to be inserted before of after the current page.
  • If you add a page to a process or process type diagram, you can select if the new page should be a graph page (the default) or a service interaction page.
  • If you add a page to a block or block type diagram, you can select if the new page should be a block interaction page or a process interaction page.

New pages are listed in the same order that they were added.

Rename

This button opens a dialog where you can rename the selected SDL page. If the page is part of a block or block type diagram, you can also change the page type (process interaction page or block interaction page) in this dialog.

Autonumbered pages cannot be renamed, unless you turn the option The Autonumbered Option off first.

The Autonumbered Option

If the option Autonumbered is on, a numeric name (1, 2, etc) will be applied to the selected page. In a dialog, you can select to auto-number the selected page or all pages in the diagram.

The Open This Page First Option

If the option Open This Page First is on, the selected page will be the page that will be displayed by default when you open the diagram. Only one page at the time can have this option set.


Comparing And Merging Diagrams

Figure 428 : The Compare Diagrams dialog

Figure 429 The Merge Diagrams dialog

When you select Compare Diagrams or Merge Diagrams from the Tools menu, a dialog will be opened where you can select the SDL diagram to compare with. (It is also possible to compare more than one diagram pair in one operation, but to do this you should use the corresponding menu choices in the Organizer. See "Compare SDL Diagrams" and "Merge SDL Diagrams" .

Specifying the Diagram to Compare With

There are two ways for specifying the diagram that should be compared with the currently displayed diagram:

  • You may specify the file in the Compare with file field.
  • You may specify another diagram already opened the SDL Editor in the Compare with editor diagram field. When you click the folder button, a dialog will be opened with a list of all diagrams opened in the SDL Editor (except for the currently displayed).
    The option Compare with editor diagram has the two restrictions:
    • It can only be used if more than one diagram is opened in the SDL Editor.
    • The folder button can only be used if more than two diagrams are loaded into the SDL Editor.

Selecting the Report Type

In the Compare Diagrams dialog, there are six alternatives for reporting differences between diagrams: Ignore white space and double space in text symbols, Textual Difference Report: Summary, Textual Difference Report: Details, Graphical Difference Report (with Merge Facility) and Select and Print Differences.

The Merge Diagrams dialog does not allow you to get a textual difference report. Instead, you always get a graphical difference report and the only option available is Auto-merge using original file.

Ignore white space and double space in text symbols

When this option is on, differences caused by different usage of white space are ignored when comparing texts. One space character is considered equal to two space characters.

Textual Difference Report: Summary

This option is only available when comparing using the Compare Diagrams menu choice.

A summary of how many differences that has been found is presented in the Organizer log. The summary may look like this:

Comparing /home/lat/x.spr
with /home/lat/y.spr
27 differences (16 symbols, 11 lines) :
7 changed objects (7 symbols, 0 lines)
13 removed objects (6 symbols, 7 lines)
7 added objects (3 symbols, 4 lines)

When you read this report, notice the following:

  • 27 is the total number of found differences in this diagram pair. This is the total of all changed, removed and added objects.
  • An object is considered to be changed if you have moved or resized it, or if you have changed a text associated with the object.

If at least one of the two compared diagrams has more than one page, then a summary is also presented for each page pair. It may look like this:

Comparing /home/lat/version1/registeredcard.spt
with /home/lat/version2/registeredcard.spt
5 differences (1 symbol, 4 lines) :
1 changed object (1 symbol, 0 lines)
2 removed objects (0 symbols, 2 lines)
2 added objects (0 symbols, 2 lines)

Page details:

Page ValidateCard
5 differences (1 symbol, 4 lines) :
1 changed object (1 symbol, 0 lines)
2 removed objects (0 symbols, 2 lines)
2 added objects (0 symbols, 2 lines)

Page RegisterMode
0 differences

Textual Difference Report: Details

This option is only available when comparing using the Compare Diagrams menu choice.

This option will print information about each found difference in the Organizer log. This makes it possible to navigate from the Organizer log to every found difference by using the Show Error operation in the Organizer log. See "Organizer Log Window" .

The detailed textual difference report may look like this:

Comparing /home/lat/d1/db.sbk
with /home/lat/d2/db.sbk

Comparing page 1

#SDTREF(SDL,/home/lat/d1/db.sbk(1),119(50,35))
ERROR This symbol has been changed...
#SDTREF(SDL,/home/lat/d2/db.sbk(1),119(50,40))
ERROR ...and now looks like this.

#SDTREF(SDL,/home/lat/d1/db.sbk(1),176(95,60))
ERROR This symbol has been removed.

#SDTREF(SDL,/home/lat/d2/db.sbk(1),182(60,60))
ERROR This line has been added.

Graphical Difference Report (with Merge Facility)

The merge facility is only available when merging with the Merge Diagrams menu choice, but you can get a graphical difference report both when comparing with the Compare Diagrams menu choice and when merging with the Merge Diagrams menu choice.

Two SDL Editor windows, named Source 1 and Source 2, displaying the two diagram versions and their differences, and one dialog will be opened. For merge, there will be a third SDL Editor window, named Result, showing the merge result.

Figure 430 : The Merge Diagrams dialog

The Compare Diagrams dialog is similar to the Merge Diagrams dialog. The difference is that the Compare Diagrams dialog is missing the first row of buttons. ("<<", Accept1, Accept2 and ">>".)
In the dialog that will be opened, you can:
  • Navigate between difference groups with the Next and Previous buttons.
  • (Merge Diagrams only.) Navigate between unresolved (not-yet merged) difference groups with the "<<" and ">>" buttons.
  • (Merge Diagrams only.) Do a merge, i.e. update the merge result diagram with information from the current difference group and one of the compared diagram versions, with the Accept1/Reject1 and Accept2/Reject2 buttons.
  • Compare or merge a text in a text symbol in the current difference group.
  • Print the current difference found in the current page pair.
    When the second compare dialog is closed, the editor windows are restored to how they appeared before the compare operation.

Comparing text in text symbols

When two text-symbols differ the CompareText button will be available in the Text Compare dialog and it will be possible to enter the text-compare dialog.

The Text Compare dialog consists of two lists of text that are placed side by side with a "gutter" that will contain extra information about the differences. This gutter-information consist of:

    • A "-" indicates that there is no corresponding line in the text compared to the other text.
    • A "|" character indicates that this line differs in the two texts.

The current difference is indicated with a highlight. Buttons make it possible to navigate to Previous and Next difference item.

Figure 431 : The Compare Text Symbols dialog

Merging text in text symbols

When manual merges are conducted the option to merge text-symbols will always be available in the navigation dialog. When merging a button TextCompare button is available as in the compare function. When a text-symbol is selected there will be an option to select either symbol or merge the text in the symbols into a new symbol.

If the text merge is selected a text-merge dialog is presented with three text-lists, the two source texts and the result text. It is possible to navigate between the unresolved differences or between all differences.

Figure 432 : The Merge Text Symbols dialog

This works in the same way as in the normal merge. The buttons "<<" and ">>" will jump between the unresolved differences and the Previous and Next buttons will jump between all differences.

The use of Accept 1/Reject 1, Accept 2/Reject 2 buttons will select neither, either or both the texts for merge. The selections from the source files are presented in the result-list the gutter will show what version is selected. Additional symbols in the result list are:

    • A "|" character indicates that this line differs in the two texts.
    • A "=" character indicates that the selected text are equal in both versions.
    • A ">" character indicates that the right text has been selected for merge.
    • A "<" character indicates that the left text has been selected for merge.

It is also possible to edit the result line-by-line by selecting a line and edit it below the list. Clicking the Change button will replace the changed line in the result list.

Ignore moved or resized objects

If this option is on, the compare operation tries to ignore differences only caused by moved or resized symbols. You should only use this option if the two compared diagrams originates from the same diagram. (For instance, you have used Save as on the original diagram to get the second copy.) This option will not work well if you create two diagrams from scratch and compare them, because the operation uses object IDs to match moved or resized objects.

Select and Print Differences

If this option is on and there are differences, then a print dialog will pop up when the first dialog is closed. Only SDL diagram pages containing differences will be printed, and the differences will be highlighted with selection markers. If the same page containing differences can be found in both compared diagrams, then the two pages will be printed after each other, beginning with the page from the diagram that was visible in the editor when the compare operation was invoked.

Auto-merge using original file

This option is only available in the Merge Diagrams dialog. It allows you to specify the original diagram file that both the diagram versions that are compared originates from. If you specify the original diagram file, then the merge operation can auto-merge all non-conflicting changes for you. Note that if you give the wrong original diagram, then the auto-merge operation may merge the two versions in the wrong way. If you do not specify an original diagram, then the merge operation leaves all merging of differences to you.

Differences That Will Be Reported

When you use Compare Diagrams or Merge Diagrams, all visual object differences will be found:

  • An object that has been moved, resized, removed, added or painted in a different color.
  • A text, associated with an object, that has been changed

An object is considered to be moved if it has been moved relative to the upper left corner of the diagram frame. This means that if you move the frame, it will have no effect.

Diagrams are compared one page pair at a time. A page pair is one page from the original diagram and one page from the other diagram where both pages have the same name. If there is no page with the same name in the other diagram, then the complete page is considered to be a difference.

Difference Groups

Differing objects from the same page pair are grouped into difference groups. Two differing objects are placed in the same group if:

  • The objects are from the same diagram and they are connected to each other. For instance, a flow line connected to a task symbol.
  • The objects are from different diagrams and they would overlap if they were in the same diagram, that is, it would be impossible to place the two objects in the same diagram without changing the position within the diagram for one of them.
  • The objects are from different diagrams and the difference operation can conclude that it is the same object that has been moved.

Color and the Current Difference Group

In the graphical difference report, all differing objects are given temporary background colors as specified in the initial dialog. As default, the color is green in the original diagram and magenta in the other diagram. Temporary colors are not saved in diagram files. How temporary colors are removed is described in "Temporary Colors > Remove" .

The dialog that will be opened during the graphical difference report, allows you to navigate between difference groups using previous and next buttons. All objects in the current difference group are selected.

Normally, version 1 of the compared diagrams (the diagram that was in the SDL editor when the compare operation was invoked) is shown in a window in the top left corner of the screen. Version 2 (the diagram that was specified in the first compare dialog) is shown in the top right corner off the screen. For complete page differences (a difference where a page can not be found in the other diagram), the window that misses the page is hidden.

Note that it is possible to manually edit the compared diagrams while the compare operation is ongoing. This can be seen as a light-weight alternative to the full merge operation (described next).

Merging

During a merge operation, three windows are used in addition to the second merge dialog:

  • The top left corner of the screen is used to show version 1 of the compared diagrams, in the editor window named Source 1. This is the diagram that was visible in the SDL editor window when the merge operation was invoked.
  • The bottom left corner of the screen is used to show version 2 of the compared diagrams, in the editor window named Source 2. This is the diagram that was specified in the first merge dialog as the diagram to compare with.
  • The right part of the screen is used to show the merge result diagram, in the editor window named Result. This is a new diagram that has been created from the two compared diagram versions.

The second Merge dialog does not only have previous and next buttons to navigate between differences. It does also have Accept/Reject buttons and "<<" (fast backward) / ">>" (fast forward) buttons.

  • Pressing Accept 1 (2) will add symbols to the merge result diagram. It is the symbols from version 1 (2) of the current difference group that will be added.
  • Pressing Reject 1 (2) will remove symbols from the merge result diagram. It is the symbols that can be found in version 1 (2) of the current difference group that will be removed.
  • Pressing "<<" (fast backward) will navigate to the previous unresolved difference group. An unresolved difference group is a difference group where both version 1 and version 2 are not accepted.
  • Pressing ">>" (fast forward) will navigate to the next unresolved difference group.

Note that it is possible to manually edit diagrams while a merge operation is ongoing. This can be useful if you want the merge result diagram to look different from both version 1 and version 2 of the compared diagrams.

When the second merge dialog is closed, the editor will ask you to save the merge result by displaying a save dialog above the window with the merge result diagram buffer. When the save dialog is closed, the editor windows are restored to how they appeared before the merge operation was invoked.


GR to PR Conversion

It is possible to convert diagrams from SDL/GR to SDL/PR. In the conversion, SDL diagrams are translated from the binary files into PR files, possibly containing CIF information. All graphical symbols in that diagram will be replaced by their corresponding keywords and any text in the symbols will be copied to the output file. When possible, the definitions in the output file will appear in the same order as in the input.

The conversion is used by the SDL Analyzer as the first step in the analysis process, and also by the SDT2CIF Converter to convert to PR that preserve the graphical layout information. You can also convert to PR by the Generate PR command in the Tools menu, or by using the Public Interface (see "GRPR" ).

The PR/CIF files produced by the SDL suite fill various purposes:

  • As a way to export information to other SDL tools
  • As a temporary storage format that is used as input to the static and semantic analyzer
  • As a format that is suitable for reading by the user. To produce this format, the PR file should be pretty printed.

Mapping between GR and PR

The following list defines the mapping between the GR and PR forms:

  • In general, when symbols of the same type are converted, symbols are ordered first of all by the page ordering within the diagram. Within the same page symbols are ordered such that a symbol with a low y-coordinate (closer to the top) will be converted first. If two symbols have the same y-coordinate the symbol with the lowest x-coordinate is treated first.

Note:

The order in which text symbols are converted may be of importance when it comes to code generation issues. This is, in particular, applicable when using the SDL to C Compiler. Therefore, you should use one text symbol only for type definitions.

  • When analyzing systems using macros, all macros are converted to PR before they are expanded. This restricts the usability of macros, for instance the number of inlets and outlets must be 0 or 1.
  • A merge symbol (a flow line connected to another flow line) is translated to PR using join and label constructs. The labels introduced will be named grst0, grst1, and so on, starting on grst0 at each diagram. In macro diagrams, the labeling is grst0%MACROID... If the label already exists in the GR diagram, the sequential number is incremental until the label is unique.
  • A block diagram may contain a block substructure diagram without its frame and heading if the block diagram does not contain any definitions but the substructure. This rule is applied to all the pages in the block diagram that are of the block interaction type.
  • When specifying a header in GR, it must be specified according to the PR syntax and the valid input signal set should be written into the heading symbol and not in a text symbol as specified by the GR syntax.
  • References to graphical symbols, which will be used by the Analyzer in error messages, are stored in the PR file using SDL comments beginning with the character "#". It is therefore recommended that you do not write comments beginning with "#".
  • To be able to perform a correct conversion of SDL/GR Substructure diagrams to SDL/PR, the enclosing diagram type, block/channel or block type, must be known. For a channel going to the environment, a name outside the frame must be a gate name, generating the via construct, if the enclosing diagram is a block type, and a channel name, generating connect statements, for other cases.
    If nothing is known about the enclosing diagram type, it is assumed that the diagram is a block.
    To resolve the ambiguity, a qualifier can be used in the kernel heading to determine the enclosing diagram type. Alternatively the Analyzer directive #BLOCKTYPE can be used to indicate that the enclosing diagram is a block type diagram. This directive should be added to the diagram kernel heading.

Differences when generating CIF

In general the PR generated as input to the analyzer will be the same as generated for CIF but for some constructs there are differences due to language limitations or to get a better error detection.

  • The conversion of a graphical comment symbol differs dependent on if the translation is made to CIF or not. When converting to CIF, the PR generated is the <comment> PR construct; in other cases, including when performing Analysis, the graphical comment is converted to "/* text inside graphical comment symbol */".
  • This difference also applies to graphical connections. If a channel C1 has a graphical connector to the outer channel outerC and another channel C2 also has a graphical connector to outerC, but the points where outerC is drawn is not the same, the conversion for CIF will contain two connect statements:
/* CIF ... */
connect outerC and C1;
/* CIF ... */
connect outerC and C2;

This PR will produce a semantic error according to SDL-92, but will be correct when using SDL-96.
When using non-CIF conversion, the two graphical connections will be combined into one statement, provided that the two texts specifying outerC are lexically the same, thus writing outerC in one text and out_\nerC in the other (\n is a newline) will not be treated as the same text. They are still considered the same if only the case differs.
connect outerC and C1,C2;

  • When PR is generated for a macrodefinition the macro inlet and macro outlet symbols will differ whether CIF is generated or not. As there are no corresponding PR to these symbols nothing will be generated when generating CIF except of course for the CIF statements itself. For non-CIF a note will generated indicating that these symbols are present in the diagram.
/* Macro Inlet Symbol */
A task having no text or having only a note/comment is allowed in GR. The correct PR correspondence is the compound statement construct having an empty statement
task { };
As this PR will restrict the use of the simulator command Next-Symbol the PR generated for non-CIF is an empty informal text
task '';
For CIF the compound statement will be generated.
  • When generating non-CIF all unattached comments will be attached to a symbol that is closest to the comment. In this way the comment text will be generated as if the text belongs to this symbol.
  • CIF generation for the class symbol is not supported. The generation for non-CIF is described in "Class Information" .

Error and Warning Message

This section contains messages that may be produced during the GR to PR conversion.

When the Telelogic Tau Public Interface performs the conversion from GR to PR, the messages will be displayed in the Organizer log. The reply message on the service will indicate that the conversion has been done and it will also contain the number of errors produced.

If the conversion for some reason fails, the reply message will contain a text stating the kind of problem that has occurred. See further the GRPR service in the Public Interface.

ERROR 5001 Unexpected end of flow

This message indicates that a symbol has been found that has no following flowline and according to the SDL syntax there must be one. In addition to the error message the following line is generated in the PR:

***** Unexpected end of flow *****

WARNING 5002 More than one line entering macro outlet

This message indicates that inside a macro there are more than one line entering the macro outlet symbol. This situation should be avoided as this can lead to syntax errors (which are hard to track) if this macro is expanded inside decision branches.

The easiest way to avoid this situation is to add a no-action task symbol with the text `' and use this as the last symbol in the macro. Let all lines enter this task symbol and add a single line between this task and the macro outlet.


45 Symbols and Lines - Quick Reference

The following notations are included in the quick reference:

  • DP - Deployment Diagrams
  • HMSC - High-level Message Sequence Charts
  • MSC - Message Sequence Charts
  • OM - Object Model
  • SC - State Charts
  • SDL - Specification and Description Language

The quick reference contains all the symbols and lines in those diagrams in combination with a short explanation of when they may be used.

There is also a landscape oriented version of this document. It is called symref.pdf and is located in /pdf/files on the installation CD. If you want to make your own printout of the quick reference, that document is perhaps the most suitable.


Symbols and Lines in DP Diagrams

Symbols in DP Diagrams

Symbol | Name | Explanation
 | Node | Is used to describe a run-time physical object that represents a computational resource.
 | Component | Represents a physical, replacable part of a system that packages implementation.
 | Thread | Represents an OS thread.
 | Object | Represents an SDL entity (system, block or process).
 | Text | Contains comments relevant for the diagram or build script information. Is not connected to any other symbol.

Lines in DP Diagrams

Line | Name | Explanation
 | Association line | Defines an association between two node symbols. To create it, select one node symbol and drag the association line handle (a rectangle). To create a line breakpoint, click in the diagram background. To attach the association line to its final destination, click the border of the associated node symbol.
 | Composite Aggregation line | Defines that the symbol connected to the simple line end is contained in the symbol connected to the diamond line end. To create it, select the container symbol and drag the aggregation line handle (a diamond). To create a line breakpoint, click in the diagram background. To attach the aggregation line to its final destination, click the border of the contained symbol.


Symbols and Lines in HMSC Diagrams

Symbols in HMSC Diagrams

Symbol | Name | Explanation
 | Start | The start symbol in an HMSC diagram. Is followed by a condition, reference or a condition point symbol.
 | Stop | The last symbol in an HMSC diagram.
 | Condition | Represents a system or process state, or indicates that a certain condition is true. Contains the name of the represented state or condition.
 | Reference | References another MSC or HMSC diagram in the same group of MSC diagrams. Contains the name of the other diagram.
 | Connection point | Splits or joins lines. One to many, many to one, or many to many.
 | Text | Contains comments relevant for the diagram. Is not connected to any other symbol.

Lines in HMSC Diagrams

Line | Name | Explanation
 | HMSC line | Defines how symbols can be traversed. Starts below the from-symbol and ends above the to-symbol. From-symbols can be start, condition, reference and connection point. To-symbols can be stop, condition, reference and connection point. To create the line, select a start, condition, reference or connection point symbol (a from symbol), and drag the line handle. To create a line endpoint, click in the diagram background. To attach the line to its final destination, click the symbol border.


Symbols and Lines in MSC Diagrams

Symbols in MSC Diagrams

Symbol | Name | Explanation
 | Text | Contains comments relevant for the diagram. Is not connected to any other symbol.
 | Comment | Contains comments relevant for a part of the diagram. Is connected to a symbol, a message sending or a message reception.
 | Instance head | Represents an instance of something that can communicate by sending and receiving messages. The "start symbol" for a created or an already existing instance.
 | Instance end | Used for graphically ending an instance axis without terminating the represented instance.
 | Message | Represents a signal sending from one instance to another. Is connected to at least one instance axis. Usually connected to an instance axis in both ends.
 | Condition | Represents a system or process state, or indicates that a certain condition is true. Contains a name of the represented state or condition. Is initially connected to one instance axis, but should often be connected to all.
 | Timer | Represents the use of a timer in an instance. Is connected to an instance axis. One symbol represents both a timer set and either a timeout or a reset.
 | Action | Is a kind of text symbol and is connected to an instance axis. Describes something that is happening in the instance.
 | Create process | Describes the creation of an instance. The arrow should go from an instance axis (the creator) to an instance head (the creator instance). The instance head is created when the create process symbol is initially laid out.
 | Process stop | Terminates an instance. The instance ceases to exist. Is connected to an instance axis.
 | Coregion | Creates a part of an instance axis where the order of received and sent signals is undefined. Is connected to an instance axis.
 | MSC reference | References another MSC or HMSC diagram in the same group of MSC diagrams. Contains the name of the other diagram. Is initially connected to one instance axis, but can be connected to several.
 | Inline expression | Is used for specification of alternative or optional parts (that is, message sending sequences) which are contained in the symbol. Is initially connected to one instance axis, but should most likely be connected to several.
 | Inline expression separator | Creates a new partition in an inline expression symbol. Initially, the inline expression symbol only contains one partition.

Lines in MSC Diagrams

Line | Name | Explanation
 | Message | Is used for defining a message sending and/or a message reception. Is at least connected to one instance axis, but is usually connected to an instance axis in both ends. Create it from the symbol menu.
 | Create process line | Is used for defining the creation of an instance. The arrow should go from an instance axis (the creator) to an instance head (the created instance). Create the process line from the symbol menu. When the create process arrow is initially laid out, the instance head is created.
 | Comment line | Associates a comment symbol with another symbol. To create it, select the comment symbol and drag the line handle to another symbol. Note that it is also possible to attach the comment symbol to a message sending or a message reception, by dragging the line handle to a connection point between a message and an instance axis.


Symbols and Lines in OM Diagrams

Symbols in OM Diagrams

Symbol | Name | Explanation
 | Class | Specifies a class. Contains three sections: Name, attributes and operations.
 | Object | Specifies an object instantiated from a class. Contains two sections: Name and attribute values
 | Text | Contains comments relevant for the diagram. Not connected to any other symbol.

Lines in OM Diagrams

Line | Name | Explanation
 | Generalization line | Defines that the class connected to the simple line end inherits from the class connected to the triangle line end. To create it, select the class symbol to inherit from and drag the generalization line handle (a triangle). To create a line break point, click in the diagram background. To attach the generalization line to its final destination, click the border of the inheriting class symbol.
 | Aggregation line | Defines that the class connected to the simple line end is contained in the class connected to the diamond line end. To create it, select the container class symbol and drag the aggregation line handle (a diamond). To create a line breakpoint, click in the diagram background. To attach the aggregation line to its final destination, click the border of the contained class symbol.
 | Association line | Defines an association between two class symbols. To create it, select one class symbol and drag the association line handle (a rectangle). To create a line breakpoint, click in the diagram background. To attach the association line to its final destination, click the border of the associated class symbol.
 | Link class line | Defines a class connected to an association line or an aggregation line. To create it, select an association or an aggregation line and drag the link class handle. The class symbol is created at the same time. There can only be one class symbol connected to one association or aggregation line.


Symbols and Lines in SC Diagrams

Symbols in SC Diagrams

Symbol | Name | Explanation
 | State | Represents a state in a state machine. May contain sub states when hierarchical state machines are specified. Is connected to other states via transition lines.
 | Start | The start symbol on a level in a state chart. Is followed by a transition to a state symbol.
 | Termination | Terminates a state machine. The state machine ceases to exist.
 | Text | Contains comments relevant for the diagram. Is not connected to any other symbol.

Lines in SC Diagrams

Line | Name | Explanation
 | Transition line | Defines a transition between two states. Is also used for defining the start transition and the last transition, by connecting a state symbol with either a start symbol or a termination symbol. To create it, select the start symbol or a state symbol and drag the transition line handle. To create a line breakpoint, click in the diagram background. To attach the transition line to its final destination, click the border of a state or termination symbol.


Symbols and Lines in SDL Diagrams

Symbols in Both SDL Structure and Behavior Diagrams

Symbol | Name | Explanation
 | Class | Defines a newtype. Contains three sections: Name, attributes and operators.

Symbols in SDL Structure Diagrams

Symbol | Name | Explanation
 | Text | Declares SDL entities such as signals and data types.
 | Comment | Contains comments in the diagram. Is attached to other symbols.
 | Text extension | Is attached to other symbols. Used if the text in another symbol is too large for the symbol. Put the last part of the text or the complete text in the text extension symbol.
 | Block reference | References a block diagram in a system, system type, sub-structure, block or block type diagram. Also used for instantiation of a block type.
 | Process reference | References a process diagram in a block or block type diagram. Is also used for instantiation of a process type
 | Block substructure reference | References a substructure diagram from a block or block type diagram.1
 | Service reference | References a service diagram in a process or process type diagram, from a service interaction page. Also used for instantiation of a service type.
 | Procedure reference | References a procedure diagram from any other diagram.
 | System type reference | References a system type diagram from a package diagram.
 | Block type reference | References a block type diagram from a package, system, system type, block or block type diagram.
 | Process type reference | References a process type diagram from a package, system, system type, block or block type diagram.
 | Service type reference | References a service type diagram from a package, system, system type, block, block type, process or process type diagram.
 | Operator reference | References an operator diagram from any other diagram.
 | Gate | Defines a gate in a block type, process type or service type diagram. Is attached to the diagram frame.
1

Not often used, because "block A in block C" is a commonly used shorthand for the more syntactically correct "block A in substructure B in block C".

Symbols in SDL Behavior Diagrams 1(2)

Symbol
Name
Explanation

State
Defines a state or terminates a transition in an already defined state. Is followed by an input, save continuous signal or priority output signal.

Input
Receives a signal. Always preceded by a state symbol. Together, they define the start of a transition. Is followed by the behavior of the transition.

Save
Saves signals from being discarded when being received in the current state (that does not handle the signal). Always preceded by a state symbol. Is not followed by any symbols.

Output
Sends a signal from a transition

In/out connector
Out connector: A jump/join/goto symbol that finishes the definition of a transition on one page, if there is not enough space. Is always associated via a name with an in connector that continues the definition.
In connector: The label symbol that is followed by the rest of the transition.

Procedure call
Calls a procedure that does not return a value from a transition. (A value returning procedure is called from a task symbol.)

Create request
Creates an instance of a process in a transition

Enabling condition/ continuous signal
Enabling condition: Is preceded by an input symbol. Contains a boolean expression that decides if the transition below it should be taken or not.
Continuous signal: Is preceded by a state symbol. Is followed by the behavior of a transition. Contains a boolean expression that is continuously evaluated while in the state. The following transition is taken when the expression evaluates to true.

Priority input
Specifies that this signal reception has higher priority than normal signal reception in the same state. Primarily intended to give signals between services in the same process higher priority than other signals. Not often used.

Procedure start
The start symbol in a procedure diagram. Is followed by the behavior of the start transition.

Procedure return
The symbol in a procedure diagram that finishes the execution of the procedure and returns to the procedure caller.

Procedure
reference
References a procedure diagram from any other diagram.

Gate
Defines a gate in a block type, process type or service type diagram. Is attached to the diagram frame.

Symbols in SDL Behavior Diagrams 2(2)

Symbol | Name | Explanation
 | Text | Declares the SDL entities such as variables, timers and types.
 | Comment | Contains comments in the diagram. Is attached to other symbols.
 | Text extension | Is attached to other symbols. Used if the text in a symbol is too large for the symbol. Put the last part of the text or the complete text in the text extension symbol.
 | Decision | Specifies alternative paths in the behavior part of a transition. Contains an expression. Each path is labeled with an answer that should match the expression for the path to be taken.
 | Task | Is used for writing textual code in the behavior part of a transition. Contains for example variable assignments, for-loops and calls of value returning procedures.
 | Macro call | Calls a macro diagram in the behavior part of a transition. Macros are a depreciated feature of SDL, consider using procedures or diagram inheritance instead.
 | Transition option | Specifies alternative paths in the behavior part of a transition. Similar to a decision symbol, but the expression must be built up of constants and (external) synonyms that can be evaluated once before execution of the system starts. Not often used.
 | Start | Starts the execution of the current diagram instance in a process, process type, service or service type diagram. Is followed by the definition of the behavior of the start transition.
 | Stop | Stops the execution of the current diagram instance in a process, process type, service or service type diagram.
 | Macro inlet | The start symbol in a macro diagram. Macros are a depreciated feature of SDL, consider using procedures or diagram inheritance instead.
 | Macro outlet | The end symbol in a macro diagram. Macros are a depreciated feature of SDL, consider using procedures or diagram inheritance instead.
 | Operator reference | References an operator diagram from any other diagram.

Lines in Both SDL Structure and Behavior Diagrams

Line | Name | Explanation
 | Comment line | Associates a comment symbol with another symbol. To create it, select the comment symbol and drag the line handle to another symbol.
 | Text extension line | Associates a text extension symbol with another symbol. To create it, select the text extension symbol and drag the line handle to another symbol.
 | Gate line | Defines a gate in a block type, process type or service type diagram. To create it, select it from the symbol menu and attach it to the diagram frame.
 | Aggregation line | Defines that the class connected to the simple line end is contained in the class connected to the diamond line end. To create it, select the container class symbol and drag the aggregation line handle (a diamond). To create a line breakpoint, click in the diagram background. To attach the aggregation line to its final destination, click the border of the contained class symbol.
 | Association line | Defines an association between two class symbols, can be unidirected or bidirected. To create it, select one class symbol and drag the association line handle (a rectangle). To create a line breakpoint, click in the diagram background. To attach the association line to its final destination, click the border of the associated class symbol.

Lines in SDL Structure Diagrams Only

Line | Name | Explanation
 | Channel | Defines a part of a communication path for signals, either between two blocks or between one block and the environment (i.e. the diagram frame). To create it, select a block symbol and drag the line handle. To make line breakpoints, click in the diagram background. To attach the line to its final destination (either another block or the diagram frame), click the symbol border. After creation, the channel can be reversed or made bidirectional. The arrow is movable and an arrow at the end of the channel indicates that the channel does not delay signals being sent.
 | Signal route | Similar to a channel. The differences are that a signal route connects to processes and services instead of blocks, and that a signal route arrow cannot be moved around.
 | Create line | Defines that the process where the create line starts, can create instances of the process where the create line ends. The create line is optional. To create it, select the process symbol and drag the create line handle. To make line breakpoints, click in the diagram background. To attach the create line to its final destination, click the symbol border.

Line in SDL Behavior Diagrams Only

Line | Name | Explanation
 | Flow line | Defines the order that symbols are executed in. Starts at the bottom of a symbol and ends at the top of another symbol. To create it, select a symbol that can be followed by other symbols and drag the flow line handle. To make line breakpoints, click in the diagram background. To attach the flow line to its final destination, click the symbol border. Note that two symbols can only be connected with a flow line if the SDL syntax rules allow it.


46 The SDL Type Viewer

The Type Viewer shows SDL-92 types and type instances in the current system and how they relate to each other.

This chapter contains a reference manual to the Type Viewer; the functionality it provides, its menus, windows and symbols.


Objects and Windows

Objects and Attributes

An object in the Type Viewer is either a type or an instance of a type. Both of these may be referred to as a type in the Type Viewer and in this chapter. For each type object, the following attributes can be presented:

  • A graphical symbol to identify the type of diagram. The symbols are identical to the icons used in the Organizer's Main window (see "Icon Types" ). The symbol is always shown.
  • The type identifier, in the form
    <virtuality> <diagram type> <object type>, where:
    • <virtuality> may be either
      Virtual, Redefined or Finalized
    • <diagram type> may be either
      System, Block, Service or Process
    • <object type> may be either
      Type or Instance
  • The name of the type or instance
  • The complete qualifier, in text form.

You can hide or show each of the last three text items. By default, the type identifier and the type name is shown.

You can open an SDL Editor by double clicking on a symbol in the Type Viewer. If a type symbol is double clicked, an SDL Editor is opened with that type diagram. If an instance symbol is double clicked, an SDL Editor is opened with the diagram that contains the instance.

Type Viewer Windows

The Type Viewer has two windows, the list window and the Tree window, which present the type information in the system in two different ways. The main window lists the type objects without showing inheritance or redefinition relations between them, whereas the Tree window shows such relations for a type object in a tree form. Both windows can display all of the object attributes above, but in somewhat different ways.

The Main window is opened when the Type Viewer is started, whereas the Tree window is not opened initially. The general characteristics of these windows are described in 1 User Interface and Basic Operations.

Updating the Type Viewer

When the Type Viewer is started, it extracts type information from the current system. If, for any reason, there are problems extracting type information, you are warned in a dialog and details can be found in the Organizer log window. You may update the information in the Type Viewer at any time, with the Update command.

The Type Viewer obtains the information about what types are defined in the SDL scope from the Information Server. The Information Server updates its contents each time an SDL diagram is saved. When the diagram is saved, the Analyzer is invoked and produces a mirrored image which is an SDL/PR description of the SDL/GR diagram. That information is then loaded into the Information Server which serves the Type Viewer with information upon request. All of this is done automatically without the user having to bother about performing any actions.

Error Reporting

Note:

In order to extract signal information from a diagram, the diagram needs to be syntactically correct in the sense that SDL/PR code can be generated from the SDL/GR diagram without encountering errors.

Any errors are appended to the Organizer log window. For a reference to error messages that may be produced by the Information Server, see "Information Server Error Messages" .


Main Window

The Drawing Area

The main window's drawing area contains a simple line-oriented list of all types in the current SDL system. No inheritance or redefinition relations are shown. The object attributes are listed in the following way (see Figure 433):

Type identifier Type name
<< Qualifier >>

The qualifier is displayed within double angle brackets on a single text line, with slashes separating the path items.

In the list, the type objects are sorted alphabetically according to the diagram type, object type and type name, i.e. all objects of the same diagram type are grouped together.

Figure 433 : Main window

When you select a type or instance in the main window, the Tree window is updated and displays the relation trees that contain the selected type/instance. If the Tree window has not been opened earlier in the same Type Viewer session, the Tree window is opened automatically.

The Menu Bar

File Menu

The File menu contains the following menu choices:

  • Update
  • Print
    (See "Printing from the SDL Suite" .)
  • Exit
    (See "Exit" .)

Update

Updates the type list in the main window and the type trees in the Tree window, according to the possibly changed SDL diagrams (see "Updating the Type Viewer" ).

This command should be used whenever changes that might have an impact on the type inheritance are applied to any of the SDL diagrams contained in the diagram structure.

View Menu

The View menu contains the following menu choices:

  • Window Options
  • List Options
  • Symbol Options
  • Set Scale

Window Options

Sets options for which parts of the main window to show. The dialog controls whether to show the tool bar and the status bar.

List Options

Sets options for which symbols to include in the list in the main window. The dialog controls whether to show Instance symbols (type symbols are always shown).

Symbol Options

Sets options for which attributes to show for each type object in the list in the main window. The dialog controls whether to show the Qualifier, the Type identifier, and the Name of the types and instances.

Set Scale

Issues a dialog where the scale for the main window may be set.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
    (See "Show Organizer" .)
  • Search
  • Search Again
  • Show in Editor
  • Show Type Trees

Search

Searches for a visible text in the type list shown in the Main window.

Figure 434 : The Search dialog

  • Search for
    Specifies the text string to search for. As a special case, a GR Reference obtained from for instance an editor may also be specified.
  • Ignore Case, Consider Case
    These options toggles between a case insensitive and a case sensitive search.
  • Search
    Starts the search and closes the dialog. The first symbol containing the text is selected. The search starts from the selected symbol, if any, or from the first symbol in the list.

If the search reaches the end of the list, you are asked whether to continue the search from the top of the list or not.

If the text cannot be found among the visible information, you are informed in a confirmation dialog.

Search Again

Searches again for the same text as in the latest search. The behavior is the same as described in "Search" .

Show in Editor

Shows the selected type or instance in an SDL Editor. If a type symbol is selected, an SDL Editor is opened with that type diagram. If an instance symbol is selected, an SDL Editor is opened with the diagram that contains the instance.

Show Type Trees

Opens or raises the Tree window. The type or instance selected in the Main window becomes selected in the Tree window.

Popup Menus

The following tables lists the menu choices in the Main window popup menus and a reference to the corresponding menu choice in the menu bar.

On the Main Window Background

Search | "Search" .
Search Again | "Search Again" .
Show Type Trees | "Show Type Trees" .

On a Symbol in the Main Window

Search | "Search" .
Search Again | "Search Again" .
Show in Editor | "Show in Editor" .
Show Type Trees | "Show Type Trees" .

Keyboard Accelerators

Apart from the general keyboard accelerators, the following accelerator can be used in the main window:

Accelerator
Reference to corresponding command

 Ctrl+E
"Show in Editor"


Tree Window

The Drawing Area

The Tree window's drawing area visualizes inheritance and redefinition relations between types by presenting the types and instances in a tree form. There are two types of trees displayed in the Tree window:

  • A Redefinition tree shows virtual types, specializations based on redefinition of the virtual types, and all instances of these types.
  • An Inheritance tree shows types, specializations based on inheritance and adding properties to the types, and all instances of these types.

The two trees for a certain type are often, but not always, identical. The Type Viewer supports you by checking if they are identical; if so, they are shown as one tree. When the Inheritance and Redefinition trees are different, both are shown separately. Each tree has a header identifying which type of tree it is.

The object attributes are listed vertically in the trees in the following way (see Figure 435):

The qualifier is displayed in italics in a multi-line form, with each path item on a separate line. No angle brackets or slashes are used.

In the tree, the type objects with the same parent are placed from left to right alphabetically according to the diagram type and object type.

Figure 435 : Tree window

The Tree window is updated when the selection in the Main window is changed. The Tree window is updated to show the Inheritance and Redefinition trees in the system that contain the type/instance that is selected in the Main window. The first occurrence of that type/instance also becomes selected in the Tree window.

It is possible to view all Inheritance and Redefinition trees in the current system at once in the Tree window (see "Show All Trees" ). The trees are lined up vertically in the same drawing area.

The Menu Bar

File Menu

The File menu contains the following menu choices:

  • Print
    (See "Printing from the SDL Suite" .)
  • Close
    (See "Close" .)

View Menu

The View menu contains the following menu choices:

  • Expand
  • Expand Substructure
  • Expand All
  • Collapse
  • Window Options
  • Tree Options
  • Symbol Options
  • Show All Trees
  • Set Scale

Expand

Expands the selected object one level down.

Expand Substructure

Expands the selected object as much as possible.

Expand All

Expands all visible trees as much as possible.

Collapse

Collapses the selected object, i.e. hides all child objects. If there is no selected object, the menu choice is named Collapse All. Collapse All collapses all trees in the window.

Window Options

Sets options for which parts of the Tree window to show. The dialog controls whether to show the tool bar and the status bar.

Tree Options

Sets options for which symbols to include in the trees in the Tree window. The dialog controls whether to show instance symbols (Type symbols are always shown).

Symbol Options

Sets options for which attributes to show for each symbol in the trees in the Tree window. The dialog controls whether to show the Qualifier, the Type identifier, and the Name of the types and instances.

Show All Trees

Shows type trees for all types in the system.

Set Scale

Issues a dialog where the scale for the Tree window may be set.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
    (See "Show Organizer" .)
  • Search
  • Search Again
  • Show in Editor
  • Show Type Viewer

Search

Searches for a text in the type trees shown in the Tree window.

Figure 436 : The Search dialog

  • Search for
    Specifies the text string to search for. As a special case, a GR Reference obtained from for instance an editor may also be specified.
  • Ignore Case, Consider Case
    These options toggles between a case insensitive and a case sensitive search.
  • Search
    Starts the search and closes the dialog. The first symbol containing the text is selected. The search starts from the selected symbol, if any, or from the first symbol in the first tree.

If the search reaches the end of the trees, you are asked whether to continue the search from the first tree.

If the text cannot be found, you are informed in a confirmation dialog.

Search Again

Searches again for the same text as in the latest search. The behavior is the same as described in "Search" .

Show in Editor

Shows the selected type or instance in an SDL Editor. If a type symbol is selected, an SDL Editor is opened with that type diagram. If an instance symbol is selected, an SDL Editor is opened with the diagram that contains the instance.

Show Type Viewer

Raises the Type Viewer's Main window.

Popup Menus

The following tables lists the menu choices in the Tree window popup menus and a reference to the corresponding menu choice in the menu bar.

On the Tree Window Background

Search | "Search" .
Search Again | "Search Again" .
Show All Trees | "Show All Trees" .
Show Type Viewer | "Show Type Viewer" .
Expand All | "Expand All" .
Collapse All | Collapse all top objects in all trees.

On a Symbol in the Tree Window

Search | "Search" .
Search Again | "Search Again" .
Show in Editor | "Show in Editor" .
Show All Trees | "Show All Trees" .
Show Type Viewer | "Show Type Viewer" .
Expand | "Expand" .
Expand Substructure | "Expand Substructure" .
Collapse | "Collapse" .

Keyboard Accelerators

Apart from the general keyboard accelerators, the following accelerator can be used in the Tree window:

Accelerator
Reference to corresponding command

 Ctrl+E
"Show in Editor"


47 The SDL Index Viewer

The Index Viewer shows all definitions of SDL entities in a system and where they are used. The Index Viewer uses cross reference files produced by the Analyzer.

In previous versions of Telelogic Tau, the Message Sequence Chart Editor could also produce listings of definitions and references from an MSC. These older listings are also supported by the Index Viewer.

This chapter contains a reference manual to the Index Viewer; the functionality it provides, its menus, windows and symbols.


Entities and Windows

Definitions and Uses

SDL

The SDL Analyzer has the ability to generate files containing SDL cross references. See the Analyzer command described in "Set-Xref" , and the Organizer's Analyzer option described in "Generate a cross reference file" . These files use a textual format that is human readable; the purpose of the Index Viewer is to provide a means to take advantage of this information in the graphical environment. SDL icons are used when displaying the contents of the files in a graphical way.

MSC

In previous versions of Telelogic Tau, the Message Sequence Chart Editor featured the generation of MSC cross references. These entities had properties that were similar to SDL cross references. Where possible, a direct mapping from MSC to the corresponding SDL concept were made. A few concepts were added so that all information of interest could be extracted from an MSC.

MSC icons identify the various MSC entities graphically, and are supported for backward compatibility reasons.

SDL Icons

Each type of SDL entity has a unique name and icon used in the Index Viewer. The different SDL diagram types use the same icon and type name as in the Organizer's Main window. For other types of entities, the following icons and names are used:

Icon | Name
 | OPERATOR
 | PACKAGE_INTERFACE
 | CHANNEL
 | SIGNALROUTE
 | GATE
 | INPUT
 | OUTPUT
 | CONNECTION
 | CREATE
 | TASK
 | SIGNAL
 | SIGNALLIST
 | GENERATOR
 | FPAR; PROCESS_PARAM, PROCEDURE_PARAM (actual param.)
 | STATE
 | NEXTSTATE
 | TIMER
 | LABEL (in-connector, out-connector)
 | INSTANTIATION
 | SET
 | USE
 | INHERITS
 | JOIN
 | STATE_LIST
 | ATLEAST
 | DECISION
 | SAVE
 | DCL; VARIABLE
 | NEWTYPE; SYNTYPE; SORT
 | SYNONYM
 | RESET
 | IMPORT; IMPORT_DEF (i.e. Imported)
 | LITERAL
 | VIEW; VIEW_DEF (i.e. Viewed)
 | REMOTE_PROCEDURE
 | REMOTE_VARIABLE
 | SIGNALSET
 | ACTIVE
 | TRANS_OPTION (i.e. transition option)
 | EXPORT
 | ENAB_COND (i.e. enabling condition)
 | CONT_SIGNAL (i.e. continuous signal)
 | NUMBER_INST (i.e. number of instances)
 | EXPORTED_PROCEDURE
 | (PROCEDURE) CALL
 | REFERENCE
 | FIELD
 | Unknown symbol type. Used for diagrams when the type of the diagram for some reason could not be determined.

MSC Icons

Each type of MSC entity has a unique name and icon used in the Index Viewer. The MSC diagram uses the same icon as in the Organizer's Main window. For other types of entities, the following icons and names are used:

Icon | Name
 | CONDITION
 | CREATE of instance
 | INPUT of message
 | INSTANCE head
 | OUTPUT of message
 | RESET of timer
 | SET of timer
 | STOP of process
 | TIMEOUT (expire of timer)
 | Unknown symbol type. Used for diagrams when the type of the diagram for some reason could not be determined.


Index Viewer Window

All entities defined in the system are listed in alphabetical order in the Index Viewer window. The entities are sorted alphabetically according to either name, or type and name. For each entity, there may be a list of uses of the entity. The general characteristics of the window is described in 1 User Interface and Basic Operations.

The Drawing Area

The window contains a list of all definitions of entities in the current SDL system or the current MSC diagram. The first line in the list gives the name of the current cross reference file.

For each entity, the following information is presented:

  • An icon identifying the type of entity (see "SDL Icons" and "MSC Icons" )
  • The name and type of the entity.
  • A reference to the diagram the entity definition is located in.
  • The number of definitions with an asterisk in front, if more than one definition of the entity exists (in SDL diagrams, it is only states that can have multiple places of definition for one entity).
  • The number of cross references found (only for SDL entities; not applicable to MSC entities)

Figure 437 : The Index Viewer window

To double click on a defined entity in the window is the same operation as Show Definition in the Tools menu (see "Show Definition" ). If there are several definitions associated with the entity, one of them is selected. If you double click again, another definition is selected. The list of definitions associated with the entity is traversed in a circular pattern.

To double click on a use in the window is the same operation as Show Use in the Tools menu (see "Show Use" ). If there are several uses associated with the symbol, one of them is selected. If you double click again, another use is selected. The list of uses associated with the reference symbol is traversed in a circular pattern.

Fast Search

There is a fast search operation available when the Index Viewer drawing area has the input focus. Just start typing on the keyboard, and the list of entities will be searched from the top. The first matching entity will be selected.

Note that the fast search operation will only match if what you type matches the beginning of the text for an entity. For instance: If you type "Ga", you will find the entity Game_On if the entities are sorted with name first, while you will not find it if you type "On". The normal Search operation does not have this restriction.

The search string used by the fast search operation will be reset whenever any other operation than the fast search operation is performed. For instance, if you have typed "Ga" and the index viewer has found the entity Game_On, and you select another entity and start typing again, then the search string used for the search operation will not contain the initial "Ga" characters (and the fast search operation will start searching from the top of the list).

It is possible to use the delete character to correct any spelling mistakes. You can see what you have typed in the message area. Matched characters are shown in non-capital letters, while unmatched are shown in capital letters.

The Menu Bar

File Menu

The File menu contains the following menu choices:

  • Open
    (See "Open" .)
  • Print
    (See "Printing from the SDL Suite" .)
  • Exit
    (See "Exit" .)

View Menu

The View menu contains the following menu choices:

  • Window Options
  • Index Options
  • Filter Types
  • Filter Uses
  • Filter Diagrams
  • Set Scale

Window Options

Sets options for which parts of the Main window to show. The dialog controls whether to show the tool bar and the status bar.

Index Options

Determines the appearance of each entity in the window.

Figure 438 : The Index Options dialog

The following alternatives are available:

  • Compact:

  • Vertical Compact:

  • Horizontal Detailed:

  • Detailed:

Filter Types

Determines which entity types to show/hide in the entity list. A dialog is opened with a sorted list of all entity types found in the current cross reference file:

Figure 439 : The Filter Types dialog

The figure shows some entity types for an SDL system. See "MSC Icons" for a list of MSC entities.

  • Show
    Shows entities in the Index Viewer window that have a type that is selected in the dialog. Entities with other types are hidden.
  • Hide
    Hides entities in the Index Viewer window that have a type that is selected in the dialog. Entities with other types are shown.
  • Show All
    Shows entities of all types in the Index Viewer window.

An SDT preference, FilterTypes can be set to an initial list of entities to show or hide whenever the Index Viewer is opened. Another SDT preference, ShowSelectedTypes, determines if the mentioned types should be shown or hidden. See "FilterTypes" .

Filter Uses

Determines which uses to show/hide. The dialog works in the same way as the dialog for Filter Types. The associated SDT preferences are named FilterUses and ShowSelectedUses.

Figure 440 : The Filter Uses dialog

Filter Diagrams

Hide/show entities based on which diagram they are defined in. The dialog works in the same way as the dialog for Filter Types. The most common use of this operation is to hide definitions from the SDL predefined package. The associated SDT preferences are named FilterDiagrams and ShowSelectedDiagrams.

Figure 441 : The Filter Diagrams dialog

Set Scale

Issues a dialog where the scale for the Tree window may be set.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
    (See "Show Organizer" .)
  • Search
  • Search Again
  • Show Definition
  • Show Use

Search

Searches for a visible text in the entity list shown in the Main window.

Figure 442 : The Search dialog

  • Search for
    Specifies the text string to search for. As a special case, a GR Reference obtained from for instance an editor may also be specified.
  • Ignore Case, Consider Case
    These options toggles between a case insensitive and a case sensitive search.
  • Search
    Starts the search and closes the dialog. The first symbol containing the text is selected. The search starts from the selected symbol, if any, or from the first symbol in the first tree.

If the search reaches the end of the trees, you are asked whether to continue the search from the first tree.

If the text cannot be found among the visible information, you are informed in a confirmation dialog.

Search Again

Searches again for the same text as in the latest search. The behavior is the same as described in "Search" .

Show Definition

Opens an editor containing the specified definition of the entity selected in the entity list. The diagram symbol containing the definition becomes selected in the editor.

The name and behavior of this menu choice depends on the number of existing definitions for the selected entity:

  • If only one definition exists, that definition is shown in the editor.
  • If more than one definition exists, a separate menu choice is available for the first 9 definitions: Show Definition 1, Show Definition 2, etc. The specified definition is shown in the editor.
  • If more than 9 definitions exist, an additional menu choice Show Definition ... is available. This menu choice opens a dialog in which the number of the definition can be specified.

Show Use

Opens an editor, showing the selected use of an entity. The Show Use operation works in the same way as the Show Definition operation.

Popup Menus

The following tables lists the menu choices in the window's popup menus and a reference to the corresponding menu choice in the menu bar.

On the Window Background

Search | "Search" .
Search Again | "Search Again" .

On an Entity in the Window

Search | "Search" .
Search Again | "Search Again" .
Show Definition | "Show Definition" . The same menu choice variations apply.

Keyboard Accelerators

Apart from the general keyboard accelerators, the following accelerator can be used in the main window:

Accelerator
Reference to corresponding command

 Ctrl+E
"Show Definition"

Quick Buttons

The following quick button is special to the Index Viewer window. The general quick buttons are described in "General Quick-Buttons" .

Toggle Order
Switches the entity sort order between name and type and name.


48 The SDL Coverage Viewer

The Coverage Viewer shows the coverage of a simulation or validation in the terms of executed transitions or symbols in the system. The information used by the Coverage Viewer can be stored in a coverage file with the file extension .cov.

Coverage files can be generated by the SDL Simulator and the SDL Validator.

This chapter contains a reference manual to the Coverage Viewer; the functionality it provides, its menus, windows and symbols.


Coverage Viewer Windows

The Coverage Viewer has two windows, the Main window and the Coverage Details window. The Main window graphically shows the simulation or validation coverage of transitions or symbols in a tree corresponding to the system structure. The Coverage Details window shows a more detailed coverage chart for a node in the tree.

The Main window is opened when the Coverage Viewer is started, whereas the Coverage Details window is not opened initially. The general characteristics of these windows are described in 1 User Interface and Basic Operations.

The Main Window

The Main window shows a graphical tree representing the diagram structure of the simulated or validated system. The tree can either present Transition Coverage or Symbol Coverage; the mode is controlled by a user option. When the Coverage Viewer first opens a coverage file, the preference ShowTransitions is used to determine the default mode.

At the top of the drawing area, above the root of the tree, is a text identifying the type of coverage tree (transition/coverage) and the name of the current coverage file.

In the tree, the different SDL diagram types use the same icons as in the Organizer's main window. For an explanation of all other icons, see "SDL Icons" .

Transition Coverage

When the tree shows transition coverage, the lowest level in the tree consists of transitions, represented by a small SDL input symbol. Both states and transitions are visible below the process and procedure diagrams in the tree structure. The start transitions are treated as all other transitions, even though they are represented in the tree by an SDL start symbol.

Figure 443 : Transition coverage in the Main window

Symbol Coverage

When the tree shows symbol coverage, the lowest level in the tree consists of symbols corresponding to SDL symbols found in flow diagrams.

Figure 444 : Symbol coverage in the Main window

Nodes

Each node in the tree consists of three parts:

Figure 445 : A coverage node

  • A graphical symbol indicating the type of node, either:
    • In SDL systems containing packages, an extra root node named "(total)" is introduced, showing the grand total for the system and all packages
    • An SDL diagram (for instance, Figure 445 shows a process type symbol)
    • An SDL state
    • A transition (start transition or input of signal/timer)
    • Any symbol that can be found in SDL flow diagrams
      The graphical notation uses the same symbols as in SDL, where applicable. See also "SDL Icons" .
  • The name of the node is presented as text below the symbol (in Figure 445, the name of the process type is "Door"). An exception to this is the symbols at the lowest level in a symbol coverage tree. These symbols are shown without a name.
  • The number of executed transitions/symbols associated with the node is presented below the name. For symbols above the lowest level of the tree, a range is also shown indicating the number of times the least and most executed transition/symbol below the node has been executed. The process type symbol in Figure 445 reads
    "2 (0 - 1)" which means that:
    • Two transitions/symbols have been executed.
    • The least frequently executed transition / symbol in process type Door has been executed zero times.
    • The most frequently executed transition / symbol in process type Door has been executed once.

Line Thickness

The number of executed transitions/symbols shown below the node symbol also controls the thickness of the vertical line connecting the node with its parent node.

The line thickness thus gives a visual clue about how much the different branches of the tree have been executed, expressed as a relative number. The thicker the line, the more the tree branch has been executed.

Filling Level

In each node symbol, the number of transitions/symbols that have been executed at least once in relation to the total number of transitions/symbols in that node is also displayed. This is done by filling the node symbol with a gray pattern, showing the percentage level (number of executed divided by total number).

The higher the filling level, the more transitions/symbols have been executed. Figure 445 for instance shows that 50% of the total number of transitions/symbols have been executed.

Dashed Nodes

The visibility condition determines if nodes should be shown or not. A node that should not be shown according to the visibility condition can be visible anyway because a child node is shown. To indicate that a visible node does not match the visibility condition, the node is drawn with a dashed line.

The Visibility Condition

When the Coverage Viewer first opens a coverage file, every node in the coverage tree is shown. You can hide and show nodes in two ways, either via the expand/collapse mechanism (see "View Menu" ), or via the visibility condition.

By using the visibility condition, you can control which nodes should be visible or not. Only those nodes that meet the visibility condition are shown in the tree, and you cannot use the expand mechanism to see nodes that do not meet the visibility condition.

The visibility condition is a threshold value for the number of times a transition/symbol is executed. It is specified with the Set Visibility menu choice in the Tree menu (see "Set Visibility" ). It can also be changed by quick buttons, as well as the Increase Tree and Decrease Tree menu choices in the Tree menu.

A node in a fully expanded tree is visible either if:

  • The number of executed transitions/symbols associated with the node meets the visibility condition.
  • At least one of the underlying nodes is visible.

The symbol of a node that meets the second condition but not the first one becomes dashed to indicate that the node itself does not meet the visibility condition.

Single and Double Clicks

When you select a node in the main window, the Coverage Details window is updated and displays the coverage chart for the selected node. The Coverage Details window must be opened by the Show Details menu choice in the Tools menu.

To double-click on a symbol in the main window opens an SDL Editor with a diagram that corresponds to the selected symbol. See "Show in Editor" for more information.

Quick Buttons

The following quick buttons are special to the Main window. The general quick buttons are described in "General Quick-Buttons" .

Coverage Type
Switches between a transition coverage tree and a symbol coverage tree in the Main window.

Show Bottom
Changes the appearance of the coverage tree to show only those transitions/symbols that have been executed the least number of times, i.e. having a number of executions exactly equal to the lowest number of available executions. This command changes the visibility condition.

Show Top
Changes the appearance of the coverage tree to show only those transitions/symbols that have been executed the most number of times, i.e.
having a number of executions exactly equal to the highest number of
available executions. This command changes the visibility condition.

Show Whole Tree
Changes the appearance of the coverage tree to show all transitions/symbols. The visibility condition is reset to zero or more (>=0).

Show Details Window
Pops up (opens/raises) the Coverage Details window.

The Menu Bar

File Menu

The File menu contains the following menu choices:

  • Open
    (See "Open" .)
  • Open Directory
  • Merge
  • Save
    (See "Save" .)
  • Print
    (See "Printing from the SDL Suite" .)
  • Exit
    (See "Exit" .)

Open Directory

This menu choice is used to merge information from all coverage files (*.cov) in one directory.

Note:

It is only possible to merge coverage files created from the same SDL system, i.e. the Open Directory operation will fail if there are coverage files from different SDL systems in the same directory.

A directory selection dialog is opened. The first coverage file in the specified directory is opened, and all other coverage files in the specified directory are merged. The resulting coverage information is presented in the main coverage window.

Merge

Reads an additional coverage file about the same system and merges the coverage information in it with the current coverage information. A File Selection Dialog is opened with the file filter set to *.cov. The contents of the main window is augmented by the additional information read from the selected file.

It is not possible to merge coverage files with another system.

View Menu

The View menu contains the following menu choices:

  • Expand
  • Expand Substructure
  • Expand All
  • Collapse
  • Window Options
  • Set Scale

Expand

Expands the selected node one level down.

Expand Substructure

Expands the selected node as much as possible.

Expand All

Expands all nodes as much as possible.

Collapse

Collapses the selected node, i.e. hides all child objects. This menu choice is named Collapse All if no node is selected. Invoking the Collapse All menu choice collapses the top node.

Window Options

Sets options for which parts of the Main window to show. The dialog controls whether to show the tool bar and the status bar.

Set Scale

Issues a dialog where the scale for the main window may be set.

Tree Menu

The Tree menu contains the following menu choices:

  • Tree Options
  • Symbol Options
  • Line Options
  • Increase Tree
  • Decrease Tree
  • Set Visibility

Tree Options

Sets options for which type of coverage tree to show in the main window. The dialog controls whether to show either:

    • Transition Coverage
    • Symbol Coverage

Symbol Options

Sets options for how to show execution numbers for the nodes in the coverage tree. The dialog controls whether to show the numbers for

    • Every node,
    • the Bottom nodes only, or
    • Do not show numbers at all.

Line Options

Sets options for controlling the line thickness of the nodes in the coverage tree.

Figure 446 : The Line Options dialog

  • Normal line thickness
  • Logarithmic line thickness
    The dialog controls whether to show Normal line thickness or Logarithmic line thickness, i.e. the thickness is proportional either to the executed number of transitions/symbols, or to the logarithm of the same number.
  • Max line thickness
    With a slide bar, you may also specify the Max line thickness, measured in 1/10 mm. The possible range of values is 1-200. The default is 60, which is the thickness of the line connecting the top node of the tree.

Increase Tree

Shows more of the coverage tree by calculating a visibility threshold (see "The Visibility Condition" ) that makes at least one more symbol become visible.

Decrease Tree

Shows less of the coverage tree by calculating a visibility threshold (see "The Visibility Condition" ) that makes at least one more symbol become hidden.

Set Visibility

Sets options to control the visibility condition of the coverage tree (see "The Visibility Condition" ).

Figure 447 : The Set Visibility dialog

The dialog controls:

  • Threshold
    The value which may be set with the slide bar,
  • Show symbols executed >= threshold
  • Show symbols executed <= threshold
    The option whether to make nodes visible that are executed more than or less than the threshold value.

Tools Menu

The Tools menu contains the following menu choices:

  • Show Organizer
    (See "Show Organizer" .)
  • Search
  • Search Again
  • Show Coverage
  • Show in Editor
  • Show Details

Search

Searches for a visible node name in the coverage tree shown in the Main window.

Figure 448 : The Search dialog

  • Search for
    Specifies the text string to search for. As a special case, a GR Reference obtained from for instance an editor may also be specified.
  • Ignore Case, Consider Case
    These options toggles between a case insensitive and a case sensitive search.
  • Search
    Starts the search and closes the dialog. The first symbol containing the text is selected. The search starts from the selected symbol, if any, or from the first symbol in the tree.

If the search reaches the end of the tree, you are asked whether to continue the search from the first node.

If the text cannot be found among the visible information, you are informed in a confirmation dialog.

Search Again

Searches again for the same text as in the latest search. The behavior is the same as described in "Search" above.

Show Coverage

Opens an SDL Editor for all the transitions/symbols that meet a certain threshold condition in the tree below the selected symbol. The diagram symbols corresponding to the transitions/symbols become selected in the SDL Editor.

Figure 449 : The Show Coverage dialog

The dialog controls the Editor threshold value with a slide bar, as well as whether to show transitions/symbols that are executed, either:

  • less than
  • equal to
  • more than

the threshold value.

The Show button displays all diagram pages containing transitions or symbols that meet the threshold condition, one page at a time, with a confirmation dialog between each page.

Transitions (represented by the input symbol) or symbols matching the threshold condition are selected and colored with a temporary background color. The temporary background color can be removed with SDL editor > View > Temporary Colors > Remove. The temporary background color is also removed when the diagram is unloaded from the editor.

There is a No Dialog button in the confirmation dialog that can be used to avoid displaying the confirmation dialog for each page with symbols to show.

Note:

The editor threshold condition specified in this dialog does not affect the visibility condition. It only controls which transitions/symbols to show in an SDL Editor.

Show in Editor

Opens an SDL Editor with a diagram that corresponds to the selected symbol. If the selected symbol is located in a process or procedure diagram, the corresponding diagram symbol becomes selected in the diagram. Only applicable on transition/symbol icons at the lowest level in the tree, including start states.

Show Details

Opens or raises the Coverage Details window, showing a coverage chart for the selected node.

Popup Menus

The following tables lists the menu choices in the main window popup menus and a reference to the corresponding menu choice in the menu bar, or the corresponding quick button.

On the Main Window Background

Show Bottom | "Show Bottom" .
Show Top | "Show Top" .
Show Whole Tree | "Show Whole Tree" .
Show Details | "Show Details" .
Expand All | "Expand All" .
Collapse All | Collapses the whole tree, i.e. only the top node becomes visible.

On a Node in the Coverage Tree

Show in Editor | "Show in Editor" .
Expand | "Expand" .
Expand Substructure | "Expand Substructure" .
Collapse | "Collapse" .

Keyboard Accelerators

Apart from the general keyboard accelerators, the following accelerator can be used in the main window:

Accelerator
Reference to corresponding command

 Ctrl+E
"Show in Editor"


Coverage Details Window

The Coverage Details window presents more detailed coverage information for the node selected in the Main window. It contains a coverage chart for transitions or symbols, depending on what type of tree is shown in the main window. Above the chart is a text identifying:

  • The type of coverage chart
  • The type and name of the node
  • The total number of executed transitions/symbols.
  • The number of covered transitions/symbols.
  • The number of not covered transitions/symbols.

The Coverage Details window is updated when the selection in the Main window is changed. The Coverage Details window is updated to show the coverage chart for the node selected in the Main window.

Figure 450 : Coverage Details window

The Coverage Chart

The coverage chart shows how many transitions/symbols in the node that have been executed a certain number of times:

  • The horizontal axis denotes the number of times a transition/symbol is executed; the range of the axis is the same as the range shown for the node in the Main window.
  • The vertical axis denotes the number of transitions/symbols that has been executed a specific number of times; the range of the axis cannot generally be determined from the values shown for the node in the Main window.

For each value along the horizontal axis (no of times), a vertical bar shows how many transitions/symbols have been executed that specific number of times. The vertical axis scale is adjusted to include the highest vertical bar, but this can be changed by using the Chart Options menu choice in the View menu (see "Chart Options" ), or the quick buttons.

The left most bar is automatically selected when a new coverage chart is displayed. The selection can be moved by using the left and right arrow keys. Double clicking on a bar in the chart executes the Show in Editor command, see "Show in Editor" .

Just below the horizontal axis is the visibility line. It underlines the bars that correspond to the visible nodes in the coverage tree in the Main window. "Visible" in this case means visible according to the visibility condition. Nodes that are hidden by collapsing a parent node are still regarded as visible in this context.

Quick Buttons

The following quick buttons are special to the Coverage Details window. The general quick buttons are described in "General Quick-Buttons" .

Show in Editor
Corresponds to the description in "Show in Editor" .

Increase Vertical Scale
Increases the vertical scale of the coverage chart by decreasing the value of the upper range of the vertical axis. Those bars that "overflows" the range of the vertical axis are shown with an up arrow at the top of the bars to indicate that the bars in reality are higher.

Decrease Vertical Scale
Decreases the vertical scale of the coverage chart by increasing the
value of the upper range of the vertical axis. The reverse of the Increase Vertical Scale quick button above.

Show Coverage Tree
Pops up the Coverage Viewer's main window (the Coverage Tree window).

The Menu Bar

File Menu

The File menu contains the following menu choices:

  • Print
    (See "Printing from the SDL Suite" .)
  • Close
    (See "Close" .)

View Menu

The View menu contains the following menu choices:

  • Window Options
  • Chart Options
  • Set Scale

Window Options

Sets options for which parts of the Coverage Details window to show. The dialog controls whether to show the tool bar and the status bar.

Chart Options

Sets options controlling the appearance of the coverage chart.

The dialog controls the value of the upper limit of the vertical axis in the chart and whether to:

  • Show visibility line
  • Hide Visibility line

Set Scale

Issues a dialog where the scale for the Coverage Details window may be set.

Tools Menu

The Tools menu contains the following menu choices:

  • Show in Editor
  • Show Coverage Tree

Show in Editor

Opens an SDL Editor for all the transitions/symbols of the selected vertical bar in the coverage chart. The diagram symbols corresponding to the transitions/symbols become selected in the SDL Editor.

A confirmation dialog is displayed between each diagram page.

Show Coverage Tree

Raises the Coverage Viewer's main window.

Popup Menu

The following table lists the menu choices in the Coverage Details window popup menu and a reference to the corresponding menu choice in the menu bar.

Show Coverage Tree
"Show Coverage Tree" .

Keyboard Accelerators

Apart from the general keyboard accelerators, the following accelerators can be used in the Coverage Details window:

Accelerator
Reference to corresponding command

 Ctrl+E
"Show in Editor"


49 The SDL Simulator

This chapter is a reference to the simulator user interface.

For a guide to how to use the simulator, see 50 Simulating a System.


The Simulator Monitor

A simulator generated by the SDL suite consists of two main parts; the application itself (the simulated SDL system), and an interactive monitor system. The monitor system is the interface between the user and the simulated system. For more information on the structure of a simulator and the features of the simulator monitor, see "Structure of a Simulator" .

Monitor User Interfaces

Two different user interfaces are provided for the simulator monitor, a textual and a graphical.

The textual interface only allows commands to be entered from the keyboard, using the syntax described in the section "Syntax of Monitor Commands" .

The graphical interface still allows commands to be entered from the keyboard in the same way, but also provides buttons, menus and dialogs for easy access to commands and other features.

The textual interface is invoked by executing the generated simulator directly from the operating system prompt. This is called running a simulator in textual mode. When started, the simulator responds with the following text:

Welcome to SDL SIMULATOR. Simulating system <system>

Command :

Another prompt may appear if the SDL system contains external synonyms. For more information, see "Supplying Values of External Synonyms" .

Note:

Before a simulator can be run in textual mode on UNIX, a command file must be executed from the operating system prompt. The file is called telelogic.sou or telelogic.profile and is located in the binary directory that is included in the user's path.
For csh-compatible shells: source <bin dir>/telelogic.sou
For sh-compatible shells: . <bin dir>/telelogic.profile

The graphical interface, known as the Simulator UI, runs in a separate window. It is started from the Organizer by selecting SDL > Simulator UI from the Tools menu. The Simulator UI is described in "Graphical User Interface" .

If a file called siminit.com exists in the current directory an implicit Include-File command will be done on this file at startup.

Activating the Monitor

Commands can be issued to the interactive monitor system when it becomes active. The simulator's monitor system becomes active:

  • When the simulator is started.
  • When the last command was Next-Transition or Next-Visible-Transition and the transitions initiated by this command have completed.
  • When the last command was Next-Symbol or Step-Symbol and one SDL symbol has been executed.
  • When the last command was Next-Statement or Step-Statement and one SDL statement has been executed.
  • When the last command was Finish and the currently executing procedure has returned.
  • When the last command was Proceed-Until and the value of the simulation time is, for the first time, equal to the time given as a parameter to the command.
  • When the last command was Proceed-To-Timer and all transitions up to the next timer output have been executed.
  • Immediately before a transition matching a transition breakpoint set by the command Breakpoint-Transition.
  • Immediately before a symbol matching a symbol breakpoint set by the command Breakpoint-At.
  • Immediately after an output symbol that contains an output matching an output breakpoint set by the command Breakpoint-Output.
  • Immediately after a symbol or assignment statement where a variable is changed matching a variable breakpoint set by the command Breakpoint-Variable.
  • When there is no transition that can be executed, that is, the system is completely inactive. (On UNIX, if no environment is present and the command Go-Forever was issued.)
  • Immediately after a symbol that included an SDL semantic error.
  • In the Simulator UI, when the Break button is clicked in the Execute button module; in textual mode, when <Return> is pressed during the output of trace information. The interactive monitor then becomes active directly after the current symbol has been executed.

Note:

No other characters may be typed before <Return> is pressed.


Syntax of Monitor Commands

The monitor system waits for commands from the user by issuing the following prompt:

Command :

The syntax to be used for the commands and their parameters are described in the following.

Command Names

A command name may be abbreviated by giving sufficient characters to distinguish it from other command names. A special character, the hyphen (-), is used to separate command names into distinct parts. Any part may be abbreviated as long as the command name does not become ambiguous.

Consider, as an example, the command name List-Process. The command name may be typed List-P or L-P. However, if only List is typed, the monitor system will respond with the message

Command was ambiguous, it might be an abbreviation of:

followed by a list of all commands starting with "List," since the command cannot be distinguished from, for example, the commands List-Ready-Queue and List-Timer.

There is no distinction made between upper and lower case letters when matching command names.

Parameters

Command parameters are separated by one or several spaces, carriage returns or tabs. A colon is also accepted between a process name and an instance number, when a PId value is required. If the parameter list following a command name is not complete the interactive monitor system will ask for the missing parameters by prompting with the type of the expected parameters.

Parameters may be abbreviated as long as the parameter value does not become ambiguous. There is no distinction made between upper and lower case letters.

Note:

The SDL keywords Sender, Parent, Self and Offspring may not be abbreviated.

Underscores in SDL Names

Command parameters that are SDL names may also be abbreviated, as long as the abbreviation is unique. The underscore character `_' is used to separate names into distinct parts in the same way as the hyphen character (-) is used with command names. If a name is equal to the first part of another name, as for example Wait and Wait_For_Me, then any abbreviation of Wait is ambiguous. However, if all characters of the shorter name are given (Wait in this example), this is considered as an exact match and the short name will be selected.

The abbreviation facility means that the introduction of underscores in SDL names simplifies simulation. If, for example, you were considering if two signals should be named GenerateOn and GenerateOff or if they should be named Generate_On and Generate_Off, the last alternative is preferable for simulations, as the abbreviations G_On and G_Off are likely to be unique.

Matching of Parameters

When a (possibly abbreviated) parameter name is entered and is to be matched with an unabbreviated name, only names in the entity class of interest are considered. That is, if the monitor expects a process name as parameter, only the names denoting process types will be part of the search for the full name.

Signal names and timer names are in the same entity class; process formal parameters and process variables are in the same entity class; each other type of name (process, procedure, state, block,...) is in an entity class of its own.

Knowledge of previous parameters is used to narrow the search for a given parameter name. Consider for example the command Output-Via, which takes two parameters, a signal and a channel. The channel name is then only searched for among the channels the given signal can be sent via.

Qualifiers

Names can still cause problems, if, for example, there are two process types with the same name in two different blocks, or if the system and a block contain signal definitions with the same name.

In the first situation the process name will always be ambiguous and in the second case the system's signal will always be used. To solve cases like this, qualifiers with the same syntax as in SDL can be used. To reach a process P defined in block B in system S, the following notations can be used:

System S / Block B P
<<System S / Block B>> P

The words "system," "block," "process," "procedure," and "substructure" in the qualifier may not be abbreviated, while all names of, for example, blocks and processes may be abbreviated according to the usual rules. It is only necessary to give those parts of the qualifier that make the qualifier path unique (this is an extension of the qualifier concept in SDL). The slash ( / ) in a qualifier may be omitted and replaced by one or more spaces. The angle brackets that are part of the qualifier when printed may be omitted when entering the qualifier.

Default Parameters

Some command parameters may be omitted, indicating a default value for the parameter. To accept a default parameter value at the prompt, just press <Return>.

If the parameter is given on the same line as the command name and/or other parameters, type a hyphen `-' to indicate a default parameter value.

Example 306 : Default Parameters in Simulator Command

Consider as an example the command Breakpoint-Transition, which takes at least eight parameters. To specify default values for all parameters, except the first and fourth parameter:

Breakpoint-Transition P - - State1 - - - -

Signal and Timer Parameters

When the parameters of a signal instance or a timer instance are to be entered, the interactive monitor system will ask for the parameters one by one, in the same way as for command parameters. The parameters can also be entered directly after the signal or timer name, possibly enclosed by parenthesis.

Example 307 : Signal and Timer Parameters in Simulator Command

Signal name : S
Parameter 1 (Integer) : 3
Parameter 2 (Boolean) : true

The same specification could also be given as:

Signal name : S 3 true

or as:

Signal name : S (3 true)

When entering signal parameters it is not necessary to give all parameter values. By entering `-' at the parameter's position, the parameter is given a "null" value (i.e. the computer's memory for the value is set to 0). By entering `)', the rest of the parameters are given "null" values.

Example 308 : Signal Parameters in Simulator Command

Signal name : S -, true

will give the first parameter a "null" value.

Signal name : S (3, -)

will give the second parameter a "null" value. Could also be given as:

Signal name : S (3)

Errors in Commands

If an error in a command name or in one of its parameters is detected, an error message is printed and the execution of the command is interrupted, that is, a command is either executed completely or not at all. On UNIX, this is the only way to cancel a command that has been entered, when not using the simulator's graphical user interface.

Context-Sensitive Help

By typing a question mark (`?'), a context-sensitive help is obtained. The monitor will respond to a `?' by giving a list of all allowed values at the current position, or by a type name, when it is not suitable to enumerate the values. After the presentation of the list, the input can be continued.

If no default value exists for the requested parameter, the list of all allowed values is also printed if the user simply presses <Return> at the prompt. In these cases, there is no need to type `?'.


Input and Output of Data Types

The syntax of literals of the predefined data types is in most cases obvious and follows the SDL definition of literals. There are, however, some extensions that are described below. As an option, it is also possible to use the ASN.1 syntax for values. On input the monitor system can manage both value notations, while there are commands in the monitor to select the type of output to be produced (SDL-Value-Notation and ASN1-Value-Notation).

Integer, Natural Values

The format of integers conforms exactly with the SDL and the ASN.1 standard, that is, an integer consists of a sequence of digits, possibly preceded by a `+' or `-'. However, with the command Define-Integer-Output-Mode it is possible to define the base of integers on output (decimal, hexadecimal, octal), which also affects how they may be entered. Hexadecimal values are preceded with "0x", and octal values are preceded with `0' (a zero).

Boolean Values

Boolean values are entered (and printed) as true and false, using upper or lower case letters. Abbreviation is allowed on input. In ASN.1 mode the value is printed in capital letters (TRUE, FALSE).

Real Values

The SDL literal syntax of real values has been extended to include the E-notation for exponents, in the same way as in many programming languages.

Example 309 : Real Values in SDL Syntax

The real number 1.4527 * 1024 can be written 1.4527E24

The real number 4.46 * 10-4 can be written 4.46E-4

The syntax for real values in ASN.1 is easiest described by an example:

Example 310 : Real Values in ASN.1 Syntax

{mantissa 23456, base 10, exponent -3}

This is the value 23.456.

Time, Duration Values

The format for Time and Duration values follows the SDL standards, i.e. real values without E-notation, with one extension. On input time values can either be absolute or relative to NOW. If the time value is given without a sign an absolute time value is assumed, while if a plus or minus sign precedes the value, a value relative to NOW is assumed.

Example 311 : Time Values in SDL Syntax

123.5 is interpreted as 123.5

+5.5 is interpreted as NOW + 5.5

-8.0 is interpreted as NOW - 8.0

Character Values

Character values are entered and printed according to the SDL standard, including the literals for the non-printable characters.

Example 312 : Character Values in SDL Syntax

'a', '3', '''', ' ', NUL, DEL

On input, the quotes may be omitted for all characters except ` ' (space) and `[`. A `should be entered as `'''.

Charstring Values

Charstring values can be entered and printed according to the SDL standard, that is, a single quote ( ' ) followed by a number of characters followed by a single quote. Any quote (') within a charstring has to be given twice. On output a non-printable character within a charstring is printed as a single quote followed by the character literal followed by a single quote.

The ASN.1 syntax for Charstring is similar to the SDL syntax. The delimiter character ` (single quote) is however replaced by the character " (double quote).

Example 313 : Charstring Values in SDL Syntax

 ''
An empty string

 'abc'
A string of three characters

 'a'NUL'c'
The second character is NUL

PId Values

Apart from the value null, which is a valid PId value, a PId value consists of two parts, the name of the process type and an instance number, which is an integer greater than 0.

The first process instance of a process type that is created will have instance number 1, the second that is created will have instance number 2, and so on. The syntax is Name:No, where Name is the process name and No is the instance number.

On input the process name and the instance number may, as an alternative, be separated by one or more spaces, if the command parameter is a PId value. In the same circumstances the instance number is not necessary (and will not be prompted for) if there is only one process instance of the process type. If, however, the command parameter is a unit that might be a process type or a process instance, only a colon (`:') is allowed between the process name and the instance number and the colon must follow directly after the process type name. Examples of such situations are the unit parameter in Set-Trace and Signal-Log.

On output a PId value may be followed by a plus sign (`+'), which indicates that the process instance is dead; that is, has executed a stop action. The plus sign is chosen as it is reminiscent of the `' character.

Bit

The Bit sort contains two values, 0 and 1. This syntax is used for input and output.

Bit_String

For Bit_String values the following syntax is used:

'0110'B

The characters between the two single quotes must be 0 or 1. On input the syntax for Octet_String, see below, can also be used.

Octet

The syntax used for an octet value is two HEX digits. Examples:

00 46 F2 a1 CC

The characters 0-9, a-f, and A-F are allowed.

Octet_String

The syntax for Octet_String is the following

'3A6F'H

Each pair of two HEX values in the string is treated as an Octet value. If there is an odd number of characters an extra 0 is inserted last in the string.

Object_Identifier

The sort Object_Identifier is in SDL treated as a String(Natural). This means that the syntax, in case SDL value notation is used, will be:

(. 2, 3, 11 .)

On input the items in the list should be separated by a comma and/or spaces - tabs. If ASN.1 value notation has been selected, the syntax will be:

{ 2 3 11 }

On input the items in the list should be separated by a comma and/or spaces - tabs.

Enumerated Values

Types that in SDL are defined as an enumeration of possible values can be entered and printed using the literals of the SDL data type definition. On input, the literals can be abbreviated as long as they are unique.

STRUCT Values

A struct value is entered and printed as the two characters "(." followed by a list of components followed by the two characters ".)". The components should, on input, be separated by a comma and/or a number of spaces (or carriage returns or tabs). Example:

(. 23, true, 'a' .)

If ASN.1 syntax is used, the component names will also be present. Example:

{ Comp1 2, Comp2 TRUE, Comp3 'a' }

On input the components using ASN.1 syntax may come in any order. Components not given any value will have the value 0, whatever that means for the data type.

Optional components that are not present, will not be printed. In SDL syntax that means an empty position between two commas.

#UNION Values

A #UNION value uses, in SDL value notation, the same syntax as a struct value. However, only the tag value and the active component is printed. In ASN.1 value notation, #UNION values use the Choice value syntax described below.

Choice Values

The syntax for a choice value is ComponentName:ComponentValue. If, for example, a choice contains a component C1 of type integer, then

C1:11

is a valid choice value.

#UNIONC Values

The syntax for a #UNIONC value is ! ComponentName ComponentValue or -> ComponentName ComponentValue. If, for example, a #UNIONC contains a component C1 of type integer, then

! C1 11

is a valid #UNIONC value. However, this syntax will not be used when printing, since the value contains no tag and hence it is not possible to know which component to use.

Array Values

An array value is entered and printed as "(:" followed by a list of components followed by a ":)". The components should, on input, be separated by a comma and/or a number of spaces (or carriage returns or tabs). Note that there should also be a space between the last component and the terminating ":)". In ASN.1 syntax, `{' and `}' are used as delimiters.

There are two syntaxes for array components depending on the implementation that the SDL to C Compiler has selected for the array implementation. This selection is described in "Array" . These easiest way to determine which syntax to use on input is to look at a variable of the array sort.

  • If an array is a simple array (i.e. index type is a simple type with one range condition and a limited range), the SDL syntax for an array value is according to the following example:
(: 1, 10, 23, 2, 11 :)
If ASN.1 value notation is selected, replace "(:" and ":)" by `{' and `}'.
  • If the array is a general array, the a syntax according to the following example should be used:
(: (others:2), (10:3), (11:4) :)
This would mean that for index 10 the value is 3, for index 11 the value is 4, and for all other indexes the value is 2. On input the commas, the parenthesis, and the colons in the components may be replaced by one or more spaces (or carriage returns or tabs).

For simple arrays the second syntax is also accepted. If the first syntax is used for simple arrays it is not mandatory to enter all values for the array components; by entering ":)" or "}" the rest of the components are set to a "null" value (i.e. the computer's memory for the value is set to 0).

String Values

A string value starts with "(." and ends with ".)". The components of the string is then enumerated, separated with commas. Example:

(. 1, 3, 6, 37 .)

On input the commas can be replaced by one or more spaces (or carriage returns or tabs). In ASN.1 syntax, `{' and `}' are used as delimiters instead of "(." and ".)".

Powerset Values

A powerset value starts with a `[' and ends with a `]'. The elements in the powerset is then enumerated, separated with commas. Example:

[ 1, 3, 6, 37 ]

On input the commas can be replaced by one or more spaces (or carriage returns or tabs).

Bag Values

A bag value starts with a `{' and ends with a `}'. The elements in the bag is then enumerated, separated with commas. Example:

{ 1, 3, 6, 37 }

On input the commas can be replaced by one or more spaces (or carriage returns or tabs). If the same value occurs more than once, then this value is in SDL syntax not enumerated several times. Instead, the number of occurrences is indicated after the value. Example

{ 1, 3:4, 6:2, 37 }

This is identical to

{ 1, 3, 3, 3, 3, 6, 6, 37 }

In ASN.1 syntax, each member is given explicitly according to the last example. On input items are separated by comma and/or one or more spaces. It is also allowed to mention the same value several times, with or without a number of items each time.

Ref Values

There are two possible syntaxes for Ref values. Either the pointer address as a HEX value, or the value of the data area referenced by the pointer. The value Null is printed as Null in both syntaxes. In the monitor system two commands are available to determine the syntax to be used (REF-Address-Notation and REF-Value-Notation). On input both syntaxes are allowed independently of what syntax that has been selected.

Example of the address notation:

HEX(23A20020)

In the value notation the keyword new() is used to indicate a reference to a value. If, for example, the following data types are available in SDL

newtype Str struct
data integer;
next StrRef;
endnewtype;

newtype StrRef Ref(Str)
endnewtype;

then a value of the StrRef type can look like the examples below:

Null
new( (. 1, Null .) )
new( (. 1, new( (. 2, Null .) ) .) )

The last example is a linked list with two elements. To handle recursive data structures, e.g. graphs, a special syntax is used: old n, where n is an integer. Example:

new( (. 1, new( (. 2, old 1 .) ) .) )

The notation old 1 in the example above means a reference to the same data area as the first new() notation refers to. So here we have two structs with next pointers referring to the other struct value. Old n would refer to the n:th new() seen from the left of the expression.

The same applies for Own and ORef values.


Monitor Commands

This section provides an alphabetical listing of all available commands in the simulator monitor. Simulator UI commands are described in "SimUI Commands" .

Alphabetical List of Commands

@ (Keyboard Polling)

Parameters:

(None)

The monitor will repeatedly look at the keyboard for a carriage return, indicating an immediate break in the execution of the current transition. Using the command @, this facility can be turned off. Each time the command @ is entered the monitor toggles between having the keyboard polling for carriage return on and off. At start up keyboard polling is on.

Note:

No other characters may be typed together with the carriage return. If some other characters are typed by mistake, please delete them before typing the carriage return.

To turn keyboard polling off is useful in some situations, for example if a user wants to paste a sequence of commands into the monitor. If the sequence contains an empty line this might cause an unwanted interrupt.

? (Interactive Context Sensitive Help)

Parameters:

(None)

The monitor will respond to a `?' (question mark) by giving a list of all allowed values at the current position, or by a type name, when it is not suitable to enumerate the values. After the presentation of the list, the input can be continued.

Typing `?' at the prompt level gives a list of all available commands, after which a command can be entered. For further help, see the command Help.

ASN1-Value-Notation

Parameters:

(None)

The value notation used in all outputs of values is set to ASN.1 value notation. See also the command SDL-Value-Notation.

Assign-Value

Parameters:

[ `(' <PId value> `)' ]
<Variable name> <Optional component selection>
<New value>

The new value is assigned to the specified variable in the process instance, service instance, or procedure given by the current scope. Sender, Offspring, and Parent may also be changed in this way, but their names may not be abbreviated.

It is, in a similar way as for the command Examine-Variable, possible to handle components in structured variables (struct, strings, array, and Ref) by appending the struct component name or a valid array index before the value to be assigned. Nested structs and arrays can be handled by entering a list of index values and struct component names.

If a PId is given within parenthesis the scope is temporarily changed to this process instance instead.

Breakpoint-At

Parameters:

<SDT reference> <Optional breakpoint commands>

A breakpoint is defined at the symbol specified by the SDT reference. If the execution reaches the symbol, the monitor becomes active immediately before that symbol. SDT references may be obtained by using the Show GR Reference command in an SDL Editor, see "Show GR Reference" .

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Breakpoint-Output

Parameters:

<Signal name>
<Receiver process name> <Receiver instance number>
<Sender process name> <Sender instance number>
<Counter>
<Optional breakpoint commands>

A breakpoint is activated and a breakpoint condition is defined. If a breakpoint condition is matched by an output, the monitor becomes active immediately after the symbol containing the output. The breakpoint condition defines one or several outputs and is specified by the parameters. Any of the parameters may be omitted, which implies that any value will match the missing fields in the breakpoint condition. Initially no breakpoints are active.

The <Counter> parameter is used to indicate how many times the breakpoint condition should be true before the monitor should become active. Default value for this parameter is 1, which means that the monitor should be activated each time the breakpoint condition is true.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Breakpoint-Transition

Parameters:

<Process name> <Instance number> <Service name>
<State name> <Signal name> <Sender process name>
<Sender instance number> <Counter>
<Optional breakpoint commands>

A breakpoint is activated and a breakpoint condition is defined. If a breakpoint condition is matched by a transition, the monitor becomes active immediately before that transition is started. The breakpoint condition matches one or several transitions and is specified by the parameters. Any of the parameters may be omitted, which implies that any value will match the missing fields in the breakpoint condition. Initially no breakpoints are active.

The <Counter> parameter is used to indicate how many times the breakpoint condition should be true before the monitor should become active. Default value for this parameter is 1, which means that the monitor should be activated each time the breakpoint condition is true.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Breakpoint-Variable

Parameters:

<Variable name> <Optional breakpoint commands>

A breakpoint is defined on the specified variable in the process instance given by the current scope. If the variable's value is changed, the monitor becomes active immediately after the symbol or assignment statement where the value is changed. The value is only checked between symbols and between assignment statements in tasks.

The breakpoint is also triggered when the variable no longer exists, i.e. the PId containing the variable is stopped or the procedure containing the variable has reached its end. In this case, the breakpoint is automatically removed.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Call-Env

Parameters:

(None)

The Call-Env command performs one call of the function InEnv. See the command Start-Env for more details.

Note:

This command and the commands Start-Env and Stop-Env are only available when the SDL to C Compiler is used to generate applications.

Call-SDL-Env

Parameters:

(None)

The command makes one call to the function that looks for incoming signals from the SDL suite communication mechanism. This means that all signals that have come to the simulator will be sent to their appropriate receiving process instances. See the command Start-SDL-Env for more details.

Cd

Parameters:

<Directory>

Change the current working directory to the specified directory.

Clear-Coverage-Table

Parameters:

(None)

This command is used to reset the coverage table to 0 in all positions, which means restart counting coverage from now.

Close-Signal-Log

Parameters:

<Entry number>

Stops the signal log with the specified entry number and closes the corresponding log file; see the command Signal-Log for more details. Entry numbers assigned by the command List-Signal-Log should be used.

Command-Log-Off

Parameters:

(None)

The command log facility is turned off; see the command Command-Log-On for details.

Command-Log-On

Parameters:

<Optional file name>

The command enables logging of all the commands given in the monitor. The first time the command is entered a file name for the log file has to be given as parameter. After that any further Command-Log-On commands, without a file name, will append more information to the previous log file, while a Command-Log-On command with a file name will close the old log file and start using a new file with the specified name.

Initially the command log facility is turned off. It can be turned off explicitly by using the command Command-Log-Off.

The generated log file is directly possible to use as a file in the command Include-File. It will, however, contain exactly the commands given in the session, even those that were not executed due to command errors. The concluding Command-Log-Off command will also be part of the log file.

Connect-To-Editor

Parameters:

(None)

This command will create a new Breakpoints menu in the SDL Editor and tell the SDL Editor to show all graphical breakpoints. If no SDL Editor is opened, the menu will appear when an SDL Editor is opened the next time. The commands given in the new menu will only be handled in those simulations that are connected. See also the Disconnect-Editor command.

Create

Parameters:

<Process name> <Parent's PId value>
<Process parameters>

A process instance of the specified process type is created. If the parent PId is not equal to null, Offspring is set in the specified parent instance. If the number of instances of the specified process type is greater than or equal to the maximum number of concurrent instances, the user has to verify the create action.

Define-Continue-Mode

Parameters:

"On" | "Off"

Defines whether the execution of the simulation shall continue after a command is given. The default is "Off".

Define-Integer-Output-Mode

Parameters:

"dec" | "hex" | "oct"

Defines whether integer values are printed in decimal, hexadecimal or octal format. In hexadecimal format the output is preceded with "0x", in octal format the output is preceded with `0' (a zero).

On input: if the format is set to hexadecimal or octal, the string determines the base as follows: After an optional leading sign a leading zero indicates octal conversion, and a leading "0x" hexadecimal conversion. Otherwise, decimal conversion is used.

The default is "dec", and no input conversion is performed.

Define-MSC-Trace-Channels

Parameters:

"On" | "Off"

Defines whether the env instance should be split into one instance for each channel connected to env in the MSC trace. The default is "Off".

Disconnect-Editor

Parameters:

(None)

This command will remove the connection to the SDL Editor. If this simulation is the only connected to the SDL Editor, it will also remove the Breakpoints menu in the SDL Editor. See also the Connect-To-Editor command.

Display-Array-With-Index

Parameters:

"On" | "Off"

When Display-Array-With-Index is On and you examine an array, the value of the array element is printed with its index. Index is added before the value of the array element. The default is "Off".

Down

Parameters:

<Optional service name>

Moves the scope one step down in the procedure call stack. If the current scope is a process containing services, one of the services should be specified. See also the commands Stack, Set-Scope and Up.

Examine-PId

Parameters:

[ `(' <PId value> `)' ]

Information about the process instance given by the current scope is printed (see the Set-Scope command for an explanation of scope). This information contains the current values of Parent, Offspring, Sender and a list of all currently active procedure calls made by the process instance (the stack). The list starts with the latest procedure call and ends with the process instance itself. If the process contains services, these services will be listed, each with its own procedure call stack.

If a PId is given within parenthesis information about this process instance is printed instead.

Examine-Signal-Instance

Parameters:

<Entry number>

The parameters of the signal instance at the position equal to entry number in the input port of the process instance given by the current scope are printed (see the Set-Scope command for an explanation of scope). The entry number is the number associated with the signal instance when the command List-Input-Port is used.

Examine-Timer-Instance

Parameters:

<Entry number>

The parameters of the specified timer instance are printed. The entry number is the number associated with the timer when the List-Timer command is used.

Examine-Variable

Parameters:

[ `(' <PId value> `)' ]
<Optional variable name>
<Optional component selection>

The value of the specified variable or formal parameter in the current scope is printed (see the Set-Scope command for an explanation of scope). Variable names may be abbreviated. If no variable name is given, all variable and formal parameter values of the process instance given by the current scope are printed. Sender, Offspring, Self, and Parent may also be examined in this way. Their names, however, may not be abbreviated and they are not included in the list of all variables.

Note:

If a variable is exported, both its current value and its exported value are printed.

It is possible to examine only a component of a struct, string or array variable, by appending the struct component name or a valid array index value as an additional parameter. The component selection can handle structs and arrays within structs and arrays to any depth by giving a list component selection parameters. SDL syntax with `!' and "( )" as well as just spaces, can be used to separate the names and the index values.

It is also possible to print a range of an array by giving "FromIndex: ToIndex" after an array name. Note that the space before the `:' is required if FromIndex is a name (enumeration literal), and that no further component selection is possible after a range specification.

To see the possible components that are available in the variable, the variable name must be appended by a space and a `?' on input. A list of components or a type name is then given, after which the input can be continued. After a component name, it is possible to append a `?' again to list possible sub components.

To print the value of the data referenced by a Ref pointer it is possible to use the SDL syntax, i.e. the "*>" notation. If, for example, Iref is a Ref(Integer) variable then Iref*> is the integer referenced by this pointer. If Sref is a Ref of a struct, then Sref*> ! Comp1 is the Comp1 component in the referenced struct. The sequence *> ! can in the monitor be replaced by -> (as for example in C).

If a PId is given within parenthesis the scope is temporarily changed to this process instance instead.

Exit

Parameters:

(None)

The simulation is terminated. If the command is abbreviated the monitor asks for confirmation. This is the same command as Quit.

Finish

Parameters:

(None)

This command will execute the currently executing procedure up to and including its return, i.e. it will finish this procedure. The execution will also be interrupted at the end of the transition. In a process, Finish will behave just like the command Next-Transition.

Go

Parameters:

(None)

The execution of the simulation is resumed. The execution will continue until one of the conditions listed in "Activating the Monitor" becomes true. To stop the execution of transitions, press <Return> (and only this key). The interactive monitor will then become active when the execution of the current SDL symbol is completed.

This command has to be used with care in the interactive monitor, as it might result in executing the simulation program "forever" (if none of the conditions for activating the monitor becomes true). In a catastrophic situation (e.g. an endless loop within an SDL symbol) it is possible to terminate the program by using the way to stop the execution of a program defined in the operating system (<Ctrl+C> on UNIX).

Go-Forever

Parameters:

(None)

The command Go-Forever behaves, in most situations, in the same way as the command Go.

For Go-Forever to behave differently than Go, there has to be an environment to the SDL system that can send signals to the SDL system (communicating simulations or environment functions). When the command Go is issued and the SDL system becomes completely idle (no possible transition and no active timer) the monitor becomes active again and is entered. If Go-Forever was used instead of Go, the monitor is not entered in this case; instead the simulation continues to wait for external stimulus. This feature is valuable when a simulation communicates with other simulations or applications.

Help

Parameters:

<Optional command name>

Issuing the Help command without a parameter will print all the available commands. If a command name is given as parameter, this command will be explained.

Include-File

Parameters:

<File name>

This command provides the possibility to execute a sequence of monitor commands stored in a text file. The Include-File facility can be useful for including, for example, an initialization sequence or a complete test case. It is allowed to use Include-File in an included sequence of commands; up to five nested levels of include files can be handled.

This command also provides the possibility to perform script calling with variable substitution.

In a script file it is possible to refer to variables using $1, $2, ... , $99. The numbered variables refer to the arguments (actual values) given when calling a script using the command Include-File.

Unix shell script expressions like $0, $#, $? and $* are not available to be given as variable references in script files. Letters are not used as reference variables. For example $a, $1b, $ac are not available to be used as reference variables.

The actual values will be given as parameters in the Include-File command after script-file name. It is possible to pass up to 99 actual values. The numbered variables will be substituted by the actual values during execution of commands in the script files.

Arguments should be separated by spaces. $1 will be substituted by arg1, $2 will be substituted by arg2, $3 will be substituted by arg3, and $4 will be substituted by arg4 and so on.

If there is an argument missing, the corresponding reference variable will not get a value, it is up to the user to provide the correct arguments when using the Include-File command.

List-Breakpoints

Parameters:

(None)

All active breakpoints are listed. Each breakpoint is assigned an entry number that can be used in the Remove-All-Breakpoints and Show-Breakpoint commands.

List-GR-Trace-Values

Parameters:

(None)

The values of all currently defined GR traces are listed. The list contains the trace unit type (system, block, process, PId), the unit name, and the GR trace value (both numeric and a textual explanation). See also the commands Set-GR-Trace and Reset-GR-Trace.

List-Input-Port

Parameters:

[ `(' <PId value> `)' ]

A list of all signal instances in the input port of the process instance given by the current scope is printed (see the Set-Scope command for an explanation of scope). For each signal instance an entry number, the signal type, and the sending process instance is given. A `*' before the entry number indicates that the corresponding signal instance is the signal instance that will be consumed in the next transition performed by the process instance. The entry number can be used in the commands Examine-Signal-Instance, Rearrange-Input-Port and Remove-Signal-Instance.

If a PId is given within parenthesis information about this process instance is printed instead.

List-MSC-Log

Parameters:

(None)

This command returns the current status of the MSC log (off / interactive / batch). See also the commands Start-Interactive-MSC-Log, Start-Batch-MSC-Log and Stop-MSC-Log.

List-MSC-Trace-Values

Parameters:

(None)

This command returns the current status for the MSC trace parameters. The list contains the trace unit type (system, block, process, PId), the unit name, and the MSC trace value (both numeric and a textual explanation). See also the commands Set-MSC-Trace and Reset-MSC-Trace.

List-Process

Parameters:

<Optional process name>

A list of all process instances associated with the specified process type is produced. If no process name is specified all process instances in the system are listed. The list will contain the same details as described for the List-Ready-Queue command.

List-Ready-Queue

Parameters:

(None)

A list is produced containing the process instances in the ready queue, i.e., those instances that have received a signal that can cause an immediate transition, but that have not yet had the opportunity to execute this transition to its end. If the process contains services, the currently active service is also listed. If a process/service instance has active procedure calls, the current executing procedure instance is also listed. For each instance in the list the following information is given:

  1. An entry number (process instances only).
  2. An identification of the process/service/procedure instance.
  3. The name of its current state. If the state name is followed by a `*', then the process/service/procedure is currently executing a transition starting from this state.
  4. The number of signal instances in the input port of the process instance.
  5. The signal name of the signal instance that will cause (or has caused) the transition by the process instance. This signal instance is marked with a `*' before the entry number, if the command List-Input-Port is issued. If the transition has started the signal is no longer in the input port.

The process instance, the state, and the signal instance determine uniquely the transition that will be executed by the process instance when it gets permission to do so.

The entry number can be used in the command Rearrange-Ready-Queue.

List-Signal-Log

Parameters:

(None)

Print information about the currently active signal log; see the command Signal-Log for more details. Each log is assigned an entry number which can be used in subsequent Close-Signal-Log commands.

List-Timer

Parameters:

(None)

A list of all currently active timers is produced. For each timer, its corresponding process instance and associated time is given. An entry number will also be part of the list, which can be used in the command Examine-Timer-Instance.

List-Trace-Values

Parameters:

(None)

The values of all currently defined traces are listed. The list contains the trace unit type (system, block, process, PId), the unit name and the trace value (both numeric and a textual explanation). See also the commands Set-Trace and Reset-Trace.

Log-Off

Parameters:

(None)

The command Log-Off turns off the interaction log facility, which is described in the command Log-On.

Log-On

Parameters:

<Optional file name>

The command Log-On takes an optional file name as a parameter and enables logging of all the interaction between a simulation program and the user that is visible on the screen. The first time the command is entered, a file name for the log file has to be given as parameter. After that any further Log-On commands, without a file name, will append more information to the previous log file, while a Log-On with a file name will close the old log file and start using a new file with the specified file name.

Initially the interaction log facility is turned off. It can be turned off explicitly by using the command Log-Off.

News

Parameters:

(None)

The News command summarizes the changes in the textual monitor user interface from previous releases.

Next-Statement

Parameters:

<Optional number of statements>

This command is used to step statement for statement through SDL transitions. A statement is the same as a symbol, except that a task symbol may contain several assignment statements; compare with the Next-Symbol command.

Next-Statement steps over procedure calls, i.e. all actions in the procedure will be executed and the monitor will be entered again when the statement after the procedure call is reached; compare with the Step-Statement command.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

The right hand side of an assignment may contain a value returning procedure call.

Next-Symbol

Parameters:

<Optional number of symbols>

This command is used to step symbol for symbol through SDL transitions. A symbol may contain several statements; compare with the Next-Statement command.

Next-Symbol steps over procedure calls, i.e. all actions in the procedure will be executed and the monitor will be entered again when the symbol after the procedure call is reached; compare with the Step-Symbol command.

Using the optional integer parameter, a specified number of symbols can be stepped through. Next-Symbol will, however, never step from within one transition into another transition.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

Join is not considered a symbol by this command.

To determine how far a transition has been executed, the commands Show-Next-Symbol and Show-Previous-Symbol, together with trace printouts and GR traces can be used. The last trace printout is from the last executed symbol (if it has caused a printout, which depends on the trace level), while the symbol next to be executed is selected by the GR trace, if GR trace is on.

Next-Transition

Parameters:

(None)

The next transition is executed. If real time is used and the next transition is a timer output scheduled in the future (more than a second from now), the command Next-Transition will wait one second, after which the monitor is entered again.

Executing a Next-Transition command within a transition will execute the remaining part of the transition.

Next-Visible-Transition

Parameters:

(None)

A number of transitions are executed up to and including the next transition with a trace value > 0. For a timer output transition, it is the trace value for the corresponding process instance that is considered.

This command should be used with care in the interactive monitor, as it might result in executing the simulation program "forever" (if no transition with trace>0 is ever executed). To stop the execution of transitions, press <Return>. The interactive monitor will then become active when the execution of the current SDL symbol is completed.

Nextstate

Parameters:

<State name>

The state of the process/service/procedure instance given by the current scope is changed (see the Set-Scope command for an explanation of scope). This command implies that all actions in a nextstate are performed, i.e. recalculation of enabling conditions and continuous signals, and searching for a signal to be received according to the input and save sets. As a consequence the ready queue for process instances may change.

Now

Parameters:

(None)

The current value of the simulation time is printed.

Output-From-Env

Parameters:

-

The command will list all signals possible to send into the system, together with receiver. If the signal contains parameters, an empty parenthesis pair will be added after the signal name. Only signals that will trigger a transition directly will be listed. So signals causing an immediate null transition or signals that will be saved are not listed.

By just giving Output-From-Env in the Simulator UI, the possible choices will be given in a dialogue and by selecting one of the signals it is sent into the system. If the signal contains parameters they will be given "null" values.

Output-Internal

Parameters:

<Signal name> <Signal parameters>
<Receiver's PId value> <Sender's PId value>

The command is used to simulate an output of an internal signal instance between two process instances in the system. The parameter <Sender's PId value> may also denote "env:1". No check is made to ensure that a path of signal routes and channels exists. The monitor responds with either of the three messages below.

Signal <name> is not in valid input signal set of process <name>

The signal was not in the valid input signal set of the receiver and can thus not be handled by the receiver. The signal was immediately discarded.

Signal <name> was sent to <receiver> from <sender>

The signal instance was successfully sent and was placed in the input port of the receiver.

Signal <name> caused an immediate null transition

The receiving process instance is currently waiting in a state where the specified signal type neither may cause an input operation, nor is saved. The signal instance is immediately discarded (in SDL this is called a null transition, i.e a transition with no actions, leading back to the same state).

Output-None

Parameters:

<PId value> <Optional service name>

The command is used to send a signal "none" to the specified process instance. If the process instance contains services, one of the services should to be specified as well. The none signal is used to indicate that a spontaneous transition should be initiated in the current state.

Output-To

Parameters:

<Signal name> <Signal parameters>
<Receiver's PId value>

The command is used to send a signal from the environment of the system to a process instance in the system. It will be checked that a path of channels and signal routes exists from the environment to the specified process instance.

The monitor will respond with either of the messages described below, or by an error message if no path existed.

Signal <name> was sent to <receiver> from <sender>

The signal instance was successfully sent and is placed into the input port of the receiver.

Signal <name> caused an immediate null transition.

The receiving process instance is currently waiting in a state where the specified signal type neither may cause an input operation, nor is saved. The signal instance is immediately discarded (in SDL this is called a null transition, a transition with no actions, leading back to the same state).

Output-Via

Parameters:

<Signal name> <Signal parameters>
<Optional channel name>

The command is used to send a signal from the environment of the system to a process instance in the system via the specified channel. If no channel is given, it is assumed that any channel from the environment to the system may be selected. It will be checked that there exists one process instance that can receive the signal, according to the rules of outputs in SDL.

The monitor will respond with either of the messages below, or by an error message if the number of possible receivers is not equal to one.

Signal <name> was sent to <receiver> from <sender>

The signal instance was successfully sent and is placed into the input port of the receiver.

Signal <name> caused an immediate null transition.

The receiving process instance is currently waiting in a state where the specified signal type neither may cause an input operation, nor is saved. The signal instance is immediately discarded (in SDL this is called a null transition, a transition with no actions, leading back to the same state).

Print-Coverage-Table

Parameters:

<File name>

This command can be used to obtain test coverage information and profiling information. Each time the command is issued a coverage file, with the name specified as parameter, is produced in the work directory containing the relevant information. The coverage file always reflects the situation from the start of the simulation. To study the information in the coverage file, it can be opened in the Coverage Viewer; see 48 The SDL Coverage Viewer.

Note:

The specified file is always overwritten, i.e. there is no confirmation message if an existing file is specified.

The generated file consists of two sections, first a summary with profiling information, containing the number of transitions and the number of symbols executed by each process type. Secondly the file contains detailed information about how many times each symbol and each state - input combination is executed.

Example 314 : Profiling Information in Coverage File

*************** PROFILING INFORMATION **************

2 System DemonGame : Transitions = 13, Symbols = 40
3 Block GameBlock
4 Process Main : Transitions = 3 (23%),
Symbols = 10 (25%), MaxQ = 2
4 Process Game : Transitions = 6 (46%),
Symbols = 15 (37%), MaxQ = 2
3 Block DemonBlock
4 Process Demon : Transitions = 4 (30%),
Symbols = 15 (37%), MaxQ = 1

This information in Example 314 should be interpreted in the following way:

  • As transitions, the number of executed input symbols + continuous signal symbols + start symbols are counted.
  • As symbols, the number of executed process symbols (task, output, decision, set, reset, call, export, stop, return, create, nextstate, input, continuous signal, start) are counted.
  • The number of transitions and the number of executed symbols are, as shown in the example above, presented both for the system (total for all processes) and for each process type. The relative numbers for the processes are, of course, relative to the numbers for the system.
  • MaxQ is the maximum input port queue length for any instance of the process type. Note that start up signals, used to implement create, and continuous signals are counted as signals in MaxQ.
  • The numbers at the beginning of each line are the scope level of the that unit. This can be used to determine if, for example, a procedure is defined within or after another procedure.

Note:

To be true, profiling information execution time ought to be measured instead of the number of transitions and number of executed symbols, but this information is still very valuable for getting a feeling for the load distribution.

Example 315 : Coverage Table in Coverage File

************** COVERAGE TABLE DETAILS **************

2 System DemonGame

3 Block GameBlock

4 Process Main
1 : Start #SDTREF(SDL,main.spr(1),131(30,10),1)
1 : Game_Off Newgame #SDTREF(SDL,main.spr(1),137
1 : Game_On Endgame #SDTREF(SDL,main.spr(1),119(
--------------------
1 START : #SDTREF(SDL,main.spr(1),131(30,10),1)
1 INPUT : #SDTREF(SDL,main.spr(1),137(31,44),1)
1 INPUT : #SDTREF(SDL,main.spr(1),119(56,44),1)
1 NEXTSTATE : #SDTREF(SDL,main.spr(1),134(34,29),1)
1 CREATE : #SDTREF(SDL,main.spr(1),140(37,59),1)
1 TASK : #SDTREF(SDL,main.spr(1),143(34,72),1)
1 NEXTSTATE : #SDTREF(SDL,main.spr(1),146(35,89),1)
1 OUTPUT : #SDTREF(SDL,main.spr(1),122(56,59),1)
1 TASK : #SDTREF(SDL,main.spr(1),125(60,72),1)
1 NEXTSTATE : #SDTREF(SDL,main.spr(1),128(59,89),1)

For each process type two types of information are given, separated by a line of hyphens:

  • The first part contains information about the start transition and each relevant state-input combination: the number of times executed and a GR or PR reference to the associated process symbol. Continuous signals are counted as a separate input.
  • The second part contains information about each process symbol: the number of times it has been executed, the type of symbol, and a GR or PR Reference to the symbol.

To identify the process symbols, the command Show GR Reference command in the SDL Editor's Tools menu can be used for the printed GR references. (See "Show GR Reference" .)

Proceed-To-Timer

Parameters:

(None)

This command will execute all transitions up to but not including the next timer output. The timer output will not be executed even if it is the next transition.

Proceed-Until

Parameters:

<Time value>

The execution of the simulation is resumed. The monitor will become active when the value of the simulation time first becomes equal to the time value given as parameter.

Note that relative time values can be given using the `+' sign. Entering "+5.0" as parameter is interpreted as the time value NOW+5.0. See also "Input and Output of Data Types" .

Quit

Parameters:

(None)

The simulation is terminated. If the command is abbreviated the monitor asks for confirmation. This is the same command as Exit.

Rearrange-Input-Port

Parameters:

<Entry number> <New entry number>

This command is used to change the order of signal instances in the input port of the process instance given by the current scope (see the Set-Scope command for an explanation of scope).

The entry number parameters refer to the numbers assigned by the command List-Input-Port. The signal instance with entry number equal to the first parameter will be moved to a position where it in a subsequent List-Input-Port command will be assigned the entry number given as the second parameter.

Rearrange-Ready-Queue

Parameters:

<Entry number> <New entry number>

This command is used to change the order in which transitions by process instances are executed. The entry number parameters refer to the entry numbers assigned by the command List-Ready-Queue. The process instance with entry number equal to the first parameter will be moved to a position where it in a subsequent List-Ready-Queue command will be assigned the entry number given as the second parameter.

The Rearrange-Ready-Queue command should be used with care when process priorities are used. The ready queue is then sorted in priority order (see also "Scheduling" ), which means that a rearrangement might disturb this order. Such a disturbance does not harm, except when a new process should be inserted into the ready queue. In this situation the insert point might not be the proper one. The following insert algorithm is used: Search from the end of the ready queue until a process with higher or equal priority (lower or equal priority value) is found, then insert the new process after the found process. If no process with higher or equal priority is found, then insert the new process first in the ready queue.

REF-Address-Notation

Parameters:

(None)

REF values (pointers introduced using the generator Ref) are printed as addresses, using the HEX value for the address. The Null value is printed as Null. On input, both this syntax and the Value-Notation (see command REF-Value-Notation) can be used.

The same applies for Own and ORef values.

REF-Value-Notation

Parameters:

(None)

REF values (pointers introduced using the generator Ref) are printed as NEW(<the value the pointer refers to>). This is the default syntax for REF values. It means that complete lists or graphs will be printed. Example:

NEW( (. 1, NEW( (. 2, Null .) ) .) )

To avoid problems in cyclic graphs a special syntax is used if a pointer refers to an address already presented in the output. OLD n, where n is a digit, means a reference to the n:th NEW in the printed value. Example:

NEW( (. 1, NEW( (. 2, OLD 1 .) ) .) )

The Null value is printed as Null. On input both this syntax and the Address-Notation (see command REF-Address-Notation) can be used.

The same applies for Own and ORef values.

Remove-All-Breakpoints

Parameters:

(None)

This command removes all breakpoints.

Remove-At

Parameters:

<SDT reference>

This command removes all breakpoints at the symbol specified by the SDT reference.

Remove-Breakpoint

Parameters:

<Entry number>

This command removes the breakpoint with the specified entry number. The entry number given by List-Breakpoints should be used.

Remove-Signal-Instance

Parameters:

<Entry number>

The signal instance with the given entry number in the input port of the process instance given by the current scope is removed (see the Set-Scope command for an explanation of scope). The entry number given by List-Input-Port should be used. If this signal was selected for the next transition, the process instance will execute an implicit nextstate action.

Note:

Entry numbers are just positions in the input port. The removal of a signal changes the entry numbers of the remaining signals.

Reset-GR-Trace

Parameters:

<Optional unit name>

The GR trace value of the given unit is reset to undefined. If no unit is specified the GR trace value of the system is reset to undefined. As there always has to be a GR trace value defined for the system,
Reset-GR-Trace on the system is considered to be equal to setting the GR trace value to 0. For more information about optional unit names, see the command Set-Trace.

Reset-MSC-Trace

Parameters:

<Optional unit name>

The MSC trace value of the given unit is reset to undefined. If no unit is specified the MSC trace value of the system is reset to undefined. As there always has to be a MSC trace value defined for the system,
Reset-MSC-Trace on the system is considered to be equal to setting the trace value to 0. For more information about optional unit names, see the command Set-MSC-Trace.

Reset-Timer

Parameters:

<Timer name> <Timer parameters>

The result of the command is exactly the same as if the process instance given by the current scope had executed a reset action. If the reset action causes a timer signal to be removed and this signal was selected for the next transition, the process instance will execute an implicit nextstate action.

Reset-Trace

Parameters:

<Optional unit name>

The trace value of the given unit is reset to undefined. If no unit is specified the trace value of the system is reset to undefined. As there always has to be a trace value defined for the system, Reset-Trace on the system is considered to be equal to setting the trace value to 0. For more information about optional unit names, see the command Set-Trace.

Restore-State

Parameters:

<File name>

This command will restore the state of the current simulation to a state given in a file created with the Save-State command. The file name is given as parameter.

The write and read functions for the sorts are used to save and restore the variable values. So if a user has added a sort via the ADT directive, these write and read functions must be consistent.

It is recommended to restart the simulator before giving the Restore-State command. The command is not allowed when the execution is within a transition.

If the SDL system contains the Any construct, the sequence of random numbers will not be the same after the restore.

Only the sdl execution state is restored, no monitor settings are restored. E.g. Show-Previous-Symbol, Show-Next-Symbol does not work directly after a restore. The MSC trace is not restored. Coverage is not restored either.

The ADT package pidlist.pr is not supported, since the PId synonyms that are initialized are not valid after the restore.

Extern C and C++ variables will not be saved and restored since the simulator has no knowledge of them.

Charstar, Voidstar and Voidstarstar variables are not handled.

Since all variables are saved, dangling Ref and ORef variables will cause problems.

Scope

Parameters:

(None)

This command prints the current scope. See the command Set-Scope for a description of scope.

SDL-Value-Notation

Parameters:

(None)

The value notation used in all outputs of values is set to SDL value notation. This is the default value notation. See also the command ASN1-Value-Notation.

Save-Breakpoints

Parameters:

<File name>

This command will save all breakpoints in a file, with the name specified as parameter (in the work directory). It is written as a text file with commands, so the breakpoints can be restored with the Include-File command.

Save-State

Parameters:

<File name>

This command will save the state of the current simulation in a file, with the name specified as parameter (in the work directory). It is written as a text file with special commands, so the state can be restored with the Restore-State command.

Set-GR-Trace

Parameters:

<Optional unit name> <Trace value>

The GR trace value is assigned to the specified unit (system, block, process, or process instance). If no unit is specified the GR trace value is assigned to the system. The initial GR trace value of the system is 0, i.e. no GR trace, while it is undefined for all other units. For more information about optional unit names, see the command Set-Trace.

For a description of the possible GR trace values, see "GR Traces" .

Set-MSC-Trace

Parameters:

<Optional unit name> <Trace value>

This command enables the trace of SDL events that take place during the simulation and which can be transformed into events in a Message Sequence Chart. Typically, the events that can be transformed are sending and consumption of signals, and creation and termination of processes.

Note:

Setting the MSC trace value with this command does not start the actual logging of MSC events. To do this, the command Start-Interactive-MSC-Log or Start-Batch-MSC-Log is used.

The scope of the trace can be delimited by specifying an optional unit name and a trace value. The general considerations for specifying the unit name for the command Set-Trace are also applicable for Set-MSC-Trace.

Optional Unit Name

  • The trace value is assigned to the specified unit (system, block, process, or process instance).
  • When specifying a unit name, the scope of trace affects all process instances contained in the underlying SDL structure.
  • Initially, the scope of trace is set on the entire SDL system. So, by default, all events will generate Message Sequence Chart traces. If the unit name is omitted, the trace value is assigned to the system.

Trace Value

  • Specifying a trace value of 0 means no trace for the currently specified unit name.
  • Specifying a trace value of 1 means trace only if both involved units have a trace value greater than 0.
  • Specifying a trace value of 2 means always trace, independent of the trace value of the other involved unit.
  • Specifying a trace value of 3 means trace on the block level.

The initial MSC trace value of the system is 1. For more information on MSC trace values, see "Message Sequence Chart Traces" .

Note:

Once the logging of Message Sequence Chart traces has been started (using any of the commands Start-Interactive-MSC-Log or Start-Batch-MSC-Log) modifying the scope of trace may cause unpredictable results, such as Message Sequence Charts with an unexpected appearance.

Set-Scope

Parameters:

<PId value> <Optional service name>

This command sets the scope to the specified process, at the bottom procedure call. If the process contains services, one of the services can be given as parameter to the command. A scope is a reference to a process instance, a reference to a service instance if the process contains services, and possibly a reference to a procedure instance called from this process/service. The scope is used for a number of other commands for examining and changing the local properties of a process instance. The scope is automatically set by the execution commands, when entering the monitor, to the next process in turn to execute.

The command Scope prints out the current scope; i.e. the name of the process instance and possibly the service instance and the called procedure instance. See also the commands Stack, Define-MSC-Trace-Channels and Up.

Set-Timer

Parameters:

<Timer name> <Timer parameters> <Time value>

The result of the command is exactly the same as if the process instance given by the current scope had executed a set action. If the set action causes a timer signal to be removed and this signal was selected for the next transition, the process instance will execute an implicit nextstate action.

Set-Trace

Parameters:

<Optional unit name> <Trace value>

The trace value is assigned to the specified unit (system, block, process, or process instance). If no unit is specified the trace value is assigned to the system. The initial trace value for the system is 4, while it is undefined for all other units. For a description of the possible trace values, see "Trace Limit Table" .

There might, in some cases, be problems in identifying a specific unit. If more than one unit in the system match the, possibly abbreviated, unit name, the first unit found when searched from the system level will be assigned. To make sure the correct unit is assigned, the unit's diagram type, e.g. "process" (unabbreviated), can be introduced before the unit name. If there still are problems, for instance due to the fact that there are several processes with the same name, a qualifier should be inserted immediately before the unit name. An example can be found in "Specifying Unit Names" .

To specify a PId value, a colon and an instance number must follow directly after the process name; see also "Input and Output of Data Types" .

Show-Breakpoint

Parameters:

<Entry number>

This command is only applicable for symbol breakpoints defined with the command Breakpoint-At. The breakpoint with the specified entry number is listed, and the symbol with the breakpoint will be selected in an SDL Editor showing the source GR document. The entry number given by List-Breakpoints should be used.

Show-C-Line-Number

Parameters:

(None)

This command prints the .c file name and line number where the execution of the current SDL transition is suspended. The Text Editor is opened with the cursor positioned on that line in the C source file. The given line number will reference a statement with the following structure:

XBETWEEN_SYMBOLS(...)

The case label just following this statement is the place where the execution will be resumed when an execute command is given in the monitor.

The Show-C-Line-Number command is mainly thought to be used when the execution is interrupted within an SDL transition. If the command is issued between two transitions, the XBETWEEN_SYMBOLS statement immediately before the last Nextstate or Stop operation will be referenced in the printout, together with a warning that this is not the current position.

Note:

Changes made in the monitor, as for example Rearrange-Ready-Queue, will not affect the printout by this command.

Show-Coverage-Viewer

Parameters:

(None)

This command starts the Coverage Viewer tool with the current test coverage loaded.

Show-Next-Symbol

Parameters:

(None)

The symbol in turn to be executed will be selected in an SDL Editor showing the source GR document. If the simulation is not connected to the SDL suite or the SDL source document is in SDL/PR, a GR symbol reference or a PR reference will instead be displayed on the screen. The details about GR symbol references are presented in "Dynamic Errors" . A PR reference is a file name and a line number. See also "Syntax" .

Note that between the execution of two transitions, i.e. after a Nextstate or Stop operation, no next symbol can be shown. Note also that changes made in the monitor, as for example changing the ready queue using the command Rearrange-Ready-Queue, will not affect the symbol selected by Show-Next-Symbol.

This command uses the same mechanisms to select symbols in the SDL Editor as the GR trace facility, so the same general characteristics as presented in "GR Traces" are also valid for this command.

Show-Previous-Symbol

Parameters:

(None)

The last executed symbol will be selected in an SDL Editor displaying the source GR document. If the simulation is not connected to the SDL suite or the SDL source document is in SDL/PR, then a GR symbol reference or a PR reference will instead be displayed on the screen. See the command Show-Next-Symbol for more information.

Show-Versions

Parameters:

(None)

The versions of the SDL to C Compiler and the runtime kernel that generated the currently executing program are presented.

Signal-Log

Parameters:

<Unit name> <File name>

Starts logging of signals to a specified file. See also the commands Close-Signal-Log and List-Signal-Log.

The unit name parameter should be either a channel, a signal route, a system, a block, a process type, or a process instance.

  • If the unit is a channel or a signal route then all signals sent through the channel or signal route will be logged on the specified file.
  • If the unit is a process type or a process instance then all signals sent to or from any instance of the process type or to or from the specified process instance will be logged.
  • If the unit is a block or a system then all signals that have relevance for the block or system will be logged, i.e. signals sent within the block or system or signals sent to or from the block or system.

Note that the process "env" is a legal unit in the Signal-Log command. By specifying "env" as unit parameter, the signal interface between the system and the environment is logged. For more information about the unit name parameter, see the command Set-Trace.

Stack

Parameters:

(None)

The procedure call stack for the PId/service defined by the scope is printed. For each entry in the stack, the type of instance (procedure/process/service), the instance name and the current state is printed. See also the commands Set-Scope, Define-MSC-Trace-Channels and Up.

Start-Batch-MSC-Log

Parameters:

<Symbol level> <File name>

This command starts the logging of SDL events which can be translated into the corresponding MSC events in a log file (see "Mapping Between SDL and MSC" ). See also the commands Start-Interactive-MSC-Log and Stop-MSC-Log.

The results will be stored in a log file, whose contents are specific for this purpose. That log file can later on be read by a Message Sequence Chart Editor, where its contents are interpreted as a Message Sequence Chart and displayed as such.

The symbol level parameter determines if states and actions should be included in the MSC log. For a description of the possible symbol level values, see "Level of Symbol Logging" .

The file name parameter to this command can be any valid file name, although it is recommended to use a file name with the suffix .mpr, since this is the default suffix used when reading a log file into a Message Sequence Chart Editor.

Start-Env

Parameters:

(None)

When the SDL to C Compiler is used to generate applications, interface functions towards the environment of the SDL system must be provided. The InEnv function, which is used to enter signals into the SDL system, is frequently called from the main loop in the process scheduler. During debugging, the polling of the InEnv function can turned on and turned off.

The Start-Env command turns on the polling of InEnv. At start up of the program polling is turned off. See also the commands Stop-Env and Call-Env.

Note:

This command and the commands Stop-Env and Call-Env are only available when the SDL to C Compiler is used to generate applications.

Start-Interactive-MSC-Log

Parameters:

<Symbol level>

This command starts the logging of SDL events which can be translated into the corresponding MSC events in a Message Sequence Chart Editor (see "Mapping Between SDL and MSC" ). See also the commands Start-Batch-MSC-Log and Stop-MSC-Log.

The symbol level parameter determines if states and actions should be included in the MSC log. For a description of the possible symbol level values, see "Level of Symbol Logging" .

When the command is issued, the following takes place:

  1. An instance of the Message Sequence Chart Editor is started. Each currently existing (SDL) process instance is displayed as an instance, with its instance head and its instance axis.
  2. Following the execution of the simulation, each SDL event which is possible to map to an MSC event and which is within the scope of MSC trace which is currently defined will automatically be displayed in the MSC Editor. Each event will cause the insertion point in the MSC Editor to be moved downwards with one step, which provides a feeling of absolute order between events.

Some drawing conventions and default layouting algorithms are used when drawing the automatically generated Message Sequence Chart. These conventions are described in "Drawing Conventions" .

Start-SDL-Env

Parameters:

(None)

A simulator can communicate with other simulations using SDL signals and the SDL suite communication mechanism. Signals sent to the environment in one simulation can enter as signals from the environment in another simulator.

This command is used to tell a simulator to start sending signals that are designated to the environment via the SDL suite communication mechanism and to start looking for incoming signals (polling) from the SDL suite communication mechanism. See also the commands Stop-SDL-Env and Call-SDL-Env.

This facility is at program start up turned off, and should only be turned on when a simulator should be able to communicate with other simulators (or applications).

Note:

The command must be given in both communicating simulators.

Start-ITEX-Com

Parameters:

(None)

This command starts the communication with the TTCN suite.

Start-SimUI

Parameters:

(None)

This command starts a Simulator UI and connects the running simulator to it. After this it is only possible to give commands in the UI.

Start-UI

Parameters:

(None)

This command attempts to start the program sdtenv in the start directory. The started program is assumed to connect itself to the SDL suite communication mechanism and can then communicate with the simulation program.

Note:

The command Start-SDL-Env should be given in the simulation program to make it communicate.

Step-Statement

Parameters:

<Optional number of statements>

This command is used to step statement for statement through SDL transitions. A statement is the same as a symbol, except that a task symbol may contain several assignment statements; compare with the command Step-Symbol.

Step-Statement will step into procedure calls; compare with the Next-Statement command.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

The right hand side of an assignment may contain a value returning procedure call.

Step-Symbol

Parameters:

<Optional number of symbols>

This command is used to step symbol for symbol through SDL transitions. A symbol may contain several statements; compare with the Step-Statement command.

Step-Symbol will step into procedure calls; compare with the Next-Symbol command.

Using the optional parameter, a specified number of symbols can be stepped through. Step-Symbol will, however, never step from within one transition into another transition.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

Join is not considered a symbol by this command.

Stop

Parameters:

<PId value> <Optional service name>

The specified process instance is stopped. If the process contains services, then either the process can be stopped by giving no service parameter, or one of the services can be stopped. The result of the command is exactly the same as if the process instance or service instance had executed a stop action.

Stop-Env

Parameters:

(None)

This command turns off the polling of the InEnv function; see the Start-Env command for more details.

Note:

This command and the commands Start-Env and Call-Env are only available when the SDL to C Compiler is used to generate applications.

Stop-MSC-Log

Parameters:

(None)

This command stops the logging of Message Sequence Chart events (in interactive mode as well as in batch mode). In the case of a batch mode logging, the log file will be closed. See the commands Start-Interactive-MSC-Log and Start-Batch-MSC-Log for more details.

Following this command, it is possible to log the rest of the session on a new file.

Stop-SDL-Env

Parameters:

(None)

The command turns off the communication mechanism described for the Start-SDL-Env command.

Up

Parameters:

(None)

Moves the scope one step up in the procedure call stack. Up from a service leads to the process containing the service. See also the commands Set-Scope, Stack and Define-MSC-Trace-Channels.


Traces

When a process instance executes actions within a transition, trace information describing the current action might be printed on the screen. The amount of information printed can be selected using the trace commands in the monitor system. A typical trace from a transition containing a few actions is given below.

*** TRANSITION START
* PId : Demon:1
* State : Generate
* Input : T
* Sender : Demon:1
* Now : 1.0000
* OUTPUT of Bump to Game:1
* SET on timer T at 2.0000
*** NEXTSTATE Generate

The transitions can also be traced in the GR source diagrams. This is discussed in detail under "GR Traces" .

Transition Trace

A trace value, which is a non-negative integer, can be assigned to process instances, to process types, blocks, and to the system. The commands associated with traces are Set-Trace, Reset-Trace and List-Trace-Values.

When a process instance starts a transition, the trace value that governs the amount of trace to be printed is computed according to the following algorithm:

  1. If a trace value is defined for the process instance executing the transition, that value is used.
  2. If not, and a trace value is defined for the process type, that value is used.
  3. Otherwise, if a trace value is defined for the block enclosing the process, that value is used.
  4. If still no trace value is found, the block structure is followed outwards until a unit is reached which has a trace value defined. The system will always have a trace value.

The hereby computed value is compared with the trace limit for each action executed during the transition. The trace information is printed only if the trace value is greater or equal to the trace limit for the action. Trace information at trace level 1 is treated specially, see below.

In the table below the trace limits for all the information that can be part of a trace is presented.

Note:

The trace messages are produced when actions defined in the SDL diagrams are executed. These messages are not used when monitor commands like Set-Timer, Nextstate, or Stop are entered.

Trace Limit Table

Action | Trace limit
Transition start | 2
Parameters of signal in input | 6
Output to environment, signal name and receiver | 1 (see below)
Output, signal name and receiver | 3
Output caused immediate null transition | 5
Parameters of signal in output | 6
Task | 4
Decision, value of expression in decision | 4
Procedure start, procedure return | 3
Parameters to procedures | 6
Create, successful or unsuccessful | 3
Parameters to create | 6
Set, timer name, time | 3
Time less than Now in set, changed to Now | 5
Parameters in set | 6
Set caused an implicit reset action | 5
Reset, timer name | 3
Reset caused timer or signal to be removed | 5
Parameters to reset | 6
Output of timer signal, timer name, receiver, time | 2
Output of timer signal caused a null transition | 5
Parameters to timer signal | 6
Nextstate, state name | 3
Null transitions at a nextstate | 5
Parameters to signals in null transitions at nextstate | 6
Stop | 3
Signals discarded at stop | 5
Parameters to signals discarded at stop | 6
Timers discarded at stop | 5
Parameters to timers discarded at stop | 6
Export | 4

The trace limit table can be summarized as follows:

0 | No trace
1 | Trace of signals to environment (environment as seen from the specified unit)
2 | Trace of transition start and timer outputs
3 | As 2 + trace of important SDL actions
4 | As 3 + trace of other SDL actions as well
5 | As 4 + result of actions (example: discarded signals)
6 | As 5 + Parameters of signals, timers, create actions

Trace information at trace level 1, i.e. trace of signals sent to the environment of the specified unit, is treated in a special way. This information is not printed if the trace value is greater than 1, instead the normal trace of outputs is used.

GR Traces

GR trace is a way to follow the execution of transitions in the GR source diagrams by selecting SDL symbols. It should normally only be used for a small number of processes to limit the amount of information displayed. The GR trace value determines to what degree the execution will be traced, i.e. how often SDL symbols will be selected in the GR diagrams (see below). After a nextstate or stop operation, i.e. between two transitions, the nextstate or stop symbol is still selected.

The commands associated with GR traces are Set-GR-Trace, Reset-GR-Trace and List-GR-Trace-Values.

The GR tracing will take place in a single SDL Editor window, which will show the appropriate GR diagram as the execution progresses. If no SDL Editor is opened, a new editor is started.

Three trace values are possible:

  • 0 - No GR trace.
  • 1 - When the monitor is entered next, show the next symbol to be executed. No symbols are selected during execution when the monitor is inactive. Thus, the SDL Editor window may not show the diagram containing the symbol currently executed.
  • 2 - Follow the execution and show each symbol as it is executed. If the execution is continued into another diagram, this diagram is loaded into the SDL Editor window.

Message Sequence Chart Traces

The commands associated with MSC traces are Set-MSC-Trace, Reset-MSC-Trace and List-MSC-Trace-Values.

Mapping Between SDL and MSC

When executing an SDL system, some of the SDL events can be transformed into a corresponding symbol in a Message Sequence Chart. The mapping rules which govern how SDL events are transformed into MSC symbols, lines and textual elements are described in "Mapping Between SDL and MSC" .

The ITU definition of the MSC language introduces the instance concept. An instance is mapped to any instance of an SDL process.

Scope of Trace for Generation of Message Sequence Charts

The scope of MSC trace is the process instances that have a calculated MSC trace value > 0.

Assume that we have set the scope of MSC trace to a part of the SDL system, for instance a block and the underlying structure in terms of processes. When an event takes place in the SDL system, one of three possible situations is possible. Let us assume for the sake of simplicity that the event is the sending of a signal from one process to another process. The three cases and their behavior are as follows:

  • First case: The two units (the sending process and the receiving process) are both within the scope of MSC trace. It is easy to transform this into the sending and consuming of a message, and the result will be a trace in a Message Sequence Chart.
  • Second case: None of the units is in the scope of MSC trace. This will not result in any trace in a Message Sequence Chart.
  • Third case: One and (one only) of the units is in the scope of MSC trace. This case is slightly more complicated. Sending and receiving messages to and from units may be of interest outside the scope of trace.
    The concept conditional trace is introduced: A conditional trace will indicate that a message has been sent or received, and that the receiver or sender is beyond the scope of trace. See also "The Void Instance" .

The MSC trace levels 1 and 2 are used to specify if conditional trace should be presented or not; see the table below. MSC trace level 3 specifies a block level trace.

MSC Trace for Sender | MSC Trace for Receiver | Result
 | 0 | No trace
0 | 1 | No trace
 | 2 | Conditional trace
 | 0 | No trace
1 | 1 | Trace
 | 2 | Trace
 | 0 | Conditional trace
2 | 1 | Trace
 | 2 | Trace

Level of Symbol Logging

The symbol level determines the amount of information that should be part of the MSC log. Three symbol levels are possible:

  • 0 - Events for signals and timers plus create and stop.
  • 1 - As level 0, plus condition symbols for each nextstate.
  • 2 - As level 1, plus action symbols for task, decision, call, and return.

Initial Trace Values

At the start of a simulation, the trace values, the GR trace values and the MSC trace values for all units except the system are undefined. The system trace is 4, the system GR trace is 0, and the system MSC trace is 1.


Dynamic Errors

Violations of the dynamic rules of SDL will cause dynamic errors during the execution of a simulation program. A dynamic error is presented to the user on the screen as an error message. See the example below.

Example 316 : Dynamic Error Printout

Warning in SDL Output of signal Bump
Signal sent to NULL, signal discarded
Sender: Demon:1
TRANSITION
Process : Demon:1
State : Generate
Input : T
Symbol : #SDTREF(SDL,/usr/tom/demon.spr(1),122(30,55),1)
TRACE BACK
Process : Demon
Block : DemonBlock
System : Demongame

The symbol reference given in the TRANSITION message should be interpreted as follows:

Item
Text in Example 316
Interpretation
1

 SDL
Reference to SDL/GR object
2

 /usr/tom/demon.spr
Reference to the file
3

 (1)
Page name
4

 122
The object identity (an unique number assigned by the SDL Editor)
5

 30
The x-coordinate of the object in mm. The origin of coordinates is the upper left corner of the page.
6

 55
The y-coordinate of the object in mm
7

 1
Line number within symbol

By entering the monitor command Show-Previous-Symbol, the symbol that caused the error is displayed.

For more information on references, see 19 SDT References.

Dynamic Errors Found by a Simulation Program

Error in SDL array index in sort <sort>:
<value> is out of range.

Violation of the index range given in an array.

Error in assignment in sort <sort>:
<value> is out of range.

Violation of the range conditions given in a syntype.

Error in SDL Decision: Value is <value>
Entering decision error state

The value of the expression in the decision did not match any of the possibilities (answers).

Error in SDL Import. Attempt to import from NULL

Error in SDL Import. Attempt to import from stopped process instance

Error in SDL Import. Attempt to import from the environment

Error in SDL Import. No process exports this variable

Error in SDL Import. The specified process does not export this variable

Error in an import statement. Supplementary information about remote variable and exporting processes is also given.

Warning in SDL Output of signal <signal>.
No path to receiver, signal discarded

An attempt was made to output a signal to a PId expression. There exists, however, no path of channels and signal routes between the sender and the receiver that can convey the signal.

Warning in SDL Output of signal <signal>.
No possible receiver found, signal discarded

An attempt was made to output a signal without specifying a to PId expression. When all paths or all paths mentioned in a via clause had been examined no possible receiver was found.

Warning in SDL Output of signal <signal>.
Signal sent to NULL, signal discarded

An attempt was made to output a signal to a PId expression that was null.

Warning in SDL Output of signal <signal>.
Signal sent to stopped process instance

An attempt was made to output a signal to a PId expression that referred to a process instance which has performed a stop action.

Error in SDL View. Attempt to view from NULL

Error in SDL View. Attempt to view from stopped process instance

Error in SDL View. Attempt to view from the environment

Error in SDL View: The specified process does not reveal this variable

Error in SDL View: No process reveals this variable

Error in a view statement. Supplementary information about viewed variable and viewing process is also given.

Error in SDL Create: Process <process>
More static instances then maximum number of instances.

Obvious!

Illegal #UNION tag value for assignment to component Name.
Tag value is xxx.

Attempt to assign a value to a non-active UNION component.

Illegal #UNION tag value for access to component Name.
Tag value is xxx.

Attempt to access a non-active UNION component.

Error when accessing component Name. Component is not Present.

Attempt to access a non-active optional struct component.

Component Name is not active.Present is xxx.

Attempt to access a non-active choice component.

Dereferencing of NULL pointer.
Pointer assigned new data area at address: HEX(xxx)

Attempt to de-reference a Null pointer defined using the Ref generator.

User specified error: SDL error expression found

Error introduced by the user, by inserting the error expression defined in SDL.

Errors Found in Operators

The errors that can be found in operators defined in the predefined data types are listed below.

Error in SDL Operator: Extract! in sort Charstring, Index out of bounds

Error in SDL Operator: Modify! in sort Charstring,
Character NUL not allowed.

Error in SDL Operator: MkString in sort Charstring,
Character NUL not allowed.

Error in SDL Operator: First in sort Charstring, Charstring length is 0

Error in SDL Operator: Fix in sort Integer, Integer overflow

Error in SDL Operator: Last in sort Charstring, Charstring length is 0

Error in SDL Operator: Substring in sort Charstring, Charstring length is 0

Error in SDL Operator: Substring in sort Charstring, Length of substring < 0

Error in SDL Operator: Substring in sort Charstring, Start index is <= 0

Error in SDL Operator: Substring in sort Charstring, Start index + length of substring > length of charstring

Error in SDL Operator: / in sort Integer, Attempt to divide by 0.

Error in SDL Operator: / in sort Real, Attempt to divide by 0.0.
Error in SDL Operator: Rem in sort Integer,
Second operand is 0

Error in SDL Operator: Mod in sort Integer,
Second operand is 0

Error in SDL Operator: Modify! in sort Bit_String,
Index out of bounds.

Error in SDL Operator: Extract! in sort Bit_String,
Index out of bounds.

Error in SDL Operator: First in sort Bit_String,
Bit_String length is zero.

Error in SDL Operator: Last in sort Bit_String,
Bit_String length is zero.

Error in SDL Operator: SubString in sort Bit_String,
Bit_String length is zero.

Error in SDL Operator: SubString in sort Bit_String,
Start is less than zero.

Error in SDL Operator: SubString in sort Bit_String,
SubLength is less than or equal to zero.

Error in SDL Operator: SubString in sort Bit_String,
Start + Substring length is greater than string length.

Error in SDL Operator: BitStr in sort Bit_String,
Illegal character in Charstring (not 0 or 1).

Error in SDL Operator: HexStr in sort Bit_String,
Illegal character in Charstring (not digit or a-f).

Error in SDL Operator: Modify! in sort Octet,
Index out of bounds.

Error in SDL Operator: Extract! in sort Octet,
Index out of bounds.

Error in SDL Operator: Division in sort Octet,
Octet division with 0.

Error in SDL Operator: Mod operator in sort Octet,
Right operand is 0.

Error in SDL Operator: Rem operator in sort Octet,
Right operand is 0.

Error in SDL Operator: BitStr in sort Octet,
An Octet should consist of not more than 8 characters 0 or 1.

Error in SDL Operator: HexStr in sort Octet,
An Octet should consist of 2 HEX values.

Error in SDL Operator: HexStr in sort Octet,
Illegal character in Charstring (not digit or a-f).

Error in SDL Operator: Modify! in sort Octet_String,
Index out of bounds.

Error in SDL Operator: Extract! in sort Octet_String,
Index out of bounds.

Error in SDL Operator: BitStr in sort Octet_String,
An Octet_String should consist of 0 and 1.

Error in SDL Operator: HexStr in sort Octet_String,
Illegal character in Charstring (not digit or a-f).

Apart from these error message each instantiation of generator String will introduce similar error messages as for the Charstring sort. Note that Object_Identifier is a predefined sort which is an instantiation of String.

Action on Dynamic Errors

After a dynamic error, the execution of the simulation program is continued until the current symbol is ended. The interactive monitor will then become active. The following actions will be taken:

  • If the error was an output error the signal will not be sent.
  • If the error was a decision error the process instance will immediately be placed in an decision error state. It can only be removed from this state by using the Nextstate command in the monitor. The input port will not be affected when the decision error state is entered. All signals sent to a process instance in a decision error state will be saved in the input port.
  • If the error occurred during the creation of static process instances, i.e. the initial number of instances is greater that the maximum number of instances, an error message is given and the number of instances specified by initial number of instances are created.
  • If the error occurred during an import or view action a data area of the correct size containing zero in all positions is returned.
  • If the error was found in a range condition check during an assignment, the variable to the left of the assignment operator will be assigned the computed value, although it is out of bounds.
  • If the error was found during a range check of an array index the index value will be changed to be the lowest value of the index type. This means that the corresponding C array will never be indexed out of its bounds.
  • If the error occurred during selection of an optional component in a struct or when selecting a component in a #UNION or Choice, an error message is given and the operation is perform anyhow.
  • If a Null pointer (Ref) is de-referenced, an new data area of correct size is allocated containing zeros. This data area is assigned to the pointer. After the error message the statement containing the de-referencing is performed.
  • If the error occurred within an expression the operator that found the error returns a default value and the evaluation of the expression is continued. The default values returned depend on the result type of the operator and are given in section "Default Values" .

Assertions

A user can define his own run-time errors or assertions. Basically the run-time library only provides an appropriate C function that can be called to print out an error message. This function is assumed to be used in #CODE directives in TASKs according to the following example:

Example 317 : Assertion in C Code

TASK '' /*#CODE
#ifdef XASSERT
if (#(I) < #(K))
xAssertError("I is less than K");
#endif
*/ ;

The xAssertError function, which has the following prototype:

extern void xAssertError ( char *Descr )

takes a string describing the assertion as parameter and will produce an SDL run-time error similar to the normal run-time errors. The function is only available if the compilation switch XASSERT is defined. For the standard libraries this is true for all libraries except the Application Library.

Run-time Prompting

For some special SDL constructs, an SDL simulator is not able to continue executing without prompting the user for necessary input. The execution continues when the user has entered an allowed value.

Decision with Any

If an SDL DECISION is encountered with an ANY question, the user will be prompted which path to execute:

Decision with ANY
1 (go path)
1 ? (show path)
2 (go path)
2 ? (show path)
3 (go path)
3 ? (show path)
Enter path :

At this point, the user must enter a path value (integer) within the allowed range. If GR trace is enabled, the user may enter a path value followed by a `?' to see the corresponding path in an SDL Editor.

Informal Decision

If an SDL DECISION is encountered with informal text, the user will be prompted which path to execute:

Informal decision: `Question1'
`answer1' 1
`answer2' 2
`ELSE' 3
Enter path :

At this point, the user must enter a path value (integer) within the allowed range. If GR trace is enabled, the user may enter a path value followed by a `?' to see the corresponding path in an SDL Editor.

Unimplemented Operator

If an expression is encountered involving an operator that is not implemented, the user will be prompted for the value to be returned depending on the parameters:

Operator op in sort s is called
Parameter 1: 50
Enter value(s) :

At this point, the user must enter a value in the resulting sort to be the returned value of the operator when called with the listed parameter values.


Graphical User Interface

This section describes the appearance and functionality of the graphical user interface to the simulator monitor (SimUI). Some user interface descriptions general to all tools in Telelogic Tau can be found in 1 User Interface and Basic Operations. These general descriptions are not repeated in this chapter.

Starting the SimUI

A new SimUI is started by selecting SDL > Simulator UI from the Tools menu in the Organizer. When the SimUI is started, a number of definition files are read, controlling the contents of the main window and some status windows. See "Definition Files" for more information.

No simulator is started automatically by the SimUI in this way. The user must start a simulator by selecting Open from the File menu, as stated in the text area of the main window, or by using the Open quick button.

A simple way to generate a simulator, start the SimUI and open the simulator is to click the Simulate quick button in the Organizer.

When a simulator is started, a file selection dialog may be opened if the SDL system contains external synonyms. For more information, see "Supplying Values of External Synonyms" .

The Main Window

The main window provides a text area (which displays output from the monitor system), an input line (used for entering and displaying textual command line input to the monitor system and the SimUI) and a button area with button modules (with buttons for execution of monitor and SimUI commands).

Figure 451 : The main window

The Text Area

The text area displays all text output from the monitor system, including user prompts, error messages and command results.

Commands cannot be entered in this area, but a command given on the input line or through the use of the command buttons is echoed after the displayed prompt:

Command :

The Input Line

The input line is used for entering and editing commands from the keyboard. For information on available monitor commands, see "Monitor Commands" . There are also special SimUI commands that are not sent on to the simulator monitor, see "SimUI Commands" .

The 100 latest commands entered on the input line are saved in a history list. The history list can be traversed by using the <Up> and <Down> keys on the input line.

When <Return> is pressed anywhere on the input line, the complete string is saved in the history list and is moved to the text area. The command is then executed.

The input line also has an associated popup menu with the choices Undo, Command, Save, Go to Source and Add to watchwindow:

  • Both Undo and Command open a dialog with all commands entered so far. In the Undo case, all the commands to redo can be selected, and the default is to redo all but the last one, which is equivalent to an Undo of the last command. In the Command case, only one of the commands to re-execute can be selected. For more information, see "Undo/Redo Commands" .
  • Save will save all monitor commands issued by the user so far to a command file. It opens a file selection dialog, in which the name of a command file is selected (on UNIX preferably with the suffix .com).
  • Go to Source will go to the SDT reference selected in the text area.
  • Add to watchwindow will add the variable selected in the text area to the watch window.

Parameter Dialogs

If a command entered on the input line requires additional user input (i.e. parameter values), the information will automatically be asked for in a dialog:

  • Parameter values that are file names are selected in File Selection Dialogs.
  • Parameter values of enumeration type are presented in lists, from which the value can be selected (see Figure 452).
  • Other parameter values are prompted for in simple text input dialogs. In these dialogs, the button Default value will enter a "null" value for the parameter in the input field.

Each parameter dialog has an OK button for confirming the value and a Cancel button for cancelling the command altogether. Some parameters have a default value that does not have to be specified. In this case, an empty value or `-' is accepted for the default value.

Enumeration Type Parameter Dialogs

Additional functionality is available in the dialog for enumeration type parameters:

Figure 452 : A typical selection dialog

In this dialog, the value can also be entered or edited on the text input line below the list in the dialog. The Sort button sorts all values in alphabetical order.

Name completion with the space character is provided. When you press <Space> after an initial string, the first value starting with the string will be selected (if any). Another <Space> will select the next value, etc. When there are no more matches, a space character will be added after the string you initially entered.

A slightly different name completion is provided with the `?' character. When you press `?' after an initial string, the first value containing the string will be selected (if any). Another `?' will select the next value. When there are no more matches, a `?' character will be added after the string you initially entered.

For those commands that take an optional variable component, the component must be entered on the text input line after the selected variable name, since it will not be asked for in a dialog. If a `?' is entered instead of a variable component, an additional dialog is opened in which the component can be selected. See the discussion of `?' in "Examine-Variable" .

Signal Parameter Dialogs

If a command takes an output signal as parameter, and that signal have parameters, the signal parameters are asked for in a separate dialog. In this dialog, all parameters are listed with their default ("null") values, and they can all be edited in the same dialog. For more information, see "Selecting Signal Parameters" .

Quick Buttons

The simulator has the following quick buttons:

  • Open simulator: Open an existing simulator executable file.
  • Restart simulator: Restart the current simulator from the initial system state.
  • Rerun script: Rerun last executed script.
  • Undo command(s): Undo one or more commands.
  • Show Organizer: Show the Organizer main window.
  • Show Help: Show help on Simulator user interface.

The Button Area

The button area is used for entering monitor or SimUI commands by clicking the left mouse button on a command button. Each button corresponds to a specific command. The buttons are divided into groups, roughly corresponding to the different types of commands listed in 50 Simulating a System. Each group is shown as a module in the button area. Any number of button modules may reside in the button area. If the modules do not fit in the button area, a vertical scroll bar is added.

The definition of the buttons and button groups are stored in a button definition file (see "Definition Files" ). New buttons can be added and existing ones deleted or redefined by using the Group menu in a button module.

To examine a button's definition without executing the command, the left mouse button is pressed on the button and the mouse pointer is moved outside the button. The command definition then appears in the status bar, but the command is not executed.

If a button's definition contains parameters, the parameter values are prompted for in dialog boxes before the command is executed, in the same way as described for commands entered from the input line. See "Parameter Dialogs" .

When no more parameter values are requested, the string shown on the input line saved in the history list and is moved to the text area. The command is then executed.

A Button Module

A button module looks like this:

Figure 453 : A button module

Each module consists of a title bar and a number of command buttons arranged in rows and columns. The title bar displays:

  • A collapse/expand toggle button. Clicking on this button collapses the module so that only the title bar is visible, and expands the module back to its current size so that the buttons become visible.
  • The group name of the button module.
  • A Group button, providing a menu with commands affecting the buttons in the module.

The Group button contains the following menu items:

Add

This menu choice adds a new button to the button module. A dialog prompts for the button label and the command to be executed when the button is pressed. The new button is added to the end of the module. Several buttons may be added with the dialog by using the Apply button instead of the OK button.

For the syntax of a button definition, see the subsection "Button and Menu Definitions" .

Note:

On UNIX, if several buttons have the same button label, it is always the first button found that will be deleted or modified, independently of the selection.

Edit

This menu choice edits the label and definition of a button. The button to edit is selected in a dialog. When a button has been selected, the label and definition can be edited using a dialog.

Note:

On UNIX, if several buttons have the same button label, it is always the first button found that will be edited, independently of the selection.

Delete

This menu choice deletes one or more buttons from the button module. The buttons to be deleted are selected in a dialog.

Note:

On UNIX, if several buttons have the same button label, it is always the first button found that will be deleted, independently of the selection.

Rename Group

This menu choice edits the name of the current button module in a dialog.

Delete Group

This menu choice deletes the current module from the button area. A dialog asks for confirmation.

The Default Button Modules

The following tables list the default buttons in the button modules and the corresponding monitor command. See "Monitor Commands" for more information.

Note:

The buttons in the button modules are specified in the button definition file. If the default button file is not used, the button modules may be different than described here. See "Button and Menu Definitions" for more information.

The Execute Module

Button | Monitor command
Symbol | Step-Symbol
Transition | Next-Transition
Go | Go
Until Timer | Proceed-To-Timer
Break | Pressing <Return>

The Send Signal Module

Button | Monitor command
Send To | Output-To
Send Via | Output-Via
Send None | Output-None

The Examine Module

Button | Monitor command
Process List | List-Process -
Variable | Examine-Variable (
Var In Scope | Examine-Variable

The Trace Module

Button | Monitor command
MSC | Start-Interactive-MSC-Log 1
SDL | Set-GR-Trace 1
TEXT | Set-Trace 6

The Menu Bar

This section describes the menu bar of the SimUI's main window and all the available menu choices. However, the Help menu is described in "Help Menu" . Simulator commands are described in "Monitor Commands" .

The menu bar contains the following menus:

  • File Menu
  • View Menu
  • Buttons Menu
  • Log Menu
  • General Menu
  • Execute Menu
  • Examine Menu
  • Change Menu
  • Show Menu
  • Trace Menu
  • Breakpoint Menu
  • Help Menu
    (See "Help Menu" .)

File Menu

The File menu contains the following menu choices:

  • Open
    (See "Open" .)
  • Restart
  • Exit
    (See "Exit" .)

Restart

Restart the currently opened simulator. After user confirmation, the currently running simulator is stopped, the Watch window is updated, and the text area is cleared from previously executed commands.

The command is dimmed if no simulator has been opened.

View Menu

The View menu contains the following menu choices:

  • Watch Window
  • Command Window
  • Open All
  • Close All
  • Clear Text Area

Watch Window

Opens the Watch window displaying variable values in the simulation. If this window is already opened, the menu item is dimmed. See "Watch Window" for more information about this window.

Command Window

Opens the Command window in which arbitrary monitor commands will be executed. If this window is already opened, the menu item is dimmed. See "Command Window" for more information about this window.

Open All

Opens the Watch and Command windows.

Close All

Closes the Watch and Command windows.

Clear Text Area

Clears the text area in the main window without affecting the simulation.

Buttons Menu

The Buttons menu contains the following menu choices:

  • Load
  • Append
  • Save
  • Save As
  • Expand Groups
  • Collapse Groups
  • Add Group

For more information on the SimUI's button definition file mentioned in the menu commands below, see "Definition Files" .

Load

Reads in a new button definition file that overrides the current button definitions. All buttons and modules currently in the button area are deleted and replaced by the buttons and modules defined in the new file. A File Selection Dialog is opened for specifying the file to load.

Append

Appends the contents of a new button definition file into the current button definitions. Buttons with new labels are added to the button area, while buttons with already existing labels in the same module will be duplicated (possibly with different definitions). A File Selection Dialog is opened for specifying the file to append.

Save

Saves the current button and module definitions in the button definition file under its current file name.

Save As

Saves the current button and module definitions in a new button definition file. A File Selection Dialog is opened for specifying the new file name.

Expand Groups

Expands all modules in the button area.

Collapse Groups

Collapses all modules in the button area.

Add Group

Adds one or more new button module after the last module in the button area. A dialog box is opened for specifying the name of the new module. Several modules may be added with the dialog by using the Apply button instead of the OK button.

Log Menu

The Log menu manages three different log variants:

  • The input history contains all textual commands sent to the SimUI.
  • The command history contains all textual commands sent to the simulator.
  • The complete log contains all textual output presented during a simulator session, this includes both user commands and simulator output.

The difference between the input history and the command history is that the SimUI processes commands before forwarding them to the simulator. The input history contains the raw user input, while the command history contains pure simulator commands. For instance:

  • Macros: The input history contains
Output-to MySignal ($maxvalue) Main
while the command history contains
Output-to MySignal (37329) Main

  • Check: This SimUI command, together with its expected output section, is saved in the input history but not in the command history.
  • Execute input script: This SimUI command is saved in the input history, while the command history contains the executed commands.

The Log menu contains the following menu choices:

  • Save Input History
  • Save Command History
  • Clear Input History
  • Clear Command History
  • Start/Stop Complete Log
  • Log Status

Clear Input History

SimUI command: clear-input-history

Normally, the input history is cleared when the simulator is restarted. You use this menu choice to clear the input history without restarting the simulator.

Save Input History

SimUI command: save-input-history

A file selection dialog appears, where you specify the file to save the input history in. The default file extension for input history files, i.e. input scripts, is *.cui.

Clear Command History

SimUI command: clear-command-history

Normally, the command history is cleared when the simulator is restarted. You use this menu choice to clear the command history without restarting the simulator.

Save Command History

SimUI command: save-command-history

A File Selection Dialog appears, where you specify the file to save the command history in. The default file extension for command history files, i.e. command scripts, is *.com.

Start/Stop Complete Log

Start Complete Log starts the logging of complete monitor interaction, i.e. the complete contents of the text area will be logged to a file. A file selection dialog is opened for specifying the log file. If an already existing log file is selected, the user is asked whether to overwrite this file or to append the log to it.

Stop Complete Log stops the complete logging to the file. The appropriate menu choice is displayed depending upon the current state of the log.

Log Status

Displays the status of the command and complete logs in a dialog box. If a log is active, the name of the log file is shown.

Additional Simulator Menus

In addition to the standard SimUI menus, a few special simulator menus are included in the menu bar. The menu choices in these menus simply execute a monitor command, i.e. they are functionally equivalent to buttons in the button modules. If the monitor command requires parameters, they are prompted for using dialogs in the same way as the command buttons.

The following tables list the default menu choices and the corresponding monitor command. See "Monitor Commands" for more information.

Note:

The additional menus in the SimUI are specified in the button definition file. If the default button file is not used, the button modules may be different than described here. See "Button and Menu Definitions" for more information.

General Menu

Menu choice | Monitor command
Command | ? (Interactive Context Sensitive Help)
Start SDL Env | Start-SDL-Env
Version | Show-Versions
News | News

Execute Menu

Menu choice | Monitor command
Go | Go
Over Symbol | Next-Symbol
Into Stmt | Step-Statement
Over Stmt | Next-Statement
Finish | Finish
Until Time | Proceed-Until
Until Trace | Next-Visible-Transition
Until Timer | Proceed-To-Timer
Input Script | execute-input-script
Command Script | Include-File
Stop Sim | Exit

Examine Menu

Menu choice | Monitor command
Ready Q | List-Ready-Queue
Now | Now
Process List | List-Process
Input Port | List-Input-Port
Signal | Examine-Signal-Instance
Timer List | List-Timer
Variable | Examine-Variable (
Call Stack | Stack
Set Scope | Set-Scope

Change Menu

Menu choice | Monitor command
Ready Q | Rearrange-Ready-Queue
State | Nextstate
Create Process | Create
Stop Process | Stop
Input Port | Rearrange-Input-Port
Del Signal | Remove-Signal-Instance
Set Timer | Set-Timer
Reset Timer | Reset-Timer
Variable | Assign-Value
Synonym File | set-synonym-file <file name>

Show Menu

Menu choice | Monitor command
Next Symbol | Show-Next-Symbol
Prev Symbol | Show-Previous-Symbol
C Line | Show-C-Line-Number
Coverage | Show-Coverage-Viewer

Trace Menu

Menu choice | Monitor command
Text Level : Set | Set-Trace
- : Show | List-Trace-Values
SDL Level : Set | Set-GR-Trace
- : Show | List-GR-Trace-Values
MSC Level : Set | Set-MSC-Trace
- : Show | List-MSC-Trace-Values
MSC Trace : Start | Start-Interactive-MSC-Log
- : Start Batch | Start-Batch-MSC-Log
- : Stop | Stop-MSC-Log

Breakpoint Menu

Menu choice | Monitor command
Transition | Breakpoint-Transition
Output | Breakpoint-Output
Variable | Breakpoint-Variable
Symbol | Breakpoint-At
Connect sdle | Connect-To-Editor
Remove | Remove-All-Breakpoints
Show | List-Breakpoints

Command Window

The Command window is an optionally visible window used for displaying the results of executed commands. The Command window is opened from the SimUI's View menu.

Figure 454 : The Command window

The Command window is updated automatically whenever the monitor becomes active and after each monitor command. See "Activating the Monitor" for information on when the monitor becomes active. The window can also be updated manually with a menu command.

Any number of commands can be defined to be executed in the Command window. Each command is executed in a scrollable module in the window.

New commands can be added to the window and existing commands can be changed. The commands to execute are by default List-Process and List-Ready-Queue. The set of commands to execute are stored in a command definition file (see "Definition Files" ). The default command definition file can be changed with the Preference Manager.

Command Modules

A command module looks like this:

Figure 455 : A command module

Each module consists of a title bar and a scrollable text area for the command output. The title bar displays:

  • A collapse/expand toggle button. Clicking this button collapses the module so that only the title bar is visible, and expands the module back to its current size so that the text area becomes visible. When a module is expanded, the text area is automatically updated.
  • The command that is executed.
  • A Command button, providing a menu with commands affecting the module.

The Command button contains the following menu items:

Edit

Opens a dialog for editing the command executed.

Delete

Deletes the command and command module from the Command window.

Size

Sets the size of the text area. A dialog is opened where the number of text rows can be set using a slider.

File Menu

The File menu contains the following menu choices:

  • Load
  • Append
  • Save
    (See "Save" .)
  • Save As
    (See "Save As" .)
  • Close
    (See "Close" .)

Load

Reads in a new command definition file that overrides the current command definitions. All commands currently in the Command window are deleted and replaced by the commands defined in the new file. A File Selection Dialog is opened for specifying the file to load.

Append

Appends the contents of a new command definition file into the current command definitions. New commands are added to the command window, but already existing commands are not affected. A File Selection Dialog is opened for specifying the file to append.

Note:

Command names in a command definition file are case sensitive. If a command in an appended file already exists in the Command window, but with different case, the command will be duplicated.

Command Menu

The Command menu contains the following menu choices:

Command

Adds a new command to the Command window. A dialog box prompts for the new command. The new command module is added to the bottom of the window. For the syntax of a command definition, see "Command Definitions" .

Update All

Updates all command modules by executing the defined commands.

Watch Window

The Watch window is an optionally visible window used for displaying values of variables defined in the currently running simulation. The Watch window is opened from the SimUI's View menu.

Figure 456 : The Watch window

The Watch window is updated automatically after each monitor command. The window can also be updated manually with a menu command.

The variables to display are selected with a menu command. The set of selected variables are stored in a variable definition file (see "Definition Files" ).

File Menu

The File menu contains the following menu choices:

  • Load
  • Append
  • Save
    (See "Save" .)
  • Save As
    (See "Save As" .)
  • Close
    (See "Close" .)

Load

Reads in a new variable definition file that overrides the current variable definitions. All variables currently in the Watch window are deleted and replaced by the variables defined in the new file. A File Selection Dialog is opened for specifying the file to load.

Append

Appends new variable definitions to the current variable definitions file. The variables in the file are added to the Watch window. A File Selection Dialog is opened for specifying the file to merge. Duplicate variable definitions are permissible.

Watch Menu

The Watch menu contains the following menu choices:

  • Update All
  • Add
  • Edit
  • Delete
  • Delete All

Update All

Updates the Watch window by showing the current value of all displayed variables.

Add

Adds one or more variables to the Watch window. A dialog is opened for specifying the variable to be added. For the syntax of a variable definition, see "Variable Definitions" . Several modules may be added with the dialog by using the Apply button instead of the OK button.

Edit

Edits a variable specification in the Watch window. The variable whose specification is to be changed is selected in a dialog. When a variable has been selected, the specification can be edited using a dialog.

Delete

Deletes one or more variables from the Watch window. The variables to delete are selected in a dialog.

Delete All

Deletes all variables from the Watch window.

Definition Files

In the SimUI, the following types of information are stored on files:

  • Button definitions
    i.e. definitions of button groups and button commands in the main window's button area.
  • Menu definitions
    i.e. definitions of additional menus and menu commands in the main window's menu bar.
  • Command definitions
    i.e. definitions of commands to be executed in the Command window.
  • Variable definitions
    i.e. definitions of variables to display in the Watch window.

At start-up of the SimUI, the files to read are determined in the following way:

  1. The file names are defined with the Preference Manager. If a file name is not defined there, the default file name def.btns, def.cmds and def.vars is used, respectively.
  2. If the file names does not contain a directory path, the files are searched for in the following directories and the following order:
    • the current directory
    • the user's home directory
    • the installation directory

Once a file has been found, it is read and the contents of the corresponding window are set up. If a file cannot be found, the corresponding window area becomes empty.

Common File Syntax

Each of three text files can contain comment lines starting with the `#' character. Empty lines are not discarded.

Note:

When a file is read, no checks are made upon the relevance or correctness of the definitions contained in the file.

Button and Menu Definitions

The button and menu definitions are stored in a button definition file with the default extension .btns. The button definitions are divided into groups where each group defines a button module in the main window's button area, or a menu in the main window's menu bar.

Syntax

In the file, a button group has the following syntax:

:[COLLAPSED] <group name>
<button label>
<definition>
<button label>
<definition>
. . .

The <group name> is the string shown in the title bar of the button module. If the group name is prefixed with the string COLLAPSED, the button module is initially collapsed. The <button label> is the label of the button in the button module. The <definition> is the monitor command that will be executed when the button is pressed. The syntax of a button definition is the same as when entering a command textually to the monitor.

A menu has the following syntax:

:MENU <menu name>
<menu choice>
<definition>
<menu choice>
<definition>
. . .

The <menu name> is the name of the menu shown in the menu bar. The <menu choice> is the name of the menu choice in the menu. The <definition> is the monitor command that will be executed when the menu choice is selected.

In the monitor command definition, a `?' as parameter will not work, but a hyphen `-' can be used to signify the default value. Missing parameters at the end of the command will open dialogs for those parameters.

Defining Multiple Commands

In addition, a button definition may consist of several monitor commands, if they are separated by a space and a semicolon, i.e. ";". The commands are then executed immediately after each other.

Example 318 : Multiple Commands in Simulator

next-transition ; out-via probe -

This button definition executes the next transition and then sends the signal Probe from the environment.

Command Definitions

The command definitions are stored in a command definition file with the default extension .cmds. Each command definition defines a command module in the Command window. The file has the following syntax:

<command>
<command>
. . .

The <command> is the monitor command that will be executed in the command module. The syntax of a command definition is the same as when entering a command textually to the monitor. All parameter values must be specified explicitly or with the default value `-', i.e. `?' is not allowed, and no parameters may be missing. Command names are case sensitive.

Note:

Care should be taken when deciding what command to execute; commands belonging to the Execute group should be avoided.

Variable Definitions

The variable definitions are stored in a variable definition file with the default extension .vars. Each variable definition defines a variable to display in the Watch window. The file has the following syntax:

(<process>) <variable>
(<process>) <variable>
. . .

The <process> is the name of the process, possibly augmented with an instance number separated with a space or colon. The <variable> is the name of the variable in that process. Names are not case sensitive.

Example 319 : Variable Definitions in Simulator

(Main) Count
(game:1) guess

Macros

The SimUI has a built-in macro facility. A macro can represent a simulator command or a part of a simulator command. Even though SimUI macro commands are processed by the SimUI, it is possible to enter SimUI macro commands almost as if they were normal simulator commands:

  • Type in the SimUI macro command. Note though, that SimUI commands cannot be abbreviated in the same way as simulator commands.
  • Define a button or a menu for the SimUI macro command.

These commands are available for macros:

  • Use add-macro to define a new macro:
add-macro <macro name> <macro value>
Example:
add-macro maxvalue 37329

  • Use list-macros to see all defined macros and their values:
list-macros
Example:
Command: list-macros
Number of macros defined: 1
Macro name: maxvalue
Macro value: 37329

  • Use $ to get the value of a defined macro:
$<macro name>
Example: The SimUI input:
Output-to MySignal ($maxvalue) Main
is sent to the simulator as
Output-to MySignal (37329) Main

  • Use remove-macro to remove an already defined macro:
remove-macro <macro name>
Example:
remove-macro maxvalue

SimUI Commands

The SimUI examines entered textual commands before sending them to the simulator. If they are SimUI commands they are not sent to the simulator.

Here is a list of all SimUI commands and what they do:

  • add-macro
    Adds a new SimUI macro. For details, see "Macros" .
  • check
    Tells the SimUI that the textual simulator output from the next command should be checked.
    • When commands are entered manually and a check command is issued, the SimUI saves the simulator output for the next command in an expected output section in the input history.
    • When commands are read from file by executing an input script, and a check command is encountered, the SimUI compares the simulator output for the next command with the expected output from the input script. The SimUI reports if the check passed or failed.
  • clear-command-history
    Clears the simulator command history without restarting the simulator. This command is useful if you want to save a command history that does not start from the beginning of a simulator session.
  • clear-input-history
    Clears the SimUI input history without restarting the simulator. This command is useful if you want to save an input history that does not start from the beginning of a simulator session.
  • execute-input-script
    Executes the commands found in an input script, i.e. an input history saved to file.
    • If a relative file name is used, then it is interpreted as relative to the Organizer source directory.
    • If parameters are given as a space separated list after the file name, then these parameters can be accessed with $1, $2, ... in the called script. It is also possible to access all parameters with $*, the number of parameters with $# and the name of the calling script with $0.
  • list-macros
    Produces a list of all defined macros and their values. For more details, see "Macros" .
  • remove-macro
    Removes an already existing SimUI macro. For more details, see "Macros" .
  • save-command-history <file name>
    Saves the simulator command history in a command script file (*.com). If no <file name> is given, a file selection dialog appears, where you can specify a file name.
  • save-input-history
    Saves the SimUI input history in an input script file (*.cui). If no <file name> is given, a file selection dialog appears, where you can specify a file name.
  • set-synonym-file <file name>
    Sets the synonym file to use the next time the simulator is restarted from the simulator UI. If no <file name> is given, a file selection dialog appears, where you can specify a file name. Note that the synonym file can also be set from the menu choice SimUI>Change>Synonym File.

Regression Testing

By using the simulator for regression testing, it is possible to check that an enhanced version of an SDL system does not break the old functionality, that is still expected to work for the same SDL system.

With regression testing in the simulator, you can for instance:

  • Send in signals and check that the correct signals are sent back out again.
  • Check that a variable has the correct value at a specific moment.

The basic idea is to save and replay the input history, and check the textual simulator output for selected commands. An input history saved to a file is called an input script. A group of input scripts can be collected in the Organizer together with the SDL system. The Organizer provides the possibility to run a group of input scripts (or test cases). This results in a textual summary where it is easy to see any test case failures. To examine a test case failure in detail, it is possible to run a single test case with the SimUI command execute-input-script (see "SimUI Commands" ).

Note that it is also possible to express test cases with the MSC notation. MSC test cases are converted to input scripts before being run in the simulator.

Here is a small example, to see how it works:

Example 320

In System DemonGame (that is provided as an example in the SDL suite installation), you can (after some initialization) send in a Result signal and expect to get a Score signal back.

To make a test case testing that we get a Score signal back:

  1. Create a simulator for System DemonGame.
  2. Execute the following simulator commands (you do not have to type in the comments):
    • Output-To NewGame Main /* Send in signal NewGame to start a new game. */
    • Next-Transition /* Execute the start transition for process Main. */
    • Next-Transition /* Execute the start transition for process Demon. */
    • Next-Transition /* Execute the transition receiving signal NewGame and creating process Game */
    • Output-To Result Game /* Send in a signal to get the current score. */
    • break-output - env - - - - - - /* Set a breakpoint on signals sent to the environment. */
    • Set-Trace System DemonGame 0 /* Minimize textual trace. */
    • check /* Check the output from the next command. */
    • go /* Execute as far as possible. The simulator will stop and report that the Score signal has been sent to the environment. */
  3. The go command that we are checking produces the following textual simulator output:
    Breakpoint matched by output of Score
  4. Save the input history in an input script, with the SimUI command save-input-history. The last part of the input script will look like this:
check
go
expected-output start
Breakpoint matched by output of Score
expected-output end

  5. Add a symbol for the input script in the Organizer, with Edit > Add New, plain text, do not show in editor.
  6. Connect the symbol to the input script file with Edit > Connect.
  7. Now, make a test: Deselect everything in the Organizer (to make sure that both the SDL system and the input script will be considered) and choose Tools > Simulator Test. After a dialog, a fresh simulator will be created and the test case run. The result is presented in the Organizer Log.
  8. To force a test case failure:
    • Edit the test case (by double-clicking on the Organizer symbol to get a text editor) by changing the expected output to be something different.
    • Save the test case.
    • Repeat the above test.
    • If everything works as expected, the test case fails.
  9. To examine the details of a test case failure:
    • Restart the simulator.
    • Execute the test case (input script) in the SimUI with the execute-input-script command.
    • If everything works as expected, the expected output from the go command did not match the actual output.


Restrictions

Restrictions on Monitor Input

The following restrictions apply to the monitor input:

  • A parameter to a monitor command may not contain more than 5,000 characters.
  • On UNIX, control characters of different types may terminate the simulation program. <Ctrl+C>, <Ctrl+D>, and <Ctrl+Z> are typical characters that might terminate a simulation program.

Restrictions on Dynamic Checks

There are a number of dynamic checks that are not performed at all or performed at the C level by the C runtime system. A C runtime error will of course lead to the simulation program being terminated. The following checks are not made at the SDL level.

  • Several paths from a decision for a certain decision expression value. A simulation program will simply choose one of the existing paths.
  • Overflow of integer and real values are checked at the C level if the actual C system performs these checks. (These checks are likely not to be performed.)


50 Simulating a System

This chapters provides general information related to simulation in the SDL suite and describes the actions you perform when simulating an SDL system.

For a reference to the simulator user interface, see 49 The SDL Simulator.


Structure of a Simulator

In order to generate a simulator, the SDL to C Compiler is used. The simulators generated using the SDL to C Compiler consist of the following components:

  • The Simulated System (the application itself)
  • The Environment Process
  • The Interactive Monitor System
  • The Graphical User Interface (the Simulator UI).

Additional tools support graphical trace when executing a simulator:

  • The SDL Editor
  • The MSC Editor.

Figure 457 : Structure of a running simulator

The Simulated System

The application is a representation in C code of the implementation of the SDL system. Having generated the application (that is, translated the SDL system into C code), the SDL to C compiler generates a makefile which contains instructions about how to compile and link the application together with the appropriate runtime library. A number of libraries are provided, which allow you to generate an application with the desired behavior. For instance, it is possible to have multiple simulators communicate with each other or communicate with an external application, provided that application has the facility to communicate through the Postmaster.

An executing simulation program contains a number of data objects that represent certain SDL objects in the system that is being simulated. Process instances, signal instances (signals that are waiting in the input port of a process instance), and timer instances (timers that are set, but that have not output their corresponding signal instance) are all examples of such objects. These objects, together with the process instance env:1, which represents the environment of the system, and the monitor system, constitute the simulation program (see Figure 457).

The process instances in the simulated system will execute transitions that consist of actions like tasks, decisions, outputs, procedure calls, and so on, according to the rules of SDL. It is assumed that a transition takes no time and that a signal instance is immediately placed in the input port of the receiver when an output operation occurs.

The Environment Process

The function of the environment process instance, env:1, is to be a receiver of signal instances sent from the system to the environment of the system. The input port of env:1 will always hold the last 20 signals sent to the environment.

The Interactive Monitor System

When generating a simulating application, a monitor system is included, the function of which is to allow the interaction between the application and the user via a command-line user interface. The monitor system provides a functionality similar to high-level language debuggers, in which you can, for instance:

  • view and modify objects defined in your SDL system,
  • set breakpoints,
  • control the execution,
  • control the logging facilities,
  • and so on...

The interactive monitor is the interface between the user and the simulated system. The monitor can be seen as an ordinary process instance, which, when executing a transition, accepts commands from the user.

One group of monitor commands terminate the current transition of the monitor, allow one or several other process instances to execute their transitions, and then start a new transition by the monitor.

The Graphical User Interface

A graphical user interface to the monitor system of a simulator, known as the Simulator UI, is also provided. It is a window-based tool which facilitates the use of the monitor system. It contains graphical components, such as buttons, menus, and scrollable lists, which make it easier to run the simulator in an intuitive way. Also, it is designed to minimize the required amount of user interaction.

Note:

Running the graphical user interface requires that the Cbasic SDL to C Compiler is present in your configuration.

When running the Simulator UI, the user has the option to take advantage of the graphical features which are provided, or to enter commands in a command line fashion in the same way as the textual interface.


Generating and Starting a Simulator

There are two ways to generate and start a simulator:

  • A quick way in one single step, adequate for most situations
  • A more complex way in several steps, giving you complete control of the generation and start process.

In the following, the more complex way will be described first, to give a full understanding of the process. The quick way is described in "Quick Start of a Simulator" .

Generating a Simulator

A Simulator for an SDL system, or a part of an SDL system, consists of the C code generated by the SDL to C compiler together with a predefined run-time kernel. To start a Simulator, it is thus necessary to first generate an executable simulator. This is performed in the Organizer.

To generate an executable simulator:

  1. Select a system, block, or process diagram in the Organizer.
  2. Select Make from the Generate menu. The Make dialog is opened.
  3. Turn on the options Analyze & generate code and Makefile.
  4. From the Standard kernel option menu, select Simulation.
  5. If you need to check the Analyzer options, click the Analyze Options button. In the dialog, set the options and click the Set button. For more information about these options, see "Analyzing Using Customized Options" .
  6. Click the Make button.
    On UNIX, a simulator for the system is now generated in the current directory with the name <system>_xxx.sct (the _xxx suffix is platform specific).
    In Windows, a simulator for the system is now generated in the current directory with the name <system>_xxx.exe (the _xxx suffix is kernel and compiler specific).
    The Status Bar of the Organizer reports the progress of the generation; the last message should be "Compiler done."
  7. Open the Organizer Log window from the Tools menu and check that no errors occurred and that a simulator was generated.
    • If errors were found, correct them and repeat the generation process. See "Locating and Correcting Analysis Errors" .
    • If no simulator was generated, repeat the generation process, but click the Full Make button in the Make dialog instead.

Starting a Simulator

An executable simulator can be run in two different modes; graphical mode and stand-alone mode (textual mode).

Graphical Mode

In graphical mode, the Simulator takes advantage of the graphical user interface and integration mechanism of the SDL suite. A separate graphical user interface, the Simulator UI, is started, giving access to the monitor system through the use of menus, command buttons, etc.

To start a simulator in graphical mode:

  1. Select SDL > Simulator UI from the Organizer's Tools menu. The graphical user interface of the Simulator is opened (see "The Graphical Interface" ).
  2. Select Open from the Simulator UI's File menu. A File Selection Dialog is opened.
    • Alternatively, click the Open quick button in the tool bar.
  3. In the dialog, select an executable simulator and click OK.

A welcome message is printed in the text area of the Simulator UI. The monitor system is now ready to accept commands. Please see "Supplying Values of External Synonyms" for some additional information that may affect the start-up.

Stand-Alone Mode (Textual Mode)

In stand-alone mode, the Simulator uses the input and output devices currently defined on your computer, which provide a textual, command-line based user interface. A very limited graphical support is provided when running the Simulator in this mode.

To start a simulator in stand-alone mode, the generated simulator is executed directly from the OS prompt, e.g.

csh% ./system_sma.sct

A welcome message is printed on the terminal:

Welcome to SDL SIMULATOR. Simulating system <system>

Command :

The monitor system is now ready to accept commands. Please see "Supplying Values of External Synonyms" for some additional information that may affect the start-up.

Note:

On UNIX, before a simulator can be run in stand-alone mode, you must execute a command file from the operating system prompt. The file is called telelogic.sou or telelogic.profile and is located in the binary directory that is included in your $path variable.
For csh-compatible shells: source <bin dir>/telelogic.sou
For sh-compatible shells: . <bin dir>/telelogic.profile

Quick Start of a Simulator

A simulator can also be generated and automatically started in graphical mode in one single step.

To quick start a simulator, click the Simulate quick button in the Organizer's tool bar. The following things happen:

  • A simulator is generated by using the simulator kernel that is specified in the Make dialog. (If no simulator kernel is specified, a default simulator kernel is used.)
  • The graphical Simulator UI is started. If a Simulator UI with the same simulator name is already open, this UI is reused. If another Simulator UI is open, a dialog is opened where you can select to start a new UI, or to reuse one of the existing UI's.
  • The generated simulator is started from the Simulator UI.

Restarting a Simulator

An executing simulator can be restarted from the beginning to reset its state completely:

  • In graphical mode, select Restart from the Simulator UI's File menu. (This is the same as opening the same simulator again.) A confirmation dialog is opened.
  • In stand-alone mode, the simulator has to be exited with the Exit command and then executed from the OS prompt again.

Supplying Values of External Synonyms

The SDL system for the simulator may contain external synonyms that do not have a corresponding macro definition (see "External Synonyms" ). In that case, you will be asked to supply the values of these synonyms, either by selecting a file with synonym definitions, or by entering each synonym value from the keyboard.

In stand-alone mode, the following prompt appears:

External synonym file :

Enter the name of a file containing synonym definitions, or press <Return> to be prompted for each synonym value.

In graphical mode, a file selection dialog is opened. Either select a file (*.syn) containing synonym definitions, or press Cancel to be prompted for each value in a separate dialog. In this dialog, the name and type of the synonym is shown together with an input text field. You can now do the following:

  • Enter a value and click OK.
  • Click Default value to get a "null" value for the synonym type entered in the input field. Accept or edit this value and click OK.
  • Click Cancel to give the synonym a "null" value (without the possibility to edit the value).
  • Click Cancel all to give the synonym and all following synonyms a "null" value.

If a synonym file is selected in the file selection dialog, this file is also used when the simulation is restarted. (If you want to use another synonym file you have to set-synonym-file simulator UI command.)

If you set the environment variable SDTEXTSYNFILE to a file before starting the SDL suite, this file will automatically be used. If SDTEXTSYNFILE is set to "[[" all synonyms are given "null" values.

Note that the simulator lists all external synonyms that have been given values in another way than from a synonym file. This is done to make it easy to cut and paste information to a synonym file, for future use. An example:

The following external synonyms were not found in synonym file
/home/lat/simulator.syn:

myThirdSynonym (integer)

The syntax of a synonym file is described in "Reading Values at Program Start up" .

Actions on Simulator Start-up

When a simulator is started, the static process instances in the system are created, but their initial transitions are not executed.

If a file called siminit.com exists in the current directory an implicit Include-File command will be done on this file at startup.


Issuing Monitor Commands

Whenever the interactive monitor system becomes active, commands are accepted from the user. When running the simulator in stand-alone mode, commands can only be entered textually from a command prompt. When running the simulator in graphical mode, commands may be issued both textually and through the use of menus and buttons.

Activating the Monitor

The simulator's monitor system becomes active when the simulator is started, when the execution has reached a stop condition or a breakpoint, when the system is completely idle, when a semantic error occurs, or when the execution is manually stopped.

These conditions are listed in greater detail in "Activating the Monitor" .

The Textual Interface

The commands to the monitor system consist of a command name and possibly one or more parameters to the command, separated by spaces or carriage return. The following general rules apply:

  • All command names and parameter values are case insensitive. They may also be abbreviated, as long as they are unique. For instance, the command List-Ready-Queue can be entered in any of the following ways:
List-Ready-Queue
list-ready
l-r-q

  • If not all parameters to a command are given on the command line, the missing parameters will be prompted for. A parameter may be optional, in which case a default value always exists. Default values may also exist for required parameters.
  • If you enter an unallowed value for a parameter, an error message is printed and the command is not executed. This is the only way to cancel a command that has been entered.

Getting Command Help

To get a simple list of all possible command names, enter a `?' at the command prompt. A command can then be entered after the list.

To get a list of all commands, grouped into different categories, use the command Help without parameters.

To get a list of all possible commands starting with a certain string, enter the string and hit <Return>. Unless the string was a complete command, all command names starting with the entered string are listed. The following example shows how to list all output commands:

Command : out
Command was ambiguous, it might be an abbreviation of:
Output-To Output-Via Output-None Output-Internal

To get short help on a specific command, use the Help command and specify the command in question as a parameter, e.g.

Command : help help

Help <Optional command name>

Issuing the help command will print all the available commands. If help is entered with a command name, this command will be explained.

Entering Parameters

To get a list of possible parameter values, enter a `?' on the command line or when prompted for a missing parameter.

To specify a default value for a parameter, enter a `-' on the command line or when prompted for a missing parameter.

If a default value exists for a parameter, you may also hit <Return> when prompted for the parameter to accept the default value. However, if no default value exists, this will list the possible values and prompt for the parameter again.

Hint:

Before you are acquainted with the monitor commands and their parameters, it is generally a good idea to only enter the command names, without parameters. When prompted for parameters, use `?' to list possible values, and `-' to accept default values.

The Graphical Interface

The graphical Simulator UI is illustrated in the figure below:

Figure 458 : The Simulator UI

All input and output texts to and from the simulator monitor is displayed in the text area to the right.

Entering Commands Textually

To enter monitor commands textually:

  1. Place and click the mouse pointer inside the Command: input field at the bottom right, below the text area.
  2. Enter the command on the input line. The same syntax is used as when running in stand-alone mode; see "The Textual Interface" . However, prompting for missing parameters are done by issuing dialogs, where the parameter value can be entered or selected from a list of possible values. See "Selecting Parameters" .

Monitor commands entered textually are saved in a history list. To re-execute a command in the history list:

  1. Place the mouse pointer inside the input field.
  2. Use the arrow keys <Up> and <Down> to display the commands that have been entered earlier.
  3. Hit <Return> on the command line to re-execute the displayed command. You may edit the command before executing it.

Issuing Commands Using Buttons

The preferred way to issue monitor commands is by using the command buttons in the left area of the Simulator UI, or by using menu choices in the menu bar. Each button or menu choice correspond to a certain monitor command. The buttons are grouped into modules, corresponding to different categories and uses of the commands. The groups are similar to those listed when using the Help command in the textual interface.

To "preview" the command associated with a button or menu choice, without executing it:

  1. Place the mouse pointer on the button or menu choice and press the mouse button. The name of the monitor command is displayed in the Status Bar at the very bottom of the Simulator UI.
  2. Move the mouse pointer outside the button or menu and release the mouse button.

To execute a command, simply click on a button.

Selecting Parameters

Parameters to monitor commands are prompted for in dialogs (unless they have been specified on the command input line). If a parameter has a set of possible values, the list of values is presented from which you may select a value:

Figure 459 : A typical parameter dialog

In this dialog, the values can be sorted alphabetically by clicking the Sort button. After having entered an initial string, you can also press <Space> to select the first value starting with this string, or press `?' to select the first value containing this string. Additional <Space> or `?' characters will select the next value, etc. When there are no more matches, a real space or `?' character will be added after the string you initially entered.

File parameters are prompted for in File Selection Dialogs. Other parameters, like integers, are prompted for in a simple text input dialog.

  • To accept a selected or entered value, click OK in the dialog.
  • To enter a "null" value for the parameter in the input field, click Default value (only available for some parameter types).
  • To specify a possible default value, click OK without having selected or entered any value, or enter a `-' in the dialog's text input field.
  • To cancel a command, click Cancel in any of the parameter dialogs, or enter an unallowed value in the dialog's text input field.

Selecting Signal Parameters

If a command parameter is an output signal and you select a signal which in turn have parameters, the signal parameters are asked for in a separate dialog. In this dialog, all parameters are listed with their default ("null") values:

Figure 460 : Editing signal parameters

To edit a signal parameter, you select the parameter and then edit the value displayed in the input field. If the parameter is of an enumerated type, the possible values can also be selected from the option menu just above the input field. By clicking Default value, the "null" value will be inserted in the input field. A changed parameter value is not updated in the parameter list until a parameter is selected in the list.

Click OK to accept all parameter values, and Cancel to abort the monitor command. The validity of the parameter values is not tested until you click the OK button.

Undo/Redo Commands

To undo a previous command, click the Undo quick button in the tool bar, or select Undo in the popup menu that is available in the text area. Then you get a dialog with all commands you have given so far. All commands are shown, even the ones entered using buttons or menu choices.

Figure 461 : Undoing a command

Initially all commands except the last is selected. If you click OK the simulation is restarted and all the selected commands will be re-executed. By clicking on the commands in the dialog you can decide which commands you want to be re-executed in the restarted simulation.

Note:

The Undo function cannot handle to undo commands for setting or removing graphical breakpoints.

To redo a command in the current simulation, select Command in the popup menu in the text area. Then you also get a dialog with all commands you have given so far, in the same way as for Undo.

Figure 462 : Redoing a command

After selecting one of the commands and clicking OK the command is executed. You can also change the command on the command line before clicking OK.


Customizing the Simulator UI

In the Simulator UI, you may change the contents and appearance of button modules and some additional windows. All these configurations are stored in a number of definition files, which are read at start-up of the Simulator UI. If you change any of the configurations, you are prompted to save them when you exit the Simulator UI.

Managing Command Buttons

You may wish to add your own command buttons for frequently used commands, or to change or delete existing command buttons. These operations are invoked from the Group menu in the button modules:

Figure 463 : The Group menu

Adding a Button

To add a button to a module:

  1. Select Add from the Group menu. A dialog is opened:

Figure 464 : Adding a button

  2. Enter a button label and a monitor command definition. The same syntax is used as when entering commands textually. If you omit a parameter value, it will be asked for in a parameter dialog when the command is executed.
  3. Click OK to add the button and close the dialog. If you click Apply, the button is added and you can specify another button to add.

Note:

You cannot specify the location of the button in the module. It will be placed in the next available empty position.

Changing a Button

To change an existing button in a module:

  1. Select Edit from the Group menu. A dialog is opened:

Figure 465 : Selecting a button

  2. Select the button to edit and click OK. A dialog similar to when adding a button is opened (see Figure 464).
  3. Edit the button label and/or the command definition and click OK.

Deleting a Button

To delete an existing button in a module:

  1. Select Delete from the Group menu. A dialog similar to when editing a button is opened (see Figure 465).
  2. Select the button to delete and click OK. The button is deleted from the module and the remaining buttons are possibly re-arranged.

Managing Button Modules

In addition to the command buttons, you may also add, rename, delete and collapse/expand the button modules.

Collapsing and Expanding Modules

Modules may be collapsed and expanded to only show the command buttons of interest at the moment. A collapsed module hides all of its buttons and only displays the title bar:

Figure 466 : A collapsed button module

To collapse and expand a module, click the toggle button to the left of the module name in the title bar.

To collapse and expand all modules, select Collapse Groups or Expand Groups in the Buttons menu.

Adding, Deleting and Renaming a Module

To add a new module to the bottom of the button module area, select Add Group in the Buttons menu. In the dialog, enter the module's name and click OK.

To delete a module, select Delete Group from the module's Group menu. In the confirmation dialog, click OK.

To rename a module, select Rename Group from the module's Group menu. In the dialog, enter a new name and click OK.

The Command and Watch Windows

In the Simulator UI, you can continuously view the internal status of the system by using the Command and Watch windows. These windows are opened from the View menu. They are both updated automatically whenever the monitor system becomes active.

The Command Window

In the Command window, you can execute a number of monitor commands automatically. The commands are executed in command modules, similar to button modules in the main window of the Simulator UI:

Figure 467 : The Command window

By default, the commands List-Ready-Queue and List-Process are executed. You are advised to only use commands for examining the system, see "Examining the System" .

The command modules are managed in the following ways:

  • To add a command module, select Command from the Command menu in the menu bar. In the dialog, enter the monitor command to execute, including possible parameters.
  • To change the command executed in a module, select Edit from the module's Command menu. In the dialog, enter a new command and click OK.
  • To delete a command module, select Delete from the module's Command menu. No confirmation dialog is issued.
  • To change the size of a module's text output area, select Size from the module's Command menu. In the dialog, use the slider to set the number of text lines to be visible.
  • To collapse or expand a module, click the toggle button to the left of the module name in the title bar.

The Watch Window

In the Watch window, you can automatically monitor values of variables in the system. The variables are displayed on separate lines in the window:

Figure 468 : The Watch window

By default, the Watch window is empty. To add a variable, select Add from the Watch menu. In the dialog, enter the variable specification and click OK. A variable specification consists of the process instance name within parenthesis, followed by the variable name, e.g.
(game:1) count.

To change a variable specification, select Edit from the Watch menu. In the dialog, select the variable to edit and click OK. In the next dialog, you can edit the specification and click OK.

To delete a variable specification, select Delete from the Watch menu. In the dialog, select the variable to delete and click OK.


Tracing the Execution

When the SDL system is executing during simulation, you can obtain trace information of the execution. This makes it easier to follow the events that happen during execution.

There are three types of execution traces:

  • Textual Trace, printed in the Simulator UI's text area, or on the terminal (in stand-alone mode)
  • GR Trace, graphically illustrated by selecting SDL symbols in an SDL Editor
  • MSC Trace and Logging, illustrated by drawing MSC events in an MSC Editor, or by saving the MSC events to a log file.

The amount of trace is determined by a trace value for each of the three trace types. The trace value controls the level of detail in the trace; the trace value 0 (zero) means no trace. Setting appropriate trace levels is often something you would like to do before the execution is started.

Apart from these continuous trace functions, there are also other possibilities to trace the execution. See "Other Tracing Functions" .

Specifying Unit Names

Trace values can be assigned to different units of the SDL system; the system as a whole, blocks, process types, and process instances.

  • When using the Simulator UI, you will be presented with a list of all units in the system, from which you may select the appropriate unit.
  • When running the simulator stand-alone, you have to specify a unit, unless you want to set the trace for the system. In the trace commands described below, you may abbreviate the name of the unit. However, if several units match a unit name, the first unit found from the system level will be used. To make sure the correct unit is specified, the name can be prefixed with the diagram type or a qualifier.

Example 321 : Specifying Trace Unit Names

System Demongame
Block GameBlock
Process Game

In this diagram structure, the unit name "Game" would refer to the block GameBlock. To specify the process Game instead, the unit could be expressed as "process Game" or "<<System Demongame / Block GameBlock>> Game".

Determining the Scope of Trace

When a process instance executes a transition, or part of a transition, the trace value for the instance is found using the following algorithm:

  1. If a trace value is defined for the process instance executing the transition, that value is used.
  2. If not, and a trace value is defined for the process type, that value is used.
  3. Otherwise, if a trace value is defined for the block enclosing the process, that value is used.
  4. If still no trace value is found, the block structure is followed outwards until a unit is reached which has a trace value defined. The system always has a trace value defined.

For MSC trace the situation is slightly more complex; see "MSC Trace" .

Textual Trace

Textual trace is printed for the transition or the SDL symbols that were last executed.

To quickly set the maximum textual trace level (6) for the system, click the TEXT button in the Trace module.

The general procedure to set the trace value for textual trace is:

  1. Choose Text Level : Set in the Trace menu, or enter the command Set-Trace. The command takes two parameters, an optional unit name and the trace value.
  2. Select or enter the name of the unit to set the trace for. If you do not specify a unit name, or the default name `-' is entered, the trace will be set for the whole system.
  3. Select or enter a trace value between 0 and 6. The trace values are shortly described in the dialog, or after hitting <Return> in stand-alone mode. The following table explains them in more detail; for a full explanation, see "Trace Limit Table" . The default textual trace value is 4 for the system.

Value
Trace Explanation and Examples
0
No trace
1
Trace of signals sent to the environment, as seen from the specified unit. This is useful if you only want to look at the external behavior of the unit. Example:
 *   OUTPUT of Score from Game:1 to env:1
 *      Parameter(s) : -1
2
Trace of transition start and timer outputs, i.e. what is causing the transition to occur.
For transition starts, the process instance, initial state, input signal, sender process and value of Now is printed, e.g.:
 *** TRANSITION START
 *      PId    : Demon:1
 *      State  : Generate
 *      Input  : T
 *      Sender : Demon:1
 *      Now    : 1.0000
For timer outputs, the timer name, receiver process and value of Now is printed, e.g.:
 *** TIMER signal was sent
 *   Timer    : T
 *   Receiver : Demon:1
 *** Now      : 1.0000
3
As 2 + trace of important SDL actions, e.g. signal output, create, timer set and reset, nextstate and stop. Examples:
 *   SET on timer T at 1.0000
 *   CREATE Game:1
 *   OUTPUT of Bump to Game:1
 *** NEXTSTATE  Generate
4
As 3 + trace of other SDL actions as well, e.g. task, decision and export. Example:
 *   ASSIGN  Count :=
5
As 4 + result of actions, e.g. null transitions, implicit resets, and discarded signals.
6
As 5 + print of parameter values for signals, timers, create actions, etc. Examples:
 *   ASSIGN  Count := 1
 *   OUTPUT of Score to env:1
 *      Parameter(s) : 1

To list the textual trace values that are defined for the units in the system, choose Trace Level : Show in the Trace menu, or enter the command List-Trace-Values.

You can also reset the trace value for textual trace for a unit, i.e., set it to undefined. To do this, enter the command Reset-Trace and specify a unit (there is no button for this command).

GR Trace

GR trace will open an SDL Editor and continuously select the next SDL symbol to be executed in the corresponding process diagram. (See also "Tracing Simulations (Graphical Trace)" .)

To quickly set the GR trace level for the system to 1 (see below), click the SDL button in the Trace module.

The general procedure to set the trace value for GR trace is:

  1. Choose SDL Level : Set in the Trace menu, or enter the command Set-GR-Trace. The command takes two parameters, an optional unit name and the trace value.
  2. Select or enter the name of the unit to set the trace for. If you do not specify a unit name, or the default name `-' is entered, the trace will be set for the whole system.
  3. Select or enter a trace value between 0 and 2. The trace values are shortly described in the dialog, or after hitting <Return> in stand-alone mode. The following table explains them in more detail. The default GR trace value is 0 for the system.

Value | Trace Explanation
0 | No trace.
1 | In an SDL Editor, show the next SDL symbol to be executed. This only happens when the monitor is activated the next time, i.e. when it becomes ready to accept a new command. No symbols are selected during execution when the monitor is inactive.
2 | In an SDL Editor, follow the execution and show each SDL symbol as it is executed, until the monitor is activated again.

To list the GR trace values that are defined for the units in the system, choose SDL Level : Show in the Trace menu, or enter the command List-GR-Trace-Values.

You can also reset the trace value for GR trace for a unit, i.e., set it to undefined. To do this, enter the command Reset-GR-Trace and specify a unit (there is no button for this command).

MSC Trace and Logging

MSC trace will enable transformation of the SDL events that take place during execution into corresponding MSC events. Of course, not all SDL events are possible to transform into MSC events; typically, the events that can be transformed are sending and consumption of signals, setting and expiration of timers, and creation and termination of processes. By default, this transformation is enabled for the whole system.

The MSC events that are created by MSC trace can then be logged in two different ways:

  • by opening an MSC Editor and continuously adding the events to an MSC diagram created for this purpose, or
  • by continuously saving the events to a log file that later can be opened from an MSC Editor.

Therefore, setting the MSC trace value does not start the actual logging of MSC events in an MSC Editor or on file.

MSC Trace

To set the trace value for MSC trace:

  1. Choose MSC Level : Set in the Trace menu, or enter the command Set-MSC-Trace. The command takes two parameters, an optional unit name and the trace value.
  2. Select or enter the name of the unit to set the trace for. If you do not specify a unit name, or the default name `-' is entered, the trace will be set for the whole system.
  3. Select or enter a trace value between 0 and 3. The trace values are shortly described in the dialog, or after hitting <Return> in stand-alone mode. The following table explains them in more detail; for a full explanation, see "Message Sequence Chart Traces" . The default MSC trace value is 1 for the system.

Value | Trace Explanation
0 | No trace.
1 | For an MSC event that involves another unit, trace only if that unit's trace value is greater than 0.
2 | For an MSC event that involves another unit, trace always, even if that unit's trace value is 0. Such an MSC event will be logged to interact with a special "void" instance in the MSC diagram.
3 | Trace on block levels.

To list the MSC trace values that are defined for the units in the system, choose MSC Level : Show in the Trace menu, or enter the command List-MSC-Trace-Values.

You can also reset the trace value for MSC trace for a unit, i.e., set it to undefined. To do this, enter the command Reset-MSC-Trace and specify a unit (there is no button for this command).

Logging of MSC Events

To start the continuous logging of MSC events in an MSC Editor:

  1. Choose MSC Trace : Start in the Trace menu, or enter the command Start-Interactive-MSC-Log. The command takes one parameter, a symbol level determining the amount of information that should be part of the MSC.
  2. Select or enter a symbol level between 0 and 2 (see the table below).
    An MSC Editor is opened and the execution is then traced by adding MSC events to the created diagram. (See also "Tracing a Simulation in a Message Sequence Chart" .)

To quickly start the continuous logging of MSC events in an MSC Editor with symbol level 1, click the MSC button in the Trace module.

To start the continuous logging of MSC events in a log file:

  1. Choose MSC Trace : Start Batch in the Trace menu, or enter the command Start-Batch-MSC-Log. The command takes two parameters, a symbol level and the name of the log file. The symbol level determines the amount of information that should be logged.
  2. Select or enter a symbol level between 0 and 2 (see the table below).
  3. Select or enter a log file name, preferably with the suffix .mpr.

When an MSC log is started, the amount of information that should be part of the log can be decided by giving the symbol level parameter an appropriate value, according to the table below:

Level | Information in MSC
0 | Basic MSC, i.e. containing events for signals and timers plus create and stop.
1 | Basic MSC extended with condition symbols for each nextstate.
2 | Basic MSC extended with condition symbols for each nextstate and action symbols for task, decision, call, and return.

Note that you cannot have both types off logging enabled at the same time. To see what type of logging is enabled, enter the command List-MSC-Log (this command has no button).

To stop the logging, choose MSC Trace : Stop in the Trace menu, or enter the command Stop-MSC-Log. If you used logging to an MSC Editor, you should then save the trace from the editor. If you used logging to file, the file is automatically saved and closed.

Other Tracing Functions

Showing SDL Symbols

If you do not have GR trace enabled, it is still possible to show the next symbol to be executed in an SDL Editor. To do this, choose
Next Symbol in the Show menu, or enter the command Show-Next-Symbol.

In a similar fashion, the last executed symbol can be shown in an SDL Editor. This will give you a correspondence between textual trace and the SDL Editor, since textual trace always is printed for the last executed symbols. To do this, choose Prev Symbol in the Show menu, or enter the command Show-Previous-Symbol.

Tracing Back to C Code

A trace-back to the generated C source code for the system is also possible. To show where in the C code the execution is at the moment, choose C Line in the Show menu, or enter the command Show-C-Line-Number. The file name and line number of the C source file is printed, and the C source file is opened in the Text Editor, positioned on the correct line.

Generating Coverage Information

To see how much of the SDL system you have covered during simulation, you can open the coverage information in a Coverage Viewer, and for instance examine which parts of the system that have not been executed during the simulation. To start the Coverage Viewer, choose Coverage in the Show menu, or enter the command Show-Coverage-Viewer.


Executing a Simulator

There are a number of monitor commands for executing one or more transitions in process instances, and for stepping symbol by symbol within a transition.

Note:

During execution, you may be prompted for input before the execution can continue. See "Run-time Prompting" for more information.

Continuous Execution

To start executing the simulation program continuously, click the Go button in the Execute module, or enter the command Go. The execution continues until one of the conditions listed in "Activating the Monitor" becomes true, for instance when reaching a breakpoint. See also "Stopping the Execution" .

Note:

The button Forever, corresponding to the command Go-Forever, behaves very similar to the above. The difference is that the monitor does not become active when the system is completely idle. This feature is valuable when communicating with other simulations or applications.

Executing Until a Condition

To execute until a certain point in time:

  1. Choose Until Time in the Execute menu, or enter the command Proceed-Until. The command takes one parameter, the value of the simulation time when to stop executing.
  2. Enter a time value, either an absolute value (without sign) or a value relative to Now (with a `+' sign). That is, "7.5" is an absolute time value, whereas "+7.5" is the time value Now+7.5.

To execute until, but not including, the next timer output, click the Until Timer button in the Execute module, or enter the command
Proceed-To-Timer.

Executing Transitions

To execute the next transition, or the remainder of the current transition, click the Transition button in the Execute module, or enter the command Next-Transition.

To execute a number of transitions until a transition with a textual trace value > 0 has been executed, choose Until Trace in the Execute menu, or enter the command Next-Visible-Transition. This is very valuable when you have set the trace value for some "uninteresting" parts of the system to 0, and you want to skip over those parts.

Single-Stepping Symbols or Statements

To execute only the next SDL symbol, choose Over Symbol in the Execute menu, or enter the command Next-Symbol. This may execute several statements, and will step over procedure calls.

To execute only the next SDL statement, choose Over Stmt in the Execute menu, or enter the command Next-Statement. This will step over procedure calls.

Executing Procedures

The only way to follow the execution into a procedure is to use the following single-stepping functions.

To execute only the next SDL symbol, and to step into possible procedure calls, click the Symbol button in the Execute module, or enter the command Step-Symbol. This may execute several statements.

To execute only the next SDL statement, and to step into possible procedure calls, choose Into Stmt in the Execute menu, or enter the command Step-Statement.

To execute a procedure up to and including its return, choose Finish in the Execute menu, or enter the command Finish. In a process, this command behaves exactly like Next-Transition.

Stopping the Execution

To stop the execution of transitions and symbols manually:

  • In the Simulator UI, click the Break button in the Execute module.
  • In stand-alone mode, press <Return> during printing of trace information (repeatedly, if necessary). No other characters may be typed before <Return> is pressed.

Caution!

There are some situations in which it is not possible to stop the execution in this way, for instance in an endless loop within an SDL symbol. The only way to stop the simulator in these situations is to terminate the simulation program from the operating system, for instance by pressing <Ctrl+C>, in which case all simulation results are lost.


Examining the System

In the Simulator, you can issue a number of monitor commands to examine the internal status of the system. Detailed information concerning processes, procedure calls, signals, timers, and variables can be requested. Using the Simulator UI, you may continuously view the internal status by using the Command and Watch windows; see "The Command and Watch Windows" .

Current Process and Scope

Some of the commands used for examining the system operate on a specific process instance, the current process, identified by the current scope. A scope is a reference to a process instance, a reference to a service instance if the process contains services, and possibly a reference to a procedure instance called from this process/service (the current procedure). The scope is also used by some of the commands for modifying the system; see "Modifying the System" .

The scope is automatically set by the execution commands, when entering the monitor, to the next process instance in turn to execute. You may change the scope if you would like to examine (or modify) another process, service or procedure instance. Changing the scope does not change the execution order of process instances. As soon as the execution continues again, the scope is reset to the next process instance in turn to execute.

The Process/service Scope

To print the current process/service scope enter the command Scope.

To set the current process/service scope:

  1. Choose Set Scope in the Examine menu, or enter the command Set-Scope. This command takes one parameter, a process instance, and optionally if the process contains services, a second parameter which specifies a service name.
  2. Select or enter the name of a process instance.
  3. If the process instance contains services, select or enter the name of a service instance.

The scope is set to the specified process/service, at the bottom procedure call.

The Procedure Scope

To print the procedure call stack for the process/service instance defined by the current scope, choose Call Stack in the Examine menu, or enter the command Stack.

To change the procedure scope within the current process/service scope, you can move the scope one step up or down in the procedure call stack by entering the command Up or Define-MSC-Trace-Channels. Going up from a service leads to the process containing the service. To go down in a service within a process, select or enter the name of the service instance.

Printing the Simulation Time

To print the current value of the simulation time, in case it is not displayed by the textual trace, choose Now in the Examine menu, or enter the command Now.

Printing the Process Ready Queue

The ready queue is the queue of process instances that are ready to execute a transition, i.e., those instances that have received a signal that can cause an immediate transition, but that have not yet had the opportunity to execute this transition to its end.

To print an ordered list of the process instances in the ready queue, choose Ready Q in the Examine menu, or enter the command List-Ready-Queue. The list contains an entry number (queue position), the process instance, its current state, the number of signals in its input port, and the name of the signal that will cause the next transition. If a process instance has active procedure calls, the current executing procedure instance is also listed. If the state name is followed by a `*', then the process/procedure is currently executing a transition starting from this state.

The ready queue is by default printed in the Command window. It may look like this:

Figure 469 : The ready queue in the Command window

Examining Process Instances

To list all active process instances of a certain process type:

  1. Click the Process List button in the Examine module, or enter the command List-Process. The command takes one parameter, the name of the process type. (The button already has the parameter `-'.)
  2. Select or enter a process type. If no process type is specified, or it is specified as `-', all active process instances in the system are listed. The list contains the same details as described for the process ready queue, above.

To print information about the current process instance, enter the command Examine-PId. The information contains the current values of Parent, Offspring, Sender and a list of all currently active procedure calls made by the process instance (the stack). For more information on current process and procedure call stack, see "Current Process and Scope" . An example of output is:

Parent : null
Offspring : Game:1
Sender : env:1

PId Main:1

Examining Signal Instances

To list all signal instances in the input port of the current process instance, choose Input Port in the Examine menu, or enter the command List-Input-Port. The list contains an entry number (queue position), the signal type, and the sending process instance. If the entry number is prefixed by a `*', the signal instance is the one to be consumed in the next transition performed by the process instance. For more information on the current process, see "Current Process and Scope" . An example of output is:

Input port of Game:1
Entry Signal name Sender
*1 Bump Demon:1
2 GameOver Main:1

To print the parameters of a signal instance in the input port of the current process instance:

  1. Choose Signal in the Examine menu, or enter the command Examine-Signal-Instance. This command takes one parameter, an entry number in the input port.
  2. Enter an entry number. To see what entry number is associated with the signal instance, list the input port as described above. An example of output is:
Signal name : Score
Parameter(s) : -1

Examining Timer Instances

To list all active timers in the system, choose Timer List in the Examine menu, or enter the command List-Timer. The list contains an entry number, the timer name, the corresponding process instance, and the associated time. An example of output is:

Entry Timer name PId Time
1 T Demon:1 4.0000

To print the parameters of an active timer instance:

  1. Enter the command Examine-Timer-Instance. This command takes one parameter, an entry number in the timer list.
  2. Enter an entry number. To see what entry number is associated with the timer instance, list the active timers as described above. If only one timer is active, the entry number is not needed.

Examining Variables

To print the value of a variable or formal parameter in the current process or procedure:

  1. Click the Var In Scope button in the Examine module, or enter the command Examine-Variable. This command takes two optional parameters, the name of the variable and a specification of a variable component.
  2. Select or enter the name of a variable, possibly abbreviated. If no variable name is specified, all variables and formal parameters of the current process or procedure are printed.
    If a variable has several components (e.g. an array, struct or string) and it is specified without a component, the values of all components of the variable is printed (e.g. the complete array).
    • To print only a certain component, specify the component after the variable name. (In the Simulator UI, this must be done on the text input line in the dialog, after a variable name has been selected.)
    • To get a list of the possible components of a variable, enter a `?' after the variable name. (In the Simulator UI, this must be done on the text input line in the dialog, after a variable name has been selected; another dialog is then opened, in which the component can be selected.)
      More information on the input and output of SDL data types can be found in "Input and Output of Data Types" .

To examine variables or formal parameters in any process, click the Variable button in the Examine module. In addition to the variable name and component (as described above), you will be prompted for the process name.


Managing Breakpoints

By setting breakpoints in the system, the execution of a simulator can be stopped and the monitor system activated at a certain point of interest. They can be used to trap certain SDL symbols, transitions, signal outputs, and variable changes.

Breakpoints are often used together with continuous execution to reach a certain state of the system (see "Continuous Execution" ). The monitor system becomes active when the breakpoint condition becomes true. Care should be taken when using continuous execution with breakpoints; if the breakpoint is never reached, the system may continue executing "forever."

Breakpoint Commands

When defining a breakpoint, you may specify one or more monitor commands to be executed after the breakpoint has been reached. In this way it is possible to, for instance, automatically print information about the system by using the examine commands. The monitor commands are specified using the same syntax as when entering them textually.

If you want to use several monitor commands, they have to be separated by spaces and semicolons. It is even possible to use the execution commands in this context to automatically continue the execution after a breakpoint has been reached. However, care should be taken to make sure the system does not end up executing "forever." An example of a combination of breakpoint commands may be:

Examine-PId ; Go

Setting a Symbol Breakpoint

Symbol breakpoints are set on a specific SDL symbol. Symbol breakpoints are checked before a symbol is executed, i.e., the symbol is not executed when the breakpoint is reached.

There are two ways to set a symbol breakpoint, either graphically by selecting the SDL symbol directly in the SDL Editor, or textually by specifying an SDT reference to the SDL symbol.

When a symbol breakpoint has been set, the breakpoint is indicated by a red "stop" sign placed at the SDL symbol in the SDL diagram.

To set a symbol breakpoint graphically using the SDL Editor:

  1. If necessary, open an SDL Editor on the diagram containing the SDL symbol.
  2. Choose Connect sdle in the Breakpoint menu in the Simulator UI, or enter the command Connect-To-Editor. A new menu Breakpoints now appear in the SDL Editor.
  3. Select the symbol in the SDL Editor.
  4. From the Breakpoints menu in the SDL Editor, choose one of the two Set Breakpoint commands. The first command opens a dialog to allow entering one or more optional breakpoint commands. The second command sets the breakpoint without any breakpoint command.

To set a symbol breakpoint textually using an SDT reference:

  1. Choose Symbol in the Breakpoint menu, or enter the command Breakpoint-At. This command takes two parameters, a textual SDT reference to the SDL symbol and an optional breakpoint command.

Setting a Transition Breakpoint

Transition breakpoints are set on a transition, i.e. the combination of a process instance, state, signal and sender. Transition breakpoints are checked before a transition is executed, i.e., the transition is not executed when the breakpoint is reached.

To set a transition breakpoint:

  1. Choose Transition in the Breakpoint menu, or enter the command Breakpoint-Transition. This command takes the following parameters: the process name and instance number, the name of a service, the state of the process/service, the signal, the sender's process name and instance number, a breakpoint counter, and an optional breakpoint command.
    Any of the parameters may be omitted or given the value `-', which means that any value will match that parameter. In this way, transition breakpoints can be matched by more than one transition.
  2. Select or enter the name of the process in which the transition exists. If no process is specified, any process will match.
  3. Enter the instance number of the process. If no instance number is specified, any instance of the process specified above will match.
  4. Select or enter the name of the service of interest.
  5. Select or enter the state of the process where the transition is executed from. If no state is specified, any state will match.
  6. Select or enter the name of the signal that causes the transition. If no signal is specified, any signal will match.
  7. Select or enter the name of the process sending the signal. If no process is specified, any sender process will match. Note that "env" may be entered for the environment process.
  8. Enter the instance number of the sender process. If no instance number is specified, any instance of the process specified above will match.
  9. Enter a breakpoint counter, i.e. how many times the breakpoint condition must be true before the execution is stopped. If no counter value is specified, the default value 1 is used.
  10. Enter one or more optional breakpoint commands.

Setting an Output Breakpoint

Output breakpoints are set on a signal output, i.e. the combination of a signal, sender process and receiver process. Output breakpoints are checked immediately after a signal is sent.

To set an output breakpoint:

  1. Choose Output in the Breakpoint menu, or enter the command Breakpoint-Output. This command takes the following parameters: the signal name, the sender's process name and instance number, the receiver's process name and instance number, a breakpoint counter, and an optional breakpoint command.
    Any of the parameters may be omitted or given the value `-', which means that any value will match that parameter. In this way, output breakpoints can be matched by more than one signal output.
  2. Select or enter the name of the signal. If no signal is specified, any signal will match.
  3. Select or enter the name of the process sending the signal. If no process is specified, any sender process will match. Note that "env" may be entered for the environment process.
  4. Enter the instance number of the sender process. If no instance number is specified, any instance of the process specified above will match.
  5. Select or enter the name of the process receiving the signal. If no process is specified, any receiver process will match. Note that "env" may be entered for the environment process.
  6. Enter the instance number of the receiver process. If no instance number is specified, any instance of the process specified above will match.
  7. Enter a breakpoint counter, i.e. how many times the breakpoint condition must be true before the execution is stopped. If no counter value is specified, the default value 1 is used.
  8. Enter one or more optional breakpoint commands.

Setting a Variable Breakpoint

Variable breakpoints are set on a specific variable and are triggered whenever the value of the variable is changed. Variable breakpoints are checked after a variable assignment, i.e., the execution stops immediately after the symbol or assignment statement where the value was changed.

To set a breakpoint on a variable in the current process:

  1. Choose Variable in the Breakpoint menu, or enter the command Breakpoint-Variable. This command takes two parameters: the variable name and an optional breakpoint command.
  2. Select or enter a variable name in the current process.
  3. Enter one or more optional breakpoint commands.

Listing and Removing Breakpoints

To list all defined breakpoints, choose List in the Breakpoint menu, or enter the command List-Breakpoints. The list contains an entry number and the break condition for each breakpoint, i.e. the values of the parameters specified when the breakpoint was defined. An omitted parameter value, where permitted, is listed as "any."

A symbol breakpoint can be visualized by opening the SDL diagram and selecting the SDL symbol in an SDL Editor. To see where a specific symbol breakpoint has been defined:

  1. Enter the command Show-Breakpoint (this command has no associated button or menu choice). This command takes one parameter, an entry number in the breakpoint list.
  2. Enter an entry number. (To see what entry number is associated with the symbol breakpoint, list the breakpoints as described above.) The SDL symbol, pointed out by the SDT reference specified for the breakpoint, becomes selected in an SDL Editor.

To remove a defined breakpoint using the Simulator UI:

  1. Choose Remove in the Breakpoint menu, or enter the command Remove-All-Breakpoints. This command takes one parameter, an entry number in the breakpoint list.
  2. Enter an entry number. (To see what entry number is associated with the symbol breakpoint, list the breakpoints as described above.) The breakpoint is removed.

To remove all symbol breakpoints set on an SDL symbol:

  1. If necessary, open an SDL Editor on the diagram containing the SDL symbol.
  2. If the Breakpoints menu is not visible in the SDL Editor menu bar, choose Connect sdle in the Breakpoint menu in the Simulator UI, or enter the command Connect-To-Editor. The menu Breakpoints now appear in the SDL Editor.
  3. Select a symbol with a red breakpoint symbol in the SDL Editor.
  4. From the Breakpoints menu in the SDL Editor, choose the Remove Breakpoint command. All symbol breakpoints are removed.

To remove all defined breakpoints:

  • Enter the command Remove-All-Breakpoints (this command has no associated button or menu choice). All defined breakpoints are now removed.


Sending Signals from the Environment

Usually, you have to send signals into the system to make something of interest happen, for instance when the system is completely idle. You can send signals directly to a process instance, or indirectly by specifying a channel.

Sending Signals to a Process

To send a signal from the environment to a certain process:

  1. Click the Send To button in the Send Signal module, or enter the command Output-To. This command takes three parameters: the signal name, any signal parameters, and the process instance of the receiver.
  2. Select or enter the name of the signal to send.
  3. If the signal has parameters, set the values of the parameters in the dialog that is opened. Select a parameter in the list, enter/edit its value using the input line, or the option menu containing possible values (for enumeration type parameters). Click the Default value button to get a "null" value for the parameter.
  4. Select or enter the name of a process instance to send the signal to.
    The Simulator tries to find a path of channels and signal routes to the receiver. If no path was found, an error message is printed. If a path was found, the signal is either successfully sent (and placed in the input port of the receiver), or is discarded (an immediate null transition occurred), i.e. the receiver is in a state that cannot receive or save the specified signal.

Sending Signals via a Channel

To send a signal from the environment via a channel:

  1. Click the Send Via button in the Send Signal module, or enter the command Output-Via. This command takes three parameters: the signal name, any signal parameters, and an optional channel.
  2. Select or enter the name of the signal to send.
  3. If the signal has parameters, set the values of the parameters in the dialog that is opened. Select a parameter in the list, enter/edit its value using the input line, or the option menu containing possible values (for enumeration type parameters). Click the Default value button to get a "null" value for the parameter.
  4. Select or enter the name of a channel to send the signal via. If no channel is specified, any channel from the environment may be used.
    The Simulator tries to find a single process instance that can receive the signal. If no or several possible receivers were found, an error message is printed. If a single receiver was found, the signal is either successfully sent (and placed in the input port of the receiver), or is discarded (an immediate null transition occurred), i.e. the receiver is in a state that cannot receive or save the specified signal.

Causing a Spontaneous Transition

To send a "none" signal to a process, i.e. to try to cause a spontaneous transition in the process:

  1. Click the Send None button in the Send Signal module, or enter the command Output-None. This command takes one parameter: the process name. If the process contains services, it is also necessary to specify one of the services.
  2. Select or enter the name of the process to send a "none" signal to. A message is printed, indicating whether a spontaneous transition occurred.


Logging the Execution

The following types of interaction during simulation can be logged to file:

  • The commands issued by the user.
  • The complete interaction with the user, i.e. commands issued and resulting print-outs. In other words, all texts visible in the Simulator UI's text area or in the terminal window.
  • The signals sent to, from and via a unit in the system.

Note:

The logging of MSC events to file is described in "MSC Trace and Logging" .

Logging Commands

To start logging of all issued monitor commands from now on:

  1. Select Start Command Log from the Log menu, or enter the command Command-Log-On. This command takes one parameter, the name of the log file.
  2. Select or enter a log file name; on UNIX preferably with the suffix .com.

To stop the logging, select Stop Command Log from the Log menu, or enter the command Command-Log-Off.

After logging has been stopped, it can be continued on the same log file, i.e. the existing log file is appended, or on a new log file.

To continue logging of monitor commands:

  • If using the Simulator UI's menu commands, select Start Command Log from the Log menu. Select or enter the same file name as before, or a new file name.
    • If a new file name was specified, the logging is continued on the new file.
    • If the name of an existing log file was specified, a dialog is opened:

Figure 470 : Continued logging on an existing file

Click Append to append the existing log file. Click Create to overwrite the existing log file.
  • If using monitor commands, enter the command
    Command-Log-On, with or without a file name parameter.
    • If you do not specify any file name, the logging is continued on the same lag file as before.
    • If a file name is specified, the logging is continued on this file.

All monitor commands issued by the user so far in the Simulator UI session can also be saved on a command file, without starting continuos logging of commands. To do this, select Save from the popup menu on the input line and select a command file.

A command log file may later be read in and executed to repeat the same command session. To do this:

  1. Choose Script in the Execute menu, or enter the command Include-File. This command takes one parameter: the name of a file containing monitor commands.
  2. Select or enter the name of an existing command file. When the file has been specified, it is read and the commands in the file are executed exactly as they are stated in the file.

Logging the User Interaction

Complete logging of all user interaction works in the same way as logging of monitor commands, described above. The only difference is the name of the menu choices and commands. Either select Start Complete Log and Stop Complete Log from the Log menu, or enter the commands Log-On and Log-Off.

Logging Signal Interaction

The signals that are sent to, from or via a unit in the system can be logged on file. The signal log file will contain a line for each signal sent, including the simulation time, the name of the signal, the sender process instance and the receiver process instance. Values of signal parameters are also printed.

More than one signal log can be active at a time, each one in a separate log file.

To start a signal log:

  1. Enter the command Signal-Log (this command has no associated button). This command takes two parameters: a unit in the system, and the name of a log file.
  2. Select or enter a unit whose signals are to be logged. A unit can be one of the following:
    • A channel or signalroute. Signals sent through the channel or signalroute are logged.
    • A process type or process instance. Signals sent to and from any of the process instances are logged.
    • A block or a system. Signals sent within, to and from the system or block are logged.
    • The process "env." In this way, the signal interface between the system and the environment is logged.
  3. Select or enter a file name of the signal log file.

To list the active signal logs, enter the command List-Signal-Log (this command has no associated button). The list contains an entry number, the unit name and the log file name.

To stop a signal log:

  1. Enter the command Close-Signal-Log (this command has no associated button). This command takes one parameter, an entry number in the signal log list.
  2. Enter an entry number. To see what entry number is associated with the timer instance, list the active signal logs as described above. If only one signal log is active, the entry number is not needed.


Modifying the System

The are a number of commands that change the behavior of the simulated system. These commands are useful to make debugging easier. They can, for example, be used to recover from logical errors, or to put the system in a state that could be difficult to achieve otherwise.

Caution!

When these commands are used, it is no longer the original system that is simulated, as the commands modify the behavior of the system. It is completely up to the user to interpret the simulation and its relation to the original system.

Some of these commands operate on the current process. For more information on the current process, see "Current Process and Scope" .

Sending an Internal Signal

To simulate the sending of an internal signal between two process instances:

  1. Enter the command Output-Internal. This command takes the following parameters: the name of the signal, values of any signal parameters, receiver process instance, and sender process instance.
  2. Select or enter the name of the signal to send.
  3. If the signal has parameters, set the values of the parameters in the dialog that is opened. Select a parameter in the list, enter/edit its value using the input line, or the option menu containing possible values (for enumeration type parameters). Click the Default value button to get a "null" value for the parameter.
  4. Select or enter the receiver process instance. Note that "env" may be entered for the environment process.
  5. Select or enter the sender process instance. Note that "env" may be entered for the environment process.

The signal is put in the input port of the receiver process, if it is in the valid input signal set; otherwise, it is discarded. No checks are made whether a path exists between the sender and the receiver.

Changing the Process State

To change the state of the current process, service, or procedure:

  1. Choose State in the Change menu, or enter the command Nextstate. This command takes one parameter: the name of the new state.
  2. Select or enter the name of the state to go to.

Creating and Stopping Processes

To create a new process instance:

  1. Choose Create Process in the Change menu, or enter the command Create. This command takes the following parameters: the process to create, the parent process instance, and any process parameters.
  2. Select or enter the name of the process to create a new instance for.
  3. Select or enter the parent process instance. "env" may be entered for the environment process, and "null" may also be entered.
  4. If the process has parameters, enter the values of the parameters one by one.
    If the number of instances already is greater than or equal to the maximum number for this process type, you have to verify the create action. The following message appears:
Attempt to create more than the max number of concurrent instances.
Do you still want to create the instance :

  5. Enter `y' or `Y' to create; all other answers cancels the create.

To stop a running process instance:

  1. Choose Stop Process in the Change menu, or enter the command Stop. This command takes one parameter, the process instance to stop.
  2. Select or enter the name of the process instance to stop.

Setting and Resetting Timers

To set a timer in the current process:

  1. Choose Set Timer in the Change menu, or enter the command Set-Timer. This command takes the following parameters: the name of the timer, any timer parameters, and a time value.
  2. Select or enter the name of a timer in the current process.
  3. If the timer has parameters, enter the values of the parameters one by one.
  4. Enter a time value when the timer is to expire, either an absolute value (without sign) or a value relative to Now (with a `+' sign). That is, "7.5" is an absolute time value, whereas "+7.5" is the time value Now+7.5.

To reset a timer in the current process:

  1. Choose Reset Timer in the Change menu, or enter the command Reset-Timer. This command takes the following parameters: the name of the timer, and any timer parameters.
  2. Select or enter the name of a timer in the current process.
  3. If the timer has parameters, enter the values of the parameters one by one.

Changing a Variable

To change the value of a variable in the current process:

  1. Choose Variable in the Change menu, or enter the command Assign-Value. This command takes the following parameters, the name of the variable, an optional specification of a variable component, and the new value.
  2. Select or enter the name of a variable, possibly abbreviated.
    If a variable has several components (e.g. an array, struct or string) and it is specified without a component, the values of all components of the variable have to be specified (e.g. the complete array). To assign a component only, the same rules as for examining a variable apply (see "Examining Variables" ):
    • To assign only a certain component, specify the component after the variable name. (In the Simulator UI, this must be done on the text input line in the dialog, after a variable name has been selected.)
    • To get a list of the possible components of a variable, enter a `?' after the variable name. (In the Simulator UI, this must be done on the text input line in the dialog, after a variable name has been selected; another dialog is then opened, in which the component can be selected.)
      More information on the input and output of SDL data types can be found in "Input and Output of Data Types" .

Changing the Input Port

To remove a signal instance in the input port of the current process:

  1. Enter the command Remove-Signal-Instance. This command takes one parameter, an entry number in the input port.
  2. Enter an entry number. To see what entry number is associated with the signal instance, list the input port as described in "Examining Signal Instances" .

Note:

Entry numbers are just positions in the input port. The removal of a signal changes the entry numbers of the remaining signals.

To change the placing of a signal instance in the input port of the current process:

  1. Choose Input Port in the Change menu, or enter the command Rearrange-Input-Port. This command takes two parameters, the current and new entry number in the input port.
  2. Enter the current entry number of the signal instance. To see what entry number is associated with the signal instance, list the input port as described in "Examining Signal Instances" .
  3. Enter the new entry number of the signal instance. The current signal instance at this position will be moved down in the queue.

Rearranging the Ready Queue

You can change the order of process instances in the ready queue, i.e. the execution order of processes.

To change the placing of a process instance in the ready queue:

  1. Choose Ready Q in the Change menu, or enter the command Rearrange-Ready-Queue. This command takes two parameters, the current and new entry number in the ready queue.
  2. Enter the current entry number of the process instance. To see what entry number is associated with the process instance, list the ready queue as described in "Printing the Process Ready Queue" .
  3. Enter the new entry number of the process instance. The current process instance at this position will be moved down in the queue.


Exiting a Simulator

To exit a simulator, choose Stop Sim in the Execute menu, or enter the command Exit or Quit. If the command is abbreviated, you have to confirm the exit operation; the following message appears:

Do you really want to exit program :

Enter `y' or `Y' to exit; all other answers cancels the exit.

To exit the Simulator UI, select Exit from the File menu. If you have changed the configuration of the Simulator UI, you are asked whether to save these changes. See "Customizing the Simulator UI" . If you save them under the default file names, they are read in and restored the next time the Simulator UI is started.


51 Remote Target Simulation

This chapter describes how to run a simulator on a target and connect it to the SDL simulator interface (SimUI) on the host via TCP/IP communication.


Target Simulation

Overview

A simulator executable (called simulator) communicates with the SDL suite tools, e.g. the SDL Simulator UI (SimUI), via the SDL suite communication mechanism (the PostMaster). By using some special features it is possible to run the simulator on a target system (called target), while the SDL suite tools and Postmaster run on a host system (called host) separate from the target. This set-up is known as target simulation. This gives the possibility to test a simulator in its correct environment and still get the trace and debug possibilities offered by the SDL suite.

For instance, the target could be a VME147 bus system running VxWorks, and the host is a Sun workstation running SunOS 5. The simulator running on the target is built using a special library, instead of the ordinary simulator library containing the simulator kernel. The special library contains the kernel for a simulator on VxWorks, as well as a communication interface to the host. On the host, the simulator is replaced by a gateway executable (called gateway) that communicates with the simulator on the target over the TCP sockets connection. Figure 471 shows the set-up for target simulation.

Figure 471 : Target simulation set-up

Architecture

Simulators, as well as other executables communicating via the Postmaster, has a set of layers as shown in Figure 472, where the layers are represented by the files that implement them. All units (the Simulator, Postmaster and SimUI) are located on the same host machine.

Figure 472 : Architecture of an ordinary simulator

sctpost.c, post.o and a few other files are then linked into the simulator kernel used for making the simulator.

The basic principle of this target simulation is to direct the communication between the simulator and the Postmaster over a TCP sockets connection. This re-direction must be transparent to the simulator and to the Postmaster.

To direct the messages between the Simulator Monitor and the Postmaster through the TCP sockets, a new layer, implemented in the file tlayer.c, is introduced between sctpost.c and post.o according to Figure 473.

Figure 473 : tlayer.c is introduced

For the target, tlayer.c emulates post.o (the same interface), and for the host, tlayer.c emulates sctpost.c (the same interface). (In Windows NT there are other communication mechanisms on host than UNIX sockets.)

The Configuration File and Simulator UI Command Extension

All configuration is made on host side in a file called tarsim.cfg. This file is searched by host_smr.sct/host_smr.exe in a directory specified by the environment variables (searched in this order):
Unix: $TARSIMPATH, $PWD, $HOME, $sdtdir.
Windows NT: the only searched variables are %TARSIMPATH%. You set the environment variable %TARSIMPATH% as described below.

  1. Open the System Control Panel and select the Environment tab.
  2. In the Variable field enter TARSIMPATH, and in the Value field enter the directory (including logical disk drive) where tarsim.cfg is located.
  3. Press Set and close down the System Control Panel.

The syntax of tarsim.cfg is described below. In the delivery, a sample tarsim.cfg is supplied.

  • All lines beginning with `#' (hash) are considered as comments and left unread.
  • All lines after the optional command END are left unread, regardless of contents.
  • All commands must be at the first position in a line.
  • All commands and arguments are case insensitive, except arguments specifying files, etc.
  • Separation between commands and arguments are any whitespace (i.e. space or tab).

Example 322 : A sample tarsim.cfg

# targsim.cfg, config file for simulating an SDT executable simulator
# on remote target with SDT SIMUI on a host.
#
# forces use of invalid IP addresses. gethostbyaddr on some networks
# returns an invalid hostent entry even if the address is usable.
# FORCEIP must come before any used IP address in TARGET or HOST
# default OFF
FORCEIP ON
#
#SERVICE IP-ADDRESS PORT NAME(optional)
TARGET 146.75.124.23 18000 targetcomputer
#HOST 111.22.33.55 17000 SDT-host
# Target must be specified, host not. Port number is default, target
# has 18000 defined in tlayer.h
#
# setting USETIMEOUT to OFF disables timeouts and makes it possible
# to suspend the target or halt it at a C debugger breakpoint
# default ON
USETIMEOUT OFF
#
# communication between host and service, only TCP (default) or TTYA/B (n/a)
# NOTE, only TCP in this version
#COM TARGET TCP
#
# in debug mode signals can be logged on file (default = stderr)
# Note! stderr will not work on Windows NT.
#
#LOG dummylog.tmp
#
# debug on/off must be set to 'on' to activate logging.
#
#debug on #default = OFF
#
# If SDL diagram files are in a different directory than is hardcoded
# into the simulator (which assumes they are in the source directory
# which was specified in SDT when it was generated), you can explicitly
# give the path to the SDL source files here.
# Note! absolute path from root, i.e. starting with /dir1/dir2/... etc.
# trailing directory (a / in the end) is optional.
# If you can not get symbol trace on SDL editor, the SDLpath need to be
# defined to where you have your SDL source files
# Note! this only works on a flat directory structure.
#
#SDLpath /home/kod/sdl/demongame
#
end
#
after an "end" statement host stops reading, so you can write anything!

Tarsim Shell (UNIX only)

On UNIX, there is a very basic shell included in host.sct.

If you start host.sct without the target running, you will enter a shell where only the commands INIT (try contacting target again) and EXIT (quit session) are applicable. If you know your target is running and still do not get contact, please check that the specified IP address and PORT of the target in tarsim.cfg are correct. PORT is for the target hardcoded in tlayer.h, the header file for tlayer.c.

During simulation you can enter the tarsim shell by entering a ":" (colon). You can only leave the simulation if the simulator is not running with GO or FOREVER. If so, first stop the simulation with the Break button.

After entering the ":" you will see a welcome text to the shell. You can enter the command HELP to see the full command set, or STATUS to see the current simulation setup. You exit the shell by entering EXIT.

Note:

Be sure you are still in the tarsim shell when entering EXIT, since it is the same command for exiting the simulation. You can see if you are in the shell by the fact that all text begin with a colon as the first character in the text window. There is a time-out in the shell, after one minute of inactivity you get back to the simulator again.

LOG and DEBUG has the same syntax and meaning as in
tarsim.cfg.

Addresses like TARGET and HOST, as well as the COM and SDLPATH statements, cannot be changed from the shell.

An additional facility for the logging is GREP, which gives a possibility to filter out up to 5 strings that you want to log and skip the rest.

To clear all GREP's and log everything:

GREP *

To add a string (this example looks for MSCE, i.e. signals to the MSC Editor):

GREP MSCE

Strings are not case sensitive by default. To search for the exact string MyPath/demo.sdt, prefix it with `=':

GREP =MyPath/demo.sdt

If you want to log everything except, for instance, signals to the SDL Editor you can use the prefix `!':

GREP !SDLE

Note:

If you have GREP MSC active and then enter GREP !MSC, status will be changed of the previously entered argument, so you cannot enter two contradictions and have both active.

You can also combine the inverse and exact functions:

GREP !=MyPath/demo.sdt

Up to five GREP arguments can be active simultaneously and each can be up to 25 characters long.

If the GREP buffer is full, empty the old with GREP *.

You can empty the buffer and enter new argument in one statement:

GREP * MSCE

Executing and Terminating the Tools

When the simulator and gateway have been started, the simulator can be controlled from the Simulator UI on the host in the same way as an ordinary simulator. Differences may be seen in execution performance and in the printing of log messages. Using Open in the File menu in the SimUI, you specify the simulator file host.sct. After you have chosen this file, host.sct will try to establish contact with the target, according to settings in tarsim.cfg. This file must be in the same directory as host.sct, and the SDL suite should also be started from this directory. (Setting Source Directory in the Organizer does not help SimUI find the target simulation file dependencies.)

The simulator on the target can be stopped by typing <Ctrl+C> on the console. It is though recommended only to stop the target by pressing the Exit button in the SimUI. The host.sct will then, before it finishes, send a stop signal to the target, and give it a chance to close all open file descriptors for TCP sockets. If not, you can get a bind error if you try to restart the target simulator without rebooting the target system.

The gateway on the host is terminated by issuing the command Exit or Quit in the SimUI.

When the simulator and gateway have been started, the simulator can be controlled from the Simulator UI on the host in the same way as an ordinary simulator. Differences may be seen in execution performance and in the printing of log messages. Using Open in the File menu in the SimUI, you specify the simulator file host_smr.sct. After you have chosen this file, host_smr.sct will try to establish contact with target, according to settings in tarsim.cfg. This file must be in the same directory as host_smr.sct, and the SDL suite should also be started from this directory. (Setting Source Directory in the Organizer does not help SimUI find the target simulation file dependencies).

The simulator on the target can be stopped by typing <Ctrl+C> on the console. It is though recommended only to stop the target by pressing the Exit button in the SimUI. The host_smr.sct will then, before it finishes, send a stop signal to the target, and give it a chance to close all open file descriptors for TCP sockets. If not, you can get a bind error if you try to restart the target simulator without rebooting the target system.

The gateway on the host is terminated by issuing the command Exit or Quit in the SimUI.

On Windows NT the host gateway is named host_smr.exe.

Known Problems

  • Some targets must be rebooted after a crash, since the OS does not make fclose on open file descriptors upon kill. You will see the error message "bind (0x30)", meaning that bind fails since the target port address is busy. However, since enhanced shutdown and bind methods has been introduced, the risk of this has been reduced.
  • Sometimes the SimUI interface hangs with a clock cursor after several reboots. Try the following solutions in the specified order until it works:
  • Press the Break button in the SimUI.
  • Select Restart in the File menu and restart the file host.sct
  • If you still get no access to the SimUI, try <Ctrl+O> (shortcut for open file) to reopen the file.
  • Find host.sct in the process list (ps -ef on Solaris) and kill it. Try 2-3 again.
  • Kill sdtsimui in the same way and restart it from the Organizer.
  • If you get no contact with the target the first time, check the
    tarsim.cfg     configuration file. Correct any incorrect IP address or port to the target (port is default 18000 except on VxWorks/VME) and restart host.sct like in step 2 above. The target's port is hardcoded into the file tlayer.h.
  • If you cannot establish connection on an IP address and you still can ping/telnet the same address, try to set the command FORCEIP ON before any TARGET statement in tarsim.cfg. This forces use of an IP address even if it is reported invalid by gethostbyaddr().
  • On a slow network connection you might lose connection with the MSC editor. It can be impossible to start it by pressing the MSC button in the Simulator User Interface, or you can get the message "Error writing MSC event". Other problems that can occur is that it is impossible to BREAK when you are running the simulation with GO or GO-FOREVER.
    The solution to all of these problems is to set the environment variable sdt_rpctimeout to 100. You need to restart the SDL suite after doing this.
  • If simulation starts but crashes after starting the MSC trace you are running out of stack space in the target. There is two solutions. Add the compiler flags MAX_READ_LENGTH=500 and MAX_WRI_LENGTH=500 in the makefile when you build the target. The flags reduces the default buffer size used by the simulation kernel. You may need to adjust the value after size and complexity of your system.
    The second fix is to set the stack size for the SDL task when you start it. Most RTOS:s has stack size as a parameter to taskSpawn, t_create or corresponding. Suitable stack size for remote simulation is 30-50 kB. Default stack in many RTOS kernels is 20kB, which will only work for very small systems.

Source Code Files

Source code for the target contains the complete standard Master Library. The only difference is that post.o does not contain any Postmaster, but a TCP socket communication program.

Both host and target use the same tlayer.c file, with the compile flags -DTARGET and -DHOST, respectively. Also the flag -DTCP need to be specified in both ends to get TCP functionality.

All other files in sctworld.o needs the flags -DTARGETSIM,
-D/compiler/, -D/rtos/, -DSCTDEBCLCOM and
-DXMAIN_NAME=sdlmain.

Also recommended: -DMAX_READ_LENGTH=500
-DMAX_WRI_LENGTH=500

See the specific integrations for the RTOS and compiler specific flags.

There is also special flags for the TCP connection. Supported flags are currently VXWORKS_SDT, PSPS_SDT and WINDOWS. Default is standard Unix/Posix.

The source file structure in tlayer.c is also documented in the top of tlayer.c in a comment.

To make the target you will need tlayer.c and tcp.c, along with the .h files which are supplied. A makefile is also provided.

Building a remote simulation project

In the remsim directory there is a subdirectory called SampleProject Into the INCLUDE directory copy *.c and *.h from the Telelogic Tau installation under sdt/sdtdir/{ARCH}sdtdir/INCLUDE and sdt/sdtdir/remsim/source. The makefiles are referring to this directory. You could of course change the makefiles to refer to the original installation if you do not need any changes.
In the directory REMSIMKERNEL you have the file Makefile.m to build a new kernel and make.opt for compiler settings used by both final build and making the kernel.
comp.opt defines the syntax for the generated makefile.
In make.opt you could by setting sctLD, sctLDFLAGS and sctEXTENSION decide if you want to build the final executable or a library to link into the final target build.

You build the kernel in the REMSIMKERNEL directory. The sample makefiles will work under Sun/Solaris with a GCC compiler. You only need to change for your cross compiler environment. Make the kernel by typing:
make -f makefile.m

The result will be a prelinked kernel called sctworld.o.

When you perform a make, you need to choose the option "Generate Makefile and use template" and select env.tpm in the REMSIMKERNEL directory. This links in the template sctenv.c (which in the delivery does nothing). You also need to select "Use kernel in directory" and select REMSIMKERNEL.
Please note that this only sample code to give you ideas how you can build your own cross compilation environment.

Special Information about Windows NT

Compiling

Both target and host has been tested on Windows NT 4.0 and compiled with Borland C++ v5.02 and Microsoft Visual C++ 5.0 and 6.0.

In the directory sdt/sdtdir/remsim/wini386,makefiles for Borland and Microsoft compilers are stored. Normally you will probably not run the target under Windows NT; this is just for demo purposes. Edit the top of the makefile, variables ccbindir and sdtsource to the absolute paths of your compiler binaries and the SDL suite installation. Make from the prompt like this:
Borland: make -f bcc_target.mak
Microsoft: nmake /f ms_target.mak

The host part is called host_smr.exe and is located into the SimUI the same way as on UNIX.

Both parts must be compiled as 32 bit console applications.

Non-supported Features

Due to the fact that there are no stdout or stderr when you run a Windows GUI application, together with the difficulties to determine the right directory to write to a file in, all debugging and logging facilities has been excluded. That means that the entries DEBUG, GREP and LOG in tarsim.cfg will be ignored. There is no extra Target Simulation Shell as on UNIX (which is not needed when you cannot do any message logging). None of this affects the target simulation as such.

Other Known Limitations

It is considerably slower to do a remote simulation in Windows NT than on UNIX, even with the same system, same options, and running target and host on the same machine. There are ways to speed up the simulation. Recommended is to give set-tr 0 as the first command in SimUI. Then all textual tracing is stopped. Instead you can ask for the value of certain variables of interest. MSC trace and SDL trace works OK; MSC is the quicker of the two.

You can of course do a normal host simulation on the NT machine and then you have no limitations. Target simulation is not recommended to be used more than for the final fine tuning into the target environment.

It is especially important in Windows to use the option SDLPATH in tarsim.cfg if the target has been compiled on another system. The parser in host.exe can read NFS syntax "/path/" and will convert it to Windows/DOS syntax "\path\". The thing that cannot be fixed automatically is the correct logical drive letter. Hence you can specify where your SDL source files are with:

SDLPATH D:\path\sdlsource

in tarsim.cfg. Of course the source files must be the same as the ones the target was compiled from.


52 The SDL Validator

This chapter is a reference to the validator user interface and a reference for the terminology used in validation.

For a guide to how to use the validator, see 53 Validating a System.


The Validator Monitor

A validator generated by the SDL suite is similar to a simulator in that it contains an interactive monitor system. The validator monitor looks and behaves very similar to the simulator monitor; the only real difference is the set of available commands.

Monitor User Interfaces

Two different user interfaces are provided for the validator monitor, a textual and a graphical.

The textual interface only allows commands to be entered from the keyboard, in the same way as for the simulator monitor.

The graphical interface still allows commands to be entered from the keyboard in the same way, but also provides buttons, menus and dialogs for easy access to commands and other features.

The textual interface is invoked by executing the generated validator directly from the operating system prompt. This is called running a validator in textual mode. When started, the validator responds with the following text:

Welcome to the SDL VALIDATOR

Command :

Another prompt may appear if the SDL system contains external synonyms. For more information, see "Supplying Values of External Synonyms" .

Note:

Before a validator can be run in textual mode on UNIX, a command file must be executed from the operating system prompt. The file is called telelogic.sou or telelogic.profile and is located in the binary directory that is included in the user's path.
For csh-compatible shells: source <bin dir>/telelogic.sou
For sh-compatible shells: . <bin dir>/telelogic.profile

The graphical interface, known as the Validator UI, runs in a separate window. It is started from the Organizer by selecting SDL > Validator UI from the Tools menu. The graphical interface is basically the same as for the simulator monitor. However, some special windows and menus have been added; see "Graphical User Interface" for more information.

Activating the Monitor

Commands can be issued to the interactive monitor system when it becomes active. The validator's monitor system becomes active:

  • When the validator is started.
  • When the last command was Next or Random-Down and the transitions initiated by this command have completed.
  • When the last command was Bit-State-Exploration, Verify-MSC or Exhaustive-Exploration and the behavior tree down to the defined search depth has been fully explored.
  • When the last command was Random-Walk and the defined number of repetitions have been executed.
  • Immediately after a report with the report action Abort has been generated during automatic state space exploration.
  • In the Validator UI, when the Break button is clicked in the Explore button module; in textual mode, when <Return> is pressed during an automatic state space exploration.

Note:

No other characters may be typed before <Return> is pressed.


Monitor Commands

This section provides an alphabetical listing of all available commands in the validator monitor. The syntax of commands and data type literals in the validator monitor is the same as for the simulator monitor. Commands may be abbreviated, as well as most command parameters. All input to the monitor is case insensitive. For more information, see "Syntax of Monitor Commands" and "Input and Output of Data Types" .

Alphabetical List of Commands

? (Interactive Context Sensitive Help)

Parameters:

(None)

The monitor will respond to a `?' (question mark) by giving a list of all allowed values at the current position, or by a type name, when it is not suitable to enumerate the values. After the presentation of the list, the input can be continued.

? (Command Execution)

Parameters:

<Command name>

Executes the monitor command given as a parameter. This is a convenience function for the Validator UI. Entering `?' as parameter gives a list of all possible command names.

Assign-Value

Parameters:

[ `(' <PId value> `)' ]
<Variable name> <Optional component selection>
<New value>

The new value is assigned to the specified variable in the process instance, service instance, or procedure given by the current scope. Sender, Offspring, and Parent may also be changed in this way, but their names may not be abbreviated.

After the command is given, the root of the behavior tree is set to the current system state.

It is, in a similar way as for the command Examine-Variable, possible to handle components in structured variables (struct, strings, array, and Ref) by appending the struct component name or a valid array index before the value to be assigned. Nested structs and arrays can be handled by entering a list of index values and struct component names.

If a PId is given within parenthesis, the scope is temporarily changed to this process instance instead.

Bit-State-Exploration

Parameters:

(None)

Starts an automatic state space exploration from the current system state using the bit state space algorithm. When the exploration is started, the following information is printed:

  • Search depth: The maximum search depth of the exploration. This can be set with the command Define-Bit-State-Depth.
  • Hash table size: The size of the hash table used during bit state exploration. This can be set with the command Define-Bit-State-Hash-Table-Size.

The exploration will continue until either the complete state space to the defined depth is explored, <Return> is pressed from the command prompt, or the Break button is pressed in the graphical user interface. The system is then returned to the state it was in before the exploration was started.

If a bit state exploration already has been started, but has been stopped, this command asks if the exploration should continue from where it was stopped, or restart from the beginning again.

A status message is printed for every 20,000 transitions that are executed.

When the exploration is finished or stopped, the Report Viewer is by default opened (this can be changed with the command Define-Report-Viewer-Autopopup). The following statistics are also printed:

  • No of reports: The number of reported situations that may be listed with the List-Reports command.
  • Generated states: The total number of system states generated.
  • Truncated paths: The number of times the exploration reached the maximum depth, causing the current execution path to be truncated.
  • Unique system states: The number of generated system states that are not duplicated anywhere in the behavior tree.
  • Size of hash table: The size of the hash table in bits and bytes.
  • No of bits set in hash table: The number of bits actually used to represent the generated state space.
  • Collision risk: The risk, in percent, of a collision occurring in the hash table for two different system states. This would cause an incorrect truncation of an execution path in a newly generated state.
  • Max depth: The maximum number of levels in the behavior tree that have been reached during the exploration.
  • Current depth: The level of the behavior tree reached at the moment when the exploration was stopped. If it is -1, the exploration was completed, i.e., the complete behavior tree down to the specified depth was explored. If it is > 0, the exploration may be continued from this level by issuing the command again.
  • Min state size: The smallest number of bytes used to store a system state when computing hash values.
  • Max state size: The largest number of bytes used to store a system state when computing hash values.
  • Symbol coverage: The percentage of the symbols in the process graphs that have been executed at least once.

Bottom

Parameters:

(None)

Go down in the behavior tree to the end of the current path.

Cd

Parameters:

<Directory>

Change the current working directory to the specified directory.

Channel-Disable

Parameters:

<Channel> | `-'

Disables all test values defined for all signals using the given channel. `-' means all channels. Use Channel-Enable to start using them again. See also Signal-Disable. Test values for a signal are only used if both the signal and the channel that transports the signal are enabled. By default, all signals and channels are enabled.

Channel-Enable

Parameters:

<Channel> | `-'

Enables all test values defined for all signals using the given channel. `-' means all channels. See also Signal-Enable. Test values for a signal are only used if both the signal and the channel that transports the signal are enabled. By default, all signals and channels are enabled.

Clear-Autolink-Configuration

Parameters:

<Directory>

Clears the current Autolink configuration.

Clear-Constraint

Parameters:

<Constraint name> | `-'

Removes the constraint specified by the parameter. If `-' is given instead of a constraint name, all constraints are cleared.

Note: Only constraints that are not used by any generated test case can be cleared. Constraints used by one or more test cases are cleared automatically if the corresponding test cases are cleared.

Clear-Coverage-Table

Parameters:

(None)

Clears the test coverage information.

Clear-Generated-Test-Case

Parameters:

<Test case name> | `-'

Removes the generated test case specified by the parameter from memory. However, the corresponding MSC test case on disk is preserved. If `-' is given instead of a test case name, all generated test cases are cleared. Alternatively, several test cases may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

Clear-Instance-Conversion

Parameters:

(None)

Clears all defined instance conversions. See also the command Define-Instance-Conversion.

Note that this command will not change an already loaded MSC.

Clear-MSC

Parameters:

(None)

Clears the currently loaded MSC and sets the current state to the current root of the behavior tree.

Clear-MSC-Test-Case

Parameters:

<File name> | `-'

Removes the MSC test case specified by the parameter from disk. If `-' is given instead of a file name, all test cases are cleared. Alternatively, several test cases may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

Clear-MSC-Test-Step

Parameters:

<File name> | `-'

Removes the MSC test case specified by the parameter from disk. If `-' is given instead of a file name, all test steps are cleared. Alternatively, several test steps may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

Clear-Observer

Parameters:

<Process type>

Defines all process instances of the given type to be usual SDL processes, not observer processes.

Clear-Parameter-Test-Values

Parameters:

( <Signal> | `-' ) ( <Parameter number> | `-' )
( <Value> | `-' )

The test value described by the value parameter is cleared for the signal parameter given as the parameter to the command. If the specified value parameter is `-', clears all test values for the signal parameter given as the parameter to the command. If `-' is given instead of the parameter number then the test values for all parameters of the signal are cleared. If `-' is given instead of the signal name then all test values for all parameters to all signals are cleared.

Regenerates the set of signals that can be sent from the environment during state space exploration.

Clear-Reports

Parameters:

(None)

Delete the current reports from the latest state space exploration.

Clear-Rule

Parameters:

(None)

The currently defined rule is deleted.

Clear-Signal-Definitions

Parameters:

<Signal> | `-'

Clears all currently defined test values for the signal given by the parameter. If `-' is given, the test values for all signals are cleared.

Note:

The signals cleared by this command may be regenerated if any of the commands for defining test values for sorts or parameters are used.

Clear-Test-Values

Parameters:

( <Sort> | `-' ) ( <Value> | `-' )

Clears all test values for the sort given as parameter. If the specified sort parameter is `-', all test values for all sorts will be cleared. If the value parameter is `-', all test values for the specified sort will be cleared.

Regenerates the set of signals that can be sent from the environment during state space exploration.

Command-Log-Off

Parameters:

(None)

The command log facility is turned off; see the command Command-Log-On for details.

Command-Log-On

Parameters:

<Optional file name>

The command enables logging of all the commands given in the monitor. The first time the command is entered a file name for the log file has to be given as parameter. After that any further Command-Log-On commands, without a file name, will append more information to the previous log file, while a Command-Log-On command with a file name will close the old log file and start using a new file with the specified name.

Initially the command log facility is turned off. It can be turned off explicitly by using the command Command-Log-Off.

The generated log file is directly possible to use as a file in the command Include-File. It will, however, contain exactly the commands given in the session, even those that were not executed due to command errors. The concluding Command-Log-Off command will also be part of the log file.

Continue-Until-Branch

Parameters:

<Optional node number>

First go to the system state node which is the child with the specified number to the current system state. Same as the Next command. Then go down as long as there is only one child, i.e. a branch is found.

Continue-Up-Until-Branch

Parameters:

(None)

Go up in the behavior tree as long as there is only one child, i.e. a branch is found.

Default-Options

Parameters:

(None)

Resets all options in the Validator to their default values and clears all reports. It also sets the current state to the current root. Compare with the command Reset.

Define-Autolink-Configuration

Parameters:

<Configuration>

Defines an Autolink configuration which might consist of:

  1. Rules for the handling of constraints and signal parameter values (naming, replacement and parameterization).
  2. Rules for the arrangement of test cases (test suite structure).
  3. Rules for declaring ASP and PDU types.
  4. A rule for stripping signal definitions from constraints.
  5. Functions used by the rules 1 and 2 above.

If any rule or function is already defined, Autolink prompts the user to decide whether to add the new rules or to clear the existing Autolink configuration. If Define-Autolink-Configuration is part of a command file, the existing configuration is always replaced.

Rules beginning with TRANSLATE are evaluated when a constraint is created during test case generation. A translation rule specifies the name and the parameters of a constraint for a given SDL signal. In addition, it allows to replace signal parameter values by wildcards in a constraint declaration table (TTCN matching mechanism). Translation rules can also be used to introduce test suite parameters and constants.

Test suite structure rules are evaluated when a test suite is saved. A test suite structure rule specifies a test group reference for test cases and/or test steps.

The two rules for the mapping of SDL sorts and signals onto ASP/PDU types are evaluated when writing the TTCN MP file. The same applies to the STRIP-SIGNALS rule that tells Autolink to create a constraint for a (single) parameter of an SDL signal instead for the signal itself.

An Autolink configuration has to obey the syntax rules described in "Autolink Configuration Syntax" .

For a detailed description of the semantics, see "Syntax and Semantics of the Autolink Configuration" .

Define-Autolink-Depth

Parameters:

<Depth>

Sets the maximum depth of the state space exploration for test case generation to the given value. The default value is 1000.

Define-Autolink-Generation-Mode

Parameters:

"Partial-Ordering" | "Total-Ordering"

Determines the way Autolink analyzes an MSC test case during test generation. If set to "Partial-Ordering", the standard semantics of MSC is used whereas "Total-Ordering" lets Autolink evaluate incoming and outgoing messages in an MSC straight from top to bottom. Typically, "Partial-Ordering" results in a behavior tree with several leaves whereas "Total-Ordering" produces only one sequence of events. The default setting is "Partial-Ordering". Note: The total ordering interpretation is not supported by the Generate-Test-Case command.

Define-Autolink-Hash-Table-Size

Parameters:

<Size>

Sets the size of the hash table used for test case generation to <Size> bytes. The default value is 1,000,000 bytes.

Define-Autolink-State-Space-Options

Parameters:

"On" | "Off"

Determines whether Autolink sets its own default state space options before generating test cases. If "On', the state space options are automatically set when Generate-Test-Case is invoked and reset to the previous options when the command is completed. The default value is "On".

Note that in general, the Validator's default options are too strict to find all inconclusive events. Also be aware that for Autolink to work correctly, the priority of "Input from ENV" has to be higher than the priority of all other event classes, and the queues for all channels to the environment have to be activated.

Define-Bit-State-Depth

Parameters:

<Depth>

The parameter is the maximum depth of bit state exploration, i.e., the number of levels to be reached in the behavior tree. If this level is reached during the exploration, the current path is8 truncated and the exploration continues in another node of the behavior tree. The default value is 100.

Define-Bit-State-Hash-Table-Size

Parameters:

<Size in bytes>

Sets the size of the hash table used to represent the generated state space during bit state exploration. The default value is 1,000,000 bytes.

Define-Bit-State-Iteration-Step

Parameters:

<Step>

The Bit-State-Exploration algorithm includes a feature to automatically make a number of explorations with an increased depth for each exploration. The iteration continues until the search depth is greater than the maximum depth search as defined by Define-Bit-State-Depth command or one exploration terminates without any truncations.

This command activates the feature and defines how much the depth is increased for each iteration. If <Step> is set to 0 the iterative exploration is deactivated, otherwise <Step> defines how much the maximum depth is increased for each exploration.

The default value is 0, i.e. the feature is not activated.

Define-Channel-Queue

Parameters:

<Channel name> ( "On" | "Off" )

Adds or removes a queue for the specified channel. If a queue is added for a channel, it implies that when a signal is sent that is transported on this channel, it will be put into the queue associated with the channel. By default no channels have queues.

Define-Concurrent-TTCN

Parameters:

"On" | "Off"

Defines whether TTCN test suites should be saved in concurrent TTCN format.

The default value is "off".

Note:

Concurrent TTCN is not supported in combination with the "Local" or "Inline" TTCN test steps format. If an error message appears when trying to enable concurrent TTCN, first set the test steps format to "Global" with Define-TTCN-Test-Steps-Format.

Define-Condition-Check

Parameters:

"On" | "Off"

Defines whether conditions in an MSC should be used for synchronization purposes during MSC verification and test case generation. If condition check is turned on, then events below a global condition can only occur if all events on all instances above that condition have been processed; the condition becomes a synchronization point. If the condition is not global, then only the connected instances are synchronized. If condition check is turned off, then conditions in MSCs are ignored.

The default value is "off".

Note:

If condition check is turned on, then the semantics of conditions is different from the semantics given in the ITU-T Recommendation Z.120!

Define-Constraint

Parameters:

<Constraint name> <Signal definition>

Defines a new constraint, which is automatically written to the test suite if the user enters the Save-Test-Suite command later.

Define-Exhaustive-Depth

Parameters:

<Depth>

The parameter defines the depth of the search when performing exhaustive exploration. The default value is 100.

Define-Global-Timer

Parameters:

"On" | "Off"

Defines whether a global timer should be added to TTCN test suites. If this option is enabled, the following things are done automatically:

  • A declaration for a timer "T_Global" is generated with default duration "PIX_T_Global" and a unit "s" (seconds);
  • A test suite parameter "PIX_T_Global" with type "INTEGER" is declared;
  • A statement "START T_Global" is inserted at the beginning of each Test Case Dynamic Behaviour table; if concurrent TTCN output is enabled, a "START T_Global" is also inserted at the beginning of each top-level Test Step Dynamic Behaviour table for all parallel test components;
  • A statement "CANCEL T_Global" is appended to every test sequence in each Test Case Dynamic Behaviour table; if concurrent TTCN output is enabled, a "CANCEL T_Global" is also added to the end of every test sequence in each top-level Test Step Dynamic Behaviour table of all parallel test components.

The default value is "on".

Note:

It is recommended that the decision on using global timers is made before test case generation is started and that it is not changed later. Changing the option after the first test case has been generated may lead to unexpected results.
The name of the global timer cannot be changed. However, the default duration and unit may be defined with the Define-Timer-Declaration command. This should be done before the first test case is generated.

Define-Instance-Conversion

Parameters:

<From string> <To string>

Adds an entry into an instance conversion table. If a string contains spaces, it must be quoted.

When reading instances in an MSC diagram and the name textually match a <From string> in the conversion table, it will be replaced by the <To string>. This is useful if you want to verify some, but not all, instances in an MSC, in which case you can convert the unwanted instances to be considered as environment.

Note that this command will not change an already loaded MSC.

Define-Integer-Output-Mode

Parameters:

"dec" | "hex" | "oct"

Defines whether integer values are printed in decimal, hexadecimal or octal format. In hexadecimal format the output is preceded with "0x", in octal format the output is preceded with `0' (a zero).

On input: if the format is set to hexadecimal or octal, the string determines the base as follows: After an optional leading sign a leading zero indicates octal conversion, and a leading "0x" hexadecimal conversion. Otherwise, decimal conversion is used.

The default is "dec", and no input conversion is performed.

Define-Max-Input-Port-Length

Parameters:

<Number>

The maximum length of the input port queues is defined. If this length is exceeded during state space exploration, a report is generated (see "Max Queue Length Exceeded" ). The default value is 3.

Define-Max-Instance

Parameters:

<Number>

Defines the maximum number of instances allowed for any particular process type. If this number is exceeded during state space exploration, a report is generated (see "Create Errors" ). The default value is 100.

Define-Max-Signal-Definitions

Parameters:

<No of signals>

This command defines the maximum no of signals that will be added to the list of signals from the environment for any particular signal. The default value is 10.

Define-Max-State-Size

Parameters:

<Size in bytes>

Sets the size of an internal array used to store each system state when computing the hash value for the system state. The default size is 100,000 bytes.

Define-Max-Test-Values

Parameters:

<No of text values>

This command defines the maximum no of test values that will be generated for a particular data type or signal parameter. The default value is 10.

Define-Max-Transition-Length

Parameters:

<Number>

The maximum number of SDL symbols allowed to be executed during the performance of a behavior tree transition is defined. If this number is exceeded during state space exploration, a report is generated (see "Transition Length Error" ). The default value is 1,000.

Define-MSC-Ignore-Parameters

Parameters:

"On" | "Off"

Defines whether the parameters of signals (and timers) will be ignored (i.e. set to default values) when reading MSC diagrams. The default is "Off".

Note that this command will not change an already loaded MSC.

Define-MSC-Search-Mode

Parameters:

"Verification" | "Violation"

Defines options for MSC verification depending on the purpose of the exploration. "Verification" mode should be used if the intention with the exploration is to verify all MSC alternatives. "Violation" mode should be used if the intention is to check if the SDL system can violate the MSC.

The difference between "Verification" and "Violation" mode is that in "Verification" mode the validator will:

  • synchronize on all MSC starts and start of inline expressions, and
  • perform a separate MSC action to enter an MSC / inline expression.

The synchronization in "Verification" mode implies that the validator will try to execute all events in one MSC before continuing with the events in a subsequent MSC. The special MSC action is executed when all events in one MSC has been executed and it is time to start with the subsequent MSC. Note that if there are more than one subsequent MSC (e.g. due to an HMSC alternative or an inline expression) each MSC action will select one of the MSCs. In the trace output (and in the Navigator) the MSC actions will be presented as "Enter MSC XXX" where XXX is the name of the MSC that the validator will try to execute next.

A simple way to get hands-on experience with the difference between "Verification" and "Violation" mode is to load an MSC that includes alternatives (either an HMSC or an MSC with inline expressions) using the Load-MSC command. Then set up the MSC search mode and use the Navigator to manually explore the state space.

Note that in "Verification" mode the par operator is not supported.

The default search mode is "Violation" mode.

Define-MSC-Test-Cases-Directory

Parameters:

<Directory name> | `-'

Defines the directory in which the MSC test cases are stored. If `-' is provided instead of a directory name, the test cases directory becomes undefined.

Define-MSC-Test-Steps-Directory

Parameters:

<Directory name> | `-'

Defines the directory in which the MSC test steps are stored. If `-' is provided instead of a directory name, the test steps directory becomes undefined.

Define-MSC-Trace-Action

Parameters:

"On" | "Off"

This command defines whether actions like tasks, decisions, etc. are shown in the MSC trace. The default value is "Off".

Define-MSC-Trace-Autopopup

Parameters:

"On" | "Off"

This command defines whether an MSC Editor automatically will pop up and show an MSC trace when going to a report. The default value is "On".

Define-MSC-Trace-State

Parameters:

"On" | "Off"

This command defines if the SDL process graph states are shown in the MSC trace. If "On", a condition symbol will be shown in the MSC trace each time a process performs a nextstate. The default value is "On".

Define-MSC-Trace-Channels

Parameters:

"On" | "Off"

Defines whether the env instance should be split into one instance for each channel connected to env in the MSC trace. The default is "Off".

Define-MSC-Verification-Algorithm

Parameters:

"TreeSearch" | "BitState"

Defines the search algorithm that is used for MSC verification. Two options are available, the tree search algorithm and the bit state algorithm. The default is "BitState".

Note that this command only defines what search algorithms that is used by the Verify-MSC command. It is possible to use other search algorithms, like Exhaustive-Exploration, by manually loading the MSC with the Load-MSC command and then starting the desired search algorithm.

Define-MSC-Verification-Depth

Parameters:

<Depth>

The parameter defines the depth of the search when performing MSC verification using the Verify-MSC command. The default value is 1,000.

Define-Observer

Parameters:

<Process type>

Defines all process instances of the given type to be observer processes.

Define-Parameter-Test-Value

Parameters:

<Signal> <Parameter number> <Value>

The parameter test value described by the command parameters is added to the current set of test values. The list of signals that can be sent from the environment is regenerated based on the new set of test values.

Define-Priorities

Parameters:

<Internal events> <Input from ENV> <Timeout events> <Channel output> <Spontaneous transitions>

Defines the priorities for the different event classes. The priorities can be set individually to 1, 2, 3, 4 or 5. For more information about event classes and priorities, see "Event Priorities" .

The default priorities are:

  • Internal events: 1
  • Input from ENV: 2
  • Timeout events: 2
  • Channel outputs: 1
  • Spontaneous transitions: 2

Note that the priorities of events processed in the validator also is affected by the command "Define-Symbol-Time" .

Define-Random-Walk-Depth

Parameters:

<Depth>

The parameter defines the depth of the search when performing random walk exploration. The default value is 100.

Define-Random-Walk-Repetitions

Parameters:

<No of repetitions>

The parameter defines the number of times the search is performed from the start state when performing random walk exploration. The default is 100.

Define-Report-Abort

Parameters:

<Report type> | `-'

Defines that the state space exploration will be aborted whenever a report of the specified type is generated.

The available report types are listed with the command Show-Options. They are also described in "Rules Checked During Exploration" . If the parameter is specified as `-', all report types will be defined in the same way.

Define-Report-Continue

Parameters:

<Report type> | `-'

Defines that a state space exploration will continue past a state where a report of the specified type is generated. With this definition, the exploration of the behavior tree is not affected by a report being generated.

The available report types are listed with the command Show-Options. They are also described in "Rules Checked During Exploration" . If the parameter is specified as `-', all report types will be defined in the same way.

Define-Report-Log

Parameters:

<Report type> ( "Off" | "One" | "All" )

Defines how many reports of a specified type will be stored in the list of found reports when they are encountered during state space exploration. Default for all report types is "One".

If "Off" is specified for a report type, reports of this type will not be stored, which implies for example that they will not be listed by the List-Reports command. However, the reports will be generated and the appropriate action taken as specified by the commands Define-Report-Abort, Define-Report-Continue and Define-Report-Prune.

If "One" is specified only one occurrence of each reported situation is stored.

If "All" is specified then all occurrences of a reported situation that have different execution paths is stored in the list.

The available report types are listed with the command Show-Options. They are also described in "Rules Checked During Exploration" . If the parameter is specified as `-', all report types will be defined in the same way.

Define-Report-Prune

Parameters:

<Report type> | `-'

Defines that a state space exploration will not continue past a state where a report of the specified type is generated. Thus, the part of the behavior tree beneath the state will not be explored. Instead, the exploration will continue in the siblings or parents of the state. This is also known as "pruning" the behavior tree at the state. This is the default behavior for all report types.

The available report types are listed with the command Show-Options. They are also described in "Rules Checked During Exploration" . If the parameter is specified as `-', all report types will be defined in the same way.

Define-Report-Viewer-Autopopup

Parameters:

"On" | "Off"

This command defines whether the Report Viewer automatically will pop up when an automatic exploration is finished. The default is "On".

Define-Root

Parameters:

"Original" | "Current"

Defines the root of the behavior tree to be either the current system state or the original start state of the SDL system.

Note:

When the root is redefined, all paths, e.g. MSC traces or report paths, will start in the new root, not in the original start state.

Define-Rule

Parameters:

<User-defined rule>

A new rule is defined that will be checked during state space exploration.

Define-Scheduling

Parameters:

"All" | "First"

Defines which process instances in the ready queue are allowed to execute at each state. The parameter defines the scheduling as follows:

  • All
    All process instances in the ready queue are allowed to execute at each state.
  • First
    Only the first process instance in the ready queue is allowed to execute at each state.

The default is "First".

Define-Signal

Parameters:

<Signal> <Optional parameter values>

A signal that is to be sent to the SDL system from the environment is defined. The signal is defined by its name and optionally the values of its parameters. Multiple Define-Signal commands may be used to define the same signal, but with different values for the parameters.

Note:

The signals defined by this command will be destroyed if the signals are regenerated, i.e., if any of the commands defining test values for sorts or signal parameters are used.

Define-Spontaneous-Transition-Progress

Parameters:

"On" | "Off"

Defines whether a spontaneous transition (input none) is considered as progress when performing non-progress loop check. Default is that spontaneous transition is considered to be progress, i.e. "On". See "Non Progress Loop Error" .

Define-Symbol-Time

Parameters:

"Zero" | "Undefined"

The time it takes to execute one symbol, e.g. an input, task or decision, in an SDL process is defined either to be zero or undefined. If it is set to zero, it is assumed that all actions performed by process instances take are infinitely fast compared to the timer values that are used in the system. If the symbol time is set to undefined, no assumption is made about how long time it takes for processes to execute symbols. Consider for example a situation where a process sets a timer with a duration 5 and then executes something that may take a long time, e.g. a long loop, and the sets a timer with duration 1. If symbol time is set to zero then the second timer will always expire first. If symbol timer is set to undefined then both timers can potentially expire first.

Note that when symbol time is set to zero, no timer will expire if an internal action is possible, even if internal and timer events have the same priority as set by the command Define-Priorities.

The default value of the symbol time options is "Zero".

Define-Test-Value

Parameters:

<Sort> <Value>

The test value described by the parameters is added to the current set of test values. The list of signals that can be sent from the environment is regenerated based on the new set of test values.

Note:

When regenerating the set of signals, all signals that have been manually defined using the Define-Signal command will be lost.

Define-Timer-Check-Level

Parameters:

<Number>

The action taken during MSC verification when checking timer statements (set, reset and timeout) is defined. The possible values for the specified number are:

  • 0: No checking of timer events is performed.
  • 1: If a timer event exists in the MSC a matching timer event must exist in the explored SDL path, but a timer event in the explored SDL path is accepted even if there is no corresponding MSC timer event.
  • 2: All timer events in the MSC must match a corresponding timer event in the explored SDL path, and vice versa.

The default value is 1.

Define-Timer-Declaration

Parameters:

<Timer name> <Duration> <Unit>

Creates or updates a TTCN timer declaration. Autolink distinguishes between implicit timer declarations, which are created from test description MSCs during test case generation, and explicit timer declarations, which are created with this command. Valid explicit declarations always override implicit ones. Existing explicit declarations cannot be updated.

The duration may be an integer value or a valid test suite parameter identifier. If a test suite parameter is specified, a declaration for this parameter is generated as well. If no valid duration is specified, the duration field in the declaration remains empty.

The unit must be a valid TTCN unit: "ps", "ns", "us", "ms", "s" or "min". No declaration is made if an invalid unit is specified.

Note:

It is recommended that all timers appearing in MSC test cases and test steps are declared explicitly prior to test case generation.

Define-Timer-Progress

Parameters:

"On" | "Off"

Defines if the expiration of a timer is considered as progress when performing non-progress loop check. Default is that timer expiration is considered to be progress, i.e. "On". See "Non Progress Loop Error" .

Define-Transition

Parameters:

"SDL" | "Symbol-Sequence"

Defines the semantics and length of the transitions in the behavior tree. The parameter defines the transitions as follows:

  • SDL
    The behavior tree transitions correspond to complete SDL process graph transitions.
  • Symbol-Sequence
    The behavior tree transitions correspond to the longest sequence of SDL symbols that can be executed without any interaction with other process instances.

The default is "SDL".

Define-Tree-Search-Depth

Parameters:

<Depth>

Defines the maximum search depth for tree search.

The default value is 100.

Define-TTCN-Compatibility

Parameters:

"Standard" | "ITEX"

Determines whether Autolink generates the declarations part of a TTCN test suite. If set to "Standard", Autolink creates declarations with ASN.1 data field names being constructed of the form "data type+parameter number" (e.g. "Integer2"). If set to "ITEX", no declarations are created. In this case, ASN.1 data field names used in constraint definitions are represented by `#' characters. This allows to merge the test suite with declarations generated by Link in the TTCN suite. The default value is "Standard".

This command exists for backward compatibility reasons only.

Define-TTCN-Signal-Mapping

Parameters:

"ASP" | "PDU"

Determines whether SDL signals are mapped onto ASN.1 ASP constraints or ASN.1 PDU constraints. By default, signals are mapped onto ASPs. The setting of Define-TTCN-Signal-Mapping can be overruled for single signals by the use of the 'ASP-Types' and 'PDU-Types' commands in the Autolink configuration language (cf. Define-Autolink-Configuration).

Define-TTCN-Test-Steps-Format

Parameters:

"Global" | "Local" | "Inline"

Defines how test steps are written in a TTCN test suite. "Global" is the default value.

If set to "Global", each test step is saved in a separate behaviour description table. If a test step is used in more than one test case, then only one behaviour description table is generated.

If set to "Local", each test step is saved as a local tree in the behaviour table of the corresponding test case. If a test step is used several times in a single test case, then only one behaviour description is generated.

If set to "Inline", all test step trees are directly inserted into the test case descriptions.

Note that a test step which is used in several places may lead to trees with different inconclusive events or different verdicts. In this case, the test steps are stored in separate tables with unique names.

Note:

Test step formats "Local" and "Inline" are not supported in combination with concurrent TTCN. If an error message appears when trying to change the test steps format, first disable concurrent TTCN with Define-Concurrent-TTCN.

Define-Variable-Mode

Parameters:

<Process or Process Type> [ <Variable name> | "Parent" | "Offspring" | "Sender" ]
[ "Compare" | "Skip" ]

This command defines how a specific variable is treated when comparing two system states during state space exploration. If the value for a variable is "Compare", this variable will be taken into account when comparing two system states. If the value is "Skip", this variable will not be taken into account, i.e. if the only difference between two system states is that values of variables in "Skip" mode differs, then the system states will be considered equal.

The purpose of the "Skip" mode for variables is to optimize the state space search. There are two different situations where this command can be used:

  • All variables that is known to be constant during an exploration can be declared "Skip".
  • All variables that will not have an effect on the dynamic behavior of the system, i.e. that will not affect the path through a decision or the expression in an "output to", can be declared "Skip".

The benefit with constant variables in "Skip" mode is that the Validator will ignore these variables when computing hash values. This can for large data structures like arrays mean that the performance of the validator can be considerably improved.

Down

Parameters:

<Number of levels>

Go down the specified number of levels in the behavior tree, each time selecting the child of the current system state that is part of the current path. If the parameter is too large, Down will stop at the end of the current path.

Evaluate-Rule

Parameters:

(None)

The currently defined rule is evaluated with respect to the current system state. The command prints whether or not the rule is satisfied.

Examine-Channel-Signal

Parameters:

<Channel name> <Entry number>

The parameters of the signal instance at the position equal to the entry number in the queue of the specified channel are printed. The entry number is the number associated with the signal instance when the command List-Channel-Queue is used.

Examine-PId

Parameters:

(None)

Information about the process instance given by the current scope is printed (see the Set-Scope command for an explanation of scope). This information contains the current values of Parent, Offspring, Sender and a list of all currently active procedure calls made by the process instance. The list starts with the latest procedure call and ends with the process instance itself.

If the process instance contains service(s), information about all services is also printed.

Examine-Signal-Instance

Parameters:

<Entry number>

The parameters of the signal instance at the specified position in the input port of the process instance given by the current scope are printed (see the Set-Scope command for an explanation of scope). The entry number is the number associated with the signal instance when the command List-Input-Port is used.

Examine-Timer-Instance

Parameters:

<Entry number>

The parameters of the specified timer instance are printed. The entry number is the number associated with the timer when the List-Timer command is used.

Examine-Variable

Parameters:

[ `(' <PId value> `)' ]
<Optional variable name>
<Optional component selection>

The value of the specified variable or formal parameter in the current scope is printed (see the Set-Scope command for an explanation of scope). Variable names may be abbreviated. If no variable name is given, all variable and formal parameter values of the process instance given by the current scope are printed. Sender, Offspring, and Parent may also be examined in this way. Their names, however, may not be abbreviated and they are not included in the list of all variables.

Note:

If a variable is exported, both its current value and its exported value are printed.

It is possible to examine only a component of a struct, string or array variable, by appending the struct component name or a valid array index value as an additional parameter. The component selection can handle structs and arrays within structs and arrays to any depth by giving a list component selection parameters. SDL syntax with `!' and "( )" as well as just spaces, can be used to separate the names and the index values.

It is also possible to print a range of an array by giving "FromIndex : ToIndex" after an array name. Note that the space before the `:' is required if FromIndex is a name (enumeration literal), and that no further component selection is possible after a range specification.

To see the possible components that are available in the variable, the variable name must be appended by a space and a `?' on input. A list of components or a type name is then given, after which the input can be continued. After a component name, it is possible to append a `?' again to list possible sub components.

To print the value of the data referenced by a Ref pointer it is possible to use the SDL syntax, i.e. the "*>" notation. If, for example, Iref is a Ref(Integer) variable, then Iref*> is the integer referenced by this pointer. If Sref is a Ref of a struct, then Sref*> ! Comp1 is the Comp1 component in the referenced struct. The sequence *> ! can in the monitor be replaced by -> (as for example in C).

If a PId is given within parenthesis, the scope is temporarily changed to
this process instance instead.

Exhaustive-Exploration

Parameters:

(None)

Starts an automatic state space exploration from the current system state, where the entire generated state space is stored in primary memory. This is only recommended for SDL systems with small state spaces.

The exploration will continue until either the complete state space to the defined depth is explored, <Return> is pressed from the command prompt, or the Break button is pressed in the graphical user interface. The system is then returned to its initial system state. The maximum depth of the exploration can be set with the command Define-Exhaustive-Depth.

If an exhaustive exploration already has been started, but has been stopped, this command asks if the exploration should continue from where it was stopped, or restart from the beginning again.

A status message is printed every 50,000 states that are generated. When the exploration is finished or stopped, the same information as for a bit state exploration is printed.

Exit

Parameters:

(None)

The executing validator is terminated. If the command is abbreviated, the monitor asks for confirmation. If any of the Validator options have been changed, the monitor will ask if the changed options should be saved. If so, the changed options are saved in a file .valinit (on UNIX), or valinit.com (in Windows), in the directory from where the SDL suite was started. This file is automatically loaded the next time a Validator is started from the same directory, thus restoring the previously saved options.

This is the same command as Quit.

Extract-Signal-Definitions-From-MSC

Parameters:

<Directory name> ( <File name> | `-' )

Extracts all signals from an MSC which are to be sent from the environment into the SDL system and adds them to the list of active signals. This command is only applicable to basic MSCs in textual format, i.e. to those MSCs stored with file extension .mpr. If `-' is given instead of a file name, signal definitions from all MSCs in the specified directory are extracted. Alternatively, several MSCs may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

Generate-Test-Case

Parameters:

<File name> | `-'

Starts the state space search algorithm which constructs an internal data structure for the MSC test case specified by the parameter. Additionally, constraints for all signals occurring in the test case are generated. At the end all constraints with identical signal definitions are merged.

If the command parameter is specified as `-', test cases are generated for all MSC test cases in the current test cases directory. Alternatively, several MSC test cases may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

If the previous generation of a test case has been interrupted, Autolink prompts the user to decide whether to continue the interrupted generation or to abort it. No file name is needed if the test case generation is to be continued.

Note that this command requires a TTCN Link license in addition to the Validator license.

Goto-Path

Parameters:

<Path>

Go to the system state specified by the path. For details about paths, see the command Print-Path.

Goto-Report

Parameters:

<Report number>

Go to the state in the behavior tree where the report with the corresponding number has been found. The last behavior tree transition that was executed before the reported situation is printed, with the same information as for a full trace during simulation. The report number is the number associated with the report when the command List-Reports is used. If only one report exists, the report number is optional.

Help

Parameters:

<Optional command name>

Issuing the Help command without a parameter will print all the available commands. If a command name is given as parameter, this command will be explained.

Include-File

Parameters:

<File name>

This command provides the possibility to execute a sequence of monitor commands stored in a text file. The Include-File facility can be useful for including, for example, an initialization sequence or a complete test case. It is allowed to use Include-File in an included sequence of commands; up to five nested levels of include files can be handled.

List-Channel-Queue

Parameters:

<Channel name>

A list of all signal instances in the specified channel queue is printed. For each signal instance an entry number, the signal type, and the sending process instance is given. The entry number can be used in the command Examine-Channel-Signal.

List-Constraints

Parameters:

(None)

Lists all currently defined constraints.

List-Generated-Test-Cases

Parameters:

(None)

Lists all test cases which have been generated either by Generate-Test-Case or Translate-MSC-Into-Test-Case, or which have been loaded with the Load-Generated-Test-Cases command.

List-Input-Port

Parameters:

[ `(' <PId value> `)' ]

A list of all signal instances in the input port of the process instance given by the current scope is printed (see the Set-Scope command for an explanation of scope). For each signal instance an entry number, the signal type, and the sending process instance is given. A `*' before the entry number indicates that the corresponding signal instance is the signal instance that will be consumed in the next transition performed by the process instance. The entry number can be used in the command Examine-Signal-Instance.

If a PId is given within parenthesis information about this process instance is printed instead.

List-Instance-Conversion

Parameters:

(None)

Lists all defined instance conversions. See also the command Define-Instance-Conversion.

List-MSC-Test-Cases-And-Test-Steps

Parameters:

(None)

Lists all MSC test cases and test steps currently stored in the test cases and test steps directories.

List-Next

Parameters:

(None)

A list of the possible behavior tree transitions that can follow from the current system state is printed.

Note:

The number of possible transitions depends on the selected state space options.

List-Observers

Parameters:

(None)

List all process types which are defined to be observer processes.

List-Parameter-Test-Values

Parameters:

(None)

Lists all currently defined test values for signal parameters.

List-Process

Parameters:

<Optional process name>

A list of all process instances with the specified process name is printed. If no process name is specified all process instances in the system are listed. The list will contain the same details as described for the List-Ready-Queue command.

If the process contains services, information about the currently active service is also printed. To get information about all services use the Examine-PId command.

List-Ready-Queue

Parameters:

(None)

A list of process instances in the ready queue is printed. For more information, see the Simulator command "List-Ready-Queue" .

List-Reports

Parameters:

(None)

All situations that have been reported during state space exploration are printed. For each report, the error or warning message describing the situation is printed, together with the depth in the behavior tree where it first occurred. Only one occurrence of each reported situation is printed; the one with the shortest path from the root of the behavior tree. The report numbers printed can be used in the command Goto-Report.

List-Signal-Definitions

Parameters:

(None)

A list of all currently defined signals is printed.

List-Test-Values

Parameters:

(None)

Lists all test values that currently are defined.

List-Timer

Parameters:

(None)

A list of all currently active timers is printed. For each timer, its corresponding process instance and associated time is given. An entry number will also be part of the list, which can be used in the command Examine-Timer-Instance.

Load-Constraints

Parameters:

<File name>

Loads all constraints stored in the file specified by the parameter. The suggested file extension is .con.

Load-Generated-Test-Cases

Parameters:

<File name>

Loads all generated test cases stored in the file specified by the parameter. The suggested file extension is .gen.

Load-MSC

Parameters:

<MSC file name>

The specified Message Sequence Chart is loaded into the Validator. Loading an MSC always resets the state space and sets the current state to the root of the behavior tree.

Load-Signal-Definitions

Parameters:

<File name>

A command file with Define-Signal commands is loaded and the signals are defined. This command exists for backward compatibility reasons only.

Log-Off

Parameters:

(None)

The command Log-Off turns off the interaction log facility, which is described in the command Log-On.

Log-On

Parameters:

<Optional file name>

The command Log-On takes an optional file name as a parameter and enables logging of all the interaction between the Validator and the user that is visible on the screen. The first time the command is entered, a file name for the log file has to be given as parameter. After that any further Log-On commands, without a file name, will append more information to the previous log file, while a Log-On with a file name will close the old log file and start using a new file with the specified file name.

Initially the interaction log facility is turned off. It can be turned off explicitly by using the command Log-Off.

Merge-Constraints

Parameters:

<First name> <Second name>

Merges the two constraints specified by the parameters. The resulting constraint has at least the formal parameters of the original constraints. If additional constraint parameters are necessary (e.g. when merging two constraints with signals S(1,1) and S(1,2)), Autolink prompts the user to enter a name for each new formal parameter. Merge-Constraints can only be applied to constraints with the same signal. The new constraint gets the name of the second constraint.

Merge-Report-File

Parameters:

<File name>

An existing report file is opened and the reports in it are added to the current reports.

MSC-Log-File

Parameters:

<File name>

A log file is produced containing information about the Message Sequence Chart for the trace from the root of the behavior tree to the current system state. This file can be opened in an MSC Editor; we recommend using a filename with the suffix .mpr, since that suffix is used as default.

MSC-Trace

Parameters:

(None)

An MSC Editor is opened, showing the Message Sequence Chart for the current execution path. The current state is shown in the MSC by the selection of some of the symbols. Whenever the current state and/or current path changes in the Validator, the MSC will be updated.

If the MSC trace is already on, this command will turn it off.

New-Report-File

Parameters:

<File name>

A new report file for report storage is created. The current reports are deleted.

Next

Parameters:

<Transition number>

Go to a system state in the next level of the behavior tree, i.e. a child to the current system state. The parameter is the transition number given by the List-Next command.

Open-Report-File

Parameters:

<File name>

An existing report file is opened and the reports in it are loaded. The current reports are deleted.

Parameterize-Constraint

Parameters:

<Constraint name> <Replacement definition>

Replaces concrete values in a constraint with formal parameters. The replacement is defined by a sequence of pairs of a signal parameter number followed by the corresponding formal parameter name. The definition must be terminated with a 0.

Print-Autolink-Configuration

Parameters:

(None)

Displays the current Autolink configuration on the screen.

Print-Evaluated-Rule

Parameters:

(None)

The currently defined rule is printed with the values obtained from the last evaluation of the rule. The printed information is in the form of a so-called parse tree, and may require some knowledge of such structures to be interpreted correctly.

Print-File

Parameters:

<File name>

The content of the named text file is displayed on the screen.

Print-Generated-Test-Case

Parameters:

<Test case name> | `-'

Displays the internal representation of the generated test case specified by the parameter on the screen. If `-' is given instead of a test case name, all generated test cases are shown. Alternatively, several test cases may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

Print-MSC

Parameters:

(None)

A textual version of the currently loaded MSC is printed. The format is similar to the textual MSC format defined in ITU recommendation Z.120.

Print-Path

Parameters:

(None)

The path to the current system state is printed. A path is a sequence of integer numbers, terminated with a 0, describing how to get to the current system state. The first number indicates what transition to select from the root, the second number what transition to choose from this state, etc. To go to the state specified by a path, use the command Goto-Path.

Print-Report-File-Name

Parameters:

(None)

The name of the current report file is printed.

Print-Rule

Parameters:

(None)

The currently defined rule is printed.

Print-Trace

Parameters:

<Number of levels>

The textual trace leading to the current system state is printed. The same information as for a full trace during simulation is printed for each behavior tree transition. The parameter determines how many levels up the trace should start. For example, Print-Trace 10 will print the ten last transitions.

Quit

Parameters:

(None)

The executing validator is terminated. If the command is abbreviated, the monitor asks for confirmation. If any of the Validator options have been changed, the monitor will ask if the changed options should be saved. If so, the changed options are saved in the file .valinit (on UNIX), or valinit.com (in Windows), in the directory from where the SDL suite was started. This file is automatically loaded the next time a Validator is started from the same directory, thus restoring the previously saved options.

This is the same command as Exit.

Random-Down

Parameters:

<Number of levels>

Go down the specified number of levels in the behavior tree, each time selecting a random child of the current system state.

Random-Walk

Parameters:

(None)

This command will perform an automatic exploration of the state space from the current system state. Random walk is based on the idea that if more than one transition is possible in a particular system state, one of them will be chosen at random. When the exploration is started, the following information is printed:

  • Search depth: The maximum depth to walk down. This can be set with the command Define-Random-Walk-Depth.
  • Repetitions: The number of random walks to perform from the start state. This can be set with the command Define-Random-Walk-Repetitions.

The exploration will continue until either it is finished, <Return> is pressed from the command prompt, or the Break button is pressed in the graphical user interface. The system is then returned to the state it was in before the exploration was started.

When the exploration is finished or stopped, the Report Viewer is by default opened (this can be changed with the command Define-Report-Viewer-Autopopup). A few statistics are also printed; see the command Bit-State-Exploration for an explanation of these.

Rename-Constraint

Parameters:

<Old name> <New name>

Renames a constraint. If a constraint with the same "new" name but a different signal definition already exists, the user is prompted to choose between one of the following operations (which can be abbreviated):

  • Rename: A different name can be chosen for the constraint.
  • Keep_old: The definition of the renamed constraint is cleared. Any references from previously generated test cases to the renamed constraint are redirected to the old constraint.
  • Overwrite_old: The definition of the old constraint is cleared. Any references from previously generated test cases to the old constraint are redirected to the renamed constraint.

Restriction: If one of the constraints contains formal parameters, then a different name must always be chosen for the renamed constraint. Rename-Constraint in combination with its options Keep_old and Overwrite_old allows to merge two constraints, e.g. if some signal parameters are irrelevant (see also the command Merge-Constraints and consider the use of CONSTRAINT MATCH ... statements in an Autolink configuration).

Reset

Parameters:

(None)

Resets the state of the Validator to its initial state. This command resets all options and test values in the Validator to their initial values and clears all reports, MSCs, and user-defined rules. It also sets the current state and the current root to the original start system state.

This command reads the .valinit (on UNIX), or valinit.com (in Windows), file (see the command Exit). It is equivalent to closing the Validator and starting it again. Compare with the command Default-Options.

Save-As-Report-File

Parameters:

<File name>

The current reports are saved in a new file. The name of the current report file is set to the new file.

Save-Autolink-Configuration

Parameters:

<File name>

Saves the current Autolink configuration in a command file. The command name Define-Autolink-Configuration and the terminating End are written at the beginning and the end of the file in order to allow to reload the configuration with Include-File. The suggested file extension is .com.

Save-Constraint

Parameters:

( <Constraint name> | `-' ) <File name>

Saves the constraint in a file identified by <File name>.If `-' is given instead of a constraint name, all currently defined constraints are saved. The suggested file extension is .con.

Save-Coverage-Table

Parameters:

<File name>

Test coverage information is saved in the specified file. The test coverage table consists of two parts, a Profiling Information section, and a Coverage Table Details section. This is the same type of file as generated by the Simulator; for more detailed information about the file, see "Print-Coverage-Table" .

Save-Error-Reports-As-MSCs

Parameters:

(None)

Saves all reports (except those indicating an MSC verification) as MSCs in the target directory. The reports are stored as complete MSCs with file extension .mpr.

For each MSC a generic name consisting of the name of the currently loaded MSC (or "ErrorReport", if none is loaded), a four letter abbreviation of the error type and a sequence number is generated.

Save-Error-Reports-As-MSCs helps to find out what went wrong when running a batch job with a large number of MSC verifications.

Note: This command does not generate MSCs for MSC violation reports if the current MSC could be verified.

Save-Generated-Test-Case

Parameters:

( <Test case name> | `-' ) <File name>

Saves the generated test case in a file. If `-' is given instead of a test case name, all generated test cases which are currently stored in memory are saved. Alternatively, several test cases may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.The suggested file extension is .gen.

This command allows to compute test cases in parallel on different machines and to merge them afterwards by using Load-Generated-Test-Cases.

Save-MSC-Test-Case

Parameters:

( <Test case name> | `*' )

Saves a test case as a system level Message Sequence Chart in the test cases directory (with file extension .mpr). The MSC contains a separate instance axis for each channel to the environment and another axis for the system. It comprises all signals sent to and from the environment for the trace from the root of the behavior tree to the current system state. If `*' is given instead of a test case name, a generic test case name is generated.

Save-MSC-Test-Step

Parameters:

( <Test step name> | `*' )

Saves a test step as a system level Message Sequence Chart in the test steps directory (with file extension .mpr). The MSC contains a separate instance axis for each channel to the environment and another axis for the system. It comprises all signals sent to and from the environment for the trace from the root of the behavior tree to the current system state. If `*' is given instead of a test step name, a generic test step name is generated.

Save-Options

Parameters:

<File name>

Creates a Validator command file with the name given as parameter. The file contains commands defining the options of the Validator. If this file is loaded (using the command Include-File) the options will be restored to their saved values.

Save-Reports-as-MSC-Test-Cases

Parameters:

( <Report type> | `-' ) <Name prefix>

Saves all reports of a specified type as MSC test cases in the test cases directory (in system level MSC format; with file extension .mpr). The MSCs contain a separate instance axis for each channel to the environment and another axis for the system. For each MSC test case, a generic name is generated consisting of the name prefix, a four letter abbreviation of the report type and a five digit number. If `-' is provided instead of a report type, all current reports are saved.

Save-State-Space

Parameters:

<File name>

A Labelled Transition System (LTS) representing the generated state space is saved to a file. For a description of the file syntax, see section "State Space Files" .

Note:

It is necessary to have executed an Exhaustive-Exploration command before the state space can be saved on a file.

Save-Test-Suite

Parameters:

<Test suite name> <File name>

Saves the generated test cases and all constraints in a test suite file in TTCN MP format. In addition, it generates the declarations part of the TTCN test suite. If the generation of a test case has been interrupted, Autolink prompts the user to decide whether to cancel the command or to abort the test case generation. The suggested file extension for the second parameter is .mp.

Note that this command requires a TTCN Link license in addition to the Validator license.

Save-Test-Values

Parameters:

<File name>

A command file is generated containing Validator commands that, if loaded with the Include-File command, will recreate the current test value definitions.

Scope

Parameters:

(None)

This command prints the current scope. See the command Set-Scope for a description of scope.

Scope-Down

Parameters:

<Optional service name>

Moves the scope one step down in the procedure call stack. If the current scope is a process containing services, one of the services should be specified. See also the commands Stack, Set-Scope and Scope-Up.

Scope-Up

Parameters:

(None)

Moves the scope one step up in the procedure call stack. Up from a service leads to the process containing the service. See also the commands Set-Scope, Stack and Scope-Down.

SDL-Trace

Parameters:

(None)

This command opens an SDL Editor that will show the transition leading to the current system state. Whenever the current system state changes in the Validator, the SDL Editor will be updated.

If the SDL trace already is on, the command will turn it off.

Set-Application-All

Parameters:

(None)

The state space options of the Validator are set to perform state space exploration according to the semantics of an application generated by the SDL Code Generator. No assumptions are made about the performance of the SDL system compared to timeout values or the performance of the environment.

This command sets the exploration mode factors by executing the following commands:

Define-Transition SDL
Define-Scheduling First
Define-Priorities 1 1 1 1 1

Set-Application-Internal

Parameters:

(None)

The state space options of the Validator are set to perform state space exploration according to the semantics of an application generated by the SDL Code Generator. The assumption is made that the time it takes for the SDL system to perform internal actions is very small compared to timeout values and the response time of the environment.

This command sets the exploration mode factors by executing the following commands:

Define-Transition SDL
Define-Scheduling First
Define-Priorities 1 2 2 1 2

Set-Scope

Parameters:

<PId value> <Optional service name>

This command sets the scope to the specified process, at the bottom procedure call. If the process contains services, one of the services can be given as parameter to the command. A scope is a reference to a process instance, a reference to a service instance if the process contains services, and possibly a reference to a procedure instance called from this process/service. The scope is used for a number of other commands for examining the local properties of a process instance. The scope is automatically set to the process that executed in the transition leading to the current system state.

See also the commands Scope, Stack, Scope-Down and Scope-Up.

Set-Specification-All

Parameters:

(None)

The state space options of the Validator are set to perform state space exploration according to the ITU semantics for SDL. No assumptions are made about the performance of the SDL system compared to timeout values, or the performance of the environment.

This command sets the exploration mode factors by executing the following commands:

Define-Transition Symbol-Sequence
Define-Scheduling All
Define-Priorities 1 1 1 1 1

Set-Specification-Internal

Parameters:

(None)

The state space options of the Validator are set to perform state space exploration according to the ITU semantics for SDL. The assumption is made that the time it takes for the SDL system to perform internal actions is very small compared to timeout values and the response time of the environment.

This command sets the exploration mode factors by executing the following commands:

Define-Transition Symbol-Sequence
Define-Scheduling All
Define-Priorities 1 2 2 1 2

Show-Coverage-Viewer

Parameters:

(None)

This command starts the Coverage Viewer. The current test coverage is automatically loaded and a symbol coverage tree is presented. See 48 The SDL Coverage Viewer for further description of the Coverage Viewer.

Show-Mode

Parameters:

(None)

This command displays a summary of the current execution mode and some other information about the current state of the SDL Validator.

Show-Navigator

Parameters:

(None)

This command starts the Navigator tool to simplify interactive navigation in the behavior tree of the SDL system. See "The Navigator Tool" for more details.

Show-Options

Parameters:

(None)

The values of all options defined for the Validator are printed, including the report action defined for each report type.

Show-Report-Viewer

Parameters:

(None)

This command starts the Report Viewer that presents a hierarchical view of all reports generated during state space explorations. See "The Report Viewer" for more details.

Show-Versions

Parameters:

(None)

The versions of the SDL to C Compiler and the runtime kernel that generated the currently executing program are presented.

Signal-Disable

Parameters:

<Signal> | `-'

Disables all test values defined for the given signal. `-' means all signals. Use Signal-Enable to start using them again. See also Channel-Disable. Test values for a signal are only used if both the signal and the channel that transports the signal are enabled. By default, all signals and channels are enabled.

Signal-Enable

Parameters:

<Signal> | `-'

Enables all test values defined for the given signal. `-' means all signals. See also Channel-Enable. Test values for a signal are only used if both the signal and the channel that transports the signal are enabled. By default, all signals and channels are enabled.

Signal-Reset

Parameters:

<Signal> | `-'

Removes all existing test values for the given signal, and defines a default set of test values instead, using the current test value settings for data types and signal parameters. `-' means all signals.

Stack

Parameters:

(None)

The procedure call stack for the PId/service defined by the scope is printed. For each entry in the stack, the type of instance (procedure/process/service), the instance name and the current state is printed. See also the commands Set-Scope, Scope-Down and Scope-Up.

Top

Parameters:

(None)

Go up in the behavior tree to the start of the current path (the root system state).

Translate-MSC-Into-Test-Case

Parameters:

( <File name> | `-' )

Translates an MSC into an internal test case data structure without performing a state space search. Additionally, constraints for all signals occurring in the test case are generated. At the end, all constraints with identical signal definitions are merged.

If the command parameter is specified as `-', all MSCs in the current test cases directory are transformed into test cases. Alternatively, several MSC test cases may be selected by a pattern enclosed in apostrophes. Such a pattern may include the special characters '*', '?', and '[...]' and is evaluated just as in a UNIX command shell.

Translate-MSC-Into-Test-Case does not require a fully specified SDL system. However, the signals used in the MSC must be defined in the SDL specification. Additionally, the channels between the SDL system and its environment have to be specified in order to find out which MSC instances relate to PCOs and which relate to the SDL system. Therefore, a direct translation cannot be applied to MSCs which consist of only a single instance axis for the environment.

Since the translation is done statically, it is not checked whether the MSC can in fact be verified. In addition, no inconclusive events are computed, unless they are stated explicitly by the use of an MSC exception expression.

Note that this command requires a TTCN Link license in addition to the Validator license.

Tree-Search

Parameters:

(None)

Performs a tree search of the state space from the current system state. A tree search is an exploration where all possible combinations of actions are executed. The tree that is explored is exactly the same tree that can manually be inspected using the Navigator feature (or manual exploration using the Next / List-Next commands).

The depth of the tree search is bounded and is defined by the Define-Tree-Search-Depth command. The default depth is 100.

The command can be aborted by the user by pressing the Break button in the Validator UI or any key if running the validator from the command prompt.

Tree-Walk

Parameters:

<Timeout> <Coverage>

Performs an automatic exploration of the state space starting from the current system state. In contrast to Random-Walk, Tree-Walk is based on a deterministic algorithm that performs a sequence of tree searches with increasing depth starting at various states in the reachability graph. Tree Walk combines the advantages of both the depth-first and breadth-first search strategy - it is able to visit states located deep in the reachability graph and to find a short path to a particular state at the same time. Tree Walk is guided by a symbol coverage heuristic. Therefore it is particularly suitable for automatic test case generation.

Computation stops if either time exceeds <Timeout> (specified in minutes) or the targeted coverage (specified in percent) is reached. Alternatively, the exploration can be stopped at any time by pressing Return at the command prompt or by pressing the Break button if the graphical user interface is used.

Tree Walk creates a number of "TreeWalk" reports. These reports can be used for the generation of MSC test cases by applying command Save-Reports-as-MSC-Test-Cases.

Up

Parameters:

<Number of levels>

Go up the specified number of levels in the behavior tree. Up 1 goes to the parent state of the current system state. Up will stop at the root of the behavior tree (the start state) if the parameter is too large.

Verify-MSC

Parameters:

<MSC file>

This command will perform an automatic exploration from the current system state to search for all execution traces that are consistent with the MSC that is given as a parameter. The search algorithm is a variant of the bit state algorithm that is adapted to suite MSC verification. Before the exploration is started, the root of the behavior tree is set to the current system state.

The file can either be an basic MSC file (.msc), a textual MSC file (.mpr) or a high-level MSC file (.mrm).

When the exploration is finished, the same information as for a bit state exploration is printed. In addition, a message is printed stating whether or not the MSC was verified, i.e. if an execution path was found that satisfied the MSC, and reports for MSC verification and MSC violation are generated.

If the MSC is a high-level MSC or it contains MSC reference expressions more that one MSC verification report can be generated. There will be one report for each sequence of `leaf' MSCs that can be verified. For more information on criteria for MSC verification, see "MSC Verification Errors" .

If the MSC was verified and exactly one MSC verification report was generated, the system state of the Validator will be set up to the last system state in the path that satisfied the MSC. Otherwise, the system is returned to its initial state.

If the MSC contains MSC references the Validator needs to match the logical MSC names in the MSC references with MSC file names. This is done according to the following algorithm:

  1. If the Autolink test step directory is set, then the MSC file is assumed to be located in this directory and have the same name as the MSC with the suffix .msc, .mpr or .mrm.
  2. The Validator then checks if there is an MSC with the correct name in the same module in the Organizer as the parent MSC. If this is the case this MSC file is used.
  3. If none of above applies then the Validator checks if there is an MSC file in the same directory as the parent MSC with the correct name and with the suffix .msc, .mpr or .mrm. If this is the case this MSC file is used.


Graphical User Interface

This section describes the appearance and functionality of the graphical user interface to the validator monitor (ValUI). Some user interface descriptions general to all tools in Telelogic Tau can be found in 1 User Interface and Basic Operations. These general descriptions are not repeated in this chapter.

Note:

The ValUI looks and behaves very much like the SimUI, the graphical user interface to the simulator monitor. The differences are the set of available monitor commands and button modules, and a few additional menus and sub windows.

For an explanation of the Validator main window, depicted in Figure 474, see "Graphical User Interface" .

Figure 474 : The main window

Starting the ValUI

A new ValUI is started by selecting SDL > Validator UI from the Tools menu in the Organizer. When the ValUI is started, a number of definition files are read, controlling the contents of the main window and some status windows. See "Definition Files" for more information.

No validator is started automatically by the ValUI in this way. The user must start a validator by selecting Open from the File menu, as stated in the text area of the main window, or by using the Open quick button.

A simple way to generate a validator, start the ValUI and open the validator is to click the Validate quick button in the Organizer.

When a simulator is started, a file selection dialog may be opened if the SDL system contains external synonyms. For more information, see "Supplying Values of External Synonyms" .

The Default Button Modules

The following tables list the default buttons in the button modules and the corresponding monitor command. See "Monitor Commands" for more information.

Note:

The buttons in the button modules are specified in the button definition file. If the default button file is not used, the button modules may be different than described here. See "Button and Menu Definitions" for more information.

The EXPLORE Module

Button | Monitor command
Bit-State | Bit-State-Exploration
Exhaustive | Exhaustive-Exploration
Top | Top
Bottom | Bottom
Random Walk | Random-Walk
Tree Search | Tree-Search
Up | Up 1
Down | Down 1
Tree Walk | Tree-Walk
Verify MSC | Verify-MSC
Navigator | Show-Navigator
Break | Pressing <Return>

The VIEW Module

Button | Monitor command
Scope | Scope
Set Scope | Set-Scope
Scope Up | Scope-Up
Scope Down | Scope-Down
Call Stack | Stack
Ready Q | List-Ready-Queue
Process List | List-Process
Process | Examine-PId
Input Port | List-Input-Port
Signal | Examine-Signal-Instance
Timer List | List-Timer
Timer | Examine-Timer-Instance
Variable | Examine-Variable

The TEST VALUES Module

Button | Monitor command
List Value | List-Test-Values
List Par | List-Parameter-Test-Values
List Signal | List-Signal-Definitions
Clear Signal | Clear-Signal-Definitions
Def Value | Define-Test-Value
Def Par | Define-Parameter-Test-Value
Def Signal | Define-Signal
Extract Sigs | Extract-Signal-Definitions-From-MSC
Clear Value | Clear-Test-Values
Clear Par | Clear-Parameter-Test-Values

The Menu Bar

This section describes the additional menus of the ValUI's menu bar in comparison with the SimUI. The menus common to both the ValUI and the SimUI is described in "The Menu Bar" .

The menu bar contains the following menus:

  • File Menu
    (See "File Menu" .)
  • View Menu
    (See "View Menu" .)
  • Buttons Menu
    (See "Buttons Menu" .)
  • Log Menu
    (See "Log Menu" .)
  • Help Menu
    (See "Help Menu" .)
  • Commands Menu
  • Options1 Menu
  • Options2 Menu
  • Autolink1 Menu
  • Autolink2 Menu

Additional Validator Menus

In addition to the standard SimUI menus, a few special validator menus are included in the menu bar. The menu choices in these menus simply execute a monitor command, i.e. they are functionally equivalent to buttons in the button modules. If the monitor command requires parameters, they are prompted for using dialogs in the same way as the command buttons.

The following tables list the default menu choices and the corresponding monitor command. See "Monitor Commands" for more information.

Note:

The additional menus in the ValUI are specified in the button definition file. If the default button file is not used, the additional menus may be different than described here. See "Button and Menu Definitions" for more information.

Commands Menu

Menu choice | Monitor command
Toggle MSC Trace | MSC-Trace
Toggle SDL Trace | SDL-Trace
Show Report Viewer | Show-Report-Viewer
Show Coverage Viewer | Show-Coverage-Viewer
Show Navigator | Show-Navigator
Define Rule | Clear-Rule ; Define-Rule
Include Command Script | Include-File

Options1 Menu

Menu choice | Monitor command
Show Options | Show-Options
Reset | Reset
Default | Default-Options
Advanced | Define-Scheduling All ; Define-Priorities 1 1 1 1 1 ; Define-Max-Input-Port-Length 2 ; Define-Report-Log MaxQueuelength Off
State Space : Transition | Define-Transition
- : Scheduling | Define-Scheduling
- : Priorities | Define-Priorities
- : Input Port Length | Define-Max-Input-Port-Length
- : Transition Length | Define-Max-Transition-Length
- : Max Instance | Define-Max-Instance
- : Timer Progress | Define-Timer-Progress
- : Channel Queues | Define-Channel-Queue
- : Max State Size | Define-Max-State-Size
- : Symbol Time | Define-Symbol-Time
Report : Continue | Define-Report-Continue
- : Prune | Define-Report-Prune
- : Abort | Define-Report-Abort
- : Report Log | Define-Report-Log
MSC Trace Auto Popup | Define-MSC-Trace-Autopopup
Report Viewer Auto Popup | Define-Report-Viewer-Autopopup

Options2 Menu

Menu choice | Monitor command
Show Options | Show-Options
Bit-State : Hash Size | Define-Bit-State-Hash-Table-Size
- : Depth | Define-Bit-State-Depth
- : Iteration Step | Define-Bit-State-Iteration-Step
Random Walk : Repetitions | Define-Random-Walk-Repetitions
- : Depth | Define-Random-Walk-Depth
Exhaustive : Depth | Define-Exhaustive-Depth
Tree Search : Depth | Define-Tree-Search-Depth
MSC Ver : Timer Check Level | Define-Timer-Check-Level
- : Condition Check | Define-Condition-Check
- : Depth | Define-MSC-Verification-Depth
Autolink : Concurrent TTCN | Define-Concurrent-TTCN
- : Depth | Define-Autolink-Depth
- : Generation Mode | Define-Autolink-Generation-Mode
- : Global Timer | Define-Global-Timer
- : Hash Table Size | Define-Autolink-Hash-Table-Size
- : Options | Define-Autolink-State-Space-Options
- : Signal Mapping | Define-TTCN-Signal-Mapping
- : Test Cases Directory | Define-MSC-Test-Cases-Directory
- : Test Steps Directory | Define-MSC-Test-Steps-Directory
- : Test Steps Format | Define-TTCN-Test-Steps-Format

Autolink1 Menu

Menu choice | Monitor command
MSC : Save Test Case | Save-MSC-Test-Case
- : Save Reports | Save-Reports-as-MSC-Test-Cases
- : Save Error Reports | Save-Error-Reports-As-MSCs
- : Save Test Step | Save-MSC-Test-Step
- : List | List-MSC-Test-Cases-And-Test-Steps
- : Clear Test Case | Clear-MSC-Test-Case
- : Clear Test Step | Clear-MSC-Test-Step
Test case : Generate | Generate-Test-Case
- : Translate | Translate-MSC-Into-Test-Case
- : List | List-Generated-Test-Cases
- : Print | Print-Generated-Test-Case
- : Clear | Clear-Generated-Test-Case
- : Save | Save-Generated-Test-Case
- : Load | Load-Generated-Test-Cases
Test suite : Save | Save-Test-Suite

Autolink2 Menu

Menu choice | Monitor command
Configuration : Define | Define-Autolink-Configuration
- : Print | Print-Autolink-Configuration
- : Clear | Clear-Autolink-Configuration
- : Save | Save-Autolink-Configuration
- : Load | Include-File
Constraint : Define | Define-Constraint
- : List | List-Constraints
- : Rename | Rename-Constraint
- : Merge | Merge-Constraints
- : Parameterize | Parameterize-Constraint
- : Clear | Clear-Constraint
- : Save | Save-Constraint
- : Load | Load-Constraints
Timer : Define | Define-Timer-Declaration

The Command and Watch Windows

The Command window of the ValUI is identical to the SimUI (see "Command Window" ). The only difference is that the default commands to execute are "List-Process -" and "Print-Trace 1". The set of commands to execute are stored in a command definition file (see "Definition Files" ). The default command definition file can be changed with the Preference Manager.

The Watch window of the ValUI is identical to the SimUI (see "Watch Window" ).

The Navigator Tool

The Navigator is a separate tool in the ValUI that is used for navigating in the behavior tree. It can be opened in the following ways:

  • By issuing the monitor command Show-Navigator
  • By selecting Show Navigator from the Commands menu.
  • By clicking the Navigator button in the button area.

Figure 475 : The Navigator window

The Navigator window consists of the tree area and the tool bar. There is no menu bar or status bar in the Navigator window.

Tree Area

The tree area of the Navigator window shows the structure of the behavior tree around the current system state. Each box, or node, represents a tree transition from one system state to another.

  • The up node, always labelled Up 1, shows the tree transition leading to the current system state.
  • The down nodes, labelled Next 1, Next 2, etc., show the possible tree transitions from the current system state. One of the down nodes may be labelled with three asterisks "***" to show which node is part of the current path, i.e., which part of the tree that already has been explored.

The text in the boxes contains the textual trace describing the tree transition. This may represent a complete or partial SDL process graph transition, depending on how the behavior tree is set up. The number of down nodes also depends on the structure of the behavior tree. This is determined by the state space options; see "State Space Options" .

Double-clicking a node in the Navigator executes the corresponding tree transition and moves one level up or down in the behavior tree. The current system state is changed and the Navigator window is updated to show the situation around the new system state.

Note:

Double-clicking a collapsed node (see below) does not expand the node; it always executes the corresponding transition.

The Navigator window is also updated whenever a monitor command is executed that changes the current system state.

Popup Menus

Each node in the node area has an associated popup menu.

Up 1 | On the up node: Go up one level in the tree. This is the same as double-clicking the up node.
Up to top | On the up node: Go to the top of the behavior tree.
Continue Up | On the up nodes: Go up in the tree until more than one transition is possible (see Continue-Up-Until-Branch command).
Goto | On the down nodes: Go down this branch of the tree. This is the same as double-clicking the down node.
Continue | On the down nodes: Go down this branch of the tree until more than one transition is possible (see Continue-Until-Branch command).
Expand | Expand the collapsed node to show the down nodes. (Not applicable on a down node.)
Expand Substructure | The same as Expand.
Collapse | Collapse the node to hide the down nodes. A small triangle below the node shows that it is collapsed. (Not applicable on a down node.)

Quick Buttons

The following quick buttons are special to the Navigator tool. The general quick buttons are described in "General Quick-Buttons" .

Close
Closes the Navigator tool.

Structure
Switches between a tree structure and a list structure in the node area.

Show Validator UI
Raises the Validator UI window.

The Report Viewer

The Report Viewer is a separate tool in the ValUI that is used for examining the reports generated during an automatic state space exploration. It is opened in one of the following ways:

  • Automatically when an automatic state space exploration has finished, unless the option Report Viewer Autopopup is off
  • By issuing the monitor command Show-Report-Viewer
  • By selecting Show Report Viewer from the Commands menu.

Figure 476 : The Report Viewer

The Report Viewer window consists of the Report Area, containing Popup Menus, and the tool bar, containing Quick Buttons. There is no menu bar or status bar in the Report Viewer window.

Report Area

The report area of the Report Viewer shows the current reports from the latest state space exploration in the form of a report tree. The report tree contains three levels of nodes (see Figure 476):

  • The top node shows how many reports there are. This node is always visible.
  • The next level contains one node for each report type. The text shows the report type and how many reports of that type there are. When the Report Viewer is started, the report type nodes are shown, but they are collapsed (indicated by a small triangle below the node). For a list of possible report types, see "Rules Checked During Exploration" .
  • The bottom level contains one node for each actual report. The text shows the error or warning message, and the depth in the behavior tree where the report was generated. If the same report has been generated more than once, only one report is shown; the one generated at the lowest depth in the tree. When the Report Viewer is started, the report nodes are not visible.

Double-clicking a report node at the bottom level causes the Validator to "go to" the report, i.e., go to the system state where the report was generated. The following things happen:

  • The textual trace from the transition where the report was generated is printed in the text area of the main window.
  • If the Navigator tool is opened, it is updated to show the transition where the report was generated and the error message.
  • An MSC Editor is opened, showing the MSC trace from the start state to the state where the report was generated. The MSC Editor is not opened if the option MSC Trace Autopopup is off.

Double-clicking the top node or a report type node will expand or collapse the node, depending on its state. A collapsed node hides its underlying nodes and is indicated by a small triangle below the node.

Popup Menus

Goto | Only on report nodes: Go to the report. This is the same as double-clicking the report node.
Expand | Expand the collapsed node to show the nodes in the next level of the tree. This is the same as double-clicking the collapsed node (top node or report type node). (Not applicable on a report node.)
Expand Substructure | Expand the collapsed node to show all nodes on all levels below it. (Not applicable on a report node.)
Collapse | Collapse the node to hide all nodes on all levels below it. This is the same as double-clicking the node (top node or report type node). (Not applicable on a report node.)

Quick Buttons

The following quick buttons are special to the Report Viewer. The general quick buttons are described in "General Quick-Buttons" .

Close
Closes the Report Viewer.

Structure
Switches between a tree structure and a list structure in the report area.

Show Validator UI
Raises the Validator UI window.

Definition Files

In the ValUI, the syntax and contents of the definition files are the same as for the SimUI; see "Definition Files" . The default file names for the definition files are val_def.btns, val_def.cmds and val_def.vars, respectively.


Rules Checked During Exploration

For each system state encountered during state space exploration, a number of rules are checked to detect errors or possible problems in the SDL system. If a rule is satisfied, a report is generated to the user.

The rules that are checked by the SDL Validator are the same ones as checked and reported by the SDL Simulator, with a few additions and differences.

Apart from the predefined rules, an additional rule can be defined by the user of the validator to check for other properties of the system states encountered. See "User-Defined Rules" for more information.

The rules are listed below, together with the reported error messages. The rules are grouped according to the corresponding report type, used in the Report Viewer in the Validator. The names of the report types listed below are the ones to be used in the monitor commands that define the report actions.

Deadlock

 Report Type:  Deadlock

Deadlock

All processes instances are waiting for some other process instance to act, implying that none of the processes will execute. This is referred to as a deadlock.

Implicit Signal Consumption

 Report Type:  ImplSigCons

Warning: Implicit signal consumption of signal <signal>

A signal was sent to a process that was not able to handle (or save) the signal in the current state, so it was implicitly consumed.

Create Errors

 Report Type:  Create

Error in SDL Create: Processtype <type>
More static instances than maximum number of instances.

There are more static instances defined than the maximum allowed number of instances.

Warning in SDL Create: Processtype <type>
Unsuccessful create. Number of instances has reached maximum number.

An attempt has been made to create a new instance of a process type of which there is already the maximum number of allowed instances active. The maximum number is either the value defined by the command Define-Max-Instance, or the value defined in the SDL diagram, whichever is smallest.

Output and Remote Procedure Call Errors

 Report Type:  Output

Error in SDL Output of signal <signal>
No valid receiver found

An attempt was made to output a signal to an invalid PId expression.

Error in SDL Output of signal <signal>
No path to receiver

An attempt was made to output a signal to a PId expression. There exists, however, no path of channels and signal routes between the sender and the receiver that can convey the signal.

Error in SDL Output of signal <signal>
No possible receiver found

An attempt was made to output a signal without specifying a PId expression. When all paths or all paths mentioned in a via clause had been examined no possible receiver was found.

Error in SDL Output of signal <signal>
Several possible receivers found

An attempt was made to output a signal without specifying a PId expression. When all paths or all paths mentioned in a via clause had been examined several possible receivers were found.

Error in SDL Output of signal <signal>
Signal sent to stopped process instance

An attempt was made to output a signal to a PId expression that referred to a process instance which has performed a stop action.

Error in SDL Output of signal <signal>
Signal sent to NULL

An attempt was made to output a signal to a PId expression that was null.

Error in SDL Output of signal <signal>
Illegal signal type in output TRANSFER

An attempt was made to output a signal with the TRANSFER directive that was not the same signal as in the preceding input.

Error in remote procedure call: <name>
More than one process provides the remote procedure

An attempt was made to call a remote procedure in a system state where there are more than one possible process instance that can provide the remote procedure.

Error in remote procedure call: <name>
No process provides the remote procedure

An attempt was made to call a remote procedure in a system state where
there is no possible process instance that can provide the remote procedure.

Max Queue Length Exceeded

 Report Type:  MaxQueuelength

Error in SDL Output of signal <signal>
Max input port length exceeded

The length of the input port of the receiving process has exceeded the value defined by the monitor command Define-Max-Input-Port-Length.

Error in SDL Output of signal <signal>
Max channel queue length exceeded

The length of the queue of the receiving channel has exceeded the value defined by the monitor command Define-Max-Input-Port-Length.

Error in channel output. Max input port length exceeded

The length of the input port of the receiving process has exceeded the value defined by the monitor command Define-Max-Input-Port-Length.

Error in channel output. Max channel queue length exceeded

The length of the queue of the receiving channel has exceeded the value defined by the monitor command Define-Max-Input-Port-Length

Channel Output Errors

 Report Type:  ChannelOutput

In addition to the following messages, information about the channel, signal, sender and receiver is also displayed.

Error in channel output. No valid receiver found

An attempt was made to output a signal to an invalid PId expression.

Error in channel output. No path to receiver

An attempt was made to output a signal to a PId expression. There exists, however, no path of channels and signal routes between the sender and the receiver that can convey the signal.

Error in channel output. No possible receiver found

An attempt was made to output a signal without specifying a PId expression. When all paths or all paths mentioned in a via clause had been examined no possible receiver was found.

Error in channel output. Several possible receivers found

An attempt was made to output a signal without specifying a PId expression. When all paths or all paths mentioned in a via clause had been examined several possible receivers were found.

Error in channel output. Signal sent to stopped process instance

An attempt was made to output a signal to a PId expression that referred to a process instance which has performed a stop action.

Error in channel output. Signal sent to NULL

An attempt was made to output a signal to a PId expression that was null.

Operator Errors

 Report Type:  Operator

The errors that can be found in operators defined in the predefined data types are listed below.

Error in SDL Operator: Modify! in sort Charstring, Index out of bounds

Error in SDL Operator: Extract! in sort Charstring, Index out of bounds

Error in SDL Operator: MkString in sort Charstring, character NUL not allowed

Error in SDL Operator: First in sort Charstring, Charstring length is zero

Error in SDL Operator: Last in sort Charstring, Charstring length is zero

Error in SDL Operator: Substring in sort Charstring, Charstring length is 0

Error in SDL Operator: Substring in sort Charstring, Sublength is less than or equal to zero

Error in SDL Operator: Substring in sort Charstring, Start is less than or equal to zero

Error in SDL Operator: Substring in sort Charstring, Start + Substring length is greater than string length.

Error in SDL Operator: Division in sort Integer, Integer division by 0.

Error in SDL Operator: Division in sort Real, Real division by 0.

Error in SDL Operator: Fix in sort Integer
Integer overflow
Second operand is 0

Error in SDL Operator: Mod in sort Integer
Second operand is 0

Error in SDL Operator: Rem in sort Integer
Second operand is 0

Range Errors

 Report Type:  Subrange

Error in assignment in sort <sort>:
<value> out of range

A variable of a restricted syntype is assigned a value out of its range.

Index Error

 Report Type:  Index

Error in SDL array index in sort <sort>:
<value> out of range

An array index is out of range.

Decision Error

 Report Type:  Decision

Error in SDL Decision: Value is <value>:
Fatal error. Analysis is not continued below this node

The value of the expression in the SDL decision did not match any of the possibilities (answers).

Import Errors

 Report Type:  Import

Error during execution of an import statement. Supplementary information about remote variables and exporting processes is also given.

Error in SDL Import. Attempt to import from the environment

Error in SDL Import. Attempt to import from NULL

Error in SDL Import. Attempt to import from stopped process instance

Error in SDL Import. Several processes exporting this variable

Error in SDL Import. The specified process does not export this variable

Error in SDL Import. No process exports this variable

Error in SDL Import. More than one process exports this variable

View Errors

 Report Type:  View

Error during execution of view statement. Supplementary information about viewed variables and revealing processes is also given.

Error in SDL View. Attempt to view from the environment

Error in SDL View. Attempt to view from NULL

Error in SDL View. Attempt to view from stopped process instance

Error in SDL View. More than one process instance reveals the variable

Error in SDL View. The specified process does not reveal the variable.

Error in SDL View. No process instance reveals this variable

Transition Length Error

 Report Type:  MaxTransLen

Max transition length exceeded

The maximum number of SDL symbols executed in one behavior tree transition is more than the value defined by the monitor command Define-Max-Transition-Length.

Non Progress Loop Error

 Report Type:  Loop

Loop Detected.

The Validator includes a mechanism for non-progress loop detection. A report will be generated if the Validator during state space exploration finds a loop in the state space which does not contain any progress transition. A progress transition is defined as a transition that either:

  • contains communication with the environment
  • contains a call to the function xProgress() in user-defined C code
  • includes a timer expiration (see "Timer Progress" )
  • includes a spontaneous transition (see "Spontaneous Transition Progress" ).

Assertion Errors

 Report Type:  Assertion

Assertion is false: <user-defined string>

A user-defined action in the SDL system has called the function
xAssertError. See "Using Assertions" for more information.

User Defined Rule

 Report Type:  UserRule

User-defined rule satisfied

A user-defined rule is evaluated to true.

Observer Errors

 Report Type:  Observer

Observer violation

A process defined as an observer process has not been able to execute a transition.

MSC Verification Errors

 Report Type:  MSCVerification
 Report Type:  MSCViolation

MSC <MSC name> verified
MSC sequence: <MSC name list>

MSC <MSC name> violated
Event: <SDL Event>

The MSC verification report is given when a state space exploration has reached a state where the execution trace from the root of the behavior tree to the current state satisfies the loaded MSC. In this case, "satisfies" means that:

  • The execution trace must include all events that exist in the MSC.
  • The execution trace must not contain any observable event that is not part of the MSC.
  • The sequence of observable events in the execution trace must be consistent with the partial ordering of the events that is defined by the MSC.

An event on the execution trace is considered to be "observable" if it is either

  • an input or output of a signal that is sent between process instances that correspond to different MSC instances, or
  • a create of a process instance that corresponds to a different MSC instance than the creating process instance, or
  • a set, reset or input of a timer, depending on the value set by the command Define-Timer-Check-Level.

Note:

Two process instances can correspond to the same MSC instance if the MSC is a system or block level MSC.

The MSC violation report is given during state space exploration for each generated execution trace that either:

  • includes an observable event that is not part of the loaded MSC, or
  • contains a sequence of observable events that is not consistent with the partial ordering of events defined by the MSC.

REF Errors

 Report Type:  RefError

No reference to dynamically allocated memory of sort: <Sort Name>

The list of dynamically allocated data areas that is maintained by the Validator contains a data area that no SDL entity (like a variable, signal parameter etc.) references. This indicates a memory leak in the system.

No reference to dynamically allocated memory

The list of dynamically allocated data areas that is maintained by the Validator contains a data area that no SDL entity (like a variable, signal parameter etc.) references. This indicates a memory leak in the system. The lack of <Sort Name> in this report indicates that this is a newly allocated data area and there has been no previous system state with a reference to this data area.

Referenced data area not found:
Variable <Variable name> in process <Process name>

A REF variable (or signal parameter, structure field etc.) has been found that references a data area that is not allocated. To avoid this report always set the REF variables to NULL after the data area has been released.

Dereferencing a NULL pointer of sort: <Sort Name>.

An expression XX*> has been evaluated where XX was NULL.

Calling UserMalloc with parameter NULL
Calling UserFree with parameter NULL

The UserMalloc or UserFree functions has been called with NULL as a parameter which is illegal.

Calling UserFree without dynamically allocated memory

UserFree has been called with a parameter that is not a pointer to one of the data areas in the list of the dynamically allocated data areas.


User-Defined Rules

User-defined rules are used during state space exploration to check for properties of the system states encountered. If a system state is found for which a user-defined rule is true, this will be listed among the other reports when giving the List-Reports command. During an exploration more that one user defined rule report can be generated. There will be one report for each value assignment that can be made to a rule. The value assignments are the values printed by the Print-Evaluated-Rule command.

A rule essentially gives the possibility to define predicates that describe properties of one particular system state. A rule consists of a predicate (as described below) followed by a semicolon (`;'). In a rule, all identifiers and reserved words can be abbreviated as long as they are unique.

Note:

Only one rule can be used at any moment. If more than one rule is needed, reformulate the rules as one rule, using the boolean operators described below.

Predicates

The following types of predicates exist:

  • Quantifiers over process instances and signals in input ports.
  • Boolean operator predicates such as "and", "not" and "or".
  • Relational operator predicates such as "=" and ">".

Parenthesis are allowed to group predicates.

Quantifiers

The quantifiers listed below are used to define rule variables denoting process instances or signals. The rule variables can be used in process or signal functions described later in this section.

exists <RULE VARIABLE> [: <PROCESS TYPE>]
[ | <PREDICATE>]

This predicate is true if there exists a process instance (of the specified type) for which the specified predicate is true. Both the process type and the predicate can be excluded. If the process type is excluded all process instances are checked. If the predicate is excluded it is considered to be true.

all <RULE VARIABLE> [ : <PROCESS TYPE>]
[ | <PREDICATE>]

This predicate is true for all process instances (of the specified type) for which the specified predicate is true. Both the process type and the predicate can be excluded. If the process type is excluded all process instances are checked. If the predicate is excluded it is considered to be true.

siexists <RULE VARIABLE> [ : <SIGNAL TYPE>]
[ - <PROCESS INSTANCE>] [ | <PREDICATE>]

This predicate is true if there exists a signal (of the specified type) in the input port of the specified process for which the specified predicate is true. If no signal type is specified, all signals are considered. If no process instance is specified the input ports of all process instances are considered. If no predicate is specified it is considered to be true. The specified process can be either a rule variable that has previously been defined in an exists or all predicate, or a process instance identifier (<PROCESS TYPE>:<INSTANCE NO>).

siall <RULE VARIABLE> [ : <SIGNAL TYPE>]
[ - <PROCESS INSTANCE>] [ | <PREDICATE>]

This predicate is true for all signals (of the specified type) in the input port of the specified process for which the specified predicate is true. If no signal type is specified all signals are considered. If no process is specified the input ports of all process instances are considered. If no predicate is specified it is considered to be true. The specified process can be either a rule variable that has previously been defined in an exists or all predicate, or a process instance identifier (<PROCESS TYPE>:<INSTANCE NO>).

Boolean Operator Predicates

The following boolean operators are included (with the conventional interpretation):

not <PREDICATE>
<PREDICATE> and <PREDICATE>
<PREDICATE> or <PREDICATE>

The operators are listed in priority order, but the priority can be changed by using parenthesis.

Relational Operator Predicates

The following relational operator predicates exist:

<EXPRESSION> = <EXPRESSION>
<EXPRESSION> != <EXPRESSION>
<EXPRESSION> < <EXPRESSION>
<EXPRESSION> > <EXPRESSION>
<EXPRESSION> <= <EXPRESSION>
<EXPRESSION> >= <EXPRESSION>

The interpretation of these predicates is conventional. The operators are only applicable to data types for which they are defined.

Expressions

The expressions that are possible to use in relational operator predicates are of the following categories:

  • Process functions: Extract values from process instances.
  • Signal functions: Extract values from signals.
  • Global functions: Examine global aspects of the system state.
  • SDL literals: Conventional SDL constant values.

Process Functions

Most of the process functions must have a process instance as a parameter. This process instance can be either a rule variable that has previously been defined in an exists or all predicate, a process instance identifier (<PROCESS TYPE>:<INSTANCE NO>), or a function that returns a process instance, e.g. sender or from.

state( <PROCESS INSTANCE> )

Returns the current SDL state of the process instance.

type( <PROCESS INSTANCE> )

Returns the type of the process instance.

iplen( <PROCESS INSTANCE> )

Returns the length of the input port queue of the process instance.

sender( <PROCESS INSTANCE> )

Returns the value of the imperative operator sender (a process instance) for the process instance.

parent( <PROCESS INSTANCE> )

Returns the value of the imperative operator parent (a process instance) for the process instance.

offspring( <PROCESS INSTANCE> )

Returns the value of the imperative operator offspring (a process instance) for the process instance.

self( <PROCESS INSTANCE> )

Returns the value of the imperative operator self (a process instance) for the process instance.

signal( <PROCESS INSTANCE> )

Returns the signal that is to be consumed if the process instance is in an SDL state. Otherwise, if the process instance is in the middle of an SDL process graph transition, it returns the signal that was consumed in the last input statement.

<PROCESS INSTANCE> -> <VARIABLE NAME>

Returns the value of the specified variable. If <PROCESS INSTANCE> is a previously defined rule variable, the exists or all predicate that defined the rule variable must also include a process type specification.

<RULE VARIABLE>

Returns the process instance value of <RULE VARIABLE>, which must be a rule variable bound to a process instance in an exists or all predicate.

Signal Functions

Most of the signal functions must have a signal as a parameter. This signal can be either a rule variable that has previously been defined in an siexists or siall predicate, or a function that returns a signal, e.g. signal.

sitype( <SIGNAL> )

Returns the type of the signal.

to( <SIGNAL> )

Returns the process instance value of the receiver of the signal.

from( <SIGNAL> )

Gives the process instance value of the sender of the signal.

<RULE VARIABLE> -> <PARAMETER NUMBER>

Returns the value of the specified signal parameter. The siexists or siall predicate that defined the rule variable must also include a signal type specification.

<RULE VARIABLE>

Returns the signal value of <RULE VARIABLE>, which must be a rule variable bound to a signal in a siexists or siall predicate.

Global Functions

maxlen( )

Gives the length of the longest input port queue in the system.

instno( [<PROCESS TYPE>] )

Returns the number of instances of type <PROCESS TYPE>. If <PROCESS TYPE> is excluded the total number of process instances is returned.

depth( )

Gives the depth of the current system state in the behavior tree/state space.

SDL Literals

<STATE ID>

The name of an SDL state.

<PROCESS TYPE>

The name of a process type.

<PROCESS INSTANCE>

A process instance identifier of the format <PROCESS TYPE>:<INSTANCE NO>, e.g. Initiator:1.

<SIGNAL TYPE>

The name of a signal type.

null

SDL null process instance value

env

Returns the value of the process instance in the environment that is the sender of all signals sent from the environment of the SDL system.

<INTEGER LITERAL>
true
false
<REAL LITERAL>
<CHARACTER LITERAL>
<CHARSTRING LITERAL>


Autolink Configuration Syntax

An Autolink configuration is created with the command Define-Autolink-Configuration. The syntax of an Autolink configuration is expressed below in EBNF format.

<Start> ::= "Define-Autolink-Configuration"
<Configuration>
"End"

<Configuration> ::= { <TransRule> | <TSStructureRule> |
<ASPTypesRule> | <PDUTypesRule> |
<StripSignalsRule> <Function> }*

<TransRule> ::= "TRANSLATE"
[ "SIGNAL" ] <AlternativeListOfTerms>
<TransRuleIf>* [ <TransRuleNoIf> ]
"END"

<TransRuleIf> ::= "IF" <Conditions> "THEN"
<TransRuleNoIf> "END"

<TransRuleNoIf> ::= { "CONSTRAINT"
<TransRuleConstraint> |
"TESTSUITE"
<TransRuleTestSuite> }*

<TransRuleConstraint> ::= { "NAME" <Term> |
"PARS" <ParameterList1> |
"MATCH" <ParameterList1> }*

<TransRuleTestSuite> ::= { "CONSTS" <ParameterList1> |
"PARS" <ParameterList2> }*

<ParameterList1> ::= <Parameter1> { "," <Parameter1> }*

<Parameter1> ::= "$" <Number> [ "=" <Term> ]

<ParameterList2> ::= <Parameter2> { "," <Parameter2> }*

<Parameter2> ::= "$" <Number> [ "=" <Term> ]
[ "/" <Term> ]

<TSStructureRule> ::= "PLACE" <AlternativeListOfTerms>
<TSStructureRuleIf>*
[ <TSStructureRuleNoIf> ]
"END"

<TSStructureRuleIf> ::= "IF" <Conditions> "THEN"
<TSStructureRuleNoIf> "END"

<TSStructureRuleNoIf> ::= "IN" <Term> { "/" <Term> }*

<ASPTypesRule> ::= "ASP-TYPES"
<SequentialListOfTerms> "END"
<PDUTypesRule> ::= "PDU-TYPES"
<SequentialListOfTerms> "END"
<StripSignalsRule> ::= "STRIP-SIGNALS"
<SequentialListOfTerms> "END"
<Function> ::= "FUNCTION" <Identifier>
<Mappings> "END"

<Mappings> ::= <Mapping> { "|" <Mapping> }*

<Mapping> ::= <Conditions> ":" <Term>

<Term> ::= <Atom> { "+" <Atom> }*

<Atom> ::= "$" <Number> | "@" <Number> |
<Text> | <Identifier> |
<FunctionCall>

<FunctionCall> ::= <Identifier>
"(" <SequentialListOfTerms> ")"

<SequentialListOfTerms> ::= <Term> { "," <Term> }*

<AlternativeListOfTerms> ::= <Term> { "|" <Term> }*

<Conditions> ::= <Condition> { "AND" <Condition> }*

<Condition> ::= <Term> { "==" | "!=" } <Term> |
"TRUE"

For a detailed description of the semantics, see "Syntax and Semantics of the Autolink Configuration" .


State Space Files

Using the command Save-State-Space, a Labelled Transition System (LTS) representing the state space generated during exhaustive exploration is saved to a file.

Syntax

The syntax of the generated LTS is (using BNF notation):

 LTS	 ::=	 `START:' StateId `LTS:' TransList*
`STATES:' State*
 TransList	 ::=	 StateId `:' Event `-' [StateId] (`,' Event
`-' [StateId])* `;'
 Event	 ::=	 (Output | Input | Timeout | Internal)
 Output	 ::=	 `o(' Signal `,' `"' GraphRef `"' `)'
 Input 	 ::=	 `i(' Signal `,' `"' GraphRef `"' `)'
 Timeout	 ::=	 `t(' Timer `)'
 Internal	 ::=	 `x'
 State	 ::=	 `*****' StateId `*****' Process*
 Process	 ::=	 ProcessName `:' InstanceNo `State:' StateName
(VariableName `:' Value)* `Input port:[' Signal
(`,' Signal)* `]' `Timers:{' Timer (`,' Timer)*
`}' Procedure*
 Procedure	 ::=	 `Procedure' ProcedureName `:' `State:'
StateName (VariableName `:' Value)*
 Signal	 ::=	 SignalName `(' ParameterName (`,'
ParameterName)* `)'
 Timer 	 ::=	 TimerName `(' ParameterName (`,'
ParameterName)* `)'

Lexical Elements

The lexical elements used above are:

 StateId	 	 An integer denoting a system state.
 GraphRef	 	 A string denoting a graphical reference to an
SDL diagram.
 ProcessName	 	 An id denoting a process type.
 InstanceNo	 	 An integer denoting a process instance.
 StateName	 	 An id denoting a state in an SDL process graph.
 VariableName	 	 An id denoting a process variable.
 Value	 	 A string denoting a value for a variable of any
defined SDL type.
 ProcedureName	 	 An id denoting a procedure.
 ParameterName	 	 An id denoting a signal or timer parameter.

Example 323 : A Generated LTS

A simple example of a generated LTS:

START:121
LTS:
2456:o(sig1(true,3),"5 P1 1 80 100")-43567;
43567:i(sig2(1),"5 P1 1 80 120")-2467,
i(sig2(2),"5 P1 1 100 120")-98567;
121:x-2456;
2467:x-27645;
98567:x-27645;
27645:i(sig2(1),"5 P1 1 80 120")-2467,
i(sig2(2),"5 P1 1 100 120")-98567;
STATES:
***** 121 *****
P1:1 State:idle Parent:null Offspring:null Sender:null i:0 Input port:[ ] Timers:{ }
***** 2456 *****
P1:1 State:idle Parent:null Offspring:null Sender:null i:5 Input port:[ ] Timers:{ }
***** 43567 *****
P1:1 State:s1 Parent:null Offspring:null Sender:null i:5 Input port:[ ] Timers:{ }
***** 2467 *****
P1:1 State:s1 Parent:null Offspring:null Sender:null i:1 Input port:[ ] Timers:{ }
***** 98567 *****
P1:1 State:s1 Parent:null Offspring:null Sender:null i:2 Input port:[ ] Timers:{ }
***** 27645 *****
P1:1 State:s1 Parent:null Offspring:null Sender:ENV i:5 Input port:[ ] Timers:{ }


Restrictions

Restrictions on the SDL System

The restrictions on the SDL system that can be validated with the SDL Validator are basically the restrictions imposed by the SDL to C compilers. See "Restrictions" for more information.

In addition to these general restrictions, the following restrictions are specific to the SDL Validator:

  • Time is not represented in the state space explored by the validator. This makes the behavior of "Now" expressions special. In the SDL Validator, "Now" will always return 0.
  • If user-defined types with dynamic memory allocation are used, the type must be implemented as a pointer to a data area. A function for freeing the memory must also be supplied. For more information, see "More about Abstract Data Types" .

Restrictions on Monitor Input

There following restrictions apply to monitor input:

  • A parameter to a monitor command may not contain more than 1,000 characters.
  • On UNIX, control characters of different types may terminate the validation program. <Ctrl+C>, <Ctrl+D>, and <Ctrl+Z> are typical characters that might terminate a validation program.

Restrictions on Dynamic Checks

There are a number of dynamic checks that are not performed at all or performed at the C level by the C runtime system. A C runtime error will of course lead to the validation program being terminated. The following check is not made at the SDL level.

  • Overflow of integer and real values are checked at the C level if the actual C system performs these checks. (These checks are likely not to be performed.)


53 Validating a System

This chapters provides general information related to validation in the SDL suite and describes the actions you perform when validating an SDL system.

For a reference to the validator user interface, see 52 The SDL Validator.

How to use Autolink, a part of the SDL Validator, is described in "Using Autolink" .


Introduction

Application Areas

The Validator is a tool intended to support engineers involved in development of specifications or designs using SDL. It is designed to give the engineers a possibility to increase the quality of their work and to automate time-consuming tasks. It is focused on the following major application areas in the development process:

  • It provides an automated fault detection mechanism that checks the robustness of the application and finds inconsistencies and problems in an early stage of development. This is often referred to as validating an SDL system. See "Validating an SDL System" .
  • When verifying the system against requirements, the Validator provides a possibility to perform automatic verification of the requirements expressed using the MSC (Message Sequence Chart) notation. See "Verifying an MSC" .
  • When designing safety-critical or complex systems the Validator provides a possibility to test specific properties of the design. See "Using Observer Processes" .
  • When developing TTCN test cases, the Autolink feature of the Validator can be used to create and use MSC test purposes and to generate TTCN test cases. See "Using Autolink" .

Structure of a Validator

An executable validator is built up in the same way as a simulator. See "Structure of a Simulator" for more information.

The same interactive monitor system as for a simulator is used, but the set of available commands differ. The graphical user interface to the validator monitor, the Validator UI, works in the same way as the Simulator UI, but the set of available command buttons differ. For a description of some other differences, see "The Validator User Interface" .


Underlying Principles and Terms

The SDL Validator is based on a technique called state space exploration, which is a well-known technique for automatic analysis of distributed systems. All state space exploration tools for SDL are based on the idea of an automatic generation of the reachable state space for the SDL systems.

For readers interested in a more detailed description of the possibilities given by state space exploration for validation of distributed systems (focused on protocols), an excellent description is given in [16], see "References" .

Behavior Trees

The SDL Validator operates on structures known as behavior trees or reachability graphs. A behavior tree is a tree structure that represents the behavior of an SDL system.

The nodes of the tree represent SDL system states. A system state is defined by:

  • The process instances that are active
  • The variable values of these processes
  • The SDL control flow state of the process instances
  • Any procedure calls (with local variables etc.)
  • Signals (with parameters) that are present in the queues of the system
  • Active timers
  • Etc.

The edges between the nodes in the tree represent atomic SDL events that transfers the SDL system from one system state to another. Therefore, the edges are also called behavior tree transitions. They can be individual SDL statements like tasks, inputs, outputs, etc. but also complete SDL transitions, depending on how the Validator is configured.

The size and structure of the behavior tree can thus vary and is determined by a number of Validator options. These options affect the number of system states generated for an SDL transition, and the number of possible behavior tree transitions from a state in the tree.

State Space Explorations

The set of all system states represented by the behavior tree is called the state space of the system. By moving around in the behavior tree, the behavior of the SDL system can be explored and the system states reached can be examined. This is known as state space exploration, and it can be performed both manually and automatically.

Note:

The "children" of a node in the behavior tree are not generated until a state space exploration actually reaches that node, i.e., the tree is not a static structure generated when a validator is started.

For each system state reached during state space exploration, a number of rules are checked to detect errors or possible problems in the SDL system. If a rule is violated, a report is generated to the user. By investigating the report and the system state where it was generated, the cause of the error can be determined.

States and Paths

The original start state of the system is called the system start state. It is the system state where the static process instances have been created but their initial start transitions have not been executed.

The current state is the system state that currently is under investigation. It is changed when manually navigating in the behavior tree, or when going to the system state where a report has been generated. Initially, it is set to the system start state.

The current root of the behavior tree can be any system state. A number of Validator commands and features use it as a starting point of operation. Initially, it is set up to the system start state, also known as the original root of the behavior tree. If it is redefined, it is not possible to reach a state above the current root in the behavior tree without resetting it back to the original root.

A path between two states in the behavior tree can be denoted by a sequence of integers, each one indicating which transition was used to get between two states in the path. The current path is a path that is set up when manually navigating in the behavior tree, or when going to the system state where a report has been generated. When set up, it is the path between the current root and the current state. The current path is changed when the Validator moves to a state that is not part of the current path, e.g. when manually navigating to a system state outside of the current path. However, moving up and down along the current path does not change it.


Generating and Starting a Validator

There are two ways to generate and start a validator:

  • A quick way in one single step, adequate for most situations
  • A more complex way in several steps, giving you complete control of the generation and start process.

In the following, the more complex way will be described first, to give a full understanding of the process. The quick way is described in "Quick Start of a Validator" .

Generating a Validator

The Validator is implemented as a precompiled run-time kernel to the SDL to C Compiler. To start a Validator for an SDL system, or a part of an SDL system, it is thus necessary to first generate an executable validator. This is done from the Organizer.

To generate an executable validator:

  1. Select a system, block, or process diagram in the Organizer.
  2. Select Make from the Generate menu. The Make dialog is opened.
  3. Turn on the options Analyze & generate code and Makefile.
  4. From the Standard kernel option menu, select Validation.
  5. If you need to check the Analyzer options, click the Analyze Options button. In the dialog, set the options and click the Set button. For more information about these options, see "Analyzing Using Customized Options" .
  6. Click the Make button.
    A validator for the system is now generated in the current directory with the name <system>_xxx.val (on UNIX), or <system>_xxx.exe (in Windows), where the _xxx suffix is platform or kernel/compiler specific. The Status Bar of the Organizer reports the progress of the generation; the last message should be "Compiler done."
  7. Open the Organizer Log window from the Tools menu and check that no errors occurred and that a validator was generated.
    • If errors were found, correct them and repeat the generation process. See "Locating and Correcting Analysis Errors" .
    • If no validator was generated, repeat the generation process, but click the Full Make button in the Make dialog instead.

Starting a Validator

An executable validator can be run in two different modes; graphical mode and stand-alone mode (textual mode).

Graphical Mode

In graphical mode, the Validator takes advantage of the graphical user interface and integration mechanism of the SDL suite. A separate graphical user interface, the Validator UI, is started, giving access to the monitor system through the use of menus, command buttons, etc.

To start a validator in graphical mode:

  1. Select SDL > Validator UI from the Organizer's Tools menu. The graphical user interface of the Validator is opened (see "The Graphical Interface" ).
  2. Select Open from the Validator UI's File menu. A File Selection Dialog dialog is opened.
    • Alternatively, click the Open quick button in the tool bar.
  3. In the dialog, locate and select an executable validator and click OK.

A welcome message is printed in the text area of the Validator UI. The monitor system is now ready to accept commands. Please see "Supplying Values of External Synonyms" for some additional information that may affect the start-up.

Stand-alone Mode (Textual Mode)

In stand-alone mode, the Validator uses the input and output devices currently defined on your computer, which provide a textual, command-line based user interface. A very limited graphical support is provided when running the Validator in this mode.

To start a validator in stand-alone mode, the generated validator is executed directly from the OS prompt, e.g.

csh% ./system_vla.val

A welcome message is printed on the terminal:

Welcome to SDL VALIDATOR

Command :

The monitor system is now ready to accept commands. Please see "Supplying Values of External Synonyms" for some additional information that may affect the start-up.

Note:

On UNIX, before a validator can be run in stand-alone mode, you must execute a command file from the operating system prompt. The file is called telelogic.sou or telelogic.profile and is located in the binary directory that is included in your $path variable.
For csh-compatible shells: source <bin.dir>/telelogic.sou
For sh-compatible shells: . <bin.dir>/telelogic.profile

Quick Start of a Validator

A validator can also be generated and automatically started in graphical mode in one single step.

To quick start a validator, click the Validate quick button in the Organizer's tool bar. The following things happen:

  • A validator is generated by using the validator kernel that is specified in the Make dialog. (If no validator kernel is specified, a default validator kernel is used.)
  • The graphical Validator UI is started. If a Validator UI with the same validator name is already open, this UI is reused. If another Validator UI is open, a dialog is opened where you can select to start a new UI, or to reuse one of the existing UI's.
  • The generated validator is started from the Validator UI.

It is possible to start a validator for a part of an SDL system (a block or a process) by selecting the block/process and then clicking on the Validate button.

Restarting a Validator

An executing validator can be restarted from the beginning to reset its state completely:

  • In graphical mode, select Restart from the Validator UI's File menu. (This is the same as opening the same validator again.) A confirmation dialog is opened.
  • In stand-alone mode, the validator has to be exited with the Exit command and then executed from the OS prompt again.

Supplying Values of External Synonyms

The SDL system for the validator may contain external synonyms that do not have a corresponding macro definition (see "External Synonyms" ). In that case, you will be asked to supply the values of these synonyms, either by selecting a file with synonym definitions or by entering each synonym value from the keyboard.

In stand-alone mode, the following prompt appears:

External synonym file :

Enter the name of a file containing synonym definitions, or press <Return> to be prompted for each synonym value.

In graphical mode, a file selection dialog is opened. Either select a file (*.syn) containing synonym definitions, or press Cancel to be prompted for each value in a separate dialog. In this dialog, the name and type of the synonym is shown together with an input text field. You can now do one of the following:

  • Enter a value and click OK.
  • Click Default value to get a "null" value for the synonym type entered in the input field. Accept or edit this value and click OK.
  • Click Cancel to give the synonym a "null" value (without the possibility to edit the value).
  • Click Cancel all to give the synonym and all following synonyms a "null" value.

If a synonym file is selected in the file selection dialog, this file is also used when the validator is restarted. (If you by any chance want to use another synonym file you have to start a new Validator UI.)

If you set the environment variable SDTEXTSYNFILE to a file before starting the SDL suite, this file will automatically be used. If SDTEXTSYNFILE is set to "[[" all synonyms are given "null" values.

The syntax of a synonym file is described in "Reading Values at Program Start up" .

Actions on Validator Start-up

When a validator is started, the static process instances in the system are created, but their initial transitions are not executed.

In some cases when the Validator is started, a message is printed that it is not possible to generate test values for all sorts and/or signal parameters. This has to do with the automatic test value generation mechanism that is used in the Validator. It happens if there are signals coming from the environment of the SDL system that have parameters of a sort that the test value generation cannot handle. To overcome this, define some test values for the sort that the Validator is complaining about. See "Defining Signals from the Environment" for more information.


The Validator User Interface

Monitor commands in the Validator are issued in the same way as in the Simulator, since the same monitor system is used in both tools. Also, the Validator UI works in the same way as the Simulator UI. Please see "Issuing Monitor Commands" for more information.

The Validator UI can be customized in the same way as the Simulator UI. Please see "Customizing the Simulator UI" for more information.

However, there are a few differences between the user interface of the Validator and the Simulator. These differences are described below.

Activating the Monitor

The validator's monitor system becomes active when the validator is started, when a transition executed during navigation has completed, when an automatic state space exploration has finished, when a report with Abort action has been generated, or when an automatic state space exploration is manually stopped.

These conditions are listed in greater detail in "Activating the Monitor" .

The Graphical Interface

The graphical Validator UI is illustrated in the figure below:

Figure 477 : The Validator UI

Since the set of available commands differ between the Simulator UI and the Validator UI, the set of button modules and command buttons is also different. In addition, three extra menus are available in the menu bar: Commands Menu, Options1 Menu and Options2 Menu. The menu choices in these menus are similar to the command buttons in the sense that each of them correspond to a certain monitor command.

The Command and Watch Windows

The Command and Watch windows are also available in the Validator UI. The difference compared to the Simulator UI is:

  • In the Command window, the default commands that are executed are "List-Process -" and "Print-Trace 1".


Navigating in the State Space

The SDL Validator provides the possibility to interactively walk around in the behavior tree of an SDL system. This is also known as manually navigating in the state space. A dedicated graphical tool, the Navigator, is available in the Validator to facilitate manual navigating. However, it is possible to use manual navigation without using the Navigator tool.

The Navigator is intended to be used in three different situations:

  1. When learning how a state space exploration tool like the Validator works, the Navigator is a convenient tool for interactively investigating the behavior tree of an SDL system.
  2. When using automatic state space exploration, there is sometimes a need to start the exploration from a different starting point than the system start state of the SDL system. In this case, the Navigator can be used to walk to a suitable system state, from which the automatic exploration can be started.
  3. When investigating a report generated during automatic exploration, the Navigator can be used to check the alternative behaviors that are possible on the path to the reported situation.

To open the Navigator tool, use one of the following methods:

  • Select Show Navigator from the Commands menu.
  • In the button module Explore, click the Navigator button.
  • Enter the command Show-Navigator.

Figure 478 : The Navigator

The boxes shown in the Navigator represent the behavior tree transitions leading to and from the current system state. They are labelled
Up 1 (for the transition leading to the current state) and Next 1, Next 2, etc. (for the transitions leading from the current state).

To close the Navigator, click the Close quick button in the tool bar.

Moving Up in the Behavior Tree

To move one level up in the behavior tree, use one of the following methods:

  • In the Navigator, double-click the Up node, or select Up 1 from the pop-up menu available on the Up node.
  • In the button module Explore, click the Up button.
  • Enter the command Tree-Walk 1.

To move more than one level up in the behavior tree at once:

  • Enter the command Tree-Walk, followed by the number of levels to move up.

To move to the current root of the behavior tree, i.e. the top of the current path, use one of the following methods:

  • In the Navigator, select Up to top from the pop-up menu available on the Up node.
  • In the button module Explore, click the Top button.
  • Enter the command Top.

Moving Down in the Behavior Tree

To see the possible Next nodes when the Navigator is not opened, enter the command List-Next. This gives a numbered list of all transitions leading from the current state.

To move one level down in the behavior tree, use one of the following methods:

  • In the Navigator, double-click one of the Next nodes, or select Goto from the pop-up menu available on the Next nodes. This will follow the branch one step.
  • Enter the command Next, followed by the number of the Next node, i.e. the number of the transition to execute.

To move more than one level down in the behavior tree at once:

  • Enter the command Random-Down, followed by the number of levels to move down. For each level, a transition is chosen at random.
  • Enter the command Continue-Until-Branch, or in the Navigator, select Continue from the popup menu available on the Next nodes. This will follow the branch several steps until there are more than one transition possible

Moving Along the Current Path

The current path can be seen as the path in the behavior tree that has been explored last. It is set up when going to a report (see "Going to a Report" ) and when interactively walking down the behavior tree.

The transitions making up the current path are labelled with three asterisks "***" in the nodes in the Navigator. However, no such marking is present when the transitions are listed with the List-Next command.

To move up along the current path, use the Up or Top commands as described in "Moving Up in the Behavior Tree" (above).

To move one level down along the current path, use one of the following methods:

  • In the Navigator, double-click the Next node labelled with three asterisks "***", or select Goto from the pop-up menu available on this node.
  • In the button module Explore, click the Down button.
  • Enter the command Down 1.

To move more than one level down along the current path at once, enter the command Down, followed by the number of levels to move down.

To move to the bottom of the current path, use one of the following methods:

  • In the button module Explore, click the Bottom button.
  • Enter the command Bottom.

Redefining the Current Root

The current root of the behavior tree is initially set up to the system start state. The current root is automatically redefined to the current state when using MSC verification (see "Verifying an MSC" ). It can also be redefined as an effect of changing validator options (see "Affecting the State Space" ).

In addition, you can at any time redefine the current root to either the current state or back to the system start state. To do this, enter the command Define-Root. Select or enter Current to redefine the current root to the current state. Select or enter Original to redefine the current root to the system start state.


Going to a System State

When using the Validator it is quite common that there is a need to go to a specific system state, for instance to be able to start an automatic state space exploration from this point. This section describe some possibilities to in an efficient way get to the wanted system state, called the target state below.

Using Manual Navigation

In many cases the simplest way is to use the Navigator tool or the navigation commands to interactively traverse the path to the target state. Manual navigation is described in "Navigating in the State Space" .

Returning to an Already Reached State

It is possible to return to a state that has been reached in an earlier stage when using the Validator. Three methods will be discussed:

  • Using Path Commands
  • Using the Command Log
  • Using MSC Trace.

The benefit of the first two techniques is that the exact same target state will be reached. The drawback is that these techniques will not work as soon as either the SDL system or the state space options have been changed (see "State Space Options" ).

The benefit of the MSC technique is that it is less vulnerable to changes in the state space options or in the SDL system. The drawback is that the exact same target state may not be reached. We only know that the path to the reached system state will satisfy the generated MSC trace.

Using Path Commands

To go to the target state using path commands:

  1. When in the target state, enter the command Print-Path. The path from the root state to the current state is printed. The path is a sequence of integers indicating which transitions must be chosen to get to the current state.
  2. At a later stage, enter the command Goto-Path, followed by the path printed above.

Using the Command Log

To go to the target state using the command log:

  1. Before navigating to the target state, select Start Command Log from the Log menu, or enter the command Command-Log-On. Specify a file name on which all subsequent monitor commands will be stored.
  2. Navigate to the target state.
  3. Select Stop Command Log from the Log menu, or enter the command Command-Log-Off. The command logging is stopped and the file is closed.
  4. Return to the same state in which the command log was started.
  5. Execute the commands stored in the file by selecting Include Command Script from the Commands menu, or enter the command
    Include-File. Select or specify the earlier file name.

Using MSC Trace

To go to the target state using MSC trace:

  1. When in the target state, generate an MSC trace from the root state to the current state. Enter the command MSC-Log-File, followed by a file name.
  2. Return to the root state by using the Top command.
  3. Go to the end of the MSC trace by verifying the MSC. See "Verifying an MSC" .

Using an MSC

If an MSC is created that describes the events leading to the target state, verifying this MSC gives a possibility to go to a system state that satisfies the MSC in an efficient way. It does not matter if the MSC is manually created, generated from the Simulator or from the Validator itself (as discussed in "Using MSC Trace" , above). However, the exact same target state may not be reached by this method. We only know that the path to the reached system state will satisfy the generated MSC trace.

Using a User-Defined Rule

If the target state can be described in terms of process states, variable values, etc., a convenient way to get to a state that satisfies the description is to use a user-defined rule (see "Using User-Defined Rules" ).

To go to a target state using a user-defined rule:

  1. Define the rule describing the target state (see "Managing User-Defined Rules" ).
  2. Define the report action for user-defined rules reports to be Abort (see "Report Action" ). This will cause an automatic exploration to stop as soon as a state is reached that satisfies the rule.
  3. Start an automatic state space exploration (see "Using a Default Exploration" ).
  4. Go to the state where the rule was satisfied and a report was generated (see "Going to a Report" ).

The benefit with this method is that it is fast and efficient, especially if the target state is on a considerable depth in the state space. The drawback is that sometimes there are shorter paths to the target state than the one that was automatically generated.


Tracing, Logging and Viewing Facilities

In the Validator, the same kind of commands as in the Simulator are available for tracing the execution, logging the user interaction and examining the system. There are a few differences, described below.

Tracing the Execution

Textual Trace

In the Validator, the same type of printed trace information is available for executed transitions as in the Simulator; see "Textual Trace" . Unlike the Simulator, however, there is no command to start continuously printing the textual trace; instead, a command must be explicitly used whenever a trace is wanted.

  • To print a textual trace for the transitions leading to the current state, enter the command Print-Trace, followed by the number of transitions to trace. That is, Print-Trace 1 prints the trace for the latest transition. The same information as for a full trace during simulation is printed.
  • By default, the command Print-Trace 1 is executed in the Command window of the Validator UI, i.e., a continuous trace is in practice available in graphical mode.

Graphical SDL Trace

Graphical trace of SDL symbols in the source GR diagrams is available. The graphical trace in the Validator selects all symbols that were executed in the transition leading to the current state. This is different from the Simulator, where GR trace selects the next symbol to be executed.

  • To enable or disable continuous graphical trace, enter the command SDL-Trace. This command toggles the graphical trace; the current state of the trace is printed after the command is executed. When the trace first is enabled, an SDL Editor is opened as soon as the next transition is executed.
  • In the Validator UI, the graphical trace can be controlled from the Commands menu. The command Toggle SDL Trace toggles the trace between enabled and disabled.

MSC Trace

MSC trace enables tracing of executed events in an MSC Editor. When the trace first is enabled, an MSC Editor is opened, showing the events executed up until the current state, and the current path is set up. After that, the trace is continuously updated in the MSC Editor as transitions are executed. This means that events are added when you navigate down the behavior tree, the selected event is changed when you navigate up, and the MSC is redrawn when you move outside the current path.

  • To enable or disable continuous MSC trace, enter the command MSC-Trace. This command toggles the trace; the current state of the trace is printed after the command is executed.
  • In the Validator UI, the MSC trace can be controlled from the Commands menu. The command Toggle MSC Trace toggles the trace between enabled and disabled.

The MSC trace from the current root to the current state can also be saved on a log file, which later may be opened from an MSC Editor. To save such an MSC log, enter the command MSC-Log-File, followed by the file name. The MSC log file should be given the file extension .mpr.

Before an MSC trace is started, you may define what types of events that will be traced. See "MSC Trace Options" for more information.

Logging the User Interaction

The interaction between the user and the Validator can be logged on file in exactly the same way as in the Simulator. See "Logging the User Interaction" for more information.

Examining the System

The current state of the system can be examined in the same way as in the Simulator. The View commands available in the View module of the Validator UI are generally the same ones as in the View module of the Simulator UI.

Current Process and Scope

Some of the commands used for examining the system operate on a specific process instance, the current process, identified by the current scope. A scope is a reference to a process instance, a reference to a service instance if the process contains services, and possibly a reference to a procedure instance called from this process/service (the current procedure).

The scope is automatically set by the validator to the process instance that executed in the transition leading to the current system state. You may change the scope if you would like to examine another process, service or procedure instance.

  • To print the current process/service scope, click the Scope button in the View module, or enter the command Scope.
  • To set the current process/service scope:
    • Click the Set Scope button in the View module, or enter the command Set-Scope. This command takes one parameter, a process instance, and optionally if the process contains services, a second parameter which specifies a service name.
    • Select or enter the name of a process instance.
    • If the process instance contains services, select or enter the name of a service instance.
    • The scope is set to the specified process/service, at the bottom procedure call.
  • To print the procedure call stack for the process/service instance defined by the current scope, click the Call Stack button in the View module, or enter the command Stack.
  • To change the procedure scope within the current process/service scope, you can move the scope one step up or down in the procedure call stack. Click the Up or Down button in the View module, or enter the command Scope-Up or Scope-Down. Going up from a service leads to the process containing the service. To go down in a service within a process, select or enter the name of the service instance.

Commands to Examine the System

The available commands are shortly described below. See "Examining the System" for more information.

  • To list the process instances in the ready queue, enter the command List-Ready-Queue, or click the Ready Q button.
  • To print overview information about process instances, enter the command List-Process, or click the Process List button.
  • To examine a process instance, enter the command Examine-PId, or click the Process button. The process instance must be specified as the first parameter.
  • To list all signal instances in the input port of a process instance, enter the command List-Input-Port, or click the Input Port button. The process instance must be specified as the first parameter.
  • To examine a signal in the input port of a process instance, enter the command Examine-Signal-Instance, or click the Signal button. The process instance must be specified as the first parameter.
  • To list all currently active timers, enter the command List-Timer, or click the Timer List button.
  • To examine a timer instance, enter the command
    Examine-Timer-Instance, or click the Timer button.
  • To examine a variable of a process instance, enter the command
    Examine-Variable, or click the Variable button. The process instance must be specified as the first parameter.


Performing Automatic State Space Explorations

This section describes how to perform an automatic state space exploration and how to examine the results. The application areas in which automatic state space exploration are used are further described in "Validating an SDL System" , "Verifying an MSC" , "Using Observer Processes" and "Using Autolink" .

In the Validator, three types of automatic state space explorations can be used, implemented as different algorithms:

  • Bit state exploration, an efficient algorithm for reasonably large SDL systems.
  • Random walk, a simple algorithm that can be used for very large SDL systems.
  • Exhaustive exploration, an algorithm suited only for small SDL systems.

The characteristics of these algorithms are further described in "Configuring the Validator" . They have the following in common:

  • They start from the current system state, which means that you may have to navigate to a suitable start state before the exploration is started.
  • They explore the state space down to a certain depth from the start state, to avoid exploring an infinite state space forever.

The performance and results of a state space exploration are also highly dependent on how the state space is configured. This is discussed in "State Space Options" .

The most important monitor commands concerning state space explorations are available in the Explore module in the Validator UI.

Executing an Exploration

The different types of explorations are started in the following way:

  • To start a bit state exploration, enter the command
    Bit-State-Exploration, or click the Bit-State button.
  • To start a random walk, enter the command Random-Walk, or click the Random Walk button.
  • To start an exhaustive exploration, enter the command
    Exhaustive-Exploration (there is no button for this command).

Note:

The button Verify MSC starts a bit state exploration, configured to suit MSC verification. This is further described in "Verifying an MSC" .

When the exploration is started, a message is printed stating the options used for this exploration type (see "Configuring the Validator" ):

** Starting bit state exploration **
Search depth : 100
Hash table size : 1000000 bytes

** Starting exhaustive exploration **
Search depth : 100

** Starting random walk **
Depth : 100
Repetitions : 100

By default, the exploration continues until it is finished, i.e., until the state space has been fully explored according to the exploration options. During the exploration, a status message is repeatedly printed after a certain number of transitions or states have been generated.

Note:

Depending on how an exploration is configured, it may take a considerable amount of time to finish!

To stop an exploration manually, click the Break button in the Validator UI, or hit <Return> in stand-alone mode. A stopped exploration may be continued by issuing the same exploration command again. You are then asked whether to continue the exploration from the state where it was stopped, or restart the exploration from the same start state as before.

When the exploration is finished or stopped, some exploration statistics are printed (see "Interpreting Exploration Statistics" ). By default, a tool called the Report Viewer is also opened (see "Examining Reports" ).

The Validator always returns to the start state of the exploration when it is finished or stopped.

Rules Checked During Exploration

During state space exploration, a number of rules are checked to detect errors or possible problems in the SDL system. If a rule is satisfied, a report is generated to the user.

The rules are used to find design errors, typically caused by unexpected behaviors of the SDL system. Often the errors are caused by events happening at the same time in different parts of the system, for example when a signal is received from the environment of the system at the same time as a timer expires. So-called signal races are often part of the error situations that are found.

Apart from the predefined rules, an additional rule can be defined by the user to check for other properties of the system. See "Using User-Defined Rules" for more information.

Interpreting Exploration Statistics

The different exploration algorithms print somewhat different statistics. The important statistics to note are the following:

  • No of reports: x
    The number of error situations found. How to investigate the reports are described in "Examining Reports" .
  • Truncated paths: x
    The number of times the exploration reached the maximum search depth. The execution path is at that stage truncated and the exploration continues in another state. If this value is greater than 0, parts of the state space have not been explored. However, this is a normal situation for SDL systems with infinite state spaces.
  • Collision risk: x
    For bit state explorations, the risk (in percent) for collisions in a hash table used to represent the generated system states (see "Bit State Exploration Options" ). This value should be very small, 0-1%; otherwise, the size of the hash table may have to be increased. If collisions occur, some execution paths may be truncated by mistake.
  • Current depth: x
    The search depth reached at the moment the exploration was finished or stopped. If this value is -1, the exploration finished by itself. If the depth is greater than 0, the exploration was stopped. In this case, it may be continued from this depth, as described in "Executing an Exploration" .
  • Symbol coverage: x
    The percentage of the SDL symbols in the system that have been reached during the exploration. If this value is less than 100, parts of the system have not been explored.

What actions to take depending on the printed statistics is discussed in "Validating an SDL System" .

Examining Reports

When an exploration has been performed, the reported error situations should be examined. A dedicated graphical tool, the Report Viewer, is available in the Validator to facilitate the report examination. However, it is possible to examine the reports without using the Report Viewer.

The Report Viewer is by default automatically opened when an exploration has been performed. To open the Report Viewer manually, either select Show Report Viewer from the Commands menu, or enter the command Show-Report-Viewer.

Figure 479 : The Report Viewer

The nodes in the Report Viewer are structured in three levels and show, from top to bottom:

  • The total number of generated reports
  • The different types of reports (errors) and the number of reports of that type
  • The actual reports with error message and trace information, and the exploration depth where the error was generated (this level of the tree is by default collapsed).

To close the Report Viewer, click the Close quick button in the tool bar.

To list the reports when the Report Viewer is not opened, enter the command List-Reports, which prints a numbered list of all reports.

Changing the Displayed Structure

Generally, to expand or collapse a node in the Report Viewer, double-click the node or select Expand or Collapse from the popup menu available on the nodes. This works for the top node and the report type nodes; for report nodes, see "Going to a Report" (below).

To show the whole report structure, select Expand Substructure from the popup menu available on the top node. To collapse the whole structure, select Collapse from the same pop-up menu, or double-click the expanded top node.

To switch between a tree structure and a list structure, click on the Structure quick button. The list structure makes it possible to easier see the different reports and report types when a large number of reports have been found.

Going to a Report

When "going to a report," the Validator goes to the system state where the report was generated. You can then examine the reported situation further.

To go to a report using the Report Viewer:

  1. Expand the report structure to show the desired report node.
  2. Double-click the report node, or select Goto from the pop-up menu available on the report node.

To go to a report using monitor commands:

  1. List the reports by entering the command List-Reports, and note the number of the desired report.
  2. Enter the command Goto-Report, followed by the report number.

After going to a report, the Navigator tool is updated and the current path is set up. You can walk along the path to the error by using the Navigator; see "Moving Along the Current Path" .

By default, an MSC Editor is also opened, showing the MSC trace from the current root to the state where the report was generated.


Validating an SDL System

This section describes how to use the automatic state space exploration facilities in the Validator to look for inconsistencies and design errors in an SDL system. The idea is essentially to test the robustness of the application, the responses to unexpected situations. Essentially the validation is an attempt to answer questions like:

  • What happens if a user does not press the buttons in the order assumed by the designer?
  • What happens if the scheduling algorithm of the operating system that supports the application is changed?
  • What happens if the environment happens to send an input to the system at the same time as a timer expires?

...and all other questions the designer never ever would imagine.

It is assumed that the SDL system is of moderate size and complexity; techniques for validating large SDL systems are described in "Validating Large Systems" .

Using a Default Exploration

When you are to use the Validator to try finding errors in a new SDL system for the first time, you are advised to start a bit state exploration using the default options.

To validate a system opened in the Validator:

  1. If you already have executed commands for the opened validator, you should reset the validator. Enter the command Reset, or click the Reset button in the Explore module. This is especially important if you earlier have loaded an MSC into the Validator.
  2. You should also make sure you use the default state space and exploration options. Enter the command Default-Options, or click the Default button in the Explore module.
  3. Start a bit state exploration (see "Executing an Exploration" ). Let the exploration run for at least 10-20 minutes.
  4. If the exploration has not finished by itself, stop it manually (see "Executing an Exploration" ). The Report Viewer is opened and the exploration statistics is printed. Note especially what the symbol coverage is.
  5. Use the Report Viewer to go to each of the reported situations (see "Examining Reports" ). Navigate along the current path to the report and use the tracing and viewing facilities to examine the report.
  6. If you find errors in the system, you may decide to correct them immediately. In that case, generate a new validator for the corrected system and rerun the validation, as described above. Otherwise, you should check if the validation is to be considered finished (see below).

Determining if the Validation is Finished

When all reports have been checked and the found errors possibly have been corrected, the next question arises: When are we finished validating the system? To answer this question, look at these aspects:

  • What was the symbol coverage reported in the statistics after the automatic exploration?
  • Did the exploration finish by itself or was it stopped by the user?

The following possibilities now exist:

  1. The symbol coverage is 100% and the exploration finished by itself.
    All symbols have been executed and furthermore most orderings of the possible actions have been tested. In this case it is probably not worthwhile continuing the validation; you may consider it finished.
    However, not all orderings of possible actions have been tested, since the search may have been truncated, collisions may have occurred in the hash table, and more orderings are possible by configuring the state space exploration differently. If you want, you can change the validator options and start a new exploration (see "Using Advanced Validation" and "Configuring the Validator" ).
  2. The symbol coverage is 100% but the exploration was manually stopped.
    In this case, it may still be worthwhile to continue the exploration until it finishes by itself. More reports may be generated, as there are still orderings of the possible actions that have not been executed.
  3. The symbol coverage was less than 100%.
    Parts of the system have never been reached during the exploration. In this case, the validation cannot be considered finished, even if the exploration finished by itself. The reasons and possible solutions for low symbol coverage are discussed next.

Handling Low Symbol Coverage

If the symbol coverage after an exploration is 100%, all parts of the system have been executed at least once. If the symbol coverage is less than 100%, the possible reasons why parts of the state space have not been reached are listed below.

  • The exploration was manually stopped before all symbols were reached.
    In this simple case, you should continue the exploration until it finishes by itself.
  • The test values were inappropriate.
    Test values are used to define the set of possible signals from the environment. The automatically generated test values may not suit all SDL systems. This may for example cause the execution to never execute one branch of a decision statement. To overcome this problem, redefine the test values for the appropriate signal parameter. For more information on test values, see "Defining Signals from the Environment" .
  • The exploration was pruned after a report.
    In most cases the Validator will prune the exploration of a particular path as soon as a report has been found, i.e., the exploration will not continue beneath the state in question. If you have examined such a report and has decided not to do anything about it, the Validator will still prune the search when it finds the report the next time. To overcome this problem, change the report action for this particular report type from prune to continue. See "Configuring the Validator" for more information.
  • Some parts of the system are, in fact, unreachable.
    If some parts of the SDL system are not reachable at all, it may be an indication that there is a design error in the system.
  • There are problems with timer expirations.
    The validator is by default configured in a way that tries to reduce the size of the state space. It will always try to execute internal actions (e.g. tasks, decisions, internal input and outputs) before any timers are allowed to expire. The assumption is that the system will always execute fast enough to ensure that no timers will expire (the timers may of course expire when waiting for input from the environment). To make a more complete test of this type of situation, see "Using Advanced Validation" .
  • The search depth was too small.
    The default search depth is 100. This may not be enough for some systems, e.g. a system with a very long initialization phase. In some cases, it is possible to overcome this problem simply by increasing the search depth (see "Configuring the Validator" ). However, the techniques discussed in "Validating Large Systems" are often more suitable.
  • The state space is too big.
    Many SDL systems of reasonable complexity quite simply have state spaces that are too big; it is not possible to explore the entire state space in one exploration. Characteristic for this situation is a low symbol coverage, truncated paths, and either manually stopped exploration or a high (>10%) collision risk. This situation is discussed in "Validating Large Systems" .

To find out which parts of the system that have not been reached, a tool called the Coverage Viewer is used. To start the Coverage Viewer, select Show Coverage Viewer from the Commands menu, or enter the command Show-Coverage-Viewer. If the symbol coverage was less than 100%, the Coverage Viewer will display a tree structure representing the parts of the system that have not been executed.

Using Advanced Validation

The default options for the state space exploration, in particular the options that define the structure of the state space, are optimized to give good results for a first validation of a system. They are intended first of all to test for internal inconsistencies in the SDL system and to get a good process graph coverage. This assumes a reasonably "nice" environment, i.e., the environment only sends signals when nothing can happen internally in the system.

This has the benefit of reducing the size of the state space while still preserving a good process graph coverage. The drawback is that some error situations are never detected. One particular class of errors that never will be detected using the default options can be characterized as signal races caused by signals sent from the environment, or timer expirations that happen at the same time. An example is a situation where a communication protocol ends up in an inconsistent system state when two connect requests are sent to the different access points at the same time.

To detect these types of errors it is necessary to change the options and perform a second set of explorations for the SDL system. The suitable settings of the options are called advanced options. When using these values for the options, the state space will get very large for most SDL systems. It is thus usually not possible to get a complete coverage of the state space, even if some of the techniques described in "Validating Large Systems" have been used. To anyway be able to get good results, the best strategy is to use the random walk algorithm when exploring the state space. See "Using Random Walk Exploration" for more information.

To set advanced options, click the Advanced button in the Explore module. In stand-alone mode, you have to enter a number of commands to achieve the same result; see "Setting Advanced Options" for information on which commands to use.

For a more in-depth explanation of the state space options, see "State Space Options" .


Validating Large Systems

This section discusses various techniques that are useful when designing and validating large SDL systems. A large system is, in this context, a system that has a state space that is too large to be completely explored using one automatic state space exploration. The techniques are pragmatic and intended to give a reasonable chance of finding any errors even though the complete state space is not searched.

The following techniques are discussed:

  • Decomposed Exploration
  • Using MSCs to Limit the Search
  • More Efficient Bit-State Exploration
  • Reducing the State Space Size
  • Using Random Walk Exploration
  • Incremental Validation.

Decomposed Exploration

The idea when using decomposed explorations is to use a number of reasonably small explorations instead of one big exploration. Quite often the behavior of an SDL system can be divided into a number of "phases" or "features." The idea is to explore each of these phases or features separately. The benefit with this approach is that it is a lot easier to explore the different phases separately than trying to explore the combination of all phases. The drawback is that errors that are caused by an interaction between different phases or features are not found. However, for large SDL systems it is sometimes the only possible method that at least can give a complete symbol coverage.

The process of finding which and how many partial explorations that are necessary is a combination of an iterative process and a planning issue where the possible features and phases that can be subject to a partial exploration are identified. If an incremental design process is used it is often possible to use the different iterations to guide the choice of partial explorations; compare with "Incremental Validation" .

A common strategy used to find the needed partial explorations is essentially the following:

  1. Start an exploration from the system start state.
  2. Check all reports and correct the errors in the system. Generate a new validator and make another exploration.
  3. When all found reports have been fixed, check the symbol coverage. If the coverage is 100%, the validation is finished; otherwise, continue with the next step.
  4. Use the Coverage Viewer to check which parts of the SDL system that need more testing.
  5. Go to a suitable system state and start a new exploration from there.
  6. Repeat the process until the symbol coverage is 100%.

There are two issues of this strategy:

  • Where to start each partial exploration.
  • How to limit each partial exploration.

Where to Start a Partial Exploration

The problem of identifying where to start a new exploration is of course system dependent and requires knowledge of the SDL system. The tool to use in this case is the Coverage Viewer, which shows exactly what parts of the SDL system that have been executed during the exploration and what parts have not been executed. Once a system state has been chosen the next issue is how to get there in the Validator. There are number of possible ways to do this; see "Going to a System State" .

How to Limit a Partial Exploration

The next problem is to limit each partial exploration to the intended part of the state space. There exists a number of factors which can be used to influence the extent of an exploration:

  • The search depth
  • The signals from the environment
  • User-defined rules

The search depth is the simplest limiting factor to use. By reducing the search depth, e.g. to 10 or 20, the size of the exploration will of course be considerably reduced compared to the default depth of 100.

By changing the list of signals that can be sent from the environment it is possible to control which parts of the system that will be exercised by an exploration. For example, if we are interested in testing the data transfer phase of a connection-oriented protocol specification, a good strategy would be the following:

  • Go to a system state where the connection is established.
  • Define the signals from environment to be only the signals relevant for the data transfer, and start the exploration. For a description of how to define and remove signals from the list of signals that can be sent from the environment, see "Defining Signals from the Environment" .

User-defined rules also give a possibility to limit the extent of an exploration. Define a rule that matches the system states where the exploration should be pruned and check that the report action for user-defined rules is to prune the search. For example, the rule
state(initiator:1)=idle would prune the exploration whenever the initiator process entered the state Idle. User-defined rules are described in "Using User-Defined Rules" .

Using MSCs to Limit the Search

Another possibility that sometimes is useful to control the exploration of the state space is to use MSCs to guide the exploration. This is particularly useful for SDL systems with a design that uses restrictions on the possible behavior of the environment of the system. It might, for example, be known that the signals A, B and C always will come in this order from the environment of the system. In this case it is not interesting to analyze what will happen if the signals will come in a different order.

An MSC can be loaded to guide the search by using the command Load-MSC. Once an MSC is loaded, both interactive navigation in the state space, e.g. by using the Navigator, and automatic exploration will only search the parts of the state space that correspond to the loaded MSC.

This means that if you want to go back to normal exploration, you have to clear the loaded MSC by using the commands Clear-MSC or Reset.

Note how the test values are used when an MSC is loaded. It is allowed to leave out parameters to messages in the MSC. If a parameter is left out on a signal from the environment, the test values are used to determine the parameter values that are actually sent to the system. This is a useful feature when using MSCs to limit the search. See section "Verifying an MSC" for more details.

Another useful hint when using MSCs is to always use system level MSCs to guide the state space exploration. A system level MSC will allow a larger part of the state space to be explored than a block or process level MSC.

An MSC loaded into the Validator must comply with some requirements; see "Requirements for MSC Verification" .

More Efficient Bit-State Exploration

The bit-state search uses a hash value based algorithm to store the state space that is traversed. Unfortunately the computation of hash values from a system state is an expensive operation and most of the execution time in a bit-state search is spent calculating hash values. The execution time for the hash algorithm is in most situations proportional to the size of each system state. The max and min system state size used by the hash algorithm is included in the statistics printed after each bit state search and should be checked if the search is slow. (See "Bit-State-Exploration" ).

If the size of a system state is big (> 10,000 bytes) the bit state execution of the validator will be fairly slow. In these cases it might be worthwhile to try to optimize the performance by reducing the state size that the validator uses when computing hash values. This can be done by informing the validator to skip a number of variables when computing hash values. The validator includes a command Define-Variable-Mode that is intended for this purpose. (See "Define-Variable-Mode" .) For example the command:

define-variable-mode monitor subscrTab skip

will make the validator skip all subscrTab variables in monitor processes.

A typical example of where this feature is useful is if the system includes a big array (or other big data structure) that is initialized at the start up of the system and that after the initialization is known to be constant in the part of the state space that is explored. The correct way to take advantage of this in the validator is to:

  1. Go to a system state where the array is initialized. (See "Going to a System State" for more info about how to navigate in the state space.)
  2. Redefine the root to the current state. (See "Define-Root" .)
  3. Change the mode of the table variable to "Skip".
  4. Start the bit-state exploration.

Using this strategy it is possible to considerably increase the performance of the validator.

Another situation where the variable mode can be changed to "Skip" is when there are variables in the system that is known not to have any influence on the dynamic behavior of the system. See "Variables Not Influencing the Dynamic Behavior" .

Reducing the State Space Size

There is a number of ways to reduce the state space that is necessary to explore by using knowledge and assumptions about the SDL system. Usually this is based on the fact that the state space of an SDL system contains various "sub state spaces" that are equivalent except for some detail, which is not very interesting for the purpose of the validation. Some examples of such details are:

  • The value of local variables
  • The number of instances of process types
  • The size of large data structures.
  • Variables that do not influence the dynamic behavior.

Local Variable Values

An example of the way local variable values influence the size of the state space is the following: Consider a situation where a process contains an integer variable that counts the number of times a particular signal comes from the environment, and then replies with this number when requested to do so from the environment. It is obviously not especially interesting to try to investigate the behavior of the SDL system for all possible values of this local variable. Instead a reasonable set of values should be selected and the state space exploration guided by this selection.

A user-defined rule (see "Using User-Defined Rules" ) provides an efficient means to reduce the size of the state space by putting restrictions on variable values. In the example above a reasonable restriction might be that we only would like check what happens the first three times the variable is increased. A rule that expresses this is:

proc:1->var < 4;

Once this rule is defined and the report action for user-defined rule violation is set to Prune (which is the default), only the interesting parts of the state space are explored.

Number of Process Instances

Another issue is the number of process instances that are used for each process type. If the number is large and all of them do the same thing, for example by modeling different connections in a connection oriented protocol, it is probably not very useful to try to explore the combination of all instances. Instead, it is better to restrict the number of instances allowed in the exploration. This can be achieved with the command Define-Max-Instance (see "Maximum Number of Instances" ). If preferred, it is also possible to use a user-defined rule or an observer process to achieve the same result.

Size of Large Data Structures

A third area where the validator performance is reduced is when large data structures, e.g. arrays, are used in the SDL system. A large data structure has two unfavorable effects on a state space exploration:

  • The size of the reachable state space increases extremely rapidly as the size of the data structure increases.
  • The efficiency of the bit state algorithm is decreased as the size of system states increase. Essentially the time to compute a new system state is linear to the size of the system states.

A good idea in this context is to, whenever possible, try to reduce the size of any large data structures in the SDL system before performing validation. Another possibility is to skip the variable when computing hash values as described in "More Efficient Bit-State Exploration" .

Variables Not Influencing the Dynamic Behavior

In many situations an SDL system contains a number of variables that does not have any impact on the dynamic behavior of the system. Essentially all variables that does not (directly or indirectly) have any influence on the path taken through a decision or the expression used when computing the receiver of a signal in output/RPC call will not influence the dynamic behavior of the system.

These variables can safely be ignored when performing a state space search. This can be accomplished by instructing the validator to skip these variables using the Define-Variable-Mode command. (See "Define-Variable-Mode" .) This will in many cases drastically reduce the size of the state space that the validator needs to search and is an efficient way to improve the performance of the validator.

Note that implicit variables like Sender/Parent/Offspring are also considered as variables in this respect. In particular Sender can be of interest to skip if it is not used, since it may change value every time a signal is received.

As an example, if Sender is not used in a process `p' the following command will make the validator ignore the Sender implicit variable when comparing two system states:

define-variable-mode p Sender skip

Using Random Walk Exploration

In some situations it is not possible to use the more elaborated techniques described in this section to cope with the problem of validating large SDL systems. The time and resources available for the validation may simply be too limited. A possible strategy to use when validating very large SDL systems is to use the random walk exploration strategy instead of the bit state algorithm.

The reason is that the random walk algorithm gives a possibility to get a partial exploration of the state space that is randomly chosen. Furthermore, the symbol coverage of the exploration is determined only by how long the exploration is allowed to run. The drawback with the algorithm is that if it is allowed to run for a long time, so that significant parts of the state space already have been covered, there is no mechanism to avoid that already explored paths are explored once more.

How to start a random walk exploration is described in "Executing an Exploration" . The random walk exploration algorithm is further described in "Random Walk Options" .

The best way to get an idea of what has been tested when using random walk is to use the Coverage Viewer to check the symbol coverage. Even if this is not the same as the coverage of the system state space, it will show if there are large portions of the system that have not been reached by the exploration.

Incremental Validation

A common way to develop large SDL specifications and designs in practice is to use an incremental development strategy. First a base functionality is implemented and then various features are added in an incremental fashion. When this type of development process is used, a good way to plan the validation of the system is to let the different increments define the state space explorations that should be performed.

First a number of state space explorations are executed with different start states, and perhaps different test values. Together these explorations should give a good process graph coverage of the SDL system representing the base functionality.

For each increment that is added, a number of additional explorations is performed that will cover the new features in the SDL system.

It is also probably worthwhile to define command scripts that automatically can execute the various explorations that should be run to achieve a good process graph coverage. This makes it possible to run all of the various explorations in an straight-forward way for each new increment that is added to the system.


Verifying an MSC

MSC verification is one the major application areas for the SDL Validator. This section describes how to use the Validator to get started with MSC verification. It also gives some ideas of how to organize MSCs to be able to use common initialization MSCs and shows how to use batch files to achieve an efficient regression testing of an SDL system using MSC verification.

The first prerequisite for MSC verification is of course that we have an MSC that describes some desirable behavior that can be used to check the SDL system against. This MSC can be interactively created using the MSC Editor as part of a requirement analysis, but it is also possible to use MSCs created as execution traces in the SDL Simulator or the Validator itself as input to the MSC verification.

It is worth noticing that the MSC does not have to be a process level MSC. It is possible to use MSCs where the MSC instances correspond to SDL blocks and systems, and even mixed MSCs where some instances correspond to processes and other to blocks.

There are some requirements on MSCs to be used for MSC verification; see "Requirements for MSC Verification" .

The characteristics of the MSC verification algorithm is further described in "MSC Verification Options" .

Basic MSC Verification

To verify an MSC for a system opened in the Validator:

  1. If necessary, go to a system state that corresponds to the start of the MSC to verify. If the MSC describes events from the start of the system, go to the system start state. You may have to reset the validator first, especially if you already have an MSC loaded.
  2. To start the MSC Verification, click the Verify MSC button in the Explore module, or enter the command Verify-MSC.
  3. The MSC that you want to verify has to be specified. Either select it in the File Selection Dialog that appears (in graphical mode), or enter the name of the file on the command line (in stand-alone mode).

Note: Illegal characters in path name

Please note that verifying an MSC fails if the path name of the MSC contains "(" or ")".

  4. A bit state exploration adapted to suit MSC verification is performed. After the exploration statistics, the result of the MSC verification is presented. If it was possible to find an execution trace that was consistent with the MSC, the text
** MSC <MSC name> verified **
is printed, where <MSC name> is the name of the MSC that was checked. If it was not possible to find a consistent execution trace, the following text is printed:
** MSC <MSC name> NOT VERIFIED **

  5. If the MSC was not verified, check the generated reports using the Report Viewer. There will be a number of "MSCViolation" reports. These reports identify the execution paths which violate the MSC, i.e., paths that contain events that are not part of the MSC. You may investigate these reports by using the method described in "Examining Reports" .
  6. If the MSC was successfully verified, there will be a
    "MSCVerification" report (there may also be a number of
    "MSCViolation" reports, but they can be discarded). You do not have to go to this report; the Validator automatically goes to the state where the MSC was verified. This means that the current path is set up automatically.
  7. To verify another MSC from the same start state, go to the top of the current path. It is now possible to directly start a new MSC verification, as described above (you do not have to reset the validator).

Note:

When MSC verification is started, the current root of the behavior tree is redefined to the current state. This feature is used in the next section, "Verifying a Combination of MSCs Using High-Level MSCs" . (It also means that you may have to reset the validator to be able to reach the system start state again.)

Converting Instances Before Verification

Before an MSC is loaded into the Validator for verification, it is possible to perform instance conversion of the MSC. Instance conversion will convert the name of an instance to another name.

This is useful if you want to verify some, but not all, instances in an MSC with an SDL system. For instance, you may have an MSC describing a complete system but an SDL system for only a part of the system. In this case, you can convert the not wanted instances to be considered as environment in the Validator, without changing the MSC.

Note that if you have more than one instance representing the environment, the environment instances must be separated using channel names.

Instance conversion is performed before an MSC is loaded into the Validator by entering the command "Define-Instance-Conversion FromString ToString" for each instance name to be converted. All instance conversions can be listed by entering the command List-Instance-Conversion, and all instance conversion can be cleared by entering the command Clear-Instance-Conversion.

Example 324

Consider an MSC with three process instances A, B and C. The SDL system specifies the behavior for instance A, but not for B or C. Before verifying the MSC, B can be converted to "channelB" and C to "channelC", where channelB is the existing SDL channel that will be used for communication between the existing A process and the non-existing process B, and channelC is the existing SDL channel that will be used for communication between the existing A process and the non-existing process C.

This is accomplished by entering the Validator commands:

Define-Instance-Conversion B "channelB"
Define-Instance-Conversion C "channelC"

The MSC can now be verified.

Verifying a Combination of MSCs Using High-Level MSCs

The high-level MSC that are available in MSC'96 provide a very convenient possibility to describe how many small MSCs are combined to form a larger use case or scenario. The Validator support verification of high-level MSCs.

As an example, consider a situation where we have an MSC "init" that will describe some initialization phase that is needed to set up the SDL system to some "connected" state from where two features are accessible. These features are described by the MSCs "datatrans" and "finish". If this would be a communication protocol, the "init" might be a connection establishment, and "datatrans" and "finish" successful data transfer and connection release. This situation could be described using the high-level MSC in Figure 480.

Figure 480 A high-level MSC

To check this combination of MSCs simply verify the "inres1" high-level MSC and the validator will generate one MSC verification report for each sequence of "leaf MSCs" that can be verified. In this case there will be reports for "init, finish", "init, datatrans, finish", "init, datatrans, datatrans, finish", etc. until the max depth for MSC verification has been reached.

State of the Validator after MSC Verification

When an MSC verification has been done, the current state of the validator is different depending on how many MSC verification reports has been found:

  • If 0 or more than 1 MSC verification report has been generated the current state of the validator is the system state where the MSC verification was started from.
  • If exactly 1 MSC verification report was generated the current state is the state where this report was found.

This is in many cases useful when using MSCs to navigate to a specific system state, especially in combination with command scripts as described in the next section. Note that if the MSC that is verified is an "old style" MSC without high-level MSCs or MSC reference expressions then there will always be at most one MSC verification report and this type of MSCs is thus best when using MSCs for navigation.

Using Batch MSC Verification

An efficient test strategy when incrementally developing SDL systems is to use regression testing. A set of MSCs describe the requirements on the SDL system and new MSCs are incrementally added to the set when new features are implemented in the SDL system. Each time a new feature is implemented the resulting system should be tested against all the old MSCs as well as the new ones, to make sure that no new errors have been introduced.

To accomplish this using the Validator the most efficient way is to use the command script facility in the Validator. A command script is simply a text file containing a number of Validator commands, usually one command per line. A command file can be loaded into the Validator by selecting Include Command Script from the Tools menu, or by entering the command Include-File.

Example 325 : Batch MSC Verification

A command script that when loaded will perform MSC verification for some requirements described as MSCs may look like:

log-on msc.log
verify-msc inres1.mrm
reset
verify-msc init2.msc
verify-msc inres2.mrm
quit

The command Log-On is used to store the output from the verification on the file msc.log.

Note in Example 325 how the MSC init2 was used to set up the start state for the verification of the high-level MSC inres2.

Verifying Message Parameters

When verifying an MSC, the parameters of the messages in the MSC can sometimes be crucial and need to be verified, and sometimes be unimportant for the behavior in question. To support this, the verification of MSCs in the Validator allows three different levels of matching of message parameters:

  • No parameters are given for the message.
  • Only some of the parameters are given.
  • All of the parameters are given.

If no parameters are given, all possible actual parameters are accepted. If the signal is sent from the environment to the system, the parameter values that are defined using the test value facility are used by the Validator when exploring the state space of the system.

When only some of the parameters are to be given, only the given parameters are checked during the exploration. The notation used to show that a specific parameter should be ignored during the verification is to simply leave out this parameter in the parameter list. For example, if only the second and fifth parameter should be used during the verification the parameter list would be ",2,,,true" in the MSC. Trailing commas can be left out, so if a signal has five parameters and only the first two are to be verified, the parameter list might be "1,2" which would ignore the last three parameters.

When only some of the parameters are given for a signal from the environment, the rest of the parameters are taken from the test value definitions when executing the signal output during state space exploration.

If all parameters are given, they are of course all checked.

Requirements for MSC Verification

The MSCs that can be loaded into the Validator must comply with the following rules:

  • It must be possible to map each MSC instance to either the environment, a channel to/from the environment, the entire SDL system, a block, or a process. This mapping is done by matching the name of the MSC instance with the names of the corresponding SDL entities. However, the name of an MSC instance can be changed before verification, see "Converting Instances Before Verification" .
  • PId values are not allowed as parameters to MSC messages from the environment of the SDL system. PId values are allowed on internal messages and messages to the environment, but the values are not checked during the exploration.
  • If the MSC is on process level, only one static instance of each process type is allowed in the MSC. There is no limit to the number of dynamically created MSC instances.
  • Only the following events/symbols are interpreted in an old-style MSC. All other events are ignored or will not be accepted by the Validator.
    • input
    • output
    • set
    • reset
    • timeout
    • create
    • stop
    • global MSC reference symbol without substitution and gates
    • condition

Note:

Conditions are interpreted as a synchronization point if Define-Condition-Check is set to "on", otherwise they are ignored. For more information, see "Synchronizing Test Events with Conditions" . Set, reset and timeout events on MSC instances representing SDL channels to the environment are only accepted by the Autolink test generation commands Generate-Test-Case and Translate-MSC-Into-Test-Case. For all other Validator commands which load an MSC, timer events on environment instances are ignored and the Validator generates a warning.

  • Only the following symbols are allowed in a high level MSC:
    • start symbol
    • end symbol
    • MSC reference symbol without substitution and gates.
    • condition symbol (ignored during verification)
    • connection point.
  • In MSC reference symbols it is allowed to use MSC reference expressions with the operators:
    • alt
    • par
    • seq
    • exc
    • opt
    • loop


Using Observer Processes

The purpose of an observer process is to make it possible to check more complex requirements on the SDL system than can be expressed using MSCs. The basic idea is to use SDL processes (called observer processes) to describe the requirements that is to be tested and then include these processes in the SDL system. Typical application areas include feature interaction analysis and safety-critical systems.

To be useful, the observer processes must be able to inspect the SDL system without interfering with it and also generate reports that convey the success or failure of whatever they are checking.

To accomplish this, three features are included in the Validator:

  • The observer process mechanism.
    By defining processes to be observer processes, the Validator will start to execute in a two-step fashion. First, the rest of the SDL system will execute one transition, and then all observer processes will execute one transition and check the new system state.
  • The assert mechanism.
    The assert mechanism enables the observer processes to generate reports during state space exploration. These reports will show up in the list of generated reports in the Report Viewer. The details of the assertion mechanism is discussed in "Using Assertions" .
  • The Access abstract data type.
    The purpose of the Access abstract data type is to give the observer processes a possibility to examine the internal states of the other processes in the system. Using the Access ADT it is possible to check variable values, contents of queues, etc., without any need to modify the observed processes. See "The Access Abstract Data Type" for more details.

A simple observer process is illustrated in Figure 481.

Figure 481 : A simple observer process

This process will check if the variable Counter in the Initiator process ever becomes equal to 2.

Two characteristics for the observer processes are:

  • the use of continuous signals with tests that use Access operator to check the internal state of other processes, and
  • the use of assertions to report the result.

To use observer processes:

  1. Create the observer processes in the SDL Editor. You should place the observer processes in a special block that you include in the diagram structure of the SDL system. In this block, you also need to specify an INCLUDE directive for the Access ADT:
/*#INCLUDE `access.pr' */

  2. In the generated validator, define each observer process by using the command Define-Observer, followed by the name of the process type. All instances of the process type will now become observer processes.
  3. Perform a state space exploration. If an assertion defined in an observer process is satisfied, an "Assertion" report is generated. To simplify the observer processes, an "Observer" report will also be generated whenever there is an observer process that cannot execute.

In some cases the Observer reports are not convenient and they can then be turned off with the Define-Report-Continue (that will cause the exploration to continue past a reported situation) and the Define-Report-Log command (that can be used to turn off the logging a s specific report type, e.g. Observer reports)

The Access Abstract Data Type

The Access abstract data type is an ADT intended to be used together with observer processes to make it possible to access the internal state of other processes from an observer process. The ADT is defined in the file access.pr that resides in the ADT directory together with the rest of the ADTs supplied together with the SDL suite. Unlike the rest of the ADTs the Access ADT is a special purpose ADT that only works with the Validator kernel.

The Access ADT defines a number of SDL operators. The signatures of these operators are defined as follows:

GetPID : CharString, integer -> PId;
/* Returns the PId value of a process instance

par 1: the name of the process type
par 2: instance number of the process instance
*/

ActivePID : integer -> PId;
/* Return the PId of the process that executes.
Returns NULL if no process executes.
Observer processes are not taken into account.

The integer parameter is a dummy parameter
needed since operators must have parameters. */

GetState : PId -> CharString;
/* Returns the name of the current state of a
process instance (or previous if the process
is not in a state)

par 1: the pid of the process instance */

GetNoOfInst: charstring -> integer;
/* Returns the number of instances for a
particular process type

par 1: the name of the process type */

terminated: PId -> boolean;
/* Returns true if the process instance is
terminated otherwise false

par 1: The PId value of the process instance */

GetProcedure: PId -> charstring;
/* Returns the name of the procecure a process
instance currently has called. If no procedure
is called `none' is returned

par 1: The PId value of the process instance */

InProcedure: PId, CharString -> boolean;
/* Returns true if a process instance currently
executes in a specific procedure, otherwise
false

par 1: The PId value of the process instance
par 2: The name of the procedure */

GetNoOfSignals: PID -> integer;
/* Returns the number of signals currently in the
input port of a process.

par 1: The PId value of the process instance */

GetSignalType: PId, integer -> charstring;
/* Returns the name of the signal type for a
signal in the input port of a process instance

par 1: The PId value of the process instance.
par 2: A number (>=1) identifying the signal */

InQueue: PId, charstring -> boolean;
/* Returns true if a process instance currently
has a signal of a specific type in its input
port queue

par 1: The PId value of the process instance.
par 2: The name of the signal type. */

/* Variable access functions. These functions return
a variable value that corresponds to one of the
variables of a process instance as specified by
the parameters.

par 1: The PId value of the process instance.
par 2: Variable name */

v : PId, charstring -> integer;
vInteger : PId, charstring -> integer;
v : PId, charstring -> real;
vReal : PId, charstring -> real;
v : PId, charstring -> boolean;
vBoolean : PId, charstring -> boolean;
v : PId, charstring -> Character;
vCharacter : PId, charstring -> Character;
v : PId, charstring -> Time;
vTime : PId, charstring -> Time;
v : PId, charstring -> Duration;
vDuration : PId, charstring -> Duration;
v : PId, charstring -> Charstring;
vCharstring : PId, charstring -> Charstring;
v : PId, charstring -> PId;
vPId : PId, charstring -> PId;

EnvOutput : CharString -> Boolean;
/* Returns true if the transition currently
executing is caused by a signal from the
environment with a specified name, otherwise
false

par 1: The name of the signal type */

The Access ADT also includes a utility procedure called Report that if called from an observer process will generate an Assertion report in the validator. The procedure takes a charstring as parameter and this is the string that will be presented in the Assertion report.

An example of the usage of some of the operators is:

P := GetPId( `Initiator', 1 ),
CS := GetState( P )

This example assigns the PId value of the first Initiator process to the PId variable P, and then assigns the name of the state of this process to the charstring variable CS.

An example of a statement that will access the variable value for one of the variables of another process instance is:

LocalVar := v(P,'Var')

In this example we assume that we have a PId variable P that identifies a process that has a variable Var of type for which a v operator is defined. The statement will access the value of Var and assign it to the local variable LocalVar.

The operators for accessing the value of a variable are given in two versions for each predefined simple type: the v operator and the vXXX operator, where XXX is the name of the type. They are equivalent and the only time there is a need to use the vXXX operator is when it is not possible to resolve by context which of the v operators that is intended.

To access variables of sorts that are syntypes to the predefined simple types, the v operator for the corresponding predefined simple type can be used.

Accessing variable of structured types, enumeration types and user-defined types is a bit more complex. There are two possible ways to do it. Either define the v operator for the type in question, or use the #CODE operator and access the variable value using a C macro XVV.

Example 326 : Structured Types in Observer Processes

Consider the following structure definition:

newtype MSDUType
struct
id IPDUType;
num Sequencenumber;
data ISDUType;
endnewtype MSDUType;

A v operator for this type can be defined as:

newtype MSDUTypeAccess
literals NotUsedMSDUTypeAccess;
operators
v /*#NAME 'XVNAME(MSDUType)'*/ :
PId, charstring -> MSDUType;
/*#ADT (H)
#TYPE
#define MSDUType #SDL(MSDUType)
*/
endnewtype MSDUTypeAccess;

Once this definition is in place, variable values for the complex data type can conveniently be accessed using the new v operator. Note also that it is possible to access the values of the fields of the structure in a simple way:

LocalVar := v(P,'MSDUVar')!id

If the type is one of the types passed as values, according to the table in "Parameter Passing to Operators" , XVNAME should be substituted to XVNAME2.

However, if the values of the complex type only is accessed in a few places, it is possible to access them directly using the #CODE operator as illustrated in the following example:

LocalVar := #CODE(`XVV(#SDL(P),"Var",#SDL(MyType))')

In this example we assume that we have a PId variable P that identifies a process that has a variable Var of type MyType. The statement will access the value of Var and assign it to the local variable LocalVar.


Defining Signals from the Environment

A problem common to all state space exploration techniques is related to the treatment of the environment of the SDL system under analysis. As an example, consider the situation during state space exploration where a signal with an integer parameter can be received from the environment. Since there is an infinite number of integer values, there will be an infinite number of successors of the current system state: one where the parameter value is 0, one where the parameter value is 1, etc.

This is obviously a situation that is not acceptable when performing state space exploration. The SDL Validator allows three different strategies to avoid situations like this:

  1. Create a closed system by specifying the environment of the system using SDL. This will solve the problem but introduces a new one; it is necessary to create an SDL model of the environment.
  2. Specify the signals that can be sent from the environment to the system. This is a simple way to avoid the problem. By enumerating the signals with their parameters that the environment can send, a finite branching is guaranteed at each system state in the state space.
  3. Use an MSC to guide the state space exploration. Since the MSC defines what signals the environment can send and their ordering, a limited part of the state space can be explored.

The second strategy is the most common and the test value feature of the Validator is designed to make it easy to define the signals from the environment.

Test Values

When the Validator is started a list of signals is automatically computed that will be used as the possible signals from the environment during state space exploration. The signal list is generated based on the concept of test values. Test values can be defined for data types and for signal parameters. When generating the signal list the Validator checks for each signal that can come from the environment which test values are defined for its parameters (or for the parameter data types). It then generates one signal instance for each combination of test values for the parameters.

Each time the Validator is in a state where input from the environment is possible during state space exploration, the list of signals defined by the test values is consulted.

The default test values for the simple data types are:

Data Type
Default Test Values

 Integer
-55, 0, 55

 Boolean
true, false

 Real
-55, 0, 55

 Natural
0, 55

 Character
`a'

 Charstring
"test"

 Duration
0

 Time
0

 PId
Environment PId

 Bit
0, 1

 Octet
00, FF

 Bit_string
'01'B

 Octet_string
'00FF'H

For other data types, test values are determined according to the following:

  • Enumerated types: All values in the type
  • Subranges of the predefined data types: All values in the range
  • Structures: All combinations of the test values of the individual fields
  • Arrays: All combinations of the test values of the component type.
  • Ref types: NULL + pointers to the test values for whatever the Ref points to.
  • Own types: NULL
  • ORef types: NULL

Test Values Restrictions and Options

Two restrictions are posed on the computed test values:

  • If the number of test values for a data type or signal parameter exceeds a maximum number, randomly chosen test values will be generated.
  • If the number of signal instances for a particular signal type exceeds a maximum number, randomly chosen signal instances will be generated for this signal type.

Two commands exist for setting options related to the above restrictions:

  • To define the maximum number of test values for any data type or signal parameter, enter the command Define-Max-Test-Values, followed by the number of test values. The default is 10.
  • To define the maximum number of signal instances for any signal type, enter the command Define-Max-Signal-Definitions, followed by the number of signal instances. The default is 10.

Note:

These options affect the state space; see "Affecting the State Space" .

Defining and Listing Test Values

The default test values are defined to be useful for a large number of applications, but they sometimes need to be modified. In some cases there are unnecessarily many test values and to enhance the performance of the state space exploration some test values can be cleared. In other cases the automatic test value generation cannot handle some of the data types used, so the test values must be manually defined.

Changing the test values are therefore only needed if you would like to fine-tune the behavior of the Validator, or if the signals from the environment have parameters that are of a user-defined or unusual data type.

Note:

Changing test values affects the state space; see "Affecting the State Space" .

Test values can be defined and cleared on three "levels": on data types, on individual signal parameters, and on signal instances. When test values are defined or cleared, the list of signals from the environment is regenerated. You are recommended to define test values either on data types and individual signal parameters, or on signal instances; do not combine both these methods.

The monitor commands concerning test values are available in the Test Values module in the Validator UI.

Test Values for Data Types

The following commands operate on the test values for a data type (sort).

  • To define a new test value for a sort, enter the command
    , or click the Def Value button. The parameters are the sort and the value. Example:
integer 20

  • To list the new test values defined for all sorts, enter the command List-Test-Values, or click the List Value button.
  • To clear all test values for a sort, enter the command
    Clear-Test-Values, or click the Clear Value button. As parameter, you either specify the sort, or `-' which means all sorts.

Test Values for Signal Parameters

The following commands operate on the test values for individual parameters to a signal.

  • To define a new test value for a signal parameter, enter the command Define-Parameter-Test-Value, or click the Def Par button. The parameters are the signal, the ordinal number of the signal parameter, and the value. Example:
Define-Parameter-Test-Value Score 1 -5

  • To list the new test values defined for all signal parameters, enter the command List-Parameter-Test-Values, or click the List Par button.
  • To clear all test values for a signal parameter, enter the command
    Clear-Parameter-Test-Values, or click the Clear Par button. As parameter, you specify the signal and the ordinal number of the signal parameter. You may use `-' for the parameter number, which means all signal parameters, or just `-' for the signal, which means all signal parameters for all signals.

Test Values for Signal Instances

The following commands operate on the test values for a specific signal instance.

  • To define a new set of test values for a signal instance, enter the command Define-Signal, or click the Def Signal button. The parameters are the signal and an optional set of values for the parameters. Multiple Define-Signal commands may be used to define several signal instances of the same signal type, but with different values. Example:
Define-Signal Test 10 'hello' true
Define-Signal Test -5 'bye'

Note:

The signals defined using this command are cleared when the signal list is regenerated, e.g. if a test value is defined for a sort or a signal parameter.

  • The command Extract-Signal-Definitions-From-MSC analyzes basic MSCs in textual form (with suffix .mpr) and extracts all signals sent from the environment axes to the system axis. If a signal definition is found which does not already exist, it is added automatically by calling Define-Signal.
  • To list all currently defined signal instances, enter the command List-Signal-Definitions, or click the List Signal button.
  • To clear all test values for a signal type, enter the command
    Clear-Signal-Definitions, or click the Clear Signal button. As parameter, you specify the signal, or `-' which means all signals.

Saving Test Values

The current set of test values can be saved on file and later be recreated by reading in the file again. The file will contain monitor commands that recreates the saved set of test values and discards any other test values.

To save the test values, enter the command Save-Test-Values, followed by a file name. To read in the saved test values again, enter the command Include-File, followed by the file name.


Validating Systems That Use the Ref Generator

The Ref generator (see "The Ref Generator) is used to create pointer structures to be used in SDL systems. The Validator supports the Ref generator, but imposes some restrictions on the usage of it due to the special requirements caused by state space exploration.

Variables that are defined to be Ref's to something can be used in two ways, either as a pointer to some other variable or as a pointer to a dynamically allocated memory area. Both ways of using Ref types are supported by the Validator.

To handle dynamically allocated data areas the Validator creates a special data structure as part of each system state. This data structure is a list of all data areas allocated by Alloc (the Ref operator that allocates a new data area) and data areas allocated in external C code (see "Validating Systems with External C Code" ). The list contains for each data area in addition to the area itself information about e.g. the sort of the data area and the size of the data area. Whenever the Validator copies a system state, the list of dynamically allocated data areas is also copied and all Ref variables are set up corresponding to the new copy of the list.

Some restrictions/simplifications are needed when using Ref sorts in the Validator:

  • Variables may not be defined to be of the VoidStar or VoidStarStar sorts, since the Validator needs to know the sort and size of what is pointed to. This is not known for VoidStar and VoidStarStar sorts.
  • A simplification is made when comparing two system states for equivalence (both in exhaustive exploration and in the hash function used by bit state exploration): Two Ref variables are considered equivalent if the data they are pointing to are equivalent. This may in some cases prune the search in situations where it should not have been pruned. Note that equivalence tests in the SDL system works correctly, if two Ref variables are compared using `=' they are considered the same only if they contain the same pointer value.

Note that the handling of pointers in the Validator introduces a significant overhead that unfortunately reduces the number of transitions per second that is executed by the Validator.

When performing state space exploration, the Validator checks the usage of Ref variables when copying system states and reports several different types of problems including:

  • memory leaks, and
  • pointers to released or never allocated memory.

For more information about the reports see "REF Errors" .


Validating Systems with External C Code

the SDL suite allows the usage of external C code together with an SDL system and this is also true for the Validator. In many cases it is possible to directly use the Validator on a system that uses external C code. However, due to the special requirements of state space exploration, some restrictions must hold for the external C code, and some modifications may have to be done to the external code to make it functions properly with the Validator.

To be able to perform a state space exploration it must be possible for the Validator to make a complete copy of a system state, including all data structures that are implemented directly in C code. The Validator must also be able to modify each copy of a system state separately. This has some implications:

  • variables defined in C code cannot be handled by the Validator,
  • C unions may not contain pointers, data types implemented by pointers (like the SDL types string and bag) or SDL PIds, and
  • some restrictions on the usage of pointers are needed since the C pointers in SDL are treated like Ref types (see "Validating Systems That Use the Ref Generator" ).

If there are variables in C code, this will not be detected by the validator. It may appear as if the Validator works, but the variables defined in C code will not be copied when the Validator copies a system state. When the value of a variable is changed by an action performed in one system state, this value will change the value for all system states that the Validator currently handles. This implies e.g. that when the Validator backtracks during an automatic exploration to test more possible successors of a particular system state, the values of variables defined in C may be different from the values they had the previous time the system state was visited and the state space exploration will not be correct.

In order to be able to copy a system state, the Validator must have exact information about the sort of all data areas in the system to be able to copy e.g. pointer-based data structures correctly. One consequence of this is that the Validator cannot support the C union sort if the union may contain pointer-based sorts, since the Validator cannot know the current sort of the union and thus cannot deduce whether to treat the union as a pointer or not. SDL PIds are also treated specially in the Validator and can also not be part of a C union.

Pointers are frequently used in C code and when used together with the SDL suite they are treated as the (nonstandard) SDL type Ref. The Validator handles the Ref types in a particular way (see "Validating Systems That Use the Ref Generator" ) and the restrictions on variables of this sort also applies to the usage of C pointers in data type in external C code.

When using dynamic memory allocation in extern C code some special additions are needed for the Validator to work properly. This is needed since the Validator keeps a list of all dynamically allocated data areas as part of each system state. If an external C function allocates memory, the Validator must be informed about the data area that was allocated, and the same holds when a C function releases memory. This is accomplished by calling two functions from the C code:

extern void UserMalloc (void *data);
extern void UserFree (void *data);

UserMalloc should be called when a data area has been allocated, and UserFree should be called immediately before the data area is released. Both functions should have a pointer to the data area as parameter.

The purpose of UserMalloc is to insert a new element into the list of dynamically allocated data areas that is maintained by the Validator. Note that there is no need to tell the Validator what sort of data was allocated or its size. This is handled automatically by the Validator simply by finding the SDL entity (e.g. a variable) that points at the data area and assuming that the sort and size given by this entity is correct. If no SDL entity can be found that points to the data area, this is considered to be an error and a Validator report is generated.

The purpose of the UserFree function is to inform the Validator that a data area has been released, and thus should be removed from the list of dynamically allocated data areas.

There exists a special C macro XVALIDATOR_LIB that can be used to check in external C files if the code is compiled together with the Validator kernel. It is thus possible to only include the calls to UserMalloc/UserFree when the C code is compiled together with the Validator using this macro, as in the following example:

...
v = malloc( 10 );
#ifdef XVALIDATOR_LIB
UserMalloc( (void *)v );
#endif


Using User-Defined Rules

In the Validator, you may define a user-defined rule to be used during state space exploration to check for properties of the encountered system states. If a system state is found for which the user-defined rule is true, a report will be generated. Note that only one user-defined rule may be defined at a time.

Different Usages

There are three different situations in which a user-defined rule is useful:

  • To verify properties of the SDL system.
    A user-defined rule describes properties of system states. By using an automatic state space exploration, it is thus possible to verify the existence of system states that satisfy the specified properties. If the state space is small enough to allow a complete exploration it is also possible to verify that the state space does not contain any system state with the specified property.
  • To search for specific system states.
    A user-defined rule makes it possible to go to a specific system state in the state space without the need to use the navigating commands of the validator monitor. By describing the desired state with a rule and using an automatic state space exploration, you can go directly to the report that satisfied the rule. In this case, the report action for the user-defined rule report should be set to Abort.
  • To reduce the state space to be explored.
    For many SDL systems, the state space can be very large or even infinite, which makes it difficult to perform a state space exploration effectively. However, in many cases the state space contains large subspaces that for some reason are not interesting to explore. For instance, they may be equivalent to other parts of the state space except for the value of one particular variable. In such cases, a user-defined rule can be used to restrict the exploration by defining system states that are considered to be uninteresting. When such a state is encountered, the exploration is truncated and continued in another node.

Examples of Rules

An example of a rule that checks a system property is:

exists P:Proc | P->var=12;

which is true for all system states where there exists a process of type "Proc" with a variable "var" that is equal to 12.

A simple example of a rule that searches for a system state is:

state(initiator:1)=disconnected;

which is true for all system states where the process instance
"initiator:1" is in the state "disconnected".

A more complex example of such a rule is:

state(Game:1)=Winning and sitype(signal(Game:1))=Probe

which is true for all system states where the state of the process instance "Game:1" is equal to "Winning" and the type of signal to be consumed by the same process instance is "Probe".

An example of a rule that reduces the state space is:

(Game:1->Count > 2) or (Game:1->Count < -2)

which is true for all system states where the absolute value of the variable "Count" in the process instance "Game:1" is greater than 2.

For a full description of the features and syntax of user-defined rules, see "User-Defined Rules" .

Managing User-Defined Rules

To define the user-defined rule, select Define Rule from the Commands menu, or enter the command Define-Rule, followed by the definition of the rule.

To clear the user-defined rule, enter the command Clear-Rule.

To print the definition of the current user-defined rule, enter the command Print-Rule.

To evaluate the user-defined rule in the current system state, i.e. to check whether the rule is satisfied, enter the command Evaluate-Rule.


Using Assertions

Like most other run-time libraries to the SDL to C Compiler, the Validator library gives the user a possibility to define his own run-time errors or assertions. An assertion is a test that is performed at run-time, for example to check that the value of a specific variable is within the expected range. Assertions are described by introducing #CODE directives with calls to the C function xAssertError in a TASK. See the following example.

Example 327 : Assertion in C Code

TASK '' /*#CODE
#ifdef XASSERT
if (#(I) < #(K))
xAssertError("I is less than K");
#endif
*/ ;

In the SDL Validator, the assertions are checked during state space exploration. Whenever xAssertError is called during the execution of a transition, a report is generated. The advantage of using this way to define assertions, as opposed to using user-defined rules, is that in-line assertions are computed much more efficiently by the validator than the user-defined rules.

The xAssertError function, which has the following prototype:

extern void xAssertError ( char *Descr )

takes a string describing the assertion as parameter and will produce an SDL run-time error similar to the normal run-time errors. The function is only available if the compilation switch XASSERT is defined. For the standard libraries this is true for all libraries except the Application Library.


Configuring the Validator

This section describe the various possibilities available to control the behavior of the Validator using the options that can be defined for different features. The available options are grouped into a number of categories; each category and option will be described later in this section.

Managing Options

Each option can be set using a monitor command, usually named something similar to "Define-<option>". Most options can also be set from the menus Options1 and Options2 in the Validator UI. The monitor command and menu choice associated with an option is listed together with the description of the option.

If the options are changed during a session with the Validator, you will be asked whether to save the options when you exit or restart the currently executing validator. If you save the options, the new values will be stored in a file named .valinit (on UNIX), or valinit.com (in Windows), in the directory from where the SDL suite was started. This file will automatically be loaded the next time the Validator is started from the same directory, thus restoring the previous options.

Some monitor commands operate on all the options:

  • To print a list of all options and their current values, select
    Show Options from either the Options1 or Options2 menu, or enter the command Show-Options. (A few of the options described here are not listed.)
  • To set all options to their predefined default values, click the
    Default button in the Explore module, or enter the command
    Default-Options. Note that this also clears all reports.
  • To set all options to their initial values, i.e. the values set when the validator was started, click the Reset button in the Explore module, or enter the command Reset.

Note:

This command also resets the validator completely and is equivalent to restarting the validator from scratch. To just set the options to their initial values without resetting the validator:
  1. Set the options to their default values. See above.
  2. Read in the file .valinit (on UNIX), or valinit.com (in Windows); see above. Select Include Command Script from the Commands menu, or enter the command Include-File.

Affecting the State Space

Some of the options affect, directly or indirectly, the size of the state space and the structure of the behavior tree. This can only be done while being in the current root of the behavior tree, since the whole structure of the tree may be affected. If such an option is changed when the validator is not in the current root of the behavior tree, you have two choices: either to change the current system state back to the current root, or to redefine the current root to the current system state.

In this case, the following dialog is opened:

Figure 482 : Changing the current root

To change the root to the current system state, select yes and click OK. (In stand-alone mode, enter yes)

To keep the current root and move back to it, select no and click OK. (In stand-alone mode, enter no)

Note:

It is not possible to cancel this operation, i.e. you have to either change the current root or the current system state.

Bit State Exploration Options

Bit state exploration is an efficient automatic state space exploration algorithm for reasonably large SDL systems (for a reference, see [16]). It performs a depth-first search through the state space and uses a bit array to store the states that has been traversed during the search.

Every time a new system state is generated during the search, two hash values are computed from the system state. The bit array is checked:

  • If both of the positions indicated by the hash values are already set, the state is considered to have been previously visited. The search of this particular path in the state space is pruned, and the search backs up to a previous system state and continues elsewhere.
  • If both of the positions are not set, the state is a new state that has not been previously visited. Both position in the bit array are then set and the search continues with the successor states.

Search Depth

The search depth is the maximum depth the Validator will explore a particular execution path in the state space. When this depth is reached, the search is truncated and the search backs up to a previous system state.

  • Default value: 100
  • Command: Define-Bit-State-Depth
  • Menu choice: Options2: Bit-State: Depth

Hash Table Size

The size of the bit array used as hash table is an important factor defining the behavior of the bit state exploration. The reason is that each time a new state is checked by comparing its hash values with previous hash values there is a risk for collision. The bigger the hash table is, the smaller the collision risk is.

  • Default value: 1,000,000 (bytes)
  • Command: Define-Bit-State-Hash-Table-Size
  • Menu choice: Options2: Bit-State: Hash Size

Random Walk Options

Random walk is an automatic state space exploration algorithm that can be useful for very large SDL systems. It performs a depth-first search through the state space by selecting transitions to execute at random.

When the maximum search depth is reached during such a "random walk," the search is restarted from the original state again and a new random walk is performed. However, there is no mechanism to avoid that already explored paths are explored once more, i.e. a system state may be visited a large number of times.

Search Depth

The search depth determines how many transitions will be executed before the search is pruned and restarted from the beginning again.

  • Default value: 100
  • Command: Define-Random-Walk-Depth
  • Menu choice: Options2: Random: Depth

Repetitions

The number of times the random walk search will be repeated from the start state before the exploration is finished.

  • Default value: 100
  • Command: Define-Random-Walk-Repetitions
  • Menu choice: Options2: Random: Repetitions

Exhaustive Exploration Options

Exhaustive exploration is an automatic state space exploration algorithm intended for small SDL systems where the requirements on correctness are very high.

The algorithm is a depth-first search through the state space similar to the bit state search, but there is no collision risk involved. The reason is that all traversed system states are stored in primary memory, so it is always possible to determine whether a newly generated system state has already been visited during the search.

The drawback with the algorithm is that very much primary memory is needed to be able to store all traversed states. This limits the complexity of the SDL systems the algorithm is applicable to.

Search Depth

The search depth is the maximum depth the Validator will explore a particular execution path in the state space. When this depth is reached, the search is truncated and the search backs up to a previous system state.

  • Default value: 100
  • Command: Define-Exhaustive-Depth
  • Menu choice: Options2: Exhaustive: Depth

MSC Verification Options

The MSC verification algorithm is a bit state exploration that is adapted to suit the needs of MSC verification:

  • An MSC is always loaded to guide the search
  • The search depth is different from the depth used during usual bit state exploration
  • The search is aborted as soon as the MSC has been verified.

Search Depth

The maximum depth searched by the algorithm. The intention is that this depth always should be enough. If the MSC verification fails and the number of truncations is more than 0, this depth should be increased.

  • Default value: 1,000
  • Command: Define-MSC-Verification-Depth
  • Menu choice: Not available

Timer Check Level

When verifying an MSC where there are timers in the MSC and/or in the SDL system, there is a choice of how to perform the matching between the timer events in the MSC and in the SDL system. The timer check level determines how this matching should be done:

  • 0: No checking of timer events is performed.
  • 1: If a timer event exists in the MSC a matching timer event must exist in the explored SDL path, but a timer event in the explored SDL path is accepted even if there is no corresponding MSC timer event.
  • 2: All timer events in the MSC must match a corresponding timer event in the explored SDL path, and vice versa.

The choice must be determined by the style of MSC that is used.

This option affects the state space; see "Affecting the State Space" .

  • Default value: 1
  • Command: Define-Timer-Check-Level
  • Menu choice: Options2: MSC: Timer check level

Report Options

For each report type, you can define the action performed when the report is found and whether it should be reported to the user.

Report Action

The report action determines what action should be performed when a report situation is encountered while performing state space exploration. There are three possibilities:

  • Continue: The search continues past the reported situation as if it never happened.
  • Prune: The search is pruned and depending on the algorithm some appropriate action is taken. For example, when using bit state exploration, the search will back up one state and continue with the next alternative transition, as if max search depth was reached and the search truncated.
  • Abort: The search is aborted and the command prompt displayed.

Note that for some report types, like Deadlock, the continue choice is impossible.

This option affects the state space; see "Affecting the State Space" .

  • Default value: Prune for all report types
  • Commands: Define-Report-Continue, Define-Report-Prune and Define-Report-Abort
  • Menu choices: Options2: Report: Continue, Options2: Report: Prune and Options2: Report: Abort

Report Log

The report log setting defines whether the report should be recorded in the list of generated reports. If the report log is set to Off for a particular report type, these reports will never show up in the report list. Note however that the report action still is performed, even though the report is not logged.

This option affects the state space; see "Affecting the State Space" .

  • Default value: On for all report types
  • Command: Define-Report-Log
  • Menu choice: Options2: Report: Report log

Report Viewer Autopopup

When an automatic state space exploration is finished, the Report Viewer is normally started automatically to present the found reports. In some cases this may be inconvenient, so there is a possibility to turn this feature off.

  • Default value: On
  • Command: Define-Report-Viewer-Autopopup
  • Menu choice: Options1: Report Viewer Auto Popup

MSC Trace Options

When the Validator performs an MSC trace, you can define what types of events that are traced.

Action Trace

By default, actions like tasks, decisions, etc. are not shown in the MSC trace. You may change this by setting action trace to On.

  • Default value: Off
  • Command: Define-MSC-Trace-Action
  • Menu choice: Not available

State Trace

By default, changes in process states are shown in the MSC trace by adding a condition symbol. You may change this by setting state trace to Off.

  • Default value: On
  • Command: Define-MSC-Trace-State
  • Menu choice: Not available

MSC Trace Autopopup

When you go to a report, an MSC Editor is normally started automatically to present the trace from the current root to the state where the report was generated. In some cases this may be inconvenient, so there is a possibility to turn this feature off.

  • Default value: On
  • Command: Define-MSC-Trace-Autopopup
  • Menu choice: Options1: MSC Trace Auto Popup

State Space Options

The structure and size of the state space that can be generated for any given SDL system can be modified in a number of ways using the state space options. The default values are defined to make the state space as small as possible to make the Validator immediately useful for as many applications as possible. This, however, also means that the search performed by the Validator is fairly scarce compared to what is possible. Some error situations may thus be overlooked during the search if they only occur in a part of the state space that never is reached.

Since these options affect the state space, note the information in "Affecting the State Space" .

Transition Type

There are two alternatives possible for the type of a behavior tree transition during state space exploration:

  • It can be equal to a complete SDL process graph transition (the value "SDL" in the command)
  • It can be a part of such an SDL transition (the value
    "Symbol-Sequence" in the command).

If it is equal to an SDL process graph transition, whenever such a transition is started, it is completed before anything else is allowed to happen. This implies that all process instances in all system states in the behavior tree will always be in an SDL process graph state.

If it is only a part of an SDL process graph transition, a transition in the behavior tree is considered to be a sequence of events that are local to the process instance, followed by a non-local event. Examples of local events are tasks and decisions; examples of non-local events are creates and inputs/outputs of signals from/to other process instances. The idea of this alternative is to model the ITU semantics for SDL as closely as possible while still allowing optimized performance during state space exploration.

  • Default value: SDL
  • Command: Define-Transition
  • Menu choice: Options1: State Space: Transition

Scheduling Algorithm

The scheduling algorithm defines which of the process instances in a system state will be allowed to execute. There are two possible alternatives:

  • All of the process instances in the ready queue are allowed to execute (the value "All" in the command)
  • Only the first process instance in the ready queue is allowed to execute (the value "First" in the command).

The ready queue is a queue containing all process instances that have received a signal that can cause an immediate transition, but that have not yet had the opportunity to execute this transition to its end.

If all process instances are allowed to execute, the semantics of ITU recommendation Z.100 are modeled. There will be one child node to the current node in the behavior tree for each process instance in the ready queue.

If only the first process instance is allowed to execute, the semantics of an application that has been generated by the SDL to C Compiler are modeled. There will only be one child node to the current node in the behavior tree, the first process instance in the ready queue.

  • Default value: First
  • Command: Define-Scheduling
  • Menu choice: Options1: State Space: Scheduling

Event Priorities

The events that are represented in a behavior tree can be divided into five classes:

  • Internal events: Events local to the processes in the system, e.g., tasks, decisions, inputs, outputs.
  • Input from ENV: Reception of signals from the environment. The signal is put in the input port of a process instance or on a channel queue.
  • Timeout events: Expiration of SDL timers. The timer signal is put in the input port of a process instance.
  • Channel outputs: A signal is removed from a channel queue and put into another channel queue or the input port of a process instance
  • Spontaneous transitions: A transition in a process caused by input of none.

To each of these event classes a priority of 1, 2, 3, 4 or 5 is assigned. These priorities are used during state space exploration to determine which transitions should be generated from each system state. The events with priority 1 are first considered. Only if no events with priority 1 are possible in the current state, the events with priority 2 are considered. Only if no events with priority 1 or 2 are possible in the current state are events with priority 3 considered, etc.

Note that also the setting of the symbol time option will have an impact on the events that will can be executed in each system state; see section "Transition Time" .

The two most common ways of assigning priorities to event classes are:

  • All event classes are assigned priority 1.
  • Internal events and channel outputs are assigned priority 1, and external, timeout and spontaneous transition events are assigned priority 2 (the default).

The first alternative represents the situation where no assumptions can be made about the time scale for the different types of events. The second alternative represents a situation where the internal delays are very short compared to the timeout durations and execution speed of the environment.

  • Default value: Priorities 1, 2, 2, 1, 2
  • Command: Define-Priorities
  • Menu choice: Options1: State Space: Priorities

Transition Time

A common simplification made in the analysis of SDL systems is to consider the time it takes for a process to execute a symbol, e.g. an action or output, to be zero. This time is of course never zero in a real system, but in many cases the time is very small compared to the timer durations in the system, and can be neglected when analyzing the system.

Consider for example a situation where a process sets a timer with a duration 5 and then executes something that may take a long time, e.g. a long loop, and then sets a timer with duration 1. If symbol time is assumed to be zero, the second timer will always expire first. If considered to be non-zero, any one of the timers can potentially expire first.

The validator allows the user to choose whether to assume that the execution time for SDL symbols is zero or undefined using the Define-Symbol-Time command.

  • Default value: Zero
  • Command: Define-Symbol-Time
  • Menu choice: Options1: State Space: Symbol time

Channel Queues

The Validator allows queues to be attached to and removed from all channels in the SDL system. If a queue is added for a channel, it implies that when a signal is sent transported on this channel it will be put into the queue associated with the channel. Then there will be a separate transition in the state space that represents the forwarding of the signal to the receiver (or the next channel queue).

  • Default: No channels have queues
  • Command: Define-Channel-Queue
  • Menu choice: Options1: State Space: Channel queues

Maximum Input Port Length

The length of the input port queues is not infinite in the Validator, since in practice it is likely to be a design error if the queues grow forever. If the length of a queue exceeds the defined max length during state space exploration, a "MaxQueuelength" report is generated.

  • Default value: 3
  • Command: Define-Max-Input-Port-Length
  • Menu choice: Options1: State Space: Input port length

Maximum Transition Length

To make it possible to detect infinite loops within a transition in the state space, the maximum number of SDL symbols allowed to be executed in one transition is defined. If this number is exceeded during state space exploration, a "MaxTransLen" report is generated.

  • Default value: 1,000
  • Command: Define-Max-Transition-Length
  • Menu choice: Options1: State Space: Transition length

Maximum Number of Instances

To avoid infinite chains of create actions in the state space, the Validator uses a max number of allowed process instances for any type. If this number is exceeded during state space exploration, a "Create" report is generated.

  • Default value: 100
  • Command: Define-Max-Instance
  • Menu choice: Options1: State Space: Max instance

Maximum State Size

When the Validator is exploring the state space, an internal buffer is used to store the system states. The size of this buffer defines the maximum size of the system states that the Validator can handle.

  • Default value: 100,000 (bytes)
  • Command: Define-Max-State-Size
  • Menu choice: Options1: State Space: Max state size

Timer Progress

One test that can be made with the Validator is to look for non-progress loops, i.e. loops in the state space without any progress being made. The intention with this test is to look for situations where the SDL system is busy doing internal communication but to an outside observer looks dead.

This option defines if the expiration of a timer is considered as progress when performing non-progress loop checking. See also "Non Progress Loop Error" .

  • Default: On (timer expiration is considered to be progress)
  • Command: Define-Timer-Progress
  • Menu choice: Options1: State Space: Timer progress

Spontaneous Transition Progress

One test that can be made with the Validator is to look for non-progress loops, i.e. loops in the state space without any progress being made. The intention with this test is to look for situations where the SDL system is busy doing internal communication but to an outside observer looks dead.

This option defines if a spontaneous transition is considered as progress when performing non-progress loop checking. See also "Non Progress Loop Error" .

  • Default: On (spontaneous transition is considered to be progress)
  • Command: Define-Spontaneous-Transition-Progress
  • Menu choice: Not available

Autolink Options

See section "Computing Test Cases" for a discussion of the Autolink options.

Setting Advanced Options

Advanced options can be set for state space explorations to achieve a much larger state space than the default, thus allowing for special kind of errors to be detected. See "Using Advanced Validation" for more information.

To set advanced options, click the Advanced button in the Explore module. This executes the following set of commands:

Define-Scheduling All
Define-Priorities 1 1 1 1 1
Define-Max-Input-Port-Length 2
Define-Report-Log MaxQueuelength Off

The reasoning behind these settings are:

  • The scheduling should be set to All, since we in this case are looking for signal races and a characteristic property of signal race conditions is that they are depending on the ordering of internal events.
  • The priorities should be set to 1 for all types of events.
  • To reduce the size of the state space, the maximum queue length should be set to a very small number. The reason is that when the environment is allowed to send signals to the system at any time, the queues that can receive signals from the environment will grow very rapidly.
  • Since a lot of maximum queue length reports will be generated with these options, the report log for this report should be set to Off. Note also that the report action for this report should be Prune (which is the default).


References

  16. Holzmann, G.J:
    Design and Validation of Computer Protocols
    Prentice-Hall, 1991
    ISBN 0-13-539834-7


54 The SDL Analyzer

The SDL Analyzer's primary task is to check SDL-92 diagrams (extended as defined in "Application Programmers Interface) with respect to syntactic and semantic rules. The Analyzer accepts both SDL/GR and SDL/PR as input, and has the ability to transform SDL/GR diagrams to SDL/PR files and vice-versa.

This chapter is a reference to the Analyzer commands. Its limitations according to the Z.100 recommendation is found in "SDL Analyzer.

For a guide to how to perform syntactic and semantic check on an SDL diagram structure, see 55 Analyzing a System. This chapter also gives an overview of the Analyzer.


The Analyzer User Interfaces

The Analyzer Graphical UI

The Analyzer's graphical user interface is managed by the Organizer.

To start the Analyzer, select Analyze from the Organizer Generate menu or click the Analyze quick button. For more information, see "Analyze" and "Quick Buttons" .

The Analyzer's graphical user interface is further described in "Using the Analyzer" .

The Analyzer Batch UI

See "Batch Facilities" for information on running the Analyzer non-interactively.

The Analyzer Command-Line UI

The Analyzer also has a command-line mode, when it is started from the OS outside the graphical environment of the SDL suite. This is the user interface that is described in the remainder of this chapter.


Starting the Analyzer

The Analyzer is started in command-line mode from the OS prompt with the command:

sdtsan 1

When the Analyzer is started in command-line mode, it responds with the prompt

SDL Analyzer
Command :
1

The directory where the SDL suite binaries are stored is assumed to be included in the PATH variable. Otherwise, the complete directory path must be supplied.


Environment Variables

  • SDTSAN_WARN_GATE
    By setting this to any value the analyzer will give warnings instead of errors for unconnected gates that should be connected. This option is only provided for backwards compatibility and should not be used if possible.
  • SDTSAN_ASN1_ENUM_OP
    By setting this to any value the analyzer will pass the -e option to asn1util. This will create all operators for ASN.1 ENUMERATED types as defined in Z.105.
  • SDTSAN_FILTER_USE
    By setting this to any value the analyzer will run the specified filter command specified in the analyzer options once before SDL package dependencies are resolved. This makes it possible for external filter scripts to exclude SDL package before make files are generated.


Syntax of Analyzer Commands

A command name may be abbreviated by giving sufficient characters to distinguish it from other command names. A hyphen ('-') is used to separate command names into distinct parts.

Any part may be abbreviated as long as the command does not become ambiguous.

Parameters to commands are separated by one or several spaces. In case you omit a parameter of type "on/off", the value currently defined will toggle between its "on" and "off" values.

In both command names and parameters there is no distinction made between upper and lower case letters.

Note:

On UNIX systems, distinction is made between upper case letters and lower case letters for file names.

Comments are indicated by the "#" character, and extend to the end of the line. Comments may only be preceded by white space.


Description of Analyzer Commands

In this section, the Analyzer commands are listed in alphabetical order, along with their parameters and a description.

Alphabetical List of Commands

! (shell escape)

Parameters:

 <operating system command>

Escape to the shell to do command.

Add-Input

Parameters:

 <Filespec>

Add a file to the list of files to be converted to PR. The file will be processed according to the setting of Input-Mode.

Analyze

Parameters:

 (None)

This command orders the Analyzer to perform the passes according to the Analyzer options as they are defined.

Hint:

The current analysis options can be printed using the command
Show-Analyze-Options (see "Show-Analyze-Options" ).

The order in which the passes are performed is:

  1. Conversion to PR, if the input is C header, ASN.1 or SDL/GR diagrams.
  2. Macro expansion (optional).
  3. Syntactic analysis (optional).
  4. Pretty-printing of a PR file (optional).
  5. PR to GR conversion (optional). This pass converts an SDL/PR input file to SDL/GR diagrams, using the native format of the SDL suite.
  6. Semantic analysis (optional).
  7. Cross reference generation (optional).

Note:

The Analyzer may need to be reset (using the New or Clear command) between subsequent Analyze commands, since the Analyzer keeps track of what passes have been performed in order to minimize analysis time.

ASN1-Coder-Name

Parameters:

 <name>

The prefix of encode and decode functions for ASN.1 types. Default is BER.

ASN1-Keyword-File

Parameters:

 <file>

Change keywords in files output by asn1util according to file. Default is no file, in this case the keywords in file asn1util_kwd.txt in the SDT installation is used.

Asn1Util

Parameters:

 <options>

Invoke asn1util through the post master. Same options as the command line interface.

Cd

Parameters:

 <directory>

Change current working directory to <directory>.

Clear

Parameters:

 (None)

Force the Analyzer to perform all passes from scratch as defined in the Analyzer options on the previously selected input. See also the New command described in "New" .

Coder-Buffer-In-Sdl

Parameters:

 Octet-String | Coder-Buf | Custom-Coder-Buf | None

Pick representation of ASN.1 Buffer in SDL, None means no encoding available in SDL. Default is Octet-String. For more information see "Buffer Management System" .

Component

Parameters:

 [<SDL qualifier>]

Add a new item to a program. See "Partitioning" .

Cpp2sdl

Parameters:

<options>

Invoke cpp2sdl through the post master. Same options as the command line interface.

Env-Header-Channel-Name

Parameters:

 [<name>]

Configuration of channel names in environment header file (.ifc). %n is the name of the entity in SDL, %s is the name of the scope. Omit <name> to exclude the definitions completely from the file. Default is %n.

Env-Header-Literal-Name

Parameters:

 [<name>]

Configuration of literal names in environment header file (.ifc). %n is the name of the entity in SDL, %s is the name of the scope. Omit <name> to exclude the definitions completely from the file. Default is %n.

Env-Header-Operators

Parameters:

 [On/Off]

Configure if operators should be present in environment header file (.ifc). Default is On.

Env-Header-Signal-Name

Parameters:

 [<name>]

Configuration of signal names in environment header file (.ifc). %n is the name of the entity in SDL, %s is the name of the scope. Omit <name> to exclude the definitions completely from the file. Default is %n.

Env-Header-Synonym-Name

Parameters:

 [<name>]

Configuration of synonym names in environment header file (.ifc). %n is the name of the entity in SDL, %s is the name of the scope. Omit <name> to exclude the definitions completely from the file. Default is %n.

Env-Header-Type-Name

Parameters:

 [<name>]

Configuration of type names in environment header file (.ifc). %n is the name of the entity in SDL, %s is the name of the scope. Type definitions are always present in the file. Default is %n.

Error-File

Parameters:

 [<file spec>]

An optional file to store analyzer messages in. Default is no error file.

Exit

Parameters:

 (None)

Terminates the Analyzer and returns you to the Operating System prompt.

Filter

Parameters:

 [Command]

This command allows filtering or preprocessing files before they are read by the Analyzer. The command should be an executable file, preferably found in $PATH. The Analyzer appends three parameters to the supplied command. The first parameter is the name of the file, the second parameter tells what the Analyzer is about to do with the file, and the third is the Source Directory. Currently the following are available:

  • use (before SDL package dependencies are resolved, this phase is only activated when the environment variable SDTSAN_FILTER_USE is set)
  • import (before converting to SDL PR)
  • macro (before macro expansion)
  • parse (before syntax analysis)
  • include (before syntax analysis)

The command is supposed to modify the file given in the parameter and leave the result in the same file. Note that the files passed are your original files.

Generate-Advanced-C

Parameters:

 (None)

This command invokes the Cadvanced SDL to C Compiler, which will produce one / multiple C program(s), as well as a makefile. This C program is then compiled and linked in order to build up an executable application. The Cadvanced SDL to C Compiler uses the options which have been previously defined using the various Generate Options commands. See also Generate-Basic-C.

Generate-Basic-C

Parameters:

 (None)

This command invokes the Cbasic SDL to C Compiler, which will produce one / multiple C program(s), as well as a makefile. This C program is then compiled and linked in order to build up an executable application. The Cbasic SDL to C Compiler uses the options which have been previously defined using the various Generate Options commands. This command cannot be used when building applications, but otherwise it is identical to Generate-Advanced-C.

Generate-Micro-C

Parameters: 1

 (None)

This command invokes the Cmicro SDL to C Compiler, which will produce one / multiple C program(s), as well as a makefile. This C program is then compiled and linked in order to build up an executable application. The Cmicro SDL to C Compiler uses the options which have been previously defined using the various Generate Options commands. See also Generate-Advanced-C.

GR-PR-File

Parameters:

 [<file spec>]

This command specifies where the output of the conversion to PR pass is stored. Default is <infile>.pr.

GR2PR

Parameters:

<GR-File> <PR-File>

The command converts the file designated by the file specifier GR-File to a textual (i.e. PR) description of the diagram, storing the results in the file designated by the file specifier PR-File.

The file GR-File should contain an SDL diagram stored in binary format.

Help

Parameters:

 [Command]

The command issues on-line help for the Analyzer commands. Depending on if a command is specified or not, the following happens:

  • By typing this command without parameters, the available commands are listed with their parameters. Control is then transferred to the Analyzer on-line help, where additional information about all commands is available. The on-line help prompt looks like this:
Topic?
    • Typing a command name followed by <Enter> issues information about the command.
    • Typing <Enter> only, returns control to the Analyzer prompt.
  • Typing the Help command followed by a command name, on-line for that command will be displayed. Control is then transferred to the Analyzer on-line help utility.

You can abbreviate any topic name, although ambiguous abbreviations result in all matches being displayed.

Include-Directory

Parameters:

 [<directory>]

Where the analyzer looks for include files. An empty <directory> clears the list.Subsequent commands adds more directories to the list. Default is an empty list.

Include-File

Parameters:

 <file spec>

Execute analyzer commands in <file spec>.

Include-Map

Parameters:

 <logical name> <file spec>

Maps logical names to file names for graphical includes when converting graphical SDL (GR) to text (PR). This command should be preceded by commands to specify input mode to GR and a GR file. Subsequent commands adds more maps to the list. Default is an empty list.

Input-Mode

Parameters:

 ASN.1 | C-Header | GR | PR

Select filter to convert input to PR. Default is PR.

Instance-File

Parameters:

 [<file spec>]

Where the instance tree is stored. Default is <system name>.ins. See "SDL Instance Information" for more information.

Macro-PR-File

Parameters:

 [<file spec>]

This command specifies where the output of the macro expander is stored. Default is <infile>.prm.

Make-File

Parameters:

 [<file spec>]

Name of makefile. Default is <system name>.m.

Make-Template-File

Parameters:

 [<file spec>]

Name of make template file. Default is no template.

New

Parameters:

 (None)

This command initializes the Analyzer. Following the New command, you will need to specify an input to the Analyzer using the Set-Input command.

See also "Clear" .

Operating-System

Parameters:

 (None)

Creates a subprocess which returns you temporarily to the Operating System. Once you terminate this process, control is returned to the Analyzer.

Organizer-Object

Parameters:

 Level Type Name File Sep SepName Selected [Depend]

Pass the Organizers info on a diagram to the Analyzer. This command is used by the Organizer.

Pretty-PR-File

Parameters:

 <Filespec>

This command specifies where the output of the pretty printer is stored. Default is <infile>.sdl.

Program

Parameters:

 [<name>]

Name of program built from components. See "Partitioning" .

Quit

Parameters:

 (None)

Synonym for exit.

SDL-Coder-Name

Parameters:

 <name>

The prefix of encode and decode functions for SDL types. Default is ASCII.

SDL-Keyword-File

Parameters:

 [<file spec>]

Produce a list of SDL keywords and SDT Ref in a file. Default is no list.

SDT-Ref

Parameters:

 [<sdt ref>]

Use <sdt ref> in error messages from command parser overriding any other <sdt ref>.

SDT-SYSTEM-4.4

Parameters:

 (None)

The Organizer uses this to make sure the right version of the analyzer is running.

Set-ASN1-Coder

Parameters:

 [On/Off]

Generates encoder and decoder from ASN.1 modules (requires separate license).

Default is off.

Set-C-Compiler-Driver

Parameters:

 [On/Off]

This option informs the SDL to C compilers if the SDL C Compiler Driver should be invoked. See 60 SDL C Compiler Driver (SCCD).

Default is off.

Set-C-Plus-Plus

Parameters:

 [On/Off]

SDL to C compilers generate code to be compiled with C++ compiler if on. Default is off.

Set-Case-Sensitive

Parameters:

 [On/Off]

Case sensitive SDL names if On. Keywords must be all upper or lower case if on.

Default is off.

Set-Compile-Link

Parameters:

 [On/Off]

This option informs the Code Generator (SDL to C compilers) whether the generated code should be compiled and linked automatically (by executing the generated makefile).

Default is on.

Set-Echo

Parameters:

 [On/Off]

This option will print (echo) all Analyzer commands as they are executed. Default is off.

Set-Env-Function

Parameters:

 [On/Off]

This option informs the code generators (SDL to C compilers) if environment functions should be generated or not.

Default is off.

Set-Env-Header

Parameters:

 [On/Off]

This option is applicable to the SDL to C compilers only. With this parameter turned on, a header file containing the definitions of the SDL system's interface to the environment is created. This file is identified by the .ifc file name extension.

Default is off.

Set-Error-Limit

Parameters:

 <Errorlimit>

This command sets the limit of reported errors after which the Analyzer will stop its execution. Use 0 to turn off the limit.

Default is a limit of 30 diagnostics.

Set-Expand-Include

Parameters:

 [On/Off]

This option specifies whether include directives should be handled and expanded when reading input files. See "Including PR Files" .

Default is on.

Set-Expression-Limit

Parameters:

 <Depth>

This command instructs the Analyzer to issue a warning when the semantic analyzer encounters an SDL expression which is at least Depth deep.

Note:

Deeply nested expressions may cause a significant degradation of performance when performing the semantic analysis pass. It is therefore recommended to break down complex expressions into multiple, less complex expressions.

Default is 0, meaning that no warnings will be issued.

Set-File-Prefix

Parameters:

 [<file name prefix>]

Prefix for files generated by the code generators. Default is no prefix.

Set-Full

Parameters:

 [On/Off]

Redo everything if on. Default is off.

Set-Generate-All-Files

Parameters:

 [On/Off]

Existing files will not be touched by C code generators if the new version is identical to the existing one and this option if Off. Default is On.

Set-Ignore-Hidden

Parameters:

 [On/Off]

Decides if PR should be generated for hidden SDL symbols. Default is On.

Set-Implicit-Type-Conversion

Parameters:

 [On/Off]

When this option is on, the Analyzer allows implicit type conversion of reference data types (generators Own, ORef, and Ref). Note that analyzing large expressions with this option on is slow. Default is off.

For more information, see "Implicit Type Conversions.

Set-Input

Parameters:

 <Filespec>

The Analyzer will use the file specified in filespec as input file. The file will be processed according to the setting of Input-Mode (see "Input-Mode" ). Use Add-Input to process a system stored in several files.

Set-Instance

Parameters:

 [On/Off]

With this option on, a file containing the SDL instance tree will be generated. Default is off. See "SDL Instance Information" for more information.

Set-Kernel

Parameters:

 <Kernel>

This option is applicable to the SDL to C compilers only. This option allows you to select the appropriate kernel with predefined runtime libraries. The makefile generated by the SDL to C compilers contains instructions which link the generated and compiled code with object modules of the selected library. The effect of this will be that the code which is generated by the SDL to C compilers will have different properties, reflecting the purpose of its usage (simulation, application generation, etc.). The allowed values of the parameter kernel vary from one configuration to another. The definitions are made in the file sdtsct.knl. The definitions for Cadvanced are made in the file sdtsct.knl, whereas the definitions for Cmicro are made in the file scmsct.knl.

The following values are recognized for Cadvanced:

Library
Application area

 SCTADEBCOM
Simulation, simulated time

 SCTADEBCLCOM
Simulation, real time

 SCTAPERFSIM
Performance simulation

 SCTAAPPLCLENV
Application

 SCTADEBCLENV
Application debug (simulation with environment, only Cadvanced)

 SCTAVALIDATOR
Validation

 SCTATTCNLINK
TTCN link

The following values are recognized for Cmicro:

Library
Application area

 SCMADEBCOM
SDL Target Tester and communication, no real time clock

 SCMADEBCLCOM
SDL Target Tester, communication and real time clock

 SCMADEBCLENVCOM
SDL Target Tester, communication, user's env and real time clock

 SCMAAPPLCLENVMIN
Application with environment, clock, etc.

 SCMAAPPLCLENV
Evaluation Kernel (no complex ADT; no SDL Target Tester)

Note:

The predefined kernels for Cmicro cannot be used with any C compiler. They require GCC 2.8.1 on UNIX, or Borland C 5.02 or Microsoft Visual C++ 5.0 in Windows.

Set-Lower-Case

Parameters:

 [On/Off]

SDL does not distinguish between lower case letters (a..z) and upper case letters (A..Z), but the high level programming language C does. With this parameter turned on, the names of, for instance, variables in the generated C code is written in lower case letters only. Otherwise, the case of an item in the SDL definition is used.

Default is off.

Set-Macro

Parameters:

 [On/Off]

Turns on or off the macro expansion pass. This option must be turned on if your diagram contains references to macro(s).

Default is off.

Set-Make

Parameters:

 [On/Off]

This command affects an option which enables or disables the generation of a makefile in conjunction with generation of C code.

Default is on.

Set-Modularity

Parameters:

 [Modularity]

Allows to specify the modularity of the code generated by the code generators, e.g. the SDL to C compilers. This option affects how many files will be generated.

Three options for the parameter Modularity are available:

  • No - One single code module is generated.
  • User - User defined, according to the definitions in the Organizer. See "Edit Separation" .
  • Full - Multiple code modules will be generated.

Default value is No.

Set-Optional-Make-Operator

Parameters:

 [On/Off]

Optional and default struct parameters are included in the make operator (invoked by (. .)) if On. Default is Off.

Set-Output

Parameters:

 <Filespec>

Allows you to save the information generated by the Analyzer in files with a different name, using Filespec as the base name.

File name extensions are appended automatically by the Analyzer.

Set-Pr2Gr

Parameters:

 [On/Off]

Turning this option on, the Analyzer will perform the PR to GR conversion pass. The steps are:

  1. The Analyzer creates diagram files with temporary names.
  2. The Analyzer lets the SDL Editor do tidy up on the diagram files.
  3. The Organizer renames/moves diagram files according to its preference.

Step 3 is only performed when a PR to GR conversion is run from the Organizer. The request to put temporary files in the current working directory is ignored on the Windows platform (they end up in some temp directory).

Default is off.

Set-Predefined-XRef

Parameters:

 [On/Off]

Include predefined data in SDL cross reference file if On. Default is Off.

Set-Prefix

Parameters:

 [Prefix]

Allows you to specify what prefix the code generators add to SDL names in the generated code.

Possible values for the parameter prefix are:

  • No
  • Entity
  • Full
  • Special

Default is Full.

Set-Pretty

Parameters:

 [On/Off]

Turning this switch on, a pretty printed PR file will be generated.

Default is off.

Set-References

Parameters:

 [On/Off]

This option allows you to disable the verification that exactly one reference corresponds to each remote definition.

Default is on.

Set-SDL-Coder

Parameters:

 [On/Off]

Generate encoder and decoder from SDL (requires separate license).

Default is off.

Set-Sdt-Ref

Parameters:

 [On/Off]

Decides if SDT references should be included in the generated code as comments for easier navigation to its source. As default, SDT references in comments are included. Note that omitting SDT references in comments by using this command is not supported by standard Telelogic code generators.

Set-Semantic

Parameters:

 [On/Off]

With this option turned on, the semantic check pass will be performed. Otherwise, the Analyzer will stop after the syntactic check.

Default is on.

See also "Optimizing a System to Reduce Analysis Time" .

Set-Signal-Number

Parameters:

 [On/Off]

Code generators will generate a file with signal numbers if on.

Default is off

Set-Source

Parameters:

 [On/Off]

This command informs the code generators whether to generate C code or not when a generate code command is given. The reason for disabling code generation is that you may want to produce a makefile only, without generating code.

Default is on.

Set-Synonym

Parameters:

 [On/Off]

Decides if the specified synonym file should be used or not. Default is Off.

Set-Syntax

Parameters:

 [On/Off]

This option turns on or off the syntax analysis pass.

Default is on.

Set-TAEX-Make

Parameters:

 [On/Off]

This command controls the generation of a makefile for Targeting Expert in conjunction to generation of C code.

Default is off.

Set-Upcase-Keyword-Pretty

Parameters:

 [On/Off]

Select between upper or lower case keywords in pretty printings.

Default is off (i.e. lower case letters).

Set-Warn-Else-Answer

Parameters:

 [On/Off]

Print a message if a decision or transition option does not have an else answer and the Analyzer is unable to decide that it is not needed.

Default is on.

Set-Warn-Match-Answer

Parameters:

 [On/Off]

Print a message if a decision or transition option does not have an answer for some value. The analyzer is not able to do this in all situations.

Default is on.

Set-Warn-Optional-Parameter

Parameters:

 [On/Off]

Print a message if an optional actual parameter is omitted.

Default is on.

Set-Warn-Output

Parameters:

 [On/Off]

Print a warning message if an SDL signal output has a different semantic meaning between SDL 88 and 92.

Default is on.

Note:

This command is particularly useful when working with SDT 2.X diagrams in an SDT 3.X environment (SDT 2.X supports SDL-88, while SDT 3.X supports SDL-92).

Set-Warn-Parameter-Count

Parameters:

 [On/Off]

Print a message if trailing actual parameters are omitted.

Default is on.

Set-Warn-Usage

Parameters:

 [On/Off]

Print a message if an SDL definition is not used.

Default is off.

Set-Xref

Parameters:

 [On/Off]

With this option on, a file containing SDL Cross References will be generated. See "SDL Cross-References" .

Default is off.

Show-Analyze-Options

Parameters:

 (None)

This command lists the current Analyzer options.

Show-Commands

Parameters:

 (None)

Similar to Help. The commands are listed without the command parameters.

Show-Generate-Options

Parameters:

 (None)

This command displays the code generator options as currently defined.

Show-License

Parameters:

 (None)

This command returns information about:

  • The total amount of software licenses
  • How many licenses are currently in use, together with the user identification, the host name and the checkout time
  • How many licenses are available

Show-Version

Parameters:

 (None)

This command displays the version number of the Analyzer.

Source-Directory

Parameters:

 [<directory>]

The analyzer looks for include files in this directory.

Default is current working directory.

Synonym-File

Parameters:

 [<file spec>]

Specifies the synonym file (containing values of external synonyms). Default is no synonym file.

TAEX-Make-File

Parameters:

 [<file spec>]

Name of makefile for Targeting Expert. See Set-TAEX-Make.

Target-Directory

Parameters:

 [<directory>]

Specifies the directory where the code generators puts their files.

Default is current working directory.

Thread

Parameters:

 <name> <stacksize> <stackprio> <maxqueuesize>
<maxmessize>

Use this command to distribute components of a program over several threads. Components following this command belongs to this thread. Parameters at the end may be omitted. Omitted parameters will use default values. The word default can be used to indicate that the default value is desired for a parameter. For more information see "Threaded Integration" .

XRef-File

Parameters:

 [<file spec>]

Specifies where the cross references are stored.

Default is <infile>.xrf.

Miscellaneous Analyzer Commands

The following commands can be used for instance in the case of malfunction or unexpected behavior. They are not described further within the scope of the user documentation.

zzMake-Options

Parameters:

 (None)

zzSet-Access-Path-Tab

Parameters:

(None)

zzSet-Optimize

Parameters:

 (None)

zzSet-Organizer-File

Parameters:

(None)

zzSet-Over-View

Parameters:

 (None)

zzSet-SDT

Parameters:

 (None)

zzSet-Verbose

Parameters:

 (None)

zzSet-Warn-Oper-Usage

Parameters:

 (None)

zzShow-Error

Parameters:

 (None)

zzShow-Organizer

Parameters:

 (None)

zzTransport

Parameters:

 (None)

zzWrite-Name-List

Parameters:

 (None)

zzWrite-Path

Parameters:

 (None)

zzWrite-Pretty

Parameters:

 (None)

zzWrite-Symbol

Parameters:

 (None)

zzWrite-Syntax

Parameters:

 (None)
1

The exact syntax is subject to change since the tool is still under development.


Conversion to PR

During the first pass of the Analyzer, an SDL/PR file suitable for processing by the following passes (Macro Expansion or Syntax analysis) is produced. The resulting PR file is not intended to be read by the human, and is not formatted for that purpose. Conversion to PR is needed when input is not already in SDL/PR format, i.e, for SDL/GR diagrams, ASN.1 files, and C header files.

Several tools might be invoked through the PostMaster to perform the actual conversion:

  • The SDL Editor to process SDL/GR. See "GR to PR Conversion" .
  • The ASN.1 Utilities to process ASN.1. See "Translation of ASN.1 to SDL" .
  • The CPP2SDL Utility to process C/C++ header files. See "C/C++ to SDL Translation Rules" .

Additional SDL/PR files may be copied into the output of this pass.

A number of checks are performed during this conversion pass. Many of these are actually syntactic in their nature. They may result in error messages; see "Error and Warning Messages" .


The Macro Expander

A macro is a form of text substitution used in the SDL system definitions. In a macro definition, a collection of lexical units is defined. A macro call indicates where the text from the macro definition body is to be included. All macro calls must be expanded before further analysis of the system definition can be done.

Note:

Macros may not contain any states.
Diagrams referenced in PR form and macros only called in PR will not be converted. If a macro is called only in PR form, the macro definition must be in PR and placed in a diagram that will be converted.

The name of the macro definition is visible in the whole system definition. A macro call may appear before its corresponding macro definition. A macro definition may contain macro calls, but not calls to itself, directly or indirectly.

A macro may use parameters, called formal parameters, in macro definitions and actual parameters in macro calls. There must be an equal number of formal parameters and actual parameters in corresponding macro definitions and macro calls. Using multiple formal parameters with the same name is not allowed.

When a character string is used as an actual parameter, the value of the character string will be used to replace the formal parameter in the macro body and not the character string itself.

The keyword MACROID may be used in a macro definition body only. The MACROID keyword will be replaced by a unique name at each expansion of the macro (that is, only one unique name is available at each expansion of a macro definition). New names can be constructed by concatenating names, parameters and MACROID using a percent sign (%) as a separator.

The reserved word MACRODEFINITION is not allowed inside a macro definition. The reserved words MACROID and ENDMACRO are only allowed inside a macro definition.

Macro expansion follows this order:

  1. The name in the macro call is used to find the corresponding macro definition, and a copy of that macro definition is made.
  2. In this copy, all occurrences of formal parameters are replaced by actual parameters. All occurrences of
    MACROID are replaced by a unique name. Also, all percent signs (%) separating names are removed.
  3. Macro calls in the modified macro definition body are expanded.
  4. The modified and expanded text is substituted for the macro call text in the system definition.

Implementation Details

The syntax checks made in the macro parser are entirely specific to macros since no other checks are possible until all macro calls are expanded. Some semantic checks are made during the expansion. These may produce error messages; see "Error and Warning Messages" .

Example 328 : Macro in SDL that Will Not Work

Constructs such as:

macro test('if par3 then',
'if not par3 then',
'k<0') ;

where the text par3 in the first and second parameter strings is intended to be replaced by the third formal parameter in the macro definition will not work. This is because all formal parameters are replaced with actual parameters in a single step.

The reserved word MACROID is replaced by a unique name consisting of the string "XMID" and an integer. To assure system wide uniqueness the name is tested against all existing names in the system and the integer will be increased until the name is unique.


The Lexical and Syntactic Analyzer

The scanner (lexical analyzer) reads the input file and passes on lexical units to the parser. The parser checks the syntax and builds an internal representation (an abstract syntax tree) for the SDL specification.

The lexical and syntactic analysis may be performed not only on complete system definitions, but also on the following SDL units:

  • Block
  • Process
  • Substructure
  • Service
  • Procedure
  • Package

If no errors are found during the syntactic analysis, the syntax tree can be passed to the pretty-printer and, if the input is a system or package definition, to the semantic analyzer. For a description of the errors that can produced, see "Error and Warning Messages" .


Separate Analysis

You may perform analysis on separate SDL units. The units that can be handled (other than system) are:

  • Block
  • Process
  • Substructure
  • Service
  • Procedure
  • Package

Note:

When performing separate analysis on a package, referred packages must be supplied as well.

If a unit is given without context, only syntactic checking can be performed. But, if the unit's placement in the system (that is, its context) is also given, both the syntactic checking and most of the semantic checking can be performed. The context of a unit is its enclosing scope units including the definitions that are not referenced, i.e. remote diagrams are excluded.

GR Input

In the Analyzer, the context is specified in the Organizer tree structure if the input is a GR diagram. The diagrams surrounding the diagram that is to be separately analyzed and the diagrams inside that diagram are translated to PR and analyzed. No errors will occur due to missing remote diagrams, except missing remote diagrams inside the separately analyzed diagram. See "Performing Syntax Check" .

PR Input

If the input is a PR file, there is no way to specify what part of the system to Analyze. Only syntax analysis is available on incomplete systems in PR form. See "Converting SDL/PR to SDL/GR" .


Including PR Files

The Analyzer allows the user to divide the SDL description into a number of separate PR files. (The macro expansion can, however, only handle one file at a time.) It may, for example, be convenient to have the system level data type definitions in a separate file. A separate file is included by adding an include directive to the SDL description.

Syntax of #INCLUDE Directives

The include directive is #INCLUDE followed by the name of the file which should be surrounded by single quotation marks. The directive should be placed in an SDL comment, directly after the comment start ("/*"), at the place where the file should be included.

  • The first single quote must be preceded by at least one space. <TAB> characters are however not allowed.
  • The second single quote may be followed by any number of spaces. <TAB> characters are however not allowed.

Example 329 : #INCLUDE in Analyzer

System Example;
/*#INCLUDE 'DataDefs.pr' */
/*#INCLUDE 'BlockA.pr' */
EndSystem Example;

Search Order for Included PR Files

The Analyzer will search for included SDL/PR files in the following order:

  1. Any directory specified with Include-Directory command
  2. Source directory
  3. The current default directory
  4. The directory designated by the environment variable HOME.
  5. The directory designated by $telelogic/sdt/include/ADT (on UNIX), or <installation directory>\sdt\include\adt (in Windows)
    (This directory contains a number of useful abstract data types in SDL/PR that are included in the release. See 62 The ADT Library for more information.)


The PR to GR Converter

General

The PR to GR Converter performs a conversion from SDL/PR files into SDL/GR diagrams. (It is also possible to input SDL/GR diagrams, which transforms them to new SDL/GR diagrams, applying default layouting algorithms.)

Conversion is done on a one-diagram-per-file basis, meaning that each generated GR diagram will be stored on one file. However, entering a PR file may generate multiple GR diagrams, depending on the contents of the PR file.

Note:

The PR to GR converter requires syntactically correct diagrams or PR files as input in order to function properly.
Diagrams containing semantic errors will be converted, but, the resulting SDL/GR interpretation may be different from the SDL/PR representation.

Conversion Principles

The Analyzer passes which are performed are:

  1. Macro expansion (if the PR input contains macro definitions).
  2. Syntax analysis.
  3. PR to GR conversion.
  4. Then, graphical layouting is done by the SDL Editor.

Resulting files

The result from the PR to GR conversion is a number of SDL/GR binary files. Each diagram will be stored on one file.

To reconstruct the SDL diagram structure, the Organizer's command Import SDL should be used (see "Import SDL" ).


SDL Cross-References

The Analyzer has the ability to produce listings of SDL entities and references to these definitions. In one file, all definitions of entities in an SDL system will be gathered, along with cross references to these entities. Entities mainly used to indicate structure (such as system, block, substructure, process, procedure, and service), as well as entities defining objects (such as signals, variables and sorts) will be considered as definitions.

The file, which is described further below, is a plain text file.

Note:

The SDL suite has support for graphical presentation of a cross-reference file, using an SDL-like graphical notation. To achieve this, you can use the Index Viewer. See 47 The SDL Index Viewer.

Definitions and Cross References Files

The file name will be <unitname>.xrf for the cross references file, where <unitname> is the name of the SDL unit selected for analysis. Alternatively, the file name is to be supplied by the user when running the Analyzer from the Organizer.

If an SDL system is selected for analysis, all definitions and cross references are generated; while if case of a non-SDL system unit, definitions and cross references in the following units are generated:

  • The unit itself
  • All subunits to the selected unit
  • All enclosing units (blocks and the system) of the selected unit

The following entities will be part of the files:

ACTIVE | ATLEAST
BLOCK | BLOCK SUBSTRUCTURE
CHANNEL | CHANNEL SUBSTRUCTURE
CONNECTION | CONTINUOUS SIGNAL
CREATE | DCL
DECISION | ENABLING CONDITION
EXPORT | EXPORTED_PROCEDURE
FORMAL PARAMETER | FPAR
GATE | GENERATOR
IMPORT | IMPORTED
IMPORTED VARIABLE | IN-CONNECTOR
INHERITS | INPUT
INSTANTIATION | JOIN
LITERAL | NEWTYPE
NEXTSTATE | NUMBER OF INSTANCES
OPERATOR | OUT-CONNECTOR
OUTPUT | PACKAGE_INTERFACE
PROCEDURE | PROCEDURE CALL
PROCEDURE PARAMETERS | PROCESS
PROCESS PARAMETERS | REMOTE PROCEDURE
REMOTE VARIABLE | RESET
SAVE | SERVICE
SET | SIGNAL
SIGNAL ROUTE | SIGNALLIST
SIGNALROUTE | SIGNALSET
SORT | STATE
STATE_LIST | SYNONYM
SYNTYPE | SYSTEM
TASK | TIMER
TRANSITION OPTION | USE
VARIABLE | VIEW
VIEWED |

Note:

No cross references will be generated for the predefined data types (INTEGER, NATURAL, CHARACTER, CHARSTRING, BOOLEAN, REAL, TIME, DURATION, PID) or for the predefined generators (ARRAY, STRING, POWERSET) as well as LITERALS and OPERATORS that are not part of the list above.

Syntax of Files

For each definition of any kind mentioned above the following information is generated:

ScopeLevel EntityType EntityName Reference

Explanation

  • The number first on the line is the scope level. The system has level 1, any definition at the system level has scope level 2, and so on.
  • Next on the line the entity type and entity name are given.
  • Last there is an SDT reference to the place where the entity is defined. For more information on the format, see "Syntax" .

For each entity used to indicate structure (system, block, substructure, process, procedure, service) there is a header consisting of three additional lines, which should be considered as a comment to increase the readability.

Example 330 : Reference in Analyzer Error

2 SIGNAL Bump \
SDTREF(SDL,/usr/tom/demongame.ssy(1),122(40,30),3)

Order of Definitions

The definitions are generated in pre-order (prefix walk in the tree formed by the definitions). This means that an entity is always followed by the entities defined within the entity. It also means that an entity at level N is defined in the first entity at level N-1 found when scanning upwards in the file.

Cross References

For each place where an entity is used, information about that cross reference is generated:

Example 331 : Cross References

4 DCL Count \
#SDTREF(SDL,/usr/tom/game.spr(1),179(80,10),2)
TASK \
#SDTREF(SDL,/usr/tom/game.spr(1),137(30,40),1)
OUTPUT \
#SDTREF(SDL,/usr/tom/game.spr(1),128(80,55),2)

Cross references consist of a keyword, describing where the reference was found, and the SDL reference. In Example 331, the variable Count is referenced in a task symbol and in an output. All cross references for an entity are placed immediately after the line for the definition.

Note:

Entities used to indicate structure can also have cross references (procedure call, process create).


SDL Instance Information

The Analyzer supports the generation of a so-called instance information file, with the file extension .ins. This file contains various kinds of information about an SDL system. Similar to a cross reference file, it is a plain text file. The file syntax is described in detail in "File Syntax" . The Analyzer invokes a tool called the Instance Generator to produce the instance information out of an analyzed SDL system.

The information that can be found in an instance information file helps to answer many questions. For example:

  • How does a complex SDL-92 system look after instantiation of all types, i.e. when all inheritance hierarchies have been flattened out? Finding this information about the instance structure of a system directly from the SDL/PR file is a non-trivial task. Therefore, one of the main objectives behind the Instance Generator is to provide this "instance view" of a system.
  • Which signals can be conveyed on a certain channel or signal route in a certain direction?
  • What is the valid input signal set of a process?
  • Which states does a process contain?
  • Which transitions will take place if a certain signal is received by a process being in a certain state?
  • Which output signals might be sent during a transition?
  • Which procedures might get called during a transition?
  • What is the set of possible nextstates after a transition?
  • How shall a procedure be interpreted when called from a certain process?

The Instance Generator

The Analyzer provides two commands to use the Instance Generator from the command line user interface. These commands are described in "The Analyzer Command-Line UI" but are repeated here for the sake of completeness.

Set-Instance

Parameters:

 [On/Off]

This command sets an option that specifies whether an instance information file should be generated or not when the SDL system is analyzed. The option is by default off.

Instance-File

Parameters:

 <file spec>

This command sets the name of the instance information file. The default filename is <systemname>.ins, where <systemname> is the name of the analyzed SDL system.

The Instance Generator can also be started from the Analyzer's graphical user interface. This is done in a way similar to how cross reference files are generated. In the Analyze dialog in the Organizer, you can check a button to make the Analyzer call the Instance Generator when the system has been analyzed. From this dialog it is also possible to set the name of the generated instance information file.

Note:

The Instance Generator is automatically invoked to produce the information needed by tools such as the State Matrix Viewer.

File Syntax

An instance information file consists of a fileheader followed by a list of records:

<fileheader>
<record>
<record>
...
<record>

The <fileheader> is a string telling which version of the Instance Generator that has generated the file. Each <record> describes an SDL entity according to the following format:

<level> <entity class> <name>
<attribute> = <value>
...
<attribute> = <value>
.

The <level> is a number that tells at what depth in the "instance tree" the entity was found. For example, the system entity has level 1, a block entity in the system has level 2, a process entity in the block has level 3, and so on.

Attributes can be divided into three distinct categories depending on the format of their values:

  1. A single value:
<attribute> = <single value>

  2. A list of single values:
<attribute> = (
<single value>
<single value>
...
<single value>
)

  3. A list of pairs of single values:
<attribute> = (
<single value> <single value
<single value> <single value>
...
<single value> <single value>
)

Sometimes an attribute is omitted from a record. This happens when the value of the attribute is an empty string or list.

The table below lists all entity classes for which information is generated in an instance information file. The attributes of the entities are also described, together with the category of the attributes (1, 2 or 3 according to above).

In the descriptions, the following terms are used:

  • A state-containing entity is an entity that may contain states, i.e. a process, process instance, service, service instance or procedure.
  • A transition initiator is an entity that can make a state-containing entity perform a transition from one state to another, i.e. a start, input, priority input, enabling condition or continuous signal.

Entity class
Attribute
Category
Description

 BLOCK

 InstRef
1
An SDT reference to the definition of this block.

 ConnectionOut
2
The names of the channels that are on the outside of this block.

 ConnectionIn
2
The names of the channels or signalroutes that are on the inside of this block.

 BLOCK_INST

 InstRef
1
An SDT reference to the definition of this block instance.

 TypeRef
2
SDT references to block type definitions. The first reference is to the block type from which this block instance is instantiated, followed by references to its supertypes all the way to the block type on top of the inheritance hierarchy.

 CALLED_
PROCEDURE

 InstRef
1
An SDT reference to the definition of this called procedure.

 CHANNEL

 InstRef
1
An SDT reference to the definition of this channel.

 SignalSet
3
The signals that are conveyed on this channel in the direction from the From-entity to the To-entity. Each signal is described by its name followed by an SDT reference to the definition of the signal.

 SignalSetRev
3
As SignalSet but for the signals that are conveyed in the opposite direction.

 From
1
The name of the block or block instance from which this channel starts. If the channel starts from the environment surrounding the system, system instance, block or block instance where this channel is located, this attribute is "env".

 FromVia
1
This attribute is specified when the From-entity is a block instance, and is then the name of the gate of that block instance to which this channel is connected.

 To
1
The name of the block or block instance to which this channel leads. If the channel leads to the environment surrounding the system, system instance, block or block instance where this channel is located, this attribute is "env".

 ToVia
1
This attribute is specified when the To-entity is a block instance, and is then the name of the gate of that block instance to which this channel is connected.

 CHANNEL_
 SUBSTRUCTURE

 InstRef
1
An SDT reference to the definition of this channel substructure.

 CONTINUOUS_
SIGNAL1

 InstRef
1
An SDT reference to the definition of this continuous signal.

 InType
1
The name of the state-containing entity in which this continuous signal is defined.

 Outputs
3
The output signals that might be sent in the transition that is initiated by this continuous signal. Each signal is described by its name followed by an SDT reference to one of the output symbols in the transition that contains that name.

 Calls
3
The procedures that might get called in the transition that is initiated by this continuous signal. Each procedure is described by its name followed by an SDT reference to one of the symbols in the transition that contains a call to a procedure with that name. This name is also the name of a CALLED_
PROCEDURE entity that describes how the procedure look from the calling state-containing entity's point of view. This entity is normally placed immediately after the state information of the state-containing entity. However, when the state-containing entity is a procedure within another state-containing entity, it might be that the procedure has been called from another place in this surrounding state-containing entity. Then the CALLED_
PROCEDURE entity is not placed here also, since it is identical to the first one.

 NextStates
3
The states that might become the nextstate after the transition that is initiated by this continuous signal. Each state is described by a name followed by an SDT reference to one of the state symbols that contains that name.

 ENABLING_
CONDITION

 InstRef
1
See the description for CONTINUOUS_ SIGNAL.

 InType
1
See the description for CONTINUOUS_ SIGNAL.

 Outputs
3
See the description for CONTINUOUS_ SIGNAL.

 Calls
3
See the description for CONTINUOUS_ SIGNAL.

 NextStates
3
See the description for CONTINUOUS_ SIGNAL.

 GATE

 InstRef
1
An SDT reference to the definition of this gate.

 SignalSet
3
The signals that are conveyed through this gate in to the block instance, process instance or service instance to which the gate belongs. Each signal is described by its name followed by an SDT reference to the definition of the signal.

 SignalSetRev
3
As SignalSet but for the signals that are conveyed in the opposite direction.

 INPUT

 InstRef
1
See the description for CONTINUOUS_ SIGNAL.

 InType
1
See the description for CONTINUOUS_ SIGNAL.

 Outputs
3
See the description for CONTINUOUS_ SIGNAL.

 Calls
3
See the description for CONTINUOUS_ SIGNAL.

 NextStates
3
See the description for CONTINUOUS_ SIGNAL.

 PRIORITY_
INPUT

 InstRef
1
See the description for CONTINUOUS_ SIGNAL.

 InType
1
See the description for CONTINUOUS_ SIGNAL.

 Outputs
3
See the description for CONTINUOUS_ SIGNAL.

 Calls
3
See the description for CONTINUOUS_ SIGNAL.

 NextStates
3
See the description for CONTINUOUS_ SIGNAL.

 PROCESS

 InstRef
1
An SDT reference to the definition of this process.

 IniNoOfInst
1
The initial number of dynamic instances of this process.

 MaxNoOfInst
1
The maximum number of dynamic instances of this process. If this attribute is omitted it means that there is no upper limit on the number of dynamic instances.

 SignalSet
3
The signals that can be received by this process. This set of signals is commonly known as the valid input signal set of the process. Each signal is described by its name followed by an SDT reference to the definition of the signal.

 ConnectionOut
2
The names of the signalroutes that are on the outside of this process. Naturally, this attribute is only present when the process consists of services.

 ConnectionIn
2
The names of the signalroutes that are on the inside of this process. Naturally, this attribute is only present when the process consists of services.

 PROCESS_
INST

 InstRef
1
An SDT reference to the definition of this process instance.

 TypeRef
2
SDT references to process type definitions. The first reference is to the process type from which this process instance is instantiated followed by references to its supertypes all the way to the process type on top of the inheritance hierarchy.

 IniNoOfInst
1
The initial number of dynamic instances of this process instance.

 MaxNoOfInst
1
The maximum number of dynamic instances of this process instance. If this attribute is omitted it means that there is no upper limit on the number of dynamic instances.

 SignalSet
3
The signals that can be received by this process instance. This set of signals is commonly known as the valid input signal set of the process instance. Each signal is described by its name followed by an SDT reference to the definition of the signal.

 SAVE

 InstRef
1
An SDT reference to the definition of this save.

 InType
1
The name of the state-containing entity in which this save is defined.

 SERVICE

 InstRef
1
An SDT reference to the definition of this service.

 SERVICE_
INST

 InstRef
1
An SDT reference to the definition of this service instance.

 TypeRef
2
SDT references to service type definitions. The first reference is to the service type from which this service instance is instantiated followed by references to its supertypes all the way to the service type on top of the inheritance hierarchy.

 SIGNALROUTE

 InstRef
1
An SDT reference to the definition of this signalroute.

 SignalSet
3
The signals that are conveyed on this signalroute in the direction from the From-entity to the To-entity. Each signal is described by its name followed by an SDT reference to the definition of the signal.

 SignalSetRev
3
As SignalSet but for the signals that are conveyed in the opposite direction.

 From
1
The name of the process, process instance, service or service instance from which this signalroute starts. If the signalroute starts from the environment surrounding the block, block instance, process or process instance where this signalroute is located, this attribute is "env".

 FromVia
1
This attribute is specified when the From-entity is a process instance or a service instance, and is then the name of the gate of that process instance or service instance to which this signalroute is connected.

 To
1
The name of the process, process instance, service or service instance to which this signalroute leads. If the signalroute leads to the environment surrounding the block, block instance, process or process instance where this signalroute is located, this attribute is "env".

 ToVia
1
This attribute is specified when the To-entity is a process instance or a service instance, and is then the name of the gate of that process instance or service instance to which this signalroute is connected.

 START2

 InstRef
1
See the description for CONTINUOUS_ SIGNAL.

 InType
1
See the description for CONTINUOUS_ SIGNAL.

 Outputs
3
See the description for CONTINUOUS_ SIGNAL.

 Calls
3
See the description for CONTINUOUS_ SIGNAL.

 NextStates
3
See the description for CONTINUOUS_ SIGNAL.

 STATE

 InstRef
2
SDT references to the state symbols in the state-containing entity that contain the name of this state. If the state-containing entity is a process type, service type or procedure, occurrences in the supertypes are also included.

 SUBSTRUCTURE

 ConnectionOut
2
The names of the channels that are on the outside of this substructure.

 ConnectionIn
2
The names of the channels or signalroutes that are on the inside of this substructure.

 SYSTEM

 InstRef
1
An SDT reference to the definition of this system.

 SYSTEM_INST

 InstRef
1
An SDT reference to the definition of this system instance.

 TypeRef
2
SDT references to system type definitions. The first reference is to the system type from which this system instance is instantiated followed by references to its supertypes all the way to the system type on top of the inheritance hierarchy.
1

The name of a CONTINUOUS_SIGNAL entity is set to the priority of the continuous signal. If no priority has been specified, maximum priority is assumed and the name is then set to "MAX_PRIO".

2

The name of a START entity is always set to "Start".

Information about the entities is generated in pre-order (prefix walk in the instance tree). This means that an entity is always followed by the entities defined within itself.

A formal and complete description of the general format of an instance information file would be rather complex, and is beyond the scope of this text. Instead, see Example 332:

Example 332 : An instance information file

Consider the SDL system below:

System ExSystem;
Signal Sig(Integer), Inp;
channel ExChannel
from ExBlock to env with Sig;
from env to ExBlock with Inp;
endchannel ExChannel;
block ExBlock referenced;
endsystem ExSystem;

Block ExBlock;
signalroute ExSignalRoute
from ExProcess to env with Sig;
from env to ExProcess with Inp;
process ExProcess referenced;
connect ExChannel and ExSignalRoute;
endblock ExBlock;

Process ExProcess;
DCL Counter Integer;
procedure ExProcedure referenced;
start ;
task Counter := 0;
grst4:
nextstate Wait;
state Wait;
input Inp;
task {
Counter := call ExProcedure(Counter);
};
output Sig(Counter);
join grst4;
endstate;
endprocess ExProcess;

Procedure ExProcedure;FPAR a Integer;RETURNS ret Integer;
start ;
nextstate Idle;
state Idle;
input *;
task {
ret := a+1;
};
return ;
endstate;
endprocedure ExProcedure;

The instance information file for this SDL system will look like this:

SDTINST V1.0
1 SYSTEM ExSystem
InstRef = #SDTREF(TEXT,ExSystem.pr,1)
.
2 CHANNEL ExChannel
InstRef = #SDTREF(TEXT,ExSystem.pr,3)
SignalSet = (
Sig #SDTREF(TEXT,ExSystem.pr,2)
)
SignalSetRev = (
Inp #SDTREF(TEXT,ExSystem.pr,2)
)
From = ExBlock
To = env
.
2 BLOCK ExBlock
InstRef = #SDTREF(TEXT,ExSystem.pr,10)
ConnectionOut = (
ExChannel
)
ConnectionIn = (
ExSignalRoute
)
.
3 SIGNALROUTE ExSignalRoute
InstRef = #SDTREF(TEXT,ExSystem.pr,11)
SignalSet = (
Sig #SDTREF(TEXT,ExSystem.pr,2)
)
SignalSetRev = (
Inp #SDTREF(TEXT,ExSystem.pr,2)
)
From = ExProcess
To = env
.
3 PROCESS ExProcess
InstRef = #SDTREF(TEXT,ExSystem.pr,18)
IniNoOfInst = 1
SignalSet = (
Inp #SDTREF(TEXT,ExSystem.pr,2)
)
.
4 START Start
InstRef = #SDTREF(TEXT,ExSystem.pr,21)
InType = ExProcess
Nextstates = (
Wait #SDTREF(TEXT,ExSystem.pr,24)
)
.
4 STATE Wait
InstRef = (
#SDTREF(TEXT,ExSystem.pr,25)
)
.

5 INPUT Inp
InstRef = #SDTREF(TEXT,ExSystem.pr,26)
InType = ExProcess
Outputs = (
Sig #SDTREF(TEXT,ExSystem.pr,30)
)
Calls = (
ExProcedure #SDTREF(TEXT,ExSystem.pr,28)
)
Nextstates = (
Wait #SDTREF(TEXT,ExSystem.pr,24)
)
.
4 CALLED_PROCEDURE ExProcedure
InstRef = #SDTREF(TEXT,ExSystem.pr,20)
.
5 START Start
InstRef = #SDTREF(TEXT,ExSystem.pr,36)
InType = ExProcedure
Nextstates = (
Idle #SDTREF(TEXT,ExSystem.pr,37)
)
.
5 STATE Idle
InstRef = (
#SDTREF(TEXT,ExSystem.pr,38)
)
.
6 INPUT Inp
InstRef = #SDTREF(TEXT,ExSystem.pr,39)
InType = ExProcedure
Nextstates = (
return #SDTREF(TEXT,ExSystem.pr,43)
)
.


Error Handling

Errors may be detected both during interaction with the user (command interpretation) and during analysis. Errors are displayed on the screen and optionally appended to an error file supplied by the user. When using the graphical UI, messages are directed to the Organizer log window.

Command Interpretation Errors

Errors that occur during command interpretation are errors due to:

  • Illegal command parameters. See "Syntax of Analyzer Commands" .
  • Problems with accessing files on your computer system.

Diagnostics Issued During Analysis

Errors may be found during the various steps of the analysis. The different types of diagnostics and the format of the messages are described below. The messages are listed in "Error and Warning Messages" .

Diagnostic Types

Errors can be of the following types: warning, error, internal error, and information.

Warning

There are different types of warnings:

  • Warnings that truncation has been performed, because the implementation limits have been exceeded.
  • Warnings due to non implemented portions of the Analyzer.
  • Warnings due to a badly designed SDL construction that is not essential for the interpretation.
  • Warnings due to analysis actions that were not performed because the Analyzer could not recover from errors in previous analysis steps.

Error

One type of error is detected; violation of an SDL rule.

Internal Error

Internal errors due to malfunction of the Analyzer are detected. An internal error often has its roots in an SDL error from which the Analyzer did not recover properly.

Information

Often used to provide additional information to the other types of messages.

Diagnostic Format

Messages generally consist of the following parts:

  • A reference to the source code that caused the diagnostic to be reported. See "Syntax" .
  • The type of the diagnostic (ERROR / WARNING / INFO).
  • A number identifying the diagnostic.
  • A message describing the diagnostic.

Example of a Syntax Error

The message describing the error includes a text line where the illegal construct is indicated with a "?". If the trace back is common to many lexical or syntactic errors, the trace back will only occur after the last of these error messages.

The error also contains a reference to the source file.

Example 333 : Syntax Error Produced by Analyzer

#SDTREF(SDL,/usr/tom/game.spr(1),137(30,40),1,11)
ERROR 312 Syntax error in rule VARIABLE, symbol = found but one of the following
expected:
! ( :=
task Count=0 ;
?

The interpretation of the error message is that the Analyzer found the symbol "=" when it expected one of the symbols "!" (the field selector), "(" or ":=".

In the current example, the assignment statement can be found in position 11 the first line in the object with the ID 137 at position (30, 40) on page 3, on page 1 in the diagram stored on file /usr/tom/game.spr.

Example of a Semantic Error

The message describing the error includes, if possible, a line containing the error, with a "?" immediately preceding the SDL item that caused the error.

The error also contains a reference to the source file.

Example 334 : Semantic Error Produced by Analyzer

#SDTREF(SDL,/usr/tom/game.spr(1),296(55,40),1)
ERROR 88 Undefined procedure
call ? ErrorHandler

The interpretation of this error message is that the procedure ErrorHandler is referred to but not is defined, and the call can be found in page 1 of the diagram stored on the on file /usr/tom/game.spr, in line 1 of the object with ID 296 and at position (55, 40).


Analyzer Files

When a diagram is being analyzed, a number of files are generated. The file names consist of the diagram name appended with a file name extension. The following file name extensions are used:

  • .pr
    The SDL/PR, (also known as phrasal representation), of the SDL diagram. This file is generated by the conversion to PR pass. The purpose of this file is an intermediate format for the Analyzer. The format used in this file makes it not suitable to be read by the human.
  • .prm
    After macros are expanded, the .pr file is used as input and expanded into a .prm file, which includes the SDL macros in an expanded form. The appearance of this file makes it not suitable to be read by the human.
  • .sdl
    The pretty-printed SDL/PR file which is generated by the pretty-printer. This file uses a layout that is easy to read by the human.
  • .err
    The error file containing the errors and warnings which were detected during the analysis.
  • .xrf
    The files containing the listings of SDL definitions and cross-references.
  • .tsp
    The file contains time stamp information from the last analysis.
  • .ins
    The file containing instance information about the analyzed SDL system. Read more about the contents of this file in "SDL Instance Information" .
  • predef.sdl
    This file contains predefined SDL entities that the Analyzer needs access to in order to function properly. The file is found using the procedure in "Search Order for Included PR Files" with the directory $sdtdir.


Error and Warning Messages

This section contains a list of the Analyzer error and warning messages. Each message has a short explanation and, where applicable, a reference to the appropriate section of the recommendation Z.100, or to the formal definition. Z.100 is appended by the Formal Definition of SDL (Annex F.1-F.3) where a formal mathematical definition of the language is given.

Some messages contain a `%' followed by a number, which is used to indicate where information, specific to the error situation, will be included.

Some messages include a reference to the object that is the source of the diagnostic. These messages adhere to the format adopted in the SDL suite. See 19 SDT References for a reference to this format and for examples.

INFO 0 Internal error: message %1 not found

This message indicates an error in the implementation of the Analyzer. Please send a report to Telelogic Customer Support, especially if the error can be reproduced as the only error message of an analysis. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 1 Internal error

This message indicates an error in the implementation of the Analyzer. Please send a report to Telelogic Customer Support, especially if the error can be reproduced as the only error message of an analysis. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 2 Cannot open file: %1

This error message indicates that an error occurred when the Analyzer attempted to open a file. Modify, if necessary, the file protection and try to run the Analyzer again. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 3 Cannot close file: %1

This error message indicates that an error occurred when the Analyzer attempted to close a file. Modify, if necessary, the file protection and try to run the Analyzer again. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 4 Cannot delete file: %1

This error message indicates that an error occurred when the Analyzer attempted to delete a file. Modify, if necessary, the file protection and try to run the Analyzer again. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 5 Cannot rename file: %1 to %2

This error message indicates that an error occurred when the Analyzer attempted to rename a file. Modify, if necessary, the file protection and try to run the Analyzer again. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 6 Recursive definition of signal list %1

A signal list must not be based on itself, directly or indirectly.
(Z.100: 2.5.5)

ERROR 7 More than one %1 is visible in Packages

Several definitions with same name were found in a package. A qualifier might resolve the problem.
(Z.100: 2.4.1.2)

ERROR 8 Ending identifier (%2) must be equal to defining identifier (%1) in a referenced definition

When writing a definition, the name must be the same on the last row as on the first row.
(Z.100: 2.2.2)

ERROR 9 Referenced definitions are not unique (%1)

There are more than one definition which matches the reference.

You get this error if:

  • You use the same diagram name for two different diagram references in one diagram.

To remove the error:

  • Rename one of the referenced diagrams.

(Z.100: 2.4.1.3)

ERROR 10 Number of instances must be lexically equal in referenced process definition and process reference

(Z.100: 2.4.4)

ERROR 11 Different virtuality attributes in reference and referenced heading

(Z.100: 6.3.2)

ERROR 12 A referenced definition may not reference itself

It is not allowed to have a reference to itself in the reference definition.
(Z.100: 2.4.1.3)

ERROR 13 No referenced definition matches reference

A reference is found but not the corresponding definition.

You get this error if:

  • You define a diagram as REFERENCED, but do not give a non-referenced definition of the diagram later.

To remove the error, either:

  • Add a non-referenced diagram definition.
  • Remove the diagram reference.

(Z.100: 2.4.1.3)

ERROR 14 Virtual start not allowed in operator definition

It is not allowed to have the start as virtual in an operator definition.

You get this error if:

  • You use the keyword VIRTUAL for the start transition in an operator.

To remove the error:

  • Remove the VIRTUAL keyword from the start transition.

(Z.100: 5.3.2)

INFO 15 Required item %1 is not connected to a file

The Organizer has ordered to analyze something depending on a diagram that is not connected to a file.

ERROR 16 Input %1 and output %2 should be different, aborting!

An Analyzer pass requires the input and output files to be different. Specify other input and/or output files.

ERROR 17 Definition name may not be qualified when not a referenced definition

A qualifier is only allowed on a definition if it is a referenced definition.

You get this error if:

  • You use a qualifier when defining a diagram in place, i.e. without using the REFERENCED keyword.

To remove the error, either:

  • Remove the qualifier.
  • Use the keyword REFERENCED and move the definition of the child diagram out of the parent diagram.

(Z.100: 2.4.1.3)

ERROR 18 Referenced definition (%1) is not referenced in the Package definition

A reference to the definition (%1) is missing in the package definition.
(Z.100: 2.4.1.3)

ERROR 19 Referenced definition (%1) is not referenced in the system definition

A reference to the definition (%1) is missing in the system definition.

You get this error if:

  • You define a diagram outside the SDL system but do not reference it from the SDL system.

To remove the error, either:

  • Introduce a reference construct in the SDL system to the diagram.
  • Remove the unwanted diagram.

(Z.100: 2.4.1.3)

ERROR 20 Invalid separate analysis unit

It is not allowed to make a separate analysis of the unit selected. Start the analysis on the whole specification instead.

ERROR 21 Referenced substructure definition without name

It is not allowed to have a substructure without a name when referencing it or converting it to SDL/GR.
(Z.100: 3.2.2, 3.2.3)

ERROR 22 System definition may not occur as referenced definition to a system

Only system types may be referenced, not systems.
(Z.100: 2.4.1.3)

ERROR 23 Illegally placed process context parameter

A process context parameter is used where it is not allowed. Examples of bad use is in a system type or in a block type.
(Z.100: 6.2, 6.1.1.1, 6.1.1.2)

ERROR 24 Illegally placed procedure context parameter

A procedure context parameter is used where it is not allowed.
(Z.100: 6.2)

ERROR 25 Illegally placed signal context parameter

A signal context parameter is used where it is not allowed.
(Z.100: 6.2)

ERROR 26 Illegally placed timer context parameter

A timer context parameter is used where it is not allowed. For example in a system type, block type or service type.
(Z.100: 6.2, 6.1.1.1, 6.1.1.2, 6.1.1.4)

ERROR 27 Illegally placed variable context parameter

A variable context parameter is used where it is not allowed. For example in a system type or block type.
(Z.100: 6.2, 6.1.1.1, 6.1.1.2)

ERROR 28 Illegally placed synonym context parameter

A synonym context parameter is used where it is not allowed. For example in a signal.
(Z.100: 6.2, 2.5.4)

ERROR 29 Illegally placed remote procedure context parameter

A remote procedure context parameter is used where it is not allowed.
(Z.100: 6.2)

ERROR 30 Illegally placed remote variable context parameter

A remote variable context parameter is used where it is not allowed.
(Z.100: 6.2)

ERROR 31 Illegally placed sort context parameter

A sort context parameter is used where it is not allowed.
(Z.100: 6.2)

ERROR 32 Illegal redeclaration of name

All definitions in the same scope unit belonging to the same entity class must have different names, with some exceptions.

You get this error if:

  • You use the same name as another item when declaring a new item.

To remove the error, either:

  • Change one of the names in all appropriate places.
  • Remove one of the declarations if the intention was to use the same variable.

(Z.100: 2.2.2)

ERROR 33 Illegally placed gate definition

A gate is defined where it is not allowed.
(Z.100: 6.1.4)

ERROR 34 %1 is not a time stamp file, will not save time stamps

On successful analysis the Analyzer saves info about this. Examine the file and rename or delete it to allow the Analyzer to save time stamps and possibly avoid unnecessary reanalysis in the future.

ERROR 35 Invalid regular interval

The character strings in a nameclass must be of length one and the first one smaller than the second.
(Z.100: 5.3.1.14)

ERROR 36 Integer literal expected

The name in the priority clause of a continuous signal must be an integer literal. This is also true for the name following a regular element in a name class literal.

You get this error if:

  • You type something that is not an integer in a place where an integer is expected.

To remove the error:

  • Replace the non-integer with an integer.

(Z.100: 4.11, 5.3.1.14)

ERROR 37 Invalid generator parameter %1

The actual generator parameter must match the type of the formal one.
(Z.100: 5.3.1.12.2)

ERROR 38 Illegal number of arguments

The number of actual parameters must be equal to the number of formal parameters when calling a procedure or creating a process. Similar rules apply for output, input and save of signals and timers.

ERROR 39 More than one default assignment; last from generator %1

A sort must not contain more than one default assignment. When instantiating many generators in a sort, only one of them may contain a default assignment.
(Z.100: 5.4.3.3)

ERROR 40 Recursive instantiation of generator %1

A generator definition must not instantiate itself, directly or indirectly.
(Z.100: 5.3.1.12.1)

ERROR 41 Undefined generator

Attempt to instantiate an undefined generator.
(Z.100: 5.3.1.12.2)

ERROR 42 No virtual definition %1 in super of enclosing definition

It is only allowed to redefine or finalize a definition if it is defined as virtual in the inherited type.

You get this error if:

  • You are trying to redefine an entity that is not declared as VIRTUAL in the super type.

To remove the error, either:

  • Make sure you are trying to redefine the correct entity.
  • Make sure that there is a virtual entity to redefine in the super type.

(Z.100: 6.3.2)

ERROR 43 Ordering must not be defined more than once

All operator signatures in a sort must be different (ordering is shorthand for the relational operators).
(Z.100: 5.3.1.8)

ERROR 44 Name of formal parameter of class type must not equal name of generator %1

A generator must not have a formal parameter of class type with the same name as the generator definition.
(Z.100: 5.3.1.12.1)

ERROR 45 Formal generator parameters of classes literal and constant mixed

Literal and constant parameters must not have the same name.
(Z.100: 5.3.1.12.1)

ERROR 46 Only task, decision and transition option allowed in operator definition

You get this error if:

  • You try to include signal sending in an operator.

To remove the error:

  • Remove the signal sending.

(Z.100: 5.3.2)

ERROR 47 Only Join and Return allowed in operator definition

(Z.100: 5.3.2)

WARNING 48 Ending name (%1) in an asterisk state may lead to an error

The optional state name ending a state may be defined only if the state list is a single state name, in which case the ending state name should be that state name. The state list for an asterisk state is probably more than a single state name.
(Z.100: 2.6.3)

ERROR 49 A state with more than one state name in the state list cannot contain an ending name (%1)

The optional state name ending a state may be defined only if the state list is a single state name, in which case the ending state name should be that state name.
(Z.100: 2.6.3)

ERROR 50 Ending name (%2) must be equal to defining name (%1)

You get this error if:

  • You use different names for a definition at the beginning and at the end of the same definition.

To remove the error, either:

  • Change the name either at the beginning or at the end of the definition to get the same name in both places.
  • Remove the optional name at the end.

(Z.100: 2.2.2, 2.6.3)

ERROR 51 Illegally placed virtuality

Virtual is used in a place where it is not allowed.

You get this error if:

  • You use the keyword VIRTUAL for a transition that is not inside a type-based diagram.

To remove the error, either:

  • Remove the VIRTUAL keyword from the transition.
  • Make the diagram a type-based diagram.

ERROR 52 Illegally placed context parameter

The context parameter is placed where it is not allowed.
(Z.100: 6.2)

ERROR 53 Illegally placed virtuality constraint

The virtuality constraint is placed where it is not allowed.

You get this error if:

  • You use the ATLEAST keyword for a type-based diagram that is not placed inside a type-based diagram.

To remove the error, either:

  • Remove the ATLEAST construct.
  • Move the type-based diagram with the ATLEAST construct to a type-based diagram.
  • Make the diagram containing the type-based diagram with the ATLEAST construct a type-based diagram too.

ERROR 54 Illegally placed specialization

The specialization is placed where it is not allowed.

ERROR 55 Illegally placed instantiation

The instantiation is placed where it is not allowed.

ERROR 56 Packages can only contain type definitions

Systems, blocks, processes and services are not allowed, but their corresponding type are.
(Z.100: 2.4.1.2)

ERROR 57 Undefined package %1 in use clause

An used package is not defined. This error may also occur if you have two mutually dependent packages, which is not allowed. If you use ASN.1 modules or C headers, it may also occur if there are no dependency links between these and the SDL system.

You get this error if:

  • You try to use a package that has not yet been declared.

To remove the error, either:

  • Add a package definition named %1.
  • Remove the use of the package.

ERROR 58 Illegally placed exported attribute

The exported attribute is placed where it is not allowed.

ERROR 59 Omitted actual context parameter

(Z.100: 6.2)

ERROR 60 Parameterized type %1 cannot be used as actual context parameter

A type with context parameters is not allowed to be used as an actual context parameter.
(Z.100: 6.2)

ERROR 61 Undefined actual context parameter

The actual context parameter is undefined or is not visible.
(Z.100: 6.2)

ERROR 62 Illegal number of actual context parameters (>)

(Z.100: 6.2)

ERROR 63 Illegal number of actual context parameters (<)

(Z.100: 6.2)

ERROR 64 Illegal number of actual context parameters (0)

(Z.100: 6.2)

ERROR 65 Formal context parameter %1 cannot be used as super type

It is not allowed to specialize a formal context parameter.
(Z.100: 6.2)

ERROR 66 Several matches

Resolution by context found several possible interpretations, use qualifiers to reduce the number of possibilities.
(Z.100: 2.2.2)

ERROR 67 No matching synonym or literal

You get this error if:

  • You are using a synonym or literal of the wrong type. For instance, a constant expression of type integer may be required, but you supply a value of type real.

To remove the error, either:

  • Replace the synonym or literal with a constant expression of the correct type.
  • Define a synonym or literal of the correct type.

(Z.100: 2.2.2)

WARNING 68 Optional parameter of sort %1 omitted

A missing parameter may lead to uninitialized values, make sure it is not left out by mistake.

You get this warning if:

  • You omit an IN parameter in a procedure call.

To remove the warning, either:

  • Supply a constant value or a variable to the parameter in the procedure call.
  • Remove the parameter from the procedure and from all calls to the procedure.

WARNING 69 Implicit remote variable, consider making it explicit

ERROR 70 Invalid import expression

The import identifier in an import expression is erroneous.

You get this error if:

  • You use an integer where a boolean is expected.

To remove the error, either:

  • Use a boolean value instead.
  • Make the expected value an integer.

(Z.100: 4.13)

ERROR 71 Signal %1 is shadowed in connection

You get this error if:

  • You have multiple declarations of a signal (same name) and two channels or signal routes that are connected uses different versions of a carried signal.

To remove the error, either:

  • remove the inner declaration of the signal
  • Rename one of the signals and determine which one the channels or signal routes in the connection should use.

ERROR 72 Invalid variable or attribute of variable

Reference to a nonexisting variable or a variable with illegal type or attribute from a view definition, a view expression or an export action.

You get this error either if:

  • You EXPORT a variable that is not visible from the current scope.
  • You EXPORT a variable that is not defined as EXPORTED.

To remove the error, either:

  • Find the correct name of the variable you want to export.
  • Make sure that the variable you want to export is defined as EXPORTED.

ERROR 73 Illegal use of parameterized signal

This message is output when context parameters are used in an SDL structure. Context parameters are not supported.

ERROR 74 Illegal use of parameterized sort

This message is output when context parameters are used in an SDL structure. Context parameters are not supported.

ERROR 75 Undefined timer

Use of an undefined timer in set, reset or active.

You get this error if:

  • You are referring to a timer that has not been declared.

To remove the error, either:

  • Declare the timer.
  • Refer to an already existing timer instead.

(Z.100: 2.8)

ERROR 76 No range condition equals true in transition option

Exactly one of the branches out from a transition option must be true.

You get this error if:

  • There is no alternative in a transition option that evaluates to true.

To remove the error, either:

  • Change the condition for taking one of the alternatives to make sure that one alternative is always taken.
  • Add a new alternative with a condition that evaluates to true.

(Z.100: 4.3.4)

ERROR 77 Undefined sort

A sort which is not defined is referenced.

You get this error if:

  • You use a sort that has not been defined.

To remove the error, either:

  • Use another sort that is already defined.
  • Define the sort.

(Z.100: 2.2.2)

ERROR 78 Error not allowed where constant required

You get this error if:

  • You use SDL keyword error in an expression required to be constant.

To remove the error:

  • Replace the SDL keyword error with something else.

(Z.100: 5.3.9.1, 5.4.2.1)

ERROR 79 Variable expected

A variable was expected at this place.

You get this error either if:

  • You use a constant value or an operator on the left side of the assignment.
  • You give a constant value or the value of an operator instead of a variable as an actual parameter in a procedure call, when the corresponding formal parameter is an IN/OUT parameter.

To remove the error in the above cases, either:

  • Use a variable on the left side of the assignment instead.
  • Use a variable as an actual parameter in the procedure call instead.

You also get this error either if:

  • You call a procedure using a constant as an actual in/out parameter.
  • You call a procedure without specifying a parameter that is an in/out parameter.

To remove the error in the above cases, either:

  • Change the constant or the not specified parameter to a variable of the correct type instead.
  • Change the procedure to accept an in parameter instead of an in/out parameter.

(Z.100: 2.4.6)

ERROR 80 In parameter expected

An in parameter was expected according to the definition.

You get this error if:

  • You are using an IN/OUT parameter in an imported procedure signature that should match an IN parameter in a remote procedure signature.

To remove the error, either:

  • Change the imported procedure signature to use an IN parameter instead.
  • Change the remote procedure signature to use an IN/OUT parameter instead.

ERROR 81 Unexpected parameter

The parameter should not be there according to the definition.

You get this error either if:

  • You supply a parameter when you create a process that is not defined in an FPAR statement in the process definition.
  • You add an extra parameter or return value to an imported procedure signature that should match a remote procedure signature.

To remove the error, either:

  • Remove the extra parameter or return value.
  • Add the extra parameter or return value to the definition of the called or created entity.

ERROR 82 Start transition required in instantiated type %1

An instantiated type must contain a start transition.

You get this error if:

  • You try to instantiate a process type or a service type that has no start transition.

To remove the error, either:

  • Instantiate a process type or a service type that has a start transition instead.
  • Add a start transition to the process type or the service type.

ERROR 83 Start transition required in called procedure

You get this error if:

  • You call a procedure that does not have a start transition.

To remove the error:

  • Add a start transition to the procedure definition.

(Z.100: 2.4.6)

ERROR 84 Procedure call not allowed where constant required

You get this error if:

  • You call a procedure in a place where a constant is required, such as in a variable or synonym definition.

To remove the error, either:

  • Assign the variable a constant value in the variable definition.
  • Assign the variable the return value of a procedure call in the start transition instead.

(Z.100: 5.3.1.9.1)

ERROR 85 Parameterized procedure cannot be called

(Z.100: 6.1.2)

ERROR 86 PId Expression or Process Identifier expected

An PId expression or a process identifier was expected at this place.

You get this error if:

  • You supply a second parameter to import, but it is not a pid expression or a process identifier.

To remove the error, either:

  • Change the second parameter to a pid expression or a process identifier.
  • Remove the second parameter if it is not needed.

ERROR 87 Pid expression in procedure call only allowed for remote procedures

It is only allowed to have PId expressions in a procedure call if the procedure is a remote procedure.

You get this error if:

  • You are using the TO keyword in a call to a procedure that is not remote and imported.

To remove the error, either:

  • Remove the TO construct from the procedure call, if it is a normal procedure residing in this process.
  • Make the procedure a REMOTE procedure in the other process, and declare the procedure as IMPORTED in this process.

(Z.100: 2.7.3, 4.14)

ERROR 88 Undefined procedure

Attempt to call an undefined procedure.

You get this error if:

  • You call a procedure that is not defined or not visible from the current scope.

To remove the error, either:

  • Make an existing procedure with the correct name visible from the current scope.
  • Create an appropriate procedure if it does not exist.

(Z.100: 2.2.2, 2.7.3)

WARNING 89 Trailing parameter of sort %1 omitted

A missing parameter may lead to uninitialized values, make sure it is not left out by mistake.

ERROR 90 Two range conditions equals true in transition option

The branches out from a transition option must be mutually exclusive.

You get this error if:

  • You have two alternatives in a transition option that are both evaluated to be true.

To remove the error, either:

  • Change the condition for taking one of the alternatives to make sure that only one alternative is taken.
  • Remove one of the alternatives that evaluated to true.

(Z.100: 4.3.4)

INFO 91 Location of the global definition previously mentioned

ERROR 92 Undefined remote variable

Attempt to use an undefined remote variable.

You get this error if:

  • You use a remote variable that has not been defined.

To remove the error, either:

  • Use another remote variable that is already defined
  • Define the remote variable.

(Z.100: 4.13)

ERROR 93 Label expected on first item in free action

(Z.100: 2.6.7)

ERROR 94 Formal parameters required in operator definition

The operator definition must have formal parameters.

You get this error if:

  • You have defined an operator that is missing a FPAR statement.

To remove the error:

  • Introduce an FPAR statement in the definition of the operator.

(Z.100: 5.3.2)

ERROR 95 Recursive definition of parent sort %1 in syntype

A syntype must not be based on itself, directly or indirectly.

You get this error if:

  • You define a syntype X that equals a syntype Y that equals syntype X.

To remove the error:

  • Make sure that syntypes not equals each other in a circular chain, and that one syntype equals a non-syn-type.

(Z.100: 5.3.1.9)

INFO 96 Setlocale failed

The Analyzer failed to set the character handling part of the locale. It will remain in the default C locale.

ERROR 97 Undefined signallist

ERROR 98 New literal %1 must only occur once in literal renaming

All literals renamed in an inheritance must be given unique names.

You get this error if:

  • You are declaring a newtype that inherits from another type, and renames two or more old literals to the same new name.

To remove the error:

  • Make sure to use unique names for all renamed literals.

(Z.100: 5.3.1.11)

ERROR 99 Old literal %1 must only occur once in literal renaming

A literal must only be renamed once when inheriting.

You get this error if:

  • You are renaming literals in a newtype that inherits from a super newtype, and the old literal names occur more than once in the list of renamings.

To remove the error:

  • Make sure that the same old literal name only occurs once on the right side of the assignment in the list of renamings.

(Z.100: 5.3.1.11)

ERROR 100 Illegal redeclaration of operator signature

It is not allowed to have several operators with the same signature. This error may also occur if you use the same name twice in a sort with implicit operators, for example "structure".

ERROR 101 Unexpected remote variable

Remote variable may not be used in [priority] input.

You get this error if:

  • You are using a remote variable in a way that is not allowed, for instance as if it was a normal signal in an input construct.

To remove the error, either:

  • Use the remote variable in a proper way instead: to update the value of the remote variable, use an IMPORT construct instead of trying to receive the value as if it was a signal.
  • Change the remote variable to another more proper type for the intended use.

ERROR 102 Expression(s) in number of instances evaluates to error

(Z.100: 2.4.4)

ERROR 103 More than one sub signal is visible

You get this error if:

  • You have two or more REFINED signals with the same name that is visible from the current place.

To remove the error:

  • Rename (or remove) one of the REFINED signals, to get unique names.

(Z.100: 3.3)

ERROR 104 Undefined signal, timer, signallist, remote procedure or remote variable

No visible definition with proper entity kind found.
(Z.100: 2.2.2)

ERROR 105 Remote procedure definition missing

A definition of the remote procedure is missing.

You get this error if:

  • You are referring to a procedure with an IMPORTED construct, but the procedure does not exist or is not defined as REMOTE.

To remove the error:

  • Make sure there is a REMOTE definition of the procedure you are referring to in the IMPORTED construct.

ERROR 106 Recursive definition of synonym

The value of a synonym must not be based on itself, directly or indirectly.

ERROR 107 Gate must be connected

You get this error if:

  • You instantiate a type without connecting all it's gates.

To remove the error:

  • Connect the gate.

(Z.100:6.1.4)

ERROR 108 Type mismatch for variable or formal parameter

ERROR 109 Signal refinement is not supported

ERROR 110 Only one varargs allowed

ERROR 111 Unexpected return value

The procedure has to be value returning to use return values.

ERROR 112 Return value expected

A value returning procedure must specify a return value.

You get this error if:

  • You are returning from a procedure without specifying a return value, when the procedure is expected to return a value because of a RETURNS construct in the procedure heading.

To remove the error, either:

  • Supply a return value in the RETURN construct.
  • Remove the RETURNS construct from the procedure heading and remove any returned values from all RETURN constructs in the same procedure.

ERROR 113 Undefined state %1

A nextstate contains a name of a state which is not defined.
(Z.100: 2.6.7.2.1)

ERROR 114 Undefined label %1

Attempt to join an undefined label (connector).
(Z.100: 2.6.8.2.2)

ERROR 115 Open range does not match

A range condition does not match the actual context.
(Z.100: 5.3.1.9.1)

ERROR 116 Inherited operator %1 is not visible

Operators containing an exclamation cannot be inherited (and renamed).

You get this error if:

  • You declare a newtype that inherits an operator that cannot be found in the current scope.

To remove the error in the above cases, either:

  • Check that you are using the correct name for the operator.
  • Declare the operator.

You also get this error if:

  • You have a newtype that inherits from a super newtype, and you try to inherit an operator from the super newtype that does not exist.

To remove the error in the above case, either:

  • Make sure that the name of the operator you wants to inherit is correct.
  • Remove the name of the non-existing operator from the list of inherited operators.

(Z.100: 5.3.1.11)

ERROR 117 Old operator name %1 must only occur once in operator renaming

An operator must only be renamed once when inheriting.

You get this error if:

  • You use the same name for the old operator name and the new operator name.

To remove the error:

  • Use a new name instead of reusing the old name.

(Z.100: 5.3.1.11)

ERROR 118 New operator name %1 must only occur once in operator renaming

All operators renamed in an inheritance must be given unique names.

You get this error if:

  • You use the same new operator name for several old operator names.

To remove the error:

  • Make sure to use unique names for every new operator name.

(Z.100: 5.3.1.11)

ERROR 119 Inheritance for %1 is circular

You get this error if:

  • You have created a circular chain of diagram inheritance.

To remove the error:

  • Break the chain of circular inheritance by removing or changing the super diagram for one of the diagrams in the chain.

(Z.100: 6.3.1)

ERROR 120 Atleast constraint for %1 is circular

(Z.100: 6.3.2)

ERROR 121 Recursive sort inheritance

A sort must not inherit from itself, directly or indirectly.

You get this error if:

  • You have created a circular chain of newtype inheritance.

To remove the error:

  • Break the chain of circular inheritance by removing or changing the super newtype for one of the newtypes in the chain.

(Z.100: 5.3.1.11)

ERROR 122 Unexpected connect statement

A connect statement was not supposed to be found at this place.

INFO 123 %1 is one of the possible matches

ERROR 124 Signal expected in output

An output must contain at least one signal.

You get this error if:

  • You are trying to send something from a process that is not a signal, such as a timer.

To remove the error, either:

  • Change the name in the output construct to match a visible signal instead.
  • Supply the value or variable that you were trying to send as a parameter to a signal.

(Z.100: 2.7.4)

ERROR 125 Undefined channel or signal route in output via

Identifiers used in a via clause of an output must be visible channels or signal routes.

You get this error if:

  • You use a name of a non-existing channel or signal route after a VIA keyword in a signal sending.

To remove the error, either:

  • Find a correct channel or signal route name and use that instead.
  • Add the channel or signal route that you references in the VIA construct.
  • Remove the VIA construct, if the VIA construct is not needed and the signal sending path can be determined uniquely anyway.

(Z.100: 2.7.4)

ERROR 126 Set with no time expression is only allowed for timers with default duration

It is only allowed to omit the time expression in set if there is a default duration specified for the timer.

You get this error if:

  • You try to set a timer that does not have a default duration without specifying a duration in the SET construct.

To remove the error, either:

  • Add a default duration to the timer definition:
    TIMER myTimer:=10    .
  • Specify a time in the SET construct: SET(Now+10, myTimer).

(Z.100: 2.8)

ERROR 127 Set must contain a time expression and a timer id

When using set you must specify when the timer should expire and which timer to set.
(Z.100: 2.8)

ERROR 128 Undefined process

Attempt to create an undefined process.

You get this error if:

  • You are trying to create a process that has not been defined.

To remove the error, either:

  • Check that you are using the correct name for the process that you want to create.
  • Add a process definition of the process you want to create.
  • Remove the process creation construct.

(Z.100: 2.2.2, 2.7.2)

ERROR 129 Created process must belong to the partition block %1

It is only allowed to create a dynamic instance of a process type if the process type definition is in the same block.

You get this error if:

  • You try to create a process instance in another block than the block that the creating process resides in.

To remove the error:

  • Make sure that the creating process and the process to be created resides in the same block diagram.
  • Make sure that the creating process uses the correct name for the process to be created.

(Z.100: 2.7.2, FD)

ERROR 130 Remote procedure input and signal list input must not have parameters

It is not allowed to have parameters in a remote procedure input or when inputting a signal list.

You get this error if:

  • You try to receive parameters by using a pair of parenthesis characters when referring to a remote procedure or a signal list in an INPUT construct.

To remove the error, either:

  • Replace the remote procedure or the signal list with ordinary signals
  • Remove the parameters and the associated pair of parenthesis characters.

(Z.100: 4.14)

WARNING 131 %1 : Signal not used in input or output

The defined signal has neither been used in an input nor in an output.

ERROR 132 Invalid procedure call

Expressions in Enabling condition and continuous signal must not contain procedure calls.

You get this error if:

  • You are calling a procedure in an inappropriate place, such as in the expression related to a continuous signal.

To remove the error:

  • Remove or move the procedure call from the inappropriate place.

ERROR 133 State name %1 in asterisk state list must be contained in other state lists

The state names used within the parenthesis (the exceptions) of an asterisk state must be defined somewhere in the enclosing body or the body of a supertype.

You get this error if:

  • You include a name of a non-existing state in the list of exceptions after an asterisk (i.e. for all states) state.

To remove the error, either:

  • Check that you are using the correct name for the state that should be excepted.
  • Remove the unwanted exception.
  • Introduce the missing state in your state machine.

(Z.100: 4.4)

ERROR 134 No state left to expand the asterisk with

The asterisk state list in the asterisk state includes all states in the enclosing process/procedure/service body.

You get this error if:

  • You are using an asterisk (i.e. for all states) state that is representing zero states.

To remove the error, either:

  • Make sure that you are not doing exceptions to the asterisk state for all states in the state machine.
  • Replace the asterisk state with a normal state not using an asterisk.

(Z.100: 4.4)

ERROR 135 At least one state list must be different from asterisk

A process/procedure/service body cannot only contain asterisk states.

You get this error if:

  • You only have asterisk states in the state machine.

To remove the error:

  • Make sure that you have at least one non-asterisk state in the state machine.

(Z.100: 4.4)

ERROR 136 Several virtual continuous signals in a state with same or no priority

It is not possible to tell which transition would be affected by a redefinition.

You get this error if:

  • You have several virtual continuous signals in the same state with the same priority.

To remove the error, either:

  • Remove one of the virtual continuous signals.
  • Give one of the virtual continuous signals another priority.

(Z.100: 6.3.3)

ERROR 137 Virtual continuous signal is virtual in super type with same or no priority

It is not possible to tell which transition would be affected by a redefinition.

You get this error if:

  • You have a virtual continuous signal in both the sub type and the super type and the priority is the same or no priority is given.

To remove the error, either:

  • Make the continuous signal in the sub type REDEFINED or FINALIZED instead of VIRTUAL.
  • Give different priority to the continuous signal in the sub type than the priority in the super type.

(Z.100: 6.3.3)

ERROR 138 Redefined continuous signal is not virtual in super type with same or no priority

Cannot find the transition to redefine.

You get this error if:

  • You redefine a continuous signal transition in a sub type and the same continuous signal transition cannot be found in a super type with the same priority.

To remove the error, either:

  • If you intend to redefine an existing continuous signal, make sure the continuous signal you are redefining is starting from the same state and have the same priority.
  • If you do not want to redefine an existing continuous signal, remove the REDEFINED or FINALIZED keyword.

(Z.100: 6.3.3)

ERROR 139 Filter exited with error code

A filter program terminated with a non zero exit code.

ERROR 140 External procedure not allowed

An external procedure cannot be mentioned in a <type expression>, in a <formal context parameter> or in an <atleast constraint>.

You get this error if:

  • You try to use an external procedure where only a normal procedure is allowed.

To remove the error, either:

  • Use a normal procedure instead of the external procedure.
  • Make the external procedure a normal procedure.

ERROR 141 Number of block instances not allowed

Number of block instances may only be specified in typebased block definitions.
(Z.100: 6.1.3.3)

ERROR 142 No diagram to put definition in

It is not possible to convert something to a text symbol in SDL/GR without a surrounding diagram.

ERROR 143 Start is already defined in super type

It is not allowed to have more than one start transition and a start transition is already defined in the inherited type.

You get this error if:

  • You redefine a transition from a super type without using the keyword REDEFINED or FINALIZED.

To correct the error, either:

  • Use the keyword REDEFINED or FINALIZED for the redefined transition, if you intend to redefine the transition; make sure that the transition you redefine is either marked with VIRTUAL or REDEFINED.
  • Remove the definition from the sub type if you do not intend to redefine it.

(Z.100: 2.6.2, 6.3)

ERROR 144 Start is defined as finalized in super type

It is not allowed to define the start transition as redefined, since it is defined as finalized in the inherited type.

You get this error if:

  • You are trying to REDEFINE or FINALIZE the start transition in a sub type when it is declared as FINALIZED in a super type.

To remove the error, either:

  • Change the start transition to VIRTUAL or REDEFINED in the closest super type where it is mentioned.
  • Remove the start transition from the sub type if you did not intend to redefine the start transition.

(Z.100: 2.6.2, 6.3.3)

ERROR 145 Start is not defined as virtual in super

It is not allowed to define the start transition as redefined, since it is not defined as virtual in the inherited type.

You get this error if:

  • You try to redefine the start transition in a sub type when the start transition is not defined as VIRTUAL in a super type.

To remove the error:

  • Make the start transition VIRTUAL in the super type.

(Z.100: 2.6.2, 6.3.3)

ERROR 146 Multiple exits from state %2 with signal, timer or remote procedure %1

The signal, timer or remote procedure is contained in two inputs or one input and one save.

You get this error if:

  • There are several ways to leave a state for the same signal, timer or remote procedure.

To remove the error:

  • Remove enough ways to leave the state to make all remaining ways unique.

(Z.100: 2.6.3, 2.6.5)

ERROR 147 Virtual input %1 is already defined as input in state %2 in supertype

It is not allowed to define the input %1 as virtual, since it is already defined without virtual in the inherited type.

You get this error if:

  • You are declaring a transition to be VIRTUAL in a sub type, when the transition is already VIRTUAL in the super type.

To remove the error:

  • Use the keyword REDEFINED instead of VIRTUAL in the sub type.
  • Make sure the transition is VIRTUAL in a super type.

(Z.100: 6.3.3)

ERROR 148 Redefined input %1 is not defined as virtual input in state %2 in supertype

It is not allowed to define the input %1 as redefined, since it is not defined with virtual in the inherited type.

You get this error if:

  • You have a redefined transition in a sub type that does not exist in the super type.
  • You have a redefined transition in a sub type that is not declared as virtual in the super type.

To remove the error, either:

  • Make sure there is a matching virtual transition in the super type.
  • Remove the REDEFINED keyword from the transition in the sub type.

(Z.100: 6.3.3)

ERROR 149 Redefined input %1 is defined as finalized input in state %2 in supertype

It is not allowed to define the input %1 as redefined, since it is defined as finalized in the inherited type.

You get this error if:

  • You are trying to REDEFINE a transition that is marked as FINALIZED in a super type.

To remove the error, either:

  • Change the transition from FINALIZED to REDEFINED in the super type.
  • Make sure that you are redefining the correct transition.

(Z.100: 6.3.3)

ERROR 150 Redefined input %1 is defined as input in state %2 in supertype

It is not allowed to define the input %1 as redefined, since it is defined without virtual in the inherited type.

You get this error if:

  • You define a transition as REDEFINED in a sub type, when the same transition in the super type is not VIRTUAL.

To remove the error, either:

  • Make the transition in the super type VIRTUAL.
  • Make sure that you are redefining the correct transition.

(Z.100: 6.3.3)

ERROR 151 Finalized input %1 is not defined as virtual input in state %2 in supertype

It is only allowed to define an input as finalized if it is a virtual defined input in a inherited type.

You get this error either if:

  • You use the keyword REDEFINED or FINALIZED for a transition that is not declared VIRTUAL in a super type.
  • There is no super type.

To remove the error, either:

  • Make the transition in the super type VIRTUAL.
  • Change the name in the sub type to match the correct transition in the super type
  • Make sure the sub type inherits from the correct super type.

ERROR 152 Finalized input %1 is defined as finalized input in state %2 in supertype

It is not allowed to define the input %1 as finalized, since it is already defined as finalized in the inherited type.

You get this error if:

  • You try to finalize a transition in a sub type that is already FINALIZED in a super type.

To remove the error, either:

  • Change the keyword FINALIZED to REDEFINED in the super type.
  • Make sure that you are trying to finalize the correct transition in the sub type.

(Z.100: 6.3.3)

ERROR 153 Signal %1 is already defined as input in state %2 in supertype

It is not allowed to have the same signal in more than one input to the same state. In this case there is already a input of the signal %1 in the type you inherit from.

You get this error if:

  • You try to define a transition that already exists in a super type, without using the keyword REDEFINED or FINALIZED, or when the transition in the super type is not virtual.

To remove the error:

  • Add the keyword REDEFINED or FINALIZED to the transition in the sub type.
  • Make sure that the transition in the super type is VIRTUAL.

ERROR 154 A state (%1) cannot contain both asterisk input and asterisk save

It is not allowed to both have a asterisk input and a asterisk save to a state.

You get this error if:

  • You have a state in your state machine that has both an asterisk input transition and an asterisk save.

To remove the error, either:

  • Remove the asterisk save.
  • remove the asterisk input transition.

(Z.100: 4.6, 4.7)

ERROR 155 A state (%1) may only contain one asterisk input

It is only allowed to have one asterisk input to a state.

You get this error if:

  • You are having more than one asterisk input transition for the same state.

To remove the error:

  • Remove all but one asterisk input transition for the same state.

(Z.100: 4.6)

ERROR 156 A state (%1) may only contain one asterisk save

It is only allowed to have one asterisk save to a state.

You get this error if:

  • You have a state in your state machine that has more than one asterisk saves.

To remove the error:

  • Reduce the number of asterisk saves for the transition to one (or zero).

(Z.100: 4.7)

ERROR 157 Valid input signal set must be specified (in process/service %1) when no signal routes or channels are specified in the enclosing block/process (%2)

If there are no signal routes or channels specified to the process/service. "Signalset" must be used inside the process/service extended heading to specify the valid input signal set.

You get this error if:

  • You have a process or service that is not connected with the outer world via signal routes or channels, and you have not specified an input SIGNALSET.

To remove the error, either:

  • Add signal routes and channels to connect the process to the outer world.
  • Add a SIGNALSET construct to the process and indicate the signals the process can receive.

(Z.100: 2.5.2)

ERROR 158 Value returning procedure expected

A value returning procedure was expected at this place.

ERROR 159 Type mismatch: sort %2 does not match %1

You get this error if:

  • You are using an integer where a boolean is expected. For instance, you are using an integer as a type for a parameter in an imported procedure signature that should match a boolean type parameter in a remote procedure signature.

To remove the error, either:

  • Use a boolean instead.
  • Change the expected type to be an integer instead.

ERROR 160 In/out parameter expected

An in/out parameter was expected according to the definition.

You get this error if:

  • You are using an IN parameter in an imported procedure signature that should match an IN/OUT parameter in a remote procedure signature.

To remove the error, either:

  • Change the imported procedure signature to use an IN/OUT parameter instead.
  • Change the remote procedure signature to use an IN parameter instead.

ERROR 161 Missing parameter

A parameter is missing according to the definition.

You get this error if:

  • You omit a parameter or return value from an imported procedure signature that should match a remote procedure signature.

To remove the error, either:

  • Add the missing parameter or return value to the imported procedure signature.
  • Remove the not wanted parameter or return value from the remote procedure signature.

ERROR 162 Virtual definitions only allowed in types

It is only allowed to use virtual in a type definition.

You get this error if:

  • You have a virtual definition of a diagram in a normal diagram.

To remove the error:

  • Remove the keyword virtual from the definition of the diagram.
  • Make the diagram with the virtual definition a type-based diagram.

ERROR 163 Virtual definition %1 does not conform to its virtuality constraint

(Z.100: 6.3.2)

ERROR 164 Redefinition of %1 does not conform to the virtuality constraint

(Z.100: 6.3.2)

ERROR 165 A gate with addition of signals can only occur in subtypes

Adding in gate definition can only be used if the type is inherited from another type.

You get this error if:

  • You are using the ADDING construct for a gate in a diagram that does not inherit from another diagram.

To remove the error, either:

  • Remove the ADDING construct from the gate definition.
  • Make the type-based diagram with the error inherit from another type-based diagram with an appropriate gate that you can use.

(Z.100: 6.1.4)

ERROR 166 Definition of %1 exists already in super type

An already defined gate cannot be defined again. If you want to add signals to an already existing gate, the word adding must be used.

You get this error if:

  • You declare a gate in a type that inherits from another type that already has a gate with the same name.

To remove the error in the above case:

  • Rename one of the gates to get two gates in the sub type.
  • Use the keyword ADDING in the gate in the sub type if you want to redefine the gate in the super type from the sub type.

You also get this error if:

  • You use the RETURNS construct in both the super procedure type and the sub procedure type.

To remove the error in the above case:

  • Remove the RETURNS construct from the sub type.

You also get this error either if:

  • You try to redefine a finalized procedure in a sub type.
  • You try to define a procedure, that has already been defined as virtual in a super type, without using REDEFINED.

To remove the error in the above cases, either:

  • Make sure that you are redefining the correct procedure.
  • Make sure that you use the REDEFINED keyword in the sub type, if you intend to redefine a procedure.
  • Change the name of the procedure in the sub type, if you do not intend to redefine any existing procedure.
  • Change the finalized procedure in the super type to be a redefined procedure.

ERROR 167 A gate with addition of signals must already be defined in a super type

Adding in gate definition cannot be used when defining a new gate.

You get this error if:

  • You declare a gate endpoint constraint with the keyword ADDING, but the gate is not already declared in any super type.

To remove the error, either:

  • Make sure that the name of the gate with the ADDING keyword matches the name of a gate in a super type.
  • Remove the ADDING keyword to get a new gate that does not depend on any gate in a super type.

(Z.100: 6.1.4)

ERROR 168 Two gate constraints may not use the same direction in gate %1

It is not allowed to have the same direction (in or out) in two gate constraints.

You get this error if:

  • You have two gates in the same type-based diagram going in the same direction.

To remove the error, either:

  • Reverse one of the gates.
  • Merge the two gates, i.e. remove one of them, if they are intended to go in the same direction.

(Z.100: 6.1.4)

ERROR 169 Undefined type %1 in gate endpoint constraint

The endpoint constraint in the gate contains a undefined or not visible type.
(Z.100: 6.1.4)

ERROR 170 The two endpoint constraints of gate %1 is not consistent

The endpoint constraints, to and from, in the gate are not consistent.

You get this error if:

  • You have two gate endpoint constraints in a type-based diagram that are going in the same direction.
  • You have two gate endpoint constraints in a type-based diagram that are not referencing the same outer entity.

To remove the error:

  • Make sure that the two gate endpoint constraints are going in different directions.
  • Make sure that if you reference an outer type-based diagram, the same type-based diagram is referenced in both gate endpoint constraints.

(Z.100: 6.1.4)

ERROR 171 Undefined block, channel or signal route in connection

Identifiers used in a connection must be visible in the scope and of the above mentioned types.
(Z.100: 2.5.3, 3.2.3)

ERROR 172 Undefined block, process or service in path

The identifiers following the text "from" and "to" in channel and signal route definitions must be visible blocks, processes or services.
(Z.100: 2.5.1, 2.5.2)

ERROR 173 Selected diagram not in an SDL system

The context must be available when analyzing part of a system.

ERROR 174 Undefined type %1 in instance specification

The type must be defined and visible in the scope to be instantiated.

You get this error if:

  • You refer to a type-based diagram that does not exist.

To remove the error, either:

  • Refer to an existing type-based diagram instead.
  • Create a matching type-based diagram.

ERROR 175 Undefined component %1/%2 in use clause

(Z.100: 2.4.1.2)

ERROR 176 Parameterized type %1 cannot be used as constraint type

It is not allowed to use a type with context parameters as a constraint type.
(Z.100: 6.3.2)

ERROR 177 Undefined type %1 in constraint specification

The type %1 used in the constraint specification is undefined or not visible.

ERROR 178 Substructure name in subtype and supertype must be the same

(Z.100: 6.3.1)

ERROR 179 Undefined type %1 in inheritance specification

A type which is inherited is not defined or not visible.

You get this error if:

  • You in a signal declaration uses the keyword INHERITS and mention another signal that has not yet been defined.

To remove the error:

  • Make sure the signal to inherit from is defined before the signal that inherits.

ERROR 180 Undefined type %1 in virtuality constraint

The type %1 used in the virtuality constraint is undefined or not visible.

You get this error if:

  • You refer to a type-based diagram that does not exist in a virtuality constraint.

To remove the error, either:

  • Use the name of an existing and matching type-based diagram instead.
  • Create a matching type-based diagram.
  • Remove the virtuality constraint.

ERROR 181 Environment must only appear in one connection

When a channel is partitioned and has the environment as one of its endpoints, the channel substructure must contain one and only one connection with environment.

You get this error if:

  • You have more than one connect statement for a signal route or channel going to or from the environment.

To remove the error:

  • Remove all but one connect statement going to or from the environment for the signal route or channel in question.

(Z.100: 3.2.3)

ERROR 182 The path %1 must only appear in one connection

It is not allowed to have the same channel or signalroute name mentioned in more than one connection.

You get this error if:

  • You mention a signal route or a channel in two or more CONNECT statements in the same diagram.

To remove the error:

  • Merge all CONNECT statements mentioning the same signal route or channel into one CONNECT statement.

(Z.100: 2.5.3, 3.2.2)

ERROR 183 All subsignals to the channel %1 must be included in the signal lists of the subchannels

In the connection between a channel and subchannels, each signal conveyed by the channel must either be conveyed by the subchannels or all of its subsignals must be conveyed by the subchannels.
(Z.100: 2.5.3, 3.3)

ERROR 184 Signal %1 must be included in the signal list of the inner paths

In a connection point, all signals in the outer paths must be conveyed by at least one of the inner paths.

You get this error if:

  • You connect two signal routes or channels that do not allow the same set of signals to be sent in each direction.

To remove the error:

  • Add or remove signals from the signal lists in the connected signal routes or channels to get matching signal lists.

(Z.100: 2.5.3, 3.3)

ERROR 185 Signal %1 must be included in the signal list of the outer paths %2

In a connection point, all signals in the inner paths must be conveyed by at least one of the outer paths.

You get this error if:

  • You connect a signal route or channel to a signal route or channel one level up in the diagram hierarchy that does not include all signals of the signal route or channel in this diagram.

To remove the error, either:

  • Add the signals you want to send to the appropriate signal lists in the diagrams outside this diagram.
  • Remove the not wanted and troublesome signal from the signal list of the channel or signal route that is connected to the world outside this diagram.

(Z.100: 2.5.3, 3.3)

ERROR 186 In the implicit connection with %2 signal %1 is not included in any of the outgoing implicit signal routes

Each signal in the channels, directed out from the block, must be mentioned in at least one output in a process. See also ERROR 187.
(Z.100: 2.5.2, 2.5.3)

ERROR 187 In the implicit connection with %2 is signal %1 not included in any of the incoming implicit signal routes

When a block contains no signal routes, the signal route definitions and the connections are derived from the valid input signal sets and the outputs (of the processes in the block) and the channels connected to the block. (The same is valid for a service decomposition with no service signal routes.) Each signal in the channels, directed into the block, must be included in at least one valid input signal set.
(Z.100: 2.5.2, 2.5.3)

ERROR 188 Actual context parameter %1 does not conform to the fpar constraint

The actual context parameter is not correct according to the fpar constraint given for the formal context parameter.
(Z.100: 6.2)

ERROR 189 Actual context parameter %1 does not conform to the sort signature constraint

The actual context parameter is not correct according to the sort signature constraint given for the formal context parameter.
(Z.100: 6.2)

ERROR 190 Actual context parameter %1 does not conform to the atleast constraint

The actual context parameter is not correct according to the at least constraint given for the formal context parameter.
(Z.100: 6.2)

ERROR 191 Actual context parameter %1 does not conform to the process type constraint

The actual context parameter is not correct according to the process type constraint given for the formal context parameter.
(Z.100: 6.2)

ERROR 192 Actual context parameter %1 does not conform to the sort list constraint

The actual context parameter is not correct according to the sort list constraint given for the formal context parameter.
(Z.100: 6.2)

ERROR 193 Actual context parameter %1 does not conform to the signal set constraint

The actual context parameter is not correct according to the signal set constraint given for the formal context parameter.
(Z.100: 6.2)

ERROR 194 Block definition must contain process, block or substructure definition

A block definition must at least contain one process or a substructure.
(Z.100: 2.4.3)

ERROR 195 Block definition must contain process definition(s) when containing signal route definition(s)

A block definition cannot contain signal routes when no processes are defined.
(Z.100: 2.4.3)

ERROR 196 Block definition must contain process or block definition(s) when containing connection(s)

A block definition cannot contain connections when no processes are defined.
(Z.100: 2.4.3)

WARNING 197 Expansion of select definition is not yet implemented

The SDL concept select definition is not supported by the SDL Analyzer.

Caution!

A consequence of this is that the parts of your SDL system which are contained in the select definition will not be analyzed or be input to the SDL to C compilers.

ERROR 198 Substructure definition must contain at least one block definition

At least one block must be defined inside a substructure.

You get this error if:

  • You have a substructure diagram that does not contain any block diagrams.

To remove the error, either:

  • Add at least one block diagram with one or several processes to the substructure diagram.
  • Instantiate a block type diagram in the substructure diagram.

(Z.100: 3.2.2)

ERROR 199 Gate only allowed in paths with instance of a type or env in a type

Gates are only allowed when connecting channels or signal routes to types.

You get this error if:

  • You are using gates without using type-based diagrams.

To remove the error in the above case, either:

  • Remove the reference to the gate.
  • Make the current diagram type-based, if you want to have gates to connect to in the environment.
  • Make referenced diagrams instances of type-based diagrams, if you want to have gates to connect to in reference symbols.

You also get this error if:

  • You use the VIA keyword when declaring a signal route or a channel, that is not going to or coming from an instantiation of a type-based diagram, and that is not going to or coming from the environment in a type-based diagram.

To remove the error in the above case:

  • Remove the VIA construct.

(Z.100: 6.1.4)

ERROR 200 Undefined gate

Use of an undefined gate in a channel or signal route definition.

You get this error if:

  • You are referring to a gate that does not exist.

To remove the error, either:

  • Remove the gate reference.
  • Add the gate you are referencing.

ERROR 201 Connected to gate (%1) in wrong scope

(Z.100: 6.1.4)

ERROR 202 Connected instance %1 does not conform to the endpoint constraint of gate %2

The type of the instance %1 connected to gate %2 must be equal to or be a subtype of the endpoint constraint of gate %2.

ERROR 203 ENV does not conform to the endpoint constraint of gate %1

A gate with an endpoint constraint cannot be connected to the environment.

You get this error if:

  • You have a gate endpoint constraint in the type you try to instantiate, and you connect the gate to an instance that is not of the same type (or a descendant of that type) as the one mentioned in the gate endpoint constraint.

To remove the error, either:

  • Connect the gate to an instance of the same type (or a descendant of that type) as the one mentioned in the gate endpoint constraint.
  • Remove or change the gate endpoint constraint.

ERROR 204 Signal %1 in path is not an incoming signal of %3 gate %2

The gate %2 of instance %3 must be defined to convey the incoming signal %1. Add the signal to the gate definition.

ERROR 205 Signal %1 in path is not an outgoing signal of %3 gate %2

The gate %2 of instance %3 must be defined to convey the outgoing signal %1. Add the signal to the gate definition.

ERROR 206 Via gate expected in env path with block type or process type

A channel or a signal route must be defined using "via <gate>" when connected to the environment in a block type or system type.

You get this error if:

  • You declare a channel or a signal route in a type-based diagram going to or coming from the environment without using a VIA keyword to specify the gate to use.

To remove the error:

  • Add a VIA keyword and mention the gate to use in the declaration of the signal route or channel.

ERROR 207 Via gate expected in path with typebased instance

Defining a channel or a signal route using "via <gate>" is only possible when the connected instance is type based and thus contain gates.

You get this error if:

  • You declare a signal route or a channel going to or coming from an instantiation of a type-based diagram, without specifying the gate to connect to with a VIA keyword.

To correct the error:

  • Add a VIA keyword and the name of the gate in the instantiated type-based diagram that you want to connect to.

ERROR 208 Endpoints of the path %1 must be different

A channel/signal route cannot connect a block/process/service with itself.

You get this error if:

  • You specify the same endpoint for both ends of a signal route or channel.

To remove the error:

  • Connect one of the ends of the signal route or channel to another endpoint.

(Z.100: 2.5.1, 2.5.2)

ERROR 209 Endpoint %1 of channel %2 must be a block or process

A channel must be connected to at least one block!

(Z.100: 2.5.1)

ERROR 210 Endpoint %1 of the path %2 must be locally defined

The endpoints of a channel/signal route must be defined in the same scope as the channel/signal route is defined.

You get this error if:

  • You try to connect a signal route or channel to a diagram that is not visible from the current diagram.

To remove the error:

  • Connect the signal route or channel to the environment or to a diagram one level below the current diagram. If necessary, create more signal routes or channels in other diagrams to reach the diagram you want to communicate with.

(Z.100: 2.5.1, 2.5.2)

ERROR 211 The second path must denote reverse direction of the first path in %1

In a bidirectional channel or signal route, the second path must be in the reverse direction of the first path.

You get this error if:

  • The second FROM-TO-VIA-WITH construct is not going in exactly the reverse direction as compared to the first one.

To remove the error, either:

  • Make sure that the same connection item is used after both FROM in the first construct and after TO in the second construct.
  • Make sure that the same connection item is used after both TO in the first construct and after FROM in the second construct.

(Z.100: 2.5.1, 2.5.2)

ERROR 212 Endpoint %1 of signal route %2 must be a process or a service

A signal route must connect at least one process or service.
(Z.100: 2.5.2)

ERROR 213 Return not allowed here

You get this error if:

  • You use the return construct in a process diagram.

To remove the error, either:

  • Replace the return with a stop.
  • Make the process diagram a procedure diagram.

(Z.100: 2.6.8.2.4)

ERROR 214 Process definition must contain either processbody or service decomposition

Syntax requirement.
(Z.100: 2.4.4)

ERROR 215 Process cannot contain timer definition when decomposed into services

(Z.100: 2.4.5)

ERROR 216 Revealed and exported variables only allowed in process and service

(Z.100: 2.4.6)

ERROR 217 Complete semantic analysis requires a system

(Z.100: 2.4.6)

ERROR 218 Procedure cannot contain stop

Syntax requirement.
(Z.100: 2.6.8.2.3)

ERROR 219 Undefined view

ERROR 220 Step expression requires a loop variable

It is not allowed to omit the variable indication from a for statement when having a step expression.

You get this error if:

  • You have a for(x,y,z)-statement where x does not define a loop variable, but z uses a loop variable.

To remove the error, either:

  • Define a loop variable in the for statement.
  • Change the step expression to match the loop variable.

ERROR 221 Break without name or continue are only allowed within a loop

Break terminates a for loop and continue does the next iteration of a for loop. They can only be used in the context of for loops.

You get this error either if:

  • You use a BREAK construct without a name outside a loop.
  • You use a CONTINUE construct outside a loop.

To remove the error, either:

  • Add a name after the break keyword that matches a label that you want to jump to.
  • Remove the break or continue construct.
  • Put the break or continue construct within a for loop.

ERROR 222 Variable used before it is defined

A variable may only be used in statements following its definition.

You get this error if:

  • You use a variable before the declaration of the variable.

To remove the error, either:

  • Move either the variable use or declaration to make sure that the variable declaration comes before the variable use.
  • Make sure you are using the correct variable.

ERROR 223 A jump statement must be contained in a labeled statement with the given name

A jump statement is a more restrictive form of a join statement. The intent is to create less convoluted code.

You get this error if:

  • You have a break construct to a label that is not visible from the break.

To remove the error:

  • If the label and the break are on the same level, begin a pair of brackets after the label that contains the break.

ERROR 224 No receiver found

ERROR 225 Two services cannot have the same signal (%1) in their valid input signal set

The complete valid input signal sets of the service definitions within a process definition must be disjointed.
(Z.100: 2.4.5)

ERROR 226 Recursive package %1 in use clause

A package must not use itself.

You get this error if:

  • There is a self-referential chain of uses of packages. For instance package A uses package B, and package B uses package A.

To remove the error:

  • Break the self-referential chain of uses of packages by removing a USE statement in an appropriate place in the chain.

ERROR 227 Ending type keyword must match starting

A process type must be terminated with endprocess type and not just endprocess, and so on.

ERROR 228 Not Charstring sort and no proper operator (Length, ...)

ERROR 229 Service signal routes cannot be specified when no signal routes are specified in the enclosing block

(Z.100: 2.4.5)

ERROR 230 Service decomposition must contain at least one service definition

(Z.100: 2.4.4)

ERROR 231 No proper Length operator found

ERROR 232 Recursive include of file %1

The file is included recursively.

ERROR 233 Qualifier in component command not in SDL system

All parts (components) of a program must belong to the same system.

ERROR 234 More than one system

Can only analyze one system at a time.

ERROR 235 Code generation requires a system

Packages are not sufficient.

ERROR 236 Valid input signal set cannot contain a timer (%1)

You get this error if:

  • You include a timer in the specification of the set of signals that a process can receive.

To remove the error:

  • Remove the timer from the signal set construct.

(Z.100: 2.4.4, 2.4.5)

ERROR 237 Two signals (%1 and %2) in the complete valid input signal set are on different refinement levels of the same signal

(Z.100: 3.3)

ERROR 238 Two signals (%1 and %2) among the output-signals of the process are on different refinement levels of the same signal

(Z.100: 3.3)

ERROR 239 Signal %1 in save cannot be received

The signal is not included in the complete valid input signal set of the process/service.
(FD)

ERROR 240 Signal %1 in input cannot be received

The signal is not included in the complete valid input signal set of the process/service.

You get this error if:

  • You try to receive a signal in an input, but you have not declared that anyone can send that signal to this process.

To remove the error, either:

  • Check that you are trying to receive the correct signal.
  • Make sure that the signal can be sent to this process via signal routes and channels, or by including the signal in a SIGNALSET construct for this process.

(FD)

ERROR 241 Error creating directory %1

A message from the operating system is following this and hopefully clarifies the problem.

ERROR 242 Signal %1 in priority input cannot be received

The signal is not included in the complete valid input signal set of the service.
(FD)

ERROR 243 Actual in/out param sort %1 does not match %2

The sort of actual and formal in/out parameters of procedures must be identical on the syntype level.

You get this error if:

  • You call a procedure using a parameter that is not of the correct type.

To remove the error, either:

  • Call the procedure with a parameter of the correct type.
  • Change the procedure to accept a parameter of the wanted type.

ERROR 244 Call procedure from expression or supply variable parameter

A value returning procedure should be called from an expression.

You get this error if:

  • You call a value-returning procedure from outside of an expression.

To remove the error, either:

  • Call the value-returning procedure from an expression in a task instead.
  • Call another, similar procedure that do not return a value.
  • Force the procedure to not return a value.

WARNING 245 Trailing parameter of sort %1 omitted

ERROR 246 Last param of procedure called from expr is not in/out

Actual in/out procedure parameters may not be omitted.

You get this error if:

  • You are calling a procedure in an expression, and the called procedure does not have a RETURNS statement.

To remove the error:

  • Add a RETURNS statement to the procedure definition, and make sure the procedure returns a value of the correct type.

ERROR 247 Actual in/out param cannot be omitted

The actual parameter can be omitted if the formal is in.

You get this error if:

  • You call a procedure without less actual parameters than all formal parameters declared for the procedure.

To correct the error, either:

  • Add the missing actual parameters to match all formal parameters declared for the procedure.
  • Remove any not wanted formal parameters from the declaration of the procedure.

WARNING 248 License %1 will expire in %2 days

This is a notification that some license will expire in the near future.

ERROR 249 Aborted by exit request

This indicate that the analyzer received a stop message

ERROR 250 Component and Thread commands requires a previous Program command

Issue a program command to set the name of the executable before adding threads or components to it.

ERROR 251 Change directory: %1: %2

An error occurred when changing default (working) directory.

ERROR 252 Get work dir: %1: %2

The analyzer failed to obtain current working directory.

ERROR 253 Connection with %1 is missing

Either a path is connected to a block/process but is not contained in a connection or a block is connected to a channel but is not contained in a connection in the channel substructure.
(Z.100: 2.5.3, 3.2.2, 3.2.3)

ERROR 254 Connection with environment is missing

When a channel is partitioned and has the environment as one of its endpoints, the channel substructure must contain a connection with the environment.

You get this error if:

  • You omit a connect statement saying that a channel or signal route is connected to the environment, when the declaration of the channel or signal route indicates that it is connected to the environment.

To correct the error:

  • Add a connect statement saying that the channel or signal route is connected to the environment.

(Z.100: 3.2.3)

ERROR 255 Transition must end with a terminator

If the terminator of a transition is omitted, then the last action in the transition must contain a terminating decision.
(Z.100: 2.6.4, 2.6.8.1)

ERROR 256 Post Master

A problem occurred when communicating with some other tool using the PostMaster.

WARNING 257 Statement not reached

SDL-92 allows dead code in transition. The warning is issued to notify the user of the dead code.

ERROR 258 Initial transition ends (directly or indirectly) with dash nextstate

A nextstate in the initial transition (of a process/ procedure/ service) must be specified with a state name.
(Z.100: 4.9)

ERROR 259 Ending name (%1) cannot be qualified (except for remote definitions)

You get this error if:

  • You are using a qualifier when specifying the name of the diagram at the end of the diagram definition.

To remove the error:

  • Remove the qualifier and keep just the name of the diagram.

(Z.100: 2.2.2)

ERROR 260 The outer channeldef must have the first connectionpoint (environment) as one of the endpoints

A channel substructure can only contain a connection with the environment if the partitioned channel is connected to the environment.
(Z.100: 3.2.3)

ERROR 261 Answers are not mutually exclusive

Exactly one answer in a decision must match the question. For instance, a boolean decision with more than 2 answers or 2 answers that are both true or both false will produce this message.

You get this error if:

  • It is possible to take two or more paths after the decision for at least one given set of values.

To remove the error:

  • Make sure that it is always only possible to take one path after the decision symbol.

ERROR 262 The outer channeldef must have the first connectionpoint (block) %1 as one of the endpoints

The block identifier in a connection in a channel substructure must identify one of the endpoints of the partitioned channel.
(Z.100: 3.2.3)

ERROR 263 One of the endpoints of path %1 must be the scope unit %2

A path that occurs as the first connection point in a connection, must be connected to the block/process that contains the connection.
(Z.100: 2.5.3, 3.2.2)

ERROR 264 The second connectionpoint %1 must be defined in the scope unit %2

A path occurring in the second part (i.e. the list of subpaths) in a connection must be locally defined.

You get this error if:

  • You have a connection statement connecting an outer channel or signal route with a non-existing inner channel or signal route.

To remove the error:

  • Change the name of the second connection point to match an existing inner signal route or channel.
  • Add an inner signal route or channel with the correct name.

(Z.100: 2.5.3, 3.2.2)

ERROR 265 One of the endpoints of path %1 must be the environment

A path that occurs in the second part (i.e. the list of subpaths) of a connection must have the environment as one of its endpoints.

You get this error if:

  • You use a signal route or a channel in a CONNECT statement, and the signal route or channel is not connected to the environment.

To remove the error, either:

  • Check that the CONNECT statement is connecting the correct signal route or channel in this diagram.
  • Change the signal route or channel in this diagram to go to the environment with one of its endpoints.
  • Remove the connect statement.

(Z.100: 2.5.3, 3.2.2)

ERROR 266 System definition must contain at least one block or process definition

An SDL system must contain at least one block or process.

You get this error if:

  • You have constructed an SDL system that does not contain any blocks or processes.

To remove the error, either:

  • Add at least one block with one or several processes to your SDL system.
  • Instantiate any existing block type diagrams.

(Z.100: 2.4.2)

WARNING 267 Optional parameter of sort %1 omitted

WARNING 268 Gate must be connected

ERROR 269 Expression evaluates to error

ERROR 270 Selected definition not allowed here

ERROR 271 All packages must either be before or after the system

The system should follow the package list according to SDL. For backwards compatibility the analyzer also accepts a package list after the system, but not both at the same time. In the Organizer this means that the icons for all packages used by a system should be above the system icon.

WARNING 272 No analysis is performed when the infile is empty

The SDL/PR input file cannot be empty.

WARNING 273 No semantic analysis is performed when the input is not a system or a package

Semantic analysis can only be performed on a system or a package.

ERROR 274 Compile and link exited with error code

The code generated by the SDL to C Compiler caused compile or link errors.

ERROR 275 Lost license

The connection to the license server is lost. You must wait until the Analyzer has regained access to the license server before resuming your work. If required, contact your system manager to get the problem solved.

ERROR 276 Cannot get license

No license was available when starting up Analyzer. You must wait until a license becomes available (which will occur when another user terminates his Analyzer).

ERROR 277 Cannot return license

The Analyzer could not return its license to the license pool. To return the license, you may need to stop and restart the license server.

INFO 278 Analyzer command could not be fully performed

The Analyzer did not perform all the passes that were ordered. The results from the Analyzer may not be what you expect. This message is output as a result from a syntactic or semantic error that in turn causes the remaining passes not to be executed.

ERROR 279 The number of block instances must be one or greater

The number of block instances in a multiple block instantiation must be greater than 0.

You get this error if:

  • You instantiate a block type in a block reference symbol with a number of instances smaller than one.

To remove the error:

  • Change the number of instances to one or more.

ERROR 280 Unreachable path %1 in VIA

The path %1 must be connected to the process instance.

You get this error if:

  • You send a signal from a process and the static structure of the SDL system does not declare that you are allowed to send that signal the way you want.

To remove the error, either:

  • Add signal routes and channels as needed (with your signal in the signal lists), to reach the wanted process or the environment.
  • Remove the sending of that particular signal.

ERROR 281 Unreachable process instance set %1 in TO expr

There must be a path leading to the process instance set %1 from this process instance.

You get this error if:

  • You send a signal from a process and the static structure of the SDL system does not declare that you are allowed to send that signal the way you want.

To remove the error, either:

  • Add signal routes and channels as needed (with your signal in the signal lists), to reach the wanted process or the environment.
  • Remove the sending of that particular signal.

WARNING 282 Several possible paths in VIA list

There are several paths that can convey the signal, one of them will be non deterministically chosen.

WARNING 283 Several possible paths

There are several paths that can convey the signal, one of the paths will be non deterministically chosen during execution.

WARNING 284 Set-Case-Sensitive should be the first command to the analyzer

ERROR 285 Hex string literal must have an even length

This applies to values for types that are strings of bytes.

ERROR 286 Bit string literal must have a length modulo 8

This applies to values for types that are strings of bytes.

ERROR 287 Literal must be one octet long

This applies to values for types that are one byte.

WARNING 288 No matching answer for %2

If a decision (or transition option) is executed with a question not covered by any answer it will be an error. (Z.100:2.7.5 and 4.3.4)

ERROR 289 Expression in transition option evaluates to error

One of the expressions in a transition option is erroneous.
(Z.100:4.3.4)

ERROR 290 External synonym not allowed

External synonyms are only allowed in a number of instances in process reference symbols and in heading symbols in process diagrams.

You get this error if:

  • You use an external synonym in the condition for a transition option alternative.

To remove the error:

  • Remove the external synonym from the condition for the transition option alternative in question.

ERROR 291 Range check failed

You get this error if:

  • You specify a value not allowed for a syntype, like a negative value in a variable of sort Natural.

To remove the error, either:

  • Change the value to one of the allowed ones.
  • Change the syntype to allow the value.
  • Use a different sort allowing the value.

(Z.100:5.3.1.9.1)

ERROR 292 Maximal number of instances equals zero

A process should have at least one instance.

You get this error if:

  • You specify zero as the maximum number of instances.

To remove the error, either:

  • Change the maximum number of instances to one or more.
  • Remove the diagram with maximum number of instances set to zero.

(Z.100:2.4.4)

ERROR 293 Maximum number of instances is less than initial number

In the process instances definitions, the maximum number of instances must be greater or equal to the initial number.

You get this error if:

  • You specify a maximum number of instances that is less than the initial number of instances.

To remove the error, either:

  • Increase the maximum number of instances to at least the initial number of instances.
  • Decrease the initial number of instances to less than or equal to the maximum number of instances.

(Z.100:2.4.4)

ERROR 294 Not allowed to change remote procedure in redefinition

(Z.100:2.4.6)

WARNING 295 Consider adding else answer

If a decision (or transition option) is executed with a question not covered by any answer it will be an error. (Z.100:2.7.5 and 4.3.4)

ERROR 296 Redefined or finalized procedure must be exported when base is

(Z.100:2.4.6)

INFO 297 Error limit reached, terminating

The number of diagnostics that the Analyzer has reported exceeds the value of the limit.

WARNING 298 Accumulated expression depth: %1 parts: %2 matches: %3

Semantic analysis of complex expression may cause long execution time. The execution time will increase in a fashion that is exponential rather than linear. If possible, try to reduce the complexity of expressions by breaking them down into multiple expressions.

WARNING 299 Expression depth: %1 parts: %2

See WARNING 298 Accumulated expression depth: %1 parts: %2 matches: %3 above.

ERROR 300 Command not found

The command that was input to the Analyzer's command interpreter was not recognized.

ERROR 301 Unexpected end of command: %1

The command that was input to the Analyzer does not contain all necessary parameters.

ERROR 302 Ambiguous command

The command that was input to the Analyzer's command interpreter was ambiguous. More characters need to be supplied to identify the command.

ERROR 303 Parameter expected

The command that was input to the Analyzer's command interpreter
requires one or more parameters.

ERROR 304 Macro must not be part of a qualifier

A macro is not allowed to be part of a qualifier.

ERROR 305 Remote entity may only be exported once in a process

This applies to exported procedures and variables.

(Z.100:2.4.6 and 2.6.1.1)

ERROR 306 No input specified

There is no input set to the Analyzer using the set-input command.

WARNING 307 %1: unknown, line ignored!

The command line is ignored.

ERROR 308 More than one package match use statement

Use Modules to group systems together with their package lists to make package names unique within a module.

INFO 309 Location of the shadowed definition

ERROR 310 Selected item %1 is not connected to a file

The Organizer has ordered to analyze a diagram that is not connected to a file.

ERROR 311 Signal %1 found in opposite direction in connection

You get this error if:

  • You connect two signal routes or channels where a signal is defined according to the signal lists to go in different directions on the inside and on the outside of the connection.

To remove the error:

  • Reverse the direction of one of the signal routes or channels, at least for the signal that caused the error.

ERROR 312 Syntax error in rule %1, symbol %2 found but one of the following expected:

Syntax error!

ERROR 313 Syntax error, symbol %1 found but one of the following expected:

Syntax error!

ERROR 314 Lexical error in rule %1, symbol %2 found but one of the following expected:

Syntax error!

You get this error either if:

  • You have typed a character or keyword that is not allowed in a CHARSTRINGLITERAL in a place where the syntax checker thinks there should be a CHARSTRINGLITERAL.
  • You have used an SDL keyword as a name for a variable.

To remove the error in the above cases, either:

  • Examine the pointed out character or keyword to see if it really belongs there.
  • Try to find out why the syntax checker expects a CHARSTRINGLITERAL; did you intend to have a CHARSTRINGLITERAL there?.
  • Rename any variable that you have given the same name as an SDL keyword.

You also get this error if:

  • You have constructed a word or token out of single characters that does not match allowed word or tokens in SDL.

To remove the error in the above case:

  • Check the word in question and replace any mistyped or misplaced characters.

ERROR 315 Lexical error, symbol %1 found but one of the following expected:

Syntax error!

ERROR 316 File %1 not found in environment variable %2 %3, check installation!

Check the installation. If the error persists, contact Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 317 Outside connect item %1 is locally defined

You get this error if:

  • Your connect statement mentions an inner channel or signal route instead of a channel or signal route outside the current diagram as the first connect item.

To correct the error, either:

  • Swap places (if the second connect item is wrong too) on the inner and outer channel or signal route in the connect statement.
  • If there is a name conflict with a locally defined item, then add a qualifier to the outer connect item.

WARNING 318 %1 : signal not used

The signal %1 should be used.

Here is a small explanation valid for all <entity> not used warning messages:

You get this error if:

  • You declare an entity but do not use it.

To remove the error, either:

  • Remove the declaration.
  • Start using the entity.
  • Rename the entity in the declaration to match a used entity of the same type that does not have a declaration.
  • Change the type in the declaration to match a used entity with the same name but with a different type (that does not have a declaration).

WARNING 319 %1 : timer not used in input

The timer %1 should occur in an input.

WARNING 320 %1 : timer not used in set

The timer %1 should be set in the process.

WARNING 321 %1 : signallist not used

The signallist %1 should be used.

WARNING 322 %1 : variable not used

The variable %1 should be used.

WARNING 323 %1 : formal parameter not used

The formal parameter %1 should be used.

WARNING 324 %1 : synonym not used

The synonym %1 should be used.

WARNING 325 %1 : viewed variable not used

The viewed variable %1 should be used.

WARNING 326 %1 : remote variable not used

The remote variable %1 should be used.

WARNING 327 %1 : sort not used

The sort %1 should be used.

WARNING 328 %1 : generator not used

The generator %1 should be used.

WARNING 329 %1 : label not used

The label %1 should be used.

WARNING 330 %1 : system type not used

The system type %1 should be used.

WARNING 331 %1 : block type not used

The block type %1 should be used.

WARNING 332 %1 : process type not used

The process type %1 should be used.

WARNING 333 %1 : procedure not used

The procedure %1 should be used.

WARNING 334 %1 : package not used

The package %1 should be used.

ERROR 335

Reserved for future purpose.

ERROR 336 Input to Instance generator must be a system

ERROR 337 Operator diagram/definition not allowed where constant required

You get this error if:

  • You call an operator in a place where a constant is required, for instance in a declaration of a variable.

To remove the error, either:

  • Remove the operator call, and replace it with a constant if needed.
  • Call a non operator definition operator.

WARNING 338 %1 : operator diagram/definition not used

WARNING 339 %1 : operator not used

WARNING 340 %1 : remote procedure not used

ERROR 341 No matching variable, formal parameter, synonym or literal

ERROR 342 Literal %1 in literal renaming is not defined in parent sort

ERROR 343 No matching field selection, array element access or prefix operator

ERROR 344 No matching quoted operator

You get this error if:

  • You try to use a quoted operator with the wrong number of arguments or the wrong type of arguments.

To remove the error, either:

  • Check that you are using two arguments for infix operators and one argument for monadic operators.
  • Check that the operators you are using are of the correct type.

ERROR 345 No matching (. .)

ERROR 346 No visible variable or formal parameter with this name

ERROR 347 Type mismatch in component selection of variable or formal parameter

ERROR 348 No matching monadic operator

ERROR 349 No matching infix operator

INFO 350 %1 is one of the possible matching types

ERROR 351 No matching remote variable in variable definition

INFO 352 %1 is one of the visible definitions

ERROR 353

Reserved for future purpose.

ERROR 354

Reserved for future purpose.

ERROR 355 No matching remote variable in import definition

ERROR 356

Reserved for future purpose.

ERROR 357 No matching character string

ERROR 358 No matching choice primary

ERROR 359 Now not allowed where constant required

ERROR 360 No matching now expression

ERROR 361 Import expression not allowed where constant required

You get this error if:

  • You use an import expression where a constant is required.

To remove the error:

  • Replace the import expression with a constant.

ERROR 362 PId expression not allowed where constant required

You get this error if:

  • You are using a pid expression where a constant is expected.

To remove the error:

  • Replace the pid expression with a constant expression.

ERROR 363 No matching PId expression

You get this error if:

  • You use a PId expression where a boolean value is expected.

To remove the error, either:

  • Replace the PId expression with a boolean expression.
  • Make the expected value to be of type PId.

ERROR 364 View expression not allowed where constant required

You get this error if:

  • You are using a view expression where a constant expression is expected.

To remove the error:

  • Replace the view expression with a constant expression.

ERROR 365 Timer active expression not allowed where constant required

ERROR 366 Any expression not allowed where constant required

ERROR 367 No matching dereferencing operator

ERROR 368 Data base error

An internal error occurred in the Analyzer. Please send a report to Telelogic Customer Support. Contact information for Telelogic Customer Support can be found in "How to Contact Customer Support".

ERROR 369 No matching field selection

You get this error if:

  • You try to access a field in a struct using a name that does not represent any field in the struct.

To remove the error, either:

  • Make sure you are using the correct name to access a field in the struct.
  • Add a field in the struct with the wanted name.

ERROR 370 Type mismatch for procedure return value

ERROR 371 Type mismatch for variable, formal parameter, synonym or literal

You get this error if:

  • You assign a variable a value of the wrong type.

To remove the error:

  • Assign the value to a variable of the correct type instead.

ERROR 372 No visible variable, formal parameter, synonym, literal or operator with this name

You get this error if:

  • You use the name of a variable, formal parameter, synonym, literal or operator that is not defined in the current scope.

To remove the error, either:

  • Change the name to match a defined entity.
  • Define the entity.

ERROR 373 No visible synonym or literal with this name

You get this error if:

  • You refer to a synonym or a literal that cannot be seen from the current scope.

To remove the error, either:

  • Correct the spelling mistake, if it was not meant to be a synonym or literal.
  • Add a synonym or literal with the given name.

ERROR 374 Variable or formal parameter not allowed where constant required

You get this error if:

  • You are using a variable or formal parameter in a place where a constant expression is expected.

To remove the error:

  • Replace the variable or formal parameter with a constant expression.

ERROR 375 Type mismatch for synonym or literal

You get this error if:

  • You use a boolean synonym or literal where an integer synonym or literal is expected.

To remove the error:

  • Replace the boolean with an integer.

ERROR 376 Only one reference to each diagram allowed

Several diagrams connected to the same file.

ERROR 377 Keyword call required for procedure call

You get this error if:

  • You are calling a value returning procedure without using the CALL keyword.

To remove the error:

  • Add the CALL keyword before the procedure name in the expression.

ERROR 378 Several macrodefinitions have the same name %1

The name of a macro must be unique.

WARNING 379 Macrodefinition %1 was never called

The macro %1 should be used.

ERROR 380 Names separated by %, %1%%2, where neither is a formal parameter nor MACROID in macrodefinition %3

(Z.100: 4.2.1)

WARNING 381 Formal parameter %1 is never used in macrodefinition %2

The formal parameter %1 should be used in the macro definition

ERROR 382 The macrodefinition name is %1, but the endmacro name is %2

The names in the macro definition and the endmacro must be equal.

ERROR 383 Two formal parameters with the same name %1 in macrodefinition %2

Two formal parameters of a macro cannot have the same name.

ERROR 384 No matching macrodefinition found

The corresponding macro definition is missing.

ERROR 385 A macro may not call itself

A macro definition cannot be circular.

WARNING 386 No macro found

The system does not contain any macros or calls.

ERROR 387 Start transition expected

A process or procedure definition must begin with a start transition.

You get this error if:

  • You define a process without defining a start transition.

To remove the error:

  • Add a start transition to the process.

ERROR 388 Illegal redeclaration of operator definition

You get this error if:

  • You declare an operator twice.

To remove the error, either:

  • Rename one of the operators if they are different and you need them both.
  • Remove one of the operator definitions.

(Z.100: 5.3.2)

ERROR 389 No matching operator signature found

The operator must be defined for this signature.

ERROR 390 This unexpected

The keyword this is only allowed in a procedure call, process create or "output to".

You get this error if:

  • You use the keyword THIS in normal diagrams.

To remove the error, either

  • Remove or replace the keyword THIS.
  • Convert the diagram to a type-based diagram.

ERROR 391 Context parameter %1 not allowed

(Z.100: 6.2)

ERROR 392 Call this invalidated by adding parameters to sub type

Call this cannot be used when formal parameters are added in the subtype.

You get this error if:

  • You use the keyword THIS in a procedure call and the called procedure is a super type to a sub type that adds parameters to be used in a procedure call.

To remove the error, either:

  • Make both the sub type and the super type use the same set of parameters by declaring all parameters in the super type if you intend to call the sub type.
  • Remove the THIS keyword if you intend not to call the sub type.

INFO 393 Instance path to the problem in previous message

This message provides additional information that may be used to locate the source of error in the previous message. This message may appear repeated times, depending on the depth of the SDL structure where the previous error is detected.

ERROR 394 Package Predefined expected, check installation

File predef.sdl does not contain the package Predefined. The error message appears only when you have altered the Telelogic Tau installation in an improper way.

ERROR 395 Type mismatch for view expression

You get this error if:

  • You view a variable of the wrong type. For instance, you assign a variable of type boolean the value of a viewed variable of type integer.

To remove the error, either:

  • Change the type either of the assigned variable or the viewed variable to match each other.
  • View another variable instead, that has the correct type.
  • Assign to another variable instead, that has the correct type.

ERROR 396 Viewed variable %1 is not revealed in block %2

The viewed variable must be declared as revealed in block %2.

ERROR 397 Context parameters are not supported

Context parameters are not implemented. Consider using an alternative approach.

WARNING 398 One line external formalism name expected on same line as alternative keyword

Syntax error! When using alternative the name of the alternative data formalism must occur on the same line as the alternative keyword.

ERROR 399 Type mismatch for timer active expression

You get this error if:

  • You are using the result of the ACTIVE call as if it had another type than boolean.

To remove the error:

  • Make sure you are using the result of the ACTIVE call as a boolean value.

ERROR 400 Type mismatch for any expression

Telelogic
http://www.telelogic.com


55 Analyzing a System

Analyzing a system means checking that its SDL description obeys the syntax and semantic rules as defined in the Z.100 recommendation (some syntax checking is performed by the SDL Editor at editing time).

The SDL Analyzer allows you to perform a complete syntactic and semantic check of an SDL system. This chapter describes the Analyzer and how you may use it to analyze an SDL system.

For a reference to the Analyzer commands and the Analyzer functionality and restrictions, see 54 The SDL Analyzer.


General Description

The Analyzer's main task is to perform syntactic and semantic analysis of SDL-92 definitions and diagrams, and to serve as a front end to code generators. You may perform full syntactic and nearly full semantic analysis of complete system definitions.

Analysis of separate units (block, process, substructure, service, and procedure) is also supported. Syntactic analysis may be performed on a unit, while restricted semantic analysis of a unit may only be performed if the context of the unit is provided. The context is the enclosing units and their definitions (for a detailed description, see the section "Separate Analysis" ).

The Analyzer works in a number of passes:

Figure 483 : Analyzer passes

  1. Conversion to PR. This pass is needed when input is not SDL/PR, i.e. for SDL/GR diagrams, ASN.1 files, C, and C++ header files. The result is a PR file with a "raw" layout, that is submitted as input to the next pass. This PR file is not intended to be read by the human. See "Conversion to PR" for a more thorough description.
  2. Macro expansion. This pass is needed when input contains references to macros (which need to be expanded). The result is a PR file where SDL macros are expanded. See "The Macro Expander" for a more complete description of the Macro Expander.
  3. Lexical and syntactic analysis. This pass checks that the input follows the SDL definition with respect to syntactic rules. During this pass, the Analyzer builds an abstract syntax tree that is used by the following passes. See "The Lexical and Syntactic Analyzer" for a more thorough description.
  4. Pretty-printing. This optional pass uses the pretty-printer to produce an SDL/PR file with a nice layout, easy to read and understand by the human. The pretty-printed PR file contains the original SDL specification formatted according to specific layout rules.
  5. PR to GR conversion. The input PR files are translated to SDL/GR diagrams, that you may open in the SDL Editor. This pass allows you to for instance import PR files from other tools supporting SDL. See also section "The PR to GR Converter" .
  6. Semantic analysis. During this pass, the Analyzer checks that your SDL diagrams obey the static semantic rules as defined in the Z.100 recommendation. During this pass, the Analyzer builds and uses a symbol table, which can also be used later by the Code Generators. The semantic analysis is likely to be the "bottleneck" when analyzing a system. See "Optimizing a System to Reduce Analysis Time" .
  7. After the semantic analysis pass, you may optionally generate:
    • cross-references listings of SDL entities; where they are defined in an SDL system, and where they are used (referred). The result from this pass is a file which contents may be displayed graphically in the Index Viewer. See 47 The SDL Index Viewer for more information.
    • instance tree information about the SDL system. The result from this pass is an instance information file consisting of records that describe the SDL entities that are present in the system after instantiation of all types. The file is a plain text file with a simple format. See "File Syntax" for more information.
  8. If your configuration includes a Code Generator1 you may include:
    • A C Code Generation pass, in order to generate a C description of your SDL system. This C code is then compiled and linked to generate a simulator, a validator or an application. The SDL to C Compiler is available as a Cbasic and as a Cadvanced code generator.
    • A Cmicro Code Generation pass. The generated C code is optimized with respect to memory requirements, making it suitable for generating applications for systems with limited resources.

Analyzer Input and Output

The input to the Analyzer consists of SDL-92 specifications, that is, SDL/GR diagrams that are stored using the storage format of the SDL suite, or SDL/PR files, or a combination of both.

The output consists mainly of PR files, error and warning messages. These messages are presented on the screen in a log window and may be stored on file. See "Error and Warning Messages" for a description of these messages.

It is also possible to obtain a pretty printed SDL/PR file of the input and to transform SDL/PR files into SDL/GR diagrams.

The Analyzer User Interfaces

The Analyzer provides the following user interfaces.

Graphical UI

When started from the Organizer with the Analyze command, the Analyzer takes advantage of the graphical user interface and integration mechanism of the SDL suite.

For instance:

  • Graphical references between source documents and error reports is supported, which facilitates locating and correcting errors in the source SDL diagrams.
  • An SDL-Make facility, managed by the Organizer, controls the Analyzer and brings down the analysis work that needs to be done.
  • On-line help on analysis diagnostics is available (provided the prerequisites for the on-line help are satisfied).

Batch UI

Suitable for running the Analyzer non-interactively. See "Batch Facilities" .

Command-Line UI

Suitable for working on the file level with detailed control. See "The Analyzer Command-Line UI" .

1

Although technically built into the Analyzer binary executable (sdtsan), the Code Generators are additional optional tools that are licensed separately.


Using the Analyzer

This section describes how you operate the Analyzer from the Organizer. We will discuss topics related to the various ways you may analyze an SDL structure. With the SDL suite, you may for instance perform syntax check on an SDL structure or check an entire SDL system with respect to the semantic rules.

Analyzing Using Default Options

To analyze an SDL structure using default options:

  1. In the Organizer, select the root node for the subtree that is the subject to be input to the Analyzer.

  2. Click the quick button for Analyze. The Organizer first checks if there are any unsaved diagrams; if any, the Organizer will prompt you to save these before analyzing them (since the Analyzer operates on the latest saved copy of a diagram).

  3. The Organizer determines what diagrams need to be analyzed and what passes need to be run, by looking at the time the diagrams were saved on file and by monitoring the Analyzer's work.
    • To perform an analysis, you may either "touch" the SDL diagram files or force the Analyzer by clicking the Full Analyze button (see Figure 484).
  4. The analysis job is submitted the to the Analyzer, using the options as they are currently defined in the Analyzer options dialog (see Figure 484).
  5. From now on, the status bar reads "Analyzer working". When done, the status bar will read "Analyzer ready".

Analyzing Using Customized Options

To analyze an SDL structure with customized options:

  1. In the Organizer, select the root node for the subtree that is the subject to be input to the Analyzer.
  2. From the Organizer's Generate menu, select the Analyze command. The Analyzer Options dialog is displayed.

Figure 484 : The Analyzer dialog

  3. Adjust, if required, some of the Analyzer options to their required values. These options govern what passes should be performed by the Analyzer, see Figure 483, and what output should be produced by the Analyzer. (The code generation pass options are however not controlled from this dialog.)
  4. Click the Analyze button. First, the Organizer checks if there are any unsaved diagrams; if any, the Organizer will prompt you to save these before analyzing them (since the Analyzer operates on the latest saved copy of a diagram).
  5. The Organizer determines what diagrams need to be analyzed and what passes need to be run, by looking at the time the diagrams were saved on file and by monitoring the Analyzer's work.
    • To perform an analysis, you may either "touch" the SDL diagram files or force the Analyzer by clicking the Full Analyze button.
  6. The Analyzer is initialized and starts executing (this is indicated in the Organizer status bar which now reads "Analyzer working").
  7. When the Analyzer has analyzed the input as specified in the options, the Organizer status bar reads "Analyzer ready". The results of the analysis are reported in the Organizer log window.

Performing Syntax Check

  1. If the input contains SDL macros, you should expand these before proceeding with the syntax analysis in the resulting SDL/PR file.
    • Turn the Macro expansion button on to order expansion of SDL macros.
  2. Turn the Syntactic analysis button on to include the syntax checking pass.
  3. Click the Analyze button.

Performing Semantic Check

Turn the Semantic analysis button on to include the semantic check pass. This option cannot be turned on unless the Syntactic analysis pass is enabled. The semantic checker may be set up with by a number of options, each one individually activated by a toggle button.

Note: Optimizing a System to Reduce Analysis Time

There are two components that, to a large extent, affect the performance of the "resolution by context" in the semantic analysis pass:
  • The depth of the expressions, because all possible combinations must be tried.
  • The size of the system, because the context is all the visible identifiers.
Deeply nested expressions may cause a significant degradation of performance when performing the semantic analysis pass. It is therefore recommended to break down complex expressions into multiple, less complex expressions. Checking for Deep Expressions (see below) can assist you doing this.
If it is an option to modify your system, it might be worthwhile to go through all synonyms, newtypes and syntypes at the system level and move them as far as possible down the system structure. This makes the context visible to every expression smaller and reduces the time spent in "resolution by context". (Doing the same thing at lower levels will also improve performance, but not as much as on higher levels.) The Index Viewer might be useful in accomplishing this.

Checking Output Semantics

The Check output semantics option controls whether to issue warnings when SDL signal sendings, where the semantics is different in SDL-88 and in SDL-92, are detected. These warnings are particularly valuable when the input consists of SDL diagram that were designed in SDL-88 (for instance with SDT 2.X).

Detecting Not Used Definitions

The Check unused definitions option, when turned on, orders the Analyzer to report definitions that are not used (for instance variables that are declared but neither written or read).

Checking Optional Parameters

The Check optional parameters option controls whether to issue warnings when an optional parameter is omitted from a procedure call, an output, a create request, or an input. Note that in/out parameters are not optional. An omitted parameter is indicated by empty parenthesis or a comma. See also Checking Trailing Parameters, below.

Checking Trailing Parameters

The Check trailing parameters option controls whether to issue warnings when the number of actual parameters is not equal to the number of formal parameters in a procedure call, an output, a create request, or an input. See also Checking Optional Parameters, above.

Checking Unique References

When the Check references option is activated, the Analyzer will check that each remote definition is referred only once. Turn this button off to disable this check.

Checking Missing Else Answer

The Check missing else answers option controls whether to issue warnings when an else part is expected but does not exist among the branches in a decision or transition option statement.

Checking Missing Answer Values

The Check missing answer values option controls whether to issue warnings when there are values not covered by any of the branches in a decision or transition option statement.

Allowing Implicit Type Conversions

The option Allow implicit type conversion controls whether implicit type conversions of reference data types (generators Own, ORef, and Ref) are allowed. For more information, see "Implicit Type Conversions.

Note:

Analyzing large expressions with this option on is slow.

Generating a Cross Reference File

Turn the Generate a cross reference file option on to have the Analyzer generate a file with a list of definitions and references to SDL entities, as an supplementary result from the semantic pass. You may also want to specify another file name than the suggested one. The contents of this file may be read and visualized graphically with the Index Viewer.

Generating an Instance Information File

Turn the Generate an instance information file on to have the Analyzer generate a file with instance information about the analyzed system. The name of the file can be set in the field below. The file is produced after the semantic pass. Read more about the contents of an instance information file in "SDL Instance Information" .

Checking for Deep Expressions

Adjust the Expression depth parameter to specify the depth limit that the Analyzer should check for when evaluating expressions. Expressions which depth exceed the specified limit will be reported. Where possible, try to break down deep expressions since they require advanced calculations and slow down the Analyzer.

Specifying the Error Limit

Adjust the Error limit parameter to an adequate value (drag the slider for coarse adjustments, click left or right on the bar for fine adjustments). The Analyzer will stop its execution once this error limit has been reached.

Using a Filter

With the Filter command files can be filtered or preprocessed before they are read by the Analyzer. The specified executable file will be called with two arguments: the file to be processed by the Analyzer, and the Analyzer pass to be executed (import, macro, or parse). Try a simple OS command and look in the Organizer log to find out exactly how it is called.

Tracing the Analyzer Execution

You can trace the execution of the Analyzer by turning on the option Echo Analyzer commands. All Analyzer commands are then printed in the Organizer Log as they are executed.

Terminating the Analyzer Process

Turn on the option Terminate Analyzer when done if you want the Analyzer process to terminate after analysis is done. Otherwise, the Analyzer process is left running in the background.

Locating and Correcting Analysis Errors

The results of the Analyzer are appended to the Organizer Log Window. (You may save the window contents on any file at any time). The results of the last run are also saved on a file with the predefined name analyzer.err

The SDL suite provides a nice feature for displaying the source of an analysis error:

  1. Locate the Organizer log (select Organizer Log if required).
  2. Select the error (or warning) message by dragging the mouse.

Figure 485 : Selecting an error message

    • The selection must contain at least the line starting with the text #SDTREF (for more information on the format of references, see 19 SDT References).

  3. Select the menu choice Show Error from the Tools menu.

  4. The symbol where the error has been detected is displayed in an SDL Editor window. When the reference also contains a line and a column reference, the text cursor is placed on the line and column of text where the error was detected.

  5. If you need additional explanations to understand the error message, select Help on Error from the Tools menu.

Producing a Pretty-Printed SDL/PR File

You may produce a pretty-printed PR file with the Analyzer, with a single command. The layout used by this PR makes it easy to read by the human. You may either submit SDL diagrams or SDL/PR files as input to the pretty-printer.

To be able to pretty-print SDL/PR, the SDL suite requires that the input must be syntactically correct. If the input does not fulfill this requirement, the SDL suite will however produce a PR file with a "raw" layout. This file is used by the SDL suite as a temporary file and it does not address the human reader.

  1. In the Organizer, select the root node of the SDL structure to be pretty-printed.
  2. From the Generate menu, select Convert to PR/MP. The Convert to PR dialog is displayed:

Figure 486 : The Convert to PR dialog

  3. Adjust, if required, the conversion options:
    • You may specify a PR file as alternative input. (The default input is the SDL structure designated by the object selected in the Organizer.) To do this, type in the name of a file into the PR file text field.
    • You may order the Analyzer to capitalize SDL reserved words or not; select the appropriate option from the Write reserved words in option menu.
    • If the SDL structure contains #INCLUDE references to SDL/PR files, you may want to expand these and include them in the resulting pretty-printed PR file. Turn the Expand included PR files button on to order expansion of included PR files.
  4. An output file where the resulting SDL/PR code will be stored is suggested. You may specify any other file to store the results on in the Destination PR file name text field.
  5. If the input contains SDL macros, you may want to expand these in the resulting SDL/PR file.
    • Click the Analyze Options button to gain access to the Analyzer options dialog, where you turn the Macro expansion button on and click the Set button.
  6. Click the Convert button to close the dialog and have the Analyzer start the conversion to SDL/PR.

Converting SDL/PR to SDL/GR

You may convert SDL/PR files to SDL/GR diagrams, storing them on files using the native format of the SDL suite. Once converted, these SDL descriptions may be managed, edited and printed by the graphical tools of the SDL suite just as if they were created using the SDL suite.

To convert an SDL/PR file to SDL/GR diagrams:

  1. From the Organizer, Generate menu, select Convert to GR. A dialog is displayed:

Figure 487 : The Convert PR to GR dialog

  2. Specify the PR file to convert from. You may either type the file specifier or click the folder button to issue a File Selection Dialog.
  3. Specify the destination directory, where to store the results of the conversion. You may either type the name of a directory or click the folder button to issue a directory selection dialog.
  4. You may specify other options:
    • Whether to capitalize SDL reserved words or not, by selecting the corresponding option from the option menu.
    • Whether to expand any included PR files or not (PR files are included using a #INCLUDE directive inside an SDL comment statement).
  5. If required, click the Analyze Options button to modify the Analyze options (typically, you may need to turn the Macro Expansion option on). Close the Analyze Options dialog with the Set button (see Figure 484).
  6. Click the Convert button to order the conversion. The Organizer's status bar reads "Analyzer ready" when the conversion is completed.
    • Each diagram that is specified (or included and expanded) in the source PR file is transformed to one file. These files are assigned default file names (see "Save in file" ).
    • The generated diagrams are assigned a layout by the SDL Editor.
    • Error and warning messages, if any, are appended to the Organizer log window.
  7. To look at the resulting diagrams, you may either open the resulting files in the SDL Editor.
    • Alternatively, identify the root diagram file that has been produced. (You may need to look at the input SDL/PR file to determine what file to look for.) Then, import this file into the Organizer, with Import SDL from the File menu. Specify the root diagram file as Root document.

Figure 488 : Importing an SDL structure


56 The Cadvanced/Cbasic SDL to C Compiler

The Cadvanced/Cbasic SDL to C Compiler translates your SDL system into a C program that you can compile and link together with a runtime library to form an executable program such as a simulator, a validator or, in the case of Cadvanced, an application.

This chapter is a reference manual to the Cadvanced/Cbasic SDL to C Compiler. There are also a number of other chapters related to code generation:

  • In 49 The SDL Simulator, you will find a reference to the simulation facilities in the SDL suite. In 50 Simulating a System, you will find a user's guide to the simulator.
  • In 52 The SDL Validator, you will find a reference to the validation facilities in the SDL suite. In 53 Validating a System, you will find a user's guide to the validator.
  • In 57 Building an Application, you may read about how to generate applications for host and target environments.
  • In 61 The Master Library, you will find information about how to customize your own libraries for a specific purpose, such as application generation for target computers. The chapter also describes the structure of the generated C code and the internal data structures in the generated C code.
  • In 62 The ADT Library, you will find a reference to the library of abstract data types that is distributed with the SDL suite and that you may use in your systems designed in SDL. Some examples of use are also available.
  • In 63 The Performance Library, you may read about how to generate and run simulators which are specially adapted for the area of performance simulation.


Introduction

Application Areas for the Cadvanced/Cbasic SDL to C Compiler

There are a number of application areas for the Cadvanced/Cbasic SDL to C Compiler, for example:

  • Functional simulation and debugging of protocol specifications
  • Debugging of system designs described in SDL
  • Generation of applications, including embedded system applications with real time characteristics
  • Performance simulations
  • Simulation of the behavior behind a user interface prototype

In this part of the manual, the general behavior of the code generator and its application for simulation and debugging are discussed. The possibility to generate simulators is described in 49 The SDL Simulator .

Functional Simulation and Debugging

During the validation of a specification or design of an application expressed in ITU SDL, you can use the Cadvanced/Cbasic SDL to C Compiler as a tool for simulation to help you understand and debug the behavior of a system description. (See 49 The SDL Simulator.)

Errors arising from two different areas have to be considered in the validation process. In the language domain, errors due to illegal or illogical usage of the language concepts might be introduced into the specification; while in the problem domain, logical errors might be introduced.

With traditional computer program development, most illegal uses of language concepts are found by compilers or by run-time systems. Examples are syntax errors, missing declarations, division by zero, or indexing an array out of its bounds.

In the problem domain, however, the only feasible ways of detecting logical errors in non-trivial programs are testing and proofreading. When it comes to specifications in SDL, language domain errors can be detected by using the SDL Analyzer, which can be seen as a compiler without a code generation facility (see 54 The SDL Analyzer). To detect problem domain errors, testing by simulating the specification is the main procedure available. Please see also 52 The SDL Validator.

The specification of a protocol in SDL, for instance, specifies a signal interface by giving a hypothetical implementation of the components in the protocol. This strategy immediately brings up two different purposes for simulating the behavior of a system specification: to understand the external view and to understand the internal view.

In the external view, the signal interface is of concern, while the internal behavior of the system specification (the behavior of the processes in the system) is of little or no interest. In the internal view, the internal behavior of the system specification is of concern, while the external signal interface is simply seen as part of the internal behavior.

A simulation of the internal behavior of a system specification constitutes an important part of the validation of the specification, both as a debugging tool and as a means to increase the understanding of the dynamic behavior of the specification. A designer of a system might use this kind of simulation to understand the specification better.

The ability to simulate and debug applications generated by the code generator at an SDL level is a very important feature towards achieving the correct overall behavior of the application. The debugging facilities provided by the SDL suite have much in common with interactive debuggers for ordinary programming languages. The debugging is performed on a host computer.

Another application of the code generator as a simulator generator, is of course in SDL education, where simulation, especially of the internal behavior of a system specification, can serve as a powerful way of clarifying the semantics of SDL concepts.

Performance Simulation

The Cadvanced/Cbasic SDL to C Compiler can be used for performance simulations. You describe the performance model of the actual system using SDL. This model can be translated to a simulation and executed. By introducing measurements of interesting data, such as queue lengths, delays, and so on, into the SDL model, it is possible to gather statistical data during the execution of the simulation. In 63 The Performance Library, you can find a description of the performance simulation facilities.

To simplify this kind of simulation, a number of SDL abstract data types and their implementations have been developed, where, for example, random number generation and handling of queues are supported. Please see 62 The ADT Library.

Validation

The SDL Validator uses the code produced by the Cadvanced/Cbasic SDL to C Compiler to form a program suitable for validation of an SDL system. The Validator uses state space exploration and can be used to:

  • Find run time errors
  • Verify MSCs against the SDL system
  • Verify user defined rules

The Validator is described in 52 The SDL Validator.

Communicating Simulations

You can specify that a generated C program should be able to communicate over the PostMaster, which is the mechanism used for communication between the SDL suite tools. Signals sent from the SDL system (the generated program) to the environment and signals coming to the SDL system from the environment can be handled. This facility makes it, for example, possible to develop simulation programs for two communicating systems, execute them using the SDL suite and obtain communication between the systems.

As a generated C program does not know what it communicates with, it can of course communicate with any type of application, as long as the application is connected to the PostMaster (the communication medium) and sends signals according to the defined format. How to achieve this is described in 13 Using the Telelogic Tau Public Interface.

A very interesting group of such applications are user interfaces. By connecting a user interface and an SDL simulation you can achieve several things: You can, for example, build well-designed application oriented user interfaces that present what is going on in a simulation, or you can in a simple way define the logic behavior behind a user interface during its prototyping phase.

Overview of the Cadvanced/Cbasic SDL to C Compiler

To facilitate the validation of SDL specifications or descriptions, the SDL Analyzer contains an SDL parser, an SDL semantic checker, and the Cadvanced/Cbasic SDL to C Compiler.

Creating a C Program

To obtain an executable program that behaves according to an SDL description, you enter the SDL description into the SDL Analyzer, which contains the Cadvanced/Cbasic SDL to C Compiler. If the SDL description is syntactically and semantically correct, a C program is generated. You then compile this program using an ordinary C compiler and link it with a predefined SDL run-time library to form an executable program. See Figure 489.

As indicated above, the C code generation facility contains two components:

  • The SDL to C Compiler, which can be seen as a back-end to the SDL Analyzer. This component generates a C program.
  • Predefined and precompiled C units, which implement an SDL runtime library and the command line user interface of a simulator, that is, a monitor system. The run-time library also includes a communication mechanism which makes it possible to trace the execution of SDL transitions in the SDL Editor. There are several versions of the library that are suitable to different application areas for the generated C code, see "Libraries" .

Figure 489 : The production of an executable program

Executing a C Program as a Simulator

The generated C program uses an internal data representation of the SDL objects in the system, for example process instances and signal instances. The process instances will execute transitions in a quasi-parallel manner. During a transition, SDL actions such as tasks, decisions and signal outputs are executed according to the semantics of SDL.

You interact, using SDL terminology, with the simulator through a monitor system, which contains a number of commands to:

  • Control the execution of transitions.
  • Examine the status of objects in the system.
  • Turn log facilities on and off.
  • Affect the system by, for example, sending signal instances from the environment to the system.

Contents of This Chapter

You can find more details on creating and executing a C program in the following sections:

  • In "Generating a C Program" , the process of generating a C program is described.
  • In "Abstract Data Types" , implementation aspects especially concerning abstract data types, are described.
  • In "Directives to the Cadvanced/Cbasic SDL to C Compiler" , possibilities to give additional information to the Cadvanced/Cbasic SDL to C Compiler are discussed.
  • The section "Using Cadvanced/Cbasic SDL to C Compiler to Generate C++" , contains considerations on class definitions as C++ code and the utilization of the classes as C++ code in SDL tasks.
  • In "Restrictions" , the Cadvanced/Cbasic SDL to C Compiler restrictions are covered.


Generating a C Program

A generated C program can be used for several things, for example as a simulator, as a validator, or as an application with the behavior defined by the translated SDL system. The process of generation of simulators, validators, or applications, see below, is started in the Organizer, in the make dialog (see "Make" ) or by the quick buttons for simulation and validation (see "Quick Buttons" ).

The SDL Analyzer, which contains the C code generation facility, can also be started as a stand-alone tool. For more information about this possibility please see "The Analyzer Command-Line UI" .

Process of Generating a C Program

There are four steps that must be performed to start the execution of, for example, a simulator:

  1. The SDL Analyzer and its built-in Cadvanced/Cbasic SDL to C Compiler create a program expressed in C source code.
  2. The generated C file (or files) is compiled.
  3. The compiled file (or files) is linked together with a predefined library.
  4. The executable program that is created in the link operation is started.

This process has been automated and requires no user knowledge about compiling or linking of programs. The process is initiated in the Organizer using the quick buttons for simulation and validation, or by using the Make dialog.

A C program can only be generated for an SDL system. The C code that constitutes the program can, however, be generated on multiple files, which means that a local change in, for example, a block diagram only requires a regeneration and recompilation of the code for that unit. The object files, (the compiled versions of the C files) for the other unchanged units can then be used in the link operation to form a new executable program. This feature in automatically used by the make facility and the quick buttons, to minimize the amount of work and thus the turn-around time, for the process from a change in the SDL system to a new simulator (for example).

The separation of the C code for an SDL system can be decided by the user. The Edit Separation command from the Generate menu is used for that purpose, see "Edit Separation" . The effect on the generated file structure and some guidelines of how to use separation can be found in the section "Selecting File Structure for Generated Code - Directive #SEPARATE" .

Executing a C Program

The generated C programs can in principle be compiled as either a simulator, a validator, or an application. Generated applications have no further connection with the SDL suite and are executed as any other application.

A generated simulator or validator can however be started in two different ways:

  • From the Simulator Graphical User Interface, which is started from the Organizer with the SDL > Simulator UI command and provides a graphical interface with buttons and menus and of course full connection to other SDL suite tools. See "Graphical User Interface" for more information.
  • From an OS shell, just like any other executable program. The user then invokes a command line monitor system. If the Organizer is running when starting a simulator or validator, the program will connect itself to the SDL suite. If the Organizer is not running or the simulator/validator is started with the program parameter -nosdt, the program will not connect itself to the SDL suite.

The SDL Unit for Which Code is Generated

The first time a C program is generated for a system, the complete system will be selected for analysis and C code generation. After that only the unit (system or block) that is changed will be selected. Note that the lowest level of possible regeneration object is a block. That block may not be a block type, or be part of a block type or system type. The reason that a process cannot be generated without regenerating the enclosing block, is that internal process information about, for example, formal parameters are used to generate code for other processes within the same block.

  • Only complete C files can be generated. If, for example, the user has specified that a block and a sub-block should be generated on the same file, it is not possible to regenerate code only for the sub-block.
  • If the file structure is changed (by, for example, changes in the Edit Separation command or in the #SEPARATE directives), then the complete system is regenerated.

Errors During Code Generation

Errors that may occur during code generation are internal errors. That is, errors due to not yet implemented features of SDL, and errors related to problems with opened or closed operations of files.

An error message starts with an SDT references and is followed by a description of the error, including a error number. Example:

ERROR 884 Not implemented: Signal refinement


Features

Partitioning

General Ideas

The partitioning concept is a way to divide one SDL system into several applications. As a special case this means also that it is possible to simulate and validate selected parts of a system. You should note the difference between partitioning and separation. The partitioning feature is a way to select the parts of an SDL system which should be handled, while the separation feature is a way to select the file structure for the generated files.

To select a partition (or a program) it is, in simple cases, possible to use selections in the Organizer, and in more general cases possible to work with build scripts, i.e. text files containing commands to the Analyzer (the syntax used when running the Analyzer stand-alone). The restriction in the Organizer view is that only one selection can be handled and that instantiation of OO types cannot be selected. In a build script on the other hand, several component commands can be used to select several parts of a system. As the component command takes an SDL qualifier as a parameter, instantiations can also easily be selected.

Using Selections in the Organizer

To start with the simple case when one block or process should be simulated, this is easy to perform directly from the Organizer: Select the proper block or process and press the Simulate button (or go via Make dialog).

Note:

If you already have generated a simulation from the Organizer, and want to generate a new one with other options or with another selection, you should perform a Full Make, as changes in options or selection is not handled by the build process. Otherwise compilation or link errors might be the result of the build process.

Only the system, a block or a process can be selected for simulation. Types, including procedures, are only definitions and are not executable objects, while services depend on its enclosing process and cannot be simulated on its own because of these dependencies. Block and process instantiations can be simulated, but only using build scripts, as such objects cannot be selected in the Organizer. The discussion above is of course also valid for generation of validators and applications.

Unconnected Diagrams

As another special case, there might be unconnected diagrams in the Organizer, i.e. objects not bound to a file. If such an object is a block, process, or a procedure, C code can anyhow be generated resulting in, for example, a Simulator or Validator.

  • If a block is unconnected, this is treated as an implicit partitioning excluding this block.
  • If a process is unconnected, this is treated as an implicit partitioning excluding this process. If other processes try to "create" such a process, this will become a null-action just indicated in the textual trace. In an application, such a create action will cause a compilation error.
  • If a procedure is unconnected, any call to this procedure is just indicated in the textual trace. In an application such a procedure call will cause a compilation error.

Build Scripts

In general cases, build scripts should be used to specify the build process. Using such a file there are a number of features that can be used.

  • It is possible to generate code for several partitions, using independent options and potentially different code generators for different parts of the system, all in one build process.
  • Each partition can consist of several objects, and objects might be instantiations.

There are two Analyzer commands, see "Description of Analyzer Commands" , that are of major interest for specifying a partition. First we have the Program command, which takes a name as parameter. Second we have the Component command, which takes a qualifier as a parameter. The Program command gives the start of a partitioning specification, while the Component command is used to select an SDL component that should be part of the partitioning. A partition specification can of course contain a number of components. The Component command is very similar to a selection in the Organizer when running directly from the Organizer.

A program section in a build script typically starts with a Program command and ends with a Generate command.

Example 335 : Build script

program MyExample
component system example/block b1
component system example/block b2/process p22
target-directory /home/jk/example/target
set-env-header on
set-modularity user
generate-advanced-c

In Windows, the target-directory command could, for example, be:

target-directory c:\example\target

The example above means that a program containing the implementation of the complete block b1 and the process p22 in block b2 is generated with the Cadvanced SDL to C Compiler. The modularity is user defined and a system header file (.ifc file) will also be generated.

Code from the code generators will be placed in a subdirectory with the name given in the Program command, to the directory given by target directory. If this subdirectory does not exist it will be created.

Note:

You should always include a target-directory command in a build script, as otherwise the target directory will depend on where the SDL suite is started!

In the example above the generated C code can be found in the directory /home/jk/example/target/MyExample
(In Windows c:\example\target\MyExample).

In the example below three programs are generated for three different partitionings, also using different code generators.

Example 336 : Build script with several programs

target-directory /home/jk/example/target

program MyExample
component system example/block b1
component system example/block b2/process p22
set-env-header on
set-modularity user
set-kernel SCTDEBCOM
generate-advanced-c

program MyExample1
component system example/block b2/process p21
generate-micro-c

program MyExample2
component system example/block b3
set-modularity no
generate-chipsy-chill

Analyzer commands that are of the type "set up an option" can be placed outside of the Program commands. The options actually used at the generate commands, are the options set up after executing all the commands up to the generate command. All the possibilities in the Make dialog and the Analyze dialog in the Organizer are also provided as commands in the Analyzer. Please see "The Analyzer Command-Line UI" , for a list of all commands.

Note:

When build scripts are used, all features in the Analyzer will have its hard coded defaults, if it is not set in the build script. Preferences and your settings in the Organizer are ignored. The default values are given in "The Analyzer Command-Line UI" , or you can start a stand-alone analyzer (sdtsan) directly in an OS shell and issue the commands Show-Analyze-Options and Show-Generate-Options.

See also "SDL Make" , for handling of build scripts in the Organizer.

Behavior of Generated Partitioning

The basic idea is to redirect all channel going to objects not part of the current partitioning to the environment. This operation is performed by the code generator at code generation time. This means that all signals sent between objects in the partitioning and objects outside the partitioning, will be seen as signals to or from the environment. This is true everywhere, in simulations, validations, applications, in generated environment header files (.ifc files), and in generated environment functions.

Generation of Support Files

The Cadvanced/Cbasic SDL to C Compiler can generate a number of support files, together with the ordinary .c, .h, and makefiles. These files are

  • System header file (.ifc)
  • Skeleton to environment functions (_env.c)
  • Signal number file (.hs)
  • Coder/decoder framework files (_cod.c, _cod.h)

The generation of these files can be selected in the Organizer Make dialog, or as an Analyzer command, depending on which interface is used. The details on the system header files and the environment function can be found in "The Environment Functions" , while the signal number file can be used to assign numbers to all signals in the system. Signal number files are most used in connection with OS integrations.


Implementation

In this section some implementation details are presented, that can be useful for understanding how a generated simulation or application behaves. Abstract data types are treated in the next section.

Time

A generated C program can be executed in two modes with respect to the treatment of time:

  • Simulated time
  • Real time

Simulated Time

Using simulated time, which is the most useful mode for simulations, means that the time in the simulation has no connection with the wall clock. Instead the discrete event simulation technique is used. This technique is based on the idea that the current value for the simulation time (Now in SDL) is equal to the time at which the currently executing event is scheduled. After one event is finished, the simulation time is increased to the time when the next event is scheduled and this event is started. Events in SDL will be process transitions, timer outputs, and signals sent to the system from the environment. As an example, the use of the discrete event simulation technique means that if the next event is a timer output scheduled one hour from now, and the next transition is allowed to execute, the timer output will occur immediately. The simulation time will be increased by one hour, but the user does not have to wait one hour.

Real Time

If real time is used, then there will be a connection between the clock in the executing program and the wall clock. In the example above the user would have to wait one hour until the timer output took place. To implement real time a clock function provided by the operating system is used. Not all systems are suitable to simulate in this way. The time scale in the system ought to be seconds or maybe minutes, not milliseconds and not hours.

At program start up the system time, SDL Now, is zero. The system clock is stopped during the time the program spends in the monitor system.

Note:

The C standard function time used as real time clock returns the time in seconds. It does not handle parts of seconds. The implementation of the clock can be changed by re-implementing the function SDL_Clock in sctos.c.

Scheduling

The process instances in the simulated system will execute transitions that consist of actions like tasks, decisions, outputs, procedure calls, etc., according to the rules of SDL. It is assumed that a transition takes no time and that a signal instance is immediately placed in the input port of the receiver when an output operation occurs.

A transition is always executed without any interrupts, if the user does not manually rearrange the ready queue using an appropriate command provided by the monitor system (Rearrange-Ready-Queue). It is possible to execute a few SDL symbols in one transition and then to re-arrange the ready queue and execute another transition. The interrupted transition can afterwards be executed to its end.

A quasi-parallel strategy for selecting transitions to be executed is thus the basic scheduling mechanism. SDL does not in itself define an execution strategy so the selected strategy is therefore an allowed, but not the only, possible strategy for execution.

As a consequence of the execution strategy, a generated simulator is not directly suited for simulation of "timing effects", that is, situations where the time or order of actions in different process instances is of vital importance.

Example 337 : Scheduling

An example of such a situation is: Suppose a process instance A outputs two signal instances during the same transition, one to process instance B and one to process instance C. During the corresponding transitions of B and C, a signal instance is sent to process instance D.

If the behavior of the system is dependent on the order in which the signal instances are received in the input port of D, this is a hazard situation where the execution speed of process instances and the delay of signals in channels will determine the behavior. The way to handle such a situation would be to manually decide the order in which transitions should be executed.

As the Cadvanced SDL to C Compiler is also intended to generate applications, process priority has been introduced as an additional feature. For more information about how to assign priorities to processes see sub-section "Assigning Priorities - Directive #PRIO" .

The Ready Queue

The ready queue is a queue containing all process instances which have received a signal that can cause a transition, but which have not yet completed that transition. The ready queue is ordered firstly according to the priority and secondly according to insert time, that is a process which will be inserted last among the processes with the same priority, but before all processes with lower priority (high priority value = low priority). A process will never be inserted before the process currently executing, as pre-emptive scheduling is not used. In more detail:

  • If a process outputs a signal to another process, which immediately can receive the signal, the receiving process will be inserted into the ready queue last among the processes with the same priority, but never before the currently executing process.
  • If the processes currently executing a nextstate immediately can continue to execute another transition, it will be inserted into the ready queue last among the processes with the same priority. This means that it can remain as first process in the ready queue, but it can also be re-inserted somewhere else.
  • If the receiving process at a timer output immediately can execute a transition as response to the received signal, the process will be inserted into the ready queue last among the processes with the same priority. This means that it can be inserted anywhere in the queue.

Enabling Conditions and Continuous Signals

Enabling conditions and continuous signals are additional concepts in SDL. The model for these concepts use repetitive signal sending, to have the expressions recalculated repeatedly. This model is not suitable during simulation, and definitely not acceptable in an application. We have therefore used an implementation strategy closer to the described behavior of the concepts, rather than the model used to define the concepts.

Implementation Strategy

First we distinguish between those enabling conditions and continuous signals that are dynamic and those that are static, that is containing expressions that can or cannot change their value when the corresponding process is waiting in the state. The expression in a dynamic enabling condition or continuous signal contains some part that can change its value, even though the process does not execute any statements. Or, put more precisely, it contains at least one import, view, or reference to Now.

Static enabling conditions or continuous signals do not provide any problems or any execution overhead, except that the corresponding expressions have to be calculated at nextstate operations. Dynamic enabling conditions or continuous signals, however, have to repeatedly be recalculated. The strategy selected for these expressions is to recalculate them after each transition or timer output performed by any process (and additionally also before the monitor is entered within a transition). In other words, each process waiting in a state containing a dynamic enabling condition or continuous signal executes an implicit nextstate operation between each transition or timer output performed by other processes.

Synonyms

Synonyms

An SDL synonym is implemented either as a C macro (#define) or as a C variable. To be translated to a macro the expression defining the value of the synonym must be:

  • Of one of the predefined SDL sorts (Integer, Real etc.).
  • Possible to calculate at analyze time, i.e. it may only contain literals and operators defined in the predefined SDL sorts and other synonyms which are possible to calculate at analyze time.

All other synonyms are implemented as variables given their values at program start up.

The reason for raising this question is because it is relevant to the implementation of arrays and powersets. There are two different implementations for each of these concepts, see "Array" and "Powerset" . An array in SDL can either be translated to an array in C or to a linked list in C. A powerset can either be translated to a bit array in C or to a linked list. The translation method is selected by looking at the index type. If the index type is a syntype with one limited range, the array and bit array scheme is used, otherwise the linked list is used.

If a synonym translated to a variable is used in a range condition of a syntype and the syntype is used as an index sort in an array or powerset instantiation, the linked list scheme is used to implement the array or powerset. The reason for this is that the length of the array cannot depend on a variable in C.

External Synonyms

External synonyms can be used to parameterize an SDL system and thereby also a generated program. The values that should be used for the external synonyms can either be read by the generated program during start up, or included as macro definitions into the generated code. The Cadvanced/Cbasic SDL to C Compiler can handle both these cases - it is not necessary to select which way should be used for each synonym until the program is compiled.

Using a Macro Definition

To use a macro definition in C to specify the value of an external synonym, perform the following steps:

  1. Write the macro definitions on a file.

Example 338 : Macro Definition

#define synonym1 value1
#define synonym2 value2

The synonym names are the SDL names (without any prefixes) and with any character not in letters, digits or underscore removed.
  2. Introduce the following #CODE directive at the system level among the SDL definitions of, for example, synonyms, sorts, and signals but before any use of the synonyms.

Example 339 : #CODE Directive

/*#CODE
#TYPE
#include "filename"
*/

If this structure is used, the value of an external synonym can be changed merely by changing the corresponding macro definition and recompiling the system.

Note:

When an application is created, macro definitions should be used for all external synonyms, as the function for reading synonym values stored on file is not available. (See below.)

Reading Values at Program Start up

The other way to supply the values of the external synonyms is to read the values at program start up. If there are any external synonyms that do not have a corresponding macro definition, it is possible to choose between supplying the values of the remaining external synonyms from the keyboard or to use a file containing the values.

When the application is started, the following prompt appears:

External synonym file :
  • Press <Return> to indicate that the values should be read from the terminal.
  • Or type the name of a file that contains the values and press <Return>.

If the user chooses to read the values from the terminal, he will be prompted for each value. In the other case the user should have created a file containing the external synonym names and their corresponding value according the following example:

Example 340 : Values at Program Startup

synonym1 value1
synonym2 value2

The synonyms may be defined in any order.

Import - Export

These concepts are not implemented with the full semantics according to the model in the SDL recommendation. The model says that an imported value should be obtained using a signal interchange between the importer and exporter.

In the Cadvanced/Cbasic SDL to C Compiler we use a model where the imported value is directly obtained from the exporter, which of course makes the import operation much faster. However, the scheduling effect of the signal interchange is lost, as well as the change of SENDER in the involved processes. If these effects are important for an application, remote procedure calls can be used instead, see below.

Remote Procedure Calls

Remote procedure calls (RPC) have much in common with import/export, except that instead of obtaining one value, RPCs give the opportunity to execute a procedure in the exporting process. In the Cadvanced/Cbasic SDL to C Compiler, the model described in the SDL recommendation is used in detail to implement RPCs.

This means that a remote procedure call is translated to:

output of pCALL signal with all parameters.
nextstate in pWAIT, i.e. a implicit wait state.
input of pREPLY signal with all IN/OUT parameters.

In the exporting process there will be implicit transitions where the pCALL signal can be handled.

input pCALL.
call remote procedure with parameters from pCALL.
output pREPLY with the IN/OUT parameters.
nextstate -

For more details about this model, please see the SDL recommendation.

Procedure Calls and Operator Calls

In SDL-92 value returning procedures (and remote procedures) are introduced. This means that an SDL procedure can be called within an expression. In the Cadvanced/Cbasic SDL to C Compiler such procedure calls are implemented according to the model in the SDL recommendation, that is by inserting an extra CALL just before the statement containing the value returning procedure call. The result from the call is stored in an anonymous variable, which is then used in the expression.

Example 341 : Procedure Call

TASK i := (call p(1)) + (call Q(i,k));

is translated to:
CALL p(1, Temp1);
CALL q(i, k , Temp2);
TASK i := Temp1 + Temp2;

Note:

The value returning procedure calls are transformed to ordinary calls, by adding a new IN/OUT parameter for the procedure result, last in the call.

Operators which are defined using operator diagrams, are according the models in the SDL recommendation, treated exactly as value returning procedure.

External Procedures And Operators

External procedures is a extension to SDL introduced in SDL-96. An external procedure is defined in a text symbol as a procedure heading:

procedure test; fpar a integer; returns integer;
external;

Instead of giving an implementation for the procedure the keyword external is inserted. The purpose of external procedures in SDL are to specify the existence of procedures without giving their implementation.

The Cadvanced/Cbasic SDL to C Compiler will generate no code for an external procedure declaration and will translate a call to such a procedure to an ordinary C function call. It is then up to the user to provide the C implementation of this function. Note that the code generator will in the generated function call use the name of the external procedure as it is. No prefix is inserted in this case, just as for external synonyms.

External operators are handled in the same way as external procedures. The name of the external operator is used in C just as it is. A quoted operator will cause an infix operator to be generated, while operators with ordinary names will cause C function calls to be generated.

Any

There are two different applications of any. It is possible to write

any(SortName)

within an expression, or to write just

any

in a decision. The second case, with any in a decision, is implemented in the following way:

  • Simulator:
    A question in the monitor giving the user a possibility to select the path to follow.
  • Validator:
    The validator sees this as an non-deterministic choice and selects all possible paths.
  • Applications:
    Should not be used!

The first case, the any(SortName) within an expression, is implemented using a random number generator to draw a random number of the given type.

Note:

any(Sort) where Sort is a syntype is only implemented if the syntype contains at most one range condition which is of the form a:b, that is one limited range. If it is a syntype of a real type, e.g. Real or Time, with a range condition it is not implemented.

If any(SortName) is used for a sort violating the note above, there will be a C compilation error on the symbol ANY_SortNameWithPrefix. This means that a user can implement any for such sorts himself by defining a C macro with this name, that implements any for the given sort. Such a macro should be inserted in the #TYPE section of a #ADT directive in the syntype.

Calculation of Receiver in Outputs

The Cadvanced/Cbasic SDL to C Compiler contains an algorithm that calculates the receiving process instance set, for outputs without TO, considering channels, signal routes, connection points, and via list. There are however a few restrictions for the algorithm:

  • Outputs in process types, or in processes in block types or system types cannot be handled. The reason is that the same output might lead to different receivers in different instantiation.
  • Paths (channels - signal routes) that lead into other units that are separate (see "Edit Separation" ) cannot be followed by the algorithm, as that would violate the separate generation scheme.
  • Outputs in global procedures cannot be handled, as the receiver depends on the caller of the procedure.

This algorithm means that for an ordinary SDL-88 system, that is not generated using separate units, no information about the channels and signal routes are needed to direct signal to the correct receiver. For more information about the possible optimizations in applications, please see the compilation switch XOPTCHAN and the ADT PidLit ("The Data Type PIdLit" ). Please note that XOPTCHAN and PidLit is almost impossible to use if the SDL system contains system types, block types, or process types.


Abstract Data Types

This section is a reference to the abstract data types. The following topics will be discussed:

  • We will have a look at the implementation of the predefined data types in SDL, see "SDL Predefined Types" . We then discuss how user-defined abstract data types are translated, see "Translation of Sorts" .
  • Next implementation of operators and the possibility to include hand-coded C functions as implementation of the operators is presented, see "Implementation of User Defined Operators" .
  • Last, in "More about Abstract Data Types" , we discuss more details about operators and the possibilities to include a hand-coded type definition in C to represent the SDL sort.

Removing un-used SDL Operators

When implementing an SDL system, you do not always use all available SDL operators. The Cbasic/Cadvanced SDL to C Compiler removes the declarations of unused operators, thus minimizing the code size of the generated application. Unused operators that are removed are:

  • operators in predefined data types, for example substring, concatenate, length in the newtype Charstring, etc.
  • operators defined in the predefined generators String, Array, Powerset, Bag
  • special operators (and help functions) like assign, equal, default, make, extract, modify, free

The Cbasic/Cadvanced SDL to C Compiler performs the following steps to optimize the code:

  1. Every C function that implements an operator is surrounded by an #ifndef definition.

Example 342 The #ifndef definition

#ifndef XNOUSE_AND_BIT_STRING
/* function implementing the operator */
#endif

  2. During the code generation, the usage of the operators in the translated SDL transitions is recorded.
  3. The interdependencies between different operators are updated. For instance, an equal operator for a struct type may depend on equal operators for all its component types.
  4. For each operator that is found to be unused, a #define definition is generated that removes the code for that operator. All the defines are placed in a file called sdl_cfg.h.

Example 343 The #define command

#define XNOUSE_AND_BIT_STRING

Note:

Even though the code size of the generated application is reduced, the code size of the generated C code is increased.

Manual override

In order to handle cases where operators are used invisibly from the Cbasic/Cadvanced SDL to C Compiler, for example in inline C code, you can manually override the automatic configuration of the unused operators.

In the code generation process, the Targeting Expert always generates a manual configuration file called sct_mcf.h. In this file you can list the unused operators that you have decided to include in the application. This is done by un-defining the previous definitions made in the sdl_cfg.h file.

The sct_mcf.h can be edited directly from Targeting Expert. Select Edit Configuration Header File from the Edit menu to open the file.

Example 344 The #undef command in the sct_mcf.h file

#ifdef XNOUSE_AND_BIT_STRING
#undef XNOUSE_AND_BIT_STRING
#endif

One section of the sct_mcf.h file, is dedicated for the manual edits. This section is marked with the text:

/* BEGIN User Code */
/* END User Code */

The manual edits must be inserted between these to lines otherwise they will be deleted, as the sct_mcf.h file is re-generated each time you generate code. The information about the unused operators available in the sdl_cfg.h file is imported to the sct_mcf.h file. This allows you to quickly see which operators that are unused.

SDL Predefined Types

Mapping Table

Below is a table which summarizes the mapping rules between SDL and C, concerning the predefined types in SDL and their operators. Note that many of the operators are in C defined as macros, and expanded by the C preprocessor to simple operators in C.

SDL name/operator
C name/expression/operator

 Boolean

 SDL_Boolean

 False, True

 SDL_False, SDL_True

 not

 xNot_SDL_Boolean

 and

 xAnd_SDL_Boolean

 or

 xOr_SDL_Boolean

 xor

 xXor_SDL_Boolean

 =>

 xImpl_SDL_Boolean

 =, /=

 yEqF_SDL_Boolean,
yNEqF_SDL_Boolean

 Character

 SDL_Character

 NUL
 SOH
...

 SDL_NUL
 SDL_SOH
... (for all unprintable characters)

 'a'
 'b'
...
 'a'
 'b'
... (for all printable characters except ' and \)

 '''', '\'

 '\'',  '\\'

 chr

 xChr_SDL_Character

 num

 xNum_SDL_Character

 <, <=, >, >=

 xLT_SDL_Character,
xLE_SDL_Character,
xGT_SDL_Character,
xGE_SDL_Character

 =, /=

 xEqF_SDL_Character,
xNEqF_SDL_Character

 Charstring

 SDL_Charstring

 'aa'

 SDL_CHARSTRING_LIT("Laa","aa")

 mkstring

 xMkString_SDL_Charstring

 length

 xLength_SDL_Charstring

 first

 xFirst_SDL_Charstring

 last

 xLast_SDL_Charstring

 //

 xConcat_SDL_Charstring

 substring

 xSubString_SDL_Charstring

 =, /=

 yEqF_SDL_Charstring,
yNEqF_SDL_Charstring

 Integer

 SDL_Integer
0, 1 etc.
SDL_INTEGER_LIT(0),
SDL_INTEGER_LIT(1) etc.

 +

 xPlus_SDL_Integer
- (monodic, dyadic)

 xMonMinus_SDL_Integer,
xMinus_SDL_Integer

 *

 xMult_SDL_Integer

 /

 xDiv_SDL_Integer

 mod

 xMod_SDL_Integer

 rem

 xRem_SDL_Integer

 float

 xFloat_SDL_Integer

 fix

 xFix_SDL_Integer

 <, <=, >, >=

 xLT_SDL_Integer,
xLE_SDL_Integer,
xGT_SDL_Integer, xGE_SDL_Integer

 =, /=

 yEqF_SDL_Integer,
yNEqF_SDL_Integer

 Natural

 SDL_Natural

 Real

 SDL_Real

 12.45, ...

 SDL_REAL_LIT(12.45, 12,
450000000)
- (monodic, dyadic)

 xMonMinus_SDL_Real,
xMinus_SDL_Real

 +

 xPlus_SDL_Real

 *

 xMult_SDL_Real

 /

 xDiv_SDL_Real

 <, <=, >, >=

 xLT_SDL_Real, xLE_SDL_Real,
xGT_SDL_Real, xGE_SDL_Real

 =, /=

 yEqF_SDL_Real, yNEqF_SDL_Real

 Pid

 SDL_PId

 Null

 SDL_NULL

 =, /=

 yEqF_SDL_PId, yNEqF_SDL_PId

 Duration

 SDL_Duration

 23.45

 SDL_DURATION_LIT(23.45, 23,
450000000)

 +

 xPlus_SDL_Duration
- (monodic)

 xMonMinus_SDL_Duration
- (dyadic)

 xMinus_SDL_Duration

 * (Duration * Real)
 * (Real * Duration)

 xMult_SDL_Duration,
xMultRD_SDL_Duration

 /

 xDiv_SDL_Duration

 <, <=, >, >=

 xLT_SDL_Duration,
xLE_SDL_Duration,
xGT_SDL_Duration,
xGE_SDL_Duration

 =, /=

 yEqF_SDL_Duration,
 yNEqF_SDL_Duration

 Time

 SDL_Time

 23.45

 SDL_TIME_LIT(23.45, 23,
450000000)

 + (Time + Duration)
 + (Duration + Time)

 xPlus_SDL_Time,
 xPlusDT_SDL_Time
- (result: Time)

 xMinusT_SDL_Time
- (result: Duration)

 xMinusD_SDL_Time

 <, <=, >, >=

 xLT_SDL_Time, xLE_SDL_Time,
 xGT_SDL_Time, xGE_SDL_Time

 =, /=

 yEqF_SDL_Time,
 yNEqF_SDL_Time

 IA5String

 SDL_IA5String

 NumericString

 SDL_NumericString

 VisibleString

 SDL_VisibleString

 PrintableString

 SDL_PrintableString

 Bit

 SDL_Bit

 not

 xNot_SDL_Bit

 and

 xAnd_SDL_Bit

 or

 xOr_SDL_Bit

 xor

 xXor_SDL_Bit

 =>

 xImpl_SDL_Bit

 =, /=

 yEq_SDL_Bit, yNEq_SDL_Bit

 Bit_string

 SDL_Bit_String

 not

 xNot_SDL_Bit_String

 and

 xAnd_SDL_Bit_String

 or

 xOr_SDL_Bit_String

 xor

 xXor_SDL_Bit_String

 =>

 xImpl_SDL_Bit_String

 mkstring

 xMkString_SDL_Bit_String

 length

 xLength_SDL_Bit_String

 first

 xFirst_SDL_Bit_String

 last

 xLast_SDL_Bit_String

 //

 xConcat_SDL_Bit_String

 substring

 xSubString_SDL_Bit_String

 bitstr

 xBitStr_SDL_Bit_String

 hexstr

 xHexStr_SDL_Bit_String

 =, /=

 yEq_SDL_Bit_String,
yNEq_SDL_Bit_String

 Octet

 SDL_Octet

 not

 xNot_SDL_Octet

 and

 xAnd_SDL_Octet

 or

 xOr_SDL_Octet

 xor

 xXor_SDL_Octet

 =>

 xImpl_SDL_Octet

 shiftl

 xShiftL_SDL_Octet

 shiftr

 xShiftR_SDL_Octet

 +

 xPlus_SDL_Octet

 -

 xMinus_SDL_Octet

 *

 xMult_SDL_Octet

 i2o

 xI2O_SDL_Octet

 o2i

 xO2I_SDL_Octet

 /

 xDiv_SDL_Octet

 mod

 xMod_SDL_Octet

 rem

 xRem_SDL_Octet

 bitstr

 xBitStr_SDL_Octet

 hexstr

 xHexStr_SDL_Octet

 <, <=, >, >=

 yLT_SDL_Octet, yLE_SDL_Octet,
yGT_SDL_Octet, yGE_SDL_Octet

 =, /=

 yEq_SDL_Octet, yNEq_SDL_Octet

 Octet_string

 SDL_Octet_String

 mkstring

 xMkString_SDL_Octet_String

 length

 xLength_SDL_Octet_String

 first

 xFirst_SDL_Octet_String

 last

 xLast_SDL_Octet_String

 //

 xConcat_SDL_Octet_String

 substring

 xSubString_SDL_Octet_String

 bitstr

 xBitStr_SDL_Octet_String

 hexstr

 xHexStr_SDL_Octet_String

 bit_string

 xBit_String_SDL_Octet_String

 hex_string

 xHex_String_SDL_Octet_String

 =, /=

 yEq_SDL_Octet_String,
yNEq_SDL_Octet_String

 Object_identifier

 SDL_Object_Identifier

 mkstring

 xMkString_SDL_Object_Identifier

 length

 xLength_SDL_Object_Identifier

 first

 xFirst_SDL_Object_Identifier

 last

 xLast_SDL_Object_Identifier

 //

 xConcat_SDL_Object_Identifier

 substring

 xSubString_SDL_Object_Identifier

 =, /=

 yEq_SDL_Object_Identifier,
yNEq_SDL_Object_Identifier

 NULL (sort)

 SDL_Null

 NULL (literal)

 SDL_NullValue

 =, /=

 yEq_SDL_Null, yNEq_SDL_Null

C Definitions

We will here discuss the types and macros supplied by the runtime library in the Cadvanced/Cbasic SDL to C Compiler for the predefined types in SDL. These macros and extern definitions for functions can be found in the file sctpred.h, except for the Pid sort which is handled in the file scttypes.h.

Note:

For more information about the Charstring sort, see the section "Handling of the Charstring Sort" .

Translation of Sorts

The following data types are handled by the Cadvanced/Cbasic SDL to C Compiler:

  • Predefined Types
  • Enumeration Type
  • Struct
  • Choice
  • Array
  • String
  • Powerset
  • Bag
  • Ref, Own, Oref
  • Syntypes
  • Inheritance

Predefined Types

All the predefined data types (Integer, Natural, Boolean, Character, Charstring, Real, Time, Duration, Pid, Bit, Bit_string, Octet, Octet_string, Object_identifier, IA5String, NumericString, PrintableString, and VisibleString) are completely handled. The name of these types in the generated C code will be SDL_Integer, SDL_Natural, SDL_Boolean, and so on. The translation rules for these types and their operators are discussed in more detail in the "SDL Predefined Types" .

Enumeration Type

A sort which is not a struct and does not contain any inheritance or generator instantiation, but which contains a literal list, is seen as an enumeration type. See the example below. Such a type is translated to int, together with a list of defines where the literals are defined as 0, 1, 2, and so on. As in all examples in this sub-section, the prefixes, which are added to names when they are translated to C, are not shown. The prefixes are added to make sure that no name conflicts occur in the generated program. For more information about prefixes see "Names and Prefixes in Generated Code" .

Example 345 : Enumeration Type

NEWTYPE EnumType
LITERALS Lit1, Lit2, Lit3;
ENDNEWTYPE;

is translated to:

typedef XENUM_TYPE EnumType;
#define Lit1 0
#define Lit2 1
#define Lit3 2

Where the macro XENUM_TYPE is defined in sctpred.c as:

#ifndef XENUM_TYPE
#define XENUM_TYPE int
#endif

This means that all enum types will be int types, except if the macro XENUM_TYPE is redefined by the user (to unsigned char for example). An enum type with 256 or more values will always be of type int and will not be affected by the macro XENUM_TYPE.

Struct

An SDL struct is translated to a struct in C, as can be seen in the example below.

Example 346 : Struct

NEWTYPE Str STRUCT
a Integer;
b Boolean;
c Real;
ENDNEWTYPE;

is translated to:

typedef struct {
SDL_Integer a;
SDL_Boolean b;
SDL_Real c;
} Str;

All the properties of a struct in SDL are preserved in the C code.

The predefined operators extract! and modify! are implemented as component selections in the struct in the same way as in SDL, that is, if S is a variable of type Str, then S!a in SDL is translated to S.a in C.

The predefined operator make!, which is a constructor of a struct value, is implemented by generating a Make function in C. This means that the expression "(. 12, true, 0.22 .)" in SDL is in principle translated to the C function call Make(12, true, 0.22).

The components of a struct may be of any sort that the code generator can handle. A component may, however, not directly or indirectly refer to the struct sort itself. As an example the sort Str above may not have a component of sort Str. In such a case the translation to a C struct would not any longer be valid.

There are some extensions to SDL that are handled by the code generator. It is possible to define bit fields, i.e, to define the size of components (as in C) and to have optional components and components with initial values (as in ASN.1). Examples are shown below.

Example 347 : Struct with bit fields

NEWTYPE str STRUCT
a Integer : 4;
b Integer : 4;
: 0;
c UnsignedInt : 2;
d Integer;
ENDNEWTYPE;

is translated to:

typedef struct str_s {
SDL_Integer a : 4;
SDL_Integer b : 4;
int : 0;
UnsignedInt c : 2;
SDL_Integer d;
} str;

Note that only Integer and UnsignedInt should be used in bit field components.

Example 348 : Struct

NEWTYPE str STRUCT
a, b integer;
c Boolean OPTIONAL;
d str2 OPTIONAL;
e Charstring := 'telelogic';
f arr3 := (. 11 .);
ENDNEWTYPE;

is translated to:

typedef struct str_s {
SDL_Integer a;
SDL_Integer b;
SDL_Boolean c;
SDL_Boolean cPresent;
str2 d;
SDL_Boolean dPresent;
SDL_Charstring e;
SDL_Boolean ePresent;
arr3 f;
SDL_Boolean fPresent;
} str;

Both optional components and components with initial values have a Present flag. This is according to ASN.1 and the translation of ASN.1 to SDL defined in Z.105. The present flag for a component with initial value is true if the component contains its default value otherwise false (the Present flag is used to determine code for some ASN.1 encoding scheme). The present flag for an optional component is false until the component is assigned a value. In SDL the present flags can only be accessed through operators and cannot be changed.

Union

Please see also the CHOICE concept presented below, as it usually provides a better and more secure solution to the same kind of problems.

Using the directive #UNION (see example below) it is possible to tell the Cadvanced/Cbasic SDL to C Compiler to generate a union according to the following example:

Example 349 : Union

NEWTYPE Str /*#UNION*/ STRUCT
tag integer;
a integer;
b Boolean;
c real;
ENDNEWTYPE;

is translated to:

typedef struct {
SDL_Integer tag;
union {
SDL_Integer a;
SDL_Boolean b;
SDL_Real c;
} U;
} Str;

The first component in the struct is assumed to be a tag value indicating which of the union components that are active. The tag should either be integer or an enumeration type. Tag value 0 or first enumeration literal is used to indicate that the first of the remaining components are active, and so on. On the SDL level a #UNION struct should be handled just like any other struct. It is up to the code generator to generate the correct code for operations on the struct, like assignment, test for equality, component selection, and so on.

Note:

It is completely up to the user to make certain that only valid components in a #UNION struct are accessed. During simulation, however, tests are inserted to ensure that only valid components are accessed.

UnionC

By using the directive #UNIONC according to the example below, it is possible to tell the Cadvanced/Cbasic SDL to C Compiler to generate a true C union.

Example 350 : UnionC

NEWTYPE Str /*#UNIONC*/ STRUCT
a integer;
b Boolean;
c real;
ENDNEWTYPE;

is translated to:

typedef union {
SDL_Integer a;
SDL_Boolean b;
SDL_Real c;
} Str;

.

Note:

The #UNIONC directive is not recommended for use as the Cadvanced/Cbasic SDL to C Compiler cannot give any support for checking the validity of component selection. Both the #UNION directive and the CHOICE concept discussed below are much better.

Note also that pointer types, including Charstrings are not allowed in #UNIONC structs, as it is not possible to know when to allocate and de-allocate memory for such components.

Choice

Choice, which is an SDL extension originating from the needs when translating ASN.1 to SDL and which is included in SDL-2000, can be used to express a union with implicit tag.

Example 351 : Choice

NEWTYPE Str CHOICE
a integer;
b Boolean;
c real;
ENDNEWTYPE;

is translated to:

typedef enum {a, b, c} StrPresent;
typedef struct {
StrPresent Present;
union {
SDL_Integer a;
SDL_Boolean b;
SDL_Real c;
} U;
} Str;

The component Present, which is the tag field, and its type (StrPresent in the example above) are both available in SDL. The Present component can in SDL be accessed, but not changed, through:

  • component selection, i.e. by Variable!Present, i.e. it is possible to for example test: V!Present = a
  • the operators aPresent, bPresent, or cPresent, which returns true or false depending on if the component is active or not.

The Present component is automatically set by the code generator when a component in the choice is given a value.

Note that during simulations and validations, it is automatically tested that a component "is present" when an attempt is made to access the component. A run-time error is issued if this is not the case.

Array

Instantiations of the predefined generator array can be handled by the code generator with the following restriction: The component and index sort may be any sorts that the code generator can handle, but may not directly or indirectly refer to the array type itself (see also the previous paragraph on struct).

If the index sort is a discrete sort, with one closed interval of values, that is of the following sorts:

  • Character
  • Boolean
  • Octet
  • Bit
  • A sort that is considered as an enumeration type
  • Syntypes of integer, character, Boolean, Octet, Bit, and enumeration types. The subtypes may only have one range condition that specifies a closed interval of values,

then the SDL array is translated to a struct containing an element which is an array in C.

If the index sort is not one of the sort in the enumeration above, the SDL array is translated to a linked list. The list head contains the default value for all possible indexes, while the list elements contain value pairs, (index_value, component_value), for each index having a component value not equal to the default value.

Example 352 : Array

SYNTYPE Syn = integer
CONSTANTS 0:10
ENDSYNTYPE;

NEWTYPE Arr ARRAY(Syn, real)
ENDNEWTYPE;

is translated to:

typedef SDL_Integer Syn;
typedef struct {
SDL_Real A[11];
} Arr;

All the properties of an array in SDL are preserved in the C code.

The predefined operators extract! and modify! are implemented as component selection of the array in C in the same way as in SDL, so if AVar is a variable of type Arr, and Index is a valid index expression, then AVar(Index) in SDL is translated to AVar.A[Index] in C. In the case of a link list implementation of the array, component selection is made through function calls.

The predefined operator make!, which is a constructor of an array value, is implemented by generic Make function in C.

String

Instantiations of the predefined generator string can be handled by the code generator with the following restriction: The component sort may be any sorts that the code generator can handle, but may not directly or indirectly refer to the string type itself.

There are two translation schemes for Strings. The directive #STRING decide whether the string should be translated to linked list or to an array. For the #STRING directive please see "Alternative Implementations of the String Generator - Directive #STRING" .

Strings are translated to linked list containing one element for each element in the string value. Operations and component selection in string sorts are fully supported.

Powerset

Instantiations of the predefined generator powerset can be handled by the code generator with the following restriction: The component sort may be any sorts that the code generator can handle, but may not directly or indirectly refer to the powerset type itself.

There are two translation schemes for powersets. If the component sort fulfills the conditions for index sorts mentioned in the subsection about arrays above ("Array" ), an array of 32-bit integers are used. Each bit will be used to represent a certain element whether it is a member of the powerset or not. If this is not the case, a linked list of all elements that are member of the set, is used to represent the powerset. All the available operations defined for Powersets in SDL are supported.

Bag

The Bag generator, which is introduced in SDL in Z.105, i.e. in the mapping from ASN.1 to SDL, is similar to powerset. However, it is possible to have several elements with the same value in a bag. A bag is always translated into a linked list, with one element for each value that is a member of the bag. Each element contains the value and the number of occurrences of this value.

Ref, Own, Oref

These generators represent pointers with different properties. They are all translated to pointers in C.

Syntypes

Syntypes may be defined for any sort that the code generator can handle, giving a new name for the sort and possibly a new default value for variables of the sort. Range conditions that restrict the allowed range of values are also allowed.

A syntype is translated to a type equal to the parent type using typedef. The check that a variable of a syntype is only assigned legal values is implemented in a test function that is generated together with the type definition. An attempt to assign an illegal value to such a variable will be reported as an SDL dynamic error. If the syntype is can be used as index sort in an array and the generated type in C would become an array, there will also be a test function that can be used to check that an index value is within its range in an array component selection.

Example 353 : Syntypes

SYNTYPE Syn = integer
CONSTANTS 0:10
ENDSYNTYPE;

SYNTYPE Syn2 = integer
CONSTANTS <0, =2, >=10
ENDSYNTYPE;

SYNTYPE Arr1 = Arr
DEFAULT (. 2.0 .);
ENDSYNTYPE;
/* Arr defined above */

is translated to:

typedef SDL_Integer Syn;
typedef SDL_Integer Syn2;
typedef Arr Arr1;

Inheritance

A type that inherits another type is translated to a type equal to the parent type using a typedef.

Default Values

Default values are fully supported for all sorts that the code generator can handle, both if a default value is given in a sort definition and if an initial value is given in a variable definition (DCL).

Default values will also be assigned to all variables and components which do not have a default value specified in SDL. The reason for this is to avoid handling undefined variables in C, which might give serious problems and unexpected behavior of an executing program. The values selected by the code generator in such a case can be found below.

Note:

This is a deviation from SDL-92. It means that the generated program does not handle the value undefined for any type.

If no default value is given in the sort and no start value is given in the data definition (DCL) for a variable, the variable will be set to 0 by using a memset to 0.

Operators

In SDL-92, it is possible to define the behavior of operators in ADTs directly in SDL, using operator diagrams or operator implementations in SDL textual form. Such operators are translated to C by the Cadvanced/Cbasic SDL to C Compiler, and none of what is said below is valid for such an operator. It is also possible to specify that an operator is external. In this case the code generator assumes that a C function with the name used in SDL exists and translates calls to the external operator directly to calls to the C function.

A user defined operator in an SDL sort definition, which is not defined by an operator diagram, is translated to a C function which asks the user for the result of the operation. At a call of an operator, the user is supplied with information describing what the operator and the sort are called, and given information about the parameter values. You are then requested to answer with the result value. If you press <Return> at the prompt for the result, the default value of the actual result type is returned. If the operator does not have a result type, no question is asked.

Example 354 : Operator

Operator Op in sort S is called.
Parameter 1: true
Parameter 2: 10
Enter value (integer) : 12

assuming that newtype S contains an operator

Op: Boolean, Integer -> Integer;

More about operator implementation, both parameter passing and how to include implementations written in C can be found in the next two sections.

Literals

In sorts that are translated to enumeration types in C, literals are obviously handled by the code generator. In sorts that are not enumeration types, literals are treated as operators without parameters and are handled in exactly the same way as user defined operators.

Note:

The Cadvanced/Cbasic SDL to C Compiler does not permit naming of literals using name class literals or character strings.

Axioms and Literal Mappings

Axioms and literal mapping are allowed by the code generator in sorts, but are completely ignored.

Parameter Passing to Operators

For performance reasons the data types in SDL have been divide in two groups, simple, small types that are passed as values and structured, larger types that are passed as references (addresses).

Types passed as addresses (structured types)
Bit_string
Octet_string
Object_identifier
Struct types (including #UNION, #UNIONC)
Choice types
Instantiations of generator Powerset
Instantiations of generator Bag
Instantiations of generator Array
Instantiations of generator String
Instantiations of generator Carray
Syntypes of a type in this list
Types that inherit a type in this list

Table 1 : Types Passed as Addresses

Types passed as values (simple types)
Integer
Real
Natural
Boolean
Character
Time
Duration
PId
Charstring
Bit
Octet
IA5String
NumericString
PrintableString
VisibleString
NULL
Enumeration types
Instantiations of generator Ref, Own, ORef
Syntypes of a type in this list
Types that inherit a type in this list

Table 2 : Types Passed as Values

Note:

For types represented as pointers (Charstring, including its syntypes, Ref, Own, ORef), the pointers, not the addresses of the pointers, are passed as parameters.

The parameter passing for operators implemented in C works as follows (for Cmicro the mechanism described below is also used for operator diagrams and procedures):

In parameters:

  • Passed as a value in C if the type is in the list "Passed as value". This means that the parameter type in C is the same type as in SDL.
  • Passed as an address in C if the type is in the list "Passed as address". This means that the C parameter is (SDL_type *) if the type in SDL is SDL_type.

In/Out parameters:

Parameters are always passed as addresses, i.e the C parameter is (SDL_type *) if the type in SDL is SDL_type.

Operator result:

  • If the result type is in the list "Passed as value", the C function result type will be the same as in SDL.
  • If the result type is in the list "Passed as address", two things are changed. Firstly, the C result type will be (SDL_type *), i.e the result will be an address. Secondly, an extra parameter is inserted last in the C function. This parameter is also of type (SDL_type *) and is used as a location to store the result of the function. At an operator call, a "dummy" variable should be passed as the actual parameter. The C function can then use this to store the result of the operator and should return the variable again as result.

Example 355 :

Assume that struct1 is a newtype struct in SDL.

operators
X : integer, in/out integer -> integer;
Y : struct1, in/out struct1 -> struct1;

The C prototypes for these operators are:

SDL_Integer X (SDL_Integer, SDL_Integer *);
struct1 * Y (struct1 *, struct1 *, struct1 *);

The example implementations are:

SDL_Integer X
(SDL_Integer Param1, SDL_Integer *Param2)
{
*Param2 = *Param2+Param1;
return *Param2;
}

struct1 * Y (struct1 *Param1,
struct1 *Param2,
struct1 *Result)
{
/* implementation assuming struct1 to contain
two integers */
(*Param2).comp1 = (*Param2).comp1+(*Param1).comp1;
(*Param2).comp2 = (*Param2).comp2+(*Param1).comp2;
*Result = *Param2;
return Result;
/* always return the last, extra, parameter */
}

Note: VERY IMPORTANT

As IN parameters are passed as addresses for structured types, changing such a parameter inside the operator might have undesired effects. A variable passed as actual parameter is then also changed. If you want to change the formal parameter copy it first to a operator local variable.
For Cadvanced/Cbasic this rule applies to operators implemented in C. For Cmicro this rule also applies to operators and procedures defined in SDL.

Implementation of User Defined Operators

Including Implementations of Operators

In a previous subsection, the default behavior of the Cadvanced/Cbasic SDL to C Compiler concerning operators (not defined in operator diagrams) and literals were described. If you do not specify otherwise interactive functions are generated, which, in each case, will ask you for the operator result or literal value. This is a fast way of getting started, but you will probably find it tedious in the long run, especially if you are using abstract data types extensively. To cope with this problem and to make it possible to generate applications, the code generator offers a possibility to include implementations written in C of the operator and literal functions. This possibility can be used as an alternative to operator diagrams or operators defined using SDL textual form, where the operator is defined directly in SDL.

When the choice between an implementation in SDL or in C is to be made there are a few things to consider:

    • There is always problems when mixing languages, for example how are C names for SDL entities constructed.
    • Checking of SDL is performed by the SDL Analyzer, which will find problems much earlier than the C compiler checking C code. Also pointing to the error will be more accurate in SDL.
    • SDL implementations will be more portable and might benefit from future improvements in the SDL Compiler.
    • The risk for backward compatibility problems in future releases of the SDL suite will be less for an SDL implementation.
    • However, a C implementation might be more efficient or you might already have a corresponding C function.

So it is not obvious if SDL or C implementations should be used. However, we recommend SDL if there are no specific reasons for using C. Note also that the SDL extension described in "Grammar for the Algorithmic Extensions could be very useful when writing implementations in SDL.

It is possible to choose between two alternatives to implement operators and literal functions:

  • Q (question)
    This is the default value and specifies that the code generator should generate the interactive routines describe above.
  • B (body)
    This specifies that the code generator should generate the heading of the operator and literal functions, while the user must supply the bodies of the functions.

Note:

The C functions are divided into a function heading (extern or static declaration) and a function body.

An example of a function heading (extern declaration) is:

Example 356 : Implementing an Operator

extern SDL_Integer Max
(SDL_Integer Para1,
SDL_Integer Para2);

while the corresponding function body is:

SDL_Integer Max
(SDL_Integer Para1,
SDL_Integer Para2)
{
if (Para1 > Para2)
return Para1;
return Para2;
}

The main reason for this division of functions into heading and body is the separate compilation scheme used in C. If, for example, an abstract data type is defined in a system and used in a process in the system, and the process is generated on a separate file, then there has to be a module interface file (a .h file) for the system containing the external interface (types, extern declarations of functions and so on). The interface file should then be included in the file generated for the process.

Even if separate compilation is not used, the division of functions into heading and body is useful. By having static declarations of the functions, the order in which functions must be defined is relaxed. If static declarations were not used, a function could only call the functions that are defined textually before the actual function.

To select the way the Cadvanced/Cbasic SDL to C Compiler should generate code for operators and literals, code generator directives are used. A code generator directive is an SDL comment with the first characters equal to `#', followed by a sequence of letters identifying the directive. In this case the letters are ADT (for Abstract Data Type) and OP (for operator). An ADT directive and a OP directive should thus look like:

/*#ADT */ /*#OP */

The text is not case sensitive.

OP directives are recognized at two different positions in an abstract data type:

  • Directly after the name of a literal
  • Directly after the semicolon ending the definition of an operator.

ADT directives are recognized immediately before the reserved word ENDNEWTYPE (or ENDSYNTYPE).

Example 357 : Implementing an Operator (#ADT)

NEWTYPE Str STRUCT
a integer;
b Boolean;
c real;
ADDING
LITERALS
Lit1 /*#OP */,
Lit2 /*#OP */;
OPERATORS
Op1 :Str,integer -> Str; /*#OP */
Op2 :Str,Boolean -> Str; /*#OP */
/*#ADT */
ENDNEWTYPE;

At each of the positions after a literal name or operator definition, there is a possibility to specify how this literal or operator should be implemented. In the directive immediately before ENDNEWTYPE the default implementation technique can be given. When the code generator determines how to generate code for a literal or an operator, it first looks for an OP directive after the literal name or operator definition. If no such directive is found it looks for a directive immediately before ENDNEWTYPE. If no ADT directive is found here, the generation technique Q (question) is assumed. For Cmicro, Q is not used, so the default is B.

An OP or ADT directive specifying a generation technique should have the following structure:

/*#OP (B) */ /*#ADT (B) */

The letter between the parentheses should be either Q (question) or B (body). The interpretation of Q and B was explained earlier. If B has been specified for any operators or literals, then the C code for these functions must be supplied by the user. This code should be placed in the #BODY section in the ADT directive, according to the following example:

Example 358 : Implementing an Operator (#ADT)

/*#ADT (B)
#BODY
C code, representing bodies of functions
*/

The section name, i.e #BODY, must be given on a line of its own and must have the # character in the first position of the line. Upper case and lower case letters are as usual considered to be equal. If the section is empty, the section name can also be removed.

Note:

The Cadvanced/Cbasic SDL to C Compiler will not check the consistency between the specification of implementation techniques and the actual code included in the body section. This check is, together with checking the C code for syntactic and semantic errors, left to the C compiler.

Unfortunately it is not possible to have C comments within the code that is included in a #ADT directive, as SDL and C use the same symbols for start and end of comments. If a C comment is included, the SDL Analyzer will consider the end of the C comment as the end of the SDL comment. Instead a C macro called COMMENT can be used according to the examples below. Note that there might be some compiler dependent restriction of the character set allowed within the COMMENT macro. For example, the character `;' might not be allowed.

Example 359 : Comment in ADT

COMMENT(This is a comment)
COMMENT(These comments may not contain commas \
and should have a backslash at each \
line break)
COMMENT((By having double parenthesis, any text
can be entered into the comments. Some
compilers might not allow everything.))

The function headings representing literals and operators are determined by their corresponding definition in SDL. The number of parameters, their types, the result type of the function and function name are all defined in SDL. In the example above, where the struct Str is defined, there are two literals (Lit1 and Lit2) and two operators
(Op1: Str, integer -> Str; and Op2: Str, Boolean -> Str;). The type Str will be passed as an address, so the parameter passing rules described previously have to be applied. The function heading of the corresponding C functions should be:

Example 360 : Implementing an Operator

extern Str* Lit1 (Str*);
extern Str* Lit2 (Str*);
extern Str* Op1 (Str*, SDL_Integer, Str*);
extern Str* Op2 (Str*, SDL_Boolean, Str*);

The function bodies, which should be supplied by the user if B is specified in the OP or ADT directive, are ordinary C functions.

Example 361 : Implementing an Operator

Str* Lit1 (Str* Result)
{
Result->a = 2;
Result->b = false;
Result->c = 10.0;
return Result;
}

Str* Op1 (Str* P1, SDL_Integer P2, Str* Result),
{
*Result = *P1;
Result->a = P1->a + P2;
return Result;
}

Before it is possible to give a complete example of an abstract data type with implementation of its operators supplied as C functions, it is necessary to look at the problem of names. When a name of some object in SDL is translated to C, a suitable sequence of characters, a prefix, is added to the SDL name, to make the name unique in the C program, see also "Names and Prefixes in Generated Code" . This strategy is selected in the Cadvanced/Cbasic SDL to C Compiler to avoid name conflicts in the generated code, but it makes it also impossible to predict the full name of, for example, a type or a function, in the generated program. To handle this problem the user can tell the code generator to translate a name in the C code in the same way as SDL names are otherwise translated. This is specified by enclosing the SDL name between `#(' and `)' in the C code. The two functions in the previous example and their headings would then become:

Example 362 : Including SDL name in C Code

extern #(Str)* #(Lit1) (#(Str)*);
extern #(Str)* #(Op1) (#(Str)*, SDL_Integer,
#(Str)*);

#(Str)* #(Lit1) (#(Str)* Result)
{
Result->a = 2;
Result->b = false;
Result->c = 10.0;
return Result;
}

#(Str)* Op1 (#(Str)* P1, SDL_Integer P2,
#(Str)* Result),
{
*Result = *P1;
Result->a = P1->a + P2;
return Result;
}

This facility to access an SDL name in C code is described in more detail in the section "Accessing SDL Names in C Code - Directive #SDL" . A few observations concerning the example above might be appropriate:

  1. The predefined sorts in SDL, that is for example integer, natural, Boolean have the names SDL_Integer, SDL_Natural, SDL_Boolean, and so on in the generated code. These types should not be enclosed between `#(' and `)'.
  2. The component names of a struct are unchanged in the struct implementation in C, which means that struct components should not be enclosed between `#(' and `)' either.

Two Examples of ADTs

We now give two complete examples of abstract data types.

Example 363 : ADT Example

NEWTYPE Str STRUCT
a Integer;
b Boolean;
c Real;
ADDING LITERALS
Lit1;
OPERATORS
Op1 : Str, Integer -> Str;
Op2 : Str, Boolean -> Str;
/*#ADT (B)
#BODY
#(Str)* #(Lit1) (#(Str)* Result)
{
Result->a = 2;
Result->b = SDL_False;
Result->c = 10.0;
return Result;
}

#(Str)* #(Op1) (#(Str)* P1, SDL_Integer P2,
#(Str)* Result)
{
*Result = *P1;
Result->a = P1->a + P2;
return Result;
}

#(Str)* #(Op2) (#(Str)* P1, SDL_Boolean P2,
#(Str)* Result)
{
if (P2)
*Result = *P1;
else
(void)#(Lit1)(Result);
return Result;
}
*/
ENDNEWTYPE;

The example above should be compared with the same example written in SDL. Note that the literal in the previous example is replaced with an operator without parameters. The algorithmic extensions described in "Grammar for the Algorithmic Extensions is also used as they provide a powerful way to write textual algorithms.

Example 364 : ADT Example in pure SDL

NEWTYPE Str STRUCT
a Integer;
b Boolean;
c Real;
OPERATORS
Lit1 : -> Str;
Op1 : Str, Integer -> Str;
Op2 : Str, Boolean -> Str;
OPERATOR Lit1 RETURNS Str
{
RETURN (. 2, false, 10.0 .);
}
OPERATOR Op1 FPAR P1 Str, P2 Integer RETURNS Str
{
DCL Result Str;
Result := P1;
Result!a := P1!a + P2;
RETURN Result;
}
OPERATOR Op2 FPAR P1 Str, P2 Boolean RETURNS Str
{
IF (P2)
RETURN P1;
RETURN Lit1;
}
ENDNEWTYPE;

Example 365 : ADT Example

SYNTYPE Index = Integer CONSTANTS 1:10
ENDSYNTYPE,

NEWTYPE A Array(Index, Integer)
ADDING LITERALS
Zero /*#OP (B) */;
OPERATORS
Add : A, A -> A; /*#OP (B) */
Sum : A -> Integer;
/*#ADT()
#BODY
#(A)* #(Zero) (#(A)* Result)
{
SDL_Integer i = 0;
GenericMakeArray(Result,
(tSDLTypeInfo *)&ySDL_#(A), &i);
return Result;
}

#(A)* #(Add) (#(A)* P1, #(A)* P2, #(A)* Result)
{
int I;
for (I = 1; I<=10; I++)
Result->A[I] = P1->A[I] + P2->A[I];
return Result;
}
*/
ENDNEWTYPE;

Note that no body is supplied for the operator Sum as the default implementation strategy for operators, which should be used for Sum, is Q (question). The GenericMakeArray function used to implement the literal is a generic function that constructs array values. The details for this function will be described later in this section.

For more information about the functions and types (supplied by the runtime library in the Cadvanced/Cbasic SDL to C Compiler and contained in generated code) that can be useful when implementing operators in C, see "SDL Predefined Types" , and last in "More about Abstract Data Types" .

Error Situations in Operators

In the C function used to implement operators (and literals) it is possible to define error situations and handle them as ordinary SDL run-time errors. The C library function xSDLOpError, with the following prototype:

extern void xSDLOpError(
char *OpName,
char *ErrText )

can be used for this purpose.

Example 366 : Error Handler in Operator

Example of use:

if ( strlen(C) <= 1 ) {
#ifdef XECSOP
xSDLOpError("First in sort Charstring",
"Charstring length is zero." );
#endif
return SDL_NUL;
} else
return C[1];

This is a simplified version of the test in the function for the operator First in the sort Charstring. Here the error situation is when we try to access the first character in a charstring of length 0. In this case the xSDLOpError is called and a default value is returned (NUL). By including the xSDLOpError call between #ifdef XECSOP - #endif the function is only called to report the error if error checks are turned on. The first parameter to xSDLOpError should identify the operator and the sort, while the second parameter should describe the error.

Handling of the Charstring Sort

The SDL sort Charstring is implemented as char * in C.

Note:

This means that the value NUL (ASCII character 0) cannot be part of a Charstring, as this value is used as string terminator in C (this is checked by the library functions for Charstring).

The code generator and the library functions for the Charstring operators use the first character (index 0) in the C string to indicate the status of the string. If the first character is:

  • 'V'
    the string is assigned to an SDL variable and may not be changed in any way.
  • 'L'
    the string is a C char * literal, and may of course not be changed.
  • 'T'
    the string is a temporary result from a function returning a Charstring. This memory should either be assigned to an SDL variable or returned to the pool of free memory.

All the library functions for Charstrings handle memory in an appropriate way. A user only has to take the extra character in to account, when Charstrings are handled in C. Any Charstring function parameters having a `T' as first character must be handled according to the discussion above. A function that returns a Charstring and that creates new temporary memory to store the result, should assign the value `T' to the first character in the Charstring.

As pointers and dynamic memory are used to implement Charstrings, it is necessary to be careful when Charstrings are handled in C code, which we show in two examples.

Example 367 : Equal Test on Charstring Sort

If the C operator == is used to check if two charstrings are equal, then the actual test that is performed is to see if the two pointer values to the data areas representing the characters in the string are equal.

To check if the characters in the charstrings are equal the equal function should be used:

yEqF_SDL_Charstring

Example 368 : Assignment on Charstring Sort

If the C assignment operator, =, is used to assign the value of one charstring variable (C1) to another charstring variable (C2), then two things will go wrong:

  1. The memory used to represent the old value of C1 is lost and can never be reused.
  2. C1 and C2 now refer to the same memory area, which means that if one of the variables is changed the other will also be changed. This leads to unpredictable behavior of the program.

The correct way to handle assignment of charstrings is to use the routine:

yAssF_SDL_Charstring

The problems mentioned above can of course also occur if a struct or array containing charstring components (or subcomponents) is handled carelessly. It is, for example, necessary to use the generic equal and assign functions to perform equal test and assignment.

To avoid problems one should be aware that Charstring is implemented as char * in C and take the consequences thereof. There are a number of help functions (that implement the operators for the Charstring sort) supplied in the runtime library that might be helpful when handling Charstrings. See "SDL Predefined Types" ).

Other Types Containing Pointers

The principal discussion about Charstrings in the previous section is also relevant for all other types containing pointers. Such types are:

    • Bit_string
    • Octet_string
    • Object_identifier
    • Strings (not #STRING)
    • General Arrays
    • General Powersets
    • Bags

All these types contain a boolean component, IsAssigned, that gives the status of the data area. IsAssigned serves the same purpose as the first extra character in a Charstring and has to be treated in a similar way.

  • IsAssigned equal to false means that this data area is a temporary result from a function returning the data type. This memory should either be assigned to an SDL variable or returned to the pool of free memory.
  • IsAssigned equal to true means that this value is assigned to a variable and may not be changed in any way. It can also mean that the value is part of (i.e. is assigned to) a larger data structure.

External Properties

As an alternative to the #ADT directive, which is a comment, the external properties clause in a newtype can be used as container for this information. See the following example:

Example 369 : External Properties in a Newtype

NEWTYPE Str STRUCT
a integer;
b Boolean;
c real;
ADDING LITERALS
Lit;
OPERATORS
Op1 : Str, integer -> Str;
Op2 : Str, Boolean -> Str;

ALTERNATIVE C;
#ADT (B)
#BODY
some appropriate C code
ENDALTERNATIVE;

ENDNEWTYPE;

The #ADT directive, without the /* */ can be placed between ALTERNATIVE C; and ENDALTERNATIVE.

Note:

According to the syntax of SDL, if you have an external properties clause (i.e. alternative - endalternative), you cannot, in the same newtype, have operator diagrams, axioms, or literal mappings.

More about Operators

For an operator in an abstract data type, not only B (body) or Q (question) may be specified. The following choices are available:

  • Q (question)
    This is the default value and specifies that the code generator should generate the interactive routines describe above.
  • B (body)
    This specifies that the code generator should generate the heading of the operator or literal function, while the user should supply the body of the function.
  • H (heading)
    This specifies that the code generator should neither generate the heading nor the body of the operator or literal function. The user is assumed to supply the necessary code.
  • S (standard)
    This is used to indicate that a standard function or operator is available in the target language, which should be used as implementation of the SDL operator (literal). No function heading or function body is generated. In expressions where such an operator is used, no prefix is added to the SDL name during the translation, but the SDL name is used as it is (if no #NAME directive is present).
  • P (prefix) or
    I (infix)
    where P is the default value. These letters are used to indicate if the operator should be used as a function or an operator:
    • As an operator: a+1 a==4 -a
    • Or as a function call: sin(a) power(a, 3)

Note:

As C does not include the possibility to have user defined operators, I (infix) is only adequate together with S (standard).

For each operator one of the letters B, Q, H, S and one of the letters P, I should be supplied, either in a #OP directive, or in a #ADT directive, or as the defaults Q and P; for literals P and I have no meaning.

The purpose of S is straight forward and easy to understand, but H might require some explanation. H means that the code generator will not generate any code for the operator, which leaves the user with a number of possibilities:

  • By not including any code for an operator, the user may skip the code for an unused operator.
  • There might already exist external declarations for a number of operators in a .h file that should be used instead of the generated headings.

Example 370 : Using S (Standard Function or Operator)

Example of usage of S (standard)

"+" : integer, real -> real; /*#OP (SI) */
sin : real -> real; /*#OP (SP) */

An SDL expression using these operators:

sin(a + 7.0) will be translated to: sin(zh723_a + 7.0)

These examples show how standard functions in the target language can be directly utilized in abstract data types. In C, it is often easiest to use #OP(HP) for such special cases, and implement the operator in the #HEADING section as a C macro transforming the call to the appropriate syntax.

Generic Functions

Type Info Nodes

A generic function can perform a certain task for several different types. To be able to write generic functions, type-specific information for the types must be made available. This type of information could be, for instance, size of the type, component types for structured types and component offsets. This information is provided by the type info nodes.

A type info node is a struct that contains information that defines the type. Each type has a corresponding type info node. Each type info node contains two sections. The first section contains a sequence of general components that is identical for all type info nodes. The second section is an individual type-specific sequence of components that defines each unique type.

Every newtype or syntype introduced in SDL will be described by a type info node in the generated C code. For the predefined data types the following type info nodes can be found in sctpred.h and sctpred.c:

extern tSDLTypeInfo ySDL_SDL_Integer;
extern tSDLTypeInfo ySDL_SDL_Real;
extern tSDLTypeInfo ySDL_SDL_Natural;
extern tSDLTypeInfo ySDL_SDL_Boolean;
extern tSDLTypeInfo ySDL_SDL_Character;
extern tSDLTypeInfo ySDL_SDL_Time;
extern tSDLTypeInfo ySDL_SDL_Duration;
extern tSDLTypeInfo ySDL_SDL_PId;
extern tSDLTypeInfo ySDL_SDL_Charstring;
extern tSDLTypeInfo ySDL_SDL_Bit;
extern tSDLTypeInfo ySDL_SDL_Bit_String;
extern tSDLTypeInfo ySDL_SDL_Octet;
extern tSDLTypeInfo ySDL_SDL_Octet_String;
extern tSDLTypeInfo ySDL_SDL_IA5String;
extern tSDLTypeInfo ySDL_SDL_NumericString;
extern tSDLTypeInfo ySDL_SDL_PrintableString;
extern tSDLTypeInfo ySDL_SDL_VisibleString;
extern tSDLTypeInfo ySDL_SDL_Null;
extern tSDLGenListInfo ySDL_SDL_Object_Identifier;

For a user-defined type the type info node will have the name

ySDL_#(TypeName)

Generic Assignment Functions

Each type in SDL has access to an assignment macro yAssF_typename. Examples for type Boolean and for a user-defined type A:

#define yAssF_SDL_Boolean(V,E,A) (V = E)

#define yAssF_A(V,E,A) yAss_A(&(V),E,A)
#define yAss_A(Addr,Expr,AssName) \    (void)GenericAssignSort(Addr,Expr,AssName,
(tSDLTypeInfo *)&ySDL_A)

This macro is used in the generated code (and in the kernel) at each location where an assignment should take place. The three macro parameters are:

  • V: the variable on the left hand side
  • E: the expression on the right hand side
  • A: an integer giving the properties of the assignment

This macro will either become an assignment statement in C or a call of an assignment function. An assignment statement will be used if assignment is allowed according to C for the current type and if it has the correct semantics comparing with assignment in SDL.

If assignment is not possible to use, the assign macro will become a call to an assignment function. The basic generic assignment function can be found in sctpred.c and sctpred.h:

extern void * GenericAssignSort(void *, void *,
int, tSDLTypeInfo *);

where:

  • The first parameter is the address of the variable on the left hand side.
  • The second parameter is the address of the expression on the right hand side.
  • The third parameter is the properties of the assignment
  • The fourth parameter is the type info node for the actual type.

GenericAssignSort returns the address passed as the first parameter.

The GenericAssignSort function performs three tasks:

  1. The old value on the left hand side variable is released, if that is specified in properties of the assignment and if the value contains any pointers.
  2. The value is copied from the expression to the variable. If possible this is performed by the function memcpy, otherwise special code depending on the kind of type is executed.
  3. The IsAssigned flags are set up for the variable according to the properties of the assignment.

Special treatment of Charstring and instantiations of the Own generator has made it necessary to introduce specific wrapper functions that in their turn call GenericAssignSort for these types:

extern void xAss_SDL_Charstring (SDL_Charstring *,
SDL_Charstring, int);
extern void * GenOwn_Assign (void *, void *, int,
tSDLTypeInfo *);

An GenericAssignSort function must consider the following questions in order to handle the objects correctly.

How should one copy the object?

This is very important because performing the wrong action will lead to memory leaks or access errors. Three different possibilities exist:

  • AC: always copy the referenced object.
  • AR: always copy the pointer, i.e reusing the referenced object.
  • MR: copy pointer if the object is temporary or copy object if not temporary.

What should be the status of the new object?

This is a preparation for the next operation on this object so the correct decision can be made according to the first question. Two different possibilities exists:

  • ASS: an object should become assigned if it is assigned to a variable and needs to be copied in future assignments, i.e corresponds to the values `V' and `L' for the first character in a C- string representing the Charstring sort. A typical case is a normal assignment statement in SDL.
  • TMP: an object should become temporary if it is not assigned to any persistent variable and therefore should not be copied in subsequent assignments, i.e corresponds to the value `T' for the first character in a C-string representing the Charstring sort. A typical case is a result value from an operator.

What should be done with the old value referenced by the left hand side variable?

Normally free should be performed on the value, as otherwise there would be a memory leak. However, when initializing a variable, no free ought to be performed, as free might be called on a random address. Two different possibilities exists:

    • FR: free old value.
    • NF: do not free old value.

The third assignment property parameter in the GenericAssignSort function should be given a value according to the ideas given above, preferably using the macros indicated.

#define XASS_AC_ASS_FR (int)25
#define XASS_MR_ASS_FR (int)26
#define XASS_AR_ASS_FR (int)28

#define XASS_AC_TMP_FR (int)17
#define XASS_MR_TMP_FR (int)18
#define XASS_AR_TMP_FR (int)20

#define XASS_AC_ASS_NF (int)9
#define XASS_MR_ASS_NF (int)10
#define XASS_AR_ASS_NF (int)12

#define XASS_AC_TMP_NF (int)1
#define XASS_MR_TMP_NF (int)2
#define XASS_AR_TMP_NF (int)4

The macro names above are all of the form XASS_1_2_3, where the abbreviations placed at 1, 2, and 3 should be read:

  • 1 = AC: always copy
  • 1 = MR: may reuse (take pointer if temporary object)
  • 1 = AR: always reuse (take pointer)
  • 2 = ASS: new object assigned to "variable"
  • 2 = TMP: new object temporary
  • 3 = FR: call free for old value referred to by variable
  • 3 = NF: do not call free for old value

The distinction between all these assignment possibility is only of interest when handling types using or containing pointers.

Generic Equal Functions

Each type in SDL has access to an equal macro yEqF_typename and an not equal macro yNEqF_typename. Examples for type Boolean and for a user-defined type A:

#define yEqF_SDL_Boolean(E1,E2) ((E1) == (E2))
#define yNEqF_SDL_Boolean(E1,E2) ((E1) != (E2))

#define yEqF_z3_A(Expr1,Expr2) yEq_z3_A(Expr1,Expr2)
#define yNEqF_z3_A(Expr1,Expr2) ( ! yEq_z3_A(Expr1,Expr2) )
#define yEq_z3_A(Expr1,Expr2) \
GenericEqualSort((void *)Expr1,(void *)Expr2, \
(tSDLTypeInfo *)&ySDL_z3_A)

These macros are used in the generated code (and in the kernel) at each location where equality tests are needed. The parameters to the equal and not equal macro are the two expressions that should be tested.

If C equal or not equal are not possible to use, the equal macros will become calls to an equal function. The basic generic equal function can be found in sctpred.h and sctpred.h:

extern SDL_Boolean GenericEqualSort(void *, void *,
tSDLTypeInfo *);

where:

  • the first two parameters are the addresses to the two expressions to be tested
  • the third parameter is the type info node for the actual type.

Special treatment of Charstring and instantiations of the Own generator has made it necessary to introduce specific wrapper functions that in turn calls GenericEqualSort for these types:

extern SDL_Boolean xEq_SDL_Charstring
(SDL_Charstring, SDL_Charstring);
extern SDL_Boolean GenOwn_Equal (void *, void *,
tSDLTypeInfo *);

Generic Free Functions

Each type in SDL that is implemented as a pointer, or that contains a pointer that references to memory that is automatically handled (in principle all pointers except Ref pointers), has access to a corresponding yFree_typename function or macro. In the generic function model, this is always a macro.

#define yFree_SDL_Charstring(P) xFree_SDL_Charstring(P)
#define xFree_SDL_Charstring(P) \
GenericFreeSort(P,(tSDLTypeInfo *)&ySDL_SDL_Charstring)

#define yFree_A(P) \
GenericFreeSort(P,(tSDLTypeInfo *)&ySDL_A)

The yFree macro will always be translated to a call to the function GenericFreeSort.

extern void GenericFreeSort (void **, tSDLTypeInfo *);

This function takes the address of a variable and a type info node and releases the dynamic memory used by this value contained in the variable.

Generic Make Functions

There are four generic functions constructing values of structured types:

extern void * GenericMakeStruct (void *, tSDLTypeInfo *, ...);
extern void * GenericMakeChoice (void *, tSDLTypeInfo *,
int, void *);
extern void * GenericMakeOwnRef (tSDLTypeInfo *, void *);
extern void * GenericMakeArray (void *, tSDLTypeInfo *,
void *);

GenericMakeStruct: According to SDL, the Make operator is only available for the struct type. However, in the SDL suite the Make operator, and thus the GenericMakeStruct function, is also available for the Object_identifier type and the instantiations of the generators string, powerset, and bag.

  • The void * parameter is the address of a variable where the result should be placed. This value is also returned.
  • The tSDLTypeInfo * parameter is the address to the type info node for the type to be created.
  • "..." denotes a list of addresses to the values for the components in the struct. All parameters must be passed as addresses (void *) regardless if the component type should be passed as an address or as a value. The only exceptions are the types represented as pointers themselves (Charstring, Ref, Own, ORef, and syntypes of these types), where the pointers are passed, not the addresses of the pointers. In case of an optional field or a field with an initializer, a `0' or '1' is passed to indicate if a value for the component is present or not. If `1' is passed the value follows as next parameter. If `0' is passed no value is present in the actual parameter list.

GenericMakeChoice: This function is used for choice types.

  • The first void * parameter is the address of a variable where the result should be placed. This value is also returned.
  • The tSDLTypeInfo * parameter is the address to the type info node for the type to be created.
  • The int parameter decides which choice component that is present.
  • The last void * parameter is the address of the value.

GenericMakeOwnRef: This function is used for instantiations of generators Own and Ref.

  • The tSDLTypeInfo * parameter is the address to the type info node for the type to be created.
  • The void * parameter is the address to the value that should be assigned to the memory allocated by this function.

GenericMakeArray: This function is used for instantiations of the generators Array, Carray, and GArray.

  • The first void * parameter is the address of a variable where the result should be placed. This value is also returned.
  • The tSDLTypeInfo * parameter is the address to the type info node for the type to be created.
  • The last void * parameter is the address to the value that should be assigned to all components of the array.

Generic Function for Operators in Pre-defined Generators

The generic function for the operators in the pre-defined generators follow the general rules for operators with a few exceptions:

  • a type info node is needed as a parameter, as the C function can handle all instantiations of a certain generator.
  • parameters of generator parameter types (component and index types for example) must in many cases be passed as addresses, as the properties of these types are not known.

General array

extern void * GenGArray_Extract (xGArray_Type *, void *,
tSDLGArrayInfo *);
extern void * GenGArray_Modify (xGArray_Type *, void *,
tSDLGArrayInfo *);

  • Parameter 1: The array
  • Parameter 2: The index value passed as an address
  • Parameter 3: The type info node
  • Result: The address of the component

Powerset

Generic functions available for powersets with a simple component type. The powerset is represented a sequences of bits (unsigned char[Appropriate_Length]).

#define GenPow_Empty(SDLInfo,Result) \
memset((void *)Result,0,(SDLInfo)->SortSize)
extern SDL_Boolean GenPow_In (int, xPowerset_Type *,
tSDLPowersetInfo *);
extern void * GenPow_Incl (int, xPowerset_Type *,
tSDLPowersetInfo *, xPowerset_Type *);
extern void * GenPow_Del (int, xPowerset_Type *,
tSDLPowersetInfo *, xPowerset_Type *);
extern void GenPow_Incl2 (int, xPowerset_Type *,
tSDLPowersetInfo *);
extern void GenPow_Del2 (int, xPowerset_Type *,
tSDLPowersetInfo *);
extern SDL_Boolean GenPow_LT (xPowerset_Type *,
xPowerset_Type *, tSDLPowersetInfo *);
extern SDL_Boolean GenPow_LE (xPowerset_Type *,
xPowerset_Type *, tSDLPowersetInfo *);
extern void * GenPow_And (xPowerset_Type *, xPowerset_Type *,
tSDLPowersetInfo *, xPowerset_Type *);
extern void * GenPow_Or (xPowerset_Type *, xPowerset_Type *,
tSDLPowersetInfo *, xPowerset_Type *);
extern SDL_Integer GenPow_Length (xPowerset_Type *,
tSDLPowersetInfo *);
extern int GenPow_Take (xPowerset_Type *, tSDLPowersetInfo *);
extern int GenPow_Take2 (xPowerset_Type *, SDL_Integer,
tSDLPowersetInfo *);

  • Parameter of type int in GenPow_In, GenPow_Incl, GenPow_Del, GenPow_Incl2, GenPow_Del2: A component value.
  • Result of type int in GenPow_Take, GenPow_Take2: A component value.
  • Parameters of type tSDLPowersetInfo *: The type info node.
  • Parameters of type xPowerset_Type * after the type info node: The address where the result should be stored. This address is returned by the function.
  • Other xPowerset_Type * parameters: Powerset in parameters.

Bag and General Powerset

The following generic functions are available for bags and powersets with complex component type. These types are represented as linked lists in C.

#define GenBag_Empty(SDLInfo,Result) \
memset((void *)Result,0,(SDLInfo)->SortSize)
extern void * GenBag_Makebag (void *, tSDLGenListInfo *,
xBag_Type *);
extern SDL_Boolean GenBag_In (void *, xBag_Type *,
tSDLGenListInfo *);
extern void * GenBag_Incl (void *, xBag_Type *,
tSDLGenListInfo *, xBag_Type *);
extern void * GenBag_Del (void *, xBag_Type *,
tSDLGenListInfo *, xBag_Type *);
extern void GenBag_Incl2 (void *, xBag_Type *,
tSDLGenListInfo *);
extern void GenBag_Del2 (void *, xBag_Type *,
tSDLGenListInfo *);
extern SDL_Boolean GenBag_LT (xBag_Type *, xBag_Type *,
tSDLGenListInfo *);
extern SDL_Boolean GenBag_LE (xBag_Type *, xBag_Type *,
tSDLGenListInfo *);
extern void * GenBag_And (xBag_Type *, xBag_Type *,
tSDLGenListInfo *, xBag_Type *);
extern void * GenBag_Or(xBag_Type *, xBag_Type *,
tSDLGenListInfo *, xBag_Type *);
extern SDL_Integer GenBag_Length (xBag_Type *,
tSDLGenListInfo *);
extern void * GenBag_Take (xBag_Type *, tSDLGenListInfo *,
void *);
extern void * GenBag_Take2 (xBag_Type *, SDL_Integer,
tSDLGenListInfo *, void *);

  • Parameter of type int in GenBag_Makebag, GenBag_In, GenBag_Incl, GenBag_Del, GenBag_Incl2, GenBag_Del2: The address of the component value.
  • Result of type int in GenBag_Take, GenBag_Take2: The address of the component value.
  • Parameters of type tSDLGenListInfo *: The type info node.
  • Parameters of type xBag_Type * after the type info node: The address where the result should be stored. This address is returned by the function.
  • Parameters of type void * after the type info node: The address where the result should be stored. This address is returned by the function.
  • Other xBag_Type * parameters: Bag/Powerset in parameters.

String

The following Generic functions are available for String instantiations. A String is implemented as a linked list.

#define GenString_Emptystring(SDLInfo,Result) \
memset((void *)Result,0,(SDLInfo)->SortSize)
extern void * GenString_MkString (void *, tSDLGenListInfo *,
xString_Type *);
extern SDL_Integer GenString_Length (xString_Type *,
tSDLGenListInfo *);
extern void * GenString_First (xString_Type *,
tSDLGenListInfo *, void *);
extern void * GenString_Last (xString_Type *,
tSDLGenListInfo *, void *);
extern void * GenString_Concat (xString_Type *,
xString_Type *, tSDLGenListInfo *, xString_Type *);
extern void * GenString_SubString (xString_Type *,
SDL_Integer, SDL_Integer, tSDLGenListInfo *,
xString_Type *);
extern void GenString_Append (xString_Type *, void *,
tSDLGenListInfo *);
extern void * GenString_Extract (xString_Type *, SDL_Integer,
tSDLGenListInfo *);

  • Parameter of type void * in GenString_MkString, GenString_Append: Address of component value.
  • Parameter of type void * or xString_Type * after type info node: The address where the result should be stored. This address is returned by the function.
  • Parameters of type tSDLGenListInfo *: The type info node.
  • Other parameters: According to SDL definition of parameters.

Limited String

Generic functions available for limited strings, i.e. strings with #STRING directive giving a max size of the string. These strings are implemented as an array in C.

#define GenLString_Emptystring(SDLInfo,Result) \
memset((void *)Result,0,(SDLInfo)->SortSize)
extern void * GenLString_MkString (void *, tSDLLStringInfo *,
xLString_Type *);
#define GenLString_Length(ST,SDLInfo) (ST)->Length
extern void * GenLString_First (xLString_Type *,
tSDLLStringInfo *, void *);
extern void * GenLString_Last (xLString_Type *,
tSDLLStringInfo *, void *);
extern void * GenLString_Concat (xLString_Type *,
xLString_Type *, tSDLLStringInfo *, xLString_Type *);
extern void * GenLString_SubString (xLString_Type *,
SDL_Integer, SDL_Integer, tSDLLStringInfo *,
xLString_Type *);
extern void GenLString_Append (xLString_Type *, void *,
tSDLLStringInfo *);
extern void * GenLString_Extract (xLString_Type *,
SDL_Integer, tSDLLStringInfo *);

  • Parameter of type void * in GenLString_MkString, GenString_Append: Address of component value.
  • Parameter of type void * or xLString_Type * after type info node: The address where the result should be stored. This address is returned by the function.
  • Parameters of type tSDLLStringInfo *: The type info node.
  • Other parameters: According to SDL definition of parameters.

More about Abstract Data Types

Including Type Definitions

Note:

Use the features presented in this section with care. The features were developed early in the SDL suite history. Now in principle every data type in C can be expressed in SDL as well. Therefore, the recommended method is to write the types in SDL or to translate C types to SDL using the cpp2sdl tool.
History has also shown that it has been difficult to keep full backward compatibility for these features and at the same time improve the performance of the generated code. This of course comes from that these features is highly dependent on the way code is generated.

In this subsection, the inclusion of a type definition in the target language for an abstract data type will be described. When this facility is used, it is necessary to specify how to perform assignment, test for equal, assign default values, and so on, as it is not possible to generate when the type definition is not known (not generated). All this information is given in the #ADT directive, which has the following structure:

/*#ADT
(T(x) A(x) E(x) F(x) K(x) X(x) M(x) W(x) R(x)
xy 'file name')
#TYPE
C code
#HEADING
C code
#BODY
C code
*/

where each x on the first line should be replaced by one of the characters B, H, Q, S, or G. Replace y by P or I. The interpretation of these characters is similar to the their interpretation for operators.

B | Body
H | Heading
Q | Question
S | Standard
G | Generate
P | Prefix
I | Infix

The reason why G (generate) is not allowed for operators or literals is of course that it would mean to generate the implementation of the operators from the axioms, which is, at least in the general case, an impossible task. For an operator defined in an operator diagram, G is assumed independently of what the user specifies.

The specifications, given in ADT directives, of how to generate code for type definition, assignment, test for equal, default values, and free function should be interpreted according to the table below.

Type Definition

First the actual type definition. The entry - should be interpreted as if no specification is given for T.

Type | Interpretation
T(G) | Generate type definition from SDL sort
T(B) | Do not generate type definition. Assume the type should be "passed as value" to operators
T(BV) | Do not generate type definition. Assume the type should be "passed as address" to operators
T | Same as T(B)
- | Same as T(G)

Assignment

It is possible to select how assignments should be performed for values of the type. Note that all generated assignments will be of the form:

yAssF_#(SortName)(....);

The yAssF_#(SortName) is a macro either implemented as assignment or as a call to the yAss_#(SortName) function (if such function is to be used), i.e as:

#define yAssF_#(S)(V,E,A) V = E
#define yAssF_#(S)(V,E,A) yAss_#(S)(&(V),E,A)

Type
Interpretation
A(B)
Use and generate heading, but not body, of yAss_#(S)
A(H)
Use, but generate no code for yAss_#(S)
A(G)
  • If the type definition is generated:
    • Use = if possible.
    • Otherwise use the GenericAssignSort function
  • If type definition is not generated ( T, T(B) ):
    • Use =
A(S)
Use =
A
Same as A(B)
-
Same as A(G)

If you define your own assign function, it must be implemented as a function, as the address of the function will be stored (in the type info node for the data type) so GenericAssignSort can call it to handle subcomponents of this type. An assign function has the following heading:

void yAss_#(SortName)
(#(SortName) *yVar,
#(SortName) *yExpr,
int AssType)

It should assign the value passed as second parameter to the variable passed as first parameter. If the type that is to be assigned contains any pointers the assign function is a bit complicated to write in order to avoid access errors and memory leaks. See the discussion about the AssType parameter to GenericAssignSort in "Generic Assignment Functions" .

Equal Test

It is possible to select how test for equality should be performed for values of the type. Note that all generated equal tests will be of the form:

yEqF_#(SortName)(....);

The yEqF_#(SortName) is a macro either implemented as C equal or as a call to the yEq_#(SortName) function (if such function is to be used), i.e as:

#define yEqF_#(S)(E1,E2) E1 == E2
#define yEqF_#(S)(E1,E2) yEq_#(S)(E1,E2)

The /= operator is represented by the macro

#define yNEqF_#(S)(E1,E2) (! yEqF_#(S)(E1,E2) ).

Type
Method
E(B)
Use and generate heading, but not body, of yEq_#(S)
E(H)
Use but generate no code for yEq_#(S)
E(G)
  • If the type definition is generated:
    • Use == if possible
    • Otherwise use the GenericEqualSort function.
  • If the type definition is not generated
    • Use ==
E(S)
Use ==
E(Q)
Use and generate an equal function that asks for the result of the test (same as Q for operators).
E
Same as E(B)
-
Same as E(G)

If you define your own equal function, it must be implemented as a function, as the address of the function will be stored (in the type info node for the data type) so GenericEqualSort can call it to handle subcomponents of this type. An equal function has the following heading:

SDL_Boolean yEq_#(SortName)
(#(SortName) *yExpr1,
#(SortName) *yExpr2);

It should return true or false depending on if the two values passed as parameters are equal or not. If the parameters contain pointers it might be necessary to free these values, please see the discussion on general parameters to operators in"Other Types Containing Pointers" .

Free of Dynamic Memory

This section describes how dynamic memory (if used for the type) will be released for reuse when it is no longer needed.

Type | Interpretation
F(B) | Generate heading, but no body of the free function yFree_#(SortName).
F(H) | Generate neither heading nor body of the free function.
F(S) | Use the function GenericFreeSort
F | Same as F(B)
- | Do not use free function.

If you define your own free function, it must be implemented as a function, as the address of the function will be stored (in the type info node for the data type) so GenericFreeSort can call it to handle subcomponents of this type. A free function should have the following prototype

void yFree_#(SortName) (void **yVar)

The function should take the address to a pointer, return the allocated memory to the pool of available memory and assign 0 to the pointer.

Extract! and Modify!

This entry specifies how component selection (struct components, array components for example) should be performed. In SDL a component can be selected in two ways:

Variable ! Component
Variable (Index)

An Extract operation can be generated in four ways:

Variable.Component used for struct and #UNIONC
Variable.U.Component used for #UNION and choice
Variable.A(Index) used for array
yExtr_SortName(Variable,Expr)

The last version, the Extract function, is used for all other cases.

Type | Interpretation
X(B) | Use Extract function
X(G) | Use component selection according to table above.
X | Same as X(B)
- | Same as X(G)

A Modify operation can in the same way be generated in four ways:

Variable.Component used for struct and #UNIONC
Variable.U.Component used for #UNION and choice
Variable.A(Index) used for array
(* yAddr_SortName((&Variable), Expr))

The last version, the Addr function, is used for all other cases.

Type | Interpretation
M(B) | Use Addr function
M(G) | Use component selection according to table above.
M | Same as M(B)
- | Same as M(G)

Read and Write Function

The write function is used by the monitor system to write values of the type.

Type | Interpretation
W(B) | Generate heading but not the body of a write function.
W(H) | Generate neither heading nor body of a write function, but assume that the user has provided such a function.
W(S) | Values of this type are to be printed as a HEX string. No write function is assumed to be present.
W | Same as W(B)
- | Same as W(S)

The read function is used by the monitor system to read values of the type.

Type | Interpretation
R(B) | Generate heading but not the body of a read function.
R(H) | Generate neither heading nor body of a read function, but assume that the user has provided such a function.
R(S) | Values of this type are to be read as a HEX string. No read function is assumed to be present.
R | Same as R(B)
- | Same as R(S)

In order to examine variable values for variables that are of a sort that is implemented in C, i.e. has #ADT(T) in its ADT directive, it is necessary to implement a write function. Otherwise the value can only be presented as a HEX string. Note that the run-time kernel can automatically handle all SDL sorts for which the code generator generates the C type definition. A write function should look like:

extern char * yWri_SortName (void * Value)

Given the address of a value of the type SortName, this function should return a char *, i.e. a character string, containing the value represented in a printable form. This character string is the string that will be printed by the monitor, when it needs to print a value of this type. To implement the write function it is not uncommon that a static char array is needed.

Note:

The following two considerations when it comes to write and read functions:

  • The read and write functions and any help variables and help functions ought to be surrounded by
#ifdef XREADANDWRITEF
#endif
to be removed if read and write functions are not needed.
  • The string format used to represent value of a type should be the same in the read and the write function. Otherwise communicating simulations will not work if this type is passed as parameter between the systems.

The function xWriteSort, which is part of the run-time kernel can be useful when implementing Write functions.

extern char * xWriteSort (
void *In_Addr,
xSortIdNode SortNode);

The xWriteSort function takes the address of a value to be printed, and a pointer to a xSortIdNode and returns the given value as a string. This function is typically useful if the sort we are implementing a write function for contains one or several components of sorts defined in SDL.

Read Function

In order to assign new values to variables that are of a sort that is implemented in C, i.e. has #ADT(T) in its ADT directive, it is necessary to implement a read function. Otherwise the value can only be read as a HEX string. Note that the run-time kernel can automatically handle all SDL sorts for which the code generator generates the C type definition. A read function should look like:

extern int yRead_SortName (void * Result)

A read function is given an address to store the value that is read. It should return 1 if the read operation was successful. Otherwise, 0 should be returned and Result should be unchanged.

There are some suitable functions in the run-time kernel which can help you when you are implementing a read function. Basically the function xScanToken described below is a tokenizer that transforms sequences of characters to tokens. This function returns tokens according to the following enum type:

typedef enum {
xxId, /* identifiers, numbers */
xxString, /* SDL Charstring literal */
xxSlash, /* / */
xxColon, /* : */
xxMinus, /* - */
xxPlus, /* + */
xxStar, /* * */
xxComma, /* , */
xxSemicolon, /* ; */
xxArrowHead, /* ^ */
xxLPar, /* ( */
xxRPar, /* ) */
xxLParDot, /* (. */
xxRParDot, /* .) */
xxLParColon, /* (: */
xxRParColon, /* :) */
xxDot, /* . */
xxLBracket, /* [ */
xxRBracket, /* ] */
xxLCurlyBracket, /* { */
xxRCurlyBracket, /* } */
xxAt, /* @ */
xxQuaStart, /* << */
xxQuaEnd, /* >> */
xxLT, /* < */
xxLE, /* <= */
xxGT, /* > */
xxGE, /* >= */
xxEQ, /* = */
xxNE, /* /= */
xxQuestionMark, /* ? */
xx2QuestionMark, /* ?? */
xxExclMark, /* ! */
xxSystem, /* system */
xxPackage, /* package */
xxBlock, /* block */
xxProcess, /* process */
xxProcedure, /* procedure */
xxOperator, /* operator */
xxSubstructure, /* substructure */
xxChannel, /* channel */
xxSignalroute, /* signalroute */
xxType, /* type */
xxNull, /* null */
xxEnv, /* env */
xxSelf, /* self */
xxParent, /* parent */
xxOffspring, /* offspring */
xxSender, /* sender */
xxEoln, /* end of line */
xxEOF, /* end of file */
xxErrorToken /* used to indicate error */
} xxToken;

Function xScanToken

The function xScanToken:

extern xxToken xScanToken ( char * strVar);

reads the next token from input (stdin or Simulator UI) and returns the type of the next token as function result. If the token is xxId or xxString the strVar parameter will contain the identifier, number, or string. The size of the char[] parameter passed as actual parameter should be large enough to store the possible values. If some other token was found, no information is stored in strVar.

xUngetToken

Sometimes it is necessary to look-ahead to determine how to handle the current token. Using the function xUngetToken below it is possible return one token to the input. Note that both parameters must have the values obtained from xScanToken.

extern void xUngetToken (
xxToken Token,
char * strVar);

The functions below can also be useful while implementing Read function. xPromptQuestionMark is suitable to obtain prompt in a similar way as for SDL defined sorts, while xReadOneParameter can be used to read element for element in a list, separated by commas and terminated either by ".)" or "]". The function xReadSort is similar to xWriteSort and can be used to read a component in the treated sort.

xPromptQuestionMark

extern xxToken xPromptQuestionMark (
char * Prompt,
char * QuestionPrompt,
char * strVar);

The function result and the parameter strVar behave in the same way as for the function xScanToken (see above). The parameter Prompt is the prompt that should be used. This string has to start with a ` `, i.e. a space. To conform with other built-in read function, the Prompt parameter should be: " (SortName) : " (note the ending space colon space). The QuestionPrompt parameter should either be identical to the Prompt parameter, or be null, i.e. (char *)0. If QuestionPrompt is null, the xPromptQuestionMark function will return xxEoln if a end-of-line is found. If QuestionPrompt is not null, the xPromptQuestionMark function will print the QuestionPrompt, and continue to read. Normally QuestionPrompt should be equal to Prompt in a simple data type, while it should be null in a structured data type.

Example 371 : ADT Example, Byte Type

This example is taken from the ADT byte (see "Abstract Data Type for Byte" ). The byte type should be read and printed using HEX format.

#ifdef XREADANDWRITEF
static char yCTmp[20];

extern int yRead_byte( void *Result )
{
unsigned temp;
xxToken Token;

Token = xPromptQuestionMark(" (byte) : ",
" (byte) : ", yCTmp);

if (Token==xxId && sscanf(yCTmp, "%X", &temp)>=1) {
*(byte *)Result = (byte)temp;
return 1;
}
xPrintString("Illegal byte value\n");
return 0;
}

extern char *yWri_byte( void * C)
{
sprintf(yCTmp, "%0.2X", *(byte *)C);
return yCTmp;
}
#endif

Example 372 : ADT Example, Struct Write Functions

This is an example of how the read and write functions for a struct with two components can look. The monitor system can handle reading of writing of struct values automatically, so please see this just as an example.

newtype struct1 /*#NAME `struct1' */ struct
a,b Integer;

/*#ADT(W)
#BODY
#ifdef XREADANDWRITEF
static char CTemp[500];

char * yWri_struct1 (void *In_Addr)
{
strcpy(CTemp, "(. ");
strcat(CTemp, xWriteSort((void *)
(&((struct1 *)In_Addr)->a), xSrtN_SDL_Integer) );
strcat(CTemp, ", ");
strcat(CTemp, xWriteSort((void *)
(&((struct1 *)In_Addr)->b), xSrtN_SDL_Integer) );
strcat(CTemp, " .)");
return CTemp;
}
#endif
*/
endnewtype;

More about #ADT

When generate is specified for a function, the code generator might decide not to generate the heading of the function, as in some cases it is not needed.

All code that is not generated is assumed to be included by the user in the #TYPE, #HEADING and #BODY sections in the #ADT directive.

Another name for an assign function, equal function and so on may be used, by including the desired name within quotes together with the generation options in the #ADT directive.

If, for example, the name of a certain assign function should be AssX, this can be obtained by specifying: A(B 'AssX') for the assign function. This name will then be used throughout the generated code, both in generated declaration and at the places where the function is called. The name should be last in the specification for the actual function.

An include statement may be generated together with or replacing the type definition by giving a file name within quotes last in the specification part of the #ADT directive, immediately before the first section with code.

Example 373 : Including a File in ADT

If the directive

/*#ADT (T(B) A(S) E(S) 'file name') */

is used, the following include statement will be generated:

#include "file name"

Note:

Turning off the generation of the objects contained in the include file must be performed by the user.

Directive #REF

Note:

This directive is provided only for backward compatibility. The SDL suite now supports in/out parameters for operators, which serves exactly the same purpose. In/out parameter is an SDL-2000 extension and is supported also in operator diagrams.

The directive #REF can be used to specify that the address, not the value, of a variable should be passed as parameter to an ADT operator, as it is defined in SDL. This feature cannot be used for operators defined in operator diagrams (the directive will be ignored for such operators).

The #REF directive is used as shown in the example below.

Example 374 : Including a File in ADT

operators
eq1 : Integer, Integer -> Integer;
eq2 : Integer/*#REF*/, Integer/*#REF*/ -> Integer;

The headings for these two operator will become in ANSI-C syntax (ignoring prefixes)

extern SDL_Integer eq1 (SDL_Integer P1,
SDL_Integer P2);
extern SDL_Integer eq2 (SDL_Integer *P1,
SDL_Integer *P2);

This feature can be used to optimize parameter passing to operators. The directive, however, also imposes the restriction that the actual parameters must be a variable or a formal parameter (see Example 375 below). This is checked by the code generator. A #REF directive does not in any way effect the way a operator call should be implemented in SDL. It is the responsibility of the code generator to generate the proper actual parameters in C.

Example 375 : Including a File in ADT

With the ADT in the previous example the following operator call is valid:

eq1(sVar, (. 1, 2, 3, 4 .) )

The same call of eq2 would not be valid as the second parameter is not a variable or a formal parameter.

Generators

The Cadvanced/Cbasic SDL to C Compiler handles all the predefined generators in SDL, i.e. Array, String, Powerset, and Bag. It is also possible for a user to write his own generators and instantiate them in newtypes. However, the behavior of a user defined generator has to be specified completely by the user. This is performed in a somewhat extended #ADT directive placed just before the endgenerator keyword. These extensions are described below.

There are three additional sections in the directive, apart from #TYPE, #HEADING, and #BODY. These are #INSTTYPE, #INSTHEADING, and #INSTBODY. The inline C code in #TYPE, #HEADING, and #BODY is placed at the point of the generator, i.e. it is generated once. The contents of #INSTTYPE, #INSTHEADING, and #INSTBODY is inserted at each instantiation of the generator, i.e. in each newtype defined using the generator.

In the #INSTTYPE, #INSTHEADING, and #INSTBODY it is possible to use # followed by a number to access the information given in the generator instantiation:

  • #0 means the name of the newtype in the instantiation
  • #1 and ##1 is the first actual generator parameter
  • #2 and ##2 is the second actual generator parameter
  • and so on.

#1 and ##1 are equal, except when the corresponding actual generator parameter is a struct (or union). In that case, assuming the SDL struct:

newtype aaa struct
a, b integer;
endnewtype;

which will be generated as

typedef struct aaa_s {
SDL_Integer a;
SDL_Integer b;
} aaa;

#1 will become struct aaa_s (or union aaa_s if a union), while ##1 will become aaa.

Example 376 : Example of User Defined Generator

GENERATOR Ref (TYPE Itemsort)
LITERALS
Null; /*#OP(S)*/
OPERATORS
Ref2VStar : Ref -> VoidStar; /*#OP(HP)*/
DEFAULT Null;
/*#ADT()
#INSTTYPE
typedef #1 *#0;
#INSTHEADING
#define #(Null)() 0
#define #(Ref2VStar)(P) ((#(VoidStar))P)
*/
ENDGENERATOR Ref;

Note the usage of #INSTTYPE and #INSTHEADING in the example above. The code in these section will be inserted in each newtype defined with this generator. For example, in a newtype:

NEWTYPE p Ref(Integer)
ENDNEWTYPE;

The #INSTTYPE section will become:

typedef SDL_Integer *p;


Directives to the Cadvanced/Cbasic SDL to C Compiler

Syntax of Directives

The Cadvanced/Cbasic SDL to C Compiler recognizes a number of directives given mainly in SDL comments. The #ADT, #OP, #UNION, and #REF directives used in abstract data types are examples of such directives. The directives #ADT and #OP were described in the section "Implementation of User Defined Operators" , "Union" , and "Directive #REF" , in connection with abstract data types and are not further discussed here.

A directive has the general structure:

  1. The start of comment character: /*
  2. A `#' character.
  3. The directive name.
  4. Possible directive parameters given in free syntax. That is, spaces and carriage returns are allowed here.
  5. The end of comment characters */.

Upper and lower case letters are considered to be equal in directive names.

Example 377 : #OP Directive

Take as an example the directive:

/*#OP (B) */.

This comment will be recognized as a directive only if no other character is inserted in the sequence /*#OP. After this part, spaces and carriage returns may be inserted freely.

Selecting File Structure for Generated Code
- Directive #SEPARATE

The purpose of the separate generation feature is to specify the file structure of the generated program. Both the division of the system into a number of files and the actual file names can be specified. There are two ways this information can be given.

  • Normally this information is set up in the Organizer, using the Edit Separation command, see "Edit Separation" . Here file names for the generated files can also be specified. In the Make dialog in the Organizer (see "Make" ) it is possible to select full separate generation, user-defined separate generation, or no separate generation.
  • For an SDL/PR file that is used as input when running the SDL Analyzer as a stand-alone tool, the same information can be entered by #SEPARATE directives directly introduced in the SDL program. Full separate generation, user-defined separate generation, or no separate generation can be set up in the command interface of a stand-alone Analyzer, see "Set-Modularity" .

The Cadvanced/Cbasic SDL to C Compiler can generate a separate file for:

  • system (always separate)
  • package (always separate)
  • system type
  • block
  • block type
  • process
  • process type
  • service
  • service type
  • procedure

Note:

Instantiations cannot be separated, i.e. an instance of a block type cannot be generated on a file of its own.

If #SEPARATE directives are used, they should be placed directly after the first semicolon in the system, block, process, or procedure heading; see the following example.

Example 378 : #SEPARATE Directive

system S; /*#SEPARATE 'filename' */
block B; /*#SEPARATE */
process type P1 inherits PType; /*#SEPARATE */
process P2 (1, ); /*#SEPARATE */
procedure Q; /*#SEPARATE */

In the example above the two versions of separate directive, with or without file name, are shown. As can be seen a file name should be enclosed between quotes. The code generator will append appropriate extensions to this name when it generates code.

If no file name is given in the directive, the name of the system, block, process, or procedure will be used to obtain a file name. In such case the file name becomes the name of the unit with the appropriate extension (.c .h) depending on contents. The file name is stripped from characters that are not letters, digits or underscores.

The possibility to set up full, user-defined, or no separation in the Organizer's Make dialog and in the user interface of a stand-alone Analyzer (see "The Analyzer Command-Line UI" ), can be used, in simple manner, to select certain default separation schemes. This setting will be interpreted in the following way:

  • No separation.
    The system and each package will be generated on a separate file.
  • User defined separation.
    The system, each package, and each unit that the user has specified as separate will become a separate file.
  • Full separation.
    The system, each package, each block, block type, process, process type, service, and service type will become a separate file. Note that even in this case a procedure is separate only if the user has specified it as separate.

Independently if No, User defined, or Full separation has be selected, the code generator will use the file name specified in the Edit Separation dialog or the #SEPARATE directive, for a file that is to be generated.

An Example of the Usage of the Separate Feature

In the following example a system structure and the #SEPARATE directives are given. The same information can easily be set up in the Organizer as well. This example is then used to show the generated file structure depending on selected generation option.

Example 379 : #SEPARATE Directive

system S; /*#SEPARATE 'Sfile' */
block B1; /*#SEPARATE */
process P11; /*#SEPARATE 'P11file' */
process P12;
block B2;
process P21;
process P22; /*#SEPARATE */
Note that #SEPARATE directives can only be used in SDL/PR files. Normally this information is given in the Organizer.

Applying Full Separate Generation

If Full separate generation is selected then the following files will be generated:

 Sfile.c

 Sfile.h

 B1.c

 B1.h

 P11file.c

 P12.c

 B2.c

 B2.h

 P21.c

 P22.c

The .c files contain the C code for the corresponding SDL unit and the .h files contain the module interfaces.

Applying Separate Generation

If User defined separate generation is selected then the following files will be generated:

 Sfile.c

 Sfile.h
Contains code for units S, B2, P21

 B1.c

 B1.h
Contains code for units B1, P12

 P11file.c
Contains code for unit P11

 P22.c
Contains code for unit P22

The user defined separate generation option thus makes it possible for a user to completely decide the file structure for the generated code. The comments on files and extensions given above are, of course, also valid in this case.

Applying No Separate Generation

If the separation option No is selected, only the following file will be generated:

 Sfile.c
Contains code for all units

The comments on files and extensions earlier are valid even here.

Guidelines

Generally a system should be divided into manageable pieces of code. That is, for a large system full separate generation should be used, while for a small system no separate generation ought to be used. The possibility to regenerate and recompile only parts of a system usually compensate for the overhead in generating and compiling several files for a large system.

Note:

A file name has to be specified, in the Organizer Edit Separation command, see "Edit Separation" , or in the #SEPARATE directive, if two units in the system have the same name in SDL and should both be generated on separate files, otherwise the same file name will be used for both units.

Accessing SDL Names in C Code
- Directive #SDL

When writing C code that is to be included in a generated program it is often necessary to refer to names of objects defined in SDL. The name of an SDL object is, however, transformed when it is translated to C. A prefix, which is a sequence of characters, is added to the SDL name to make the C name unique in the C program. Furthermore, all characters in SDL name which are not allowed in a C name are removed. The prefixes are calculated by looking at the structure of definitions in the actual scope and in all scopes above. This means that adding a declaration at the system level might change all prefixes in blocks and processes contained in the system. As a consequence it is almost impossible to know the prefix of an object in advance.

To be able to write C code and use the name of SDL objects in that code, the Cadvanced/Cbasic SDL to C Compiler provides the directive #SDL which is used in C code to translate an SDL name to the corresponding C name.

The syntax of the #SDL directive is as follows:

#SDL (SDL name)

or

#SDL (SDL name, entity class name)

There is also a short form for the directive. No characters are allowed between the # character and the left parentheses in this form:

#(SDL name)

or

#(SDL name, entity class name)

Replace SDL name with the name of an object in the SDL definition and entity class name by any of the following identifiers (upper and lower case letters are considered to be equal):

 block
 blockinst
 blocksubst
 blocktype
 channel
 channelsubst
 connect
 formalpar
 gate
 generator
 label
 literal
 newtype

 operator
 package
 predef
 procedure
 process
 processinst
 processtype
 remoteprd
 remotevar
 service
 serviceinst
 servicetype

 signal
 signallist
 signalroute
 sort (= newtype)
 state
 synonym
 syntype
 system
 systemtype
 timer
 variable
 view

This list contains all entity classes, which means that not all of the entries are relevant for practical use. When a #SDL directive is found in included C code, the code generator first identifies what SDL object is referred to and then replaces the directive by the C name for that object. The search for the SDL object starts in the current scope (the scope where the C code is included), and follows the scope hierarchy outward to the system definition, until an appropriate SDL object is found. An appropriate SDL name is considered to be found if it has the specified name and is in the specified entity class. If no entity class name is given the search is performed for all entity classes.

Note:

In types, especially in block types, #SDL should be used with care. The reason is that some of the objects in a block type are generated for each instantiation of the block. A #SDL directive on such an object might lead to overloading of names in C. Sensitive objects are processes, process instantiations, signal routes, channels, remote definitions.

The table in the subsection "SDL Predefined Types" gives the direct translation between an SDL name and the corresponding C name or expression. For these names the #SDL directive should not be used.

Including C Code in Task - Directive #CODE

The user's own C code may be included in tasks by using the #CODE directive. This directive has the following syntax:

/*#CODE
C code that should
be included in
generated code */

Type the directive name on the first line and the C code on the following lines up to the end of comment symbol. Note that text on the same line as the #CODE directive are not handled.

A #CODE directive can be placed:

  • Before the first assignment statement or informal text
  • Immediately preceding or just following the comma that separates two assignment statements or informal texts
  • After the last assignment statement or informal text
  • Immediately after the ending semicolon (;) of a task (this position is only available in SDL/PR).

The C code in the directives is textually included in the generated code at the position of the directive. If, for example, a code directive is placed between two assignment statements, the code in the directive is inserted between the translated version of the assignment statements.

Note:

The Cadvanced/Cbasic SDL to C Compiler handles the C code in directives as text and performs no check that the code is valid C code.

The code directive is included as a facility in the code generator to provide experienced users an escape possibility to the target language C. This increases the application range of the code generator.

An example of a possible use of the code directive is: An algorithm for some computation, which in the SDL description is only indicated as a task with an informal text, could be implemented in C. In this case the directive #SDL described in the previous subsection will probably become useful to access variables and formal parameters defined in SDL.

Some general hints on how to write C code that can be included into a simulation program, especially when charstrings or sorts containing charstrings as components are used, can be found in the last part of the section "Implementation of User Defined Operators" .

Unfortunately it is not possible to have C comments within the code that is included in any directive, as SDL and C use the same symbols for start and end of comments. See also Example 359 which illustrates the possibility to use the C macro COMMENT.

Including C Declarations - Directive #CODE

The #CODE directive can also be used to include C declarations; for example types, variables, functions, #define, and #include in the declaration parts of the C program. This version of the code directive has the following structure:

/*#CODE
#TYPE
C code containing:
Types and variables
#HEADING
C code containing:
Extern or static declarations of functions
#BODY
C code containing:
Bodies of functions
*/

The separation of functions into HEADING and BODY sections serves the same purpose as in the #ADT directive, see "Implementation of User Defined Operators" .

Code directives to include C declarations may, generally speaking, be placed immediately after a semicolon that ends a declaration in SDL. More precisely it is allowed to place a #CODE directive after the semicolon that ends:

  • A heading of a system, block, substructure, process, procedure
  • The formal parameters of a process or procedure
  • The definition of a block, process, procedure
  • The definition of a channel, signal route, signal, signal list, newtype, syntype, synonym, generator, connection, valid input signal set, variable, view, import, timer, remote variable, remote procedure

In the following small PR example the allowed positions are marked with an * followed by a number.

Example 380 : #CODE Directive

system s; *1
signal s1, s2(integer); *2
channel c1 from env to b1
with s1, s2; *3
newtype n
...
endnewtype n; *4
block b1; *5
signalroute sr1 from env to p1
with s1, s2; *6
connect c1 with sr1; *7
process p1 (1,1); *8
signalset s1, s2; *9
dcl a n; *10
start;
...
state ...;
...
endprocess p1; *11
endblock b1; *12
endsystem s1;

A code directive is considered to belong to the unit where it is defined and the declarations within the directive are thus placed among the other C declaration for that unit. In the example above, directives at positions 1, 2, 3, 4, 12 belong to system s, directives at positions 5,6,7,11 belong to block b1, while directives at positions 8, 9, 10 belong to process p1. Only one code directive may be placed at each available position.

Note:

A variable declared in a #CODE directive that belongs to a process will be shared between the process instances of the process instance set. Such a variable should only be used to represent some common property of all the process instances. To have a variable that is local to a process instance, the variable should be defined in SDL using DCL.

In the generated code the type sections are included in the order of appearance in SDL. However, the type sections are also sensitive for their relative position comparing with SDL sort definitions. This means that the order of the type definitions in the system in the example above will be as follows:

  1. Type sections in 1, 2, 3
  2. Type generated for newtype n
  3. Type sections in 4, 12

As the Cadvanced/Cbasic SDL to C Compiler will generate the SDL sorts in the correct order, definition before usage, in C, the full algorithm is as follows.

  • Step through all definitions in SDL in the order of appearance and include:
    • the type section of #CODE directives and #ADT directives.
    • generate typedef for a sort that have no reference to some other not yet generated sort.
  • Step through all sorts that have not been generated, checking whether each sort references some other sort that has not been generated. If a sort does not reference some other un-generated sort, it requires typedef generation.
  • Repeat the previous step until all sorts have been generated, or until no more sorts can be generated. If sorts remain not generated at this step a recursive dependency has been detected.

The heading sections are placed in the order of their appearance in SDL. This applies to the body sections as well. All body sections will be placed after the sequence of heading sections and the heading section will be placed after all the type definitions. The SDL declarations made in the corresponding unit are available in the code directives and can as usual be reached using the #SDL directive. All declarations made in code directives are of course available in code directives in tasks in the corresponding unit or in its subunits.

The general hints on how to write C code that fits into a generated C program given in the section "Implementation of User Defined Operators" and in the section "Accessing SDL Names in C Code - Directive #SDL" are also applicable here.

Including C Code in SDL Expressions
- Operator #CODE

For each sort defined in an SDL system, both predefined and user defined, the Cadvanced/Cbasic SDL to C Compiler includes an operator #CODE with the following signature:

#CODE : Charstring -> S;

where S is replaced by the sort name. This operator or rather these operators make it possible to access variables and functions defined in C using the #CODE directive in SDL expressions and still have syntactically and semantically correct SDL expressions.

During code generation, the code generator will just copy the Charstring parameter at the place of the #CODE operator.

Example 381 : #CODE Directive

Suppose that x and y are SDL variables, which are translated to z72_x and z73_y, that a and b are C variables, and f is a C function defined in #CODE directives.

SDL expression
C expression

 x + #CODE('a')

 z72_x + a

 x + #CODE('a*b')

 z72_x + a*b

 x*#CODE('(a+b)')*y

 z72_x*(a+b)* z73_y

 #CODE('f(a,#SDL(x))')

 f(a, z72_x)

Within the Charstring parameter of a #CODE operator the #SDL directive is available in the same way as in other included C code. This is also shown in the last of the examples above.

As there is one #CODE operator for each sort in the system, it is sometimes necessary to qualify the operator with a sort name to make it possible for the SDL Analyzer to resolve which operator that has been used. If, for example, the question and all answers in a decision are given as applications of #CODE operators, then it is not possible to determine the type for the decision. One of the #CODE operators should then be qualified with a sort name to resolve the conflict.

Example 382 : Code Directive

DECISION #CODE('a');
(#CODE('1')) : TASK ...;
(#CODE('2')) : TASK ...;
ENDDECISION;

In this case the sort of the decision cannot be resolved. To overcome this problem the question could be written as

DECISION TYPE integer #CODE('a');

Names and Prefixes in Generated Code

When an SDL name is translated to an identifier in C, a prefix is normally added to the name given in SDL. This prefix is used to prevent name conflicts in the generated code, as SDL has other scope rules than C and also allow different objects defined in the same scope to have the same name, if the objects are of different entity classes. It is, for example, allowed in SDL to have a sort, a variable and a procedure with the same name defined in a process. So the purpose of the prefixes is to make each translated SDL name to a unique name in the C program.

A generated name for an SDL object contains four parts in the following order:

  1. The character "z"
  2. A sequence of characters that make the name unique. If the object is part of a package, the package name will appear in this sequence.
  3. An underscore "_"
  4. The SDL name stripped from characters not allowed in C identifiers

Sequence of Characters

A C identifier may contain letters, digits, and underscore "_" and must start with a letter.

The sequence of characters that make the name unique is determined by the position of the declaration in structure of declarations in the system:

  • Each declaration on a level is given a number: 0, 1, 2, .., 9, a, b, .., z.
  • If the number of declaration on a level is greater than 36, the sequence is: 00, 10, 20, .., 90, a0, .., z0, 01, 11, 21, .., 91, a1, .., z1, ......, 0z, 1z, 2z, .., 9z, az, .., zz.
  • If the number of declarations is greater than 36 * 36 then three character sequences are used, and so on.

The total sequence making a name unique is now constructed from the "declaration numbers" for the unit and its parents, that is the units in which it is defined, starting from the top.

If, for example, a sort is defined as the 5th declaration in a block that in turn is the 12th declaration in the system, then the total sequence will be b4 (if not more than 36 declarations are present on any of the two levels).

Example 383 : Generated Names in Code

Examples of generated names:

SDL Name | Position of the Declaration | Generated Name
S1 | 10th declaration in the system | z9_S1
Var2 | 3rd declaration in the process, which is the 5th declaration in the block, which is the 15th declaration is system | ze42_Var2

There will also be other generated names using the prefixes. If, for example, a sort MySort is translated to za2c_MySort, then the equal function connected to this type (if it exists) will be called yEq_za2c_MySort.

Prefixes

Note:

If the OO diagram types in SDL-92 are used (system type, block type, process type), full prefix should always be used, as the OO concepts in itself most likely mean the name conflicts will be introduced in C.

This strategy for naming objects in the generated code should be used in all normal situations, as it guarantees that no name conflicts occur. The Cadvanced/Cbasic SDL to C Compiler offers, however, possibilities to change this strategy. In the Make dialog in the Organizer (see "Make" ) and in the user interface an Analyzer running stand-alone (see "The Analyzer Command-Line UI" ), it is possible to select one of the following strategies: full prefix, entity class prefix, no prefix, or special prefix. Full prefix is default and is the strategy described above.

Entity Class Prefix

If entity class prefix is selected, then the prefix that is concatenated with the SDL name will be in accordance with the table below and depends only of the entity class of the object.

Entity class
Prefix
Entity class
Prefix
Block, block type, block instance

 blo
Process, Process type, Process instance

 prs
Block substructure

 bls
Remote procedure

 rpc
Channel

 cha
Remote variable

 imp
Channel substructure

 chs
Service, Service type, Service instance

 ser
Connection

 con
Signal

 sig
Formal parameter

 for
Signal list

 sil
Gate

 gat
Signal route

 sir
Generator

 gen
Sort = Newtype

 sor
Import

 imp
State

 sta
Label

 lab
Syntype

 syt
Literal

 lit
Synonym

 syo
Operator

 ope
System, System type

 sys
Package

 pac
Timer

 tim
Predef

 pre
Variable

 var
Procedure

 prd
View

 vie

Using entity class prefix means that the user must guarantee that no name conflict occurs. It also means, however, that the generated names are predictable and thus simplifies writing C code where the SDL names are used. It is only necessary to look for name conflicts within entity classes, for example not having two sorts with the same name. The entity class prefixes handle the case when two objects of different entity class have the same name. Note that the table above contains all entity classes. Not all of the items are actually used by the code generator.

No Prefix

The third alternative, no prefix, means of course that no prefixes are added to the SDL name. The name in the C program will then be the SDL name stripped form characters that are not allowed in C identifiers (everything except letters, digits, and underscore). In this case, the user must guarantee that no name conflict occurs and that the stripped name is allowed as a C identifier, that is, that it begins with a letter.

Special Prefix

In the fourth alternative, special prefix, full prefixes are used for all entity classes except variable, formal parameter, sort, and syntype. For these entity classes no prefix is used.

Conclusion

As was said in the beginning of this subsection, the user should have a good reason for selecting anything but the full prefix, as it could be very difficult to spot name conflicts. The C compiler will in some cases find a conflict, but may in other cases consider the program as legal and generate an executable program with a possibly unwanted behavior. The note above about OO concepts is also a strong argument for full prefix.

Case Sensitivity

Another aspect concerning identifiers is that SDL is case insensitive, while C is case sensitive. The Cadvanced/Cbasic SDL to C Compiler has two translation schemes for identifiers, one is to use the capitalization used in the declaration of the object of concern (default), and one is to use lower case identifiers. The translation scheme is selected in the Make dialog in the Organizer (see "Make" ) or in the user interface of the Analyzer, when it is executed stand-alone ("The Analyzer Command-Line UI" ).

Specifying Names in Generated Code
- Directive #NAME

If you wish to decide the name of an object in generated code yourself you can use the #NAME directive. Place the directive directly after the name in the declaration of the object. It should contain the desired name to be used in the generated code within quotes.

Example 384 : #NAME Directive

NEWTYPE S /*#NAME 'S' */ STRUCT
a integer;
b Boolean;
ADDING OPERATORS
Op /*#NAME 'OtherName' */ :
S, S -> Boolean;
ENDNEWTYPE;

The name defined in a #NAME directive will be used everywhere that the SDL name is used in the generated code, with two exceptions:

  • In the monitor system the SDL names will be used in the communication with the user.
  • The name of the files for generated code are not affected by the usage of #NAME directives.

There are, however, some restrictions on where #NAME directives can be placed. Some objects in, for example, a block type are generated in each instantiation of the block type. If a name directive is placed at such an object, the name will probably be overloaded in C, resulting in a C compilation error. The sensitive objects are processes, process instantiations, signal routes, channels, remote variables, and remote procedures.

Assigning Priorities - Directive #PRIO

Priorities can be assigned to processes and process instantiations using the directive #PRIO. The process priorities will affect the scheduling of processes in the ready queue, see "Time" . A priority is a positive integer, where low value means high priority. #PRIO directives can be placed directly after the process heading in the definition of the actual process or last in the reference symbol (in SDL/GR).

Example 385 : #PRIO Directive in process headings .

Process P1; /*#PRIO 3 */
Process P2(1,1); /*#PRIO 5 */

Process P3 : P3Type; /*#PRIO 3 */
Process P4(1,1) : P4Type; /*#PRIO 5 */

Processes that do not contain any priority directive will have the default priority 100.

Initialization - Directive #MAIN

The #MAIN directive is used to include initialization code that should be executed before any process transitions are started. The directive should be placed in the system definition directly after the system heading.

Example 386 : #MAIN Directive

System S;
/*#MAIN
C code for initialization */

The #MAIN directive has exactly the same structure as the #CODE directive for including code in tasks. The included code will, however, be placed last in the yInit function, after the initialization of the internal structure, but before any transitions are executed.

Modifying Outputs - Directive #EXTSIG, #ALT, #TRANSFER

The purpose of these directives is to modify the standard behavior of an SDL output. The #EXTSIG directive can be used to build applications with the SDL suite run-time library. The directives #ALT and #TRANSFER are only useful together with other real-time operating systems.

The directive #EXTSIG is used to replace the code for an SDL output with any appropriate in-line C code. This is an optimization and an alternative to the OutEnv function (see 57 Building an Application). The #EXTSIG directive can be specified:

  • Last in an output symbol (in PR just before the `;').
  • Just before the `,' or `;' ending the definition of a signal.

In the first case the #EXTSIG is valid for the signal(s) sent in the output symbol, and in the second case for all outputs of the defined signal.

Example 387 : #EXTSIG Directive

signal
Signal1 /*#EXTSIG */,
Signal2(integer) /*#EXTSIG */;

output Signal3 To Sender /*#EXTSIG */;

For each output of a signal with a #EXTSIG directive (in either way described above) the following code is generated:

#ifndef EXT_SignalName
"the normal implementation of an output"
#else
EXT_SignalName(
SignalName, ySigN_SignalNameWithPrefix,
ToExpression, SignalParameters)
#endif

where SignalName is the name of the signal in SDL. The parameter ToExpression is a translated version of the SDL expression after TO in the output. If no TO expression is given in the output, this parameter will be xNotDefPId. The entry SignalParameters will be replaced by the list of signal parameter values given in the output.

The intention of this code is to give the user the possibility of introducing a macro with the same name as the signal, where the implementation of the output is expanded to in-line code. By just having a compilation switch which selects if this macro is visible or not, the same generated code can be used both for simulation and for highly optimized applications. An appropriate switch is probably XENV, which governs the normal way of connecting an SDL system to the environment.

Example 388 : #CODE Directive

The following #CODE directive can be included in a text symbol in the system diagram (assuming a signal called SigName with one parameter).

/*#CODE
#TYPE
#ifdef XENV
#define EXT_SigName(Name, IdNode, ToExpr, Param1) \
suitable macro code
#endif
*/

The other two directives, #ALT and #TRANSFER, can be used together with appropriate real-time operating systems, to have two different interpretations of an output (internal or external output for example) and to specify that a received signal should be immediately retransmitted (#TRANSFER). These kinds of features are not uncommon in real-time operating systems, and can be modeled and simulated by the Cadvanced/Cbasic SDL to C Compiler using these directives. Both these directives should be placed last in the output symbol.

The presence of an #ALT directive will be reflected in the generated code in the way described below.

  • If no directive is used, the following macros will be present in generated code for sending a signal:
    • SDL_2OUTPUT: used when the receiver is known.
    • SDL_2OUTPUT_NO_TO: used when the receiver has to be calculated during runtime.
    • SDL_2OUTPUT_COMPUTED_TO: used when the receiver is calculated during code generation.
  • If an #ALT directive is given these macros are replaced by:
    • SDL_ALT2OUTPUT
    • SDL_ALT2OUTPUT_NO_TO
    • SDL_ALT2OUTPUT_COMPUTED_TO

In the Master Library, the macros with and without ALT are expanded identically. In an OS integration they might be handled differently to implement two classes of signal sending.

The presence of a #TRANSFER directive indicates that a signal should be directly retransmitted to some other receiver. This can of course be performed in SDL by an input-output, but then it is necessary to create a new signal and copy the contents of the received signal to the new signal. Using the #TRANSFER directive this copying can be avoided.

In generated code the macros

  • ALLOC_SIGNAL
  • ALLOC_SIGNAL_PAR

are generated to allocate the data area for a new signal. If a #TRANSFER directive is present in the output statement, these macros are replaced by:

  • TRANSFER_SIGNAL
  • TRANSFER_SIGNAL_PAR

Note:

In the master library #TRANSFER will still be implemented as a signal copy. It may be possible in an OS integration to avoid the copying if the OS supports such actions.

Normally the #TRANSFER directive should be used in the following way:

INPUT signal1(,,,);
OUTPUT signal1(,,,) /*#TRANSFER*/;

That is, receive none of the signal parameters in the input and retransmit the signal unchanged. If you want to receive, for example, the second parameter (in variable Var1) and retransmit the signal unchanged except for parameter 3, that should have a new value (73), the following code can be used:

INPUT signal1(,Var1,,);
OUTPUT signal1(,,73,) /*#TRANSFER*/;

Linking with Other Object Files
- Directive #WITH

Note:

This feature is only valid for SDL/PR as input, when the Analyzer is executed stand-alone. Similar features are available in the Organizer's Make dialog among the Generate makefile options, see "Generate makefile" .

You can tell the Cadvanced/Cbasic SDL to C Compiler that a number of user defined and precompiled units should be linked together with a generated simulation program. You do this in a #WITH directive that should be placed in the system definition directly after the system heading.

Example 389 : #WITH Directive

System S; /*#WITH 'file1.o' 'file2.o' */

Within the #WITH directive the object files that are to be part in the link operation should be given between quotes, as in the example above. These files will be included in the definition of the link operation in the generated .m file.

The make file will, however, not include any definition of how to compile the corresponding source files, as it is impossible for the code generator to know the compilation options or even what compiler the user wants. A user that knows how to interface routines in other languages in a C program, can with this knowledge and the #WITH directive link modules written in another language together with the generated program.

Note:

The #WITH directive will only affect the generated make file. There will be no change in the generated C code when a #WITH directive is introduced.

Naming Tasks in Trace Output - Directive #ID

To simplify the identification of a TASK in a trace printout, the Cadvanced/Cbasic SDL to C Compiler uses the variable on the left hand side of the first assignment statement or the first informal text in the task symbol. A user that is not satisfied with this can name the tasks using #ID directives. An ID directive should contain the character string that is to be used as identification in trace printouts.

Example 390 : #ID Directive

/*#ID 'Identification of task' */

The code generator will use the first ID directive it finds in a TASK (if any). An ID directive may be placed:

  • First in the task (in PR that is just after the keyword TASK)
  • Immediately before or just after a comma separating two assignments or two informal texts
  • Last in a task (in PR that is just before the semicolon)
  • Directly after the semicolon (this position is only available in SDL/PR).

Directive #C, #SYNT, #SYNTNN, #ASN1

These directives are used to pass information from the tools generating SDL from other languages, for example for C (a .h file) or ASN.1.

The #C and the #ASN.1 directive will be inserted after the semicolon ending the package definition or after the package name.

package asn1_module; /*#ASN.1 `Module_Name' */
package asn1_module /*#ASN.1 `Module_Name' */;

The #ASN.1 directive contains the ASN.1 module name and the #C directive contains the name of the originating .h file.

The #SYNT directive and its special form the #SYNTNN directive are used in a package generated from C, to indicate which SDL sorts that are synthesized, i.e. which sorts that where needed in SDL but do not have a name and definition in C. As the originating .h file is included in the generated code (with a #include), no typedefs should be generated for the non-#SYNT sorts, while typedefs have to be generated for the synthesized sorts. The #SYNT directive is inserted directly after the name of the newtype or syntype.

Alternative Implementations of the String Generator - Directive #STRING

An instantiation of the string generator can be translated to either a linked list or an array when implemented in C. The #STRING directive is used to determine which translation method to select. The directive should be inserted in a NEWTYPE definition, directly after the string name, when defining a new string data type.

If the #STRING directive is not included in the NEWTYPE definition, the string is implemented as a linked list. This is the default translation method. However, just adding the directive to the NEWTYPE definition is not enough to implement the string as an array. The length of the array must also be defined. This can be done either by using a directive parameter or by using a size constraint in the NEWTYPE definition of the string generator. How this is done is presented in the examples below.

Linked List Implementations

The following examples show how to translate an instantiation of the string generator to a linked list.

Example 391 : No #STRING Directive

NEWTYPE Example_String
string(integer, empty)
constants size (0:10)
ENDNEWTYPE;

If the #STRING directive is missing from the NEWTYPE definition, the string will be implemented as a linked list. The length of the list is unlimited, unless a size constraints is defined. In this case the length of the string is within the range of 0 and 10.

Example 392 : #STRING Directive without Limited String Size

NEWTYPE Example_String /*#STRING */
string(integer, empty)
ENDNEWTYPE;

In this example the string is also implemented as a linked list. The reason for this is that we have not defined a maximum length of the string.

Example 393 : #STRING Directive with Parameter Value 0

NEWTYPE Example_String /*#STRING 0*/
string(integer, empty)
constants size (0:10)
ENDNEWTYPE;

If the parameter value of the #STRING directive is 0, the directive is ignored. Therefore the string will be implemented as a linked list. The size constant will still decide the length of the string.

This example, however, shows how to gradually migrate from a linked list implementation to an array implementation. By just changing the parameter value to anything larger than 0, this NEWTYPE definition creates an array implementation.

Array Implementations

The following examples show how to translate an instantiation of the string generator to an array.

Example 394 : #STRING Directive with Limited String Size

NEWTYPE Example_String /*#STRING */
string(integer, empty)
constants size (0:10)
ENDNEWTYPE;

In this case the string is implemented as an array with the maximum length of 10.

Example 395 : #STRING Directive with Parameter Value

NEWTYPE Example_String /*#STRING 100*/
string(integer, empty)
constants size (0:10)
ENDNEWTYPE;

In this example the string will be implemented as an array with the length of 100. The parameter value in the #STRING directive overrides the size constant, which in this case is redundant.

Size constraint

The size constraint is decided by adding a constant in the NEWTYPE definition. The following declarations are valid when defining a maximum size of the string:

constants size (a:b)
constants size (a)
constants size (=a)
constants size (<a)
constants size (<=a)

Differences between the Implementations Methods

The different implementation methods affect the behavior and performance of the generated code. The following general statements apply to the methods:

  • The performance of the array implementation is usually better than that of the linked list implementation.
  • If the number of string values are equal to or close to the maximum string length, the array implementation is smaller.
  • If the number of string values are substantially smaller than the maximum string length, the linked list requires less memory.
  • The linked list requires memory allocation, while the array does not.

Selecting implementation Methods

It is of course hard to advice which method to select, but the following recommendations apply:

  • If the string size is not known, use the linked list.
  • If the number of string values is substantially smaller than the maximum string length, use the linked list if speed is not very important.
  • If the maximum length is not large or the number of string values are almost equal to the maximum length, use the array.


Using Cadvanced/Cbasic SDL to C Compiler to Generate C++

General

The C code in the Master Library and the C code generated by the Cadvanced/Cbasic SDL to C Compiler is in the common subset of C and C++, and will thus compile both as a C program and as a C++ program. There is one special feature in the code generator concerning C++ when it comes to abstract data types and the possibility to match a C++ class and an SDL data type. Otherwise all the features for including C code, directive #ADT, directive #CODE (see "Abstract Data Types" and "Accessing SDL Names in C Code - Directive #SDL" ), and so on, are directly applicable for C++ as well. The #CODE directives make it possible to include class definitions as C++ code and the utilization of the classes as C++ code in SDL tasks.

Example 396 : Using C++ Classes

CODE directive containing declarations (see "Including C Declarations - Directive #CODE" ) which should be placed among the SDL declarations:

/*#CODE
#HEADING
class TEST {
public:
void putvar(int avar, int bvar)
{a = avar; b = bvar;}
int geta()
{return a;}
int getb()
{return b;}
private:
int a,b;
} TESTvar;
*/

Example of usage of the class in a CODE directive in a TASK (see "Including C Code in Task - Directive #CODE" ).

TASK '' /*#CODE
TESTvar.putvar(#(I), #(I)+10); */;

Example of usage of the class in a CODE operators in expressions (see "Including C Code in SDL Expressions - Operator #CODE" ).

OUTPUT Score(
#CODE('TESTvar.geta()'),
#CODE('TESTvar.getb()'),
#CODE('#(TClass)->getVar()')
);

Connection Between C++ Classes and SDL

To obtain a close connection between a C++ class and SDL, an abstract data type in SDL can be used; see below.

If you have a C++ class (from a class library or developed specifically for the project), then the following correspondence rules can be used to map the class on an abstract data type.

C++ | SDL
Class definition | Abstract data type definition
Class instance pointer | Process variable
Member functions | Operators
new, delete | Operators

Example 397 : SDL and C++ Class

Suppose we have a C++ class with the following interface (.h file):

class TestClass {
public :
TestClass (int);
TestClass ();
~TestClass ();
int updateVar(int);
int getVar();
private :
int v;
};

then the following abstract data type can be used to represent the class (in the example the NAME directive, see "Specifying Names in Generated Code - Directive #NAME" , is used to instruct the Cadvanced/Cbasic SDL to C Compiler which name to use in C for particular SDL objects):

NEWTYPE TestClass /*#NAME 'TestClassPtr' */

LITERALS
newTestClass /*#NAME 'new1TestClass' */
;

OPERATORS
newTestClass /*#NAME 'new2TestClass' */
: integer -> TestClass;

deleteTestClass /*#NAME 'deleteTestClass' */
: TestClass -> TestClass;

updateVar /*#NAME 'updateVar' */
: TestClass, integer -> integer; /*#OP(HC) */

getVar /*#NAME 'getVar' */
: TestClass -> integer; /*#OP(HC) */

/*#ADT(T A(S) E(S) D(H) H P)

#TYPE
#include "TestClass.h"
typedef TestClass * TestClassPtr;
COMMENT((NOTE! SDL data type TestClass is
pointer to C++ class TestClass))

#HEADING
#define yDef_TestClassPtr(p) *(p) = 0
#define new1TestClass() new TestClass()
#define new2TestClass(P) new TestClass(P)

extern TestClassPtr deleteTestClass
(TestClassPtr);

#BODY
extern TestClassPtr deleteTestClass
(TestClassPtr P)
{
delete P;
return (TestClassPtr)0;
}
*/
ENDNEWTYPE;

Note that the #ADT specification means that no code will be generated for the abstract data type. The abstract data type can utilized in the following way:

DCL
TClass TestClass,
I Integer;

TASK TClass := newTestClass;
TASK TClass := newTestClass(2);
TASK I := updateVar(TClass, I);
TASK I := getVar(TClass);
TASK TClass := deleteTestClass(TClass);

The only feature that is not described before is the C option in the #OP directive. C (class) is an alternative to I (infix) and P (prefix), and specifies that the operator call should be translated to a member function call of a C++ member function. #OP(C) means that an operator call

F(a, b, c)

is translated to

a->F(b, c)

Note:

This means that each operator mapped on class member function should have the class instance pointer as first parameter.


Restrictions

SDL Restrictions

The Cadvanced/Cbasic SDL to C Compiler handles the majority of SDL concepts according to the definition of SDL-92. There are however a number of restrictions that are discussed in this section.

Analyzer Restrictions

The restrictions in the SDL Analyzer are, of course, also valid in the Cadvanced/Cbasic SDL to C Compiler. For more information see "SDL Analyzer.

Cadvanced/Cbasic SDL to C Compiler Restrictions

The Cadvanced/Cbasic SDL to C Compiler introduces more severe restrictions on the allowed set of SDL concepts than the Analyzer. For more information, see "SDL to C Compiler.


Migration Guide for Generic Functions

General

This section provides help to migrate a system using old-style code generation for operators to the new Generic Function style.

Introduction

The basic idea of the generic function approach is to decrease the number of generated help functions and functions for operators in predefined generators. This is accomplished by generating generic functions that can be re-used by different types.

This means, for instance, that only one assignment function is created. This function, however, can be used by all types. In the old-style method, one assignment function was created for each type. For operators in predefined generators, there is now one single length function calculating the length of all string generator instantiations.

In order to implement the generic functions, the parameter passing mechanisms have been changed. In principle, a generic function cannot take a value as parameter, it must receive a pointer to the value. This approach has a positive effect on the performance. However, the generic function approach introduces incompatibility problems if your existing system calls generated functions from inline C-code. If this is the case, the function calls must be changed.

If you need to migrate an SDL system created with the old-style code generation, you must solve the incompatibility issue.

References to Information

Generic Functions

The major source of information regarding generic functions is "Abstract Data Types" , which contains a number of sections discussing different aspects of data types and operators:

  • "Translation of Sorts" describes how different SDL types are translated to C.
  • "Parameter Passing to Operators" discusses the general parameter passing principles for operators and literal functions. This section also lists which types that are passed as values and which types that are passed as addresses.
  • "Implementation of User Defined Operators" describes how to include your own implementation in C for an operator.
  • "Generic Functions" introduces you to the type info node concept and describes the general operators assign, equal, free, etc.
  • "Generic Function for Operators in Pre-defined Generators" describes the operators in the predefined generators.
  • "More about Abstract Data Types" comprises information on how to change the implementation of a data type.

SDL Data Types

Information on SDL data types and operators, seen from the SDL point of view, is available in "Using SDL Data Types. Although this section does not discuss the use of generic functions, it provides the framework for SDL data types and operators. In some circumstances it might be better to rewrite a data type or operator in SDL, than to fix the problems in C. A number of extensions and improvements have been included in the support for data types.

Type Info Nodes

For more information on the contents of the type info nodes, please see "Type Info Nodes. This section does not cover migration aspects, but provides implementation details for an interested reader.

Migrating Strategy

Overview

The common problems that might occur when migrating a system from the old-style operator implementation to the generic functions implementation can be divided into two groups:

  • Some user-defined SDL operators have changed their prototypes in C. This means that user-provided implementations of the operators have to be changed and that calls to such operators directly from C have to be changed.
  • Predefined operators like assignment, equal test, make, and so on, as well as operators in predefined generators might have changed their prototypes in C, which means that calls to such operators directly in C have to be changed. Also types where the implementation of assignment, equal and similar operators are changed by a #ADT directive, might have to be updated.

The first of these problems is fairly straight forward to fix, while the second might be more complex.

Step 1: Identifying Migration Problems

Before continuing with the migration instructions, check if your SDL systems are affected by any incompatibility problems.

  1. Find an SDL system that compiles without errors in a previous version of the SDL suite (with the old-style operator implementations)
  2. Open it in the 4.4 version of Telelogic Tau.
  3. Compile it and see if you get any compilations errors.

If your compilation errors are similar to the errors in Example 398 you can assume that you have a migration problem.

Example 398 : Compilation Errors

The compilation error in this example originates from the GNU compiler, gcc. It gives a fairly good feeling of what kind of errors you can expect.

file.c:50825: conflicting types for `yAss_example'
file.c:50844: conflicting types for `yEq_example'
file.c:51496: conflicting types for `op1'
file.c:211376: too many arguments to function `op1'
file.c:211376: cannot convert to a pointer type
file.c:6042: incompatible type for argument 2 of `GenericAssignSort'
file.c:6081: incompatible type for argument 2 of `op1'

Step 2: Locating the Compatibility Problems

Note:

Before you try to investigate and correct any error from the list of C compilation errors, you should perform this step. The reason is that many of the errors will point at the wrong place so correcting them might introduce errors rather than correcting anything.

The Cadvanced, Cbasic, and Cmicro SDL to C compilers allows you to find the operators and literals that should be updated. By setting the environment variable SDT_COMP_WARN the code generators will produce a file called compatibility.warn in the target directory, while generating code for the system. In the first section of this file all operators and literals that might have to be changed are listed.

Example 399 : Contents of compatibility.warn

LITERAL NewDb C-name: z0V0_NewDb
<<SYSTEM accesscontrolooa>>
#SDTREF(TEXT,file.sdl,57,12)
Literal function result passed as address

OPERATOR ValidateCard C-name: z0V1_ValidateCard
<<SYSTEM accesscontrolooa/TYPE CardDbType>>
#SDTREF(TEXT,file.sdl,59,5)
Parameter 2 passed as address
Used in DIRECTIVE at #SDTREF(TEXT,file.sdl,62)
Used in DIRECTIVE at #SDTREF(TEXT,file.sdl,62)

This example shows one literal and one operator that have to be updated:

  • The first line contains the name of the operator/literal in SDL and in C.
  • The second line contains an appropriate qualifier, that gives information on where in the system the item is defined.
  • The third line is the SDT reference to the operator/literal. This can be used in the Organizer's Goto Source feature to show where the SDL source is located.
  • The following lines indicate where changes are needed. Each line states that the result or a parameter is passed as an address. This means that previously this item was passed as a value, but now it should be passed as an address. A complete list of types that must be changed can be found in "Mapping Table" .
  • Last, a number of cross references might be found. These show places where the operator is called from inline C using an #SDL directive. These calls might have to be updated.

Step 3: Updating Operators and Literals

For each operator or literal that is listed in the file compatibility.warn, perform the instructions presented in this section.

Note:

Literals should be treated as operators without parameters.

Updating the Headers

The headers of the corresponding C functions must be updated. If you have specified #OP(B), the header is generated and thus already correct, but if you have specified #OP(H), you have included the header in C probably in the #HEADING section in the #ADT directive for the type.

  1. For each parameter that should be passed as an address, add a `*' after the corresponding type name in C.
  2. If the result should be passed as an address, add a `*' after the result type in C, and add an extra parameter with the same C type as the updated function result, last among the parameters.

When this step has been performed for all types, the C compilation errors will be reliable again.

Example 400 : Headers

extern str lit1 (void);
extern str op1 (str, SDL_Integer);

Assume str is the type that should be passed as an address. The results of both functions and the first parameter of op1 are mentioned in the compatibility.warn file. The heading should be updated to:

extern str* lit1 (str*);
extern str* op1 (str*, SDL_Integer, str*);

Updating Parameter Specifications

The parameter specification and result in the function implementation must be updated to match the heading. The function implementation is probably in the #BODY section in the #ADT directive of the type.

Example 401 : Parameter Specifications (continued from Example 400)

str lit1 (void)
{ .... }
str op1 (str P1, SDL_Integer P2)
{ .... }

should be changed to:

str* lit1 (str* Result)
{ .... }
str* op1 (str* P1, SDL_Integer P2, str* Result);
{ .... }

Updating Operator/Literal Functions

The implementation of the operator/literal functions must be updated to reflect the change in parameters.

Example 402 : Operator/Literal Functions (continued from Example 401)

In the function op1 every occurrence of:

P1 should be replaced by (*P1)

Special cases where other changes might be more appropriate:

&P1 should be replaced by P1
P1.abc should be replaced by P1->abc

The new Result parameter must be assigned the result value of the function and the function must end with a return statement.

Example 403 : Return Parameter

return Result;

It is not unusual that the function contains a local variable used for calculating the result. Normally this variable is no longer needed.

While updating the implementation of the function, information from the next section on, for example, assign and equal function might be valuable.

Note:

Check that parameters that are passed as addresses are NOT CHANGED within the function. If that is the case, copy the value to a local variable first, and work with that variable.

Update Calls to Functions

The calls to the changed functions must be updated. Calls made from SDL cause no problems as the SDL compilers produce the correct code. Only calls made directly from inline C code may have to be updated. The operator list in the file compatibility.warn contains cross-references to the inline C code where the operator is called using an #SDL directive.

Note:

Operator calls in C without the #SDL directive, are not listed in compatibility.warn. These calls can only be found via the compiler error list.

For parameters that has changed parameter passing mechanism from pass as value to pass as address you should perform one of the following tasks:

  • If the actual parameter is a variable (or something it is possible to take the address of), add a `&', before the variable.
  • If the actual parameter is a call to a function, then probably this function has changed its prototype so that it now returns an address. In that case nothing needs to be performed. In other cases proceed to the next possibility.
  • If none of the situation above is appropriate, insert a new function local variable of the parameter type, assign the value of the actual parameter to this variable, and insert the address of the variable as actual parameter.

Implementation Hint

Note:

The following information is not required for the migration of the system, but can be used to improve the performance of the system.

When updating the operators, it might be worth investigating the available features in the SDL suite, including extensions for operators, in/out parameters, no parameters, no result, etc.

One not too uncommon situation is when a value is passed as an in parameter, then changed by the operator and returned as result value. In every operator call, the same variable is used as both the actual parameter and the receiver of the result. To improve speed of the application, the operator, could be changed to an operator without result and using in/out parameters.

If you perform a change like this, remember to use the cross-reference tool to find all places where the operator is used.

Step 4: Updating typedefs

Overview

Another area where backward incompatibility problems might be present is when the typedef is changed in an #ADT directive, especially if the assign, equal, or free functions are changed as well. In the second section of the file compatibility.warn all types changing the typedef and at least one of assign, equal, or free functions are listed.

Example 404 : Typedef Change

NEWTYPE example C-name:zDZ_example
<<SYSTEM mysystem>>
#SDTREF(TEXT,file.sdl,3096,9)
Pass as Value #ADT(T(B)A(B)E(B)F(B))

The example should be interpreted like this:

  • The first line contains the name of the newtype in SDL and in C.
  • The second line contains an appropriate qualifier that gives information on where in the system the newtype is defined.
  • The third line is the SDT reference to the newtype. This can be used in the Organizer's "goto source" feature to locate the SDL source code.
  • The fourth line contains either "Pass as Value" or "Pass as Address", depending on the property of the newtype, followed by the interpretation of the #ADT directive.

As the #ADT directive can be used in many different ways, it is impossible to describe a general method how to correct any problems. The type list in the compatibility.warn file indicates what newtypes that have highest probability to cause problems. It is recommended that you go through the listed newtypes and review them given the information in the following sections.

You also have to find and in some cases correct the places where the functions discussed below are called. The compiler error list is the main source of information for this task. Please see "Locating Source Code" if you have problems locating the corresponding SDL source listed in a C compilation error message.

Assignment Functions

For all types passed as addresses, the differences between the old-style, and the new generic assignment functions are:

  • The old functions pass the value of the right-hand side expression as the second parameter, while the new pass the address of the right-hand side expression.
  • The old functions returns void, but the generic functions return the first parameter, i.e. the address of variable.
  • It is now required that the assignment function must be a function (it cannot be a macro), as the address of the function is stored in the type info node for the newtype.

Example 405 : The Assignment Function

The prototype for an old assign function would be:

void yAss_typename (typename*, typename, int)

The prototype for a new assign function should be:

typename* yAss_typename (typename*, typename*, int)

The body of the assignment function must be updated for these changes.

If assignment for a type passed as an address is used in inline C code, one of the following tasks must be performed:

  • If the expression parameter is a variable, a `&', should be added before the variable.
  • If the expression is an SDL operator call, a change is normally not needed, as the operator in the generic function model will return the address of a value, not the value itself (for types passed as address).
  • You might want to add (void) before the yAss call to tell the compiler that you want to ignore the result.

For more information please see "Generic Assignment Functions" .

Equal Functions

For all types passed as addresses, the differences between the old and the new generic equal functions are:

  • The old functions pass the values of the two expression, while the new generic equal functions pass the addresses of the expressions.
  • It is now required that the equal function must be a function (it cannot be a macro), as the address of the function is stored in the type info node for the newtype.

Example 406 : The Equal Function

The prototype for an old equal function would be:

SDL_Boolean yEq_typename (typename, typename)

The prototype for a new equal function should be:

SDL_Boolean yEq_typename (typename*, typename*)

The body of the equal function must be updated for these changes.

If equal for a type passed as an address is used in inline C code, perform the same tasks as presented for the assignment function.

For more information please see "Generic Equal Functions" .

Free Functions

The yFree_typename function is backward compatible. However, it is now required that the equal function must be a function (it cannot be a macro), as the address of the function is stored in the type info node for the newtype.

For more information please see "Generic Free Functions" .

Default Functions

The yDef_typename macro or function from the non-generic mode is no longer used or generated. Initialization of SDL variables are performed as follows:

  • if the variable has an initial value given in the declaration, the variable is assigned this value, using an assignment statement.
  • else if the type of the variable has a default value, the variables are assigned this value, using an assignment statement.
  • else the variable is set to 0 using memset. If 0 is not an appropriate initial value, the function GenericDefault is called to initialize the variable. Examples of types where 0 is not an appropriate value are structs with components with initial values, Object_identifiers, Strings, general Powersets, Bags and general Arrays.

As yDef functions/macros do not exist in Generic mode, all usage in inline C code must be changed. There are several possibilities. First, decide if assigning a default value is really necessary. If it is necessary, then some of the following principle solutions might be used:

  • memset to 0
  • GenericDefault(&variable,
    (tSDLTypeInfo *)&ySDL_typename)
  • yAss_typename(variable, expression,
    XASS_MR_ASS_NF)
  • direct C assignment, if possible

Make Functions

The yMake_typename function from the non-generic mode is no longer used or generated. All calls in inline code to yMake functions must be replaced by calls to proper GenericMake functions as described in "Generic Make Functions" .

Note:

yMake functions pass component values as values, while GenericMake functions pass component values as addresses

Operators in Predefined Generators

The operators in predefined generators have got new generic implementations. All the available generic implementations are listed in "Generic Function for Operators in Pre-defined Generators" . Macros that support the old operators names and translate them to the generic functions are generated. If you get compilation errors in such a call you should compare the call with the macro and the generic function, to see if there are any differences in the parameter passing principle.

Locating Source Code

A typical error message from a C compiler lists a file name, a line number, and a description of the error. To locate the corresponding SDL source code perform the following:

  1. In a text editor, open the file that is listed in the error message
  2. Go to the given line number.
  3. Search upwards for an SDT reference, that is, a C comment starting with:
/*#SDTREF(

Copy the SDT reference and paste it into the Goto Source feature in the Organizer. The Organizer will show you where the C code originated from.


57 Building an Application

This chapter describes how you can use the Cadvanced SDL to C Compiler to generate applications and especially how to design the environment functions. These functions allows you connect the SDL system with the environment of the system.

You should read 56 The Cadvanced/Cbasic SDL to C Compiler before reading this chapter to understand the general behavior of the Cadvanced SDL to C Compiler. Much of what you need to know to generate an application may be found there, and that information is not repeated here.


Introduction

The Basic Idea

An application generated with the Cadvanced SDL to C Compiler can be viewed as having three parts:

  • The SDL system
  • The physical environment of the system
  • The environment functions, where you connect the SDL system with the environment of the system

In the SDL system process transitions are executed in priority order, signals are sent from one process to another initiating new transitions, timer signals are sent, and so on. These are examples of internal actions that only affect the execution of the SDL system. An SDL system communicates with its environment by sending signals to the environment and by receiving signals from the environment.

The physical environment of an application consists of an operating system, a file system, the hardware, a network of computers, and so on. In this world other actions than just signal sending are required. Examples of actions that an application wants to perform are:

  • To read or to write on a file
  • To send or receive messages over a network
  • To respond on interrupts
  • To read and to write information on hardware ports or on sockets

The environment functions are the place where the two worlds, the SDL system and the physical environment, meet. Here signals sent from the SDL system to the environment can induce all kinds of events in the physical environment, and events in the environment might cause signals to be sent into the SDL system. You have to provide the environment functions, as the Cadvanced SDL to C Compiler has no knowledge of the actions that should be performed.

Figure 490 : Structure of an application

In a distributed system an application might consist of several communicating SDL systems. Each SDL system will become one executable program. It might execute either as an operating system process, communicating with other operating system processes, or it might execute in a processor of its own, communicating over a network with other processors. There may, of course, also be combinations of these cases. Let us for the sake of simplicity call the operating system processes or processors for nodes communicating over a network. In the case of communicating operating system (OS) processes, the network will be the facilities for process communication provided by the OS.

There are no problems in building an application consisting of several nodes communicating over a network using the Cadvanced SDL to C Compiler. However, you have to implement the communication between the nodes in the environment functions.

Note:

All nodes in a network do not need to be programs generated by the Cadvanced SDL to C Compiler from SDL systems. As long as a node can communicate with other nodes, it might be implemented using any technique.

The PId values (references to process instances), are a problem in a distributed world containing several communicating SDL systems. We still want, for example, "Output To Sender" to work, even if Sender refers to a process instance in another SDL system. To cope with this kind of problem, a global node number has been introduced as a component in a PId value. The global node number, which is a unique integer value assigned to each node, identifies the node where the current process instance resides, while the other component in the PId value is a local identification of the process instance within the node (SDL system).

The partitioning of an application into an SDL system and the environment functions has additional advantages. It separates external actions into the logical decision to perform the action (the decision to send a signal to the environment) and the implementation details of the action (treating the signal in the environment functions). This kind of separation reduces the complexity of the problem and allows separate testing. It also allows parallel development of the logic (the SDL system) and the interface towards the environment (the environment functions). When the signal interface between the SDL system and its environment is settled, it is possible to continue both the activities in parallel.

Libraries

Two libraries, Application and ApplicationDebug, are provided to generate applications. Both use real time (see "Time" and perform calls to environment functions (see section "The Environment Functions" ). The difference is that ApplicationDebug includes the monitor system while Application does not include the monitor system.

When an application is developed, it is usually appropriate to first simulate and debug the SDL system or systems without its environment. One of the libraries Simulation or RealTimeSimulation may then be used. You first simulate each SDL system on its own and can then simulate the systems together (if you have communicating systems) using the facility of communicating simulations. After that you probably want to debug the application with the environment functions. This may be performed with the library ApplicationDebug. You may then generate the application with the library Application.

The library Validation allows you to build validators from the code generated by the Cadvanced SDL to C Compiler. A Validator has a user interface and executing principles that are similar to a Simulator. The technical approach is however different; a Validator is based on a technique called state space exploration and operates on structures called behavior trees. Its purpose is to validate an SDL system in order to find errors and to verify its consistency against Message Sequence Charts.


Reference Section

Representation of Signals and Processes

In this first section, the representation of signals and processes is presented. The symbol table, which is a representation of the static structure of the system, will also be discussed. The information given here will be used in the next part of this section where the environment functions, which should be provided by the user, are described.

Types Representing Signals

A signal is represented by a C struct containing general information about the signal followed by the parameters carried by the signal.

Figure 491 : Data structure representing a signal

A general typedef xSignalRec for a signal without parameters and for a pointer to such a signal, xSignalNode, are given below. These types may be found in the file scttypes.h. These types may be used for type casting of any signal to access the general components.

typedef struct xSignalRec *xSignalNode;
typedef struct xSignalRec {
xSignalNode Pre;
xSignalNode Suc;
SDL_PId Receiver;
SDL_PId Sender;
xIdNode NameNode;
int Prio;
} xSignalRec;

A xSignalRec contains the following components:

  • Pre and Suc. These components are used to link the signal in the input port list of the receiving process instance. The input port is implemented as a double linked list. When a signal has been consumed and the information contained in the signal is no longer needed, the signal will be returned to an avail list to be re-used in future outputs. The component Suc is used to link the signal into the avail list, while Pre will be (xSignalNode)0 as long as the signal is in the avail list.
  • Receiver. The receiving process instance.
  • Sender. The sending process instance.
  • NameNode. This component is a pointer to the node in the symbol table that represents the signal type. The symbol table is a tree with information about the SDL system and contains, among other things, one node for each signal type that is defined within the SDL system.
  • Prio. This component represents the priority of the signal and is used in connection with continuous signals.

In the generated code there will be types to represent the parameters of the signals according to the following example:

Example 407 : Generated C Code for Signal Definition

Assume the following signal definitions in SDL:

SIGNAL
S1(Integer),
S2,
S3(Integer, Boolean, OwnType);

then the C code below will be generated:

typedef struct {
SIGNAL_VARS
SDL_Integer Param1;
} yPDef_z0f_S1;
typedef yPDef_z0f_S1 *yPDP_z0f_S1;

typedef struct {
SIGNAL_VARS
SDL_Integer Param1;
SDL_Boolean Param2;
z09_OwnType Param3;
} yPDef_z0h_S3;
typedef yPDef_z0h_S3 *yPDP_z0h_S3;

where SIGNAL_VARS is a macro defined in scttypes.h that is expanded to the common components in a signal struct.

For each signal with parameters there are two generated types, a struct type and a pointer type. The struct type contains one component for each parameter in the signal definition and the components will be named Param1, Param2 and so on. The components will be placed in the same order in the struct as the parameters are placed in the signal definition.

Note:

There are no generated types for a signal without parameters.

Types Representing Processes

A PId value is a struct consisting of two components, a global node number, which is an integer (see also "Function xGlobalNodeNumber" and "The Basic Idea" ) and a local PId value, which is a pointer.

typedef xLocalPIdRec *xLocalPIdNode;

typedef struct {
int GlobalNodeNr;
xLocalPIdNode LocalPId;
} SDL_PId;

The global node number identifies the SDL system that the process instance belongs to, while the local PId value identifies the process instance within the system. The local PId pointer value should not be referenced outside the SDL system where it is defined.

By introducing a global node number in the PId values, these values are possible to interpret throughout an application consisting of several SDL systems. You can also define your own PId values in non-SDL defined parts of the application and still use communication with signals.

The variable SDL_NULL, which represents a null value for PIds and which is defined in the runtime library and available through the file scttypes.h, contains zero in both the global node number and the local PId component. Note that the global node number should be greater than zero in all PId values except SDL_NULL.

The Symbol Table

The symbol table is a tree built up during the initialization phase in the execution of the generated program and contains information about the static structure of the SDL system. The symbol table contains, for example, nodes which represent signal types, blocks, channels, process types, and procedures. The C type that are used to represent for example signals in the symbol table is given below.

typedef struct xSignalIdStruct *xSignalIdNode;
typedef struct xSignalIdStruct {
/* components */
} xSignalIdRec;

It is the nodes that represent the signal types, for signals sent to and from the environment of the SDL system, that are of major interest in connection with the environment functions. For each signal type there will be a symbol table node. That node may be referenced using the name ySigN_ followed by the signal name with prefix. Such references may be used in, for example, xOutEnv to find the signal type of the signal passed as parameter.

In some cases the symbol table nodes for channels from the environment to a block in the system are of interest to refer to. In a similar way as for signals such nodes may be referenced using the name yChaN_ followed by the channel name with prefix.

The Environment Functions

An SDL system communicates with its environment by sending signals to the environment and by receiving signals from the environment. As no information about the environment is given in the SDL system, the Cadvanced SDL to C Compiler cannot generate the actions that should be performed when, for instance, a signal is sent to the environment. Instead you have to provide a function that performs this mapping between a signal sent to the environment and the actions that then should be performed. Examples of such actions are writing a bit pattern on a port, sending information over a network to another computer and sending information to another OS process using some OS primitive.

You should provide the following functions to represent the environment of the SDL system:

  • xInitEnv and xCloseEnv, which are called during initialization and termination of the application
  • xOutEnv which should treat signals sent to the environment
  • xInEnv which should treat signals sent into the SDL system from the environment

There are two ways to get a skeleton for the env functions:

  • You can copy the file sctenv.c from the directory
    <installation directory>/sdt/sdtdir/<machine dependent dir>/INCLUDE
    where <machine dependent dir> is for example sunos5sdtdir on SunOS 5, hppasdtdir on HP, and wini386 in Windows. (In Windows, / should be replaced by \ in the path above.)
    This file also contains some trace mechanisms that may be used to trace the execution in a target computer. This trace can, however, only be used if you have the source code for the run-time library (included in the Cadvanced SDL to C Compiler) and can produce a new object library with the appropriate switches.
  • You can generate a skeleton by using the Generate environment functions option in the Make dialog in the Organizer. In very simple cases you might obtain executable env functions by just tuning the macros in this generated file, but in the general case you must use it as a skeleton and edit it. Remember then to copy the file so that it is not overwritten when code is generated the next time.

An advantage with the generated env functions is that the SDL to C Compiler knows about the signal interface to be implemented in the env functions, and can therefore insert code or macros for all signals in the interface. To calculate this information is not that easy, especially if partitioning (generating code for a part of a system) is used.

Note:

A make template file is generated every time you generate an environment file. This file contains make information for the environment file and possibly for data encoding and decoding files. If you need to change this skeleton file, then remember to copy it so it is not overwritten next time an environment file is generated. The file can be used as make template in the Organizer's generate options. Note that you may have to generate the file first, before you can select it in the Organizer.

The env functions are thoroughly discussed below, but first we will introduce the system interface header file which considerably simplifies writing the environment functions.

System Interface Header File

The system interface header file contains code for objects that are defined in the system diagram. Included are all type definitions and other external definitions that are needed in order to implement external C code. These object definitions simplify the implementation of the environment functions. Therefore the system interface header file is also known the environment header file. This file is generated if:

  • Code is generated for the complete system.
  • The Generate environment header file option is selected in the Make dialog in the Organizer (see "Code Generation Options" ).

The default name of the generated interface header file is <system_file_name>.ifc.

The system interface header file, has the following structure:

  • Macros for all synonyms that are translated to macros.
  • All type definitions generated from newtypes and syntypes. This includes #TYPE and #HEADING sections in #ADT directives and in #CODE directives.
  • External definitions of variables for all synonyms that are translated to variables.
  • For each signal defined in the system diagram there will be an extern definition for the xSignalIdRec variable representing the signal.
  • For each signal with parameters defined in the system diagram, there will be definitions of the types yPDef_SignalName and yPDP_SignalName, i.e. of the types used to represent a signal.
  • For each remote procedure (that can be sent to or from the environment), code will be generated exactly as for two signals named pCALL_procedurename and pREPLY_procedurename.
  • For each channel defined in the system diagram there will be extern definitions for the xChannelIdRec representing the channel.

Together with these definitions, macros that simplify the translation of SDL names to C names are also be generated.

Names of SDL Objects in C

Due to differences in naming rules in SDL and C, prefixing is used to make C identifiers unique (see section "Names and Prefixes in Generated Code" ). These prefixes, however, may change when you update your SDL diagrams and cannot be predicted. Therefore you should not use the prefixed object names in the environment functions. Instead macros, generated in the system interface header file, assist you by mapping static names to the prefixed names. This means that you must regenerate the system interface header file each time you regenerate code for the system. The good part is that you do not have to make any changes in the environment functions, as the interface names are static.

Example 408 : Macro in the system interface header file

If an SDL signal called Sig1 is defined in the system, the following macro is created:

extern XCONST struct xSignalIdStruct ySigR_z5_Sig1;
#ifndef Sig1
#define Sig1 (&ySigR_z5_Sig1)
#endif

This macro allows you to refer to the xIdNode by using the static name Sig1 rather than the prefixed name, ySigR_z5_Sig1.

Macros generate static names for the following SDL types:

  • Synonyms (both translated to macros and variables).
  • Newtypes and Syntypes. If the newtype is translated to an enumeration type, all the literals are available directly in C using their SDL names.
  • xSignalIdNode representing signals. (No ySigN_ prefix).
  • xChannelIdNode representing channels. (Use prefix xIN_ or xOUT_ to access the incoming or outgoing direction of the channel).
  • The yPDP_SignalName pointer type. This type may be referred to using the name yPDP_SignalName, where SignalName is the SDL name.

Note:

You must always generate the system interface header file before editing or generating the environment functions.

Avoiding name clashes

In SDL it is allowed to give the same name to different objects. This is not allowed in C. For instance, in SDL you can give a signal and a Newtype the same name. In order to distinguish between the names in the system interface header file, you must define static unambiguous names. Using the Env. Header File Generation tab in the Targeting Expert, you can do this by using available general identifiers. The identifiers are:

  • %n - This identifier is the SDL name
  • %s - This identifier is the SDL name of the scope.
  • sdlobject - In order to identify the type of object, you can type the object name as a prefix, e.g. signal, literal, etc.

Any combination of the identifiers can be used and they are all optional. However, in order to create a useful system interface header file, it is recommended that the %n identifier is always included. Leaving the field empty means that no objects of that type is included in the system interface header file at all.

Note:

If you select to include all objects and use the %n identifier only, the system interface header file will become compatible with earlier versions.

Example 409 : Name Mapping in an system interface header file

If the signal Signal1 is in the system System2 you should type the following in the Signal field in the TAEX.

sig_%n_%s

The result in the system interface header file will be:

sig_Signal1_System2

This approach helps you to avoid name clashes in the ifc file. Literals, for example, are often given the same name when defined in different types. The following example shows how this can be solved.

Example 410 : Avoiding Name Clashes

In an SDL system the following two newtypes are defined:

NewType s
literals red, green

NewType t
literals red, yellow

As the literal red appears in both newtypes, the C code cannot distinguish between them. However, by using the identifiers in the literals field,

lit_%n_%s

the literals are given the following names:

lit_red_s
lit_red_t

Thus we will avoid a possible name clash.

Structure of File for Environment Functions

The file containing the environment functions should have the following structure:

#include "scttypes.h"
#include "file with macros for external synonyms"
#include "systemfilename.ifc"

void xInitEnv XPP((void))
{
}

void xCloseEnv XPP((void))
{
}

#ifndef XNOPROTO
void xOutEnv (xSignalNode *S)
#else
void xOutEnv (S)
xSignalNode *S;
#endif
{
}

#ifndef XNOPROTO
void xInEnv (SDL_Time Time_for_next_event)
#else
void xInEnv (Time_for_next_event)
SDL_Time Time_for_next_event;
#endif
{
}

int xGlobalNodeNumber XPP((void))
{
}

The last function, xGlobalNodeNumber, will be discussed later, see "Function xGlobalNodeNumber" . The usage of the macros XPP and XNOPROTO makes the code possible to compile both with compilers that can handle prototypes and with compilers that cannot. If you do not need this portability, you can reduce the complexity of the function headings somewhat. In the minor examples in the remaining part of this section, only versions with prototypes are shown.

Functions xInitEnv and xCloseEnv

There are two functions among the environment functions that handle initialization and termination of the environment. These functions, as well as the other environment functions, should be provided by the user.

void xInitEnv ( void );

void xCloseEnv ( void );

In the implementation of these functions you can place the appropriate code needed to initialize and terminate the software and the hardware. The function xInitEnv will be called during the start up of the program as first action, while the xCloseEnv will be called in the function SDL_Halt. Calling SDL_Halt is the appropriate way to terminate the program. The easiest way to call SDL_Halt is to include the call in a #CODE directive in a TASK. SDL_Halt is part of the runtime library and has the following definition:

void SDL_Halt ( void );

Note:

xInitEnv will be called before the SDL system is initialized, which means that no references to the SDL system are allowed in this function. To, for example, send signals into the system during the initialization phase, the #MAIN directive should be used (see "Initialization - Directive #MAIN" ). This directive code can be used after the initialization of the SDL system, but before any transitions are executed.

Function xOutEnv

Each time a signal is sent from the SDL system to the environment of the system, the function xOutEnv will be called.

void xOutEnv ( xSignalNode *S );

The xOutEnv function will have the current signal as parameter, so you have all the information contained in the signal at your disposal when you implement the actions that should be performed. The signal contains the signal type, the sending and receiving process instance and the parameters of the signal. For more information about the types used to represent signals and processes, see section "Types Representing Signals" and "Types Representing Processes" .

Note that the parameter of xOutEnv is an address to xSignalNode, that is, an address to a pointer to a struct representing the signal. The reason for this is that the signal that is given as parameter to xOutEnv should be returned to the pool of available memory before return is made from the xOutEnv function. This is made by calling the function xReleaseSignal, which takes an address to an xSignalNode as parameter, returns the signal to the pool of available memory, and assigns 0 to the xSignalNode parameter. Thus, there should be a call

xReleaseSignal(S);

before returning from xOutEnv. The xReleaseSignal function is defined as follows:

void xReleaseSignal ( xSignalNode *S );

In the function xOutEnv you may use the information in the signal that is passed as parameters to the function. First it is usually suitable to determine the signal type of the signal. This is best performed by if statements containing expressions of the following form, assuming the use of the system interface header file and that the signal has the name Sig1 in SDL:

(*S)->NameNode == Sig1

Suitable expressions to reach the Receiver, the Sender, and the signal parameters are:

(*S)->Receiver
(*S)->Sender
((yPDP_Sig1)(*S)) -> Param1
((yPDP_Sig1)(*S)) -> Param2

(and so on)

Sender will always refer to the sending process instance, while Receiver is either a reference to a process in the environment or the value xEnv. xEnv is a PId value that refers to an environment process instance, which is used to represent the general concept of environment, without specifying an explicit process instance in the environment.

Note:

It is not possible to calculate the PId value for a process in the environment, the value has to be taken from an incoming signal (sender or signal parameter). This is the normal procedure in SDL to establish direct communication between two processes in the same SDL system.

Receiver will refer to the process xEnv if the PId expression in an output TO refers to xEnv, or if the signal was sent in an output without a TO clause and the environment was selected as receiver in the scan for receivers.

Remote procedure calls to or from the environment should in the environment functions be treated a two signals, a pCALL_procedurename and a pREPLY_procedurename signal.

Recommended Structure of the xOutEnv Function

You can, of course, write the xOutEnv function as you wish - the structure discussed below may be seen as an example - but also as a guideline of how to design xOutEnv functions.

Example 411 : Structure of xOutEnv Function

void xOutEnv ( xSignalNode *S )
{
if ( (*S)->NameNode == Sig1 ) {
/* perform appropriate actions */
xReleaseSignal(S);
return;
}
if ( (*S)->NameNode == Sig2 ){
/* perform appropriate actions */
xReleaseSignal(S);
return;
}
/* and so on */
}

Function xInEnv

To make it possible to receive signals from the environment and to send them into the SDL system, the user provided function xInEnv is repeatedly called during the execution of the system (see section "Program Structure" ). During such a call you should scan the environment to see if anything has occurred which should trigger a signal to be sent to a process within the SDL system.

void xInEnv (SDL_Time Time_for_next_event);

To implement the sending of a signal into the SDL system, two functions are available: xGetSignal, which is used to obtain a data area suitable to represent the signal, and SDL_Output, which sends the signal to the specified receiver according to the semantic rules of SDL. These functions will be described later in this subsection.

The parameter Time_for_next_event will contain the time for the next event scheduled in the SDL system. The parameter will either be 0, which indicates that there is a transition (or a timer output) that can be executed immediately, or be greater than Now, indicating that the next event is a timer output scheduled at the specified time, or be a very large number, indicating that there is no scheduled action in the system, that is, the system is waiting for an external stimuli. This large value can be found in the variable xSysD.xMaxTime.

You should scan the environment, perform the current outputs, and return as fast as possible if Time has past Time_for_next_event.

If Time has not past Time_for_next_event, you have a choice to either return from the xInEnv function at once and have repeated calls of xInEnv, or stay in the xInEnv until something triggers a signal output (a signal sent to the SDL system) or until Time has past Time_for_next_event.

Note:

We recommend always to return from the xInEnv function as fast as possible to ensure that it will work appropriately together with the monitor (during debugging). Otherwise, the keyboard polling, that is, typing <RETURN> in order to interrupt the execution, will not work.

The function xGetSignal, which is one of the service functions suitable to use when a signal should be sent, returns a pointer to a data area that represents a signal instance of the type specified by the first parameter.

xSignalNode xGetSignal
( xSignalIdNode SType,
SDL_PId Receiver,
SDL_PId Sender );

The components Receiver and Sender in the signal instance will also be given the values of the corresponding parameters.

  • SType. This parameter should be a reference to the symbol table node that represents the current signal type. Using the system interface header file, such a symbol table node may be referenced using the signal name directly.
  • Receiver. This parameter should either be a PId value for a process instance within the system, or the value xNotDefPId. The value xNotDefPId is used to indicate that the signal should be sent as an output without TO clause, while if a PId value is given the output, it is treated as an output with TO clause. Note that PId values for process instances in an SDL system cannot be calculated, but have to be captured from the information (sender or parameter) carried by signals coming from the system. This is the normal procedure in SDL to establish direct communication.
  • Sender. Sender should either be a PId value representing a process instance in the environment of the current SDL system or the value xEnv. xEnv is a PId value that refers to an environment process instance, which is used to represent the general concept of the SDL environment, without specifying an explicit process instance in the environment.

The function SDL_Output takes a reference to a signal instance and outputs the signal according to the rules of SDL.

void SDL_Output
( xSignalNode S,
xIdNode ViaList[] );

  • S. This parameter should be a reference to a signal instance with all components filled in.
  • ViaList. This parameter is used to specify if a VIA clause is or is not part of the output statement. The value (xIdNode *)0 (a null pointer), is used to represent that no VIA clause is present. For information about how to build a via list, please see below.

We now have enough information to be able to write the code to send a signal. Suppose we want to send a signal S1, without parameters, from xEnv into the system without an explicit receiver (without TO). The code will then be:

Example 412 : C Code to Send a Signal to the Environment

SDL_Output( xGetSignal(S1, xNotDefPId, xEnv),
(xIdNode *)0 );

If S2, with two integer parameters, should be sent from xEnv to the process instance referenced by the variable P, the code will be:

xSignalNode OutputSignal; /* local variable */
...
OutputSignal = xGetSignal(S2, P, xEnv);
((yPDP_S2)OutputSignal)->Param1 = 1;
((yPDP_S2)OutputSignal)->Param2 = 2;
SDL_Output( OutputSignal, (xIdNode *)0 );

For the details of how to reference the parameters of a signal see the subsection "Types Representing Signals" .

To introduce a via list in the output requires a variable, which should be an array of xIdNode, that contains references to the symbol table nodes representing the current channels (or signal routes) in the via list. In more detail, we need a variable

ViaList xIdNode[N];

where N should be replaced by the length of the longest via list we want to represent plus one. The components in the variable should then be given appropriate values, such that component 0 is a reference to the first channel (its symbol table node) in the via list, component 1 is a reference to the second channel, and so on. The last component with a reference to a channel must be followed by a component containing a null pointer (the value (xIdNode)0). Components after the null pointer will not be referenced. Below is an example of how to create a via list of two channels, C1 and C2.

Example 413 : Via List of two Channels.

ViaList xIdNode[4];
/* longest via has length 3 */
...
/* this via has length 2 */
ViaList[0] = (xIdNode)xIN_C1;
ViaList[1] = (xIdNode)xIN_C2;
ViaList[2] = (xIdNode)0;

The variable ViaList may then be used as a ViaList parameter in a subsequent call to SDL_Output.

Guidelines for the xInEnv Function

It is more difficult to give a structure for the xInEnv function, than for the xOutEnv function discussed in the previous subsection. A xInEnv function will in principle consist of a number of if statements where the environment is investigated. When some information is found that means that a signal is to be sent to the SDL system, then the appropriate code to send a signal (see above) should be executed.

The structure given in the example below may serve as an idea of how to design the xInEnv function.

Example 414 : Structure of xInEnv Function

void xInEnv (SDL_Time Time_for_next_event)
{
xSignalNode S;

if ( Sig1 should be sent to the system ) {
SDL_Output (xGetSignal(Sig1, xNotDefPId,
xEnv), (xIdNode *)0);
}
if ( Sig2 should be sent to the system ) {
S = xGetSignal(Sig1, xNotDefPId, xEnv);
((xPDP_Sig2)S)->Param1 = 3;
((xPDP_Sig2)S)->Param2 = SDL_True;
SDL_Output (S, (xIdNode *)0);
}
/* and so on */
}

This basic structure can be modified to suit your own needs. The if statements could, for example, be substituted for while statements. The signal types might be sorted in some "priority order" and a return can be introduced last in the if statements. This means that only one signal is sent during a xInEnv call, which reduces the latency.

Alternative to OutEnv - Directive #EXTSIG

To speed up an application it is sometimes possible to use the directive #EXTSIG instead of the xOutEnv function. The decision to use #EXTSIG or xOutEnv may be taken individually for each signal type.

The usage of the #EXTSIG directive is described in the section "Modifying Outputs - Directive #EXTSIG, #ALT, #TRANSFER" . This information is not repeated here.

By using the #EXTSIG directive the following overhead can be avoided:

  • Calling SDL_Output (the library function for outputs)
  • SDL_Output determines that the signal is to be sent to the environment
  • SDL_Output calls xOutEnv
  • xOutEnv executes nested "if" statements to determine the signal type.

Including the Environment Functions in the SDL System Design

Apart from having the environment functions on a file of their own, it is of course possible to include these function directly into the system diagram in a #CODE directive.

Example 415 : Including Environment Functions in SDL System

/*#CODE
#BODY
... code for the environment functions ...
*/

In this case you cannot use the system interface header file, but instead you have all the necessary declarations already at your disposal, as the functions will be part of the SDL system. The only problem you will encounter is the prefixing of SDL names when they are translated to C. The #SDL directive should be used to handle this problem (or the #NAME directive), see sections "Accessing SDL Names in C Code - Directive #SDL" and "Specifying Names in Generated Code - Directive #NAME" . The following table shows how to obtain C names for some SDL objects of interest:

#(Synonym name)
#(Newtype or syntype name)
ySigN_#(Signal name)
yPDP_#(Signal name)
yChaN_#(Channel name)

SDL Data Encoding and Decoding, ASCII coder

Communication between nodes often requires data encoding and decoding between node internal representations and a common format in a protocol buffer. The sending node writes information in the common format and the receiving node reads information from the common format. Data encoding is the transformation from a node internal representation into a common format and data decoding is the transformation from a common format into a node internal representation.

Supported common formats are:

  • BER
  • PER
  • ASCII

BER (Basic Encoding Rules) is specified in ITU standard X.690 and PER (Packed Encoding Rules) is specified in ITU standard X.691. BER and PER are based on ASN.1 specifications of data types and can only be used for types specified in ASN.1 specifications. See 58 ASN.1 Encoding and De-coding in the SDL Suite and 8 Tutorial: Using ASN.1 Data Types.

ASCII is a format where the data is represented as ASCII characters. It is easy to read and analyze. The ASCII format is specified in appendix A.

Example 416 ASCII common format

newtype Person struct
nm Charstring;
nr Integer;
fm Boolean;
endnewtype Person;

dcl boss Person := (.'Joe',5,false.);

ASCII format:{`Joe',5,F}

The ASCII coder uses the same buffer management and error management as the BER and PER coders, see 58 ASN.1 Encoding and De-coding in the SDL Suite.

Type description nodes for SDL types

SDL data encoders and data decoders need information about types and signals, information that is stored in type descriptions nodes. Type description nodes for an SDL system are generated if the Generate SDL coder option is selected in the organizer, see 2 The Organizer, or in the targeting expert, see 59 The Targeting Expert. Declarations to access the type nodes are in the system interface header files and in a file with the name <system_file_name>_cod.h. Type nodes can be found in any generated c-file from a system or a package and also in the <system_file_name>_cod.c file.

A type description node for SDL is implemented as a static variable with the type information. The variable can be accessed by using the name ySDL_<type_name> or ySDL_<signal_name>, where <type_name> and <signal_name> are the names used in the interface header file. See "Names of SDL Objects in C" for more information.

Encoding signal and signal parameters into a buffer

You can use an encode function to encode signal parameters into a buffer. There is one encoding function for each common format. For ASCII, it is accessed by using the macro ASCII_ENCODE. An encoding function has a buffer reference as the first parameter, a pointer to a type node as the second parameter and a pointer to the variable to encode as the third. The encoding function returns an integer value, which is 0 if the encoding was successful and error code if it was not. More details about encoding functions, the buffer reference, type nodes and error codes can be found in 58 ASN.1 Encoding and De-coding in the SDL Suite.

Function declarations are in the file "ascii/ascii.h" ("ascii\ascii.h" on Windows platforms) in the coder directory.

Example 417 ASCII encoding of signal parameters

In SDL:
SIGNAL Sig1(Integer,Person,Boolean);

In xOutEnv:
BufInitWriteMode(buf);
result = ASCII_ENCODE(buf,
(tSDLTypeInfo *)&ySDL_Integer,
(void *)&((yPDP_Sig1)(*S))->Param1));
if (result!=0) /* handle error */;
result = ASCII_ENCODE(buf,
(tSDLTypeInfo *)&ySDL_Person
(void *)&((yPDP_Sig1)(*S))->Param2));
if (result!=0) /* handle error */;
result = ASCII_ENCODE(buf,
(tSDLTypeInfo *)&ySDL_Boolean
(void *)&((yPDP_Sig1)(*S))->Param3));
if (result!=0) /* handle error */;
BufCloseWriteMode(buf);

Example 418 ASCII encoding of whole signal (all signal parameters)

In SDL:
SIGNAL Sig1(Integer,Person,Boolean);

In xOutEnv:
BufInitWriteMode(buf);
result = ASCII_ENCODE(buf,
(tSDLTypeInfo *)&ySDL_Sig1,
(void *)(*S));
if (result!=0) /* handle error */;
BufCloseWriteMode(buf);

Note:

The names of the type nodes in the examples, the second parameter in ASCII_ENCODE, depend on the settings for generating system interface header files.

Decoding into signal parameters from a buffer

You can use a decode function to decode from a buffer into a signal parameter. There is one decoding function for each common format. For ASCII, it is accessed by using the macro ASCII_DECODE. A decode function has a buffer reference as the first parameter, a pointer to a type node as the second parameter and a pointer to the variable to decode as the third. The decoding function returns an integer value, which is 0 if the decoding was successful and an error code if it was not. More details about decoding functions, the buffer reference, type nodes and error codes can be found in 58 ASN.1 Encoding and De-coding in the SDL Suite.

Function declarations are in the file "ascii/ascii.h" ("ascii\ascii.h" on Windows platforms) in the coder directory.

Example 419 ASCII decoding into signal parameters

In SDL:
SIGNAL Sig1(Integer,Person,Boolean);

In xInEnv:
BufInitReadMode(buf);
result = ASCII_DECODE(buf,
(tSDLTypeInfo *)&ySDL_Integer,
(void *)&((yPDP_Sig1)(S))->Param1));
if (result!=0) /* handle error */;
result = ASCII_DECODE(buf,
(tSDLTypeInfo *)&ySDL_Person
(void *)&((yPDP_Sig1)(S))->Param2));
if (result!=0) /* handle error */;
result = ASCII_DECODE(buf,
(tSDLTypeInfo *)&ySDL_Boolean
(void *)&((yPDP_Sig1)(S))->Param3));
if (result!=0) /* handle error */;
BufCloseReadMode(buf);

Example 420 ASCII decoding of whole signal (all signal parameters)

In SDL:
SIGNAL Sig1(Integer,Person,Boolean);

In xInEnv:
BufInitReadMode(buf);
result = ASCII_DECODE(buf,
(tSDLTypeInfo *)&ySDL_Sig1,
(void *)S);
if (result!=0) /* handle error */;
BufCloseReadMode(buf);

Note:

The names of the type nodes in the examples, the second parameter in ASCII_DECODE, depend on the settings for generating system interface header files.

Encoding and decoding signal identifier for ASCII encoding

When sending signals between nodes it is often important to put a signal identifier first in the buffer. The signal identifier must be a unique identifier of the signal in the distributed system. Decoding is then a two step process, first decode signal identifier and find signal information and second decode signal parameters.

You can use any representation of signal identifiers in the environment functions.

For SDL types there is a special signal id type node that supports character string signal ids. The type node can be used for ASCII encoding.

Example 421 Using signal identifier

In SDL:
SIGNAL Sig1(Integer);

In xOutEnv:
void xOutEnv ( xSignalNode *S )
{
char * signalId;

BufInitWriteMode(buf);
if ( (*S)->NameNode == Sig1 ) {
/* encode signal id into buffer */
signalId="Sig1";
result = ASCII_ENCODE(buf,
(tSDLInfo *)&ySDL_SignalId,
(void *)signalId);
if (result!=0) /* handle error */;
/* encode signal parameter */
result = ASCII_ENCODE(buf,
(tSDLTypeInfo *)&ySDL_Sig1,
(void *)(*S));
if (result!=0) /* handle error */;

/* send buffer using protocol*/

/* release memory */

xReleaseSignal(S);
return;
}
BufCloseWriteMode(buf);
}

In xInEnv:
void xInEnv (SDL_Time Time_for_next_event) {
char SId[100];

BufInitReadMode(buf);
/* decode signal id */
result = ASCII_DECODE(buf,
(tSDLTypeInfo *)&ySDL_SignalId,
SId) );
if (result!=0) /* handle error */;
/* signal Sig1 in buffer */
if ( strcmp(SId,"Sig1") ) {
S=xGetSignal(Sig1,xNotDefPId, xEnv);
result = ASCII_DECODE(buf,
(tSDLTypeInfo *)&ySDL_Sig1,
(void *)S);
if (result!=0) /* handle error */;
SDL_Output(S, (xIdNode *)0 );
}
BufCloseReadMode(buf);
}

Function xGlobalNodeNumber

You should also provide a function, xGlobalNodeNumber, with no parameters, which returns an integer that is unique for each executing system.

int xGlobalNodeNumber ( void )

The returned integer should be greater than zero and should be unique among the communicating SDL systems that constitutes an application. If the application consists of only one application then this number is of minor interest (it still has to be set). The global node number is used in PId values to identify the node (OS process / processor) that the process instance belongs to. PId values are thereby universally accessible and you may, for example, in a simple way make "Output To Sender" work between processes in different SDL systems (OS processes / processors).

When an application consisting of several communicating SDL systems is designed, you have to map the global node number to the current OS process or processor, to be able to transmit signals addressed to non-local PIds to the correct OS process or processor. This will be part of the xOutEnv function.

Program Structure

The generated code will contain two important types of functions, the initialization functions and the PAD functions. The PAD functions implement the actions performed by processes during transitions. There will be one initialization function in each generated.c file. In the file that represents the system this function will have the name yInit. Each process in the system will be represented by a PAD function, which is called when a process instance of the current instance set is to execute a transition.

The example below shows the structure of the main, MainInit, and MainLoop functions.

Example 422 : Start up structure

void main ( void )
{
xMainInit();
xMainLoop();
}

void xMainInit ( void )
{
xInitEnv();
Init of internal data structures in the
runtime library;
yInit();
}

void xMainLoop ( void )
{
while (1) {
xInEnv(...);
if ( Timer output is possible )
SDL_OutputTimerSignal();
else if ( Process transition is possible )
Call appropriate PAD function;
}
}

The function xMainLoop contains an endless loop. The appropriate way to stop the execution of the program is to call the runtime library function SDL_Halt. The call of this C function should normally be included in an appropriate task, using the directive #CODE. SDL_Halt which has the following structure:

void SDL_Halt ( void )
{
xCloseEnv();
exit(0);
}

To complete this overview, which emphasizes the usage of the environment functions, we have to deal with the xOutEnv function. Within PAD functions, the runtime library function SDL_Output is called to implement outputs of signals. When SDL_Output identifies the receiver of a signal to be a process instance that is not part of the current SDL system, SDL_Output will call the xOutEnv function.

Dynamic Errors

In the library for applications SDL runtime errors will not be reported. The application will just perform some appropriate actions and continue to execute. These actions are in almost all cases the same as the actions at dynamic errors described in the "Dynamic Errors" .

  • Output warnings: If a signal is sent to NULL or to a stopped process instance, or if no receiver is found in an output without a "to" clause, the signal will not be sent, that is, the output statement is a null action. If a signal is sent to a process instance and there is no path between the sender and the receiver, the signal will be sent anyway (actually, no check will be performed).
  • If the error was a decision error, that is, no path exists for the current decision value, the execution of the program will continue in an unpredictable way. To avoid these kind of problems you should always have else paths in decisions (if not all values in the current data type are covered in other paths).
  • If the error occurred during an import or view action, a data area of the correct size containing zero in all positions is returned.
  • No checks of assignment or index out of range will be performed. This means that if an array index is out of bounds, then the corresponding C array will be indexed out of its bounds.
  • No checks when accessing struct, #UNION, or choice components are performed. No checks are performed when de-referencing a pointer value (Ref generator). These operations will just be executed.
  • If the dynamic error occurred within an SDL expression, the operator that found the error will return a default value and the evaluation of the expression is continued. The default values returned depend on the result type of the operator and are given in the section "Default Values" .


Example Section

In this section a complete example of an application is presented. The application is simple but it still contains most of the problems that arise when the Cadvanced SDL to C Compiler is used to generate applications. All source code for this example, together with the running application are delivered with the runtime libraries for application generation. Note that the example is developed for SunOS 5 and HP-UX. The example is not updated to use encoding and decoding support.

The Example

We want to develop an application that consists of several communicating UNIX processes. Each UNIX process should also be connected to the keyboard and the screen. When a complete line is typed on the keyboard (when <Return> is pressed) in one of the UNIX processes, that line should be sent to and printed by all the UNIX processes, including the one where the line was entered. If a line starting with the character "." is entered in any UNIX process then all the UNIX processes should terminate immediately.

There are some observations we can make from this short description.

  • Firstly, all the UNIX processes should behave exactly the same, which means that the behavior can be described in one SDL system and one application can be generated. This application should be able to communicate with other instances of itself and should simultaneously be started in as many instances as we want communicating UNIX processes.
  • Secondly, each UNIX process needs access to the terminal. To simplify the connection between a UNIX process and the terminal, we assume that each instance of the application is started from its own window (its own shell tool). In this way the underlying window manager will solve the problem of directing input typed on the keyboard to the correct application, as well as making it possible for you to distinguish between output from different applications.
  • Thirdly, the UNIX processes have to be connected so they can communicate with each other. We have decided to use sockets as communication media, and to let the UNIX processes form a ring. This means that when a UNIX process receives a message containing a line, it should print the line and send the message on to the next UNIX process in the ring, if it did not itself originally send the line message.

The SDL System

The SDL system with a behavior as outlined above is very simple. It contains, for example, only one process. The system can receive three types of signals, TermInput from the terminal, and Message and Terminate from the SDL system that is the previous node in the ring. The system will respond by sending Display to the terminal and Message and Terminate to the SDL system next in the ring. The signals TermInput and Display take a line (which is read from the terminal or should be printed on the terminal) as parameter. The signal Message takes a line and a PId value (the original sender in the ring) as parameter, while the signal Terminate takes a PId value (the original sender in the ring) as parameter.

The diagrams for the SDL system may be found in "Appendix C: The SDL System" . In the section "Where to Find the Example" , references to where to find the source code for this example are given.

Simulating the Behavior

At this stage of the development of the application, when the SDL system is completed but the environment functions are not implemented, it is time to simulate the SDL system to debug it at the SDL level. The runtime library Simulation is appropriate in this case for simulation.

There are six cases that should be tested:

  • If TermInput (with a line not starting with a period) is sent to the system, it should respond by sending a Message signal to the environment. The first parameter in this signal should be equal to the parameter in the received TermInput signal. The second parameter should be the PId value of the sending process.
  • If TermInput (with a line starting with a period) is sent to the system, it should respond by sending a Terminate signal to the environment. The parameter should be the PId value of the sending process.
  • If Message (with a PId parameter not equal to the receiving process) is sent to the system, it should respond by sending a copy of the Message signal to the environment. It should also send Display to the environment with the received line as parameter.
  • If Message (with a PId parameter equal to the receiving process) is sent to the system, it should respond by just sending a Display signal to the environment with the received line as parameter.
  • If Terminate (with a PId parameter not equal to the receiving process) is sent to the system, it should respond by sending a copy of the Terminate signal to the environment. The execution of the program should then terminate.
  • If Terminate (with a PId parameter equal to the receiving process) is sent to the system, the program should just stop executing.

Let us now verify that the SDL system behaves according to this. In the two executions of the simulation shown below, the cases described above are tested in the same order as they are listed.

Example 423 : Execution Trace of Generated Application

Start program Phone.sim.sct:

Command : set-trace 6
Default trace set to 6

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : start state
* Now : 0.0000
*** NEXTSTATE idle

Command : output-via
Signal name : TermInput
Parameter 1 (charstring) : `hello'
Channel name :
Signal TermInput was sent to PhonePr:1 from env:1
Process scope : PhonePr:1

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : idle
* Input : TermInput
* Sender : env:1
* Now : 0.0000
* Parameter(s) : `hello'
* DECISION Value: true
* DECISION Value: false
* OUTPUT of Message to env:1
* Parameter(s) : `hello', PhonePr:1
*** NEXTSTATE idle
Command : output-via TermInput `.' -
Signal TermInput was sent to PhonePr:1 from env:1
Process Scope : PhonePr:1

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : idle
* Input : TermInput
* Sender : env:1
* Now : 0.0000
* Parameter(s) : `.'
* DECISION Value: true
* DECISION Value: true
* OUTPUT of Terminate to env:1
* Parameter(s) : PhonePr:1
*** NEXTSTATE idle

Command : output-via Message
Parameter 1 (charstring) : `hello'
Parameter 2 (pid) : env
Channel name :
Signal Message was sent to PhonePr:1 from env:1
Process scope : PhonePr:1

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : idle
* Input : Message
* Sender : env:1
* Now : 0.0000
* Parameter(s) : `hello', env:1
* DECISION Value: false
* OUTPUT of Message to env:1
* Parameter(s) : `hello', env:1
* OUTPUT of Display to env:1
* Parameter(s) : `hello'
*** NEXTSTATE idle

Command : output-via Message
Parameter 1 (charstring) : `hello'
Parameter 2 (pid) : PhonePr:1
Channel name :
Signal Message was sent to PhonePr:1 from env:1
Process scope : PhonePr:1

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : idle
* Input : Message
* Sender : env:1
* Now : 0.0000
* Parameter(s) : `hello', PhonePr:1
* DECISION Value: true
* OUTPUT of Display to env:1
* Parameter(s) : `hello'
*** NEXTSTATE idle

Command : output-via Terminate
Parameter 1 (pid) : env
Channel name :
Signal Terminate was sent to PhonePr:1 from env:1
Process scope : PhonePr:1

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : idle
* Input : Terminate
* Sender : env:1
* Now : 0.0000
* Parameter(s) : env:1
* DECISION Value: false
* OUTPUT of Terminate to env:1
* Parameter(s) : env:1
* TASK Halt

Example 424

Start program Phone.sim.sct:

Command : set-trace 6
Default trace set to 6

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : start state
* Now : 0.0000
*** NEXTSTATE idle

Command : output-via Terminate
Parameter 1 (pid) : PhonePr:1
Channel name :
Signal Terminate was sent to PhonePr:1 from env:1
Process scope : PhonePr:1

Command : next-transition

*** TRANSITION START
* PId : PhonePr:1
* State : idle
* Input : Terminate
* Sender : env:1
* Now : 0.0000
* Parameter(s) : PhonePr:1
* DECISION Value: true
* TASK Halt

By running the system with the SDL monitor, as in the examples above, you may debug the system at the SDL level. The overall behavior of the system can thus be tested.

It is possible to start two instances of the simulation and have the simulators communicate with each other. Then Message and Terminate signals sent to the environment in one of the simulations will appear as signals coming from the environment in the other.

Note:

Do not forget the monitor command Start-SDL-Env to make the simulation programs start communicating.

The Environment

In the environment functions we use the socket facility in UNIX to implement the communication between the executing programs. In the current example, the implementation is developed for SunOS 5 and HP-UX.

To simplify the example we assume that each instance of the application is started in a window of its own (a shell tool window under for instance X Windows, where UNIX commands can be entered). This means that we will have no problems with the interpretation of stdin and stdout in the programs.

The name of the socket for incoming messages for a certain instance of the application will be the string "Phone" concatenated with the UNIX process number for the current program. The socket will be created in the directory /tmp. Each application instance will print this number during the initialization and will then ask for the process number of the application instance where it should send its messages. You have to enter these numbers in such a way as to form a ring among the applications.

The Environment Functions

The environment functions, which may be found in the file PhoneEnv.c, are shown in section "Appendix D: The Environment Functions" . The file is developed according to the structure discussed in the previous part of this chapter and uses the system interface header file generated from the SDL system.

As the PhoneEnv.c file includes scttypes.h and uses some C macros, it should be compiled using the same compiler options as the C file for the SDL system. For information about how to extend the generated make file to handle also non-generated files, please see "Makefile Options" .

In the code for the environment functions a number of UNIX functions are used. Their basic behavior is described below. For any details please see the UNIX manuals available from Sun Microsystems.

Function name
Functionality

 getpid
Returns the UNIX process number for the current program.

 socket
Returns a new, unnamed socket.

 bind
Binds a socket to a name in the file system.

 listen
Starts listen for other programs trying to connect to this socket.

 connect
Should be called by other programs that want to establish a connection to the current socket.

 accept
Accepts a connection request.

 select
Returns 1 if anything readable can be found in any of the specified file descriptors, where a file descriptor can represent a file, a socket, and the terminal (stdin and stdout).

 read, write
Reads or writes on a file (a file descriptor).

 close
Closes a file.

 unlink
Removes a file.

If we now look at the code for the environment functions (see "Appendix D: The Environment Functions" ), we see that xInitEnv mainly performs the following actions:

  • It creates two unnamed sockets, one for message in (Connection_Socket) and one for messages out (Out_Socket).
  • It binds Connection_Socket to the file system (in the /tmp directory) and starts listen for connections.
  • It prints its UNIX process number.
  • It reads the UNIX process number of the process where to send messages.
  • It attempts to connect to the socket of the process where to send messages.
  • It accepts the connection from the process that will send messages here.

In xCloseEnv the created sockets are closed and removed.

The xInEnv and xOutEnv functions follow the guidelines for these functions given in the reference section. In xInEnv the select function is used to determine if any messages are ready to be received from the terminal (stdin) or from the incoming socket. An available message is then read and the information is converted to an SDL signal, which is sent to the SDL system using the SDL_Output function. In xOutEnv a test on the NameNode in the signal is used to determine the signal type. Depending on the signal type the appropriate information is written either on the outgoing socket or on the terminal (stdout).

Debugging

The first part of the debugging activity is, of course, when the SDL system is simulated and examined through the monitor system. Now we also want to include the environment functions during debugging. The intention of the library ApplicationDebug is to use the monitor and the environment functions together.

When the environment functions (xInEnv) read information from the keyboard there is, however, a problem in using xInEnv together with the monitor. In our system, for instance, a line typed on the keyboard may either be a monitor command or a line typed to the SDL system. As both the monitor and xInEnv are polling for lines from stdin, the interpretation of a typed line depends on which one first finds the line.

A better way is to eliminate this indeterministic behavior by not polling for typed lines in xInEnv. Instead, you may use the monitor command:

Output-Via TermInput 'the line'

to simulate a line typed on the keyboard. In this way all the other parts of the environment functions can be tested under the monitor. If you enclose the sections in xInEnv handling keyboard polling between #ifndef XMONITOR and #endif this code is removed when the monitor is used; that is if the library ApplicationDebug is used (see the code for xInEnv in "Appendix D: The Environment Functions" ).

A C source code debugger is of course also useful when debugging the environment functions. The initialization phase, xInitEnv, is probably the most difficult part to get working correctly in our system. All the source code for this function is available, and a C debugger can be used.

While debugging generated code from SDL at the C level, it is always easy to find the currently executing SDL symbol, by using the SDT references (see "Syntax" ) in the C code and the Go To Source menu choice in the Edit menu in the Organizer. For more details please see "Go To Source" .

Running the Application

To have an application of the Phone system you now only need to make a new executing program with the library Application.

When you run the Phone system, start the program from two (or more) shell tools (on UNIX). Each instance of the program will then print:

My Pid: 2311
Connect me to:

You should answer these questions in such a way that a ring is formed by the programs. When the initialization is completed for a program it prints:

******** Welcome to SDT Phone System ********
phone ->

The program is now ready to receive lines printed on the keyboard and messages sent from other programs. A Display signal received from another program is printed as follows:

display -> the line received in Display signal

Where to Find the Example

All files concerning this example may be found in the directory:

<installation directory>/sdt/examples/phone

Use these files if you only want to look at the source files and if you are using a Sun workstation you could try the executing versions of the program. Otherwise you should copy the files to one of your own directories. Please be sure not to change the original files.

In the directory you will find the following files:

File name
Purpose

 Phone.sdt
The system file

 Phone.ssy
Represents the SDL system

 PhoneBl.sbk
Represents the SDL block

 PhonePr.spr
Represents the SDL process

 phone.pr
The generated PR file after GR to PR

 phone.c
The generated C file after C code generation

 phone.ifc
The generated .ifc file

 PhoneEnv.c
Contains the environment functions

 Phone.m
The make file for HP-UX

 Phone.solaris.m
The make file for SunOS 5


Appendix A: Formats for ASCII

The ASCII encoding function, ASCII_ENCODE, encodes the SDL signal parameters and variables as ASCII characters before adding into the buffer. The output into the buffer is illustrated with a number of examples.

Braces { } are used for most data types and show where the data types start and stop. Signal parameters start and stop with braces.

Comma is used to delimit.

For more information about data types see "Using SDL Data Types" .

Array, CArray

Array is used to define a fixed number of elements.

Array takes two generator parameters, an index sort and a component sort.

Example 425 : Using Array

newtype A1 Array(b, Integer) endnewtype;

dcl Var_Array A1;

task Var_Array := (. 3 .);

Output to the buffer: {3,3,3}

Bag

Bag is almost the same as Powerset. The only difference is that Bag contains the same value several times. Bag can be used as an abstraction of other data types.

Bag takes one generator parameter, the item sort.

Example 426 : Using Bag

newtype B1 Bag(Integer) endnewtype;

dcl Var_Bag B1;

task Var_Bag := (. 7, 4, 7 .);

Output to the buffer: {2:7,1:4}

Example 427 : Using Bag (old-style SDL operator code generation)

newtype B1 Bag(Integer) endnewtype;

dcl Var_Bag B1;

task Var_Bag := Incl(7, Incl(4, Incl(7, Empty)));

Output to the buffer: {2:7,1:4}

Bit

Bit can only take two values, 0 and 1.

Example 428 : Using Bit

dcl Var_Bit Bit;

task Var_Bit := 1;

Output to the buffer: 1

Bit_String

Bit_String is used to represent a sequence of bits.

Example 429 : Using Bit_String

dcl Var_Bit Bit_String;

task Var_Bit := Mkstring(I20(1101));

Output to the buffer: `1101'

Boolean

Boolean can only take two values, False and True.

Example 430 : Using Boolean

dcl Var_Boolean Boolean;

task Var_Boolean := TRUE;

Output to the buffer: T

If Var_Boolean is set to FALSE, the output to the buffer will be F.

Character

Character is used to represent the ASCII characters.

Example 431 : Using Character

dcl Var_Character Character;

task Var_Character := `M'

Output to the buffer: M

CharStar, PId, UnionC, Userdef, VoidStar, VoidStarStar

The user has to define encoding/decoding procedures for these types, see "Appendix B: User defined ASCII encoding and decoding" . If no encoding/decoding procedure is defined, then there will be no output to buffer.

For threaded integrations, the PId value will be encoded/decoded by coding the memory address as an integer.

CharString, IA5String, NumericString, PrintableString, VisibleString

These string types are used to represent sequences of characters.

Example 432 : Using Charstring

dcl Var_Charstring Charstring;

task Var_Charstring := `Hello world'

Output to the buffer: `Hello world'

Choice, Union

Choice represents the ASN.1 concept CHOICE and can also be seen as a C union with an implicit tag field.

Example 433 : Using Choice

newtype C Choice
c1 Character;
c2 Boolean;
endnewtype;

dcl Var_Choice C;

task Var_Choice := c2:true;

Output to the buffer: {1,T}, where 1 is an implicit tag.

Duration, Time

Time is used to denote `a point in time' and Duration is used to denote `a time interval'.

A value of sort Time represents a point of time in the real world. The Time unit is usually 1 second.

Example 434 : Using Time

dcl Var_Time Time;

task Var_Time := 1;

Output to the buffer: {1,0}. The first field is seconds and the second field is nano-seconds.

Enum

Enum contains only the values enumerated in a sort.

Example 435 : Using Enum

newtype E /*Enum*/
literals e1, e2, e3;
endnewtype;

dcl Var_Enum E;

task Var_Enum := e2;

Output to the buffer: 1

Float

Float is equivalent to float in C.

Example 436 : Using Float

dcl Var_Float Float;

task Var_Float := 3.14159;

Output to the buffer: 3.1415901e0 (always 7 decimals)

GPowerset, Object_Identifier, String

GPowerset is used as an abstraction of other data types. GPowerset takes one generator parameter, the item sort.

Object_Identifier is a sequence of Natural values.

String can be used to build lists of items of the same type. String has two generator parameters, the component sort and the name of an empty string.

Example 437 : Using GPowerset

newtype GP Powerset(Integer) endnewtype;

dcl Var_GPowerset GP;

task Var_GPowerset := Incl(7, Incl(4, Empty));

Output to the buffer: {3,4}

Object_Identifier and String are used in the same way as GPowerset.

Inherits, Syntype

Syntype and Inherits create a new type, that has the same properties as an existing type, by inheriting the type or make a syntype of the type.

Example 438 : Using Syntype

syntype newinteger = Integer endsyntype;

dcl Var_Newinteger newinteger;

task Var_Newinteger := 2

Output to the buffer: 2

Integer, LongInt, ShortInt, UnsignedInt, UnsignedLongInt, UnsignedShortInt, Natural

Integer is used to represent mathematical integers.

Natural is a syntype of Integer.

Example 439 : Using Integer

dcl Var_Integer Integer;

task Var_Integer := 1

Output to the buffer: 1

Null

The sort Null only contains one value, Null.

Example 440 : Using Null

dcl Var_Null Null;

task Var_Null := Null;

Output to the buffer: 0

Octet

Octet is used to represent eight-bit values.

Example 441 : Using Octet

dcl Var_Octet Octet;

task Var_Octet := I20(12);

Output to the buffer: 0c

Octet_String

Octet_String represents a sequence of Octet values.

Octet_String always contains an equal number of characters, since every octet takes two characters.

Example 442 : Using Octet_String

dcl Var_OctetString Octet_String;

task Var_OctetString := Mkstring(I20(12));

Output to the buffer: `0c'

ORef, Own, Ref

ORef, Own and Ref are used to define pointer types.

Example 443 : Using Ref

newtype R Ref(r1) endnewtype;

dcl Var_Ref R;

task Var_Ref := (. (. 1, 2, `Telelogic' .) .);

Output to the buffer: {{1,2,'Telelogic'}}

Powerset

Powerset takes one generator parameter, the item sort, and implements a powerset over that sort. Powerset can be used as an abstraction of other data types.

Example 444 : Using Powerset

newtype P Powerset(p1) endnewtype;

dcl Var_Powerset P;

task Var_Powerset := (. 4, 3 .);

Output to the buffer: `00110000000000000000000000000000'

The bits are an equal multiple of sizeof(unsigned long).

Example 445 : Using Powerset (old-style SDL operator code generation)

newtype P Powerset(p1) endnewtype;

dcl Var_Powerset P;

task Var_Powerset := Incl(4, Incl(3, Empty));

Output to the buffer: `00110000000000000000000000000000'

The bits are an equal multiple of sizeof(unsigned long).

Real

Real is used to represent the mathematical real values.

Example 446 : Using Real

dcl Var_Real Real;

task Var_Real := 1.0;

Output to the buffer: 1.0000000000000e0 (always 13 decimals)

SignalId

SignalId is used to describe the signal ID.

SignalId is a sequence with characters.

Example 447 : Using SignalId

dcl Var_SignalId SignalId;

task Var_SignalId := `Sig1';

Output to the buffer: `Sig1'

Struct

Struct can be used to make an aggregate of data that belong together.

Example 448 : Using Struct

newtype S struct
s1 integer;
s2 integer;
s3 charstring;
endnewtype;

dcl Var_Struct S;

task Var_Struct := (. 1, 2, `Telelogic' .);

Output to the buffer: {1,2,'Telelogic'}


Appendix B: User defined ASCII encoding and decoding

The types CharStar, PId, UnionC, Userdef, VoidStar, VoidStarStar do not have a natural transformation to ASCII format. The desired encoding probably differs from application to application. The ASCII encoding procedure and the ASCII decoding procedures do not encode or decode these types, but they can invoke user written procedures for encoding and decoding them.

For threaded integrations, the PId value will be encoded/decoded by coding the memory address as an integer.

If you want to add encoding for these types, then do the following steps:

  • Implement a C-function for encoding with input and output parameters compatible with tEncodeFunc, which is declared in file "coderucf.h". The encode functions in "coderascii.c" can be used as an example.
  • Set static variable AsciiUserEncode to your encode function in xInitEnv.

If you want to add decoding for these types, then do the following steps:

  • Implement a C-function for decoding with input and output parameters compatible with tDecodeFunc, which is declared in file "coderucf.h". The decode functions in "coderascii.c" can be used as an example.
  • Set static variable AsciiUserDecode to your decode function in xInitEnv.

Example 449 User defined ASCII encoding

int MyAsciiEncoder( tBuffer Buf,
tSDLTypeInfo* TypeNode,
void* Value )
{
/* my error handling code for one or more of
CharStar, PId, UnionC, Userdef, VoidStar, VoidStarStar */
/* return 1 if it was succesful,
return 0 if it failed */
}

In xInitEnv:

AsciiUserEncode = MyAsciiEncoder;


Appendix C: The SDL System

Figure 492 : The system Phone

Figure 493 : The block PhoneBl

Figure 494 : The process PhonePr


Appendix D: The Environment Functions

This section contains the environment functions included in the example. Note that this example is not updated to use the ASCII encoder.

/****+*******************************************************
00 sctEnv.c for SimplePhoneSys
************************************************************/
#include "scttypes.h"
#include <stdio.h>

#include "phone.ifc"

#include <sys/types.h>
#include <sys/time.h>
#include <sys/socket.h>
#ifdef AIXV3CC
#include <sys/select.h>
#endif
#include <sys/un.h>

#include <unistd.h>
#define getdtablesize() ( (int) sysconf(_SC_OPEN_MAX) )

int Out_Socket, In_Socket;
struct sockaddr_un Connection_Socket_Addr;
struct sockaddr_un Connected_Socket_Addr;

#ifdef ULTRIXCC
#define PRINTF(s) \
printf(s); \
/* flush output to get a prompt */ \
fflush( stdout)
#else
#define PRINTF(s) printf(s)
#endif

#ifdef XENV

/*#if !defined(XPMCOMM) && defined(XENV)*/
/*---+-------------------------------------------------------
xGlobalNodeNumber extern
-----------------------------------------------------------*/
#ifndef XNOPROTO
int
xGlobalNodeNumber( void )
#else
int
xGlobalNodeNumber()
#endif
{
static int ProcId = -1;

if (ProcId < 0)
ProcId = getpid();
return (ProcId);
}
/*#endif*/

/*---+-------------------------------------------------------
xInitEnv extern
-----------------------------------------------------------*/
#ifndef XNOPROTO
void
xInitEnv( void )
#else
void
xInitEnv()
#endif
{
fd_set readfds;
int addr_size;
int Connection_Socket;
char TmpStr[132];
struct timeval t;

t.tv_sec = 60;
t.tv_usec = 0;

if ( (Connection_Socket = socket(PF_UNIX,SOCK_STREAM,0)) < 0 ) {
PRINTF("\nError: No Connection_Socket available!\n");
SDL_Halt();
}
if ( (Out_Socket = socket(PF_UNIX,SOCK_STREAM,0)) < 0 ) {
PRINTF("\nError: No Out_Socket available!\n");
SDL_Halt();
}

sprintf(Connection_Socket_Addr.sun_path,
"/tmp/Phone%d", xGlobalNodeNumber());
Connection_Socket_Addr.sun_family = PF_UNIX;
if ( 0 > bind(Connection_Socket, &Connection_Socket_Addr,
strlen(Connection_Socket_Addr.sun_path)+2) ) {
PRINTF("\nError: Bind did not succeed!\n");
SDL_Halt();
}
listen(Connection_Socket, 3);

sprintf(TmpStr, "\nMy Pid: %d\n", xGlobalNodeNumber());
PRINTF(TmpStr);
PRINTF("\nConnect me to: ");

FD_ZERO(&readfds);
FD_SET(1,&readfds);
FD_SET(Connection_Socket,&readfds);
if ( 0 < select(getdtablesize(), &readfds,
(fd_set*)0, (fd_set*)0, &t) ) {
if ( FD_ISSET(1, &readfds) ) {
(void)gets(TmpStr);
sscanf(TmpStr, "%s", TmpStr);
sprintf(Connected_Socket_Addr.sun_path, "/tmp/Phone%s",
TmpStr);
Connected_Socket_Addr.sun_family = PF_UNIX;
if (connect(Out_Socket, (struct sockaddr *)&Connected_Socket_Addr,
strlen(Connected_Socket_Addr.sun_path)+2) < 0) {
PRINTF("Error from connect\n");
SDL_Halt();
}
FD_ZERO(&readfds);
FD_SET(Connection_Socket,&readfds);
if ( 0 < select(getdtablesize(), &readfds, (fd_set*)0,
(fd_set*)0, &t) ) {
if ( FD_ISSET(Connection_Socket, &readfds) ) {
addr_size = strlen(Connection_Socket_Addr.sun_path)+2;
In_Socket = accept(Connection_Socket, &Connection_Socket_Addr,
&addr_size);
}
} else {
PRINTF("\nError: Timed out\n");
SDL_Halt();
}
}
else if ( FD_ISSET(Connection_Socket, &readfds) ) {
addr_size = strlen(Connection_Socket_Addr.sun_path)+2;
In_Socket = accept(Connection_Socket, &Connection_Socket_Addr,
&addr_size);
FD_ZERO(&readfds);
FD_SET(1,&readfds);
if ( 0 < select(getdtablesize(), &readfds,
(fd_set*)0, (fd_set*)0, &t) ) {
if ( FD_ISSET(1, &readfds) ) {
(void)gets(TmpStr);
sscanf(TmpStr, "%s", TmpStr);
sprintf(Connected_Socket_Addr.sun_path, "/tmp/Phone%s",
TmpStr);
Connected_Socket_Addr.sun_family = PF_UNIX;
if (connect(Out_Socket, (struct sockaddr *)&Connected_Socket_Addr,
strlen(Connected_Socket_Addr.sun_path)+2) < 0) {
PRINTF("Error from connect\n");
SDL_Halt();
}
}
} else {
PRINTF("\nError: Timed out\n");
SDL_Halt();
}
}
} else {
PRINTF("\nError: Timed out\n");
SDL_Halt();
}

PRINTF("\n\n************ Welcome to SDT Phone System ************\n");
PRINTF("\nphone -> ");
}

/*---+-------------------------------------------------------
xCloseEnv extern
-----------------------------------------------------------*/
#ifndef XNOPROTO
void
xCloseEnv( void )
#else
void
xCloseEnv()
#endif
{
close(Out_Socket);
close(In_Socket);
unlink(Connected_Socket_Addr.sun_path);
unlink(Connection_Socket_Addr.sun_path);
PRINTF("\nClosing this session.\n");
}
/*---+-------------------------------------------------------
xInEnv extern
-----------------------------------------------------------*/
#ifndef XNOPROTO
void
xInEnv( SDL_Time Time_for_next_event )
#else
void
xInEnv( Time_for_next_event )
SDL_Time Time_for_next_event;
#endif
{
struct timeval t;
fd_set readfds;
char *Instr;
int NrOfReadChars;
char SignalName = '\0';
xSignalNode yOutputSignal;
int i = 0;
char chr = '\0';

t.tv_sec = 0;
t.tv_usec = 1000;
FD_ZERO(&readfds);
#ifndef XMONITOR
FD_SET(1,&readfds);
#endif
FD_SET(In_Socket,&readfds);
if ( select(getdtablesize(),&readfds,0,0,&t) > 0 ) {
#ifndef XMONITOR
/*SDL-signal TermInput */
if FD_ISSET(1, &readfds) {
Instr = (char *)xAlloc(132);
Instr[0]='L';
Instr++;
(void)gets(Instr);
yOutputSignal = xGetSignal(TermInput, xNotDefPId, xEnv);
xAss_SDL_Charstring(
&((yPDP_TermInput)(OUTSIGNAL_DATA_PTR))->Param1, --Instr,XASS);
SDL_Output(yOutputSignal, (xIdNode *)NIL);
xFree((void**)&Instr);
}
#endif
if FD_ISSET(In_Socket, &readfds) {
Instr = (char *)xAlloc(151);
do {
read(In_Socket, &chr, 1);
Instr[i++] = chr;
} while ( chr!='\0' );
sscanf(Instr, "%c", &SignalName);

if ( SignalName == 'M' ) {
/* SDL-signal Message */
yOutputSignal = xGetSignal(Message, xNotDefPId, xEnv);
sscanf(
Instr+1,
"%d %x%n",
&(((yPDP_Message)(OUTSIGNAL_DATA_PTR))->Param2.GlobalNodeNr),
&(((yPDP_Message)(OUTSIGNAL_DATA_PTR))->Param2.LocalPId),
&NrOfReadChars);
xAss_SDL_Charstring(
&((yPDP_Message)(OUTSIGNAL_DATA_PTR))->Param1,
(Instr+NrOfReadChars+2),XASS);
SDL_Output(yOutputSignal, (xIdNode *)NIL);
}
else if ( SignalName == 'T' ) {
/* SDL-signal Terminate */
yOutputSignal = xGetSignal(Terminate, xNotDefPId, xEnv);
sscanf(
Instr+1,
"%d %x",
&(((yPDP_Terminate)(OUTSIGNAL_DATA_PTR))->Param1.GlobalNodeNr),
&(((yPDP_Terminate)(OUTSIGNAL_DATA_PTR))->Param1.LocalPId));
SDL_Output(yOutputSignal, (xIdNode*)0);
}
xFree((void**)&Instr);
}
}
}

/*---+-------------------------------------------------------
xOutEnv extern
-----------------------------------------------------------*/
#ifndef XNOPROTO
void
xOutEnv( xSignalNode *S )
#else
void
xOutEnv( S )
xSignalNode *S;
#endif
{
char Outstr[150];

/* SDL-signal Message */
if ( (*S)->NameNode == Message ) {
sprintf(Outstr,
"M %d %x %.*s",
((yPDP_Message)((*S)))->Param2.GlobalNodeNr,
((yPDP_Message)((*S)))->Param2.LocalPId,
strlen(((yPDP_Message)((*S)))->Param1),
((yPDP_Message)((*S)))->Param1);
write(Out_Socket, Outstr, strlen(Outstr)+1);
xReleaseSignal(S);
return;
}
/* SDL-signal Terminate */
if ( (*S)->NameNode == Terminate) {
sprintf(Outstr,
"T %d %x",
((yPDP_Terminate)((*S)))->Param1.GlobalNodeNr,
((yPDP_Terminate)((*S)))->Param1.LocalPId);
write(Out_Socket, Outstr, strlen(Outstr)+1);
xReleaseSignal(S);
return;
}
/* SDL-signal Display */
if ( (*S)->NameNode == Display ) {
sprintf(Outstr, "\ndisplay ->%.*s",
strlen(((yPDP_Display)((*S)))->Param1),
((yPDP_Display)((*S)))->Param1+1);
PRINTF(Outstr);
PRINTF("\nphone -> ");
xReleaseSignal(S);
return;
}
}
#endif


58 ASN.1 Encoding and De-coding in the SDL Suite

This chapter is a reference manual for the ASN.1 encoding and decoding support in the SDL Suite. The support will help you to create applications and simulators that can both produce and decode protocol data units with bit patterns according to ASN.1 specifications and ASN.1 encoding rules. The SDL Suite supports BER (Basic Encoding Rules) and PER (Packed Encoding Rules).

In order for you to fully take advantage of this reference chapter, you should be familiar with the SDL Suite and the basics of ASN.1.

Note:

This chapter is not intended to describe the ASN.1 syntax or the general theory about ASN.1 encoding and decoding. This information can be found in the standard documents from ITU and from books about ASN.1.


Introduction

Supported Standards

The following standards are supported:

  • ASN.1 according to ITU X.680, X.681, X.682 and X.683, 1997 version
  • BER (Basic Encoding Rules) according to ITU X.690, 1997 version
  • Basic PER (Packed Encoding Rules) according to ITU X.691, 1997 version, both aligned and unaligned variants.

Restrictions are listed in the Known Limitations chapter in the Release Guide.

Overview

The Abstract Syntax Notation One (ASN.1) is a notation language that is used for describing structured information that is intended to be transferred across some type of interface or communication medium. It is especially used for defining communication protocols.

SDL is suitable for specifying the semantic actions of a protocol, something that ASN.1 does not cover.

By using ASN.1 data types in the implementation of your application, you will optimize your development process. The following list displays some of the advantages of ASN.1:

  • ASN.1 is a standardized, vendor-, platform- and language independent notation.
  • A vast number of telecommunication protocols and services are defined using ASN.1. This means that pre-defined ASN.1 packages and modules are available and can be obtained from standardization organizations, RFCs, etc.
  • When ASN.1 data types are transmitted over computer networks, their values must be represented in bit-patterns. Encoding and decoding rules determining the bit-patterns are already defined for ASN.1. The SDL Suite supports BER and PER encoding.

The SDL Suite support for ASN.1 consists of two major parts:

  • An ASN.1 to SDL translator, ASN.1 Utilities, which allows you to use the ASN.1 types in your SDL systems.
  • ASN.1 coders that will automatically encode your SDL values to bit-patterns and decode from bit-patterns to SDL values.

You can access the ASN.1 coders from SDL diagrams as well as from the C code.

Before you start the encoding and decoding steps, you must perform some preliminary steps. These are presented in Tutorial: Using ASN.1 Data Types.

Related Documents

Additional information about using ASN.1 and about encoding and decoding can be found in:

  • Tutorial: Using ASN.1 Data Types
  • 14 The ASN.1 Utilities
  • 57 Building an Application
  • 65 The Cmicro SDL to C Compiler


Basic Concept

ASN.1 is suitable for specifying the information in a protocol and SDL is suitable for describing the semantic actions of a protocol. They are often used by standard bodies to specify protocol standards.

One of the main ideas behind ASN.1 is that you should be able to work with information in the protocol in the same way as you work with types and values in your implementation language. It should not be more difficult to create a bit-pattern in a protocol data unit then it is to assign a value to a variable. The encoder and decoder functions will automatically deal with all the details about bit-patterns and bit-layouts.

ASN.1 Utilities

The ASN.1 to SDL translator, ASN.1 Utilities, translates ASN.1 types and constants into SDL types and constants. An ASN.1 module generates an SDL package. This allows you to work with translated types and constants in the same way as any SDL type or constant. For instance, you can use them when you declare variables and when you declare signal parameters.

Information about ASN.1 to SDL translation and C representation of SDL data types is available in:

  • 14 The ASN.1 Utilities
  • Data Types

Encoding and Decoding

Encoding and decoding functionality consists of several parts.

First of all, it is the encoding and decoding algorithms themselves. You encode a variable or signal parameter into a bit-pattern by calling the encoder functions. You decode a bit-pattern into a variable or signal parameter by calling the decoder functions.

Another integral part of the coding functionality is the buffer handling. The decoder function takes the bit-pattern from the buffer and creates values for the application. The encoding function takes the internal value and encodes it into a sequence of bits in the buffer.

Error handling functionality is also present in the coding framework. Several types of errors can occur when encoding and decoding, such as buffer errors, incorrect values, decoding errors. Error handling functions allow to handle all possible erroneous situations.

Coding Access Interfaces

The coding functionality has got several access interfaces that allow you to access it in different ways.

It is possible to access encoding and decoding functions, call buffer functions and check error codes directly from the SDL diagram or from the C code in the environment files. For the C access interface, calls to encoder and decoder functions together with the appropriate buffer access procedures can be generated automatically if a few options in the user interface has been selected.

Basic SDL Interface and Extended SDL Interface

In SDL, you can use the basic interface or the extended interface. The basic interface is easy to use but gives you no possibility to control the buffer management. The extended interface gives you flexibility that the basic interface lacks.

The basic interface contains encode and decode functions which operates at SDL octet strings. The extended interface adds the possibility to access the buffer interface from within SDL and operates at a new type call CoderBuf. Furthermore, the extended interface contains a new type called CustomCoderBuf with which you could implement your own mapping between SDL and the encode and decode functions.

Within an SDL system, it is only possible to use one type of SDL interface. Either the SDL Basic Interface, the SDL Extended Interface with CoderBuf or the SDL Extended Interface with CustomCoderBuf.

C Code Interface

The coder library contains encoding and decoding functions and also several help functions for buffer management, error management and printing information. If you choose to call encoding and decoding from outside the environment files, note that:

  • You need a file named <ASN.1 module>.ifc with necessary C declarations of types, literals and operators. The SDL to C Compiler generates this file if you have added the ASN.1 module to your SDL system with a use package clause.
  • You need generated C files and static kernel C files. These files will be present if you have generated an SDL system with your ASN.1 module.

General information about using .ifc files and writing C code with SDL is available in:

  • 57 Building an Application
  • 65 The Cmicro SDL to C Compiler


Solution

This section describes the structure and design of the encoding and decoding support in the SDL Suite. It is intended to give you an understanding of the solution.

Functionality

The main goal is to help you to develop executable files, applications or simulators, that can:

  • produce BER/PER bit patterns
  • consume and decode BER/PER bit patterns
  • be configured to work with user specific environment (memory management, buffer management and error handling)

ASN.1 coder framework contains the following functional modules:

  • Encoding and decoding functionality (see "Encoding and Decoding Functionality" )
  • Buffer Management System (BMS) (see "Buffer Management System" )
  • Memory Management System (MMS) (see "Memory Management System" )
  • Error Management System (EMS) (see "Error Management System" )
  • Debug print opportunities (see "Printing Opportunities" )

All these modules will be described in more details in this chapter.

Figure 495 : Relationship between functional modules of the encoding/decoding solution

Functionality Access Interfaces

When using the coder functionality, you can choose between different access interfaces. They all share the same implementation.

  • Basic SDL interface
    SDL operators that put bytes in octet strings and read bytes from octet strings. Buffer access functions are not visible in this SDL interface. For more information see "Encoding/decoding the SDL Basic Interface" .
  • Extended SDL interface
    SDL encode and decode operators that put bytes in the types CoderBuf and CustomCoderBuf. Parts of the buffer management is visible in the interface. For more information see "Encoding/decoding the SDL Extended Interface" .
  • C code interface
    This interface is used when calling the coders from C code, for example in the environment files. For more information see "C Encoding and Decoding Interface" .

The SDL and C interfaces are not identical. They are adapted to the properties of the languages.

It is preferred to access the coders from SDL when the encoded bit-pattern must be further processed in the SDL system. One interesting example is when the bit pattern is sent in a signal to another process.

It is preferred to access the coders in C-code in the environment files when the SDL-system does not process the bit pattern internally, for example when sending it to a protocol in the environment.


Encoding and Decoding Functionality

Encoding and Decoding Functions

An encoding function encodes an SDL variable or signal parameter into a bit-pattern according to BER or PER. A decoding function decodes from a PER or BER bit-pattern to an SDL variable or signal parameter. You can access the encoding and decoding functions either from the C code (see "C Encoding and Decoding Interface" ) or from SDL diagrams (see "SDL Encoding and Decoding Interfaces" ).

C Encoding and Decoding Interface

The most common example of implementing coders in C is in the environment file. The SDL to C Compiler automatically generates an environment file with all needed calls. The coders can be accessed from any function or module implemented in C code.

There is one set of functions for BER and one set of functions for PER. The functions are accessed by using macros BER_ENCODE and BER_DECODE, respectively PER_ENCODE and PER_DECODE.

There is also a set of common functions which choose encoding rules dynamically according to the parameter written to the buffer by function BufSetRule(buffer, rule), see "Buffer Management Functions" . The functions are accessed by using macros ASN1_ENCODE and ASN1_DECODE.

Example 450 Dynamic encoding rules configuration

BufInitWriteMode(buf);
BufSetRule(buf, er_PER | er_Aligned);

/* PER Aligned will be applied */

ASN1_ENCODE( buf, (tASN1TypeInfo *)&yASN1_MyType1,
(void *)&((yPDP_Sig1)(*S))->Param1));
BufSetRule(buf, er_BER | er_Definite);

/* BER Definite will be applied */

ASN1_ENCODE( buf, (tASN1TypeInfo *)&yASN1_MyType2,
(void *)&((yPDP_Sig2)(*S))->Param1));
BufCloseWriteMode(buf);

All the encode and decode macros, ASN1_ENCODE,ASN1_DECODE, BER_ENCODE, BER_DECODE, PER_ENCODE and PER_DECODE have three parameters:

  • First parameter:
    The first parameter is a reference to a buffer of type tBuffer (see "Types and definitions" ). During encoding the resulting bit pattern will be stored in a memory section associated with the buffer. The buffer must be in the write mode when the encode function is called, because it writes bytes to the buffer. During decoding a bit pattern will be read from a memory section associated with the buffer. The buffer must be in read mode when the decode function is called, because it reads bytes from the buffer. For more information about buffer handling see "Buffer Management System" .
  • Second parameter:
    Pointer to ASN.1 type information (see "ASN.1 Type Information Generated by ASN.1 Utilities" ). All information that is needed about the type in the ASN.1 specification is represented in this type information. The reference to type information is of type tASN1TypeInfo*. The type information structure is a global variable with a name yASN1_<type name>. The reference to the type information structure is then (tASN1TypeInfo*)&yASN1_<type name>.
  • Third parameter:
    Memory pointer to variable or signal parameter to encode or decode. The memory pointer is of type void* .

The buffer macro returns an error code which is a literal from an enumerated type (see "Error codes" ). The return value indicates whether the encoding or decoding procedure was successful or not. If this value is ec_SUCCESS, then procedure was successful.

Example 451 : BER encoding of signal parameter

In ASN1:

Message ::= SEQUENCE {
id INTEGER,
info INFOTYPE
}

In SDL:

SIGNAL Sig2(Message);

In xOutEnv:

BufInitWriteMode(buf);
BER_ENCODE( buf,
(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(*S))->Param1));
BufCloseWriteMode(buf);

Example 452 : PER encoding of signal parameters

In xOutEnv:

BufInitWriteMode(buf);
PER_ENCODE( buf,
(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(*S))->Param1));
BufCloseWriteMode(buf);

Example 453 : BER decoding of signal parameters

In xInEnv:

BufInitReadMode(buf);
BER_DECODE( buf,
(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(S))->Param1));

BufCloseReadMode(buf);

Example 454 : PER decoding of signal parameters

In xInEnv:

BufInitReadMode(buf);
PER_DECODE( buf,
(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(S))->Param1));

BufCloseReadMode(buf);

ASN.1 Type Information Generated by ASN.1 Utilities

The encoder and decoder functions need information about the types from the ASN.1 specifications. This information is stored in type information structures, called type information nodes or simply type nodes. Almost all information about the types that you can find in the ASN.1 specifications is stored in the type information nodes.

The internal structure of the type information nodes is important in an implementation of encoding and decoding functions, but not from the application that calls the functions. There, it is only important to find a reference to a node. The internal details of the type nodes are not described in this section.

The type information nodes are represented in C code as a set of global read-only variables. The information in a node cannot be changed during execution. The nodes are linked to each other by using memory references. The type nodes can be declared as const variables by defining a macro, which means that in some application they can be moved to program memory or read only memory. For more information, see "Compilation switches" .

The name of a node is yASN1_<type name>. A reference to a type node is simply a memory pointer to the type node cast to a basic type node declaration.

Example 455 : Reference to a type node

If the type name is Pdu1 in the ASN.1 specification, the reference to the type node is:
(tASN1TypeInfo*)&yASN1_Pdu1.

The nodes reflect the information in ASN.1 specifications and must be generated by ASN.1 Utilities. ASN.1 Utilities parses and analyzes the ASN.1 information and generates C code containing type nodes. One .c-file and one .h file per ASN.1 module is generated and the files are named <module name>_asn1coder.c and <module name>_asn1coder.h.

SDL Type and Operator Information Generated by the SDL to C Compiler

The encoder and decoder functions also need information generated by the SDL to C compiler, for example declarations of operators and literals for manipulating the translated ASN.1 types. This information is also stored in the type nodes.

ASN.1 utilities generates one SDL package for each ASN.1 module. The SDL to C Compiler generates one .c and .h file for each package, with type and operator information, together with one .ifc file for an external view of the types and operators. For more detailed information about the C code generation see "System Interface Header File" .

The ASN.1 type information files includes the <package>.ifc files. All relationships are resolved during compile and link time and the information is read-only at execution time.

SDL Encoding and Decoding Interfaces

In the SDL interface, the ASN.1 type information pointer is not seen. It is implicit and derived from the type of the memory pointer.

There are two types of coder interfaces available from within an SDL system: SDL basic interface (see "Encoding/decoding the SDL Basic Interface" ) and SDL extended interface (see "Encoding/decoding the SDL Extended Interface" ). In the SDL basic interface, the buffer reference is replaced with an octet_ string and the encoded bit-pattern is put directly in a variable of octet_string type. In the SDL extended interface, the buffer reference is CoderBuf or CustomCoderBuf.

Encoding/decoding the SDL Basic Interface

You can encode and decode directly from the SDL diagram by using the operators encode and decode.

The syntax of the encode function is:

result:= encode(encoded_octet_string, ASN1_variable)

The two parameters of the encode function are defined as:

  • encoded_octet_string is an Octet_string that contains the encoded value of the ASN1_variable if the encoding was successful.
  • ASN1_variable is the ASN.1 variable to be encoded.

The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see "SDL error interface" .

The encoded value in the octet string could then be used in a signal sent to an other part of the system or to the environment.

Figure 496 Example of a encode call in an SDL diagram

The syntax of the decode function is:

result:= decode(octet_string_to_decode, ASN1_variable)

The two parameters of the decode function are defined as:

  • octet_string_to_decode is an Octet_string that contains the encoded value to decode.
  • ASN1_variable is the ASN.1 variable that will contain the result after the decoding was performed.

The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see "SDL error interface" .

Figure 497 Example of a encode call (SDL Basic Interface)

Encoding/decoding the SDL Extended Interface

As with the Basic SDL Interface you can encode and decode directly from the SDL diagram by using the operators encode and decode.

The syntax of the encode function is:

result:= encode(CoderBuf, ASN1_variable)

The two parameters of the encode function are defined as:

  • CoderBuf is a type defined in the file CoderBuf.sdl . It is a mapping of the buffer management C-interface (see "C interface to buffer management system" ). For more information about operations at CoderBuf see "SDL CoderBuf interface" .
  • ASN1_variable is the ASN.1 variable to be encoded.

The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see "SDL error interface" .

Figure 498 : Example of en encode call (SDL Extended interface)

The syntax of the decode function is:

result:= decode(CoderBuf, ASN1_variable)

The two parameters of the decode function are defined as:

  • CoderBuf is a type defined in the file CoderBuf.sdl. It is a mapping of the buffer management C-interface (see "C interface to buffer management system" ). For more information about operations at CoderBuf see "SDL CoderBuf interface" .
  • ASN1_variable is the ASN.1 variable that will contain the result after the decoding was performed.

The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see "SDL error interface" .

Figure 499 : Example of decode call (SDL Extended Interface)

How to Include the Extended SDL Interface in Your System

Add the package in the Organizer. In the directory <installation_directory>/sdt/include/ADT/ there are two versions of the BufferInterface package. One for C, CoderBuf.sun, and one for C++, CoderBufCPP.sun . When the package is included in the Organizer, add a use statement of the BufferInterface in your system.

Note: Types in the BufferInterface package

In the BufferInterface package BasicCTypes and CPointer or the corresponding C++ versions of those files are included. This must be considered when using cpp2sdl together with your system so that those files are included only once.

The Extended SDL Interface in the Simulator

You can display the value of a CoderBuf and change it when running the Simulator by using the commands examine-variable and assign-variable. If you have written your own buffer you can add information in the provided files to be able to use them in the Simulator, see below.

Examine CoderBuf

Command: ex-va encode_buffer

encode_buffer (CoderBuf) = bms_UserBuffer(NM)3'020102'H

bms_UserBuffer is the buffer type, (NM) shows the current mode of the coderbuffer(NoMode, ReadMode or WriteMode), 3 is the length of the coder buffer value in bytes and '020102'H is the value of the coder buffer in octet string form

Limitations:

Examining the value when the coder buffer is in Write Mode is not possible.

If the user has defined a new buffer type other than Small Buffer and User buffer the buffer type will not be displayed.

Example:

encode_buffer (CoderBuf) = BufferType(NM)3'020102'H

To display the right buffer type the user has to do some modifications in the write function (yWri_CoderBuf) in the file CoderBuf.sdl.

Only the first 100 bytes of a coder buffer value are displayed during simulation.

Assign new values to a coder buffer:

Command: ass-va encode_buffer 2 '0101'H ReadMode(RM)

Value assigned:

encode_buffer (CoderBuf) = bms_UserBuffer(RM)2'0101'H

When you assign value to a coder buffer:

Command: ass-va <length> <value> <Mode>

Length is the length of the value in bytes. Value is the new value (octet string). Mode, the user sets the mode of the coder buffer (Read, Write and No).

In order for the assignment to be successful the user has to give the two first parameters; otherwise the command will not be executed. An error message will be displayed to the user.

If the length of the value passed as parameter is less than the length passed as parameter, extra zeros (0) are added to the octet string to match the length passed by the user. If the length of the value passed as parameter is greater than the length passed as parameter, then the octet string to be assigned will be cut to match the length.

If the user does not choose the buffer mode, the buffer mode will be set to No Mode (default).

Limitations:

If the user has defined a new buffer type other than Small Buffer and User buffer, the user has to do some modifications in the read function (yRead_CoderBuf) in CoderBuf.sdl in order to initiate the new coder buffer to be assigned to the old coder buffer with right coder buffer type.

The maximum size of the coder buffer is assumed to be 128 Mega bytes.


Buffer Management System

Figure 500 : Relationship between coders and buffer management

The buffer interface is a set of functions that operates with data. Buffer management stores data in the buffer memory. Data is presented as byte, bit or character segment. Available basic operations are get, put, peek and skip. The buffer interface also opens a possibility for direct access to buffer memory from BMS environment (from encode and decode). According to this there is direct access to the buffer memory which presented as one continuos piece.

The buffer management functions have an open design, where it is possible to choose between different buffer implementations with different characteristics. This choice is available in runtime mode and also within compilation by switches defined in "Buffers configuration" . This is possible due to an open and specified buffer interface that all encode and decode functions use and that your SDL specifications and C functions should use as well. The interface is specified as a set of C macros. See "C interface to buffer management system" for more information. The buffer management implements all the macros in the interface.

The buffer management is accessed from an SDL system by using operators in the buffer management Abstract Data Type. The operators are mapped to the open buffer management interface.

The only buffer management implementation at present in the SDL Suite is the small buffer (see "Small Buffer Implementation" ).

C interface to buffer management system

This chapter describes the open buffer interface. This is the C access interface to the buffer management.

Types and definitions

The buffer access type is tBuffer. tBuffer is defined as a pointer to a structure tCoder.

Example 456 : Buffer as a reference

tBuffer buf = NULL;
BufInitBuf(buf, bms_SmallBuffer);

tCoder is used as access type only in tiny mode (see Example 466).

BMS introduces several specific types which are described below.

tBMSLength

BMS length type is defined as unsigned long.

tBMSUserMemory

This type is structure describing information about memory provided by the user. It contains three fields:

  • MemSize of type tBMSLength - size of the provided memory
  • DataLength of type tBMSLength - size of the data written to the provided user memory
  • MemPtr of type void * - pointer to the provided memory

This type is used as parameter type in the buffer interface functions BaseBufInitBufWithMemory and BaseBufCloseBufToMemory.

tBMSBufType

This type is an enumeration describing all following possible types of buffers. Two types of buffers are available:

  • bms_SmallBuffer - predefined buffer type (see "Small Buffer Implementation" )
  • bms_UserBuffer - type denoting user defined buffer (see "User defined Buffer Handling" )

This type is used for specifying the type of buffer which will be used.

tERRule

This type is an enumeration describing possible kinds of encoding rules. It contains basic rules (BER, PER, etc.) as well as their different variations:

  • er_BER
  • er_Definite
  • er_Indefinite
  • er_PER
  • er_Aligned
  • er_Unaligned
  • er_NoEndPad - PER without end padding
  • er_UER - User defined encoding rules
  • er_NoRule

The enumeration values are regarded as bit masks for different kinds of encoding rules, for example, PER Aligned can be specified with er_PER | er_Aligned; expression ( SpecifiedRule & ( er_PER | er_Aligned ) ) will check if the specified type of encoding rules SpecifiedRule is PER Aligned.

tBMSMode

This type is an enumeration describing possible modes for the buffer:

  • bms_ReadMode - reading mode, writing is allowed for appending. See BufSetAppendBufFunc( buffer, func ) for more information.
  • bms_WriteMode - writing mode, reading is not allowed
  • bms_NoMode

Buffer Management Functions

The buffer management functions put bytes and bits into a buffer which you can use to send over a protocol. The buffer management also provide several interfaces to operate with buffer memory and buffer handling.

The internal implementation of the buffer is not shown in the buffer interface, thus all manipulation of the buffer should be done using the macros. A buffer must be created before use. It must be opened before a read/write session and closed after a session. A buffer can be in either a read mode or a write mode, but not in both modes at the same time.

The open buffer interface macros are described below (parameter buffer in all functions is of type tBuffer, see "Types and definitions" ):

  • BufInitBuf( buffer, buffer_type )
    This function is used to initialize the buffer management. Memory used by the buffer is allocated by CUCF_ALLOC function, so memory management used in the buffer handling can be configured by means of MMS configuration opportunities (see "User defined Memory Handling" ). The second parameter is the type of the buffer (see "tBMSBufType" ). The function returns error status (see "Error codes" ).
  • BufCloseBuf( buffer )
    Closes a buffer and if the buffer has not been initialized by the user memory, releases buffer memory by using CUCF_FREE. The function returns error status (see "Error codes" ).
  • BufInitBufWithMemory( buffer, buffer_type, user_memory)
    This function initializes the buffer with the user memory provided in the third parameter (see "tBMSUserMemory" ) without allocating any memory. If user memory contains any encoded data, the buffer can be used further by the decode function. The second parameter is the type of the buffer (see "tBMSBufType" ). The function returns error status (see "Error codes" ).
  • BufCloseBufToMemory( buffer, user_memory )
    This function closes the buffer. It does not release any memory, but returns it in the user_memory parameter of type "tBMSUserMemory" passed by reference. The function returns error status (see "Error codes" ).
  • BufGetMemory( buffer, length )
    Returns pointer to the buffer memory. The second parameter is used for returning. It is pointer to the length of memory.
  • BufAppendMemory( buffer, append_length )
    Used for the appending of the buffer memory with required append_length. Returns pointer to the beginning of the memory (root).
  • BufGetDataCurr( buffer, bit_position )
    Returns current data pointer in the buffer handling. The second parameter is used for returning. It is a pointer to a char with current bit position in the buffer handling. This function is used by the decoder.
  • BufSetDataCurr( buffer, length, bit_position )
    Used to increment current data pointer by length in the buffer handling and also sets current bit position to bit_position there. This function is used by the decoder.
  • BufGetDataEnd ( buffer, bit_position )
    Returns end data pointer in the buffer handling. The second parameter is used for returning. It is a pointer to a char with the end bit position in the buffer handling. This function is used by the encoder and decoder.
  • BufSetDataEnd ( buffer, length, bit_position )
    Uses to increment end data pointer by length in the buffer handling and also sets end bit position to bit_position there. This function is used by encoder.
  • BufCopyBuf( buffer_dst, buffer_src )
    This function copies the source buffer buffer_src to target buffer buffer_dst. The function returns error status (see "Error codes" ).
  • BufInitReadMode( buffer )
    Prepares the buffer for read operations (read mode, see "tBMSMode" ) and puts the current pointer to the start of the buffer data. The buffer content is not changed or released. The function returns error status (see "Error codes" ).
  • BufCloseReadMode( buffer )
    Closes read mode for the buffer. The buffer content is not changed or released. The function returns error status (see "Error codes" ).
  • BufCloseDeleteReadMode( buffer )
    Closes read mode for the buffer and logically (without memory releasing) removes read bytes from buffer. Bytes that are not read are still in the buffer. The function returns error status (see "Error codes" ).
  • BufInitWriteMode( buffer )
    Prepares the buffer for write operations (write mode, see "tBMSMode" ) and sets the current pointer to the start of the buffer. Previous information in buffer is logically lost (the bytes are still there but they are considered to be empty). The function returns error status (see "Error codes" ).
  • BufCloseWriteMode( buffer )
    Closes write mode for the buffer. The buffer content is not changed or released. The function returns error status (see "Error codes" ).
  • BufGetBufType( buffer )
    Returns the type of the buffer, see "tBMSBufType" . It can be useful when the system supports more than one buffer interface and the type of the buffer is not obvious and can change dynamically.
  • BufGetDataLen( buffer )
    Returns the byte length (see "tBMSLength" ) of all data that is physically present in the buffer.
  • BufGetDataBitLen( buffer )
    Returns the bit length (see "tBMSLength" ) of all data that is physically present in the buffer.
  • BufGetReadDataLen( buffer )
    Returns the byte length (see "tBMSLength" ) of the information which has been read from the buffer.
  • BufGetReadDataBitLen( buffer )
    Returns bit length (see "tBMSLength" ) of the information which has been read from the buffer.
  • BufGetValueLen( buffer )
    Returns byte length (see "tBMSLength" ) of the last value encoded to the buffer or decoded from the buffer.
  • BufGetValueBitLen( buffer )
    Returns bit length (see "tBMSLength" ) of the last value encoded to the buffer or decoded from the buffer.
  • BufGetMode( buffer )
    Returns buffer mode, see "tBMSMode" .
  • BufInReadMode( buffer )
    This is a boolean function returning true if the buffer is in the read mode (see "tBMSMode" ).
  • BufInWriteMode( buffer )
    This is a boolean function returning true if the buffer is in the write mode (see "tBMSMode" ).
  • BufInNoMode( buffer )
    This is a boolean function returning true if the mode of the buffer is not defined.
  • BufSetRule( buffer, rule )
    This function sets the encoding rules to the buffer. Each setting overrides the previous. They are checked later in the encode and decode functions. The second parameter is combination of encoding rule masks of type tERRule (see "tERRule" ), it is automatically cast to unsigned long, which is the type of the second parameter. For example, PER without end padding encoding rule is set with an expression BufSetRule(er_PER | er_NoEndPad). If not a complete set of rules is specified then BufSetRule will use default settings, for example BufSetRule(er_PER) is used (without bit masks er_Aligned, er_Unaligned and er_NoEndPad), then default PER variant will be applied which is configured by compilation switches, see "Compilation switches" . The BufGetRule will return the encoding rules including those that have been applied depending on default settings.
  • BufGetRule( buffer )
    This function returns value of type unsigned long which can be checked by binary "AND" operation with bit masks of type ERRule (see "tERRule" ), for example, (SpecifiedRule & er_PER) returns true if specified rule is PER.

Caution! Checking specified encoding rules

unsigned long SpecifiedRule = BufGetRule( buffer );

( SpecifiedRule & er_PER & er_Aligned ) is not a correct check for PER Aligned.

( SpecifiedRule & ( er_PER | er_Aligned ) ) should be used instead.

  • BufGetUserData( buffer )
    This function returns a reference to the user data defined by tUserData type (see "User Data" ).
  • BufSetErrInitFunc( buffer, func )
    This function sets a reference to the user error handling function. The interface is available only if CODER_REMOVE_PATH compile switch is absent (see "Error handling configuration" ).
  • BufGetErrInitFunc( buffer )
    This function returns a reference to the user error handling function. NULL is returned if the function has not been set. The interface is available only if CODER_REMOVE_PATH compile switch is absent (see "Error handling configuration" ).
  • BufGetErrorPath( buffer )
    This function returns a reference to the tErrorPath structure that contains a path of fields from the root type up to the field where an error has occurred. The C-representation of the tErrorPath is:
typedef struct
{
void* Fields[CODER_PATH_DEEP];
unsigned long NumOfFields;
...
} tErrorPath;
where CODER_PATH_DEEP is the maximum number of nested types, see "Error handling configuration" . It is used within the user error handling function. The interface is available only if CODER_REMOVE_PATH compile switch is absent (see "Error handling configuration" ). The first element in the Fields array is a reference to the root Type Info - tASN1TypeInfo*. The next element might be one of the following:
tASN1Component* - for the SEQUENCE/SET component
tASN1Alternative* - for the CHOICE alternative
tASN1Object* - for an open object
long* - for the SEQUENCE OF/SET OF item index
  • BufGetMainVal( buffer )
    This function returns a reference to the encode/decode value and it is used in the user error handling to assign the default contents to the value if an error has occurred. The interface is available only if CODER_REMOVE_PATH compile switch is absent(see "Error handling configuration" ).
  • BufSetErrorCode( buffer, error_code )
    This function sets an error code (see "Error codes" ) to the buffer.
  • BufGetErrorCode( buffer )
    This function returns an error code (see "Error codes" ).
  • BufGetByte( buffer )
    Reads one byte from the buffer and returns it in a variable of type unsigned char after logically removing it from the buffer. The byte that has been returned will not be read from the buffer once again by another reading procedure. This function returns unsigned char.
  • BufPeekByte( buffer )
    Takes one byte from the buffer and returns it in a variable of type unsigned char without removing it from the buffer. The byte that has been returned can be peeked from the buffer any number of times. This function returns unsigned char.
  • BufPutByte( buffer, byte )
    Puts one byte from the second parameter of type unsigned char to the buffer.
  • BufGetSeg( buffer, length )
    Reads a segment of length (see "tBMSLength" ) bytes from a buffer and returns a segment pointer that points at the start of the retrieved segment. Note that this pointer should not be freed, because it is pointing into the memory segment of the buffer. The segment that has been returned will not be read from the buffer once again by another reading procedure. This function returns unsigned char*.
  • BufSkipSeg( buffer, length )
    Skips length (see "tBMSLength" ) bytes from the buffer.
  • BufPeekSeg( buffer, length )
    Takes length (see "tBMSLength" ) bytes from the buffer and returns a segment pointer from buffer without moving current pointer in a variable of type unsigned char*. The segment that has been returned can be peeked from the buffer any number of times. Note that this pointer should not be freed, because it is pointing into the memory segment of the buffer.
  • BufPutSeg( buffer, segment, length )
    Puts a whole segment of length (see "tBMSLength" ) bytes to the buffer. The second parameter segment is of type unsigned char* and is a pointer to the segment start.
  • BufGetBit( buffer )
    Reads one bit from the buffer and returns it in a variable of type unsigned char after logically removing it from the buffer. The bit that has been returned will not be read from the buffer once again by another reading procedure. This function returns unsigned char, where returned bit is the right-most bit in the unsigned char value.
  • BufPutBit( buffer, bit )
    Puts one bit which is the right-most bit of function parameter of type unsigned char to the buffer.
  • BufGetBits( buffer, number )
    Reads number bits from the buffer and returns them in number right-most bits in a variable of type unsigned long after logically removing them from the buffer. The bits that have been returned will not be read from the buffer once again by another reading procedure. The second parameter number is of type unsigned char. Bits are returned in a variable of type unsigned long, so number should be less or equal to sizeof(unsigned long)*8.
  • BufPutBits( buffer, bits, number )
    Puts number right-most bits from a variable of type unsigned long to the buffer. Bits are passed in a variable of type unsigned long, so number should be <= sizeof(unsigned long)*8.
  • BufAlign( buffer )
    This procedure skips all the bits from the buffer till the end of the byte.
  • BufSetAppendBufFunc( buffer, func )
    Sets a reference to an append function. The append function is called when there are not enough bytes left in the buffer for a get operation and more bytes must be put into the buffer. Default is no append function.

Example 457 : Sending a buffer

unsigned char * data;
unsigned int datalen;

BufInitReadMode(buf);
datalen = BufGetDataLen(buf);
data = BufGetSeg(buf,datalen);
send_protocol(sa,data,datalen);
BufCloseReadMode(buf);

Example 458 : Receiving from protocol and putting in a buffer

unsigned char data[MAXSIZE];
unsigned int datalen;

BufInitWriteMode(buf);
datalen=1;
while(datalen>0) {
datalen = receive_protocol(sa,data,MAXSIZE,0);
if (datalen>0)
BufPutSeg(buf,data,datalen);
}
BufCloseWriteMode(buf);

You can write an append function that will be called when there are not enough bytes left in the buffer for a read operation. An example of when this can occur is during the execution of a decode function. The calling function calculates how many bytes that must be added to the buffer. The append function can choose to add more bytes than this. An append function can be called several times during a decode execution.

The buffer is in write mode when the append function is called and will automatically be set to read mode after the append function is finished. Do not use the BufInitWriteMode or BufInitReadMode macros in the append function.

If you want to add an append function for a buffer, then do the following steps:

  1. Implement a C-procedure for appending data to the buffer. The C-procedure must have parameters compatible with tBufAppendFunc.
typedef void (*tBufAppendBufFunc)(tBuffer buf, unsigned int len);
  2. Use the macro BufSetAppendBufFunc, with the buffer and the append procedure as input parameters, immediately after a call to BufInitBuf.

Example 459 : Buffer Append Procedure

void MyAppendBuf( tBuffer buf,
unsigned int minbytes );
{
/* receive at least minbytes from
protocol or sockets or ... */

BufPutSeg(buf,seg,len );
}

Setting appending function:

BufInitBuf(buf);
BufSetAppendBufFunc(buf,MyAppendBuf);

  • BufGetAppendBufFunc( buffer )
    Returns a reference to an append function. Returns NULL if the append function does not set.

Small Buffer Implementation

A small buffer has a memory segment, an array of unsigned char. The encoded bit patterns are written to this segment and the bit patterns to decode are read from it.

The buffer pointer is a pointer to a control structure and a data structure. The control structure and the data structure contains information and memory pointers that the small buffer uses.

In the data structure, there is a pointer that points at the beginning of the memory segment, a pointer that points at the end of the memory segment and a pointer that points at current position for a read or write operation.

Memory is allocated inside the small buffer implementation. An initial memory segment is allocated. The size of the initial segment is set by defining the macro CODER_SMALLBUF_SIZE, which has the default value equal to 0x1000, see "Buffers configuration" . When a memory segment is full and a bigger segment is needed, then a 2 times larger segment is allocated, the contents in the old segment copied and the old segment freed. The macros CUCF_ALLOC and CUCF_FREE are used for all memory allocation and de-allocation.

SDL Interface to Buffer Management System

SDL CoderBuf interface

In the Extended SDL Interface, encoded data is stored in the C-buffer interface. From SDL, this data is accessed via the SDL type CoderBuf. The interface is not a direct mapping of the C-interface. Some of the functions are not accessible from SDL. For more detailed information about C-interface to the buffer management system see "C interface to buffer management system" .

Below is a summary of the contents in the file CoderBuf.sdl.

Types

The SDL buffer interface type names are the same as the ones in the C buffer interface (see "Types and definitions" ). The following type is introduced in the SDL buffer interface

  • Type ptr_tBMSUserMemory is a pointer to tBMSUserMemory.

Operators

  • BufInitBuf : CoderBuf, tBMSBufType [-> int];
  • BufInitBufWithMemory : CoderBuf, tBMSBufType, ptr_tBMSUserMemory [-> int];
  • BufCloseBuf : CoderBuf [-> int];
  • BufCloseBufToMemory : CoderBuf, ptr_tBMSUserMemory [-> int];
  • BufInitReadMode : CoderBuf [-> int];
  • BufInitWriteMode : CoderBuf [-> int];
  • BufCloseReadMode : CoderBuf [-> int];
  • BufCloseDeleteReadMode : CoderBuf [-> int];
  • BufCloseWriteMode : CoderBuf [-> int];
  • BufGetDataLen : CoderBuf -> tBMSLength;
  • BufGetReadDataLen : CoderBuf -> tBMSLength;
  • BufGetByte : CoderBuf -> unsigned_char;
  • BufPeekByte : CoderBuf -> unsigned_char;
  • BufPutByte : CoderBuf, unsigned_char;
  • BufSetRule : CoderBuf, tERRule;
  • BufGetRule : CoderBuf -> tERRule;
  • BufCopyBuf : CoderBuf, CoderBuf [-> int];
  • BufPutSeg : CoderBuf, Octet_string, int;
  • BufGetSeg : CoderBuf, int -> Octet_string;
  • BufPeekSeg : CoderBuf, int -> Octet_string;

These operators are mapped to the C buffer interface functions, so the semantics of SDL operators is the same as described for the corresponding C procedures in "Buffer Management Functions" .

SDL CustomCoderBuf interface

If you want a solution of your own for accessing the coder library from within SDL, you can use CustomCoderBuf. This can be achieved by modifying the file CustomCoderBuf.sdl and writing two C-procedures. CustomCoderBuf can then be used in the calls of encode and decode instead of CoderBuf.

If only minor changes are of interest, you could copy the CoderBuf.sdl file to CustomCoderBuf.sdl as a start. Even when the goal is to make a completely new access interface, CoderBuf.sdl could be used as an example.

Implementing the procedures ASN1EncodeCustomBuf and ASN1DecodeCustomBuf in a file of your own, means that the file should then be included in the build process. For further information about parameters and return values of those procedures see the file cucf_er_sdt.h in the coder library. When CustomCoderBuf is selected in the user interface, the code generator generates code that calls those two procedures.

The procedures ASN1EncodeCoderBuf/ASN1DecodeCoderBuf and ASN1EncodeOctet/ASN1DecodeOctet could be seen as Telelogic Tau versions of a CustomCoderBuf. The first parameter in that implementation is CoderBuf and Octet_string respectively. When implementing your own CustomCoderBuf, you can select whatever type of this first parameter you want. However, it is important that the type defined in CustomCoderBuf.sdl file corresponds to the first parameter of the two above procedures.

The choice of using a custom implementation must be selected in the Analyzer dialog. See "Analyze SDL" .

User defined Buffer Handling

The coder library can be configured to work with user defined buffers. It is possible to write your own specific buffer handling procedures which will be invoked instead of the default buffer handlers.

All coder library buffer implementations are based on the open buffer interface approach which allows you to introduce user types of buffer management in the same style as, for example, predefined small buffer management implementation.

If you want to use your own buffers, then perform the following steps:

  1. Define the structure UserBufFuncs of type tBaseBuf (see "Types and definitions" ).
  2. Set the value bms_UserBuffer to the field BufType.
  3. Implement the buffer access functions and assign references to these functions to the corresponding fields of UserBufferFuncs. Buffer access functions should have compatible interfaces with the function pointer types defined for tBaseBuf structure in the file bms.h (see "Buffer Management System sub-directory" ) and should support the semantics of buffer access functions described in "Buffer Management Functions" .

Note: Buffer implementation example

The small buffer implementation is based on the open buffer interface and can be used as an example of a user defined buffer implementation. Looking into the files bms_small.h and bms_small.c in the installation (see "Buffer Management System sub-directory" ) will be helpful before starting the implementation.

  4. Compile coder library with CODER_USE_USERBUF compile switch, see "Buffers configuration" ,
  5. Compile and link the application with the user buffer handling functions and the defined structures.


Memory Management System

Figure 501 : Memory management

The coder solution contains memory management functions. There are only two basic functions used for memory management: alloc and free.

Memory management in the coder library consists of allocation and freeing of memory, and releasing of memory in case of errors.

Coder library contains two levels of memory access functions:

  • Pure allocation and freeing of memory - CUCF_ALLOC(size, type) and CUCF_FREE(ptr, size, type),
    • where size is of type size_t and represents the size of memory in bytes to be allocated,
    • type is not used (reserved for the future),
    • ptr is of type void* and is a pointer to the memory to be released.
  • Safe memory allocating and releasing - CUCFAlloc(info, size, type), CUCFFree(info, ptr, size, type) and CUCFRelease(info, ptr), where size, type and ptr are the same as for the previous memory handling functions. Apart from allocating, CUCFAlloc function saves a pointer to the allocated memory block in the internal stack, which is used for memory freeing in case of error. The first parameter info in these three memory handling functions is of type tEMSInfo* and it is a pointer to the stack where all allocated memory segments are stored. Safe functions use pure memory management functions for memory operations. CUCFAlloc calls CUCF_ALLOC for allocating memory for storage cell in the stack and for allocating size required bytes, CUCFFree frees memory pointed by ptr and also the corresponding stack cell.

Figure 502 : Memory management functions

Safe memory handling functions are used in those places where memory freeing procedure will not be performed in case of error, for example, in the coder library kernel. Pure memory handling functions are called from the safe functions. They are also called directly in those places where memory can still be released even after an error has occurred, for example, buffer memory allocation (memory is released by BufCloseBuf function).

Predefined Memory Handling

There are two types of predefined memory handling functions which can be used to perform allocation and freeing of memory:

  • SDL Suite memory handlers XALLOC and XFREE, see "Functions for Allocation and Deallocation" , and
  • standard malloc and free functions from <stdlib.h> which are the default memory handlers.

Users can also define their own application specific memory handling functions, see "User defined Memory Handling" .

The type of memory handler to be invoked for allocation and freeing of memory is configured when compiling coder library by compile switches, see "Memory management configuration" .

User defined Memory Handling

The coder library can be configured to work with user-specific memory handling procedures. It is possible to write your own allocate and free procedures, which will be invoked instead of the default memory handlers.

Note: Performance optimization

Fast memory handling, if applicable, can help optimize the performance of the executable quite a lot. One of the examples of fast memory handling is working with statically allocated memory instead of dynamically allocated in alloc and free procedures.

If you want to use your own memory handler, perform the following steps:

  1. Create file mms_user.h and insert definitions of macros USER_ALLOC_FUNC(size, type) and USER_FREE_FUNC(ptr, size, type) to point to the user defined memory handling procedures. These macros will be used for redefining pure memory handling procedures.
  2. Compile the coder library with the CODER_MMS_USER compile switch, see "Memory management configuration" .
  3. Add include path for the file mms_user.h to the compilation settings.
  4. Compile and link the user memory handler function to the application.

Example 460 : File mms_user.h

#ifndef mms_user_h
#define mms_user_h

#define USER_ALLOC_FUNC(size,type) UserAlloc(size)
#define USER_FREE_FUNC(ptr,size,type) UserFree(ptr)

extern void* UserAlloc(size_t size);
extern void UserFree(void* ptr);

#endif

There are also two BMS user-specific memory handling procedures that are referenced through macros defined in the mms_user.h:

#define USER_BMS_ALLOC_FUNC(buffer, size, type) UserBmsAlloc(buffer, size)
#define USER_BMS_FREE_FUNC(coder, ptr, size, type) UserBmsFree(buffer, ptr, size)

These interfaces are used only in the buffer functions (see "Buffer Management Functions" ). By default (without this definition) USER_ALLOC_FUNC and USER_FREE_FUNC are used inside the buffer functions.

The BMS user-specific memory handlers use buffer access types tCoder* or tBuffer as the first argument. This argument opens the access to the tUserData (see "User Data" ) inside the BMS memory handling:

void* UserBmsAlloc(tCoder* Coder, size_t Size)
{
tUserData* data = BufGetUserData(Coder);
... /* user implementation */
}

void UserBmsFree(tCoder* Coder, void* Ptr, size_t Size)
{
tUserData* data = BufGetUserData(Coder);
... /* user implementation */
}


Error Management System

Figure 503 : Error management

The coder solution contains error management functions. The error management consists of fault detection, error handling and error output. The error management is optional and can be removed from the application.

The fault detection consists of monitoring code that checks for all kinds of faults when encoding and decoding. When a problem is detected the fault detection part will start the error handler. The monitoring code is controlled by C macros and can be removed by defining macros, see "Error checking configuration" . The user defined error handling functionality is described in "User defined Error Handling" .

SDL Suite error output functionality has several error output implementations for the different types of kernels. The behavior is different for simulation and for application. It is possible to register a different error output function. See "User defined Error Output" .

There are several types of error output functions which can be used to perform error output:

  • SDL Suite error output as default
  • Coder library error output
  • user defined application specific error output functions.

The type of error output to be invoked upon error detection is configured when compiling coder library by compile switches, see "Error output configuration" .

Error Management Interface

Encode and decode functions return a status code, which is equal to a success code, or one of the error codes in case of failure. Error codes are visible in both SDL and C functional interfaces. If an error occurs, its code is returned by the encoding or decoding function, and is written into the buffer at the same time.

The behavior of the fault detection can be controlled by compilation switches, that are described in "Error checking configuration" . For instance, it is possible to remove all fault detection by defining a corresponding switch.

Detailed error messages

Error messages contain a type name with a path to the field where an error has occurred. The path contains a sequence of SET/CHOICE/SEQUENCE fields and open type objects from the root type up to the field where an error has occurred.

There are two possible representations for the path:

  • Path fields are represented by their names. This representation is available only if one of the following compile switches are present, CODER_TI_NAMES (see "Error output configuration" ) or CODER_VMS_PRINT (see "Printing configuration" ). For example:
ERROR 21 No more data for read at BOOLEAN, type: BOOLEAN, path: yASN1_Type1.field2.comp1
  • Path fields are represented by their indexes - in this case root type is named "undef" and path contains indexes of SEQUENCE/SET components, CHOICE alternatives and open type objects, for example:
ERROR 21 No more data for read at BOOLEAN, type: undef, path: SEQUENCE.2.1

By default the second representation with indexes is used.

If an error occurs within the encoding/decoding then you can unambiguously understand the exact place of the error. For example if we have a complex type with the several nested sequences:

Type1 ::= SEQUENCE {
field1 Type2,
field2 Type2
}
Type2 ::= SEQUENCE {
comp1 [0] Bool,
comp2 [1] Int
}
Bool ::= [0] BOOLEAN
Int ::= [1] INTEGER

And the error is:

ERROR 21 No more data for read at BOOLEAN, type: BOOLEAN, path: yASN1_Type1.field2.comp1
(in the first representation)
ERROR 21 No more data for read at BOOLEAN, type: undef, path: SEQUENCE.2.1
(in the second representation)

Then the exact place of the error is known. The error occurred in Bool type in the second nested sequence by the path Type1.field2.comp2 .

The benefits of this feature become significant in a huge ASN.1 specifications with the long nested fields, like UMTS. This is an example of a real error message from the RRC specification (subpart of UMTS):

ERROR 22: Wrong TAGGED identifier octet, type: CPCH_SetInfo_INLINE_3, path: yASN1_DL_DCCH_Message.message.radioBearerSetup.modeSpecificPhysChInfo.fdd.cpch_SetInfo.ap_AICH_ScramblingCode

Detailed error messages (type and path) is used in the ec_VAL_ and ec_DEC_ errors.

The default configuration includes detailed error messages. Detailed messages require extra resources from the speed and from the Type Info size (if names information is enabled). The encoding/decoding speed becomes a bit slower because the feature requires extra manipulations with the stack to store the temporary path. If you do not need to use this feature then you should use CODER_REMOVE_PATH compile switch (see "Error handling configuration" ). Error messages in this case will look like:

ERROR 21 No more data for read at BOOLEAN, type: undef, path: undef

SDL error interface

In SDL, error codes are represented by integer values and are defined as Integer synonyms. Names of synonyms are the same as error codes described in "Error codes" . The file codererrors.sdl contains a complete list of Integer synonyms for coder error codes. This file must be included to the SDL system that is going to check coder error codes after encoding and decoding.

C error interface

In the C error interface, error codes are literals of one big enumerated type, and they can be treated as C integer values. All possible error codes are listed in the file errors.h in the `ems' folder of the library installation (see "Files and File Descriptions" ). For detailed description of error codes see "Error codes" .

Error codes

If the decode or encode succeeded, ec_SUCCESS is returned.

In case of failure, an error code is returned that helps to understand the reason of the failure. All possible error codes with short descriptions are listed below.

Memory access errors

ec_MEM_NotEnoughMemory

The application has run out of memory and one of the coder library functions can not allocate memory.

Buffer errors

ec_BUF_DifferentBufferTypes

This is a buffer copying error. The BufCopyBuf function belongs to the general buffer interface which supports different buffer types. The error occurs when the source and destination buffers in the copying function are of different buffer types.

ec_BUF_WrongBufferType

The message is reported when the buffer initialize function has been called with the buffer type which has been excluded from the application by compile switches (see "Buffers configuration" ).

ec_BUF_CloseNotInitialized

The message is reported when BufCloseBuf is called on a buffer that has not been initialized.

ec_BUF_WorkWithNotInitialized

One of the two buffer modes, read or write, has to be initialized before accessing the buffer with reading or writing procedures. If a read or write procedure has been applied to a buffer that has not been initialized, the ec_BUF_WorkWithNoneInitialized error is reported.

ec_BUF_NullPtrToUserMemory

BufInitBufWithMemory or BufCloseBufToMemory is called with NULL pointer to user memory.

ec_BUF_NotEnoughUserMemory

This error is specific for buffers that are initialized by the user memory, and it denotes that the size of the user memory assigned to the buffer is not enough for storing data.

ec_BUF_OpenOpened

This error is reported when trying to reopen the buffer which has already has been opened for write or read mode, and has not been closed afterwards.

ec_BUF_IllegalClose

This error is reported when BufCloseBuf is called on the buffer for which one of the modes, reading or writing, has not been closed.

ec_BUF_CloseWrongMode

This error is returned when trying to close the buffer for a mode different from the opened one. This situation can happen, for example, when BufCloseWriteMode follows the function BufInitReadMode, or when BufCloseReadMode is called to the buffer which mode has been initialized by the function BufInitWriteMode.

ec_BUF_OperationWrongMode

This error denotes that you are trying to perform an incorrect operation for the current buffer mode. For example, you are trying to read data from the buffer which has been opened for writing by function BufInitWriteMode.

ec_BUF_NoMoreDataForRead

This error is returned when you are trying to read data from a buffer which is already empty.

ec_BUF_TooBigNumberOfBits

The error is returned when you are trying to put or get more bits from the buffer than it is possible to pass to the bit buffer interface function. The operations BufGetBits and BufPutBits operate with bits stored in the value of type long and can not process more then sizeof(long) number of bits. So when they are called with a number of bits more then sizeof(long), an error message is reported.

ec_BUF_InvalidEncodingRules

This error code is returned when the combination of bit masks passed as the second parameter to the function BufSetRule does not form a valid encoding rule. For example, BufSetRule( buffer, er_BER | er_Aligned ) will return this error code because er_Aligned is an alternative of PER and does not have any sense together with BER.

Value errors

ec_VAL_IllegalRealBase

The real value received for encoding is represented with a base that cannot be handled by the encoder function.

ec_VAL_WrongConstrainedValue

The value passed to the coder function does not satisfy constraints specified for the corresponding type.

ec_VAL_WrongConstrainedLength

The size of the value passed to the coder function does not satisfy the size constraint specified for the corresponding type.

ec_VAL_WrongConstrainedAlphabet

Characters in the string value passed to the coder function do not satisfy the permitted alphabet constraint specified for the corresponding type.

Decoding errors

ec_DEC_NoMoreDataForRead

This error is returned when you are trying to read data from a buffer which is already empty. There is a difference in the formats between ec_DEC_NoMoreDataForRead and ec_DEC_NoMoreDataForRead. ec_DEC_NoMoreDataForRead uses the detailed error message approach (with type and path) but ec_BUF_NoMoreDataForRead does not.

ec_DEC_WrongIdentifierOctet

This is a BER specific error, based on BER encoding TLV (Type-Length-Value) structure. The type information from TLV is stored in a so called identifier octet. If the data in the identifier octet for the sequence of bits to be decoded is wrong (for example, ASN.1 type is defined to be INTEGER, but the identifier octet for the value of that type claims that value to be decoded if of type BOOLEAN), an error is returned.

ec_DEC_WrongLength

For some ASN.1 types, the range of the encoded value length is restricted. When length is out of range, the wrong length error is returned.

ec_DEC_TooBigTagNumber

Tag numbers are stored in the variable of type unsigned long, so the value of a tag is restricted. When the tag number occupies more then 32 bits, restriction is violated and this error message is returned.

ec_DEC_WrongConstructedLengthPrefix

When constructed encoding is used, each group of bytes from the encoding is prefixed by the group information. For example, if it is the last group in the constructed encoding or not, and similar. Constructed encoding prefix occupies 8 bits, but not all bit combinations are meaningful. When the combination is wrong, this error is returned.

ec_DEC_WrongUnusedBits

This is a BER specific error. BIT STRING values in BER are encoded into a sequence of bytes, although they cannot contain exactly an integer number of 8 bits. For correct value encoding, the number of unused bits in the last byte is also encoded. When this number is not in the range between 0 and 7, an error is returned.

ec_DEC_TooBigSubIdent

This object identifier decoding error is reported when the sub-identifier is too big and cannot be stored in the variable of type long (4 bytes).

ec_DEC_WrongRealPrefix

The real value encoding contains a prefix denoting the type of real value that has been encoded, plus infinity and minus infinity real values, zero real value, other common real value (mantissa + base + exponent). The real prefix is encoded into 8 bits but not all of them have meaning. If the real encoding contains a bad prefix, this error is reported.

ec_DEC_UnsupportedRealBase

Trying to decode a real value which has been encoded with a base that is not supported in the coding library.

ec_DEC_UnsupportedRealDecimalEncoding

Decimal encoding of real values is not supported. If real value has been encoded according to decimal real encoding algorithm, the decoder will not be able to decode it and it will return this error code.

ec_DEC_RequiredComponentIsAbsent

This error can be reported when decoding SEQUENCE or SET type values and it denotes that not all required components are present in the value encoding.

ec_DEC_ExtRequiredComponentIsAbsent

This is SEQUENCE and SET decoding specific error. It points out that not all required components from extension addition group are present in the value encoding, although the group itself is encoded as present.

ec_DEC_AbsentComponentIsPresent

This error can appear while decoding a value of sequence or set type with the ABSENT constraint applied. When the component constrained to be absent is present in the encoded value, this error message is reported.

ec_DEC_AbsentAlternativeIsPresent

This error can appear while decoding a value of choice type with the ABSENT constraint applied. When the alternative constrained to be absent is present in the encoded value, this error message is reported.

ec_DEC_UnknownComponent

This is SEQUENCE and SET specific decoding error, and it is reported when the encoded field tag is not a known tag from the type fields of SEQUENCE or SET type.

ec_DEC_UnknownAlternative

This is CHOICE specific error, and it is returned when the encoded choice alternative has got a tag which does not belong to the set of possible tags for the decoded choice type.

ec_DEC_NoOpenId

This is open type specific error. It is reported when open type value can not be decoded because open type identifier field is absent for some reason in the encoding.

ec_DEC_UnknownObject

This is open type specific error. It is reported when decoded open type identifier is not equal to any of identifier in the open type restricting table.

ASCII decoding errors

Each ASCII decoding error refer to a particular type and denotes that there are problems or errors when decoding value of that type, for example, ec_ERROR_DECODING_PARSTART is reported when there are errors when decoding start of signal parameter or variable from the buffer.

All possible ASCII decoding errors are listed below.

ec_ERROR_DECODING_INTEGER ec_ERROR_DECODING_REAL ec_ERROR_DECODING_BOOLEAN ec_ERROR_DECODING_TIME ec_ERROR_DECODING_CHARSTRING ec_ERROR_DECODING_BIT ec_ERROR_DECODING_BITSTRING ec_ERROR_DECODING_OCTET ec_ERROR_DECODING_OCTETSTRING ec_ERROR_DECODING_SIGNALID ec_ERROR_DECODING_STRUCT ec_ERROR_DECODING_CHOICE ec_ERROR_DECODING_POWERSET ec_ERROR_DECODING_BAG ec_ERROR_DECODING_STRING ec_ERROR_DECODING_ARRAY ec_ERROR_DECODING_REF ec_ERROR_DECODING_USERDEF ec_ERROR_UNKNOWN_TYPE_NODE ec_ERROR_DECODING_PARSTART ec_ERROR_DECODING_PAREND

Internal errors

ec_INT_InternalError

This is coder library internal error. If coder function returns this error, please, contact Telelogic Customer Support. Internal error will never be reported if CODER_CHECK_NONE_INNER compile switch is set up (see "Error checking configuration" ), in this case all internal error checks are removed from the library code.

ec_INT_UnsupportedType

This is also coder library internal error. It is reported when the type specified for the encode or decode function in the ASN.1 type info structure is not supported by the coder library. Internal error will never be reported if CODER_CHECK_NONE_INNER compile switch is set up (see "Error checking configuration" ), in this case all internal error checks are removed from the library code.

Note: Error codes backwards compatibility

Backwards compatibility is implemented for those error codes which have been removed or renamed in comparison with the previous versions of the coder library error management system. All old error names will be mapped to new ones with the same functionality for the systems using previous version of coder library. An example of error code which is not used in the new coder library any more is ec_SMLBUF_READ_ERROR.

Definition of your own error codes

It is possible to specify your own error codes. It might be useful for user encoding rules or user memory management implementation.

If you want to use your own error codes, perform the following steps:

  1. Create file errors_user.h and insert your own error codes by using the following format:

CUCF_ERROR(ec_<error identifier>, "Error message")

Example 461 : File errors_user.h

CUCF_ERROR(ec_MY_ERROR_ONE, "My error one")
CUCF_ERROR(ec_ME_ERROR_TWO, "My error two")

  2. Compile the coder library with the CODER_EC_USER="errors_user.h".
  3. Add include path for the file errors_user.h to the compilation settings.

User defined Error Handling

This functionality allows to call a user defined error handling function inside the decoding procedure. If an error occurs this function will be called. Combined with the BufGetErrorPath( buffer ) buffer interface (see "Buffer Management Functions" ), error handling function gives an opportunity to insert a default value to the field for which the decoding failed.

An error handler function must be written by the user according to the following format:

typedef void (*tBufErrInitFunc)(tBuffer Buffer);

There is an interface in the buffer functionality BufSetErrInitFunc( buffer, func ) that allows to set user error handling by reference into the buffer and it will be used by the decoder. BufGetErrInitFunc( buffer ) returns a reference to an error handling function. By default there is no error handler and it returns NULL. Below there is an example with the user defined error handling.

These two checks between ErrorPath and TypeInfo help to determine the exact place where an error has occurred:

#define EQ_TI(field, ti) \
((tASN1TypeInfo*)(field)==(tASN1TypeInfo*)&ti)
#define EQ_CMP(field, ti) \
(((tASN1Component*)(field))->TypeInfo==(tASN1TypeInfo*)&ti)

Error handling:

void TinyErrorHandling(tBuffer b)
{
int res = BufGetErrorCode(b);
tErrorPath *ep = BufGetErrorPath(b);
LineB* lineB = (LineB *)BufGetMainVal(b);
if ( res == ec_VAL_WrongConstrainedValue &&
ep->NumOfFields == 2 &&
EQ_TI(ep->Fields[0], yASN1_LineB) &&
EQ_CMP(ep->Fields[1], yASN1_PointB_INLINE_0))
{
lineB.point1.x = 40;
return;
}
if ( res == ec_VAL_WrongConstrainedValue &&
ep->NumOfFields == 2 &&
EQ_TI(ep->Fields[0], yASN1_LineB) &&
EQ_CMP(ep->Fields[1], yASN1_PointB_INLINE_1))
{
lineB.point2.y = 25;
return;
}
}

ASN.1:

Tiny DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
PointA ::= SEQUENCE {
x INTEGER (0..42),
y INTEGER (0..26)
}
PointB ::= SEQUENCE {
x INTEGER (0..40), -- lineA.point2.x = 42
y INTEGER (0..25) -- lineB.point1.y = 26
}
LineA ::= SEQUENCE {
point1 PointA,
point2 PointA
}
LineB ::= SEQUENCE {
point1 PointB,
point2 PointB
}
lineA LineA ::= { point1 { x 11, y 26 }, point2 { x 42, y 24 } }
lineB LineB ::= { point1 { x 11, y 25 }, point2 { x 40, y 24 } }
END

The code example with the encoding of LineA type and LineB as the type for the decoding. The encoded lineA value does not satisfy the LineB constraint and that is why there are two constraint errors:

ERROR 18 Wrong INTEGER constrained value, type: PointB_INLINE_0, path: yASN1_LineB.point1.x
ERROR 18 Wrong INTEGER constrained value, type: PointB_INLINE_1, path: yASN1_LineB.point2.y

The TinyErrorHandling function catches these errors with a corresponding assignment to the correct values.

BufInitBuf(b, bms_SmallBuffer);
BufSetErrInitFunc(b, TinyErrorHandling); /* set TinyErrorHandling as decoding
BufInitWriteMode(b);
res = ASN1_ENCODE(b, (tASN1TypeInfo *)&yASN1_LineA, lineA);
BufCloseWriteMode(b);
BufInitReadMode(b);
res = ASN1_DECODE(b, (tASN1TypeInfo *)&yASN1_LineB, dec_lineB); /*
BufCloseReadMode(b);
BufCloseBuf(b);

User error handling requires the same resources as for detailed error messages (see "Detailed error messages" ). The encoding/decoding speed becomes slower because of some extra manipulations with the stack. CODER_REMOVE_PATH compile switch (see "Error handling configuration" ) should be defined to disable the error handling.

User defined Error Output

It is possible to write your own error output function, which will be invoked when a fault is detected.

If you want to use your own error output, perform the following steps:

  1. Implement a C-procedure for error output with the prototype void USERErrorOutputFunc(FILE* File, tEMSErrorCode Code, va_list MessageArguments). tEMSErrorCode is an enumerated type containing all possible error codes returned by coder library functions, see "Error codes" . You can also find a list of the different error codes in errors.h from /cucf/ems folder.
  2. Compile the coder library with CODER_EO_USER compile switch, see "Error output configuration" ,
  3. Compile and link the user error output function to the application.

The USERErrorOutputFunc function takes error message arguments as the third parameter which corresponds to the message string defined in the coder library. The error management system provides a function that allows you to get the coder library message string for the error code: char* CUCFGetErrorMessage(tEMSErrorCode Code). Example 462 illustrates one possible way of defining a user error output function.

Example 462 Error output

void USERErrorOutputFunc( FILE* File,
int Code,
va_list MessageArguments )
{
/* user error output with the code and message */
fprintf(File, "USER ERROR %d ", Code);
vfprintf(File, ErrorMessageArray[Code], MessageArguments);
fputc('\n', File);
}


User Data

There is an option to include your own data fields into the buffer type. C-type tUserData is defined in the user_data.h file and it can be included into the buffer by CODER_USER_DATA compile switch (see "User data configuration" ). By default type tUserData is defined as void*, but you can redefine it according to your needs.

tUserData with your own fields might be useful in the user error handling function (see "User defined Error Handling" ) to store the data for the later manipulation outside the decoder or in the USER_BMS_ALLOC_FUNC/USER_BMS_FREE_FUNC (see "User defined Memory Handling" ). The buffer interface BufGetUserData( buffer ) (see "Buffer Management Functions" ) returns a reference to tUserData for your further handling. If you want to use your own data fields as tUserData, perform the following steps:

  1. Create file user_data.h and insert declaration of the tUserData C-structure.
  2. Compile the coder library with the CODER_USER_DATA compile switch.
  3. Add include path for the file user_data.h to the compilation settings.

Example 463 : File user_data.h

#ifndef user_data_h
#define user_data_h

typedef struct {
int UserInt1;
int UserInt2;
int UserInt3;
} tUserData;

#endif


Printing Opportunities

The print functions can be used for test and debug purposes. They will be available at runtime only if the compilation switch CODER_VMS_PRINT is set, see "Printing configuration" .

There are two print functions available, ASN1_PRINT_TYPE and ASN1_PRINT. The print functions use the type information in the same way as an encoding function.

The function ASN1_PRINT_TYPE prints the contents of the type information structure for one particular type. There are two input parameters, the first is a file handle and the second is a reference to the type information.

The function ASN1_PRINT prints the value of a variable or signal parameter. This print function has got three input parameters, the first is a file reference, the second is a reference to the type information structure and the third is a reference to the variable or the signal parameter.

Example 464 : Print type information

FILE * logfile;

logfile = fopen( "asn1print.log", "w" );

ASN1_PRINT_TYPE( logfile,
(tASN1TypeInfo *)&yASN1_TestType);

fclose( logfile );

Example 465 : Print value of signal parameter

FILE * logfile;

logfile = fopen( "asn1print.log", "w" );

ASN1_PRINT( logfile, (tASN1TypeInfo *)&yASN1_TestType,
(void *)&((yPDef_outsig *)(*SignalOut))->Param1);
fclose( logfile );


Structure and Configuration

An application with ASN.1 encoding or decoding support contains the following:

  • Encoding and decoding functions. One set of functions for BER encoding and decoding and one set of functions for PER encoding and decoding.

Note: ASCII coder

ASCII encoding and decoding, which is based on Telelogic Tau SDL Suite internal encoding rules is also available. ASCII encoding and decoding is described in "SDL Data Encoding and Decoding, ASCII coder" .

  • Buffer management functions.
  • Error management functions (optional).
  • Print functions (optional).
  • ASN.1 type information generated by the ASN.1 Utilities.
  • SDL type and operator information generated by the SDL C code generators.

Files and File Descriptions

This section describes the static file structure of the coder directories in the installation.

Figure 504 : The coder directory

The coder directory contains five sub-directories which correspond to the functional modules in the coder library:

  • coder/er - this directory contains three sub-directories which correspond to different encoding rules supported by the coder library.
  • coder/bms - Buffer Management System files.
  • coder/ems - Error Management System files.
  • coder/mms - Memory Management System files.
  • coder/vms - Value Management System files.

There are also several files included to the root coder directory:

  • cucf.h - main header file of the coder library. It includes all useful header files from the library functional modules.
  • cucf_cfg.h - standard C library includes, like <stdio.h>, <sdtlib.h> and others.
  • cucf_er.h - declarations of main encode and decode coder interface functions.
  • cucf_er.c - definition of main encode and decode coder interface functions.
  • cucf_er_sdt.h - declarations of SDL Suite specific encode and decode interface functions which are used for encode and decode within SDL support.
  • cucf_er_sdt.c - definition of SDL Suite specific encode and decode interface functions which are used for encode and decode within SDL support.
  • cucf_er_ttcn.h - declarations of TTCN Suite specific encode and decode interface functions which are used for encode and decode within TTCN support.
  • cucf_er_ttcn.c - definition of TTCN Suite specific encode and decode interface functions which are used for encode and decode within TTCN support.
  • coderascii.h, coderber.h, coderper.h, coderucf.h - these files are not used inside the library, but provide backwards compatibility solutions for the SDL systems created with the previous versions of SDL coder support.

Encoding rules sub-directory

Sub-directory coder/er contains three sub-directories corresponding to different types of encoding rules supported by the coder library:

  • ascii
    This directory contains files with encoding and decoding function according to internal rules of the SDL Suite. The ASCII coders are described in "SDL Data Encoding and Decoding, ASCII coder" .
  • ber
    This directory contains files with encoding and decoding functions according to BER (Basic Encoding Rules), see "BER sub-directory" .
  • per
    This directory contains files with encoding and decoding functions according to PER (Basic Encoding Rules), see "PER sub-directory" .

BER sub-directory

Sub-directory coder/er/ber contains the following files:

  • ber.h - header file with declaration of BEREncode and BERDecode functions.
  • ber_base.h - contains declarations of basic functions needed by the encode and decode functions.
  • ber_base.c - contains implementation of basic functions needed by encode and decode functions.
  • ber_content.h - contains declarations of functions that encode and decode ASN.1 predefined types.
  • ber_content.c - contains implementation of functions that encode and decode ASN.1 predefined types.
  • ber_decode.c - definition of main outermost function BERDecode which references functions from ber_base and ber_content modules.
  • ber_encode.c - definition of main outermost function BEREncode which references functions from ber_base and ber_content modules.

PER sub-directory

Sub-directory coder/er/per contains the following files:

  • per.h - header file with declaration of PEREncode and PERDecode functions.
  • per_base.h - contains declarations of basic functions needed by the encode and decode functions.
  • per_base.c - contains implementation of basic functions needed by encode and decode functions.
  • per_content.h - contains declarations of functions that encode and decode ASN.1 predefined types.
  • per_content.c - contains implementation of functions that encode and decode ASN.1 predefined types.
  • per_decode.c - definition of main outermost function PERDecode which references functions from per_base and per_content modules.
  • per_encode.c - definition of main outermost function PEREncode which references functions from per_base and per_content modules.

Buffer Management System sub-directory

Sub-directory coder/bms contains the following files:

  • bms.h - base buffer management declarations, this header contains base buffer control structure definitions. This is the main header file for buffer management.
  • bms.c - implementation of base buffer functions which are common for all types of buffers.
  • bms_small.h - small buffer management specific declarations.
  • bms_small.c - implementation of small buffer management.

Error Management System sub-directory

Sub-directory coder/ems contains the following files:

  • ems.h - error management declarations. This is the main header file for coder error handling.
  • ems.c - implementation of common error management functions.
  • ems_eo_sdt.h - SDT specific error management declarations and includes.
  • ems_eo_sdt.c - implementation of SDT specific error handling functions.
  • errors.h - declaration of error codes and error information.

Memory Management System sub-directory

Sub-directory coder/mms contains the following files:

  • mms.h - declarations of pure memory handling macros CUCF_ALLOC and CUCF_FREE and safe memory management functions CUCFAlloc and CUCFFree (see "Memory Management System" ). This is the main header file for coder memory handling.
  • mms.c - implementation of safe memory handling functions.

Value Management System sub-directory

Sub-directory coder/vms contains the following files:

  • vms.h - this is the main header file for value management system, it contains includes of all other useful header files from this folder.
  • vms_type.h - definitions of types used in ASN.1 type nodes.
  • vms_macro.h - definitions of macros which are used for declaration and filling ASN.1 type structure nodes. Calls to these macros are generated by ASN.1 coder generator.
  • vms_vr_sdt.h - definitions of macros which are used for inserting SDL Suite specific information to ASN.1 type structure nodes. Calls to these macros are generated by ASN.1 coder generator only for SDL Suite coder generation.
  • vms_vr_ttcn.h - definitions of macros which are used for inserting TTCN Suite specific information to ASN.1 type structure nodes. Calls to these macros are generated by ASN.1 coder generator only for TTCN Suite coder generation.
  • vms_export.h - type node declarations for predefined ASN.1 types, such as BOOLEAN, INTEGER, BIT STRING, OCTET_STRING, NULL, OBJECT IDENTIFIER, REAL, string types.
  • vms_export.c - type node definitions for predefined ASN.1 types.
  • vms_internal.h - internal value representation type and macro definitions.
  • vms_base.h - declarations of internal value representation access procedures.
  • vms_base.c - implementation of internal value representation access procedures.
  • vms_check.h - declarations of check procedures.
  • vms_check.c - implementation of procedures that perform error checking of type nodes and values.
  • vms_print.h - declarations of print procedures used for test and debug purposes.
  • vms_print.c - implementation of print procedures used for test and debug purposes.

Compilation switches

You can change the default properties and configure the BER and PER coders by setting the compilation switches. Some of these switches can be set by choosing options in the Targeting Expert, see 59 The Targeting Expert.

Available compile switches can be separated onto several groups. Below there are descriptions of compile switches that can be used to configure the behavior of coder functions.

Encoding rules configuration

Removing runtime encoding rules availability

  • CODER_REMOVE_ASCII - compile coding library without ascii encoding rules available at runtime
  • CODER_REMOVE_BER - compile coding library without BER encoding rules available at runtime
  • CODER_REMOVE_PER - compile coding library without PER encoding rules available at runtime
  • CODER_USE_UER - add user defined encoding and decoding functions to be available at runtime (file "uer.h" will be used during library compilation)

By default all the library included ascii, ber and per encoding rules to be present in the compiled object library.

Choosing default encoding rules

This compilation switches influence on which encoding rules will be applied when the coder function is called without specifying which type of encoding rules should be applied

  • CODER_ER_DEFAULT_PER - use PER as default encoding rules
  • CODER_ER_DEFAULT_BER - use BER as default encoding rules
  • CODER_ER_DEFAULT_UER - apply USER encoding rules by default

The default setting is CODER_ER_DEFAULT_BER.

  • CODER_BER_DEFINITE - use definite length form encoding for BER by default
  • CODER_BER_INDEFINITE - use indefinite length form encoding for BER by default

The default setting is CODER_BER_INDEFINITE.

  • CODER_PER_NO_ENDPAD - use PER unaligned without end padding as default encoding rules
  • CODER_PER_ALIGNED - use PER aligned as default encoding rules
  • CODER_PER_UNALIGNED - use PER unaligned as default encoding rules

The default setting is CODER_PER_UNALIGNED.

  • CODER_BER_CONSTRUCTED - use constructed form of BER by default
  • CODER_BER_PRIMITIVE - use primitive form of BER by default

The default setting is CODER_BER_PRIMITIVE.

  • CODER_BER_CONSTRUCTED_LENGTH=<number> - use <number> as length of constructed sequence of bytes for BER

The default setting is CODER_BER_CONSTRUCTED_LENGTH=1000.

  • CODER_BER_CANONICAL_ON - restrict BER decode for SET type by canonical order.
  • CODER_BER_CANONICAL_OFF - BER decode for SET type as defined in ITU X.690.

The default setting is CODER_BER_CANONICAL_ON.

Real values encoding

For encoding real values are divided into the following number values: (sign * 2^factor * number * base^exponent). It is the user option to choose which factor and which base should be used when encoding.

  • CODER_BER_REAL_FACTOR_0 - use real factor 0 for coding
  • CODER_BER_REAL_FACTOR_1 - use real factor 1 for coding
  • CODER_BER_REAL_FACTOR_2 - use real factor 2 for coding
  • CODER_BER_REAL_FACTOR_3 - use real factor 3 for coding
  • CODER_REAL_BASE_2 - use real base 2 for encoding
  • CODER_REAL_BASE_8 - use real base 8 for encoding
  • CODER_REAL_BASE_16 - use real base 16 for encoding

The default setting is CODER_BER_REAL_FACTOR_0 and CODER_REAL_BASE_2.

Error checking configuration

  • CODER_CHECK_NONE - remove all error checks from compiled library
  • CODER_CHECK_NONE_VALUE - remove error checks of input values to encoding and decoding function from the compiled library
  • CODER_CHECK_NONE_BUFFER - remove error checks in buffer management from the compiled library
  • CODER_CHECK_NONE_DECODING - remove error checks in decoding functions from the compiled library
  • CODER_CHECK_NONE_INNER - remove internal error checks in encoding and decoding functions from the compiled library

Note: Error checks in decoding functions

All decoding functions start with a check of type nodes and input values. These tests are not removed by defining the CODER_CHECK_NONE_DECODING macro. Checks in the buffer management are not affected by the macro either. You can remove these checks by using other macros in this list.

By default all checks are switched ON.

Encoding configuration

You can use the following switches to remove code for ASN.1 type from the compilation:

  • CODER_NOUSE_BOOLEAN
  • CODER_NOUSE_INTEGER
  • CODER_NOUSE_NULL
  • CODER_NOUSE_OBJECT_IDENTIFIER
  • CODER_NOUSE_REAL
  • CODER_NOUSE_BIT_STRING
  • CODER_NOUSE_OCTET_STRING
  • CODER_NOUSE_CHARACTER_STRING - NumericString, PrintableString, IA5String, VisibleString, UTCTime, GeneralizedTime
  • CODER_NOUSE_ENUMERATED
  • CODER_NOUSE_ENUMERTAED_ITEMS - ENUMERATED items if they are 0 1 2 3 etc
  • CODER_NOUSE_SEQUENCE
  • CODER_NOUSE_SET
  • CODER_NOUSE_SET_OF
  • CODER_NOUSE_SEQUENCE_OF
  • CODER_NOUSE_CHOICE
  • CODER_NOUSE_OPEN
  • CODER_NOUSE_EXT - extension marker in ASN.1 sequence and set

You can use the following switches to redefine C type for ASN.1 type information field:

  • CODER_ENUMERATED_TYPE=<type> - enumerated value. Default is "long"
  • CODER_TagNumber_TYPE=<type> - ASN.1 tag class number. Default is "unsigned long"
  • CODER_NumOf_TYPE=<type> - number of components. Default is "unsigned long"
  • CODER_INTEGER_LBOUND_TYPE=<type> - low bound in integer constraint. Default is "long"
  • CODER_INTEGER_UBOUND_TYPE=<type> - upper bound in integer constraint. Default is "long"
  • CODER_SIZE_LBOUND_TYPE=<type> - low bound in size constraint. Default is "unsigned long"
  • CODER_SIZE_UBOUND_TYPE=<type> - upper bound in size constraint. Default is "unsigned long"

These compile switches can be set automatically. asn1util generates asn1_cfg.h file for the -c option where the above compile switches are included after #define directives to minimize coder library code size automatically, see also "Configuration file generation" . To be able to use this asn1_cfg.h automatic configuration you should define the following compile switch:

  • CODER_AUTOMATIC_CONFIG - enables automatic configuration generated to the asn1_cfg.h file. This switch can be set by choosing the corresponding option in the Targeting Expert.

Buffers configuration

  • CODER_BMS_SMALLBUF - uses small buffer implementation. The second argument of BufInitBuf interface - type of the buffer (see "tBMSBufType" ) will not be in use for this case.
  • CODER_REMOVE_SMALLBUF - removes small buffer code from the compiled library

The default is including only small buffers to the library. When all buffers are absent, then only a null buffer will be available (a null buffer is a stub buffer without any functionality).

  • CODER_USE_USERBUF - includes the user buffer into the library to be available at runtime
  • CODER_BMS_USERBUF - uses the user buffer implementation if it is made available by previous switch
  • CODER_BMS_TINY - uses a minimum set of bms interfaces. Interfaces to operate with buffer mode, character segment, bytes, bits also copy buffer interface are not available for this switch. It is allowed to use both buffer access types tBuffer and tCoder in this mode.

Example 466 : Encoding in tiny mode

tCoder coder;
tBMSUserMemory UserMemory;

BufInitBuf(&coder, bms_SmallBuffer);
ASN1_ENCODE(&coder,
(tASN1TypeInfo *)&yASN1_Message,
encValue);
BufCloseBufToMemory(&coder, &UserMemory);
...
BufInitBufWithMemory(&coder, &UserMemory);
ASN1_DECODE(&coder,
(tASN1TypeInfo *)&yASN1_Message,
decValue);
BufCloseBuf(&coder);
CUCF_FREE(UserMemory.MemPtr, UserMemory.MemSize, 0);

Example 467 : tBuffer access type in tiny mode

tBuffer buf = NULL;
BufInitBuf(buf, bms_SmallBuffer);

Note:

The buffer value for this mode must be initialized by NULL before being used in buffer management. The behavior will otherwise be unpredictable.

Following buffer interfaces are not available in this mode:

BufGetMode, BufInNoMode, BufInReadMode, BufInWriteMode
BufCopyBuf
BufInitWriteMode, BufCloseWriteMode
BufInitReadMode, BufCloseReadMode, BufCloseDeleteReadMode
BufGetByte, BufPeekByte, BufPutByte
BufGetSeg, BufSkipSeg, BufPeekSeg, BufPutSeg
BufPutBit, BufGetBit, BufPutBits, BufGetBits
  • CODER_SMALLBUF_SIZE=<number> - <number> defines small buffer allocation block

The default setting for the size is CODER_SMALLBUF_SIZE=0x1000.

Memory management configuration

  • CODER_MMS_SDT - use SDT alloc/free procedures when working with memory in the coder library functions
  • CODER_MMS_USER - apply user defined alloc/free functions when working with memory in the coder library functions (file "mms_user.h" will be added for library compilation)

By default standard malloc and free functions from <stdlib.h> are used.

Error output configuration

  • CODER_EO_SDT - use SDT error output functions (when this switch is turned on, SDT error output switch XECODER can influence error output functionality)
  • CODER_EO_USER - apply user defined error output procedures to the library and use them for error output (file "ems_eo_user.h" will be added for library compilation)
  • CODER_EO_DEBUG - use internal library functions for printing error messages
  • CODER_EO_NONE - do not output error messages text

The default setting is CODER_EO_SDT.

  • CODER_TI_NAMES - enable name information in the Type Info.

Error handling configuration

  • CODER_PATH_DEEP=<number> - nesting coefficient. It depends on the ASN.1 specification. The nesting coefficient is the maximum number of nested SEQUENCE, SET, CHOICE, SEQUENCE OF, SET OF or open types. By default CODER_PATH_DEEP is defined to 16. If the nesting coefficient in the ASN.1 specification is greater then 16 then you should define the CODER_PATH_DEEP compile switch with this value yourself, otherwise "segmentation fault" error will occur. The nesting coefficient for the following example is 4:
MySeq ::= SEQUENCE { -- NC=4
a MyChoice,
b NULL
}
MySet ::= SET { -- NC=1
a INTEGER,
b BOOLEAN
}
MyChoice ::= CHOICE { -- NC=3
a MySeqOf,
b MySetOf
}
MySeqOf ::= SEQUENCE OF MySet -- NC=2
MySetOf ::= SET OF BOOLEAN -- NC=1
  • CODER_REMOVE_PATH - do not use detailed error messages (see "Detailed error messages" ) and user error handling (see "User defined Error Handling" )

User data configuration

  • CODER_USER_DATA - include tUserData defined in the user_data.h into the coder buffer, see "User Data"

Value management configuration

  • CODER_VMS_SDT - use SDT value interface when accessing external values from the encoding and decoding functions (this switch comes together with SDT switch XUSE_GENERIC_FUNC, which chooses generic value representation out of two available value representations for SDT/C values, by default it is turned off and old (backwards compatible) value representation is used)
  • CODER_VMS_TTCN - use TTCN value interface when accessing external values from the encoding and decoding functions
  • CODER_VMS_USER - choose user value interface for accessing external values from the encoding and decoding functions (file "vms_vr_user.h" must be edited to configure user value access, it is included for library compilation)

By default CODER_VMS_SDT is chosen.

Printing configuration

  • CODER_VMS_PRINT - enable debug printing opportunities (see "Printing Opportunities" )

By default the coder library is compiled without debug printing functionality.

Generating Environment Files with Coding

You can call the encoding and decoding functions from the environment functions if you do not want to manipulate the encoded bit pattern explicitly in your SDL system.

The SDL Suite tools generate templates for the environment files that contains all necessary calls to buffer management functions, encoding functions and decoding functions. You can, of course, adapt this template to your needs or even write all the calls yourself. See 57 Building an Application or 65 The Cmicro SDL to C Compiler.

The template solution in the environment files has the following properties:

  • One global buffer reference created at start-up of system. This buffer reference is used in all calls for all signals and for both encoding and decoding.
  • All signals out from the system are encoded into bit-patterns. All parameters of the signals are encoded.
  • All signals into the system decodes bit-patterns.

Compiling and Linking

The instructions you must perform in order to compile and link are listed in Tutorial: Using ASN.1 Data Types.


59 The Targeting Expert

When doing targeting there is a lot of information to be provided, for instance how to generate the C source code, how to configure the SDL to C compiler, which compiler to be used etc.

The Targeting Expert is a tool managing the complete process of targeting (for the Cadvanced and the Cmicro SDL to C compilers only).

The easiest way to get an executable from an SDL specification (just generate C code for a complete SDL system - compile and link the executable) is as well supported as more complex cases. Therefore there are several Pre-defined Integration Settings which are ready-to-use.

Furthermore the Targeting Expert is able to re-use the deployments done in the Deployment Editor (see "The Deployment Editor" ) and to configure any single option thinkable in the process of doing targeting with Telelogic Tau. Those options can be the SDL to C compiler's options, the compiler, linker and make tool options, for example.

After all this chapter is a description of the Targeting Expert Interactive Mode and a reference for the Batch Mode.

A list of FAQs (frequently asked questions) can be found at the end of this document.


Introduction

The Targeting Expert assists you in setting up and configuring a complete target application. A sub-set of the Targeting Expert functionality can be used in Batch Mode when it is only desired to re-build the complete system (or just several components).

Starting the Targeting Expert

In graphical Mode

Starting the Targeting Expert in the graphical mode means that the user interface is visible and you can directly interact by selecting function and menu items.

You enter the graphical mode by selecting Targeting Expert in the Organizer's Generate menu or by using the following command line options:

sdttaex [ -h | -v | -pdm <partition_diagram>.pdm | -sdt <systemname>.sdt | -pr <systemname>.pr] [ -t <target>] [ -hostsim | -realsim | -sim | -val | -makeall ]

Option | Relevance
-v | The version number is shown and the application exits.
-h | Information about the usage is shown and the application exits.
-pdm <partition_diagram>.pdm | The partitioning diagram file to be used.
-sdt <systemname>.sdt | The system file to be used.
-pr <systemname>.pr | The system's PR file to be used
-t <target> | The qualifier of the SDL system's part to build
-makeint <integration> | Make the given integration
-makeall | Re-make last configuration

More information about the user interface can be found in "The Main Window" .

See "Interactive Mode" to get familiar with the Targeting Expert functionality.

In Batch Mode

The command line mode is also called Batch Mode. Please see the appropriate sections for a more detailed description.

Possible command line options are:

taexbatch [ -v | -h | -yes | -no ]

Option | Relevance
-v | The version number is printed to stdout and the application exits.
-h | Information about the usage is printed to stdout and the application exits.
-yes | All the questions that probably come up will be answered with 'yes'.
-no | All the questions that probably come up will be answered with 'no'.

For more information about the commands allowed in a batch file see "Description of Batch Mode Commands" .


The Graphical User Interface

This section describes the appearance and functionality of the graphical user interface of the Targeting Expert (sdttaex). Some user interface descriptions common to all tools in Telelogic Tau can be found in 1 User Interface and Basic Operations.

The Main Window

When you start the Targeting Expert in the interactive mode its main window is displayed.

Figure 505 : The Targeting Expert main window

The Menu Bar

This section describes the menu bar of the Targeting Expert Main window and all the available menu choices.

The menu bar contains the following menus:

  • File Menu
  • Edit Menu
  • Make Menu
  • Tools Menu
  • Help Menu
    (See "Help Menu" .)

Configurable Menus

In Telelogic Tau, some menu choices may be available through the concept of user-defined menus. For more information, see "Defining Menus in the SDL Suite" .

The definition file for user-defined menus searched for by the Targeting Expert is called taex-menus.ini.

There are several placeholders possible to be used with the FormattedCommand clause in taex-menus.ini.

placeholder | ... will be replaced by ...
%s | system directory
%b | target directory (the one given in the Organizer)
%t | sub target directory (the one calculated depending on the selected component and integration)
%e | executable name (inclusive extension)
%i | intermediate directory

File Menu

The File menu contains the following menu choices:

  • Open
  • Save
  • Exit

See "File Menu" .

Edit Menu

The Edit menu gives access to the enlargement of the Targeting Expert configuration files.

  • Add Compiler
  • Edit Compiler Section
  • Remove Compiler
  • Add Communications Link
  • Remove Communications Link
  • Edit Makefile
    A text editor is displayed where you can modify the generated makefile.
  • Edit Configuration Header File
    A text editor is displayed where you can modify the generated configuration header file.
  • Edit Environment File
    A text editor is displayed where you can modify the generated environment C file.

Make Menu

The Make menu allows to control the make process of the Targeting Expert.

  • Analyze
    The selected integration will be analyzed.
  • Generate code
    C code will be generated for the selected integration.
  • Make all
    All the configured components will be made again.
  • Clean
    All the object files in the object directory will be removed.

Tools Menu

The Tools menu gives access to other Telelogic Tau tools.

  • Show Organizer
    The Organizer main window is displayed.
  • Load SDL System
    The partitioned SDL system that is currently worked on in the Targeting Expert can be loaded into the Organizer. Use this entry if the Targeting Expert main window is displayed after the execution in the batch mode has failed.
  • Utilities > DOS to UNIX
    It is possible to specify a list of ASCII files. All the files in this list will be converted from DOS to UNIX style. See "DOS to UNIX"
  • Utilities > UNIX to DOS
    It is possible to specify a list of ASCII files. All the files in this list will be converted from UNIX to DOS style. See "UNIX to DOS"
  • Utilities > Indent
    The indentation of all the ASCII files in the list of files specified by the user will be corrected. See "Indent"
  • Utilities > Preprocess
    The list of generated C files that is specified by the user will be preprocesses. See "Preprocessor"
  • Wizards > TCP/IP communication
    A wizard dialog pops up and allows you to configure the TCP/IP communication between different components. See "TCP/IP signal sending"
  • SDL > Simulator UI
    This menu choice starts a new, empty Simulator UI. Several Simulator UIs may exist at the same time. See "Graphical User Interface" .
  • SDL > Validator UI
    This menu choice starts a new, empty Validator UI. Several Validator UIs may exist at the same time. See "Graphical User Interface" .
  • SDL > SDL Target Tester
    This menu choice starts a new, empty SDL Target Tester UI. See "Graphical User Interface" .
  • Customize
    A dialog pops up and allows to customize the Targeting Expert. See "Customization" for more details.

The Integration Tool Bar

The integration tool bar should be used to (from left to right)

  • Select the Pre-defined Integration Settings
  • Get help about the selected integration
  • Select an SDL to C Compiler
  • Select a C Compiler to be used

Furthermore it should also be used to handle pre-defined and user-defined integration settings (see "Handling of Settings" ), i.e.

  • to set a new user settings file name
  • to export user settings as pre-defined settings
  • to import node or application settings

The Work Area

The work area of the Targeting Expert is used for giving input masks for the different configurations and scalings.

The different input masks are described in

  • "Configure how to Make the Component"
  • "Configure Compiler, Linker and Make"
  • "Configure and Scale the Target Library"
  • "Configure the SDL Target Tester (Cmicro only)"
  • "Configure the Host (Cmicro only)"

The Event Log

The Targeting Expert has an event log containing information about found inconsistencies, read/write problems concerning file access, output, etc.

Figure 506 : The event log

Analyzer/Compiler Errors

You can access analyzer and compiler errors by double clicking the error message in the event log.

  • In case of an analyzer error the SDL Editor is displayed with the erroneous SDL symbol highlighted.
  • In case of a compiler error the selected editor is displayed with the erroneous line highlighted.
    Note 1: the selected editor must be able to highlight the desired line. It has to be selected in the Customization of the Targeting Expert.
    Note 2: the compiler's error message syntax must be described in the Compiler Error Descriptions section in file sdttaex.par for the compiler used.


Interactive Mode

You can use the Targeting Expert interactive mode to achieve different targets to:

  • Build an un-configured or optimized target executable by following the steps described in "Targeting Work Flow" .
  • Configure the distributed Telelogic Tau release and handle the already done settings. Please see below.

Although most of the steps in targeting are supported in the Targeting Work Flow you sometimes need access to other functionality, for example:

  • Compiler Definition for Compilation to the target library's known compilers.
  • Communications Link Definition for Compilation (for the inter-communication with the SDL Target Tester's host application).
  • Handling of Settings
  • Customization

Compiler Definition for Compilation

Note:

All the modifications that can be done here are only valid for the current system, i.e. all the information will be stored into the system's target directory.

Add

The following is applicable only if using the Cmicro SDL to C compiler:

Select Add a new Compiler from the Edit menu. The Add compiler dialog is displayed.

Figure 507 : Add compiler dialog

  • Compiler Name
    The text you enter here will be used to identify the compiler in the Compiler Flag list.
  • Compiler Macro
    The macro name you enter here will be used to identify the compiler in the target library. The compiler macro must fit to [A-Za-z_][A-Za-z0-9_]*

When you click Add the compiler is added to the c*_conf.def file. Please see "Configuration Files" for information about the file's syntax and duty.

Edit

For each compiler that is supported by a target library there is a specific section in

  • scttypes.h (Cadvanced), see "Compiler Definition Section in scttypes.h" .
  • ml_typ.h (Cmicro), see "Adaptation to Compilers"

Whenever there is a compiler flag defined, not known by the library, a file called user_cc.h will be included which has to contain the compiler specific settings.

The dialogs shown below are input masks that request all the needed information to generate such a file. Select Edit Compiler Section from the Edit Menu.

Cadvanced

Figure 508 : Edit compiler section dialog (Cadvanced)

For Cadvanced the following is requested:

  • #define xptrint
    Enter the mapping for xptrint values; usually unsigned long.
  • Include paths
    • The compiler supports <stdio.h>
      If selected this section will be generated:
      #ifdef XREADANDWRITEF
      #include <stdio.h>
      #endif
      Otherwise nothing will be generated here.
    • Additional includes
      The contents of the edit box will simply be copied in to the user_cc.h file. It should carry something like #include <file>.
  • User definitions
    Enter user definitions for the user_cc.h file.

Cmicro

Figure 509 : Edit compiler section dialog (Cmicro)

For Cmicro the following is requested:

  • #define xptrint
    Enter the mapping for xptrint values; usually unsigned long.
  • #define xint32
    Enter the mapping for xint32 values; usually long.
  • The compiler is able to handle function prototypes as in ANSI C
    • If selected this section will be generated:
      #undef XNOPROTO
      #define XPP(x) x
      #define PROTO(x) x
    • If not selected this section will be generated:
      #define XNOPROTO
      #define XPP(x)
      #define PROTO(x)
  • The micro controller/processor is faster in accessing characters than integer values.
    • If selected this section will be generated:
      #define xmk_OPT_INT char
    • If not selected this section will be generated:
      #define xmk_OPT_INT integer
  • The compiler supports variables stored in registers
    • If selected this section will be generated:
      #undef X_REGISTER
      #define X_REGISTER register
    • If not selected this section will be generated:
      #undef X_REGISTER
      #define X_REGISTER
  • The compiler is able to handle the C keyword <const> in the correct way
    • If selected this section will be generated:
      #undef XCONST
      #define XCONST const
    • If not selected this section will be generated:
      #undef XCONST
      #define XCONST
  • Target platform offers OS functions
    • If selected this section will be generated:
      #define XMK_USE_OS_ENVIRONMENT
    • If not selected this section will be generated:
      #undef XMK_USE_OS_ENVIRONMENT
  • Critical paths
    Enter the commands which are needed to have critical paths, i.e. how to disable and enable interrupts.

Note:

All the commands you enter will be copied in to user_cc.h. If there is more than one line of source code, each line must end with a '\' because the compiler's preprocessor depends on it.

  • "no more memory" action
    Enter the action (e.g. a function call) to process if no more memory can be allocated.
  • Kernel exit
    Enter the function call to process if the kernel should be exited. DEfault is exit();
  • Include paths
    • The compiler supports <stdio.h>
      If selected this section will be generated:
      #ifdef XMK_ADD_PRINTF
      #include <stdio.h>
      #endif
      Otherwise nothing will be generated here.
    • Additional includes
      The contents of the edit box will simply be copied into the user_cc.h file. It should carry something like #include <file>.
  • User definitions
    Enter user definitions for the user_cc.h file.

Remove

The following is applicable only if using the Cmicro SDL to C compiler:

To remove a compiler from the private c*_conf.def file, select Remove an Unused Compiler from the Edit Menu

Figure 510 : Remove compiler dialog

Note:

The file user_cc.h will not be affected by removing a compiler from the c*_conf.def file.

Communications Link Definition for Compilation

The following is only applicable if using the Cmicro SDL to C compiler.

Note:

All the modifications that can be done here are only valid for the current system, i.e. all the information will be stored into the system's target directory.

Add

To allow the selection of a new communications link in the Targeting Expert user interface the appropriate macros should be given in the Targeting Expert.

Select Add a User Defined Communications Link from the Edit Menu.

Figure 511 : Add a user defined communications link

  • CommLink Name
    The text will be shown in the Targeting Expert UI to identify it in the dialog described in "Configure the SDL Target Tester (Cmicro only)" .
  • CommLink Macro
    The macro name will be used to identify the communications link in the target library. The communications link macro must fit to [A-Za-z_][A-Za-z0-9_]*
  • CommLink Group
    The text will be used to build a group of the communications link description done here, i.e. the CommLink macro and the dependent flags will be summarized as the group given here.
  • Dependent Flags
    • Add List
      A dialog where you enter a Value List is displayed.
    • Add Text
      A dialog where you enter a Text Value Flag is displayed.
    • Remove
      The entry you have selected in the list box will be removed.

When you click Add the communications link is added to the c*_conf.def file. Please see "Configuration Files" for information about the file's syntax and duty.

Note:

The communications link source code has to be set up by the user.

Value List

Figure 512 : Add a flag taking a list of values

  • Name
    The name is used for identification purposes in the Targeting Expert user interface.
  • Macro
    The macro will be used for scaling purposes in the target library. It must fit to [A-Za-z_][A-Za-z0-9_]*
  • List of possible values
    Enter a list of all allowed values the macro can take. Each entry has to be delimited by <return>.
  • Default value
    Enter the default value which must be one of the possible values entered above.

When you click Add this value list is added to the communications link you entered in the dialog in Figure 511.

Text Value Flag

Figure 513 : Add a flag taking text

  • Name
    The name is used for identification purposes in the Targeting Expert user interface.
  • Macro
    The macro will be used for scaling purposes in the target library. It must fit to [A-Za-z_][A-Za-z0-9_]*
  • Lower limit
    Enter the lower limit if the value given with this macro is an integer value.
  • Upper limit
    Enter the upper limit if the value given with this macro is an integer value.
  • Default value
    The default value of the macro in this edit line has to be between the lower and upper limit if it is an integer value. Of course, it is possible to enter an alphanumeric value here, too.

When you click Add this value list is added to the communications link you entered in the dialog shown in Figure 511.

Remove

To remove a communications link from the private c_conf.def file, select Remove a communications link from the Edit Menu.

Figure 514 : Remove a communications link

Handling of Settings

General

The integration tool bar on the main window offers four buttons to handle the settings, i.e. the way settings are stored and where they are taken from can be influenced.

Figure 515 : Integration tool bar in the main window

Note:

The settings addressed in this section are only compiler, linker and make settings. The configuration of the SDL to C compiler library is not touched!

After selecting pre-defined integration settings the Targeting Expert automatically creates a file called <integration_name>.uis in the according component directory. (Please see "Target Sub-Directory Structure" ).

For some reasons it is sometimes useful to modify this way of saving the user done settings. E.g.

  • To be able to "play" with settings it can be useful to switch to another file while the default one is not touched. After playing it is easy to switch back to the old settings by selecting the old file again.

  • After doing an adaptation for a specific target the manually modified settings can be exported as new pre-defined integration settings. Please see "Export" .

  • Estimated there are several components inside of a node and each of them should be build the same way, then it is probably useful to do the adaptation of settings once on node level and to import these settings for each component.
    This also means that the compiler, linker and make settings can no longer be modified on component level.

  • Estimated there are several components in different nodes that should be build the same way, then it is possible to import the setting from the application.
    This also means that the compiler, linker and make settings can not be modified any longer on component level.

Estimated there is an integration 'A' and there are modified settings on this integration on application, node and component level. Then there are three different files A.uis saved in the correspondent application, node and component directories.
Figure 516 shows where the settings can be done and where they are taken from when the component is selected.

Figure 516 : handling the user settings

Export

The settings of the currently selected integration will be exported as new Pre-defined Integration Settings with the name given in the first dialog that pops up.

Figure 517

Note:

All the integrations must have unique names, i.e. it is not possible to export settings with an already known name.

  • Export pre-defined integration as project settings
    In this case the new .its file is stored in the same directory as the <systemname>.sdt file. This has the advantage that all users working on the system can access the pre-defined integration.
  • Export pre-defined integration as user settings
    The .its file is stored in the <installationdir> in Windows or respectively the §HOME/.telelogic directory on UNIX. This has the advantage that other users do not see all the new pre-defined integration settings.

In the second dialog a list of template files which have to be copied into the target directory can be specified. As default, the list of files from the "parent" settings will be given. Modify the list to your needs. Directly after exporting the settings they can be used for further configurations.

Note:

The sections Configuration Settings to Be Set and Configuration Settings to Be Reset are not exported.

Customization

The Targeting Expert interactive mode can be customized. After selecting the Customize entry in the Tools Menu the dialog shown in Figure 518 pops up.

Figure 518 : Customize dialog

Text Editor

The text editor which should be opened to edit or view text files can be selected here. The list of supported editors depends on the platform the Targeting Expert is running on (Windows/UNIX). It can be modified or extended in the file sdttaex.par. Please see "Parameter File sdttaex.par" .

Advanced Mode

The advanced mode allows you to:

  • do more configurations than possible in the non-advanced mode. See "More Configurations" for more information.
  • switch between different dialogs without using the Cancel or Save button
  • start the code generation automatically when selecting a new integration
  • configure all compilers. Even the ones that are not available on the used platform.

More Configurations

  • Normally there is no need to modify the compiler flag if using a pre-defined integration, but in the advanced mode the Compiler Flag can be modified.
  • The standard pre-defined integrations do not allow you to use all the configuration options in the Configure and Scale the Target Library dialog (disabled). If the advanced mode is switched on, it is possible to switch on and off all the options supported by the SDL to C compiler library.

Caution!

The pre-defined integrations distributed are tested only with the given library configuration. It is not guaranteed that it will work for all kinds of modifications!


Targeting Work Flow

Introduction

You can start the Targeting Expert form the Organizer's Generate menu when having a deployment diagram, the SDL system or a block/process of the SDL system selected.

Estimated the SDL system is selected the Targeting Expert converts the system into a default partitioning diagram model (deployment diagram). This is done because the Targeting Expert can only handle partitioning diagram models as an input. The tree window shown in Figure 519 gives an idea how the default partitioning diagram model looks like.

Figure 519 : Partitioning diagram in the Targeting Expert

The different entries have got the following meaning:

application
This is the collection of all the deployed SDL systems. It is used as an object to allow configurations of several nodes only, i.e. it is not possible to make an application.
node
A node symbolizes an instance of the platform/computational resource that components execute on, i.e. it is not possible to make a node.
component
A component is interpreted as an executable program.

I.e. an application or node can be configured but not build. Only components can end up in executable programs.

In the start-up phase, directly after the partitioning diagram model has been displayed, the Targeting Expert generates a sub-directory structure into which all the configuration settings, object files and so on will be put. Please see "Target Sub-Directory Structure" for more information.

Now you can use the Targeting Expert to configure each component.

Hint:

If you switch the Targeting Assistant on in the "Help" menu, there are tool tips displayed for each entry on the main window.

Operation Steps

The following operation steps should be done at least once when doing targeting for a component the very first time. When the Targeting Expert is used again later to optimize the target it is of course not necessary to do all the steps once more.

Actions to perform:
  • Select the component which should be configured.

Note:

All the settings you define and the actions automatically performed by the Targeting Expert have an influence only on the component selected in the Targeting Expert tree window (see Figure 519).
If the configuration should be re-used (this is sometimes reasonable if several components should be built using exactly the same settings), you can modify the way your settings are handled. Please see "Handling of Settings" .

Actions to perform:
  • Select the Pre-defined Integration Settings
  • Select an SDL to C Compiler (if not already done in the pre-defined integration settings)
  • Select a C Compiler (if not already done in the pre-defined integration settings)

Figure 520 : Integration selection in the main window

Select the Pre-defined Integration Settings

Delivered with every Telelogic Tau distribution there are several Pre-defined Integration Settings which you can use to get a target executable in an easy manner.

To get an optimized target executable concerning size and speed these pre-defined integration settings should only be seen as templates.

Please see "Distributed Pre-defined Integration Settings" .

The pre-defined integration settings can be selected in the integration tool bar in the main window (see Figure 520). All the pre-defined integration settings are sorted into the groups

  • Simulations
  • Validations
  • Target Tests
  • Bare Integrations
  • Light Integrations
  • Threaded Integrations
  • Tight Integrations

Additionally the integration <user defined>, which does not belong to an integration type and is not pre-defined, can be selected.

Hint:

If there is no set of pre-defined integration settings that fits your needs (e.g. a not yet supported compiler), it is recommended to select <user-defined> and to do the further configurations by hand.

Select an SDL to C Compiler

The SDL to C compiler to be used will automatically be set if you select one of the pre-defined integration settings. It is only necessary to select the SDL to C compiler if the <user-defined> settings have been selected. All the available SDL to C compilers will be given in the combo box shown in Figure 520.

Depending on the licenses found the following SDL to C compilers are supported:

  • Cadvanced
  • Cmicro

Note:

Directly after the SDL to C compiler is selected (i.e. after pre-defined integration settings are selected) the Targeting Expert checks if there is already an automatic configuration file sdl_cfg.h (done by the SDL to C compiler) available.
If not, the SDL to C compiler should be invoked to generate an automatic configuration.
For Cadvanced this is only done if the flag USER_CONFIG is set in the compiler options (e.g. -DUSER_CONFIG).

Select a C Compiler

After a pre-defined integration setting is selected the Targeting Expert tries to automatically set the compiler to be used, i.e.

  • if there is only one compiler supported with the selected pre-defined integration settings than that one is set.
  • if there are more than one compiler supported the Targeting Expert tries to set the default compiler selected in the Telelogic Tau Preferences. (Please see 3 The Preference Manager)

However, it is possible to set another compiler by selecting it in the combo box shown in Figure 520.

If the <user defined> integration has been chosen, a new compiler can be added by selecting the entry "Add new compiler description".

Actions to perform:
  • Configure Compiler, Linker and Make
  • Configure and Scale the Target Library
  • Configure the SDL Target Tester (Cmicro only)
  • Configure the Host (Cmicro only)

To select the desired configuration dialog, please select the correspondent entry in the partitioning diagram.

Figure 521 : Tree structure in the partitioning diagram

Configure Compiler, Linker and Make

This part of the configuration is divided into four sub-steps which are taken from the selected pre-defined integration settings as far as possible.

Compiler

You enter the needed compiler configuration in a special input mask. The compiler you specify here will be used to compile the generated code and the target library.

Figure 522 : Compiler configuration

Click Default if you want to restore the default values.

  • Compiler Name
    Enter the name of the compiler application.
  • Options
    Enter the options given to the compiler as command line arguments here.
    • Enter the placeholder %s where the source file name of the file to be compiled has to be inserted (used for the makefile generation).
    • Enter the dummy parameter %o where the object file's name has to be inserted (used for the makefile generation).
    • Enter the dummy parameter %I where the include path option has to be placed (see below).
  • Compile as C++
    The compiler options to compile C files as C++ files will be added/removed from the Options. For a definition of the used compiler options see the "Parameter File sdttaex.par" .
  • Compile as debug
    The compiler options to generate the object files including debug information will be added/removed from the Options. For a definition of the used compiler options see the "Parameter File sdttaex.par" .
  • Library Flag
    The compiler option to define a flag plus the C macro used to select the desired library must be given here. (When using Cmicro this field is empty per default.)
  • Include
    Enter the compiler option needed to specify include paths and the include paths themselves here. The complete contents of this entry will replace the entry %I in the Options (see above).
    The include path can contain the following environment variables (The environment variables will be expanded during the make execution):

Variable | Path it points to
sdtdir | <installationdir>/sdt/sdtdir/<platform> as long as Library directory is not set
scttargetdir | Absolute path to the current target directory (depends on the selected component)
sctobjdir | $(scttargetdir) + the relative path selected in Object directory
sctuseinclude (Cadvanced only) | $(sdtdir)/INCLUDE
sctincludedir (Cmicro only) | $(sdtdir)/cmicro/include
sctkerneldir (Cmicro only) | $(sdtdir)/cmicro/kernel
scttesterdir (Cmicro only) | $(sdtdir)/cmicro/tester

  • Comm Include
    The compiler option needed to specify include paths and the include paths to the coder library must be given here. (Only used if the ASN.1 and/or SDL coder functions are generated and used)
  • Obj. extension
    Enter the object extension to be used for the compiler output.

If only the information up to here is specified in this dialog, each C file is compiled in one single step as shown in Figure 523.

Figure 523 :Single step compilation model

For some target compilers, compilation is done in three steps using three different tools. If that is the case, the compilation of each C file is done like shown in Figure 524. In this case the following entries also need to be given.

Figure 524 :Three step compilation model

  • C parser name
    The name of the C parser application has to be given here.
  • Options (C parser)
    Enter the options given to the C parser as command line arguments here.
    • Enter the placeholder %s where the input file name of the file to be parsed has to be inserted (used for the makefile generation).
    • Enter the dummy parameter %o where the output file's name has to be inserted (used for the makefile generation).
  • Input extension (C parser)
    Enter the input file's extension for the C parser.
  • Assembler
    The third step to process is the execution of the assembler. Enter the name of the assembler application here.
  • Options (Assembler)
    Enter the options given to the assembler as command line arguments here.
    • Enter the placeholder %s where the input file name of the file to be assemble has to be inserted (used for the makefile generation).
    • Enter the dummy parameter %o where the output file's name has to be inserted (used for the makefile generation).
  • Input Extension (Assembler)
    The input file's extension used by the assembler has to be specified in this edit line.

Source Files

All the files (except the coder and the generated files) which will be compiled and linked to the target executable are listed here.

Figure 525 : Source files used

  • Used kernel and library files and
    Used SDL Target Tester files (Cmicro only)
    • Default
      Restores the default values.
    • Add
      A file selection dialog is opened where you can select the file which should be added to the list of kernel files.
    • Remove
      Removes the item you have selected in the list box.
    • Modify
      A dialog pops up and the selected entry can be modified.
    • Clear
      Deletes all the items in the list box.

Compiler Flag

Note:

This section is only available if the Advanced Mode is selected and the SDL to C compiler Cmicro is used.

When compiling the generated code and/or the SDL to C compiler's library you need to set a compiler flag to adjust the code.

The list of available compilers shown in Figure 526 belongs to the Cadvanced target library.

Figure 526 : Flag selection

Caution!

You must select the correct compiler flag in order to avoid compilation errors.

For more information concerning the compiler specific adjustment of the libraries see

  • scttypes.h (Cadvanced), see "Compiler Definition Section in scttypes.h" .
  • ml_typ.h (Cmicro), see "Adaptation to Compilers"

Additional Compiler

If there are other files than the generated ones or the SDL to C compiler's library to be compiled all the requested things in this section have to be entered.

Figure 527 : Additional compiler configuration

  • Compiler Name
    Enter the name of the compiler application.
  • Options
    Enter the options given to the compiler as command line arguments here.
    • Enter the placeholder %s where the source file name of the file to be compiled has to be inserted (used for the makefile generation).
    • Enter the dummy parameter %o where the object file's name has to be inserted (used for the makefile generation).
    • Enter the dummy parameter %I where the include path option has to be placed (see below).
  • Include
    Enter the compiler option needed to specify include paths and the include paths themselves here. The complete contents of this entry will replace the entry %I in the Options (see above).
  • Obj. extension
    Enter the object extension to be used for the compiler output.
  • List of files
    • Default
      Restores the default values.
    • Add
      A file selection dialog is opened where you can select the file which should be additionally compiled.
    • Remove
      Removes the item you have selected in the list box.
    • Modify
      A dialog is displayed and the selected entry can be modified
    • Clear
      Deletes all the items in the list box.
  • Dependencies
    List the dependencies for the makefile here. Note that the name of the additional file itself is automatically generated as a dependency.

Linker

To link all the compiled files (generated ones, the ones building the library and additional ones) you must configure a linker.

Figure 528 : Linker configuration

Click Default if you want to restore the default values.

  • Linker name
    Enter the name of the linker application.
  • Options
    Enter the options given to the compiler as command line arguments here.
    • Enter the dummy parameter %O in the place of the list of all compiled files and the additional object files to link (used for the makefile generation).
    • Enter the dummy parameter %L in the place of the list of all the libraries (if there are some) which have to be linked.
    • Enter the dummy parameter %e in the place where the executable file's name has to be inserted (used for the makefile generation).
  • Exe. extension
    Enter the executable extension to be used for the linker output.
  • Additional object files and Additional libraries
    • Default
      Restores the default values.
    • Add
      A file selection dialog is opened where you can select the file which should be additionally linked to the executable.
    • Remove
      Removes the item you have selected in the list box.
    • Modify
      A dialog is displayed and the selected item in the list box can be modified.
    • Clear
      Deletes all the items in the list box.

Library Manager

Note:

This section is available only if an SDL and/or ASN.1 coder is selected. Please see "Communication" for details on how to select a coder.

The library manager offers the command that will be used to build a library from all the coder files. The dialog is shown in Figure 529

Figure 529 : Library Manager Configuration

Note:

If no library manager is given all the coder object files will be linked directly to the target application.

Click Default if you want to restore the default values.

  • Lib. Manager
    Enter the name of the library manager application.
  • Options
    Enter the options given to the library manager as command line arguments here.
    • Enter the dummy parameter %O in the place of the list of all coder object files to link (used for the makefile generation).
    • Enter the dummy parameter %l in the place where the library's name has to be inserted (used for the makefile generation).
  • Library extension
    Enter the library extension here.

Make

You can select the make tool to do all the compile and link actions here.

Figure 530 : Make tool configuration

Click Default if you want to restore the default values.

  • Make tool
    Select the make tool you wish to use. Currently the following make tools are supported: (see "Make Applications" )
    • Borland make (using temporary response file)
    • Borland make (ignore exit codes)
    • Borland make
    • Microsoft nmake (using temporary response file)
    • Microsoft nmake (ignore exit codes)
    • Microsoft nmake
    • UNIX make
    • Tasking mk166
    • Tornado make

Hint:

"Using temporary response file" means that the compiler's and the linker's command line options are passed to the compiler/linker via a temporary file generated by the make tool.
This feature can only be used if the compiler in use supports this facility.

Note:

If the make tool you would like to use is not in the list. Please add a new definition in sdttaex.par. For more information view "Make Applications"

  • Generate makefile
    Select this if a makefile should be generated before make is invoked. The name of the generated makefile is the one in Makefile.
  • Generator
    The Targeting Expert is designed to execute external makefile generators whenever the build-in makefile generator (intern) is not sufficient.
    Enter the name (and the path) of the external makefile generator here. Please see "External Makefile Generator" for further information about how to build an external makefile generator.
  • Makefile
    Enter the name of the makefile.
  • Object directory
    The object directory is the relative path seen from the current target directory, in which the compiler output files (object files) should be written.

Note:

If the directory <target_directory>/<object_directory> does not exist it will be automatically created.

  • Library directory
    The library directory is the absolute path to the target library to be used. Under normal circumstances this field can be left empty as the Targeting Expert automatically uses the path in the Telelogic Tau installation:
<installationdir>/sdt/sdtdir/<platform_sdtdir>

Note:

The Cmicro target library will be expected in a sub-directory called cmicro.
The Cadvanced library will be expected in a sub-directory called INCLUDE.

  • Pre-make
    The pre-make step will be executed before any other action specified in the makefile is performed.
    • The placeholder %s will automatically be replaced by the component's name.
  • Pre-compile
    The pre-compile of the generated file(s) will be executed before they are compiled.
    Enter the application which performs the pre-compile here.
    • The placeholder %s can be used to represent the source files name.
    • The preprocessor button inserts the complete command that is necessary to pre-process the generated C file with the default compiler before the compilation with the target compiler.

Hint:

It is probably useful to use the utility functions delivered in combination with the Targeting Expert. Please see "Utilities"

  • Post-link
    The post-link of the linked files will be executed as the last step in the make task.
    Enter the application which performs the post-link here. (E.g. a conversion from absolute to Intel-HEX format).
    • The placeholder %s can be used to represent the linker output file.

Configure and Scale the Target Library

The configuration and the scaling of the used target library is done by setting/resetting compiler macros (#define in C). These macros will be called "flags" in the further description.

For more information concerning allowed flags see

  • sct_mcf.h (Cadvanced), see "Some Configuration Macros" .
  • ml_mcf.h (Cmicro), see "Compilation Flags"

The Targeting Expert offers an easy way of setting/resetting these flags. All the allowed flags are divided into different groups, e.g. SDL support and environment.

Figure 531 shows an example for Cmicro.

Figure 531 : Configuration flag dialog

When all the configurations have been done the Targeting Expert generates

  • ml_mcf.h (a C header file for Cmicro) which will be included in ml_typ.h during the compilation of the corresponding files.
    This is done for all the pre-defined integrations using the SDL to C compiler Cmicro.
  • sct_mcf.h (a C header file for Cadvanced) which will be included in scttypes.h if the flag USER_CONFIG is defined.
    The flag USER_CONFIG is only defined for the pre-defined integrations Application (applclenv) and Application, debug (debclenvcom) using the SDL to C compiler Cadvanced.

Configure the SDL Target Tester (Cmicro only)

The configuration of the SDL Target Tester is very similar to the configuration of the target library.

The settings done for the target will also be generated into the file ml_mcf.h. (Please see "Configure and Scale the Target Library" .)

Configure the Host (Cmicro only)

The settings for the host will be generated into the file sdtmt.opt which will be read by the SDL Target Tester during start-up to get information about the gateway to be used and the target's memory layout. Please see "Communication Setup on the Host System" for more information about how to configure the SDL Target Tester's host application.

Actions to perform:
  • Configure how to Make the Component
  • Make the Component

Configure how to Make the Component

The possible options are divided into four pages:

Note:

All the Analyzer options entered in the Organizer will be re-used by the Targeting Expert.

SDL to C Compiler

Figure 532

Note:

Because the Advanced Mode is switched off there might be some controls disabled because it does not make sense to modify them for the selected integration.

  • Analyze/generate code
    Switch the Analyzer and SDL to C compiler execution on/off when starting the make process.
  • Analyzer options
    The Organizer's Analyzer-Options dialog is displayed and the Analyzer options used for all the integrations can be modified. Please see "Analyze SDL" .
  • Save commands
    A text file containing all the Analyzer commands configured for the selected integration can be saved. It is possible to start the Analyzer directly using this command file with sdtsan < commandfile
  • All files
    If selected, the SDL to C compiler will generate all files anew. It does not matter whether the file's contents have changed or not. Un-selecting it can economize the build process.
  • Capitalization lower case
    When selected all identifiers are translated to lower case. Otherwise capitalization is used in the declaration of the object
  • Full variable prefix
    All the variables used in SDL will be generated with a full prefix to C to make them unique if this item is selected. This comes with a disadvantage of long variable names.
  • Instance information file
    An instance information file will be generated. Please see "SDL Instance Information" .
  • Separation
    It is possible to select between three alternatives:
    • do not separate
    • use the user defined separation done in Organizer
    • separate each SDL entity into one C file
  • File name prefix
    All the generated files (except those with fixed names like sdl_cfg.h) will be generated with the given file name prefix.
  • Environment header file
    The environment header file (.ifc) which is used in the coder and environment functions will be generated if switched on.
  • Environment functions
    Environment functions will be generated or not.

Note:

If the generation of environment functions is switched on it may be needed to add the environment source file to Source Files.

Please see
  • "Initializing the Environment / Interface to the Environment" for Cmicro
  • "Building an Application" for Cadvanced
  • Signal number file (Cadvanced only)
    Generate a signal number file if selected.
  • Conversion style (Cmicro only)
    Select the rules how to generate the converter file here.
  • Filename (Cmicro only)
    Give a name to the converter file

Communication

Figure 533 : Communication configuration

  • Generate/do not generate SDL coder functions.
    (Please see "Type description nodes for SDL types" .)
  • Generate/do not generate ASN.1 coder functions.
    (Please see "ASN.1 Type Information Generated by ASN.1 Utilities" .)
  • TCP/IP signal sending

Note:

The TCP/IP communication is supported only for a threaded integration using the SDL to C compiler Cadvanced.

The signal sending to other components can be done via a communications link. If it is switched on, a wizard dialog to set up all the needed information pops up (see Figure 534).

Figure 534 : TCP/IP communication wizard

As described in the dialog there are settings done in different sections of the Targeting Expert:

    • the manual configuration file sct_mcf.h
    • the list of source files to compile, i.e. the makefile

Furthermore the generation of

    • an Environment header file
    • Environment functions and
    • SDL coder functions

will be switched on.

Caution!

If the TCP/IP communication is switched on, a routing source file has to be provided, so that the signals destination can be calculated correctly! Otherwise all the signals will be sent to the sending application.

Caution!

If the TCP/IP communication is switched off the routing source file needs to be removed from the list of source files to compile by hand!

Env. Header File

Figure 535 : Env. header file configuration

The way the environment header file(.ifc file) is generated can be configured here. Please see "System Interface Header File" on page 2680 in chapter 57, Building an Application for more information.

Note:

The CHANNELS section cannot be configured for Cmicro because the SDL systems structure (blocks and channels) will be lost after code generation.

Execution

Figure 536 : Download and test tool configuration

  • Download Application
    Enter also the complete command line which will be necessary to invoke the download application. You can use the placeholder %t which will automatically be replaced by the name of the target executable's name (including the full path).

Note:

The selected download application will automatically be started if make was successful. The Targeting Expert does not try to invoke a download application if "Use download application" is un-checked.

  • Test Application
    There are two kinds of test applications:
    • The applications that are part of the SDL suite, i.e."The SDL Simulator" , "The SDL Validator" and "The SDL Target Tester" .
    • The applications from other vendors, e.g. a debugger or emulator.
      If you select Other you have to enter also the complete command line for the desired test tool. You can use the placeholder %t which will automatically be replaced by the target executable (including the full path).

Make the Component

The whole make process consists of several different tasks which will automatically be executed one after another. These tasks are:

  • Analyze and Generate Code
  • Generate a Makefile
  • Compile and link
  • Execute (target application or the application in Download Application and/or Test Application)

The execution of the next task will be stopped if the current task returns with an error. The Targeting Expert event log will give information about the process' state.

Analyze and Generate Code

The selected SDL to C compiler will be invoked and code will be generated for the selected component.

There are two possibilities:

  • make
    In that case only code for the modified parts of the SDL system will be generated.
  • full make
    Code for the complete SDL system is generated. Even if there are no modifications.

Generate a Makefile

The makefile to be used will be generated. Please see "Make" for information on how to give the makefile's name and how to switch the makefile generation on or off.

Hint:

If the build-in makefile generation does not fit your needs it is possible to customize the makefile generation.
Please see "External Makefile Generator" to get information on how to build a makefile generator.

Compile and link

The external make tool will be invoked using the generated makefile. Please see "Make" for information on how to select the make tool.

Hint:

To force a compilation of all the C source files the object files have to be deleted first. Please use the Clean entry in the Make Menu.

Execute

The target executable will be executed.

Note:

It is sometimes not possible to invoke the target executable from the Targeting Expert, e.g. if the target executable is built for a micro controller. In this case you can select a download application or any other test tool (e.g. debugger) which will be executed instead. Please see "Download Application" and "Test Application" .

Hint:

For running test cases the target executable's output to stdout and stderr will be re-directed automatically into the Targeting Expert event Log. The target simply should be executed by entering "%t" as the test application (Please see "Test Application" ).


Batch Mode

Using the Targeting Expert in the batch mode means starting taexbatch instead of sdttaex.

The commands have to be given one after another by hand or in a command file. (Please see an Example of a Batch File.) In this case the Targeting Expert has to be started with taexbatch < commandfile

Note:

If the commands are given in a command file the Targeting Expert should be started with one of the options -yes or -no to answer all upcoming questions automatically. Otherwise the application will probably hang up.

Syntax of Batch Mode Commands

Command Names

You may abbreviate a command name by giving sufficient characters to distinguish it from other command names. A hyphen ('-') is used to separate command names into distinct parts.

Abbreviation of Commands

You may abbreviate any part as long as the command does not become ambiguous.

Hint:

Commands used in command files should not be abbreviated because future implementations may conflict with those abbreviations.

Parameters in Commands

Parameters are separated by one or several spaces. Parameters containing spaces have to be given in quotation marks.

Case Insensitivity in Commands

In command names there is no distinction made between upper and lower case letters.

Some more Detailed Description of Parameter Types

  • <flagname>
    Allowed flag names depend on the SDL to C compiler in use.
    • For Cadvanced a description of allowed flags can be found in section "Some Configuration Macros" .
    • For Cmicro see "Compilation Flags" for a more detailed description.
      <flagname> parameters are case sensitive.
  • <boolvalue>
    Allowed boolean values can be true, on and yes which all have the same meaning no matter if written lower case or not. The same applies for the values false, off and no.
  • <stringvalue>
    Any string value is allowed here. There is no check at all if the value can be interpreted correctly. E.g. if "abc" is entered although and integer value is needed it will not be checked but probably cause a compilation error afterwards.
  • <entry>
    Allowed entries depend on the class used in the command. Please see <class>. Parameters of type <entry> are case insensitive.
  • <class>
    Allowed classes and the depending entries are shown in the table below. Parameters of type <class> are case insensitive.
    For all allowed combinations of classes and entries the commands Get-Setting and Default-Setting can be used.
    • Compiler

allowed entries | function to set contents
AsCpp | Set-Setting-String
CodInclude | Set-Setting-String
FilesToCompile | Add-Setting-String
Include | Set-Setting-String
LibFlag | Set-Setting-String
Options | Set-Setting-String
Options2 | Set-Setting-String
Options3 | Set-Setting-String
TesterFilesToCompile | Set-Setting-String
Tool | Set-Setting-String
Tool2 | Set-Setting-String
Tool3 | Set-Setting-String

    • Linker

allowed entries | function to set contents
LibrariesToLink | Add-Setting-String
ObjectsToLink | Add-Setting-String
Options | Set-Setting-String
Tool | Set-Setting-String

    • AddCompiler

allowed entries | function to set contents
AddFilesToCompile | Add-Setting-String
Depend | Set-Setting-String
Include | Set-Setting-String
Options | Set-Setting-String
Tool | Set-Setting-String

    • Make

allowed entries | function to set contents
Tool | Set-Setting-String

    • Global

allowed entries | function to set contents
AddObjectExtension | Set-Setting-String
CodeGenerator | Set-Setting-String
ExecutableExtension | Set-Setting-String
FileNamePrefix | Set-Setting-String
FullSeparation | Set-Setting-Bool
GenerateASNCoder | Set-Setting-Bool
GenerateEnvFunctions | Set-Setting-Bool
GenerateEnvHeader | Set-Setting-Bool
GenerateIfcChannels | Set-Setting-Bool
GenerateIfcLiterals | Set-Setting-Bool
GenerateIfcOperators | Set-Setting-Bool
GenerateIfcSignals | Set-Setting-Bool
GenerateIfcSynonyms | Set-Setting-Bool
GenerateIfcTypedefs | Set-Setting-Bool
GenerateInstanceInfo | Set-Setting-Bool
GenerateLowerCase | Set-Setting-Bool
GenerateMakefile | Set-Setting-Bool
GenerateSDLCoder | Set-Setting-Bool
GenerateSignalNumber | Set-Setting-Bool
IfcPrefixChannels | Set-Setting-String
IfcPrefixLiterals | Set-Setting-String
IfcPrefixSignals | Set-Setting-String
IfcPrefixSynonyms | Set-Setting-String
IfcPrefixTypes | Set-Setting-String
LibraryDirectory | Set-Setting-String
MakefileGenerator | Set-Setting-String
MakefileName | Set-Setting-String
PreCompile | Set-Setting-String
PreMake | Set-Setting-String
PostLink | Set-Setting-String
ObjectDirectory | Set-Setting-String
ObjectExtension | Set-Setting-String
TestTool | Set-Setting-String

Description of Batch Mode Commands

In this section, the batch mode commands are listed in alphabetical order, along with their parameters and a description.

Add-PR

Parameters:

<pr-filename>

Further PR files can be specified here which should be considered by the SDL to C compiler.

The first PR file has to be given by using Open-PR command.

Add-Setting-String

Parameters:

<class> <entry> <stringvalue>

The list <entry> will be extended for the item <stringvalue>.

Add-UserSection-String

Parameters:

<stringvalue>

The <stringvalue> will be added in the user section of ml_mcf.h (Cmicro) or respectively sct_mcf.h (Cadvanced).

Analyze

Parameters:

<none>

The SDL system will be analyzed.

Append-Setting-String

Parameters:

<class> <entry> <stringvalue>

<stringvalue> will be appended to the current value of <class> <entry>.

Clear-UserSection

Parameters:

<none>

The complete user section of ml_mcf.h (Cmicro) or respectively sct_mcf.h (Cadvanced) will be removed.

Default-Setting

Parameters:

<class> <entry>

The default value of the given <entry> will be restored.

Exit

Parameters:

<none>

The Targeting Expert exits (same as Quit).

Generate-Code

Parameters:

<none>

A code generation for the selected component is done using the SDL to C compiler selected in the associated settings.

Generate-Code-Full

Parameters:

<none>

A full code generation for the selected component is done using the SDL to C compiler selected in the associated settings.

Generate-Makefile

Parameters:

<none>

A makefile will be generated for the selected component. The makefile's name is taken from the associated settings.

Get-Setting

Parameters:

<class> <entry>

The current contents of <entry> will be printed on the screen.

Include

Parameters:

<batch-filename>

All the commands listed in <batch-filename> will be processed.

Help

Parameters:

<none>

A list of all commands with their needed parameters is printed.

Make-All

<none>

For the application or all the nodes and components that are configured (combined or separate configuration) the steps of analysis, code generation, makefile generation and compilation/linkage will be performed.

Make-Clean

Parameters:

<none>

All the object files will be removed.

Make-Selected

Parameters:

<none>

The make tool will be executed using the associated make tool and the associated makefile of the selected component.

Open-PDM

Parameters:

<filename>

The partitioning diagram file <filename> will be loaded.

Open-PR

Parameters:

<filename>

The PR file <filename> will be loaded and internally converted into a partitioning diagram model.

Open-SDT

Parameters:

<filename>

The system file <filename> will be loaded and internally converted into a partitioning diagram model.

Prepend-Setting-String

Parameters:

<class> <entry> <stringvalue>

<stringvalue> will be prepended to the current value of <class> <entry>.

Qualifier

Parameters:

<SDL-qualifier>

The given <SDL-qualifier> will be used for building a part of the SDL system.

Quit

Parameters:

<none>

The Targeting Expert exits (same as Exit).

Replace-Setting-String

Parameters:

<class> <entry> <old-stringvalue> <new-stringvalue>

The string <old-stringvalue> of <entry> will be replaced with <new-stringvalue>.

Save-Settings

Parameters:

<none>

The modified settings of all the available applications, nodes and components will be saved.

Select

Parameters:

[<application-node-component>]

The entry specified by <application-node-component> in the partitioning diagram will be selected. This step has to be executed before you can generate.

One of the commands Open-PDM, Open-PR or Open-SDT has to be executed before.

Set-Compiler

Parameters:

<compilername>

The given <compilername> will be set as the used compiler. The <compilername> must be available in the default settings of the Set-Integration.

The command Set-Integration has to be executed before.

Set-Flag-Bool

Parameters:

<flagname> <boolvalue>

The SDL to C compiler's library flag <flagname> will be set/reset due to the <boolvalue>.

Caution!

There is no check for interdependencies to other flags.

Set-Flag-String

Parameters:

<flagname> <stringvalue>

The SDL to C compiler's library flag <flagname> will be set to the <value>.

Caution!

There is no check for upper and lower limits. You must be aware to set a value that is in the allowed range!

Set-Integration

Parameters:

<integration>

The pre-defined integration settings <integration> will be set.

  • Simulations
    • Performance Simulation
    • Realtime Simulation
    • Simulation
    • TTCN Link
  • Validations
    • Validation
  • TargetTest
    • Application DEBUG CA
    • HostSimulation
    • HostSimulation (CL)
    • HostSimulation (CLENV)
  • Light Integrations
    • Application CA
    • Application CM
    • Application TEST
  • Threaded Integrations
    • OSE
    • Solaris
    • VxWorks
    • POSIX/Linux
    • Win32
  • Tight Integrations
    • OSE
    • Solaris
    • VxWorks
    • Win32

Note:

To set a Realtime Simulation for example, the <integration> has to be given in quotation marks, i.e.
Set-Integration "Realtime Simulation"

Caution!

In batch mode there is no check if the selected integration fits to the component settings!

Please have a look to "Distributed Pre-defined Integration Settings" for more information.

The command Select has to be executed before.

Set-Setting-Bool

Parameters:

<class> <entry> <boolvalue>

The boolean <entry> will be set to its new value.

Set-Setting-String

Parameters:

<class> <entry> <stringvalue>

The non-boolean <entry> will get the new content <stringvalue>.

Start-Download

Parameters:

<none>

The download application selected in Download Application will be invoked.

Start-Testtool

Parameters:

<none>

The test application specified in Test Application will be invoked.

system

Parameters:

<systemcommand>

Executes the <systemcommand> on the underlying OS. The following placeholders can be used in <systemcommand> and will be replaced before execution:

placeholder
... will be replaced by ...

 %s
system directory

 %b
target directory (the one given in the Organizer)

 %t
sub target directory (the one calculated depending on the selected component and integration)

 %e
executable name (inclusive extension)

 %i
intermediate directory

Write-Log

Parameters:

<filename>

All the output to stdout and stderr will also be written into the file <filename>.

Example of a Batch File

The following batch file can be used to build a Simulator using the Targeting Expert batch mode.

Example 468 : Simple batch file

Open-SDT access.sdt
select access-node-component
set-integration Simulation
set-Compiler Microsoft
Generate-Code
Generate-Makefile
Make-selected
Exit

Note:

The items application, node and component depend on the partitioning diagram model used.


Internal

Partitioning Diagram Model File

The Targeting Expert needs to know how the SDL system which is used for targeting should be partitioned. This is done by using a partitioning diagram model.

Note:

The partitioning diagram model will be generated by the Deployment Editor for deployed systems into a partitioning diagram model file <partitioning diagram model>.pdm. It should not be modified by hand! Please see "Generating Partitioning Diagram Data for the Targeting Expert" for more information.
If there is no deployment done for a system, the Targeting Expert generates a default partitioning diagram model for its internal use. This partitioning diagram model is not available as a file. For a default partitioning diagram model there is no chance to specify integration models or threads.

Definitions

The complete SDL system is mirrored in the partitioning diagram's application which takes several nodes.

Each node can represent a run-time (physical) object with memory and processing capability and is a collection of several components.

Each component is a collection of different objects, with each object representing an SDL qualifier. A component will result in one executable or OS task.

File Syntax Example

Estimated there is an SDL system like the one shown in Figure 537,

Figure 537 : An SDL system

then the simplest possible partitioning diagram model looks like the one shown in Figure 538.

Figure 538 : A possible partitioning diagram model

The first few lines of the corresponding partitioning diagram model file is shown in Example 469:

Example 469 : Partitioning diagram model file

TIMESTAMP: 948787119

APPLICATION*0: access
detail+SystemFileName: access.sdt

NODE*1: node

COMPONENT*2: component

OBJECT*3: object
detail+Qualifier: access

Explanations

  • The TIMESTAMP entry is needed for future implementations.
  • The APPLICATION*0: access gives the name of the used SDL system. The 0 is used as an identifier for internal purposes.
  • detail+SystemFileName is the name of the used <systemname>.sdt file
  • detail+PRFileName is the name of the used <systemname>.pr file. Subsequent entries of detail+PRFileName can be used to insert more than one PR file.
  • NODE*1: node specifies that the following components belong to the node. The node is called node and the unique id 1 is used for internal purposes.
  • COMPONENT*2: component specifies that the following objects belong to this component. The component is called component and the unique id 2 is used for internal purposes.
  • OBJECT+5: object gives one further object which will be assigned to the current component.
  • detail+Qualifier: access means that all the SDL entities that are sub entities of the qualifier access (in this case the complete system) will be part of the object.

More Supported Keywords

Details of COMPONENT

  • detail+Integration: Light|Threaded|Tight specifies in which integration model the component should be build. For backwards compatibility, the keyword ThreadedLight is accepted as an alias for Threaded.

Details of OBJECT

  • detail+Type: system|block|process tells which kind of SDL agent the qualifier is all about.

Details of THREAD

  • THREAD: name is a sub entry of COMPONENT and specifies a thread, e.g. for a threaded integration.
  • detail+ThreadPriority: value specifies the OS priority of the particular thread.
  • detail+StackSize: value specifies the stack size of the thread. (bytes)
  • detail+QueueSize: value specifies the maximum number of signals that are allowed in the queue.
  • detail+MaxSignalSize: value specifies the maximum size of an individual signal in the queue. (bytes)
  • detail+OneThreadPerInstance: true|false tells if each process instance will become its own thread in a threaded integration if the value is true.

Configuration Files

For each SDL to C compiler that will be used there is one configuration file ca_conf.def (Cadvanced) and cm_conf.def (Cmicro).

The configuration files for all SDL to C compilers can be found in <installationdir>/sdt/sdtdir.

The c*_conf.def files are ASCII text files that can be (should be) extended by you to adapt a new compiler or to adapt a new communications link (Cmicro only).

You can find all the known configuration flags in:

  • "Some Configuration Macros" (Cadvanced)
  • "Compilation Flags" (for Cmicro)

Structure of the Configuration File cm_conf.def

Note:

All the descriptions in this section are valid for the SDL to C compiler Cmicro only.

Compiler

All the compilers currently supported by a SDL to C compiler library are listed in the c*_conf.def file like displayed in Example 470.

Example 470 : Structure of a compiler entry

BEGIN
IAR_C51
IAR systems compiler of 8051
COMPILER
Microcontroller compiler
END

The first and the last line of the example simply marks the start and the end of one entry.

Line 2 is the flag which will be used to include the appropriate compiler section in the used library (see ml_typ.h for Cmicro and scttypes.h for Cadvanced).

Line 3 is the text which will be shown in the Targeting Experts user interface.

Line 4 must be COMPILER in this case.

Line 5 is the compiler group this compiler should be associated with. In the distributed files c*_conf.def there are three groups, namely:

    • Micro controller compiler
    • PC compiler
    • Workstation compiler

Communications Link

Note:

This section is valid only if the Cmicro SDL to C Compiler is used.

The example below shows the structure of one entry.

Example 471 : Structure of a cm_conf.def entries

1 BEGIN
2 XMK_USE_V24
3 V24 communication
4 COMMLINK
5 V24 interface
6 AUTOSET
7 XMK_V24_BAUD
8 XMK_V24_DEVICE
9 END
10 END

Lines 1 and 10 mark the start and the end of one entry.

Line 2 gives the name of the flag as it appears in the generated file ml_mcf.h. According to this example line 3 is the marker which appears in the Targeting Expert graphical user interface.

Line 4 specifies the main group this entry belongs to. It has to be COMMLINK in this case.

Line 5 gives the subgroup of the entry. This subgroup can be anything you like. In the delivered version there is only the subgroup V24 interface. However, you can define your own communications link CAN Bus for example.

The lines 6 and 9 belong together and between these lines all flags are listed which have to be set when the flag on line 2 is set. The amount of flags (lines 7 and 8 in the example) is free. In the same way as AUTOSET in line 6 there can also be the entries RESET or DEPEND.

RESET means the following flags will be reset if this flag is defined and DEPEND means this flag can only be set if the following flags (lines 7 and 8) are already defined.

Not given in the example above is the section VALUE, (like AUTOSET finished by an END) which assign a value to the flag. This section can include three lines of information. The first gives the default value. And, if the value is numeric, the second line gives the lowest and the third one the highest value. You are asked to have a look into c*_conf.def.

Also not given in the example above is the section VALUE_LIST (finished by an END) which assign a value to the flag with a list of allowed values given. The first value is the default value, the following values (with no upper limit) are giving the list of allowed values. The default value must be given in the list again.

Pre-defined Integration Settings

Introduction

Pre-defined integration settings must be seen as a set of default values which can be used for targeting purposes.

There are several pre-defined integration settings distributed with each Telelogic Tau installation.

  • Each set of predefined integration settings is stored in an ASCII file with the extension .its.
  • The amount of pre-defined integration settings that are to be handled by the Targeting Expert can simply be enlarged by copying a new file <name>.its or by exporting own settings. (See "Export" )
  • The integration names have to be unique!
  • The Targeting Expert searches for .its files in the following directories:

Figure 539 : Search order on UNIX

Figure 540 : Search order in Windows

Distributed Pre-defined Integration Settings

For Use with Cadvanced SDL to C Compiler

  • Simulation (debcom)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are not implemented, i.e. timers set in the SDL system will expire at once
Environment
Will be handled in the Simulator UI
More info
See 49 The SDL Simulator.

  • Realtime Simulation (debclcom)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Will be handled in the Simulator UI
More info
See 49 The SDL Simulator.

  • Performance Simulation (perfsim)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Not handled
Environment
Not handled
More info
See 63 The Performance Library.

  • TTCN Link

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
On HP:
    • HP GNU gcc
    • cc
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory

 $(sdtdir)/SCT*TTCNLINK
More info
See 36 TTCN Test Suite Generation.

  • Validation

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
On HP:
    • HP GNU gcc
    • HP cc
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory

 $(sdtdir)/SCT*VALIDATOR
More info
See 52 The SDL Validator.

  • Application (applclenv)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Has to be implemented by the user.
More info
See "Compilation Switches" .

  • Application, debug (debclenvcom)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Has to be implemented by the user.
More info
See "Compilation Switches" .

  • Threaded integrations for the platforms
    • OSE (Softkernel Solaris and Windows)
    • Solaris
    • VxWorks (Softkernel Solaris and Windows)

Note: (VxWorks only)

The environment variable WIND_BASE has to be set on your system!

    • Win32
    • OSE (Softkernel Solaris)

Note: (OSE only)

The environment variable OSE_ROOT has to be set on your system!

Supported compiler
OSE:
    • Sun GNU gcc
    • Microsoft VC++
Solaris:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
VxWorks:
    • Tornado ccsimpc
    • Tornado ccsimso
Win32:
    • Microsoft VC++
Used kernel directory
-
Timers
OS timer
More info
See "Threaded Integration" .

  • Tight integrations for the platform
    • OSE (Softkernel Win32)

Note: (OSE only)

The environment variable OSE_ROOT has to be set on your system!

    • Solaris
    • VxWorks (Softkernel Win32)

Note: (VxWorks only)

The environment variable WIND_BASE has to be set on your system!

    • Win32

Supported compiler
OSE:
    • Microsoft VC++
Solaris:
    • Sun GNU gcc
VxWorks:
    • Tornado ccsimpc
Win32:
    • Microsoft VC++
Used kernel directory
OSE: sdt/sdtdir/RTOS/OSEDelta
Solaris: sdt/sdtdir/RTOS/Solaris
VxWorks: sdt/sdtdir/RTOS/VxWorks
Win32: sdt/sdtdir/RTOS/Win32
Timers
OS timer
More info
See "Tight Integration" .

For Use with the Cmicro SDL to C Compiler

  • Application (applclenv)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Has to be implemented by the user.
Template files
Taken from $(sdtdir)\cmicro\template
More info
The target executable can be executed on a command line.

  • Application including Target Tester and communication via sockets

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop cc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP cc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Has to be implemented by the user.
Template files
Taken from $(sdtdir)\cmicro\template
More info
The target executable has to be started manually after the Target Tester is started by the Targeting Expert.

  • Host Simulation (debcom)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are not implemented, i.e a timer set in the SDL system will never expire.
Environment
Will be handled in the SDL Target Tester UI.
Template files
Taken from $(sdtdir)\cmicro\template
More info
The target is executed as the SDL Target Tester's gateway. After a complete make The SDL Target Testerwill be started and the target can be tested.

  • Real-time Host Simulation (debclcom)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Will be handled in the SDL Target Tester UI.
Template files
Taken from $(sdtdir)\cmicro\template
More help
The target is executed as the SDL Target Tester's gateway. After a complete make The SDL Target Tester will be started and the target can be tested.

  • Real-time Host Simulation with environment (debclenvcom)

Supported compiler
On Sun:
    • Sun GNU gcc
    • Sun Workshop CC
On HP:
    • HP GNU gcc
    • HP aCC
In Windows:
    • Borland C++
    • Microsoft VC++
Used kernel directory
-
Timers
Timers are implemented in a way that one timer tick is equal to one second, i.e. a timer set to 10 in the SDL system will expire after 10 seconds.
Environment
Has to be implemented by the user.
Template files
Taken from $(sdtdir)\cmicro\template
More help
The target is executed as the SDL Target Tester's gateway. After a complete make The SDL Target Tester will be started and the target can be tested.

Syntax of the .its Files

There is a more or less complex syntax to be followed in .its files which will be described here. In principle each .its file is divided into four sections:

  • The Description about the Settings
  • The Settings which are once more split into
    • the Global Settings (A)
    • the Compiler specific Definitions
  • The Configuration Settings to Be Set
  • The Configuration Settings to Be Reset

You can find further syntax information in "Comments and empty Lines" and "Other Rules" .

Description about the Settings

The Targeting Expert will read in the description and display it in the user interface whenever a set of pre-defined integration settings is selected.

This section starts with [DESCRIPTION] and has got the only entry HelpLink. The description is a link name to this manual.

The Settings

The section of the .its files which contains the settings starts with [SETTINGS]. They must be ordered with the Global Settings (A) first, followed by the Compiler specific Definitions.

  • Global Settings (A)

The global settings start with the <keyword1> equal to Preferences and the delimiter '+', i.e. an allowed line in this section looks like:

Preferences+<keyword2>: parameter

Example 472 : Pre-defined integration settings (2A)

Preference+IntegrationSettings: <name>

The meaning of <keyword2> can be found in the table below.

Keyword 2 | Meaning of the parameter
IntegrationSettings | The name of this pre-defined integration setting is entered here.

  • Global Settings (B)

The global settings part B start with the <keyword1> equal to the name of the pre-defined integration settings (see Global Settings (A)) and the delimiter '+', i.e. an allowed line in this section looks like:

<name>+<keyword2>: parameter

Example 473 : Pre-defined integration settings (2B)

Simulation+CompilersUsed: Microsoft
Simulation+CodeGenerator: Cadvanced
Simulation+GenerateMakefile: YES

The meaning of <keyword2> can be found in the table below.

Keyword 2
Meaning of the parameter

 CompilersUsed
The name of a compiler which is used to build the target application must be entered here. This line can appear more than once per file to allow the description of more than one compiler.

 CodeGenerator
The name of the SDL to C compiler this pre-defined integration settings are designed for must be entered to the right of this keyword. Currently the SDL to C compilers
    • Cadvanced
    • Cmicro
are possible here.

 GenerateAllFiles
All the files will be re-generated even if the contents have not changed (YES) or not (NO)

 GenerateMakefile
The makefile generation should be switched on (YES) but can of course be switched off by specifying NO here.

 GenerateLowerCase
The SDL to C compiler should generate all SDL identifiers in lower case (YES) or as defined (NO)

 GenerateEnvFunctions
The SDL to C compiler should generate template environment functions (YES) or not (NO)

 GenerateEnvHeader
The SDL to C compiler should generate an environment header file (YES) or not (NO)

 GeneratePrefix
All variables will be generated with full prefix. Default is (YES) but can of course be switched off by specifying NO here.

 GenerateSignalNumber
The SDL to C compiler should generate a signal number file (YES) or not (NO)

 GenerateSDLCoder
The SDL to C compiler should generate an SDL coder functions file (NO, ASCII or <user>)

 GenerateASNCoder
The SDL to C compiler should generate an ASN.1 coder functions file (NO, BER, PER or <user>)

 Separation
The SDL to C compiler shall generate the C files separated according to the given value: NO, USER, FULL

 Analyze
The Analyzer/SDL to C compiler should be invoked during the make (YES) or not (NO)

 TestTool
The Test application to be used can be entered here, i.e. the entries Simulator, Validator or Tester but also a complete command line.

 FileNamePrefix
The SDL to C compiler will generate all files with the given filename prefix.

 GenerateIfcSynonyms
The SDL to C compiler should generate the
SYNONYMS section into the env. header file (YES) or not (NO).
(depends on GenerateEnvHeader)

 GenerateIfcLiterals
The SDL to C compiler should generate the
LITERALS section into the env. header file (YES) or not (NO).
(depends on GenerateEnvHeader)

 GenerateIfcTypedefs
The SDL to C compiler should generate the
TYPEDEFS section into the env. header file (YES) or not (NO).
(depends on GenerateEnvHeader)

 GenerateIfcOperators
The SDL to C compiler should generate the
OPERATORS section into the env. header file (YES) or not (NO).
(depends on GenerateEnvHeader)

 GenerateIfcSignals
The SDL to C compiler should generate the
SIGNALS section into the env. header file (YES) or not (NO).
(depends on GenerateEnvHeader)

 GenerateIfcChannels
The SDL to C compiler should generate the
CHANNELS section into the env. header file (YES) or not (NO).
(depends on GenerateEnvHeader)

 IfcPrefixSynonyms
The SDL to C compiler will generate SYNONYMS using the specified rule (Default is %n)

 IfcPrefixLiterals
The SDL to C compiler will generate SYNONYMS using the specified rule (Default is %n)

 IfcPrefixTypes
The SDL to C compiler will generate SYNONYMS using the specified rule (Default is %n)

 IfcPrefixSignals
The SDL to C compiler will generate SYNONYMS using the specified rule (Default is %n)

 IfcPrefixChannels
The SDL to C compiler will generate SYNONYMS using the specified rule (Default is %n)

 SuppressText
The Analyzer error or warning message to suppress can be given here.

  • Compiler specific Definitions

This segment has got all the definitions for an unlimited amount of compilers. All the keywords start with

<name of the setting>+<compiler-name>*

followed by one or two further keywords. If it is followed by two keywords both are separated by '~'.

Example 474 : Pre-defined integration settings (3)

Simulation+Microsoft*Compiler~Tool: cl
Simulation+Microsoft*Compiler~Options: -nologo %I -ML -c -D_Windows -DSCTDEBCOM /Fo%o %s
Simulation+Microsoft*Compiler~Include: -I$(sctuseinclude)
Simulation+Microsoft*Compiler~Flag: IC86
Simulation+Microsoft*Linker~Tool: link
Simulation+Microsoft*Linker~Options: -nologo -subsystem:console %O /OUT:%e
Simulation+Microsoft*ObjectExtension: _smc.obj
Simulation+Microsoft*ExecutableExtension: _smc.exe
Simulation+Microsoft*FileToCompile: $(sdtdir)\INCLUDE\sctsdl.c
Simulation+Microsoft*FileToCompile: $(sdtdir)\INCLUDE\sctpred.c
Simulation+Microsoft*FileToCompile: $(sdtdir)\INCLUDE\sctos.c
Simulation+Microsoft*FileToCompile: $(sdtdir)\INCLUDE\sctmon.c
Simulation+Microsoft*FileToCompile: $(sdtdir)\INCLUDE\sctutil.c
Simulation+Microsoft*FileToCompile: $(sdtdir)\SCTADEBCOM\sctpost.c
Simulation+Microsoft*LibrariesToLink: $(sdtdir)\INCLUDE\msvc50\libpost.lib
Simulation+Microsoft*LibrariesToLink: user32.lib
Simulation+Microsoft*Make~Tool: Microsoft nmake (using temporary response file)
Simulation+Microsoft*MakefileName: my_makefile.m
Simulation+Microsoft*MakefileGenerator: -
Simulation+Microsoft*ObjectDirectory: objects

All the keywords and the allowed combinations can be found in the table below.

Keyword 3
Keyword 4
Meaning of the parameter

 Compiler

 Tool
Name of the compiler application

 Compiler

 Tool2
Name of the C parser application (optional)

 Compiler

 Tool3
Name of the assembler application (optional)

 Compiler

 Options
Compiler command line options (Please see "Compiler" )

 Compiler

 Options2
C parser command line options (optional)

 Compiler

 Options3
Assembler command line options (optional)

 Compiler

 LibFlag
The compiler's option to set defines plus the library flag (e.g. SCTDEBCOM)

 Compiler

 Include
The compiler's option for include paths and the include paths

 Compiler

 CodInclude
The compiler's option for include paths and the include paths to the coder files

 Compiler

 Flag
Compiler flag (Please see "Compiler Flag" )

 Linker

 Tool
Name of the linker application

 Linker

 Options
Linker command line options (Please see "Linker" )

 ObjectExtension
Extension of the object files

 ExecutableExtension
Extension of the target executable
 FilesToCompile
Kernel, library and template files to be compiled. This entry can be used more than once.

 TesterFilesToCompile
Tester files to be compiled. This entry can be used more than once. (Cmicro only)

 FilesToCopy
Template files which should be copied into the target directory. Environment variable §(sdtdir) can be used

 ObjectsToLink
Additional object files to be linked. This entry can be used more than once.

 LibrariesToLink
Additional libraries to be linked (e.g. the compiler's libraries). This entry can be used more than once.

 Make

 Tool
The name of the make application. This can be:
  • Borland make (using temporary response file)
  • Borland make
  • Microsoft nmake (using temporary response file)
  • Microsoft nmake
  • UNIX make
 MakefileName
The name of the makefile to be generated (or respectively to be used) is entered here.

 MakefileGenerator
The Targeting Experts supports the use of external makefile generators which is to be entered here. An intern means that the build-in makefile generator is to be used

 ObjectDirectory
The relative path (seen from the target directory) for the object directory can be entered here. If not specified Targeting expert will generate the makefile in a way that the object files will be written into the target directory when make is executed.

 LibraryDirectory
If this entry is specified the SDL to C compiler's library will be taken from the specified path. If not specified it will be taken from $sdtdir (%SDTDIR%).

 Download

 Tool
The full command line to invoke the download application.

 PreMake
Action to perform before the target application will be made in the makefile.

 PreCompile
If the generated code should be modified before it is compiled, an appropriate application (complete command line) should be entered here.

 PostLink
If the linked target application needs to be modified (e.g. conversion into HEX format), the appropriate application (complete command line) should be entered here.

 AddCompiler

 Tool
For the additional files (see FilesToCompile) the name of the compiler application must be entered here.

 AddCompiler

 Options
The command line options for the compiler in AddCompiler must be specified here.

 AddCompiler

 Include
The compiler's option for include paths and the include paths for the compiler entered in AddCompiler

 AddCompiler

 Depend
The dependencies for the additional files (used inside of the generated makefile).

 AddObjectExtension
The object extension of the AddCompiler must be entered here.

 AddFilesToCompile
Kernel files to be compiled (e.g. communications link). This entry can be used more than once.

Default Configuration Settings

For several pre-defined integrations it is necessary to have some configuration flags defined as default. In this section a simple list of all configuration flags which should be set is given.

This section starts with [CONFIGURATION_DEFAULT].

Please see "Configuration Files" for more information about configuration flags.

Configuration Settings to Be Set

For several pre-defined integrations it is necessary to have some configuration flags set without giving you the chance to un-select them. In this section a simple list of all configuration flags which have to be set is given.

This section starts with [CONFIGURATION_SET].

Please see "Configuration Files" for more information about configuration flags.

Configuration Settings to Be Reset

In opposite to the configuration flags which have to be set, it is of course necessary sometimes to prevent the selection of other flags. This can be done in this section by simply listing all the flags that have to be reset.

This section starts with [CONFIGURATION_RESET].

Please see "Configuration Files" for more information about configuration flags.

SDL to C Compiler Settings to Be Disabled

For some pre-defined integrations it does not make sense to configure all the SDL to C compiler options available. It is possible here to list all the options to be disabled in the user interface.

This section starts with [SDL_TO_C_COMPILER_DISABLED].

Comments and empty Lines

  • Empty lines are allowed everywhere in the an .its file.
  • Comments are allowed everywhere in the .its file but have to start with an '#' in the first column.

Other Rules

  • Only one set is allowed per .its file
  • The amount of compilers supported for each set is unlimited.
  • The characters '[', ']', '+', '*', '~' and ':' are forbidden in compiler names or the name of the pre-defined integration settings itself.

User-defined Integration Settings

All the settings done by the user will be stored in separate files into the target directory, i.e.:

  • The complete set of settings will be stored (not the difference to the defaults)
  • There is one file for each integration configuration done for an application, node or component
  • If several nodes or components have to use the same settings it is possible to manually select one file for them.
    Please see "Handling of Settings" .

Target Sub-Directory Structure

The Targeting Expert automatically sets up a sub-directory structure for all the applications, nodes and components. Furthermore there is a sub directory for each kind of integration done.

Example 475 : Sub-directory structure

Figure 541 : Example of a partitioning diagram

Estimated there is a partitioning diagram which looks like Figure 541, the Targeting Expert generates a sub-directory structure like:

<target_dir>
+ application._0
+ node._1
+ component._2

Note:

The suffixes ._* give unique identifiers which make it possible to rename the application, nodes or components and to keep the done settings. In this case the Targeting Expert automatically modifies the names of the subdirectories.

Later, after you have built a Simulator and a Validator for the component, for example, then the sub-directory structure was extended to:
<target_dir>
+ application._0
+ node._1
+ component._2
+ Simulator
+ Validator

Flat Directory Structure

When using an .sdt or .pr file as input the directory structure will be flatten automatically. I.e it will look like

<target_dir>
+ application._0
+ Simulator
+ Validator

This is possible because there can only be one node with one component in both cases.

Generated Makefile

Before the selected make tool is invoked the Targeting Expert generates a makefile with all of the necessary settings done. (Please see "Configure Compiler, Linker and Make" for information on how to set up the makefile generation.)

Caution!

The standard header files of the used SDL to C compiler library are not used as dependencies in the compilation rules, i.e. after modifying one of these files you have to select the Clean entry in the Make Menu.

Comparisons

There are a few differences that need to be mentioned when comparing the way the Targeting Expert handles makefiles with the way the Organizer's Make dialog does.

When using the Targeting Expert ...

  • ... there is no makefile (systemname.m) generated by the SDL to C compiler. Instead it generates a sub-makefile (component_gen.m) which is automatically parsed and inserted into the Targeting Expert makefile, i.e. the Targeting Expert still gets all the information from the SDL to C compiler but in a different way.
  • ... there is not support of template makefiles by the Targeting Expert. The makefiles generated by the Targeting Expert can be modified directly in the so called "user sections". Please see "User Modifications" .
  • ... there are no makeoptions/make.opt files (taken from the kernel directories) used at all. Instead of this, the Targeting Expert gets all the make information from the Pre-defined Integration Settings and places them into its makefile.
  • ... the comp.opt files placed in the kernel directories are not used at all! Again all the information is taken from the Pre-defined Integration Settings.
  • ... the sccd cannot be used for pre-processing purposes as default because the Targeting Expert does not use sccd.cfg files from the kernel directories. It is recommended to use the Targeting Expert Preprocessor instead.

Note:

The only exceptions in which the Targeting Expert uses some information from the associated kernel directory are the integrations Validation and TTCN Link. In both cases a library is taken from the kernel directory.

User Modifications

After all it is possible that there are a few adaptations to be done, e.g. if there is an assembler file which needs to be assembled and linked.

Example 476 shows the section of a generated makefile where it is possible to add further object files.

Example 476 : Generated makefile (1)

######## UserObjectsStart (Do not edit this line!) ##########
userOBJECTFILES1 =

userOBJECTFILES2 =

######## UserObjectsEnd (Do not edit this line!) ##########

The list userOBJECTFILES1 will be inserted at the front of all the object files to link. Accordingly userOBJECTFILES2 will be inserted at the end.

The rules and the dependencies for the files in Example 476 must be given in the section shown in Example 477.

Example 477 : Generated makefile (2)

######## UserRulesStart (Do not edit this line!) ##########

######## UserRulesEnd (Do not edit this line!) ##########

Caution!

Any modification that is done outside of the sections described in Example 476 and Example 477 will be overwritten when the makefile is generated anew.

Parameter File sdttaex.par

General

One of the delivered configuration files used by the Targeting Expert is called sdttaex.par. Several different sections give information that is statically used during runtime. Under normal circumstances this file does not need to be modified. However, there might be the need to extend the Targeting Expert functions.

Please see the following sub-sections for more information what can be configured:

  • Compiler Error Descriptions
  • Preprocessor Commands
  • Make Applications
  • C++ Options
  • Debug Options
  • Compiler Dependent Defaults
  • Restricted Compilers
  • Editor Commands
  • Additional Files
  • Host Configuration Options (used for Cmicro only)

Search Order for sdttaex.par

The following shown search order applies when the Targeting Expert is started. The distributed version of sdttaex.par is always placed in <installationdir>/bin/<platform>bin

Figure 542 : Search order for sdttaex.par on UNIX

Figure 543 : Search order for sdttaex.par in Windows

Compiler Error Descriptions

The section [COMPILER-ERROR-DESCRIPTION] of sdttaex.par is filled with regular expressions describing the construction of compiler error messages.

Example 478 : [COMPILER-ERROR-DESCRIPTION]

[COMPILER-ERROR-DESCRIPTION]
{cl} {1} {.*([1234567890]} {0} {2} {([1234567890]*)} {1} {1}
{bcc32} {1} {Error .* [1234567890]} {6} {2} { [1234567890]*:} {1} {1}
{cc166} {2} {.*[A-Za-z]:} {0} {1} {[1234567890]*: } {0} {2}
{gcc} {1} {.*:[1234567890]} {0} {2} {:[1234567890]*:} {1} {1}
{icc8051} {1} {.*,[1234567890]} {1} {3} {,[1234567890]* } {1} {1}
{c51} {1} {OF .*[CH]: } {3} {2} {LINE [1234567890]* OF} {5} {3}
{cc} {1} {.*, l} {1} {4} {line [1234567890]*:} {5} {1}
{CC} {1} {.*, l} {1} {2} {line [1234567890]*:} {5} {1}
{aCC} {1} {: .*,} {3} {2} {line [1234567890]* #} {5} {2}
{ccsimpc} {1} {.*:[1234567890]} {0} {2} {:[1234567890]*:} {1} {1}
{icpp} {1} {!E .*(} {3} {1} {(.*)} {1} {1}

Each line gives the description for one compiler. The eight entries have the meaning shown below (explained on the gcc entry):

  1. The name of the compiler executable
  2. The amount of lines the compiler error message takes
  3. The regular expression to determine the erroneous file
  4. The amount of characters thrown away at the beginning of the found file name
  5. The amount of characters thrown away at the end of the found file name. (In this example the colon and the numeric character do not belong to the file name but both are needed to find it.)
  6. The regular expression to determine the line number
  7. The amount of characters thrown away at the beginning of the found line. (In this example the colon at the front of the regular expression does not belong to the line number but is needed to find it).
  8. The amount of characters thrown away at the end of the found line. (In this example the colon at the end of the regular expression does not belong to the line number but is needed to find it).

Preprocessor Commands

This section takes the preprocessor commands for all the default compilers that can be set in the preferences. It has got the following contents:

Example 479 : [PREPROCESSOR-COMMANDS]

[PREPROCESSOR-COMMANDS]
{Sun GNU gcc} {gcc -P -E -C}
{Sun Workshop cc} {cc -C -P}
{Sun Workshop CC} {CC -E}
{HP GNU gcc} {gcc -P -E -C}
{HP cc} {cc -C -P}
{HP aCC} {aCC -E}
{Microsoft} {cl -P -EP -C -nologo}
{Borland} {cpp32 -P-}

Make Applications

The section [MAKE_APPLICATIONS] of sdttaex.par is used to specify the command line of the make application, i.e. how it will be invoked.

Example 480 : [MAKE_APPLICATIONS]

[MAKE_APPLICATIONS]
{Borland make} {make -f} {} {}
{Borland make (ignore exit codes)} {make -i -f} {} {}
{Borland make (using temporary response file)} {make -f} {@&&!\n\t}{\n!}
{Microsoft nmake} {nmake /f} {} {}
{Microsoft nmake (ignore exit codes)} {nmake /i /f} {} {}
{Microsoft nmake (using temporary response file)} {nmake /f} {@<<\n\t} {\n<<}
{Tasking mk166} {mk166 -f} {} {}
{Tornado make} {make -f} {} {}
{UNIX make} {make -f} {} {}

Each line is the description for one make application. The four entries (given between '{' and '}') have the following meaning.

  1. The text to identify it in the make configuration. See "Make tool"
  2. The name of the make application and the option used to specify the makefile.
  3. This is the start sequence for the generation of temporary response files. Empty for most make applications.
  4. This is the stop sequence for the generation of temporary response files. Empty for most make applications.

C++ Options

The C++ options specify what has to be added to the compiler's Options and the linker's Options to compile and link the SDL to C compiler's library as C++ code.

Example 481 : [C++-OPTIONS]

[C++OPTIONS]
{Sun GNU gcc} {-xc++} {-lstdc++}
{HP GNU gcc} {-xc++} {-lstdc++}
{Microsoft} {-TP} {}
{Borland} {-P} {}

Each line consist of the three entries

  1. compiler name
  2. compiler command line option
  3. linker command line option

Debug Options

The debug options specify what has to be added to the compiler's Options and the linker's Options to compile and link the target application including debug information.

Example 482 : [DEBUG_OPTIONS]

[DEBUG-OPTIONS]
{Sun GNU gcc} {-g} {-g}
{Sun Workshop cc} {-g} {-g}
{Sun Workshop CC} {-g} {-g}
{HP GNU gcc} {-g} {-g}
{HP cc} {-g} {-g}
{HP aCC} {-g} {-g}
{Microsoft} {-D "_DEBUG"} {/debug}
{Borland} {-v} {-v}
{icc12} {-g} {-g}

Each line consist of the three entries

  1. compiler name
  2. compiler command line option
  3. linker command line option

Compiler Dependent Defaults

The compiler dependent defaults ease the implementation of new pre-defined integrations because the values given here do not need to appear again in the .its file(s).

Example 483 : [COMPILER-DEPENDENT-DEFAULTS]

[COMPILER-DEPENDENT-DEFAULTS]
{Borland} {bcc32} {bcc32} {tlib} {.obj} {.exe} {.lib} {%I -c -w- -DUSING_DLL -DIC86 -o%o %s} {-e%e %L %O} {%l /C /E /P256 %O} {-I$(sctCODERDIR)} {bcc_obj} {Borland make (using temporary response file)}

The different entries mean the following (listed from left to right):

  1. Compiler name
  2. Compiler tool name
  3. Linker tool name
  4. Library manager name
  5. Object file extension
  6. Executable file extension
  7. Library file extension
  8. Compiler options
  9. Linker options
  10. Library Manager Options
  11. Coder include path
  12. Relative path to intermediate directory
  13. make application to use per default

Restricted Compilers

There are a few target compilers which do not support file names which are longer that 8.3 (8 character in front of '.' and a 3 character extension). To ensure that files are generated only which fit to the 8.3 requirement. This section looks as follows:

Example 484 : [8.3-COMPILERS]

[8.3-COMPILERS]
{c51}
{icpp}
{icc12}

Editor Commands

The Targeting Expert allows to use other text editor different to the build-in one. The information how to start these editors is given in the section [EDITOR-COMMANDS] shown below.

Example 485 : [EDITOR-COMMANDS]

[EDITOR-COMMANDS]
{Windows} {TextPad} {textpad -ca -q "%f"(%l,0)}
{Windows} {UltraEdit} {UEdit32 %f/%l/0}
{Windows} {Codewright} {codewright %f -G%l}
{Windows} {MS DeveloperStudio} {msdev %f}
{UNIX} {Emacs} {emacs %f}
{UNIX} {dtpad} {/usr/dt/bin/dtpad %f}
{UNIX} {nedit} {nedit -line %l %f}

There are 2 placeholders used in the command. %f will be replaced by the name of the file to open and %l gives the line number which should be shown.

Additional Files

The sections shown in Example 486 will used to find out which files belong to external parts of the distributed SDL to C compiler libraries.

Example 486 : Additional Files Sections

[CMICRO-KERNEL-FILES]
$(sctkerneldir)/mk_main.c
$(sctkerneldir)/mk_sche.c
$(sctkerneldir)/mk_queu.c
$(sctkerneldir)/mk_outp.c
$(sctkerneldir)/mk_tim1.c
$(sctkerneldir)/sctpred.c

[CMICRO-TI-KERNEL-FILES]
$(sctkerneldir)/ti_sche.c
$(sctkerneldir)/ti_queu.c
$(sctkerneldir)/ti_outp.c
$(sctkerneldir)/ti_tim1.c
$(sctkerneldir)/ti_init.c
$(sctkerneldir)/sctpred.c

[TESTER-FILES]
$(scttesterdir)/mt_tsdl.c
$(scttesterdir)/mt_tsys.c
$(scttesterdir)/mt_cod.c
$(scttesterdir)/mt_cmd.c
$(scttesterdir)/mt_opt.c
$(scttesterdir)/mt_deb.c
$(scttesterdir)/mt_rec.c
$(scttesterdir)/mt_play.c
$(sctkerneldir)/ml_buf.c

[TI-TESTER-FILES]
$(scttesterdir)/mt_tsdl.c
$(scttesterdir)/mt_tsys.c
$(scttesterdir)/mt_cod.c
$(scttesterdir)/mt_cmd.c
$(scttesterdir)/mt_opt.c
$(scttesterdir)/mt_deb.c
$(sctkerneldir)/ml_buf.c

[CODER-FILES]
$(sctCODERDIR)/cucf_er.c
$(sctCODERDIR)/cucf_er_sdt.c
$(sctCODERDIR)/bms/bms.c
$(sctCODERDIR)/bms/bms_small.c
$(sctCODERDIR)/ems/ems.c
$(sctCODERDIR)/ems/ems_eo_sdt.c
$(sctCODERDIR)/er/ascii/ascii.c
$(sctCODERDIR)/er/ber/ber_base.c
$(sctCODERDIR)/er/ber/ber_content.c
$(sctCODERDIR)/er/ber/ber_decode.c
$(sctCODERDIR)/er/ber/ber_encode.c
$(sctCODERDIR)/er/per/per_base.c
$(sctCODERDIR)/er/per/per_content.c
$(sctCODERDIR)/er/per/per_decode.c
$(sctCODERDIR)/er/per/per_encode.c
$(sctCODERDIR)/er/mms/mms.c
$(sctCODERDIR)/vms/vms_base.c
$(sctCODERDIR)/vms/vms_check.c
$(sctCODERDIR)/vms/vms_export.c
$(sctCODERDIR)/vms/vms_print.c

[TCP-IP-FILES]
$(sctTCPIPDIR)/tcpipcomm.c

Note:

The [TESTER-FILES] and [TI-TESTER-FILES] only apply for the Cmicro SDL to C compiler.
The [TCP-IP-FILES] only applies for the Cadvanced SDL to C compiler.

Host Configuration Options

The host configuration options are the default host configurations for different compilers when using the Target Tester, i.e. these options are only used for Cmicro applications. An example can be found below.

Example 487 : [HOST-CONFIGURATION-OPTIONS] (Borland compiler)

[HOST-CONFIGURATION-OPTIONS]
bcc32 "UNIT-NAME sec"
bcc32 "UNIT-SCALE 1.0"
bcc32 "LENGTH_CHAR 1"
bcc32 "LENGTH_SHORT 2"
bcc32 "LENGTH_INT 4"
bcc32 "LENGTH_LONG 4"
bcc32 "LENGTH_FLOAT 4"
bcc32 "LENGTH_DOUBLE 8"
bcc32 "LENGTH_POINTER 4"
bcc32 "ALIGN_CHAR 8"
bcc32 "ALIGN_SHORT 8"
bcc32 "ALIGN_INT 8"
bcc32 "ALIGN_LONG 8"
bcc32 "ALIGN_FLOAT 8"
bcc32 "ALIGN_DOUBLE 8"
bcc32 "ALIGN_POINTER 8"
bcc32 "ENDIAN_CHAR 1"
bcc32 "ENDIAN_SHORT 21"
bcc32 "ENDIAN_INT 41"
bcc32 "ENDIAN_LONG 41"
bcc32 "ENDIAN_FLOAT 41"
bcc32 "ENDIAN_DOUBLE 81"
bcc32 "ENDIAN_POINTER 41"


External Makefile Generator

General

As it is probably necessary for you to modify the layout of the generated makefile, the source code of the external makefile generator "makegen" is delivered with every Telelogic Tau distribution. It can be found in <installationdir>/sdt/sdtdir/util/<platform>.

Source and Make Files

The source files delivered are:

  • makegen.[ch]
  • ini_api.h
  • pdm_api.h

Furthermore there are makefiles and libraries:

  • cc - compiler on UNIX
    • makegencc.m
    • makegenlib.a
  • gcc 2.95.2 - compiler on UNIX
    • makegengcc.m
    • makegenlib.a
  • Microsoft VC++ 6.0 compiler in Windows
    • makegencl.m
    • makegencl.lib
  • Borland C++ Builder 5.51 compiler in Windows
    • makegenbcb.m
    • makegenbcb.lib


Utilities

General

Delivered in combination with the Targeting Expert there is an application called taexutil. This application can be used directly from the Targeting Expert Tools menu or on the command line, e.g. in makefiles.

The following utility functions are supported:

  • DOS to UNIX
  • UNIX to DOS
  • Indent
  • Preprocessor

Note:

Each utility will create a backup file called <inputfile>.bak

DOS to UNIX

This utility can be used to modify ASCII files. It replaces all the found '\r\n' sequences against '\n'.

  • Command line:
    taexutil D2U <inputfile> <outputfile>
    <inputfile>     and <outputfile> can be equal but both must be given.

UNIX to DOS

This utility can be used to modify ASCII files. It replaces all the found '\n' characters against '\r\n' sequences.

  • Command line:
    taexutil U2D <inputfile> <outputfile>
    <inputfile>     and <outputfile> can be equal but both must be given.

Indent

The indentation of the given ASCII file will be corrected. This means

  • all the preprocessor directives (staring with '#') will be moved into the first column. This is necessary to conform with K&R compilers.
  • all the other lines will be indented according to the given blocks in C, i.e. it is controlled by the use of '{' and '}' characters.
  • all TAB characters ('\t') will be removed.
  • all the SPACE (' ') characters at the end of lines will be removed.

Caution!

The indent offered by here does not offer the same functionality as indent known from UNIX!

  • Command line:
    taexutil INDENT <inputfile> <outputfile>
    <inputfile>     and <outputfile> can be equal but both must be given.

Preprocessor

Note:

The main intention of the preprocessor given here is not to get an easy to read source file. Instead it is to get a preprocessed file that can be compiled by a target compiler (e.g. Keil, Tasking, ... ) because long macros are not supported by some target compilers.

The preprocessor utility should only be used to preprocess generated C files. The following tasks will be processed:

  1. Copy the SDL to C compilers main header file (ml_typ.h/scttypes.h) beside the output file.
  2. Put all the lines of the main header file containing #include <...> statements into comments
  3. Preprocess the selected generated C file by using the default compiler (see Telelogic Tau Preferences).
  4. Remove all the empty lines in the preprocessed file.
  5. Run Indent on the preprocessed file.
  6. Remove all the comments surrounding #include < ...> in the preprocessed file.
  7. Remove the private copy of the main header file.

Note:

All the files given with #include "..." will be included during the preprocessing.

  • Command line:
    taexutil PREPRO <inputfile> <outputfile> "<cmd>" <compiler_flag>
    • <inputfile> and <outputfile> can be equal but both must be given.
    • <cmd> is the command line needed to invoke the preprocessor of the default compiler
    • <compiler_flag> is the define to select the target compiler. (Please see "Compiler Flag" )


FAQs

  • How can I set the target directory in the Targeting Expert?
    It is not possible to set the target directory in the Targeting Expert. The one given in the Organizer will be used instead. To make it possible to have different integrations in one target directory the Targeting Expert creates a Target Sub-Directory Structure.
  • Where can I add my own macro definitions?
    There is a manual configuration file written for each integration. It is called sct_mcf.h for Cadvanced and ml_mcf.h for Cmicro.
    This header file is included in the SDL to C compiler's library during compilation and contains a section where you can insert your own macro definitions. The section begins with
/* BEGIN User Code */
and ends with the line
/* END User Code */
All the text given between both lines will be saved if the manual configuration file is re-generated.

Caution!

The manual configuration file sct_mcf.h for Cadvanced is included only if the flag USER_CONFIG is set. This can be done in most cases by defining -DUSER_CONFIG in the compiler options.

  • How can I modify the value of $sdtdir in the generated makefile?
    Per default the value of $sdtdir is set to
    <installationdir>/sdt/sdtdir/<platformsdtdir>. In some cases it is probably necessary to get the library files from another directory. In this case you can modify the Library Directory in the Make dialog. The sub-directory structure must be the same as given under <installationdir>/sdt/sdtdir/<platformsdtdir>.
  • How can I modify the configuration flags that are disabled in the Targeting Expert user interface?
    The Targeting Expert can be customized in a way so that the configuration flags listed under Configuration Settings to Be Set or Configuration Settings to Be Reset are not disabled. To achieve that open the Customize dialog via the menu choice Tools > Customize and select the Advanced Mode. (Please see "Customization" for more details)
  • How can I create my own pre-defined integration?
    You can create your own pre-defined integrations by
    • selecting one of the distributed pre-defined integrations (the one that fits most to your needs
    • configure it as you like (maybe it is necessary to switch into the Advanced Mode to have access to all the dialogs)
    • export the settings like it is described in "Export" #
      After you have done so the pre-defined integration will be available.
  • I have exported an pre-defined integration but my colleagues are not able to access it in my home directory/in my PC installation. What to do?
    When exporting settings to pre-defined integration settings it is possible to
    • export as project settings - or
    • export as user settings
      You have probably exported as user settings, i.e. the .its file is not accessible for other users. You can move the <integration>.its file in the same directory where the <systemname>.sdt file of your project is saved. So it will be visible for all users working on this system.


60 SDL C Compiler Driver (SCCD)

The SDL C Compiler Driver (SCCD) is a utility intended to simplify C level debugging of code generated by the SDL suite and handwritten code. It can be invoked from the makefiles used by the SDL suite or stand-alone from the OS command line.


Introduction

The SDL C Compiler Driver (SCCD) is intended to simplify C level debugging by generating an intermediate C file placed in a user defined directory. This C file has all its macros expanded and is optionally "beautified" (pretty-printed). For ease of use SCCD is used as a C compiler driver called from the SDL suite generated or handwritten makefiles. SCCD may also be used as a command line option when compiling C code.

The simplest way to introduce this facility for use in the standard SDL suite environment is to modify the makeoptions or make.opt file associated with the predefined run-time library to be used. To enable this feature in a modified the SDL suite run-time library, the directory and file structure must be similar to the pre-defined one.

The makeoptions or make.opt file is found in the $sdtdir/SCT[Kernel name] directory. The only modification required is to change the line

sctCC = cc /* or some other compiler executable name */

to

sctCC = sccd cc /* or some other compiler executable name */

SCCD must of course be visible in your path.

To customize the behavior of SCCD, modify the configuration file sccd_<your_compiler_type>.cfg variables described in the following sections.


Syntax for Invoking

The following syntax can be used to invoke SCCD:

To execute SCCD:

sccd <C compiler command line>

The C compiler command line should be the normal command line used to compile a C file: it should include the name of your C compiler, possible compiler options, and finally the name of the C file.

To print the values of the variables in the configuration file sccd.cfg:

sccd

To print the variables with extra help information:

sccd -h


Return Codes

0: Success.

1: After printing "help".

2: No .c file.

3: Could not open InFile.c.

4: Could not open InFile.i for write.

5: sccdMOVE or sccdOUTFILEREDIR needs to be defined.

6: Could not open InFile.i for read.

7: Could not open/create TmpDir/InFile.c.


Actions Performed by SCCD

  1. Execute an optional first-user defined command (sccdUSER_CMD1).
  2. Create a sub-directory for temporary files and the pre-processed .c files.
  3. Execute an optional second user-defined command (sccdUSER_CMD2).
  4. Run a C pre-processor pass to expand all macros.
  5. Execute an optional third user-defined command (sccdUSER_CMD3).
  6. Pretty print the file.
  7. Optional clean-up of the sub-directory.
  8. Optionally copy .hs files to the sub-directory.
  9. Execute an optional fourth user-defined command (sccdUSER_CMD4). You should use this command if you wish to invoke the "indent" utility from SCCD (see "C Beautifier" for more information).
  10. Optionally compile, i.e. run the original command line.
  11. Optional clean-up of the sub-directory, but leave the pre-processed .c file(s) for debugging purposes.


Configuration File

The behavior of SCCD is defined using a number of variables, each starting with "sccd". The variables are defined in a configuration file, sccd_<your_compiler_type>.cfg. Select the configuration file that corresponds to your C compiler and copy this file as sccd.cfg. If run from the SDL suite, SCCD uses $sctdir/sccd.cfg as the configuration file; otherwise SCCD searches for sccd.cfg in the current directory, $SCCD, and (on UNIX) $HOME.

Note:

If sccd.cfg is not found, hard-coded defaults suitable for the Gnu C compiler (gcc) are used.

Below are the variables that control the behavior of SCCD. Note that all characters in variable values are significant, including white spaces.

sccdNAME = "Default"
Compiler name as defined in scttypes.h.
sccdINFILESUFFIX = ".c"
The expected file name suffix of the In-file(s), Default ".c".
sccdCPP = ""
The name of the C pre-processor. If this is left empty, CPP is used. Default "".
sccdCPPFLAGS = ""
Enable CPP and do not remove comments. This is C compiler dependent. Default for gcc is "-P -E -C", and for cc "-C -P".
sccdMACROPREFIX = "-D"
CPP command-line define MACRO prefix. Default "-D".
sccdINCLUDE1 = "-I"
CPP command-line include-path prefix. Default "-I".
sccdINCLUDE2 = ""
Alternative CPP command-line include-path prefix. Default "".
sccdOUTFILEREDIR = "-o "
Character sequence to control CPP output file name. If empty, use sccdFMOVE instead.
sccdFMOVE = ""
OS forced file move or copy command. Used instead of sccdOUTFILEREDIR. Default: "".
sccdDELETE = "rm -f"
OS forced delete file command. Default: "rm -f".
sccdCOPY = "cp"
OS normal copy command. Default: "cp".
sccdCOMPILE = "ON"
Controls whether the final compilation pass should be run or not. Values are: "OFF" and default is "ON".
sccdDEBUG = "OFF"
Enable execution. Values are: "ON" and default is "OFF".
sccdPURGE = "ON"
Purge temporary files. Values are: "OFF" and default is "ON".
sccdUSE_HS = "OFF"
When set "ON", the .hs files are not included until the compilation pass. Values are: "ON" and default is "OFF".
sccdSILENT = "OFF"
Enable trace printout. Values are: "ON" and default is "OFF".
sccdTMPDIR = "sccdtmp"
Temporary directory for the pre-processing. Default is sccdtmp. Setting sccdTMPDIR to "" or "." in the configuration file suppresses temporary directory creation.
sccdUSER_CMD1 = ""
sccdUSER_CMD2 = ""
sccdUSER_CMD3 = ""
sccdUSER_CMD4 = ""
User-defined commands (see "Actions Performed by SCCD" ). The following pseudo variables can be used in all but the first one (sccdUSER_CMD1):
%f expands to In-file name without extension.
%p expands to In-file path.
%d expands to the value of sccdTMPDIR.
Example: echo \"Pre-processed C-file = %p/%d/%f.c\"

To include `#' in sccdUSER_CMDx and sccdTMPDIR, enter \#
To include `"' in sccdUSER_CMDx and sccdTMPDIR, enter \"
To include `\' in sccdUSER_CMDx and sccdTMPDIR, enter \\


C Beautifier

If you need a C beautifier to further format the C code from the SDL suite, do as follows.

Try the indent utility (courtesy of Joseph Arcaneaux). The .zip file contains source code and an executable compiled as a win32 application; the .tar file contains the original indent-1.9.1 source code for UNIX. The UNIX version must be compiled for the appropriate platform but this work is normally simplified if you read the documentation in the .tar file and use the enclosed make file.

The indent executable must be placed in your path.

In order to easily invoke indent from SCCD, insert the following statement in sccdUSER_CMD4 in the appropriate sccd.cfg file(s), assuming no other changes have been made to the sccd.cfg file(s):

For UNIX compiler environments:

sccdUSER_CMD4 = "indent -kr -l70 -i2 %p/%d/%f.c"

For "DOS"-like compiler environments:

sccdUSER_CMD4 = "indent -kr -l70 -i2 %p\\%d\\%f.c"

This setup gives a .c source file formatted according to rules very like the ones used in the Kernighan & Richie "C" book. It will also try to force lines to be shorter than 70 characters and will use 2 positions indentation in if/while/... statements.

A slightly more elaborate example:

sccdUSER_CMD4 = "indent -kr -l70 -br -nce -nlp -ci3 -i2 %p/%d/%f.c"


61 The Master Library

This chapter covers the following topics:

  • The structure of the source code of the SDL suite Master Library
  • The runtime model used for the programs generated by the SDL to C compiler. The chapter also describes the data structures for representing the various SDL objects.
  • The memory requirements for applications
  • How to make a customized Master Library
  • The compilation switches which affect the properties of the Master Library

Note that the Master Library is only used together with the Cadvanced/Cbasic SDL to C Compiler. It cannot be used together with the Cmicro SDL to C Compiler.


Introduction

This chapter describes the source code of the runtime library for applications generated by the Cadvanced/Cbasic SDL to C Compiler. Applications generated by the Cmicro SDL to C Compiler are not covered.

The chapter covers basically two topics:

  1. The sections "File Structure" , "The Symbol Table" , and "The SDL Model" describe the run-time model for programs generated by the SDL Cadvanced/Cbasic SDL to C Compiler.
    Mainly it is the data structure used to represent various SDL objects that is discussed, both from the static point of view (the type definitions), and from the dynamic point of view (what information it represents and how it is initialized, changed, and used).
    The full runtime model that is used during simulations (with the monitor) is described. From this model, an optimization is made to obtain an application (not using the monitor). The optimization is discussed under "Compilation Switches" .
  2. In the sections "Compilation Switches" , "Creating a New Library" , and "Adaptation to Compilers" , different aspects on how to make new versions of the runtime library are discussed.
    The compilation switches treated in the section "Compilation Switches" are used to determine the properties of the runtime library and the generated C code, while section "Creating a New Library" shows how to make new versions of the runtime library using for example new combinations of compilation switches.
    In the section "Adaptation to Compilers" , porting issues are discussed.


File Structure

The runtime library is structured into a number of files. These are:

    • scttypes.h
    • sctlocal.h
    • sctpred.h
    • sctsdl.c
    • sctpred.c
    • sctutil.c
    • sctmon.c
    • sctpost.c
    • sctos.c
    • post.h, sdt.h, itex.h, dll.h
      On UNIX:
    • post.o
      In Windows:
    • libpost.lib (the statically linked library)
    • post.lib (for dynamically linking)
    • post.dll (the dynamically linked library)

On UNIX, all files can be found in the directory $telelogic/sdt/sdtdir/<machine dependent dir>/INCLUDE where <machine dependent dir> is for example sunos5sdtdir on SunOS 5, and hppasdtdir on HP.

In Windows, all files can be found in the directory <installation directory>\sdt\sdtdir\wini386\include. There are different kernel directories for the Borland and the Microsoft compiler. The Borland directories have the prefix scta while the Microsoft compiler directories have the prefix sctam.

Description of Files

scttypes.h

This file contains type definitions and extern declarations of variables and functions. The file is included by sctsdl.c, sctpred.c, sctutil.c, sctmon.c, sctpost.c, sctos.c, and by each generated C file.

sctlocal.h

This file contains type definitions and extern declarations of variables and functions that are used only in the kernel. This file is not included in generated code.

sctpred.h

This file contains type definitions and extern declarations handling the predefined data types in SDL (except PId, which is in scttypes.h). This file is included in generated code via scttypes.h.

sctsdt.c

In this file the implementation of the SDL operations can be found, together with the functions used for scheduling. In more detail, this file contains groups of functions for:

  • Handling and reporting SDL dynamic errors
  • SDL operations, such as Output, Create, Stop, Nextstate, Set, Reset, together with help functions for these activities
  • Initialization and the main loop (the scheduler).

sctpred.c

The functions implementing the operations defined in the SDL predefined data types can be fund in this file. Operators for PId is implemented in sctsdl.c.

sctutil.c

This file contains basic read and write functions together with functions to handle reading and writing of values of abstract data types, including the predefined data types. It also contains the functions for MSC trace.

sctmon.c

The sctmon.c file contains the functions that implement the monitor interface, that is, interpreting and executing monitor commands.

sctpost.c

This file contains all the basic functions that are used to connect a simulator with the other parts of the SDL suite.

sctos.c

In this file, some functions that represent the dependencies of hardware, operating system and compiler are placed.

The basic functions necessary for an application are a function to read the clock and a function to allocate memory.

To move a generated C program plus the runtime library to a new platform (including a new compiler), the major changes are to be made in this file, together with writing a new section in scttypes.h to describe the properties of the new compiler.

post.h and sdt.h

These files are included in sctpost.c if the communication mechanism with other the SDL suite applications should be part of the actual object code version of the library. The file post.h contains the function interface, while sdt.h contains message definitions.

Caution!

Windows only: When linking with the PostMaster's dynamically linked libraries (post.lib and post.dll), the environment variable USING_DLL must be defined before including post.h. Example:

 #define USING_DLL
 #include "post.h"
 #undef USING_DLL

post.o (post.lib in Windows)

This file contains the implementation of functions needed to send messages, via the Postmaster, to other tools in the SDL suite.


The Symbol Table

The symbol table is used for storing information mainly about the static properties of the SDL system, such as the block structure, connections of channels and the valid input signal set for processes. Some dynamic properties are also placed in the symbol table; for example the list of all active process instances of a process instance set. This is part of the node representing the process instance set.

The nodes in the symbol table are structs with components initialized in the declaration. During the initialization of the application, in the yInit function in generated code, a tree is built up from these nodes.

Symbol Table Tree Structure

The symbol table is created in two steps:

  1. First, symbol table nodes are declared as structs with components initialized in the declaration (in generated code).
  2. Then, the yInit function (in generated code) updates some components in the nodes and builds a tree from the nodes. This operation is not needed in an application!

The following names can be used to refer to some of the nodes that are always present. These names are defined in scttypes.h.

xSymbolTableRoot
xEnvId
xSrtN_SDL_Bit
xSrtN_SDL_Bit_String
xSrtN_SDL_Boolean
xSrtN_SDL_Character
xSrtN_SDL_Charstring
xSrtN_SDL_Duration
xSrtN_SDL_IA5String
xSrtN_SDL_Integer
xSrtN_SDL_Natural
xSrtN_SDL_Null
xSrtN_SDL_NumericString
xSrtN_SDL_Object_Identifier
xSrtN_SDL_Octet
xSrtN_SDL_Octet_String
xSrtN_SDL_PId
xSrtN_SDL_PrintableString
xSrtN_SDL_Real
xSrtN_SDL_Time
xSrtN_SDL_VisibleString

xSymbolTableRoot is the root node in the symbol table tree. Below this node the system node is inserted. After the system node, there is a node representing the environment of the system (xEnvId). Then there is one node for each package referenced from the SDL system. This is true also for the package predefined containing the predefined data types. The nodes for the predefined data types, that are sons to the node for the package predefined, can be directly referenced by the names xSrtN_SDL_xxx, according to the list above.

Nodes in the symbol table are placed in the tree exactly according its place of declaration in SDL. A node that represent an item declared in a block is placed as a child to that block node, and so on. The hierarchy in the symbol table tree will directly reflect the block structure and declarations within the blocks and processes.

A small example can be found in Figure 550. The following node types will be present in the tree:

Node Type
Description

 xSystemEC
Represent the system or the system instance.

 xSystemTypeEC
Represents a system type.

 xPackageEC
Represents a package.

 xBlockEC
Represent blocks and block instances.

 xBlockTypeEC
Represents a block type.

 xBlockSubstEC
Represents a block substructure and can be found as a child of a block node.

 xProcessEC
Represent processes and process instances. The environment process node is placed after the system node and is used to represent the environment of the system.

 xProcessTypeEC
Represents a process type.

 xServiceEC
Represents a service or service instance.

 xServiceTypeEC
Represents a service type.

 xProcedureEC
Represents a procedure.

 xOperatorEC
Represents an operator diagram, i.e. an ADT operator with an implementation in SDL.

 xCompoundStmtEC
Represents a compound statement containing variable declarations.

 xSignalEC
 xTimerEC
Represents a signal or timer type.

 xRPCSignalEC
Represents the implicit signals (pCALL, pREPLY) used to implement RPCs.

 xSignalParEC
There will be one signal parameter node, as a child to a signal, timer, and RPC signal node, for each signal or timer parameter.

 xStartUpSignalEC
Represents a start-up signal, that is, the signal sent to a newly created process containing the actual FPAR parameters. An xStartUpSignalEC node is always placed directly after the node for its process.

 xSortEC
xSyntypeEC
Represents a newtype or a syntype.

 Struct Component
Node
(xVariableEC)
A sort node representing a struct has one struct component node as child for each struct component in the sort definition.

 xLiteralEC
A sort node similar to an enum type has one literal node as child for each literal in literal list.

 xStateEC
Represents a state and can be found as a child to process and procedure nodes.

 xVariableEC
xFormalParEC
Represents a variable (DCL) or a formal parameter (FPAR) and can be found as children of process and procedure nodes.

 xChannelEC
xSignalRouteEC
 xGate
Represents a channel, a signal route, or a gate.
 xRemoteVarEC
Represents a remote variable definition.

 xRemotePrdEC
Represents a remote procedure definition.

 xSyntVariableEC
Represents implicit variables or components introduced by the Cadvanced/Cbasic SDL to C Compiler. Used only by the Validator.

 xSynonymEC
Represent synonyms. Used only by the Validator.

The nodes (the struct variables) will in generated code be given names according to the following table:

ySysR_SystemName
(system, system type, system instance)
yPacR_PackageName
yBloR_BlockName
(block, block type, block instance)
yBSuR_SubstructureName
yPrsR_ProcessName
(process, process type, process instance)
yPrdR_ProcedureName (procedure, operator)
ySigR_SignalName
(signal, timer, startup signal, RPC signal)
yChaR_ChannelName (channel, signal route, gate)
yStaR_StateName
ySrtR_NewtypeName (newtype, syntype)
yLitR_LiteralName
yVarR_VariableName
(variable, formal parameter, signal
parameter, struct component, synt.variable)
yReVR_RemoteVariable
yRePR_RemoteProcedure

In most cases it is of interest to refer to a symbol table node via a pointer. By taking the address of a variable according to the table above, i.e.

& yPrsR_Process1

such a reference is obtained. For backward compatibility, macros according to the following example is also generated for several of the entity classes:

#define yPrsN_ProcessName (&yPrsR_ProcessName)

Types Representing the Symbol Table Nodes

The following type definitions, from the file scttypes.h, are used in connection with the symbol table:

typedef enum {
xRemoteVarEC,
xRemotePrdEC,
xSignalrouteEC,
xStateEC,
xTimerEC,
xFormalParEC,
xLiteralEC,
xVariableEC,
xBlocksubstEC,
xPackageEC,
xProcedureEC,
xOperatorEC,
xProcessEC,
xProcessTypeEC,
xGateEC,
xSignalEC,
xSignalParEC,
xStartUpSignalEC,
xRPCSignalEC,
xSortEC,
xSyntypeEC,
xSystemEC,
xSystemTypeEC,
xBlockEC,
xBlockTypeEC,
xChannelEC,
xServiceEC,
xServiceTypeEC,
xCompoundStmtEC,
xSyntVariableEC
xMonitorCommandEC
} xEntityClassType;

typedef enum {
xPredef, xUserdef, xEnum,
xStruct, xArray, xGArray, xCArray,
xOwn, xORef, xRef, xString,
xPowerSet, xGPowerSet, xBag, xInherits, xSyntype,
xUnion, xUnionC, xChoice
} xTypeOfSort;

typedef char *xNameType;

typedef struct xIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
} xIdRec;

/*BLOCKSUBSTRUCTURE*/
typedef struct xBlockSubstIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
} xBlockSubstIdRec;

/*LITERAL*/
typedef struct xLiteralIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
int LiteralValue;
} xLiteralIdRec;

/*PACKAGE*/
typedef struct xPackageIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
#ifdef XIDNAMES
xNameType ModuleName;
#endif
} xPackageIdRec;

/*SYSTEM*/
typedef struct xSystemIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xIdNode *Contents;
xPrdIdNode *VirtPrdList;
xSystemIdNode Super;
#ifdef XTRACE
int Trace_Default;
#endif
#ifdef XGRTRACE
int GRTrace;
#endif
#ifdef XMSCE
int MSCETrace;
#endif
} xSystemIdRec;

/*CHANNEL,SIGNALROUTE,GATE*/
#ifndef XOPTCHAN
typedef struct xChannelIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xSignalIdNode *SignalSet; /*Array*/
xIdNode *ToId; /*Array*/
xChannelIdNode Reverse;
} xChannelIdRec; /* And xSignalRouteEC.*/
#endif

/*BLOCK*/
typedef struct xBlockIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xBlockIdNode Super;
xIdNode *Contents;
xPrdIdNode *VirtPrdList;
xViewListRec *ViewList;
int NumberOfInst;
#ifdef XTRACE
int Trace_Default;
#endif
#ifdef XGRTRACE
int GRTrace;
#endif
#ifdef XMSCE
int MSCETrace;
int GlobalInstanceId;
#endif
} xBlockIdRec;

/*PROCESS*/
typedef struct xPrsIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xStateIdNode *StateList;
xSignalIdNode *SignalSet;
#ifndef XNOUSEOFSERVICE
xIdNode *Contents;
#endif
#ifndef XOPTCHAN
xIdNode *ToId; /*Array*/
#endif
int MaxNoOfInst;
#ifdef XNRINST
int NextNr;
int NoOfStaticInst;
#endif
xPrsNode *ActivePrsList;
xptrint VarSize;
#if defined(XPRSPRIO) || defined(XSIGPRSPRIO) || \
defined(XPRSSIGPRIO)
int Prio;
#endif
xPrsNode *AvailPrsList;
#ifdef XTRACE
int Trace_Default;
#endif
#ifdef XGRTRACE
int GRTrace;
#endif
#ifdef XBREAKBEFORE
char *(*GRrefFunc) (int, xSymbolType *);
int MaxSymbolNumber;
int SignalSetLength;
#endif
#ifdef XMSCE
int MSCETrace;
#endif
#ifdef XCOVERAGE
long int *CoverageArray;
long int NoOfStartTransitions;
long int MaxQueueLength;
#endif
void (*PAD_Function) (xPrsNode);
void (*Free_Vars) (void *);
xPrsIdNode Super;
xPrdIdNode *VirtPrdList;
xBlockIdNode InBlockInst;
#ifdef XBREAKBEFORE
char *RefToDefinition;
#endif
} xPrsIdRec;

#ifndef XNOUSEOFSERVICE
/*SERVICE*/
typedef struct xSrvIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xStateIdNode *StateList;
xSignalIdNode *SignalSet;
#ifndef XOPTCHAN
xIdNode *ToId;
#endif
xptrint VarSize;
#ifdef XBREAKBEFORE
char *(*GRrefFunc) (int, xSymbolType *);
int MaxSymbolNumber;
int SignalSetLength;
#endif
#ifdef XCOVERAGE
long int *CoverageArray;
long int NoOfStartTransitions;
#endif
xSrvNode *AvailSrvList;
void (*PAD_Function) (xPrsNode);
void (*Free_Vars) (void *);
xSrvIdNode Super;
xPrdIdNode *VirtPrdList;
} xSrvIdRec;
#endif

/*PROCEDURE*/
typedef struct xPrdIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xStateIdNode *StateList;
xSignalIdNode *SignalSet;
xbool (*Assoc_Function) (xPrsNode);
void (*Free_Vars) (void *);
xptrint VarSize;
xPrdNode *AvailPrdList;
#ifdef XBREAKBEFORE
char *(*GRrefFunc) (int, xSymbolType*);
int MaxSymbolNumber;
int SignalSetLength;
#endif
#ifdef XCOVERAGE
long int *CoverageArray;
#endif
xPrdIdNode Super;
xPrdIdNode *VirtPrdList;
} xPrdIdRec;

typedef struct xRemotePrdIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xRemotePrdListNode RemoteList;
} xRemotePrdIdRec;

/* SIGNAL, TIMER */
typedef struct xSignalIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xptrint VarSize;
xSignalNode *AvailSignalList;
xbool (*Equal_Timer) (void *, void *);
#ifdef XFREESIGNALFUNCS
void (*Free_Signal) (void *);
#endif
#ifdef XBREAKBEFORE
char *RefToDefinition;
#endif
#if defined(XSIGPRIO) || defined(XSIGPRSPRIO) || defined(XPRSSIGPRIO)
int Prio;
#endif
} xSignalIdRec; /* and xTimerEC, xStartUpSignalEC,
and xRPCSignalEC.*/

/*STATE*/
typedef struct xStateIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
int StateNumber;
xInputAction *SignalHandlArray;
int *InputRef;
xInputAction (*EnablCond_Function)
(XSIGTYPE, void *);
void (*ContSig_Function)
(void *, int *, xIdNode *, int *);
int StateProperties;
#ifdef XCOVERAGE
long int *CoverageArray;
#endif
xStateIdNode Super;
#ifdef XBREAKBEFORE
char *RefToDefinition;
#endif
} xStateIdRec;

/*SORT*/
typedef struct xSortIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
#ifdef XFREEFUNCS
void (*Free_Function) (void **);
#endif
#ifdef XTESTF
xbool (*Test_Function) (void *);
#endif
xptrint SortSize;
xTypeOfSort SortType;
xSortIdNode CompOrFatherSort;
xSortIdNode IndexSort;
long int LowestValue;
long int HighestValue;
long int yrecIndexOffset;
long int typeDataOffset;
} xSortIdRec;

/*VARIABLE,...*/
typedef struct xVarIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xSortIdNode SortNode;
xptrint Offset;
xptrint Offset2;
int IsAddress;
} xVarIdRec; /* And xFormalParEC and
xSignalParEC.*/

typedef struct xRemoteVarIdStruct {
xEntityClassType EC;
#ifdef XSYMBTLINK
xIdNode First;
xIdNode Suc;
#endif
xIdNode Parent;
#ifdef XIDNAMES
xNameType Name;
#endif
xptrint SortSize;
xRemoteVarListNode RemoteList;
} xRemoteVarIdRec;

There are also pointer types defined for each of the x EC IdStruct according to the following example:

typedef XCONST struct xIdStruct *xIdNode;

The type definitions above define the contents in the symbol table nodes. Each x EC IdStruct, where EC should be replaced by an appropriate string, have the first five components in common. These components are used to build the symbol table tree. To access these components, a pointer to a symbol table node can be type cast to any of the xId EC Node types. The type xIdNode is used as such general type, for example when traversing the tree.

The five components present in all xIdNode are:

  • EC of type xEntityClassType. This component is used to determine what sort of SDL object the node represents. xEntityClassType is an enum type containing elements for all entity classes in SDL.
  • First, Suc, and Parent of type xIdNode. These components are used to build the symbol table tree. First refers to the first child of the current node. Suc refers to the next brother, while Parent refers to the father node. Only Parent is needed in an application.
  • Name of type xNameType, which is defined as char *. This component is used to represent the name of the current SDL object as a character string. Not needed in an application.

Next there are components depending on what entity class that is to be represented. Below we discuss the non-common elements in the other x EC IdStruct.

Package

  • ModuleName of type xNameType. If the package is generated from ASN.1, this component holds the name of the ASN.1 module as a char *.

System, System Type

  • Content of type xIdNode *. This component contains a list of all channels at the system level.
  • VirtPrdList of type xPrdIdNode *. This is a list of all virtual procedures in this system instance.
  • Super of type xSystemIdNode. This is a reference to the inherited system type. In a system this component in null. In a system instance it is a reference to the instantiated system type.
  • Trace_Default of type int. This component contains the current trace value defined for the system.
  • GRTrace of type int. This component contains the current GR (graphical) trace value defined for the system.
  • MSCETrace of type int. This component contains the current MSCE (Message Sequence Chart Editor) trace value defined for the system.

Channel, Signal route, Gate

For channels, signal routes, and gates there are always two consecutive xChannelIdNodes in the symbol table, representing the two possible directions for a channel, signal route, or gate. The components are:

  • SignalSet of type xIdNode *. This component represents the signal set of the channel in the current direction (a unidirectional channel has an empty signal set in the opposite direction).
    SignalSet is an array with components referring to the xSignalIdNodes that represent the signals which are members of the signal set. The last component in the array is always a NULL pointer (the value (xSignalIdNode)0).
  • ToId of type xIdNode *. This is an array of xIdNodes, where each array component is a pointer to a symbol table node representing an SDL object, which this Channel/Signal route/Gate is connected to (connected to in the sense: to the SDL objects that signals are sent forward to).
    The SDL objects that may be referenced in ToId are channels, signal routes, gates, processes, and services. The last component in the array is always a NULL pointer (the value (xIdNode)0). See also "Channels and Signal Routes" .
  • Reverse of type xChannelIdNode. This is a reference to the symbol table node that represents the other direction of the same channel, signal route, or gate.

Block, Block Type, Block Instance

  • Super of type xBlockIdNode. In a block, this component is NULL. In a block type this component is a reference to the block that this block inherits from (NULL if no inheritance). In a block instance, this is a reference to the block type that is instantiated.
  • Contents of type xIdNode *. In a block instance, these components contains list of:
    • The process instantiations in the block
    • The signal routes in the block
    • The outgoing gates from the block
    • The processes in the block
    • The gates defined in process instantiations in the block.
  • VirtPrdList of type xPrdIdNode *. This is a list of all virtual procedures in this block instance.
  • ViewList of type xViewListRec *. This is a list of all revealed variables in the block or block instance.
  • NumberOfInst of type int. This is the number of block instances in a block instance set. The component is thus only relevant for a block instance.
  • Trace_Default of type int. This component contains the current value of the trace defined for the block.
  • GRTrace of type int. This component contains the current value of the GR trace defined for the block.
  • MSCETrace of type int. This component contains the current MSCE (Message Sequence Chart Editor) trace value defined for the block.
  • GlobalInstanceId of type int. This component is used to store a unique id needed when performing MSCE trace.

Process, Process Type, Process Instance

  • StateList of type xStateIdNode *. This is a list of references to the xStateIdNodes for this process or process type. Using the state value of an executing process, this list can be used to find the corresponding xStateIdNode.
  • SignalSet of type xIdNode *. This represents the valid input signal set of the process or process type.
    SignalSet is an array with components that refer to xSignalIdNodes that represent the signals and timers which are part of the signal set. The last component in the array is always a NULL pointer (the value (xSignalIdNode)0).
  • Contents of type xIdNode *. This is an array containing references to the xSrvIdNodes of the services and service instances in this process.
  • ToId of type xIdNode *. This is an array of xIdNode, where each array component is a pointer to an IdNode representing an SDL object that this process or process instance is connected to (connected to in the sense: to the SDL objects that signals are sent forward to).
    The SDL objects that may be referenced in ToId are channels, signal routes, gates, processes, and services. The last component in the array is always a NULL pointer (the value (xIdNode)0). See also section "Channels and Signal Routes" .
  • MaxNoOfInst of type int. This represents the maximum number of concurrent processes that may exist according to the specification for the current process or process instance. An infinite number of concurrent processes is represented by -1.
  • NextNo of type int. This is the instance number that will be assigned to the next instance that is created of this process instance set.
  • NoOfStaticInst of type int.This component contains the number of static instance of this process instance set that should be present at start up. Used for process and process instance.
  • ActivePrsList of type xPrsNode *. This is the address of a pointer to the "first" in the (single linked) list of active process instances of the current process or process instantiation.
    The list is continued using the NextPrs component in the xPrsRec struct that is used to represent a process instance. The order in the list is such that the first created of the active process instances is last, and the latest created is first.
  • VarSize of type xptrint. The size, in bytes, of the data area used to represent the process (the struct: yVDef_ProcessName).
  • Prio of type int. This represents the process priority.
  • AvailPrsList of type xPrsNode. This is the address to the avail list pointer for process instances that have stopped. The data area can later be reused in subsequent Create actions on this process or process instantiation.
  • Trace_Default of type int. This component contains the current value of the trace defined for the process.
  • GRTrace of type int. This component contains the current value of the GR trace defined for the process.
  • GRrefFunc, which is a pointer to a function that, given a symbol number (number assigned to a process symbol), will return a string containing the SDT reference to that symbol.
  • MaxSymbolNumber of type int. This component is the number of symbols contained in the current process or process type.
  • SignalSetLength of type int. This component is the number of signals contained in the signal set of the current process or process type.
  • MSCETrace of type int. This component contains the current MSCE (Message Sequence Chart Editor) trace value defined for the process.
  • CoverageArray of type long int *. This component is used as an array over all symbols in the process. Each time a symbol is executed the corresponding array component is increased by 1.
  • NoOfStartTransitions of type long int. This component is used to count the number of times the start transition of the current process is executed. This information is presented in the coverage tables.
  • MaxQueueLength of type long int. This component is used to register the maximum input port length for any instance of the current process. The information is presented in the coverage tables.
  • PAD_Function, which is a pointer to a function. This pointer refers to the yPAD_ProcessName function for the current process. This function is called when a process instance of this type is to execute a transition. The PAD_Functions will of course be part of generated code, as they contain the action defined in the process graphs.
  • Free_Vars, which is a pointer to a function. This pointer refers to the yFree_ProcessName function for the current process. This function is called when the process performs a stop action to deallocate memory used by the local variables in the process.
  • Super of type xPrsIdNode. In a process this component is NULL. In a process type this component is a reference to the process type that this process type inherits from (NULL if no inheritance). In a process instance set, this is a reference to the process type that is instantiated.
  • VirtPrdList of type xPrdIdNode *. This is a list of all virtual procedures in this process instantiation.
  • InBlockInst of type xBlockIdNode. This component is a reference to the block instance set (if any) that this process or process instantiation is part of.
  • RefToDefinition of type char *. This is the SDT reference to this process.

Service, Service Type, Service Instance

  • StateList of type xStateIdNode *. This is a list of the references to the xStateIdNodes for this service or service type. Using the state value of an executing service, this list can be used to find the corresponding xStateIdNode.
  • SignalSet of type xIdNode *. This represents the valid input signal set of the service or service type.
    SignalSet is an array with components that refer to xSignalIdNodes that represent the signals and timers which are part of the signal set. The last component in the array is always a NULL pointer (the value (xSignalIdNode)0).
  • ToId of type xIdNode *. This is an array of xIdNode, where each array component is a pointer to an IdNode representing an SDL object that this service or service instance is connected to (connected to in the sense: to the SDL objects that signals are sent forward to).
    The SDL objects that may be referenced in ToId are channels, signal routes, gates, processes, and service. The last component in the array is always a NULL pointer (the value (xIdNode)0). See also section "Channels and Signal Routes" .
  • VarSize of type xptrint. The size, in bytes, of the data area used to represent the service (the struct: yVDef_ServiceName).
  • GRrefFunc, which is a pointer to a function that, given a symbol number (number assigned to a service symbol), will return a string containing the SDT reference to that symbol.
  • MaxSymbolNumber of type int. This component is the number of symbols contained in the current service or service type.
  • SignalSetLength of type int. This component is the number of signals contained in the signal set of the current service or service type.
  • CoverageArray of type long int. This component is used as an array over all symbols in the service. Each time a symbol is executed the corresponding array component is increased by 1.
  • NoOfStartTransitions of type long int. This component is used to count the number of times the start transition of the current service is executed. This information is presented in the coverage tables.
  • AvailSrvList of type xSrvNode. This is the address to the avail list pointer for service instances that have stopped. The data area can later be reused.
  • PAD_Function, which is a pointer to a function. This pointer refers to the yPAD_ServiceName function for the current service. This function is called when a service instance of this type is to execute a transition. The PAD_Functions will of course be part of generated code, as they contain the action defined in the service graphs.
  • Free_Vars, which is a pointer to a function. This pointer refers to the yFree_SeriveName function for the current service. This function is called when the service performs a stop action to deallocate memory used by the local variables in the service.
  • Super of type xSrvIdNode. In a service this component is NULL. In a service type this component is a reference to the service type that this service type inherits from (NULL if no inheritance). In a service instantiation this is a reference to the service type that is instantiated.
  • VirtPrdList of type xPrdIdNode *. This is a list of all virtual procedures in this service instantiation.

Procedure, Operator Diagram, Compound Statement

Note that operator diagrams and compound statements containing variable declarations are treated as procedures. However, such objects can, for example, not contain states.

  • StateList of type xStateIdNode *. This is a list of references to the xStateIdNodes for this process or process type. Using the state value of an executing process, this list can be used to find the corresponding xStateIdNode.
  • SignalSet of type xIdNode *. This represents the valid input signal set of the process or process type.
    SignalSet is an array with components that refer to xSignalIdNodes that represent the signals and timers which are part of the signal set. The last component in the array is always a NULL pointer (the value (xSignalIdNode)0).
  • Assoc_Function, which is a pointer to a function. This pointer refers to the y ProcedureName function for the current procedure. This function is called when the SDL procedure is called and will execute the appropriate actions. The y ProcedureName functions will, of course, be part of generated code as they contain the action defined in the procedure graphs.
  • Free_Vars, which is a pointer to a function. This pointer refers to the yFree_ProcedureName function for the current procedure. This function is called when the procedure performs a return action to deallocate memory used by the local variables in the procedure.
  • VarSize of type xptrint. The size, in bytes, of the data area used to represent the procedure (struct yVDef_ProcedureName).
  • AvailPrdList of type xPrdNode *. This is the address of the avail list pointer for the data areas used to represent procedure instances. At a return action the data area is placed in the avail list and can later be reused in subsequent Calls of this procedure type.
  • GRrefFunc, which is a pointer to a function that given a symbol number (number assigned to a procedure symbol) will return a string containing the SDT reference to that symbol.
  • MaxSymbolNumber of type int. This component is the number of symbols contained in the current procedure.
  • SignalSetLength of type int. This component is the number of signals contained in the signal set of the current procedure.
  • CoverageArray of type long int. This component is used as an array over all symbols in the procedure. Each time a symbol is executed the corresponding array component is increased by 1.
  • Super of type xPrdIdNode. This component is a reference to the procedure that this procedure inherits from (NULL if no inheritance).
  • VirtPrdList of type xPrdIdNode *. This is a list of all virtual procedures in this procedure.

Remote Procedure

  • RemoteList of type xRemotePrdListNode. This component is the start of a list of all processes that exports this procedure. This list is a linked list of xRemotePrdListStructs, where each node contains a reference to the exporting process.

Signal, Timer, StartUpSignal, and RPC Signals

  • VarSize of type xptrint. The size, in bytes, of the data area used to represent the signal (the struct: yPDef_SignalName).
  • AvailSignalList of type xSignalNode *. This is the address to the avail list pointer for signal instances of this signal type.
  • Equal_Timer, which is a pointer to a function. This pointer only refers to a function when this node is used to represent a timer with parameters.
    In this case the referenced function can be used to investigate if the parameters of two timers are equal or not, which is necessary at reset actions. The Equal_Timer functions will be part of generated code. These functions are called from the functions xRemoveTimer and xRemoveTimerSignal, both defined in sctsdl.c
  • Free_Signal, which is a function. This function takes a signal reference and returns any dynamic data referenced from the signal parameters to the pool of available memory.
  • RefToDefinition of type char *. The SDT reference to the definition of the signal or timer.
  • Prio, of type int. The priority of the signal.

State

  • StateNumber of type int. The int value used to represent this state.
  • SignalHandlArray of type xInputAction *. This component refers to an array of xInputAction, where xInputAction is an enum type with the possible values xDiscard, xInput, xSave, xEnablCond, xPrioInput.
    The array will have the same number of components as the SignalSet array in the node representing the process in which this state is contained. Each position in the SignalHandlArray represents the way the signal in the corresponding position in the SignalSet array in the process should be treated in this state.
    The last component in the SignalHandlArray is equal to xDiscard, which corresponds to the 0 value last in the SignalSet.
    If the SignalHandlArray contains the value xInput, xSave, or xDiscard at a given index, the way to handle the signal is obvious. If the SignalHandlArray contains the value xEnablCond, it is, however, necessary to calculate the enabling condition expression to know if the signal should cause an input or should be saved. This calculation is exactly the purpose of the EnablCond_Function described below.
  • InputRef of type int *. This component is an array. If the SignalHandlArray contains xInput, xPrioInput, or xEnablCond at a certain index, this InputRef contains the symbol number for the corresponding input symbol in the graph.
  • EnablCond_Function, which is a function that returns xInputAction. If the state contains any enabling conditions, this pointer will refer to a function. Otherwise it refers to 0. An EnablCond_Function takes a reference to an xSignalIdNode (referring to a signal) and a reference to a process instance and calculates the enabling condition for the input of the current signal in the current state of the given process instance.
    The function returns either of the values xInput or xSave. The EnablCond_Functions will of course be part of generated code, as they contain enabling condition expressions. These functions are called from the function xFindInputAction in the file sctsdl.c. xFindInputAction is used by the SDL_Output and SDL_Nextstate functions.
  • ContSig_Function, which is a function returning int. If the state contains any continuous signals, this pointer will refer to a function. Otherwise it refers to 0.
  • StateProperties of type int. In this component the three least significant bits are used to indicate:
    • If any enabling condition or continuous signal expression in the state contains a reference to an object that might change its value even though the process does not execute any actions.
    • If there are any priority inputs in the state.
    • If there are any virtual priority inputs in the state.
      Objects according to the first item in the list are: Now, Active (timer is active), Import, View, and Sender. StateProperties is used in the function SDL_Nextstate to take appropriate actions when a process enters a state.
  • CoverageArray of type long int. This component is used as an array over the signalset (+1) of the process. Each time an input operation is performed, the corresponding array component is increased by 1. The last component, at index equal to the length of the signalset, is used to record the number of continuous signals "received" in the state. The information stored in this component is presented in the coverage table.
  • Super of type xPrdIdNode. This component is a reference to the procedure that this procedure inherits from (NULL if no inheritance).
  • RefToDefinition of type char *. The SDT reference to the definition of the state (one of the symbols where this state is defined).

Sort and Syntype

  • Free_Function, which is a function. This function pointer is non-0 for types represented using dynamic memory (Charstring, Octet_string, Strings, Bags, for example). The Free_Functions are used to return dynamic memory to the pool of dynamic memory.
  • Test_Function, which is a function returning xbool. This function is non-0 for all types containing range conditions. The function pointers are used by the monitor system to check the validity of a value when assigning it to a variable.
  • SortSize of type xptrint. This component represents the size, in bytes, of a variable of the current sort.
  • SortType of type xTypeOfSort. This component indicates the type of sort. Possible values are: xPredef, xUserdef, xEnum, xStruct, xArray, xGArray, xCArray, xRef, xString, xPowerSet, xBag, xGPowerSet, xInherits, xSyntype, xUnion, xUnionC, and xChoice.

SortType is xArray, xGArray, xCArray

  • CompOrFatherSort of type xSortIdNode. This is a pointer to the SortIdNode that represents the component sort.
  • IndexSort of type xSortIdNode. This is a pointer to the SortIdNode that represents the index sort. In a xCArray the index sort in always Integer.
  • In xGArray, LowestValue is used as the offset of Data in the xxx_ystruct.
    In xArray and xCArray it is 0.
  • In xGArray, HighestValue is used as the size of the xxx_ystruct. In xArray it is 0.
    In xCArray it is the highest index, i.e. the Length - 1.
  • In xGArray, yrecIndexOffset is used as the offset of Index in the xxx_ystruct.
    In xArray and xCArray it is 0.
  • In xGArray, yrecDataOffset is used as the offset of Data in the type (i.e. the value representing the default value).
    In xArray and xCArray it is 0.

SortType is xString, xGPowerSet, xBag

  • CompOrFatherSort of type xSortIdNode. This is a pointer to the SortIdNode that represents the component sort.
  • LowestValue is used as the offset of Data in the xxx_ystruct.
  • HighestValue is used as the size of the xxx_ystruct.

SortType is xPowerSet, xRef, xOwn, xORef

  • CompOrFatherSort of type xSortIdNode. This is a pointer to the SortIdNode that represents the component sort.

SortType is xInherits

  • CompOrFatherSort, of type xSortIdNode. This is a pointer to the SortIdNode that represents the inherited sort.

SortType is xSyntype

  • CompOrFatherSort, of type xSortIdNode. This is a pointer to the SortIdNode that represents the father sort (the newtype from which the syntype originates, even if it is a syntype of a syntype).
  • IndexSort, of type xSortIdNode. This is a pointer to the SortIdNode that represents the represents the father sort (the newtype or syntype from which the syntype originates).
  • LowestValue, of type long int. If the syntype can be used as an index in an array (translated to a C array) then this value is the lowest value in the syntype range, otherwise it is 0.
  • HighestValue, of type long int. If the syntype can be used as an index in an array (translated to a C array) then this value is the highest value in the syntype range, otherwise it is 0. The LowestValue and HighestValue are used by the monitor when it handles arrays with this type as index type.

Variable, FormalPar, SignalPar, and Struct Components

  • SortNode of type xSortIdNode. This component is a pointer to the SortIdNode that represents the sort of this variable or parameter.
  • Offset of type xptrint. This component represents the offset, in bytes, within the struct that represents the process or procedure variables, the signal parameter, or the SDL struct. In other words, this is the relative place of this component within the struct.
  • Offset2 of type xptrint. For a formal parameter in a process this component represents the offset, in bytes, of a formal parameter in the StartUpSignal. For an exported variable in a process this component represents the offset, in bytes, of the exported value for this variable.
  • IsAddress of type int. This component is only used for procedure and operator formal parameters and is then used to indicate if the parameter in IN or IN/OUT or a result variable.

Remote Variable

  • SortSize of type xptrint. This component is the size of the type of the exported variables.
  • RemoteList of type xRemoteVarListNode. This component is the start of a list of all processes that exports this variable. This list is a linked list of xRemoteVarListStructs, where each node contains a reference to the exporting process and the Offset where to find the exported value.

Type Info Nodes

This section describes the most important implementation details regarding the type info node. Type info nodes are data structures that are used during run-time by the functions providing generic implementations of SDL operators. As the type info nodes contain essentially the same information as the xSortIdNodes, the type info nodes are used in more and more places in the code where xSortIdNode previously were used. In the longer perspective the xSortIdNode will be removed completely.

The type definitions that describe the type info nodes are listed in the sctpred.h file.

Each type info node is a struct that consists of:

  • general components that are available for all type info nodes
  • type-specific components that describe each specific type.

The following utility macros can be used to configure the type info nodes:

#ifndef T_CONST
#define T_CONST const
#endif

#ifndef T_SDL_EXTRA_COMP
#define T_SDL_EXTRA_COMP
#define T_SDL_EXTRA_VALUE
#endif

#ifndef T_SDL_USERDEF_COMP
#define T_SDL_USERDEF_COMP
#endif

#if defined(XREADANDWRITEF) && !defined(T_SDL_NAMES)
#define T_SDL_NAMES
#endif

#ifdef T_SDL_NAMES
#define T_SDL_Names(P) , P
#else
#define T_SDL_Names(P)
#endif

#ifdef T_SIGNAL_SDL_NAMES
#define T_Signal_SDL_Names(P) , P
#else
#define T_Signal_SDL_Names(P)
#endif

#ifdef T_SDL_INFO
#define T_SDL_Info(P) , P
#else
#define T_SDL_Info(P)
#endif

#ifndef XNOUSE_OPFUNCS
#define T_SDL_OPFUNCS(P) , P
#else
#define T_SDL_OPFUNCS(P)
#endif

struct tSDLFuncInfo;

General Components

The following components are available for all type info nodes. The definition of the components is only listed in this section, but it is valid for each type info node listed in the next section.

/* --- General type information for SDL types --- */

typedef T_CONST struct tSDLTypeInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
} tSDLTypeInfo;

  • TypeClass: This component defines which type the info node describes. A list of available types and their corresponding values can be found in the enum type definition below:
typedef enum
{
/*SDL - standard types*/
type_SDL_Integer=128,
type_SDL_Real=129,
type_SDL_Natural=130,
type_SDL_Boolean=131,
type_SDL_Character=132,
type_SDL_Time=133,
type_SDL_Duration=134,
type_SDL_Pid=135,
type_SDL_Charstring=136,
type_SDL_Bit=137,
type_SDL_Bit_string=138,
type_SDL_Octet=139,
type_SDL_Octet_string=140,
type_SDL_IA5String=141,
type_SDL_NumericString=142,
type_SDL_PrintableString=143,
type_SDL_VisibleString=144,
type_SDL_NULL=145,
type_SDL_Object_identifier=146,

/* SDL - standard ctypes */
type_SDL_ShortInt=150,
type_SDL_LongInt=151,
type_SDL_UnsignedShortInt=152,
type_SDL_UnsignedInt=153,
type_SDL_UnsignedLongInt=154,
type_SDL_Float=155,
type_SDL_Charstar=156,
type_SDL_Voidstar=157,
type_SDL_Voidstarstar=158,

/* SDL - user defined types */
type_SDL_Syntype=170,
type_SDL_Inherits=171,
type_SDL_Enum=172,
type_SDL_Struct=173,
type_SDL_Union=174,
type_SDL_UnionC=175,
type_SDL_Choice=176,
type_SDL_ChoicePresent=177,
type_SDL_Powerset=178,
type_SDL_GPowerset=179,
type_SDL_Bag=180,
type_SDL_String=181,
type_SDL_LString=182,
type_SDL_Array=183,
type_SDL_Carray=184,
type_SDL_GArray=185,
type_SDL_Own=186,
type_SDL_Oref=187,
type_SDL_Ref=188,
type_SDL_Userdef=189,
type_SDL_EmptyType=190,

/* SDL - signals */
type_SDL_Signal=200,
type_SDL_SignalId=201

} tSDLTypeClass;

  • OpNeeds: This component contains four bits that give the properties of the type regarding assignment, equal test, free function, and initialization.
    • The first bit indicates if the type is a pointer that needs to be automatically freed, or if it contains a pointer that needs to be automatically freed. If the first bit is set, it is necessary to look for memory to be freed inside of a value of this type.
    • The second bit indicates if memcmp can be used to test if two values of this type are equal or not. If the bit is set, special treatment is needed.
    • The third bit indicates if memcpy can be used to perform assign of this type. If the bit is set, special treatment is needed.
    • The fourth bit indicates if this type needs to be initialized to anything else than 0.

The following macros can be used to test these properties:

#define NEEDSFREE(P) \
(((tSDLTypeInfo *)(P))->OpNeeds & (unsigned char)1)
#define NEEDSEQUAL(P) \
(((tSDLTypeInfo *)(P))->OpNeeds & (unsigned char)2)
#define NEEDSASSIGN(P) \
(((tSDLTypeInfo *)(P))->OpNeeds & (unsigned char)4)
#define NEEDSINIT(P) \
(((tSDLTypeInfo *)(P))->OpNeeds & (unsigned char)8)

  • SortSize: This component defines the size of the type.
  • OpFuncs: This is a pointer to a struct containing references to specific assign, equal, free, read, and write functions. This component is only used in special cases. If assign, equal, free, read or write functions have been implemented using #ADT directives, information about this is stored in the OpFuncs field. The default value of the OpFuncs field is 0, but if you have provided any of these functions, the field will be a pointer to a tSDLFuncInfo struct. This struct will in turn refer to the provided functions.
typedef struct tSDLFuncInfo {
void *(*AssFunc) (void *, void *, int);
SDL_Boolean (*EqFunc) (void *, void *);
void (*FreeFunc) (void **);
#ifdef XREADANDWRITEF
char *(*WriteFunc) (void *);
int (*ReadFunc) (void *);
#endif
} tSDLFuncInfo;

  • Name: This is the name of the type as a string literal.
  • FatherScope: This is a pointer to the IdNode for the scope that the type is defined in.
  • SortIdNode: This is a pointer to the xSortIdNode that describes the same type. This field will in a longer perspective be removed.

Type-Specific Components

The following section lists the components that defines the type info nodes. Only the type-specific components are explained. The general components are listed and explained in the section above.

Enumeration types

/* ------------- Enumeration type --------------- */
typedef T_CONST struct {
int LiteralValue;
char *LiteralName;
} tSDLEnumLiteralInfo;

typedef T_CONST struct tSDLEnumInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
#ifdef XREADANDWRITEF
int NoOfLiterals;
tSDLEnumLiteralInfo *LiteralList;
#endif
} tSDLEnumInfo;

  • NoOfLiterals: The number of literals in the enum type.
  • LiteralList: a pointer to an array of tSDLEnumLiteralInfo elements. This list implements a translation table between enum values and literal names as strings

Syntypes, types with inheritance, and Own, Ref, Oref instantiations

/* ------ Syntype, Inherits, Own, Oref, Ref ----- */
typedef T_CONST struct tSDLGenInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLTypeInfo *CompOrFatherSort;
} tSDLGenInfo;

  • CompOrFatherSort: Reference to the type info node of the father sort (syntype, inherits) or component sort (Own, Ref, Oref).

Powersets (implemented as unsigned in [ ])

/* ------------------ Powerset ------------------ */
typedef T_CONST struct tSDLPowersetInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLTypeInfo *CompSort;
int Length;
int LowestValue;
} tSDLPowersetInfo;

  • CompSort: Reference to the type info node of the component sort.
  • Length: The number of possible values in the component sort.
  • LowestValue: The value of the lowest value in the component sort.

Structs

/* ------------------- Struct ------------------- */
typedef int (*tGetFunc) (void *);
typedef void (*tAssFunc) (void *, int);

typedef T_CONST struct {
xptrint OffsetPresent; /* 0 if not optional */
void *DefaultValue;
} tSDLFieldOptInfo;

typedef T_CONST struct {
tGetFunc GetTag;
tAssFunc AssTag;
} tSDLFieldBitFInfo;

typedef T_CONST struct {
tSDLTypeInfo *CompSort;
#ifdef T_SDL_NAMES
char *Name;
#endif
xptrint Offset; /* ~0 for bitfield */
tSDLFieldOptInfo *ExtraInfo;
} tSDLFieldInfo;

typedef T_CONST struct tSDLStructInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLFieldInfo *Components;
int NumOfComponents;
} tSDLStructInfo;

  • Components: An array of tSDLFieldInfo; one component in the array for each field of the struct.
  • NumOfComponents: The number of fields in the struct.
  • CompSort in tSDLFieldInfo: The reference to the type info node of the field sort.
  • Name in tSDLFieldInfo: The name of the field as a string.
  • Offset in tSDLFieldInfo: The offset of the field in the C struct that represents the SDL struct. This component is ~0 for bitfield in SDL (offsets cannot be calculated for bitfields).
  • ExtraInfo in tSDLFieldInfo: The interpretation of this component depends on the properties in the SDL field.
    • if Offset is ~0, the field is a bitfield and ExtraInfo is a pointer to a tSDLFieldBitFInfo struct containing two functions to set and get the value of the bitfield.
    • if Offset is not ~0 and ExtraInfo != 0, the SDL field is either optional or has a default value. ExtraInfo is a pointer to a tSDLFieldOptInfo struct containing the offset for the Present flag (0 if not optional) and a pointer to the default value (0 if no default value).

Choice and #union

/* ---------------- Choice, Union --------------- */

typedef T_CONST struct {
tSDLTypeInfo *CompSort;
#ifdef T_SDL_NAMES
char *Name;
#endif
} tSDLChoiceFieldInfo;

typedef T_CONST struct tSDLChoiceInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLChoiceFieldInfo *Components;
int NumOfComponents;
xptrint OffsetToUnion;
xptrint TagSortSize;
#ifdef XREADANDWRITEF
tSDLTypeInfo *TagSort;
#endif
} tSDLChoiceInfo;

  • Components: An array of tSDLChoiceFieldInfo; one component in the array for each field in the choice/#union.
  • NumOfComponents: The number of fields in the choice/#union.
  • OffsetToUnion: The offset to where the union, within the representation of the choice/#union, starts.
  • TagSortSize: The size of the tag type.
  • TagSort: A reference to the type info node of the tag sort.

Array and Carray

/* --------------- Array, CArray ---------------- */
typedef T_CONST struct tSDLArrayInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLTypeInfo *CompSort;
int Length;
#ifdef XREADANDWRITEF
tSDLTypeInfo *IndexSort;
int LowestValue;
#endif
} tSDLArrayInfo;

  • CompSort: The reference to the type info node of the component sort.
  • Length: The number of components in the array.
  • IndexSort: The reference to the type info node of the index sort.
  • LowestValue: The start value of the index range (as an int).

General arrays

A general array is an array that is represented as a linked list in C.

/* ------------------- GArray ------------------- */
typedef T_CONST struct tSDLGArrayInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLTypeInfo *IndexSort;
tSDLTypeInfo *CompSort;
xptrint yrecSize;
xptrint yrecIndexOffset;
xptrint yrecDataOffset;
xptrint arrayDataOffset;
} tSDLGArrayInfo;

  • IndexSort: The reference to the type info node of the index sort.
  • CompSort: The reference to the type info node of the component sort.
  • yrecSize: The size of the type SDLType_yrec.
  • yrecIndexOffset: The offset of Index in type SDLType_yrec.
  • yrecDataOffset: The offset of Data in type SDLType_yrec.
  • arrayDataOffset: The offset of Data in type SDLType, where SDLType is the name in C of the translated array type.

General powersets, Bags, Strings and Object_identifier

/* -- GPowerset, Bag, String, Object_Identifier - */
typedef T_CONST struct tSDLGenListInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLTypeInfo *CompSort;
xptrint yrecSize;
xptrint yrecDataOffset;
} tSDLGenListInfo;
  • CompSort: The reference to the type info node of the component sort.
  • yrecSize: The size of the type SDLType_yrec
  • yrecDataOffset: The offset of Data in type SDLType_yrec

Limited strings

A limited string is a string that is implemented as an array in C.

/* ------------------ LString ------------------- */
typedef T_CONST struct tSDLLStringInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
tSDLTypeInfo *CompSort;
int MaxLength;
xptrint DataOffset;
} tSDLLStringInfo;

  • CompSort: The reference to the type info node of the component sort.
  • MaxLength: The maximum length of the string.
  • DataOffset: The offset of Data in type SDLType, where SDLType is the name in C of the translated string type.

SDL type (C representation decided with a #ADT directive)

/* ------------------ Userdef ------------------- */
/* used for user defined types #ADT(T(h)) */
typedef T_CONST struct tSDLUserdefInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SDL_NAMES
char *Name;
#endif
#ifdef XREADANDWRITEF
xIdNode FatherScope;
xSortIdNode SortIdNode;
#endif
T_SDL_USERDEF_COMP
} tSDLUserdefInfo;

SDL signal

A signal is treated in the same way as a struct.

/* ------------------- Signal ------------------- */
typedef T_CONST struct {
tSDLTypeInfo *ParaSort;
xptrint Offset;
} tSDLSignalParaInfo;

typedef T_CONST struct tSDLSignalInfoS {
tSDLTypeClass TypeClass;
unsigned char OpNeeds;
xptrint SortSize;
struct tSDLFuncInfo *OpFuncs;
T_SDL_EXTRA_COMP
#ifdef T_SIGNAL_SDL_NAMES
char *Name;
#endif
tSDLSignalParaInfo *Param;
int NoOfPara;
} tSDLSignalInfo;

  • Param: An array with a component of the type tSDLSignalParaInfo for each signal parameter type. For each parameter, the parameter sort is given as a reference to the type info node and as the offset for the parameter value within the struct representing the signal.
  • NoOfPara: The number of parameters in the signal.


The SDL Model

Signals and Timers

Data Structure Representing Signals and Timers

A signal is represented by a struct type. The xSignalRec struct, defined in scttypes.h, is a struct containing general information about a signal except from the signal parameters. In scttypes.h the following information about signals can be found:

#ifdef XMSCE
#define GLOBALINSTID int GlobalInstanceId;
#else
#define GLOBALINSTID
#endif

#if defined(XSIGPATH) && defined(XMSCE)
#define ENVCHANNEL xChannelIdNode EnvChannel;
/* Used if env split into channels in MSC trace */
#else
#define ENVCHANNEL
#endif

#ifdef XENV_CONFORM_2_3
#define XSIGNAL_VARP void * VarP;
#else
#define XSIGNAL_VARP
#endif

define SIGNAL_VARS \
xSignalNode Pre; \
xSignalNode Suc; \
int Prio; \
SDL_PId Receiver; \
SDL_PId Sender; \
xSignalIdNode NameNode; \
GLOBALINSTID \
ENVCHANNEL \
XSIGNAL_VARP

typedef struct xSignalStruct *xSignalNode;
typedef struct xSignalStruct {
SIGNAL_VARS
} xSignalRec;

The xSignalNode type is thus a pointer type which is used to refer to allocated data areas of type xSignalRec. The components in the xSignalRec struct are used as follows:

  • Pre and Suc. These pointers are used to link a signal into the input port of the receiving process instance.
    The input port is a doubly linked list of signals. Suc is also used to link a signal into the avail lists for the current signal type. This list can be found in the SignalIdNode that represents this signal type. If the signal is in the avail list Pre is 0.
  • Prio is used to represent the priority of the signal instance. Signal priorities are used by continuous signals and by ordinary signals if signal priorities are defined (signal priority is a possible extension provided in the product).
  • Receiver is used to reference the receiver of the signal. It is either set in the output statement (OUTPUT TO), or calculated (OUTPUT without TO).
  • Sender is the PId value of the sending process instance. This value is necessary to provide the SDL function SENDER.
  • NameNode is a reference to the xSignalIdNode representing the signal type and thus defines the signal type of this signal instance.
  • VarP is a pointer introduced via the macro XSIGNAL_VARP to make signal compatible with SDT 2.3. Normally this components is not present.
  • EnvChannel is used to identify the outgoing channel in MSCE trace.
  • GlobalInstanceId is used in the MSCE trace as a unique identification of the signal instance.

A signal without parameters are represented by a xSignalStruct, while for signals with parameters a struct type named yPDef_SignalName and a pointer type referencing this struct type (yPDP_SignalName) are defined in generated code. The struct type will start with the SIGNAL_VARS macro and then have one component for each signal parameter, in the same order as the signal parameters are defined. The components will be named Param1, Param2, and so on.

Example 488

typedef struct {
SIGNAL_VARS
SDL_Integer Param1;
SDL_Boolean Param2;
} yPDef_sig;
typedef yPDef_sig *yPDP_sig;

These types would represent a signal sig(Integer, Boolean).

As all signals starts with the components defined in SIGNAL_VARS it is possible to type cast a pointer to a signal, to the xSignalNode type, if only the components in SIGNAL_VARS is to be accessed.

Allocation of Data Areas for Signals

In sctos.c there are two functions, xGetSignal and xReleaseSignal, where data areas for signal are handled:

xSignalNode xGetSignal(
xSignalIdNode SType,
SDL_PId Receiver,
SDL_PId Sender )

void xReleaseSignal( xSignalNode *S )

xGetSignal takes a reference to the SignalIdNode identifying the signal type and two PId values (sending and receiving process instance) and returns a signal instance. xGetSignal first looks in the avail list for the signal type (the component AvailSignalList in the SignalIdNode for the signal type) and reuses any available signal there. Only if the avail list is empty new memory is allocated. The component VarSize in the SignalIdNode for the signal type provides the size information needed to correctly allocate the yPDef_SignalName even though the type is unknown for the xGetSignal function.

The function xReleaseSignal takes the address of an xSignalNode pointer and returns the referenced signal to the avail list for the signal type. The xSignalNode pointer is then set to 0.

The function xGetSignal is used:

  • In generated code (output, set, reset)
  • In a number of places in the library:
    SDL_Create
    SDL_SimpleReset
    SDL_Nextstate (to handle continuous signals)
  • In the postmaster communication section and in the monitor to obtain signal instances.

The function xReleaseSignal is used by:

  • SDL_Nextstate
  • SDL_Stop, in both cases to release the signal that initiated the transition.

Overview of Output and Input of Signals

In this subsection the signal handling operation is only outlined. More details will be given in the section treating processes. See "Output and Input of Signals" .

Signal instances are sent using the function SDL_Output. That function takes a signal instance and inserts it into the input port of the receiving process instance.

If the receiver is not already in the ready queue (the queue containing the processes that can perform a transition, but which have not yet been scheduled to do so) and the current signal may cause an immediate transition, the process instance is inserted into the ready queue.

If the receiver is already in the ready queue or in a state where the current signal should be saved, the signal instance is just inserted into the input port.

If the signal instance can neither cause a transition nor should be saved, it is immediately discarded (the data area for the signal instance is returned to the avail list).

The input port is scanned during nextstate operations, according the rules of SDL, to find the next signal in the input port that can cause a transition. Signal instances may then be saved or discarded.

There is no specific input function, instead this behavior is distributed both in the runtime library and in the generated code. The signal instance that should cause the next transition to be executed is removed from the input port in the main loop (the scheduler), immediately before the PAD function for the current process is called. The PAD function is the function where the behavior of the process is implemented and is part of the generated code. The assignment of the signal parameters to local SDL variables is one of the first actions performed by the PAD function.

The signal instance that caused a transition is released and returned to the avail list in the nextstate or stop action that ends the current transition.

Timers and Operations on Timers

A timer with parameters is represented by a type definition, where the timer parameters are defined, in exactly the same way as for a signal definition, see "Data Structure Representing Signals and Timers" . At runtime, all timers that are set and where the timer time has not expired, are represented by a xTimerRec struct and a signal instance:

#define TIMER_VARS \
xSignalNode Pre; \
xSignalNode Suc; \
int Prio; \
SDL_PId Receiver; \
SDL_PId Sender; \
xSignalIdNode NameNode; \
GLOBALINSTID \
ENVCHANNEL \
SDL_Time TimerTime;

typedef xTimerRec *xTimerNode;

typedef struct xTimerStruct {
TIMER_VARS
} xTimerRec;

The TIMER_VARS is and must be identical to the SIGNAL_VARS macro, except for the TimerTime component last in the macro. A timer with parameters have yPDef_timername and yPDP_timername types in generated code exactly as a signal (see previous section), except that SIGNAL_VARS is replaced by TIMER_VARS.

During its life-time a timer have two different appearances. First it is a timer waiting for the timer time to expire. In that phase the timer is inserted in the xTimerQueue. When the timer time expires the timer becomes a signal and is inserted in the input port of the receiver just like any other signal. Due to the identical typedefs for xSignalRec and xTimerRec, there are no problems with type casting between xTimerNode and xSignalNode types.

When a timer is treated as a signal the components in the xTimerRec are used in the same ways as for a xSignalRec. While the timer is in the timer queue, the components are used as follows:

  • Pre and Suc are pointers used to link the xTimerRec into the timer queue (the queue of active timers, see below).
  • TimerTime is the time given in the Set operation.

The queue mentioned above, the timer queue for active timers is represented by the component xTimerQueue in the variable xSysD:

xTimerNode xTimerQueue;

The variable is initialized in the function xInitKernel in sctsdl.c. xTimerQueue is initialized it refers to the queue head of the timer queue.

The queue head is an extra element in the timer queue that does not represent a timer, but is introduced as it simplifies the algorithms for queue handling. The TimerTime component in the queue head is set to a very large time value (xSysD.xMaxTime).

The timer queue is thus a doubly linked list with a list head and it is sorted according to the timer times, so that the timer with lowest time is at the first position.

The xTimerRec structs are allocated and reused in the same way as signal.

From the SDL point of view, timers are handled in:

  • Timer definitions
  • Set and reset operations
  • Timer outputs.

The timer output is the event when the timer time has expired and the timer signal is sent. After that, a timer signal is treated as an ordinary signal. These operations are implemented as follows:

void SDL_Set(
SDL_Time T,
xSignalNode S )

This function, which represents the Set operation, takes the timer time and a signal instance as parameters. It first uses the signal instance to make an implicit reset (see reset operation below) It then updates the TimerTime component in S and inserts S into the timer queue at the correct position.

The SDL_Set operation is used in generated code, together with xGetSignal, in much the same way as SDL_Output. First a signal instance is created (by xGetSignal), then timer parameters are assigned their values, and finally the Set operation is performed (by SDL_Set).

void SDL_Reset( xSignalNode *TimerS )

void SDL_SimpleReset(
xPrsNode P,
xSignalIdNode TimerId )

Two functions are used to represent the SDL action reset. SDL_SimpleReset is used for timers without parameters and SDL_Reset for timers with parameters.

SDL_Reset uses the two functions xRemoveTimer and xRemoveTimerSignal to remove a timer in the timer queue and to remove a signal instance in the input port of the process. It then releases the signal instance given as parameter. This signal is only used to carry the parameter values given in the reset action.

The function SDL_SimpleReset is implemented in the same way as SDL_Reset, except that it creates its own signal instance (without parameters).

At a reset action the possibly found timer is removed from the timer queue and returned to the avail list. A found signal instance (in the input port) is removed from the input port and returned to the avail list for the current signal type.

static void SDL_OutputTimerSignal( xTimerNode T )

The SDL_OutputTimerSignal is called from the main loop (the scheduler) when the timer time has expired for the timer first in the timer queue. The corresponding signal instance is then sent.

SDL_OutputTimerSignal takes a pointer to an xTimerRec as parameter, removes it from the timer queue and sends as an ordinary output using the function SDL_Output.

It can be checked if timer is active by using a call to the function SDL_Active. This function is used in generated code to represent the SDL operator active.

SDL_Boolean SDL_Active (
xSignalIdNode TimerId,
xPrsNode P )

Note:

Only timers without parameters can be tested. This is a restriction in the Cadvanced/Cbasic SDL to C Compiler.

There is one more place where timers are handled. When a process instance performs a stop action all timers in the timer queue connected to this process instance are removed. This is performed by calling the function xRemoveTimer with the first parameter equal to 0.

Processes

Data Structure Representing Processes

A process instance is represented by two structs, an xLocalPIdRec and a struct containing both the general process data and the local variables and formal parameters of the process (yVDef_ProcessName), see also Figure 544. The reason for having both the -xLocalPIdRec and the yVDef_ProcessName will be discussed under "Create and Stop Operations" .

Figure 544 : Representation of a process instance

The corresponding type definitions, which can be found in scttypes.h, are:

#ifdef XPRSSENDER
#define XPRSSENDERCOMP SDL_PId Sender;
#else
#define XPRSSENDERCOMP
#endif

#ifdef XTRACE
#define XTRACEDEFAULTCOMP int Trace_Default;
#else
#define XTRACEDEFAULTCOMP
#endif

#ifdef XGRTRACE
#define XGRTRACECOMP int GRTrace;
#else
#define XGRTRACECOMP
#endif

#ifdef XMSCE
#define XMSCETRACECOMP int MSCETrace;
#else
#define XMSCETRACECOMP
#endif

#if defined(XMONITOR) || defined(XTRACE)
#define XINTRANSCOMP xbool InTransition;
#else
#define XINTRANSCOMP
#endif

#ifdef XMONITOR
#define XCALL_ADDR int CallAddress;
#else
#define XCALL_ADDR
#endif

#ifndef XNOUSEOFSERVICE
#define XSERVICE_COMP \
xSrvNode ActiveSrv; xSrvNode SrvList;
#else
#define XSERVICE_COMP
#endif

#define PROCESS_VARS \
xPrsNode Pre; \
xPrsNode Suc; \
int RestartAddress; \
xPrdNode ActivePrd; \
void (*RestartPAD) (xPrsNode VarP); \
XCALL_ADDR \
XSERVICE_COMP \
xPrsNode NextPrs; \
SDL_PId Self; \
xPrsIdNode NameNode; \
int State; \
xSignalNode Signal; \
xInputPortRec InputPort; \
SDL_PId Parent; \
SDL_PId Offspring; \
int BlockInstNumber; \
XSIGTYPE pREPLY_Waited_For; \
xSignalNode pREPLY_Signal; \
XPRSSENDERCOMP \
XTRACEDEFAULTCOMP \
XGRTRACECOMP \
XMSCETRACECOMP \
XINTRANSCOMP

typedef struct {
xPrsNode PrsP;
int InstNr;
int GlobalInstanceId;
} xLocalPIdRec;

typedef xLocalPIdRec *xLocalPIdNode;

typedef struct {
int GlobalNodeNr;
xLocalPIdNode LocalPId;
} SDL_PId;

typedef struct xPrsStruct *xPrsNode;

typedef struct xPrsStruct {
PROCESS_VARS
} xPrsRec;

A PId value is thus a struct containing two components:

  • The global node number
  • A pointer to a xLocalPIdRec struct.

The use of the global node number is discussed in the 57 Building an Application.

A xLocalPIdRec contains the following three components:

  • PrsP of type xPrsNode. This component is a pointer to the xPrsRec struct that is part of the representation of the process instance.
  • InstNr of type int. This is the instance number of the current process instance, which is used in the communication with the user in the monitor and in dynamic error messages.
  • GlobalInstanceId is used in MSCE traces to have a unique identification of the process instance.

A xPrsRec struct contains the following components described below. As each yVDef_ProcessName struct contains the PROCESS_VARS macro as first item, it is possible to cast pointer values between a pointer to xPrsRec and a pointer to a yVDef_ProcessName struct.

  • Pre and Suc of type xPrsNode. These components are used to link the process instance in the ready queue (see below).
  • RestartAddress of type int. This component is used to find the appropriate SDL symbol to continue execute from.
  • ActivePrd of type xPrdNode. This is a pointer to the xPrdRec that represents the currently executing procedure called from this process instance. The pointer is 0 if no procedure is currently called.
  • RestartPAD, which is a pointer to a PAD function. This component refers to the PAD function where to execute the sequence of SDL symbols. RestartPAD is used to handle inheritance between process types.
  • CallAddress of type int. This component contains the symbol number of the procedure call currently executed by this process.
  • ActiveSrv of type xSrvNode. This component contains a reference to the currently active service (or latest active service) in this process.
  • SrvList of type xSrvNode. This component contains a reference to the first service contained in this process. The component NextSrv in the struct representing a service can be used to find next active service in the process.
  • NextPrs of type xPrsNode. This component is used to link the process instance either in the active list or in the avail list for this process type. The start of these two lists are the components ActivePrsList and AvailPrsList in the IdNode representing the current process type.
  • Self of type SDL_PId. This is the PId value of the current process instance.
  • NameNode of type xPrsIdNode. This is a pointer to the PrsIdNode representing the current process or process instantiation.
  • State of type int. This component contains the int value used to representing the current state of the process instance.
  • Signal of type xSignalNode. This is a pointer to a signal instance. The referenced signal is the signal that will cause the next transition by the current process instance, or that caused the transition that is currently executed by the process instance.
  • InputPort of type xInputPortRec. This is the queue head in the doubly linked list that represents the input port of the process instance. The signals are linked in this list using the Pre and Suc components in the xSignalRec struct.
  • Parent of type SDL_PId. This is the PId value of the parent process (according to the rules of SDL). A static process instance has parent equal to NULL.
  • Offspring of type SDL_PId. This is the PId value of the latest created process instance (according to the rules of SDL). A process instance that has not created any processes has offspring equal to NULL.
  • BlockInstNumber of type int. If the process is part of a block instance set, this component indicates which of the blocks that the process belongs to.
  • pREPLY_Waited_For of type xSignalIdNode. When a process is waiting in the implicit state for the pREPLY signal in a RPC call, this components is used to store the IdNode for the expected pREPLY signal.
  • pREPLY_Signal of type xSignalNode. When a process receives a pCALL signal, i.e. accepts a RPC, it immediately creates the return signal, the pREPLY signal. This component is used to refer to this pREPLY signal until it is sent.
  • Sender of type SDL_PId. This component represents the SDL concept Sender.
  • Trace_Default of type int. This component contains the current value of the trace defined for the process instance.
  • GRTrace of type int. This component contains the current value of the GR trace defined for the process instance.
  • MSCETrace of type int. This component contains the current MSCE trace value for the process instance.
  • InTransition of type xbool. This component is true while the process is executing a transition and it is false while the process is waiting in a state. The monitor system needs this information to be able to print out relevant information.

The Ready Queue, Scheduling

The ready queue is a doubly linked list with a head. It contains the process instances that can execute an immediate transition, but which has not been allowed to complete that transition. Process instances are inserted into the ready queue during output operations and nextstate operations and are removed from the ready queue when they execute the nextstate or stop operation that ends the current transition. The head in the ready queue, which is an object in the queue that does not represent any process but is inserted only to simplify the queue operations, is referenced by the xSysD component:

xPrsNode xReadyQueue;

This component is initiated in the function xInitKernel and used throughout the runtime library to reference the ready queue.

Scheduling of events is performed by the function xMainLoop, which is called from the main function after the initialization is performed.

void xMainLoop()

The strategy to have all interesting queues (the ready queue, the timer queue, and the input ports) sorted in the correct order is used in the library. Sorting is thus performed when an object is inserted into a queue, which means that scheduling is a simple task: select the first object in the timer queue or in the ready queue and submit it for execution.

There are several versions of the body of the endless loop in the function xMainLoop, which are used for different combinations of compilation switches. When it comes to scheduling of transitions and timer outputs they all have the following outline:

while (1) {
if ( xTimerQueue->Suc->TimerTime <= SDL_Now() )
SDL_OutputTimerSignal( xTimerQueue->Suc );
else if ( xReadyQueue->Suc != xReadyQueue) {
xRemoveFromInputPort(xReadyQueue->Suc->Signal);
xReadyQueue->Suc->Sender =
xReadyQueue->Suc->Signal->Sender;
(*xReadyQueue->Suc->RestartPAD)(xReadyQueue->Suc);
}
}

or, in descriptive terms:

while (1) {
if ( there is a timer that has expired )
send the corresponding timer signal;
else if ( there is a process that can execute
a transition ) {
remove the signal causing the transition
from input port;
set up Sender in the process to Sender of
the signal;
execute the PAD function for the process;
}
}

The different versions of the main loop handle different combinations of compilation switches. Other actions necessary in the main loop are dependent of the compilation switches. Example of such actions are:

  • Handling of the monitor
  • Calling the xInEnv function
  • Handling real time or simulated time
  • Delay execution up to the next scheduled event
  • Handling enabling conditions and continuous signals that need to be recalculated.

Create and Stop Operations

A process instance is, while it is active, represented by the two structs:

  • xLocalPIdRec
  • The yVDef_ProcessName struct.

These two structs are dynamically allocated. A PId value is also a struct (not allocated) containing two components, GlobalNodeNr and LocalPId, where LocalPId is a pointer to the xLocalPIdRec. Figure 545 shows how the xLocalPIdRec and the yVDef_ProcessName structs representing a process instance are connected.

Figure 545 : A xLocalPIdRec and a yVDef_ProcessName
representing a Process instance

When a process instance performs a stop action, the memory used for the process instance should be reclaimed and it should be possible to reuse in subsequent create actions. After the stop action, old (invalid) PId values might however be stored in variables in other process instances.

If a signal is sent to such an old PId value, that is, to a stopped process instance, it should be possible to find and perform appropriate actions. If the complete representation of a process instance is reused then this will not be possible. There must therefore remain some little piece of information and thus some memory for each process instance that has ever existed. This is the purpose of the xLocalPIdRec. These structs will never be reused. Instead the following (see Figure 546) will happen when the process instance in Figure 545 performs a stop action.

Figure 546 : The memory structure after the process in
Figure 545 has performed a stop action

A new xLocalPIdRec is allocated and its PrsP references the yVDef_ProcessName (InstNr is 0). The Self component in the yVDef_ProcessName is changed to reference this new xLocalPIdRec. The old xLocalPIdRec still references the yVDef_ProcessName. The yVDef_ProcessName is entered into the avail list for this process type.

To reuse the data area for a process instance at a create operation it is only necessary to remove the yVDef_ProcessName from the avail list and update the InstNr component in the xLocalPIdRec referenced by Self.

Using this somewhat complicated structure to represent process instances allows a simple test to see if a PId value refers to an active or a stopped instance:

If P is a PId variable then the following expression:

P.LocalPId == P.LocalPId->PrsP->Self.LocalPId

is true if the process instance is active and false if it is stopped.

The basic behavior of the create and stop operations is performed by the functions SDL_Create and SDL_Stop.

void SDL_Create(
xSignalNode StartUpSig,
xPrsIdNode PrsId )

void SDL_Stop( xPrsNode PrsP )

To create a process instance takes three steps performed in generated code:

  1. Call xGetSignal to obtain the start-up signal.
  2. Assign the actual process parameters to the start up signal parameters.
  3. Call SDL_Create with the start-up signal as parameter, together with the PrsIdNode representing the process to be created.

In xGetProcess the process instance is removed from the avail list of the process instance set (the component AvailPrsList in the PrsIdNode representing the process instance set), or if the avail list is empty new memory is allocated.

The process instance is linked into the list of active process instances (the component ActivePrsList in the PrsIdNode representing the process instance set). Both the avail list and the active list are single linked lists (without a head) using the component NextPrs in the yVDef_ProcessName struct as link.

To have an equal treatment of the initial transition and other transitions, the start state is implemented as an ordinary state with the name "start state" It is represented by 0. To execute the initial transition a "startup" signal is sent to the process. The start state can thus be seen as a state with one input of the startup signal and with save for all other signals. This implementation is completely transparent in the monitor, where startup signals are never shown in any way.

Note:

The actual values for FPARs are passed in the startup signal.

Two IdNodes that are not part of the symbol table tree are created to represent a start state and a startup signal.

xStateIdNode xStartStateId;
xSignalIdNode xStartUpSignalId;

These xSysD components are initialized in the function xInitSymbolTable, which is part of sctsdl.c.

At a stop operation the function SDL_Stop is called. This function will release the signal that caused the current transition and all other signals in the input port. It will also remove all timers in the timer queue that are connected to this process instance by calling xRemoveTimer with the first parameter equal to 0. It then removes the process executing the stop operation from the ready queue and from the active list of the process type and returns the memory to the avail list of the current process instance set.

Output and Input of Signals

There are three actions performed in generated code to send a signal. First xGetSignal is called to obtain a data area that represents the signal instance, then the signal parameters are assigned their values and finally the function SDL_Output is called to actually send the signal. First in the SDL_Output function there are a number of dynamic tests (check if receiver in TO-clause is not NULL and not stopped, check if there is a path to the receiver). If the output does not contain any TO-clause and the Cadvanced/Cbasic SDL to C Compiler has not been able to calculate the receiver, the xFindReceiver function is called to calculate the receiver according to the rules of SDL.

Next, in SDL_Output signals to the environment are handled. Three cases can be identified here:

  1. The environment function xOutEnv is called.
  2. The corresponding function that sends signals via the SDL suite communication mechanism (xOutPM) is called.
  3. The signal is inserted into the input port of the process representing the environment (xEnv).

Finally, internal signals in the SDL system are treated. Here also three cases can be identified (how this is evaluated is described last in this subsection):

  1. The signal can cause an immediate transition by the receiver.
  2. The signal should be saved.
  3. The signal should be immediately discarded.

If the signal can cause an immediate transition, the signal is inserted into the input port of the receiver, and the receiving process instance is inserted into the ready queue.

If the signal should be saved, the signal is just inserted into the input port of the receiver.

If the signal should be discarded, the function xReleaseSignal is called to reused the data area for the signal.

When a signal is identified to be the signal that should cause the next transition by the current process instance (at an Output or Nextstate operation), the component Signal in the yVDef_ProcessName for the process is set to refer to the signal. The signal is still part of the input port list.

When the transition is to be executed, the signal is removed from the input port in the main loop (see "The Ready Queue, Scheduling" ) immediately before the PAD function for the process is called.

First in the PAD function, the parameters of the signal are copied to the local variables according to the input statement. In the ending Nextstate or Stop operation of the transition the signal instance is returned to the avail list.

Evaluating How To Handle a Received Signal

There are two places in the run-time kernel where it is necessary to evaluate how to handle signals (input, save, discard,...):

  • At an Output operation to a currently idle process.
  • At a Nextstate operation, when the process have signals in the input port.

This calculation is implemented in the run-time kernel function xFindInputAction.

typedef unsigned char xInputAction;
#define xDiscard (xInputAction)0
#define xInput (xInputAction)1
#define xSave (xInputAction)2
#define xEnablCond (xInputAction)3
#define xPrioInput (xInputAction)4

static xInputAction xFindInputAction(
xSignalNode SignalId,
xPrsNode VarP,
xbool CheckPrioInput )

The parameters of this function is:

  • SignalId, which is a pointer to a signal.
  • VarP, which is a pointer to a process instance.
  • CheckPrioInput, which is a boolean value indicating is the function should check only for priority inputs or for ordinary inputs.

As a result the function should return:

  • The action that should be performed for this signal (input, save,...), taking all information about this process into account, like inheritance between processes, virtual - redefined transitions and so on.
  • If the function result is xInput or xPrioInput, then the RestartPAD and RestartAddr components in the VarP struct should be updated with information about where this input can be found.

After this last update the correct transition can be started by the scheduler by just calling the function referenced by RestartPAD, which the as first action performs switch RestartAddr and starts execute the input symbol.

Figure 547 : Data structure used to evaluate the xFindInputAction

The algorithm to find the InputAction, the RestartAddr, and the RestartPAD is as follows:

  1. Let ProcessId become yVarP->NameNode and let StateId become ProcessId->StateList[yVarP->State].
  2. In ProcessId->SignalSet find the index (Index) where SignalId->NameNode is found. If the signal is not found, this signal is not in the signal set of the process, and the algorithm terminates returning the result xDiscard.
  3. StateId->SignalHandlArray[Index] now gives the action to be performed. If this value is xEnablCond, then the function StateId->EnablCond_Function is called. This function returns either xInput or xSave.
  4. If the result from step 3 is xInput, the algorithm terminates returning this value. yVarP->RestartAddr is also updated to
    StateId->InputRef[Index], while yVarP->RestartPAD is updated to ProcessId->PAD_Function.
    If the result from step 3 is xSave, the algorithm terminates returning this value.
    If the result from step 3 is xDiscard and ProcessId->Super equal to NULL, then the algorithm terminates returning this value.
    If the result from step 3 is xDiscard and ProcessId->Super not equal to NULL, then we are in a process type that inherits from another process type. We then have to perform step 2 - 4 again, with ProcessId assigned the value ProcessId->Super and StateId assigned the value StateId->Super.

Nextstate Operations

The nextstate operation is implemented by the SDL_Nextstate function, where the following actions are performed:

  1. The signal that caused the current transition (component Signal in the yVDef_ProcessName) is released and the state variable (component State in the yVDef_ProcessName) is updated to the new state.
  2. Then the input port of the process is scanned for a signal that can cause a transition. During the scan signals might be saved or discarded until a signal specified in an input is found. Priority inputs are treated according to the rules of SDL.
  3. If no signal that can cause a transition is found, a check is made if any continuous signal can cause a transition (see "Enabling Conditions and Continuous Signals" ). The process is thereafter removed from the ready queue.
  4. If any signal (or continuous signal) can cause a transition then the process is re-inserted into the ready queue again at a position determined by its priority, else if the new state contains any continuous signal or enabling condition with an expression that might change its value during the time the process is in the state (view, import...), the process is inserted into the check list (see also "Enabling Conditions and Continuous Signals" ).

Decision and Task Operations

Decision and Task operations are implemented in generated code, except for the Trace-functions implemented in the sctutil.c and sctmon.c files and for informal and any decisions that uses some support functions in sctmon.c. A Decision is implemented as a C if-statement, while the assignments in a Task are implemented as assignments or function calls in C.

Compound Statements

A compound statement without variable declarations is translated just to the sequence of action it contains, while a compound statement with variable declarations is translated in the same way as an SDL procedure (without parameters). Statements within a compound statement are translated according to the normal rules. The new statement types in compound statements are translated as:

  • if in SDL is translated to if in C
  • decision in compound statements is translated as ordinary decisions.
  • for loops, continue, and break are all translated using goto in C.

Enabling Conditions and Continuous Signals

The expressions involved in continuous signals and enabling conditions are implemented in generated code in functions called yCont_StateName and yEnab_StateName. These functions are generated for each state containing continuous signals respectively enabling conditions. The functions are referenced through the components ContSig_Function and EnablCond_Function in the StateIdNode for the state. These components are 0 if no corresponding functions are generated.

The EnablCond_Functions are called from the function xFindInputAction, which is called from SDL_Output and SDL_Nextstate. If the enabling condition expression for the current signal is true then xInput is returned else xSave is returned. This information is then used to determine how to handle the signal in this state.

The ContSig_Functions are called from SDL_Nextstate, if the component ContSig_Function is not 0 and no signal that can cause an immediate transition is found during the input port scan. A ContSig_Function has the following prototype:

void ContSig_Function_Name (
void *, int *, xIdNode *, int *);

where the first parameter is the pointer to the yVDef_ProcessName. The remaining parameters are all out parameters; the second contains the priority of the continuous signal with highest priority (=lowest value) that has an expression with the value true. Otherwise <0 is returned here. The third and fourth is only defined the second parameter >=0; the third is the IdNode for the process/procedure where the actual continuous signal can be found and the fourth is the RestartAddress connected to this continuous signal.

If a continuous signal expression with value true is found, a signal instance representing the continuous signal is created and inserted in the input port, and is thereafter treated as an ordinary signal. The signal type is continuous signal and is represented by an SignalIdNode (referenced by the variable xContSigId).

The check list is a list that contains the processes that wait in a state where enabling conditions or continuous signals need to be repeatedly recalculated.

A process is inserted into the check list if:

  1. It enters a state containing enabling conditions and/or continuous signals and
  2. No signal or continuous signal can cause an immediate transition and
  3. One or several of the expressions in the enabling conditions or continuous signals can change its value while the process is in the state (view, import, now, ...)

The component StateProperties in the StateIdNode reflects if any such expression is present in the state.

The check list is represented by the xSysD component:

xPrsNode xCheckList;

The behavior of enabling conditions and continuous signals is in SDL modeled by letting the process repeatedly send signals to itself, thereby to repeatedly entering the current state. In the implementation chosen here, nextstate operations are performed "behind the scene" for all processes in the check list directly after a call to a PAD function is completed, that is directly after a transition is ended and directly after a timer output. This is performed by calling the function xCheckCheckList in the main loop of the program.

View and Reveal

A view expression is part of an expression in generated code and implemented by calling the function SDL_View.

void * SDL_View (
xViewListRec *VList,
SDL_PId P,
xbool IsDefP,
xPrsNode ViewingPrs,
char * Reveal_Var
int SortSize);

  • VList is a list of all revealed variables in this block.
  • P is the PId expression given in the view statement.
  • IsDefP is 1 is the view expression contained a PId value, 0 otherwise.
  • ViewingPrs is the process instance performing the view operation.
  • Reveal_Var is the name of the revealed variable as a string. The Reveal_Var parameter is only used in error messages and is remove under certain conditions.
  • SortSize is the size of the data type of the viewed variable.

The SDL_View function performs a test that the view expression is not NULL, refers to a process in the environment, or to a stopped process instance. If no errors are found the address of the revealed variable is returned as result from the SDL_View function. Otherwise the address of a variable containing only zeros is returned.

Import, Export, and Remote Variables

For an exported variable there are two components in the yVDef_ProcessName struct. One for the current value of the variable and one for the currently exported value of the variable. For each exported variable there will also be a struct that can be linked into a list in the corresponding RemoteVarIdNode. This list is then used to find a suitable exporter of a variable in an import action.

An export action is a simple operation. The current value of the variable is copied to the component representing the exported value. This is performed in generated code.

An import action is more complicated. It involves mainly a call of the function xGetExportAddr:

void * xGetExportAddr (
xRemoteVarIdNode RemoteVarNode,
SDL_PId P,
xbool IsDefP,
xPrsNode Importer )

RemoteVarNode is a reference to the RemoteVarIdNode representing the remote variable (implicit or explicit), P is the PId expression given in the import action and IsDef is 0 or 1 depending on if any PId expression was given in the import action or not, Importer is the importing process instance. The xGetExportAddr will check the legality of the import action and will, if no PId expression is given, calculate which process it should be imported from.

If no errors are found the function will return the address where the exported value can be found. This address is then casted to the correct type (in generated code) and the value is obtained. If no process possible to import from is found, the address of a variable containing only zeros is returned by the xGetExportAddr function.

Note:

The strategy for import actions is in one sense not equal to the model for import given in the SDL recommendation. An import action is in the recommendation modeled as a signal sent from the importing process to the exporting process asking for the exported value, and a signal with this value sent back again. The synchronization effects by this signal communication is lost in the implementation model we have chosen. Instead our model is much easier and faster and the primary part of the import action, to obtain the exported value, is the same.

Services

Data Structure Representing Services

A service is represented by a struct type. The xSrvRec struct defined in scttypes.h, is, just like xPrsRec for processes, a struct containing general information about a service, while the parameters and variables of the service are defined in generated code in the same way as for processes.

In scttypes.h the following types concerning procedures can be found:

#ifdef XMONITOR
#define XCALL_ADDR int CallAddress;
#else
#define XCALL_ADDR
#endif

#define SERVICE_VARS \
xSrvNode NextSrv; \
xPrsNode ContainerPrs; \
int RestartAddress; \
xPrdNode ActivePrd; \
void (*RestartPAD) (xPrsNode VarP); \
XCALL_ADDR \
xSrvIdNode NameNode; \
int State; \
XSIGTYPE pREPLY_Waited_For; \
xSignalNode pREPLY_Signal; \
XINTRANSCOMP
#ifndef XNOUSEOFSERVICE
typedef struct xSrvStruct *xSrvNode;
#endif

#ifndef XNOUSEOFSERVICE
typedef struct xSrvStruct {
SERVICE_VARS
} xSrvRec;
#endif

In generated code yVDef_ProcedureName structs are defined according to the following:

typedef struct {
SERVICE_VARS
components for FPAR and DCL
} yVDef_ServiceName;

The components in the xSrvRec are used as follows:

  • NextSrv of type xSrvNode. Reference to next service contained in this process.
  • ContainerPrs of type xPrsNode. Reference to the process instance containing this service.
  • RestartAddress of type int. This component is used to find the appropriate SDL symbol to continue execution from.
  • ActivePrd of type xPrdNode. This is a pointer to the xPrdRec that represents the currently executing procedure called from this service instance. The pointer is 0 if no procedure is currently called.
  • RestartPAD, which is a pointer to a PAD function. This component refers to the PAD function where to execute the sequence of SDL symbols. RestartPAD is used to handle inheritance between service types.
  • CallAddress of type int. This component contains the symbol number of the procedure call performed from this procedure (if any).
  • NameNode of type xSrvIdNode. This is a pointer to the IdNode representing the service or service instantiation.
  • State of type int. This component contains the int value used to represent the current state of the service instance.
  • pREPLY_Waited_For of type xSignalIdNode. When a service is waiting in the implicit state for the pREPLY signal in a RPC call, this components is used to store the IdNode for the expected pREPLY signal.
  • pREPLY_Signal of type xSignalNode. When a service receives a pCALL signal, i.e. accepts a RPC, it immediately creates the return signal, the pREPLY signal. This component is used to refer to this pREPLY signal until it is sent.
  • InTransition of type xbool. This component is true while the service is executing a transition and it is false while the service is waiting in a state. The monitor system needs this information to be able to print out relevant information.

Executing Transitions in Services

From the scheduler's point view, it is not of interest if a process contains services or not. It is still the process instance that is scheduled in the ready queue and the PAD function of the process that is to be called to execute a transition. The PAD function for a process containing services performs three different actions:

  • Assign default value to variables declared at the process level
  • Create one service instance for each service or service instantiation in the process.
  • Calls the proper PAD function for a service to execute transitions.

The structure for a PAD function for a process with services are as follows:

YPAD_FUNCTION(yPAD_z00_P1)
{
YPAD_YSVARP
YPAD_YVARP(yVDef_z00_P1)
YPRSNAME_VAR("P1")
LOOP_LABEL_SERVICEDECOMP
CALL_SERVICE

/*-----
* Initialization (no START symbol)
------*/
BEGIN_START_TRANSITION(yPDef_z00_P1)
yAssF_SDL_Integer(yVarP->z002_Global,
SDL_INTEGER_LIT(10), XASS);
START_SERVICES
}

where LOOP_LABEL_SERVICEDECOMP and BEGIN_START_TARNSITION are empty macros, i.e. expanded to no code. The yAss_SDL_Integer statement in an assignment of a default value to a process variable.

The macro CALL_SERVICE is expanded to:

if (yVarP->ActiveSrv != (xSrvNode)0) {
(*yVarP->ActiveSrv->RestartPAD)(VarP);
return; \
}

that is to a call of the PAD function of service reference by ActiveSrv.

The macro START_SERVICE is expanded to a call to the function xStart_Services, which can be found in sctsdl.c.The function creates the service instances, sets up the ActiveSrv pointer for the process to the first service, and then schedules the process for a new transition. This means that the next action performed by the system will be the start transition by the first service instance. When the first service executes a nextstate or stop action in the end of its start transition, the process will be scheduled again to execute the start transition of the second service, and so on until all services in the process has executed its start transitions.

For ordinary transitions, i.e. reception of a signal, it is obvious from the code above that the ActiveSrv pointer is essential. It should refer to the service instance that is to be executed. When a signal is to be received by a process, it is the function xFindInputAction (in sctsdl.c) that determines how to handle the signal and if it is to be received, where is the code for that transition. This function now also determines and sets up the ActiveSrv pointer.

Procedures

Data Structure Representing Procedures

A procedure is represented by a struct type. The xPrdRec struct defined in scttypes.h, is, just like xPrsRec for processes, a struct containing general information about a procedure, while the parameters and variables of the procedure are defined in generated code in the same way as for processes.

In scttypes.h the following types concerning procedures can be found:

#define PROCEDURE_VARS \
xPrdIdNode NameNode; \
xPrdNode StaticFather; \
xPrdNode DynamicFather; \
int RestartAddress; \
XCALL_ADDR \
void (*RestartPAD) (xPrsNode VarP); \
xSignalNode pREPLY_Signal; \
int State;

typedef struct xPrdStruct *xPrdNode;

typedef struct xPrdStruct {
PROCEDURE_VARS
} xPrdRec;

In generated code yVDef_ProcedureName structs are defined according to the following:

typedef struct {
PROCEDURE_VARS
components for FPAR and DCL
} yVDef_ProcedureName;

The components in the xPrdRec are used as follows:

  • NameNode of type xPrdIdNode. This is a pointer to the IdNode representing the procedure type.
  • StaticFather of type xPrdNode. This is a pointer that represents the scope hierarchy of procedures (and the process at the top), which is used when a procedure instance refers to non-local variables. An example is shown in Figure 548. StaticFather == 0 means that the static father is the process.
  • DynamicFather of type xPrdNode. This is a pointer that represents that this procedure is called by the referenced procedure. DynamicFather == 0 means that this procedure was called from the process. This component is also used to link the xPrdRec in the avail list for the procedure type.
  • RestartAddress of type int. This component is used to find the appropriate SDL symbol to continue execution from.
  • CallAddress of type int. This component contains the symbol number of the procedure call performed from this procedure (if any).
  • RestartPRD is a pointer to a procedure function. This component refers to the PRD function where to execute the next sequence of SDL symbols. RestartPRD is used to handle inheritance between procedures.
  • pREPLY_Signal of type xSignalNode. When a process receives a pCALL signal, i.e. accepts a RPC, it immediately creates the return signal, the pREPLY signal. This component is used to refer to this pREPLY signal until it is sent.
  • State of type int. This is the value representing the current state of the procedure instance.

In Figure 548 an example of the structure of yVDef_ProcedureName after four nested procedure calls are presented. Note that procedure Q is declared in the process, procedure R and S in Q and T in S.

Figure 548 : Structure of yVDef_ProcedureName
after four nested procedure calls

The SDL procedures are partly implemented using C functions and partly using the structure shown above. Each SDL procedure is represented by a C function, which is called to execute actions defined in the procedure. This function corresponds to the PAD function for processes. The formal parameters and the variables are however implemented using a struct defined in generated code. The procedure stack for nested procedure calls is implemented using the components StaticFather and DynamicFather, and does not use the C function stack.

Calling and Returning from Procedures

Procedure calls and procedure returns are handled by three functions, one handling allocation of the data areas for procedures:

xPrdNode xGetPrd( xPrdIdNode PrdId )

and two functions called from generated code at a procedure call and a procedure return:

void xAddPrdCall(
xPrdNode R,
xPrsNode VarP,
int StaticFatherLevel,
int RestartAddress )

void xReleasePrd (xPrsNode VarP)

A procedure call in SDL is in C represented by the following steps:

  1. Calling xGetPrd to obtain a data area for the procedure.
  2. Assigning procedure parameters to the data area.
  3. Calling xAddPrdCall to link the procedure into the static and dynamic chains.
  4. Calling the C function modeling the SDL procedure, i.e. the yProcedureName function.

The parameters to xAddPrdCall are as follows:

  • R. A reference to the xPrdNode obtained from the call of xGetPrd.
  • VarP. A reference to the yVDef_ProcessName, i.e. the data area for variables and parameters of the process (even if it is a procedure that performed the procedure call).
  • StaticFatherLevel. This is the difference in declaration levels between the caller and the called procedure. This information is used to set up the StaticFather component correctly.
  • RestartAddress. This is the symbol number of the SDL symbol directly after the procedure call. The symbol number is the switch case label generated for all symbols.

The xGetPrd returns a pointer to an xPrdRec, which can then be used to assign the parameter values directly to the components in the data area representing the formal parameters and variables of the procedure. Note that IN/OUT parameters are represented as addresses in this struct.

A procedure return is in generated code represented by calling the xReleasePrd followed by return 0, whereby the function representing the behavior of the SDL procedure is left.

The function representing the behavior of the SDL procedure is returned in two main situations:

  • When an SDL Return is reached (the function returns 0)
  • When a Nextstate is reached (the function returns 1).

If 0 is returned then the execution should continue with the next SDL symbol after the procedure call, while if 1 is returned the execution of the process instance should be terminated and the scheduler (main loop) should take control. This could mean that a number of nested SDL procedure calls should be terminated.

To continue to execute at the correct symbol when a procedure should be resumed after a nextstate operation, the following code is introduced in the PAD function for processes containing procedure calls:

while ( yVarP->ActivePrd != (xPrdNode)0 )
if ((*yVarP->ActivePrd->RestartPRD)(VarP))
return;

This means that uncompleted procedures are resumed one after one from the bottom of the procedure stack, until all procedures are completed or until one of them returns 1, i.e. executes a nextstate operation, at which the process is left for the scheduler again.

Channels and Signal Routes

The ChannelIdNodes for channels, signal routes, and gates are used in the functions xFindReceiver and xIsPath, which are both called from SDL_Output, to find the receiving process when there is no TO clause in the Output statement, respectively to check that there is a path to the receiver in the case of a TO clause in the Output statement. In both cases the paths built up using the ToId components in the IdNodes for processes, channels and signal routes are followed. To show the structure of these paths we use the small SDL system given in Figure 549.

Figure 549 : A small SDL system

During the initialization of the system, the symbol table is built up. The part of the symbol table starting with the system will then have the structure outlined in Figure 550. As we can see in this example the declarations in the SDL system are directly reflected by IdNodes.

Note:

Each channel and signal route is represented by two IdNodes, one for each direction. This is also true for an unidirectional channel or signal route. In this case the signal set will be empty for the unused direction.

Figure 550 : The symbol table tree for the system in Figure 549

.

Each IdNode representing a process, a signal route, or a channel will have a component ToId. A ToId component is an address to an array of references to IdNodes. The size of this array is dependent on the number of items this object is connected to. A process that has three outgoing signal routes will have a ToId array which can represent three pointers plus an ending 0 pointer.

In the example in Figure 549 and Figure 550 there is no branching, so all ToId arrays will be of the size necessary for two pointers. Figure 551 shows how the IdNodes for the processes, signal routes and channels are connected to form paths, using the components ToId. In this case only simple paths are found (one from P1, via SR1, C, SR2, to P2, and one in the reverse direction). The generalization of this structure to handle branches is straightforward and discussed in the previous paragraph.

Figure 551 : The connection of ToId for the system in
Figure 549 and Figure 550

The Type Concept in SDL-92

The probably most important new feature in SDL-92 is the introduction of the object oriented features, such as TYPE, INHERITS, VIRTUAL, and REDEFINED. Here we start by discussing process types.

For each process type the Cadvanced/Cbasic SDL to C Compiler will generate:

  • a PrsIdNode
  • a PAD function
  • a yVDef_ProcessName struct.

In the PrsIdNode there is one component (Super) that will refer to the PrsIdNode for the process type inherited by this process type. As sons to a PrsIdNode, IdNodes for declaration that are common for all instantiation of the process type can be found. Examples of such IdNodes are: nodes for variables, formal parameters, signals, timers, procedures, states, newtypes, and syntypes. Any typedefs or help functions for such units are also treated in the process type.

The PAD function will be independent of the PAD function for a inherited type, each PAD function just implementing the action described in its process type.

A yVDef_ProcessName struct will on the other hand include all variables and formal parameters from the top of the inheritance chain and downwards. Example:

process type P1;
fpar f1 integer;
dcl d1 integer;
...
endprocess;

process type P2 inherits P1;
fpar f2 integer;
dcl d2 integer;
...
endprocess;

This will generate the following principle yVDef_... structs:

typedef struct {
PROCESS_VARS
SDL_Integer f1;
SDL_Integer d1;
} yVDef_P1;

typedef struct {
PROCESS_VARS
SDL_Integer f1;
SDL_Integer d1;
SDL_Integer f2;
SDL_Integer d2;
} yVDef_P2;

A pointer to yVDef_P2 can thus be casted to a pointer to yVDef_P1, if only the common component (in PROCESS_VARS) or the variables in P1 is to be accessed. This possibility is used every time the PAD function for an inherited process type is called.

Each process instantiation will all be implemented as a xPrsIdNode. The Super component in such an object refers to the process type that is instantiated. No PAD function or yVDef_... struct will be generated. As sons to the PrsIdNode for a process instantiation, only such object are inserted that are different in different instantiations. For a process instantiation this is the gates. For other types of information the process instantiation uses the information given for its process type.

A very similar structure when it comes to IdNodes generated for block types and block instantiations are used by the code generator. There will be a BlockIdNode for both a block type and for a block instantiation. As sons to a block type, nodes that are the same in each block instantiation can be found (example: signal, newtype, syntype, block type, process type, procedure). As sons to a block instantiation, nodes that are needs to be represented in each block instantiation can be found (example: block instantiation, process instantiation, channel, signal route, gate, remote definitions).

Note:

A block or process (according to SDL-88), that is contained in a block type or a system type, is translated as if it was a type and instantiation at the same place.

A way to look at the structure of IdNodes in a particular system is to use the command Symboltable in the monitor system. This command prints the IdNode structure as an indented list of objects.


Allocating Dynamic Memory

Introduction

This section deals with the allocation and deallocation of dynamic memory.

Note:

This information is only valid when the Master Library is used. The OS integrations might have different strategies for memory allocation.

Information is provided about the following topics:

  • Explanation about how dynamic memory is allocated and reused (deallocation and avail lists)
  • How to estimate the total need of dynamic memory for an application.

Dynamic memory is used for a number of objects in a run-time model for applications generated by the Cadvanced/Cbasic SDL to C Compiler. These objects are:

  • Process instances
  • Signal and timer instances
  • Procedure instances
  • Charstring, Octet_string, Bit_string, and Object_identifer variables and variables of String, Bag, general Array, and general Powerset types.
  • Variables of other user-defined data types, where the user has decided to use dynamic memory.

To help to estimate the need for memory for an application we will give information about the size of these objects and about how many of the objects are created. The size information given is true for generated applications, that is, ones that do not, for example, contain the monitor. The type definitions given are stripped of components that will not be part of an application. The full definitions may be found in the file scttypes.h.

Processes

Each process instance is represented by two structs that will be allocated on the heap. In scttypes.h the type xLocalPIdRec is defined and in generated code yVDef_ProcessName structs are defined:

typedef struct {
xPrsNode PrsP;
} xLocalPIdRec;

typedef struct {
xPrsNode Pre;
xPrsNode Suc;
int RestartAddress;
xPrdNode ActivePrd;
void (*RestartPAD) (xPrsNode VarP);
#ifndef XNOUSEOFSERVICE
xSrvNode ActiveSrv;
xSrvNode SrvList;
#endif
xPrsNode NextPrs;
SDL_PId Self;
xPrsIdNode NameNode;
int State;
xSignalNode Signal;
xInputPortRec InputPort;
SDL_PId Parent;
SDL_PId Offspring;
int BlockInstNumber;
xSignalIdNode pREPLY_Waited_For;
xSignalNode pREPLY_Signal;

/* variables and formal parameters in the
process */
} yVDef_ProcessName;

To calculate the size of the structs above it is necessary to know more about the components in the structs. The types xPrsNode, xPrdNode, xSignalNode, xPrsIdNode, xStateIdNode, and xSignalIdNode are all pointers, while SDL_PId is a struct containing an int and a pointer. The xInputPortRec is a struct with two pointers and one int.

This means that it is possible to calculate the size of the xLocalPIdRec and the xPrsRec struct using the following formulas, if the compiler does not use any strange alignment rules:

The size of xPrsRec can be reduced by 2 x sizeof (address) if the code is compiled with the XNOUSEOFSERVICE flag. Then, of course, the SDL concept service cannot be used. The size of yVDef_ProcessName is the size of the xPrsRec plus the size of the variables and parameters in the process. Any overhead introduced by the C system should also be added. The size of the formal parameter and variables is of course dependent on the declarations in the process. The translation rules for SDL types, both predefined and user defined, can be found in 56 The Cadvanced/Cbasic SDL to C Compiler.

For each process instance set in the system the following number of structs of a different kind will be allocated:

  • There will be one xLocalPIdRec for each process instance created. These structs will not be reused, as they serve as identification of process instances that have existed (see also optimizations below).
  • There will be as many yVDef_ProcessName structs as the maximum concurrently executing process instances of the process instance set (maximum during the complete execution of the program).

The yVDef_ProcessName structs are reused by having an avail list where this struct is placed when the process instance it represents perform a stop action. There is one avail list for each process type. When a process instance should be created, the runtime library first looks at the avail list and reuses an item from the list. Only if the avail list is empty new memory is allocated.

Compilation switch XPRSOPT

If the compilation switch XPRSOPT is defined then:

  • xLocalPIdRecs are reused together with the xPrsRecs.
  • xLocalPIdRecs contain an additional int component.

Services

Services are handled very similar to processes. The following struct type are allocated for each service instance.

typedef struct xSrvStruct {
xSrvNode NextSrv;
xPrsNode ContainerPrs;
int RestartAddress;
xPrdNode ActivePrd;
void (*RestartPAD) (xPrsNode VarP);
xSrvIdNode NameNode;
int State;
XSIGTYPE pREPLY_Waited_For;
xSignalNode pREPLY_Signal;
} xSrvRec;

This means that:

The size of yVDef_ServiceName is the size of the xSrvRec plus the size of the variables in the service. yVDef_ServiceName struct are reused in the same way as for processes (see previous section).

Signals

Signals are handled in much the same way as processes. A signal instance is represented by one struct (in generated code generated).

typedef struct {
xSignalNode Pre;
xSignalNode Suc;
int Prio;
SDL_PId Receiver;
SDL_PId Sender;
xIdNode NameNode;

/* Signal parameters */
} yPDef_SignalName;

This struct type contains one component for each signal parameter. The component types will be the translated version of the SDL types of the parameters.

This means that it is possible can calculate the size of a xSignalRec, which is the same as a struct for a signal without parameters, using the following formula:

The size of a yPDef_SignalName struct is thus equal to the size of the xSignalRec plus the size of the parameters. The translation rules for SDL types, both the predefined and user defined, can be found in 56 The Cadvanced/Cbasic SDL to C Compiler.

For each signal type in the system the following number of data areas will be allocated:

  • There will be as many yPDef_SignalName struct as the maximum number of signals (during the complete execution of the program) of the signal type that are sent but not yet received in an input operation.

The yPDef_SignalName struct is reused by having an avail list, where the struct is placed when the signal instance they represent is received. The exact point where the signal instance is returned to the avail list is when the transition caused by the signal instance is ended by a nextstate or stop action. There is one avail list for each signal type. When a signal instance should be created, for example during an output operation, the runtime library first looks at the avail list and reuses an item from this list. Only if the avail list is empty new memory is allocated.

Note:

There is one common avail list for all signals without parameters.

Timers

The memory needed for timers can be calculated in the same way as for signals with one exception, each timer contains an extra SDL_Time component, i.e. two extra 32-bit integers.

Procedures

Procedures and processes have much in common in terms of memory allocation. A procedure is, during the time it exists from call to return, represented by a struct; the yVDef_ProcedureName.

typedef struct {
xPrdIdNode NameNode;
xPrdNode StaticFather;
xPrdNode DynamicFather;
int RestartAddress;
int (*RestartPRD) (xPrsNode VarP);
xSignalNode pREPLY_Signal;
int State;

/* Formal parameters and variables */
} yVDef_ProcedureName;

The struct type contains one component for each formal parameter or variable. The component types will be the translated version of the SDL types of the parameters, except for an IN/OUT parameter which is represented as an address.

The size of the xPrdRec struct (which is the same as a procedure without variables and formal parameters) can be calculated using the following formula:

The size of a yVDef_ProcedureName struct is the size of the xPrdRec plus the size of the formal parameter and variables defined in the procedure. The translation rules for SDL types, both the predefined and user defined can be found in 56 The Cadvanced/Cbasic SDL to C Compiler.

For each type of procedure in the system the following number of data areas will be allocated:

  • There will be as many yVDef_ProcedureName structs as the maximum number of concurrent calls (during the complete execution of the program) of the procedure. Concurrent calls occur both when a procedure calls itself recursively within one process instance, and when several process instances of the same process type calls the same procedure during overlapping times.

The yVDef_ProcedureName struct is reused by having an avail list, where this two struct is placed when the procedure instance executes a return action. There is one avail list for each procedure type. When a procedure instance should be created, that is, at a call operation, the runtime library first looks at the avail list and reuses an item in the list. Only if the avail list is empty new memory is allocated.

Data types

The predefined SDL type charstring is implemented as char * in C and thus requires dynamic memory allocation. The predefined data types Bit_string, Octet_string, and Object_identifier are also implemented using dynamic memory.

The implementation of the SDL sorts Charstring, Bit_string, Octet_string, and Object_identifier is both flexible in length and all memory can be reused.

The mechanism used to release unused memory is to call the xFree function in the file sctos.c, which uses the standard function free to release the memory.

Charstrings, Bit_strings, Octet_strings, and Object_identifiers are also handled correctly if they are part of structs or arrays. When, for example, a new value is given to a struct having a charstring component, the old charstring value will be released. For all structured types containing any of these types there will also be a Free function that is utilized to release all dynamic memory in the structured variable.

Functions for Allocation and Deallocation

The allocation and deallocation of memory is handled by the functions xAlloc and xFree in the file sctos.c. The functions in this file are used for the adoption of the generated applications to the operating system or hardware. The sctos.c file is described in detail in "The sctos.c File" .

In generated code and in the run-time library the functions xAlloc and xFree are used in each situation where memory is needed or can be released. xAlloc receives as parameter a requested size in bytes and returns the address to a data area of the requested size. All bytes in the data area are set to zero. xFree takes the address of a pointer and returns the data area referenced by the pointer to the pool of free memory. It also sets the pointer to 0.

The xAlloc and xFree functions are usually implemented using some version of the C standard functions for allocation (malloc, calloc) and deallocation (free). Other implementations are of course possible as long as the interface described in the previous section is fulfilled. In a micro controller, for example, it is probably necessary to handle allocation and deallocation directly towards the physical memory.

To prevent memory fragmentation we have used our own avail lists in almost all circumstances. Memory fragmentation is phenomena occurring when a program allocates and de-allocates data areas (of different sizes) in some "random" order. Then small pieces of memory here and there are lost, since their sizes are to small to fit an allocation request. This can lead to a slowly increasing demand for memory for the application.

Note that deallocation of memory is only used for data types. More specific it is used for variables of type:

  • Charstring
  • Octet_string
  • Bit_string
  • Object_identifier
  • Types created by String (not #STRING) and Bag generator
  • Types created by Array generator, if the index type is such that an array in C cannot be used. (General array)
  • Types created by Powerset generator, if the component type has the has property as for the index type in general arrays.

This means that if variables of the above mentioned types are not used and the user has not introduced the need for deallocation of memory himself, no memory deallocation will occur. In this case it is of course unnecessary to implement the xFree function.

It is easy to trace the need for dynamic memory. As all memory allocation is carried out through the xAlloc function and this function is available in source code (in sctos.c), it is only necessary to introduce whatever count statements or printout statements that are appropriate.


Compilation Switches

The compilation switches are used to decide the properties of the Master Library and the generated C code. Both in the library and in generated code #ifdefs are used to include or exclude parts of the code.

The switches that are used can be divided into four groups.

  1. Switches defining properties of the compiler.
  2. Switches defining a library version.
  3. Switches defining a property of a library version.
  4. Switches defining the implementation of a property.

The first group will be discussed in "Adaptation to Compilers" .

The following switches define the library version:

Switch
Corresponds to Library

 SCTDEBCOM
Simulation

 SCTDEBCLCOM
RealTimeSimulation

 SCTAPPLCLENV
Application

 SCTDEBCLENVCOM
ApplicationDebug
(Simulation with environment)

 SCTPERFSIM
PerformanceSimulation
(Library with simulated time, no environment functions, no monitor.)

The definition of the properties of these libraries can be found in scttypes.h and will be discussed below. Each library version is specified by the switches in the group property switches that it defines.

New library versions, containing other combinations of property switches, can easily be defined by introducing new library definitions in the scttypes.h file.

The property switches discussed below can be used to form library versions. If not stated otherwise for a certain property, all code, variables, struct components, and so on, are either included or excluded using conditional compiling (#ifdef), depending on whether the property is used or not.

This means, for example, that all code for the monitor interface will be removed in an application not using the monitor, which makes the application both smaller and faster.

Description of Compilation Switches

XCLOCK

If this compilation switch is not defined then simulated time is used, otherwise the system time is connected to a real clock, via the sctos.c function SDL_Clock.

XCALENDARCLOCK

This is the same as XCLOCK (it will actually define XCLOCK), except that if XCLOCK is used, time will be zero at system start up, while if XCALENDARCLOCK is used, time will be whatever the clock returns at system start up.

XPMCOMM

Define this compilation switch if the application should be able to communicate with signals via the SDL suite communication mechanism. This facility is used to accomplish communicating simulations and simulations communicating with, for example, user interfaces.

XITEXCOMM

This switch should be defined if a generated simulator should be able to communicate with a TTCN simulator.

XENV

If this compilation switch is defined the environment functions xInitEnv, xCloseEnv, xInEnv, and xOutEnv will be called at appropriate places.

XTENV

This is the same as XENV (it will actually define XENV), except that xInEnv should return a time value which is the next time it should be called (a value of type SDL_Time). The main loop will call xInEnv at the first possible occasion after the specified time has expired, or when the SDL system becomes idle.

XENV_CONFORM_2_3

This switch make signals using a compatible data structure as in SDT 2.3. This means that an extra and unnecessary component yVarP is inserted in each signal.

XSIGLOG

This facility makes it possible for a user to implement his own log of the major events in the system. This compilation switch is normally not defined. By defining this switch, each output of a signal, i.e. each call of the function SDL_Output, will result in a call of the function xSignalLog. Each time a transition is started, the function xProcessLog will be called.

These functions have the following prototypes:

extern void xSignalLog
(xSignalNode Signal,
int NrOfReceivers,
xIdNode * Path,
int PathLength);

extern void xProcessLog
(xPrsNode P);

which are included in scttypes.h if XSIGLOG is defined.

Signal will be a pointer to the data area representing the signal instance.

NrOfReceivers will indicate the success of the output according to the following table:

NrOfReceivers | Output Statement Contents
-1: | A TO clause, but no path of channels and signal routes were found between the sender and the receiver.
0: | No TO clause, and no possible receivers were found in the search for receivers.
1: | If the output statement contains a TO clause, a path of channels and signal routes was found between the sender and the receiver. If the output statement contains no TO clause, exactly one possible receiver was found in the search for receivers. The output was thus successful. The only error situation that still might be present is if an output with a TO clause is directed to a process instance that is stopped.

The third parameter, Path, is an array of pointer to IdNodes, where Path[0] refers to the IdNode for the sending process, Path[1] refers to the first signal route (or channel) in the path between the sender and the receiver, and so on, until Path[PathLength] which refers to the IdNode for the receiving process.

The parameter P in the xProcessLog function will refer to the process just about to start executing.

The fourth parameter, PathLength, represents thus the number of components in the Path array that are used to represent the path for the signal sent in the output. If the signal is sent to or from the environment, either Path[0] or Path[PathLength] will refer to xEnvId, that is to the IdNode for the environment process.

In the implementation of the xSignalLog and xProcessLog functions which should be provided by the user, the user has full freedom to use the information provided by the parameters in any suitable way, except that it is not possible to change the contents of the signal instance. The functions are provided to make it possible for a user to implement a simple log facility in environments where standard IO is not provided, or where the monitor system is too slow or too large to fit. A suitable implementation can be found in the file sctenv.c

XTRACE

If this compilation switch is defined, traces of the execution can be printed.

This facility is normally used together with the monitor, but can also be used without the monitor. The file stdout must of course be available for printing.

Setting trace values must, without the monitor, be performed in included C code, as the monitor interface is excluded. The trace components are called Trace_Default and can be found in IdNodes representing system, blocks, and processes, and in the struct xPrsRec used to represent a process instance. The values stored in these components are the values given in the Set-Trace command in the monitor. The value undefined is represented by -1.

When the monitor is excluded all trace values will be undefined at startup, except for the system which has trace value 0. This means that no trace is active at start up.

Example 489

Suitable statements to set trace values in C code:

xSystemId->Trace_Default = value;
/* System trace */
xPrsN_ProcessName->Trace_Default = value;
/* Process type trace */
PId_Var.LocalPId->PrsP->NameNode->Trace_Default =
value
/* Process type trace */
PId_Var.LocalPId->PrsP->Trace_Default = value;
/* Process instance trace */

PId_Var is assumed to be a variable of type PId.

Note:

Note that the variable xPrsN_ProcessName is declared, and therefore only available, in the file containing the block where the process is defined (and in files representing processes contained in the block).

XGRTRACE

If this compilation switch is defined it is possible for a simulation to communicate with the Organizer and the SDL Editor to highlight SDL symbols in the graphical representation.

This feature is used together with the monitor to implement graphical trace and commands like Show-Next-Symbol and Show-Previous-Symbol. It is possible to use graphical trace without the monitor in the same way as the ordinary trace (substitute Trace_Default with GRTrace in the description above). However the graphical trace is synchronized which means that the speed of the application is dramatically reduced.

XCTRACE

Defining this compilation switch makes information available to the monitor about where in the source C code the execution is currently suspended. This facility, which is used together with the monitor, makes it possible to implement the monitor command Show-C-Line-Number.

XMONITOR

If this compilation switch is defined, the monitor system is included in the generated application.

XCOVERAGE

This compilation switch makes it possible to generate coverage tables. It should be used together with XMONITOR.

MAX_READ_LENGTH

This macro controls the length of the char * buffers used to read values of SDL sorts. A typical usage is when the monitor commands Assign-Value is entered. If large data types are used, it is possible to redefine the sizes of the buffers from their default size (10000 bytes) to something more appropriate.

XSIMULATORUI

This compilation switch should be defined if the generated simulator is to be executed from the Graphical User Interface to the simulator monitor.

XMSCE

This compilation switch should be defined if the generated simulator should be able to generate Message Sequence Charts.

XSDLENVUI

This compilation switch should be defined if it should be possible to start and communicate with a user interface (or another application) from the simulation. This feature should be used together with the monitor and will define the switch XPMCOMM (see also this switch).

XNOMAIN

When this compilation switch is defined the functions main and xMainLoop are removed using conditional compiling. This feature is intended to be used when a generated SDL application should be part of an already existing application, that is when the SDL system implements a new function in an existing environment. The following functions are available for the user to implement scheduling of SDL actions:

extern void xMainInit(
void (*Init_System) (void)
#ifdef XCONNECTPM
,int argc,
char *argv[]
#endif
);

#ifdef XNOMAIN
extern void SDL_Execute (void);

extern int SDL_Transition_Prio (void);

extern void SDL_OutputTimer (void);

extern int SDL_Timer_Prio (void);

extern SDL_Time SDL_Timer_Time (void);
#endif

The behavior of these functions are as follows:

xMainInit: This function should be called to initialize the SDL system before any other function in the runtime library is called. An appropriate way to call xMainInit is:

#ifdef XCONNECTPM
xMainInit(yInit, argc, argv);
#else
xMainInit(yInit);
#endif

The compilation switch XCONNECTPM will be defined if the any switch that requires communication via the SDL suite communication mechanism is defined (XPMCOMM or XGRTRACE).

SDL_Execute: This function will execute one transition by the process instance first in the ready queue.

Before calling this function it must be checked that there really is at least one process instance in the ready queue. This test can be performed using the function SDL_Transition_Prio discussed below.

SDL_Transition_Prio: This function returns the priority of the process first in the ready queue (if signal priorities are used it is the priority of the signal that has caused the transition by the actual process instance). If the ready queue is empty, -1 is returned.

SDL_OutputTimer: This function will execute one timer output and may only be called if there is a timer ready to perform a timer output. This test can be performed with either SDL_Timer_Prio or SDL_Timer_Time described below.

SDL_Timer_Prio: This function returns the priority of the timer first in the timer queue if the timer time has expired for this timer. That is, if Now is greater than or equal to the time given in the Set statement for the timer.

If the timer queue is empty or the timer time for the first timer has not expired, -1 will be returned.

If signal priorities are used, the priority returned is the priority assigned to the timer type (in the timer definition) or the default timer priority; while if process priorities are used the priority returned is the priority of the process that has set the timer.

SDL_Timer_Time: This function returns the time given in the set statement for the first timer in the timer queue. If the timer queue is empty, the largest possible time value (xSysD.xMaxTime) is returned.

Depending on how the SDL system is integrated in an existing environment it might be possible to also use the monitor system. In that case the function xCheckMonitors should be called to execute monitor commands.

extern void xCheckMonitors (void);

To give some idea of how to use the functions discussed above, an example reflecting the way the internal scheduler in the runtime library works is given below:

Example 490

while (1) {
#ifdef XMONITOR
xCheckMonitors();
#endif
if ( SDL_Timer_Prio() >= 0 )
SDL_OutputTimer();
else if ( SDL_Transition_Prio() >= 0 )
SDL_Execute();
}

XMAIN_NAME

Sometimes when integrating generated application or simulations in larger environments the main function can be useful but cannot have the name main. This name can be changed to something else by defining the macro XMAIN_NAME. The main function came be found in the file sctsdl.c.

XSIGPRIO

The XSIGPRIO compilation switch defines that priorities on signals (set in Output statements) should be used. This switch and the three other switches for priorities given below are, of course, mutually exclusive.

A signal priority is specified with a priority directive (see "Assigning Priorities - Directive #PRIO" , that is by a comment with the following outline:

/*#PRIO 5 */.

A priority can be assigned to a signal instance in an output statement by putting a #PRIO directive last in the output symbol. In SDL/PR it is possible to put the #PRIO directive both immediately before and immediately after the semicolon ending the output statement. The Cadvanced/Cbasic SDL to C Compiler will first look for #PRIO directives in the output statement. If no directive is found there it will look in the signal definition for the signal for a priority directive. A #PRIO directive should be placed directly before the comma or semicolon ending the definition of the signal.

Example 491

SIGNAL
S1 /*#PRIO 3 */,
S2 (Integer) /*#PRIO 5 */;

If no priority directive is found in the output symbol or in the definition of the signal, the default value for signal priority is used. This value is 100. Timers can be assigned priorities in timer definitions in the same way as signals in signal definitions.

The signal priorities will be used to sort the input port of process instances in priority order, so that the signal with highest priority (lowest priority value) is at the first position. Two signals with same priority are placed in the order they arrive. The priority of the signal that can cause the next transition by a process instance is used to sort the ready queue in priority order, so that the process with a signal of highest priority is first. With equal priority, the processes are placed in the order they are inserted into the ready queue. If a continuous signal caused a processes to be inserted into the ready queue, it is the priority of the continuous signal that will be used as signal priority for this "signal".

Note that a start transition also have a "signal priority". This is by default also 100 and is set by the macro xDefaultPrioCreate described below.

Caution!

Signal priority is not included in SDL according to ITU Recommendation Z.100, and that sorting the signals in the input port of a process instance according to priorities is a direct violation of the SDL standard. This feature is however included for users that need such a behavior to implement their applications.

XPRSPRIO

This compilation switch defines that process priorities should be used. For more information see 56 The Cadvanced/Cbasic SDL to C Compiler, section Assigning Priorities - Directive #PRIO.

XSIGPRSPRIO

This compilation switch defines that priorities on signals should be used as first key for sorting in priority order, and process priorities should be used as second key.

XPRSSIGPRIO

This compilation switch defines that process priorities should be used as first key for sorting in priority order, and priorities on signals should be used as second key.

xDefaultPrio...

It is possible to redefine the default priorities for processes, signals, timer signals, continuous signals and start-up signals by defining the symbols below to appropriate values. The default value for these defaults are 100.

xDefaultPrioProcess
xDefaultPrioSignal
xDefaultPrioTimerSignal
xDefaultPrioContSignal
xDefaultPrioCreate

XOPT

This compilation switch will turn on full optimization (except XOPTCHAN), that is, it will define the following switches:

 XOPTSIGPARA

 XOPTDCL

 XOPTFPAR

 XOPTSTRUCT

 XOPTLIT

 XOPTSORT

For more information, see these switches below. The XOPT switches should not be used together with the monitor.

XOPTSIGPARA

In the symbol table tree (see section "Symbol Table Tree Structure" ) there will be one node for each parameter to a signal. These nodes are not necessary in an application and can be removed by defining the compilation switch XOPTSIGPARA.

XOPTDCL

There will be a VarIdNode in the symbol table tree for each variable declared in processes, procedures, or operator diagram. These nodes are not used in an application (without the monitor) and can be removed by defining the compilation switch XOPTDCL.

XOPTFPAR

There will be a VarIdNode in the symbol table tree for each formal parameter in a processes, procedures, or operator diagram. These node are not used in an application and may be removed by defining the compilation switch XOPTFPAR.

XOPTSTRUCT

For each component in an SDL struct there will be one VarIdNode defining the properties of this component. These VarIdNodes are not used in an application and can be removed by defining the compilation switch XOPTSTRUCT.

XOPTLIT

For each literal in a newtype that will be translated to an enum type, there will be an LitIdNode representing the literal. These nodes will not be used in an application and can be removed by defining the compilation switch XOPTLIT.

XOPTSORT

Each newtype and syntype, including the SDL standard types, will be represented by an SortIdNode. These nodes are not used in an application if all the other XOPT... mentioned above are defined.

XNOUSEOFREAL

Defining this compilation switch will remove all occurrences of C float and double types, and means for example that the SDL type Real is no longer available.

This switch is intended to be used in situations when it is important to save space, to see to that the library functions for floating type operations are not necessary to load. It cannot handle situations when the user includes floating type operations in C code, for example #CODE directives. Another consideration is if BasicCTypes.pr, or other ADTs, are included in the system. If so, it is required that types dependent on SDL Real be removed from these packages.

XNOUSEOFOBJECTIDENTIFER

Defining this switch will remove all code for the SDL predefined sort Object_identifier.

XNOUSEOFOCTETBITSTRING

Defining this switch will remove all code for the SDL predefined sorts Bit_string, Octet, and Octet_string.

Special consideration needs to be taken if BasicCTypes.pr, or other ADTs, are included in the system. If so, it is required that types dependent on these types be removed from these packages.

XNOUSEOFEXPORT

By defining this switch the user states that he is not going to use the export - import concept in SDL.

Caution!

An attempt to perform an import operation when
XNOUSEOFEXPORT is defined will result in a compilation error, as the function xGetExportAddr is not defined.

XNOUSEOFSERVICE

This compilation switch can be defined to save space, both in data and in the size of the kernel, if the SDL concept service is not used. If services are used and this switch is defined, there will be compilation errors (probably many!), when the generated code is compiled.

XPRSOPT

Section "Create and Stop Operations" describes how xLocalPIdRec structs are allocated for each created process instance, and how these structs are used to represent process instances even after they have performed stop actions. This method for handling xLocalPIdRecs is required to be able to detect when a signal is sent to a process instance that has performed a stop operation.

In an application that is going to run for a "long" period of time and that uses dynamic processes instances, this way of handling xLocalPIdRecs will eventually lead to no memory being available.

By defining the compilation switch XPRSOPT, the memory for the xLocalPIdRecs will be reused together the yVDef_ProcessName structs. This has two consequences:

  1. The need for memory will not increase due to the use of dynamic processes (the memory need depends on the maximum number of concurrent instances).
  2. It will no longer be possible to always find the situation when a signal is sent to a process instance that has performed a stop action.

More precisely, if we have a PId variable that refers to a process instance which performs a stop operation and after that a create operation (on the same process instance set) is performed where the same data area is reused, then the PId variable will now refer to the new process instance.

This means, for example, that signals intended for the old instance will be sent to the new instance. Note that it is still possible to detect signal sending to processes in the avail list even if XPRSOPT is defined.

XOPTCHAN

This switch can be used to remove all information about the paths of channels and signal routes in the system. The following memory optimization will take place:

  • The two ChannelIdNodes for each channel, signal route, and gate are removed.
  • The ToId component in the xPrsIdNodes representing processes is removed.
  • A number of functions in the library (sctsdl.c) are no longer needed and are removed.

When the information about channels, signal routes, and gates is not present two types of calculations can no longer be performed:

  1. To check if there is a path of channels and signal routes between the sender and the receiver in an OUTPUT statement with a TO clause. This is no problem as this is just an error test that we probably do not want to be performed in an application.
  2. To calculate the receiver in an OUTPUT without TO clause, if the Cadvanced/Cbasic SDL to C Compiler has not performed this calculation at generate time (see "Calculation of Receiver in Outputs" ). This is more serious, as it means that OUTPUT without TO cannot always be used. The restrictions are:
    • No outputs without to in process types, or in process in block or system types.
    • No outputs without to, designated to a process in a SEPARATE unit.

Caution!

If the XOPTCHAN switch is defined and still OUTPUT without TO clause are used (which the Cadvanced/Cbasic SDL to C Compiler cannot optimize), there will be a C compilation error saying that the name xNotDefPId is not defined.

In an ordinary SDL system OUTPUTs without TO must be used to start up the communication between different parts of the system, as there is no other way in SDL to distribute the PId values needed for OUTPUTs with TO.

This problem is solved if the Cadvanced/Cbasic SDL to C Compiler can calculate the receiver. Otherwise the data type PIdList in the library of abstract data types is intended to solve this problem. It is described in 62 The ADT Library. When this data type is used, global PId literals my be introduced, implemented as SDL synonyms. These literals can then be used to utilize OUTPUT statements with TO clauses from the very beginning.

X_LONG_INT

The SDL sort Integer is translated to int in C. To translate the Integer sort to long int instead, just define the compilation switch X_LONG_INT.

XENVSIGNALLIMIT

If this switch is defined, only a limited number of signals will be stored in the input port of the Env function. The limit is equal to the value defined for XENVSIGNALLIMIT and is normally set to 20.

XEALL

This switch will define all error handling switches (XE...) and XASSERT given below.

XECREATE

This switch will report if the initial number of instances of a process type is greater than the maximum number.

XECSOP

This switch will report error situations in ADT operator.

XEDECISION

This switch will report if no path out from a Decision is found.

XEEXPORT

This switch will report errors during Import actions.

XEFIXOF

This switch will report overflow when an SDL Real value is converted to an SDL Integer value using the operator Fix.

XEINDEX

This switch will report value out of range for array index.

XEINTDIV

This switch will report division by zero in an integer division.

XEOUTPUT

This switch will report errors during Output operations.

XERANGE

This switch will report range errors when a value is assigned to a variable of a sort containing range conditions.

XEREALDIV

This switch will report division by zero in a real division.

XEVIEW

This switch will report errors in View operations

XECHOICE

This switch will turn on error reports when accessing non-active choice components.

XEOPTIONAL

This switch will turn on error reports when accessing non-present optional struct components.

XEUNION

This switch will turn on error reports when accessing non-active union components.

XEREF, XEOWN

These switches turn on error checking on pointers (generator Ref and Own).

XASSERT

By defining this switch the possibility to define user assertions which is described in "Assertions" .

XTRACHANNELSTOENV

When using partitioning of a system a problem during the redirection of channels is that the number of channels going to the environment is not known at code generation time, which means that the size of the data area used for the connections is not known. This problem is solved in two ways.

Either the function handling redirections allocates more memory, which is the default, or the user specifies how many channels that will be redirected (which could be difficult to compute, but will lead to less need of memory).

In the first case (allocation of more memory) the macros:

#define XTRACHANNELSTOENV 0
#define XTRACHANNELLIST

should be defined like above. This is the standard in scttypes.h. If the user wants to specify the number of channels himself then

#define XTRACHANNELSTOENV 10
#define XTRACHANNELLIST ,0,0,0,0,0,0,0,0,0,0

i.e. XTRACHANNELSTOENV should be the number of channels, while XTRACHANNELLIST should be a list of that many zeros.

XDEBUG_LABEL

It is for debugging purposes sometimes of interest to introduce extra labels. The macro XDEBUG_LABEL is inserted in the code for each input symbol. As macro parameter it has a name which is the name of the state concatenated with an underscore concatenated with the signal name.

Example 492

state State1; input Sig1;
state State2; input *;
state *; input Sig2;

In the generated code for these input statements the following macros will be found:

XDEBUG_LABEL(State1_Sig1)
XDEBUG_LABEL(State2_ASTERISK)
XDEBUG_LABEL(ASTERISK_Sig2)

A suitable macro definition to introduce label would be:

#define XDEBUG_LABEL(L) L: ;

To use these label the usage of SDL must be restricted in one area. The same state may not receive two different signals with the same name! This is allowed and handled by the SDL suite. The signal have to be defined at different block or system level and the outermost signal must be referenced with a qualifier.

XCONST, XCONST_COMP

Using these compilation switches most of the memory used for the IdStructs can be moved from RAM to ROM. This depends of course on the compiler and what properties it has.

The following macro definitions can be inserted:

#define XCONST const
#define XCONST_COMP const

This will introduce const in the declaration of most of the IdStructs. It is then up to the compiler to handle const.

The XCONST_COMP macro is used to introduce const on components within a struct definition. This is necessary for some compilers to accept const on the struct as such.

If const is successfully introduced, there is a lot of RAM memory that will be saved, as probably 90% of the data area for IdStructs can be made const.

Compilation Switches - Summary

The property switches are in principle independent, except for the relations given in the descriptions above, and it should always be possible to any combination.

The number of combinations is, however, so huge that it is impossible for us to even compile all combinations. If you happen to form a combination that does not work, please let us know, so that we either can correct the code, or, if that is not possible, publish a warning against that combination.

The switches defining a standard library version will define the following property switches:

SCTDEBCOM
 XPRSPRIO
XPARTITION
XEALL
XMONITOR
XTRACE
XCTRACE
XMSCE
XCOVERAGE
XGRTRACE
XPMCOMM
XSDLENVUI
XITEXCOMM
XSIMULATORUI
SCTDEBCLCOM
 XCLOCK
XPRSPRIO
XPARTITION
XEALL
XMONITOR
XTRACE
XCTRACE
XMSCE
XCOVERAGE
XGRTRACE
XPMCOMM
XSDLENVUI
XSIMULATORUI
SCTAPPLCLENV
 XCALENDARCLOCK
XENV
XPRSPRIO
XOPT
XPRSOPT
SCTDEBCLENVCOM
 XCALENDARCLOCK
XPRSPRIO
XPARTITION
XENV
XPRSOPT
XEALL
XMONITOR
XTRACE
XCTRACE
XMSCE
XCOVERAGE
XGRTRACE
XPMCOMM
XSDLENVUI
XSIMULATORUI
SCTPERFSIM
 XEALL
XPRSPRIO

The lowest layer of switches (that handle the implementation details) are set up using the three layers above. These switches will not be discussed here. Please refer to the source code files scttypes.h and sctsdl.c for more details.


Creating a New Library

Caution!

If you create new versions of the library, make sure that the library and the generated code are compiled with the same compilation switches. If not, you might experience any type of strange behavior in the generated application!

This section describes how to generate a new library. The following topics are covered:

  • The directory structure for source and object code.
  • The sdtsct.knl file, which determines what libraries the Analyzer knows about, that is, what libraries that will be shown when Generate-Options is selected.
  • The comp.opt file and the makeoptions (make.opt in Windows) file, which determines the properties of an object code library.
  • The make file Makefile, which includes the makeoptions (make.opt) file and generates a new object code library with the properties given by the included makeoptions (make.opt) file.
  • The relations with the generated make files for SDL systems will also be discussed.

Directory Structure

The structure of files and directories used for the Cadvanced/Cbasic SDL to C Compiler libraries is shown in Figure 552 The directory sdtdir is in the installation:

<installation directory>/sdt/sdtdir/<machine
dependent dir>

where <machine dependent dir> is for example sunos5sdtdir on SunOS 5, hppasdtdir on HP, and wini386 in Windows. (In Windows, / should be replaced by \ in the path above.)

This directory is here called sdtdir and is in UNIX normally referred to by the environment variable sdtdir.

Figure 552 : Directory structure

"sctdir" is a reference to an object library and is usually setup as a parameter in the call to make. It can also be an environment variable.

In the sdtdir directory three important files are found:

  3. predef.sdl contains the definition of the predefined sorts in SDL.
  4. sdtsct.knl contains a list of the available libraries that can be used together with code generated by the Cadvanced/Cbasic SDL to C Compiler.
  5. help_sct.hlp contains the help information that can be obtained using the monitor command help.

The file predef.sdl is read by the SDL Analyzer during analysis, while the file sdtsct.knl is used to present the available libraries in the Make dialog in the Organizer (see "Make" ).

In the INCLUDE directory, there are two important groups of files:

  1. The source code files for the runtime library:
    scttypes.h, sctlocal.h, sctsdl.c, sctutil.c, sctpost.c, sctpred.h, sctpred.c, sctmon.c, sctos.c and sctenv.c
  2. The files necessary to include communication with other SCT applications: post.h, post.o (post.lib in Windows), sdt.h, itex.h.

In parallel with the INCLUDE directory there are a number of directories for libraries in object form. The SCTDEBCOM directory in Figure 552 is an example of such a directory. Each of these directories will contain three files: comp.opt, makeoptions (make.opt in Windows).

The comp.opt file determines the contents of the generated makefile and how make is called. For more details see below.

The makeoptions (make.opt) file describes the properties of the library, such as the compiler used, compiler options, linker options, and so on.

To guarantee the consistency of, for example, compilation flags between the SDL system and the kernel, the makeoptions (make.opt) file is used both by the make file compiling the library (Makefile) and by the generated make files used to compile the generated SDL system. Non-consistency in this sense between the library and the SDL system will make the result unpredictable.

File sdtsct.knl

The sdtsct.knl file describes which libraries that are available. This is presented by the Organizer in the Make dialog see "Make" ). The sdtsct.knl file has the following structure. Each available library is described on a line of its own. Such a line should first contain the name of the library (the name presented in the dialog), then the path to the directory containing the library, and last a comment up to end of line.

The path to the library can either be the complete path or a relative path. A relative path is relative to the environment variable sdtdir (on UNIX) or SDTDIR (in Windows), if that variable is defined. Otherwise it is relative to the SDL suite installation.

Example 493

Simulation SCTDEBCOM
RealTimeSimulation SCTDEBCLCOM
Application SCTAPPLCLENV
ApplicationDebug /util/sct/SCTDEBCLENVCOM

ApplicationDebug x:\sdt\sdtdir\dbclecom
MyTestLibrary ..\testlib\dbcom

Not that the two last lines is examples for Windows, while the fourth line is for UNIX.

The Organizer will look for an sdtsct.knl file first in the directory the SDL suite is started from, then in the home directory for the user, and then in the directory referenced by the environment variable sdtdir (SDTDIR) if it is defined, and in the directory where the SDL suite was installed.

File Makefile

In each directory that contains a library version there is a Makefile that can "make" the library. To create a new library after an update of the source code, change directory to the directory for the library and execute the Makefile. The Makefile uses the makeoptions (make.opt) file in the directory to get the correct compilation switches and other relevant information.

Caution!

Do not generate and test libraries in the installation directory structure. Create an appropriate copy.

Note:

The environment variables (if used) sdtdir (SDTDIR) and sctdir (SCTDIR) need not necessarily refer to directories in the installation directory. Any directory containing the relevant files may be used.

File comp.opt

This file determines the details of the generated make files, and the command issued to execute the makefile. A comp.opt file contains zero, one or more initial lines starting with a #. These lines are treated as comments. After that it contains five lines of essential data.

  • Line 1: How to include the makeoptions (make.opt) file
  • Line 2: Compile script
  • Line 3: Link script
  • Line 4: Command to run make
  • Line 5: How to build a library (archive). Used for coders/decoders.

On each of these lines % codes can be used to insert specific information.

On all five lines:

%n : newline
%t : tab
%d : target directory
%s : source directory
%k : kernel directory
%f : base name of generated executable (no path, no
file extension). NOT on line 2 or 5.

On line 2, the compile script:

%c : c file in compile script
%C : c file in compile script, without extension
%o : resulting object file in compile script

On line 3, the link script:

%o : list of all object files in link script
%O : list of all object files in link script, with
\ followed by newline between files
%e : executable file in link script

On line 4, the make command:

%m : name of generated makefile

On line 5, the archive command:

%o : list of object files, i.e. $(sctCODER_OBJS).
%a : the archive file, i.e.
libstcoder$(sctLIBEXTENSION)

Example 494 : comp.opt file for UNIX

# makefile for unix make
include $(sctdir)/makeoptions
%t$(sctCC) $(sctCPPFLAGS) $(sctCCFLAGS) $(sctIFDEF) %c -o %o
%t$(sctLD) $(sctLDFLAGS) %o -o %e
make -f %m sctdir=%k
%t$(sctAR) $(sctARFLAGS) %a %o

File makeoptions / make.opt

This file has the following structure:

Example on UNIX:

# #
sctLIBNAME = Simulation
sctIFDEF = -DSCTDEBCOM
sctEXTENSION = _smd.sct
sctOEXTENSION = _smd.o
sctLIBEXTENSION= _smd.a
sctKERNEL = $(sctdir)/../INCLUDE
sctCODERDIR = $(sctdir)/../coder

#Compiling, linking
sctCC = cc
sctCODERFLAGS = -I$(sctCODERDIR)
sctCPPFLAGS = -I. -I$(sctKERNEL) $(sctCODERFLAGS)
$(sctCOMPFLAGS) $(sctUSERDEFS)
sctCCFLAGS = -c -Xc
sctLD = cc
sctLDFLAGS =
sctAR = ar
sctARFLAGS = rcu

all : default

# below this point there are a large number of
# compilation rules for compiling the Master Library
# and the Coder library (used for encoding/decoding)
# The following name of any importance are defined:

sctLINKKERNEL =
sctLINKKERNELDEP =
sctLINKCODERLIB =
sctLINKCODERLIBDEP =

The information to the right of the equal signs should be seen as an example. These environment variables set in the makeoptions (make.opt) file should specify:

  • sctLIBNAME. This is only used by the Makefile to report what it is doing.
  • sctIFDEF. This variable should specify what compilation switches, among those defined by the Cadvanced/Cbasic SDL to C Compiler system, that should be used. Usually there is one switch defining the library version.
  • sctEXTENSION. This is used to determine the file extension of the executable files.
  • sctOEXTENSION. This is used to determine the file extension of the object files.
  • sctLIBEXTENSION. The extension of the archive/library
  • sctKERNEL. Directory of Master Library source code.
  • sctCODERDIR. The directory for the source code of the coders/decoders.
  • sctCC. This defines the compiler to be used.
  • sctCODERFLAGS. Compilation options needed to compile the coder/decoder files
  • sctCPPFLAGS. This variable should give the compilation flag necessary to specify where the C preprocessor can find the include files scttypes.h, sctlocal.h, sctpred.h, sdt.h, and post.h.
  • sctCCFLAGS. This should specify other compiler flags that should be used, as for example -g (Sun cc) or -v (Borland bcc32) for debug information, -O for optimization.
  • sctLD. This defines the linker to be used.
  • sctLDFLAGS. This should specify other flags that should be used in the link operation.
  • sctAR. The archive application
  • sctARFLAGS. Flags to sctAR.
  • sctLINKKERNEL. This variable should specify the .o files for the Master Library source files. It will be used in the link command in the generated make file.
  • sctLINKKERNELDEP. Used to implement the dependencies to recompile the kernel when it is needed.
  • sctLINKCODERLIB. This variable should specify the .o files for the Coder Library source files. It will be used in the link command in the generated make file.
  • sctLINKCODERLIBDEP. Used to implement the dependencies to recompile the Coder Library when it is needed.

Generated Make Files

The generated make files for an SDL system will as first action include the makeoptions (make.opt) file in the directory referenced by the environment variable sctdir. It will then use the variables sctIFDEF, sctLINKKERNEL, sctCC, sctCPPFLAGS, sctCCFLAGS, sctLD, and sctLDFLAGS to compile and link the SDL system with the selected library.

The make file is generated and executed by the Cadvanced/Cbasic SDL to C Compiler.

Example 495

Below, a UNIX make file generated for the SDL system example is shown.

# makefile for System: example

sctAUTOCFGDEP =
sctCOMPFLAGS = -DXUSE_GENERIC_FUNC

include $(sctdir)/makeoptions

default: example$(sctEXTENSION)

example$(sctEXTENSION): \
example$(sctOEXTENSION) \
$(sctLINKKERNELDEP)
$(sctLD) $(sctLDFLAGS) \
example$(sctOEXTENSION) $(sctLINKKERNEL) \
-o example$(sctEXTENSION)

example$(sctOEXTENSION): \
example.c
$(sctCC) $(sctCPPFLAGS) $(sctCCFLAGS) \
$(sctIFDEF) example.c -o example$(sctOEXTENSION)


Adaptation to Compilers

In this section the necessary changes to the source code to adapt it to a new environment are discussed. Adapting to a new environment could mean moving the code to new hardware or using a new compiler.

There are two parts of the source code that might need changes:

  1. In scttypes.h there is a section defining the properties of different compilers, where a new compiler can be added.
  2. In sctos.c the functions that depend on the operating system or hardware are collected. These might need to be changed due to a new compiler, a new OS, or a new hardware.

In "Compiler Definition Section in scttypes.h" the compiler definition section in scttypes.h is discussed in detail, while sctos.c is treated in "The sctos.c File" .

Compiler Definition Section in scttypes.h

Caution!

Do not to use the compiler /usr/ucb/cc. Our experience is that the bundled compiler is subject to generating compilation errors.

Instead, we recommend to run the unbundled compiler
/opt/SUNWSpro/bin/cc or the GNU C compiler.

In scttypes.h the properties of the compiler is recognized by the compiler/computer dependent switches set by the compiler:

#if defined(__linux)
#define SCT_POSIX

#elif defined(__sun)
#define SCT_POSIX

#elif defined(__hpux)
#define SCT_POSIX

#elif defined(__CYGWIN__)
#define SCT_POSIX

#elif defined(QNX4_CC)
#define SCT_POSIX

#elif defined(__BORLANDC__)
#define SCT_WINDOWS

#elif defined(_MSC_VER)
#define SCT_WINDOWS

#else
#include "user_cc.h"

#endif

Basically this section distinguishes between Unix-like/POSIX compilers and Windows compilers. In the case the compiler is not in the list above, the user must configure it himself by writing a file user_cc.h, which is best placed in the target directory.

The compilers above are:

  • __linux : gcc on linux
  • __sun : different compilers on SUN
  • __hpux : different compilers on HP
  • __CYGWIN__ : gcc on windows, for more information please see
    http://sources.redhat.com/cygwin/
  • QNX4_CC : QNX
  • __BORLANDC__ : Borland compiler on Windows
  • _MSC_VER : Microsoft compiler on Windows

After this compiler configuration section a general configuration section follows:

#if defined(SCT_POSIX) || defined(SCT_WINDOWS)
#define XMULTIBYTE_SUPPORT
#endif

#include <string.h>
#include <stdlib.h>
#include <limits.h>
#include <stdarg.h>
#ifdef XREADANDWRITEF
#include <stdio.h>
#ifdef XMULTIBYTE_SUPPORT
#include <locale.h>
#endif
#endif

#ifndef GETINTRAND
#define GETINTRAND rand()
#endif
#ifndef GETINTRAND_MAX
#define GETINTRAND_MAX RAND_MAX
#endif

#ifndef xptrint
#if (UINT_MAX < 4294967295)
#define xptrint unsigned long
#define X_XPTRINT_LONG
#else
#define xptrint unsigned
#endif
#endif

#ifndef xint32
#if (INT_MAX >= 2147483647)
#define xint32 int
#define X_XINT32_INT
#else
#define xint32 long int
#endif
#endif

First, the presence of multi-byte character support is set up. Then a number of standard include files are included, followed by setting up properties for random number generation. Last the two types, xptrint, which defines an unsigned int type with the same size as an address, and xint32, which defines a 32-bits int type, is configured.

The last three parts in this section handle the utility functions needed by sctos.c to implement some of the operating system dependent functions. Please see below where sctos.c is discussed in detail.

The sctos.c File

The following important functions are defined in sctos.c

extern void * xAlloc (xptrint Size);

extern void xFree (void **P);

extern void xHalt (void);

#ifdef XCLOCK
extern SDL_Time SDL_Clock (void);
#endif

#if defined(XCLOCK) && !defined(XENV)
extern void xSleepUntil (SDL_Time WakeUpTime);
#endif

#if defined(XPMCOMM) && !defined(XENV)
extern int xGlobalNodeNumber (void);
#endif

#if defined(XMONITOR) && !defined(XNOSELECT)
extern xbool xCheckForKeyboardInput (
long xKeyboardTimeout);
#endif

Several of these functions have three different implementations, one for SCT_POSIX, one for SCT_WINDOWS and one for other cases. The other cases solution is "an empty implementation" that does not do anything. If the standard solutions in sctos.c do not fit the needs of a certain application, any of the functions above can be supplied by the user instead. By defining some of the switches:

  • XUSER_ALLOC_FUNC
  • XUSER_FREE_FUNC
  • XUSER_HALT_FUNC
  • XUSER_CLOCK_FUNC
  • XUSER_SLEEP_FUNC
  • XUSER_KEYBOARD_FUNC

the corresponding function or functions are removed from sctos.o and have to be supplied by the user instead.

xAlloc

The function xAlloc is used to allocate dynamic memory and is used throughout the runtime library and in generated code. The function is given a size in bytes and should return a pointer to a data area of the requested size. All bytes in this data area are set to zero. The standard implementation of this function uses the C function calloc.

A user who wants to estimate the need for dynamic memory can introduce statements in xAlloc to record the number of calls of xAlloc and the total requested size of dynamic memory. Please note two things. A program using the monitor requires more dynamic memory than a program not using the monitor, so estimates should be made with the appropriate compilation switches. A call of calloc will actually allocate more memory than is requested to make it possible for the C runtime system to deallocate and reuse memory. The size of this additional memory is compiler-dependent.

A user who wants to handle the case when no more memory is available at an allocation request can implement that in xAlloc. In the standard implementation for xAlloc a test if calloc returns 0 can be introduced, at which the program can be terminated with an appropriate message.

xFree

The function xFree is used to return memory to the list of free memory so it can be reused by subsequent calls of xAlloc. The standard implementation of this function uses the C function free. In very simple cases, no data types using dynamic memory are used and no other introduction of dynamic data by the user, this function will not be used.

The parameter of the xFree function, is the address of the pointer to the allocated memory.

Example 496 Using the xFree function

unsigned char *ptr;
ptr = xAlloc(100);
xFree (&ptr); /* NOTE: Not xFree(ptr); */

xHalt

The function xHalt is used to exit from a program and is in the standard implementation using the C function exit to perform its task.

SDL_Clock

The function SDL_Clock should return the current time, read from a clock somewhere in the OS or hardware. The return value is of type SDL_Time, that is a struct with two 32-bits integer components, representing seconds and nanoseconds in the time value.

typedef struct {
xint32 s; /* for seconds */
xint32 ns; /* for nanoseconds */
} SDL_Time;

The standard implementation of SDL_Clock uses the C function time, which returns the number of seconds since some defined date.

Note:

Note that the C function time only handles full seconds.

In an embedded system or any other application that requires better time resolution, or when the C function time is not available, SDL_Clock should be implemented by the user.

Note:

If an application does not require a connection with real time (for example if it is not using timers and should run as fast as possible), there is no need for a clock function. In such a case it is probably suitable to use simulated time by not defining the compilation switch XCLOCK, whereby SDL_Clock is never called and does not need to be implemented. An alternative is to let SDL_Clock always return the time value 0.

A typical implementation in an embedded system is to have hardware generating interrupts at a predefined rate. At each such interrupt a variable containing the current time is updated. This variable can then be read by SDL_Clock to return the current time.

Caution!

The variable must be protected from updates during the period of time that the SDL_Clock reads the clock variable.

Calling the interrupt routine while the SDL_Clock reads the clock variable would cause a system disaster.

xSleep_Until

The function xSleep_Until is given a time value, as a value of type SDL_Time (see above) and should suspend the executing until this time is reached, when it should return.

This function is used only when real time is used (the switch XCLOCK is defined) and when there is no environment functions (XENV is not defined). The xSleep_Until function is used to wait until the next event is scheduled when there is no environment that can generate events.

xGlobalNodeNumber

The function xGlobalNodeNumber is used to assign unique numbers to each SDL system which is part of an application.

If environment functions are used for an SDL system this function should be implemented there. If, however, we have communicating simulations, there are no env functions and the xGlobalNodeNumber function is defined in sctos.c instead.

So the xGlobalNodeNumber function is only used if XPMCOMM is defined and XENV is not defined. As this function is only used in the case of a communicating simulation, it is only necessary to implement it for computers/compilers that communicate with the SDL suite, which means that it is not interesting for a user to change the standard implementation of this function. The implementation calls the function getpid, and uses thus the OS process number as global node number.

xCheckForKeyboardInput

The function xCheckForKeyboardInput is used to determine if there is a line typed on the keyboard (stdin) or not. If this is difficult to implement it can instead determine if there are any characters typed on the keyboard or not. This function is only used by the monitor system, (when XMONITOR is defined).

The xCheckForKeyboardInput function is used to implement the possibility to interrupt the execution of SDL transitions by typing <Return> and to handle polling of the environment (xInEnv or its equivalent when communicating simulations is used) when the program is waiting at the "Command :" prompt in the monitor.


List of All Compilation Switches

Introduction

This section is a reference to the macros that are used together with the generated C code from the Cadvanced/Cbasic SDL to C Compiler. Here the macros are just enumerated and explained. The section is divided in a number of subsection, each treating one major aspect of the code. Within the subsections the macros are enumerated in alphabetic order.

Information about some of the macros (Library Version Macros, Compiler Definition Section Macros, and General Properties) can also be found in the section "Compilation Switches" .

To fully understand the descriptions of the macros in this section it is also necessary to know the basic data structures used, especially for the static structures, i.e. the xIdNodes. This information can be found in the section "The Symbol Table" .

The information about the data types used for the dynamic structure of the system, i.e. about process instances, signal, timers, and so on, are also of interest. This can be found in "The SDL Model" .

Library Version Macros

SCTAPPLCLENV

Application.

SCTAPPLENV

Application without clock.

SCTDEB

Stand-alone simulator for any environment. Should be executed from OS.

SCTDEBCL

Stand-alone simulator with real time for any environment. Should be executed from OS.

SCTDEBCLCOM

Simulator with real time for host. Can be executed from the SDL suite or from OS.

SCTDEBCLENV

Stand-alone simulator, with real time and env functions, for any environment. Should be executed from OS.

SCTDEBCLENVCOM

Simulator, with real time and env functions, for any environment. May be executed from OS or from simulator GUI.

SCTDEBCOM

Simulator for host. Can be executed from the SDL suite or from OS.

SCTOPT1APPLCLENV

Application with minimal memory requirements. Real cannot be used. No channel information

SCTOPT2APPLCLENV

Application with minimal memory requirements. Real cannot be used. Const for all channel information.

SCTPERFSIM

Suitable for execution of performance simulations.

Compiler Definition Section Macros

SCT_POSIX

Set up for UNIX/POSIX like compilers/systems.

SCT_WINDOWS

Set up for compilers on Windows

Some Configuration Macros

COMMENT(P)

Should be defined as:

#define COMMENT(P)

The macro is used to insert comments in included C code. See Example 359.

GETINTRAND

A random generation function. Usually rand() or random().

GETINTRAND_MAX

The max int value generated by function mentioned in GETINTRAND. Usually RAND_MAX or 2147483647 (32-bit integers).

SCT_VERSION_4_4

Defined in generated code if the Cadvanced/Cbasic SDL to C Compiler version 4.4 was used.

XCAT(P1,P2)

Should concatenate token P1 and P2. Possibilities:

#define XCAT(P1,P2) P1##P2

or

#define XCAT(P1,P2) P1/**/P2

or

#define XCAT(P1,P2) XCAT2(P1)P2
#define XCAT2(P2) P2

XMULTIBYTE_SUPPORT

Should be set if the compiler supports multi byte characters.

XNOSELECT

Should be defined if there is no support for the select function found in UNIX operating systems. This is used to implement "user defined interrupt" by typing the return key while simulating.

XNO_VERSION_CHECK

If this macro is defined there will be no version check between the generated code and the scttypes.h file.

XSCT_CBASIC

Defined in generated code if Cbasic was used.

XSCT_CADVANCED

Defined in generated code if Cadvanced was used.

X_SCTTYPES_H

Defined in scttypes.h in a way that it possible to include the scttypes.h file several times without any problems.

X_XINT32_INT

Should be defined if xint32 is int.

X_XPTRINT_LONG

Should be defined if xptrint is unsigned long.

General Properties

TARGETSIM

Can be used to connect an application with a monitor on a target system with the SDL suite running on a host computer.

XASSERT

Detect and report user defined assertions that are not valid.

XCALENDARCLOCK

Use the clock function in sctos.c (not simulated time). Time is whatever the clock function returns.

XCLOCK

Use the clock function in sctos.c (not simulated time). Time is zero at system start up.

XCOVERAGE

Compile with code to store information about the current coverage of the SDL system. This information can also be printed in the monitor.

XCTRACE

Compile preserving the possibility to report the current C line number during simulations.

XEALL

Defines XEOUTPUT, XEINTDIV, XEREALDIV, XECSOP, XEFIXOF, XERANGE, XEINDEX, XECREATE, XEDECISION, XEEXPORT, XEVIEW, XEERROR, XEUNION, XECHOICE, XEOPTIONAL, XEREF, XEOWN, and XASSERT.

For more information, see these macros.

XECHOICE

Detect and report attempts to access non-active components in Choice variables.

XECREATE

Detect and report if more static instances are created at start up, than the maximum number of concurrent instances.

XECSOP

Detect and report errors in ADT operators.

XEDECISION

Detect and report when there is no possible path out from a decision.

XEERROR

Detect and report the usage of the error term in an SDL expression.

XEEXPORT

Detect and report errors in import actions.

XEFIXOF

Detect and report integer overflow in the operator fix.

XEINDEX

Detect and report index out of bounds in arrays.

XEINTDIV

Detect and report integer division with 0.

XENV

Call the env functions.

XENV_CONFORM_2_3

Insert the VarP pointer in the xSignalNode so that signals conform with their implementation in SDT 2.3.

XEOPTIONAL

Detect and report attempts to access optional struct components that are not present.

XEOUTPUT

Detect and report warnings in outputs (mainly outputs where signal is immediately discarded).

XEOWN

Detect and report illegal usage of Own and ORef pointers.

XERANGE

Detect and report subrange errors.

XEREALDIV

Detect and report real division with 0.0.

XEREF

Detect and report attempts to dereference null pointer.

XEUNION

Detect and report attempts to access non-active components in a #UNION.

XEVIEW

Detect and report errors in view actions.

XGRTRACE

Compile with the trace in source SDL graphs enabled.

XITEXCOMM

Enable the possibility for an executable to communicate with the TTCN suite via the Postmaster.

XMAIN_NAME

If this macro is defined the main function in sctsdl.c will be renamed to the name given by the macro.

XMONITOR

Compile with the monitor system. This macro will implicitly set up a number of other macros as well.

XMSCE

Compile with the MSC trace enabled.

XNOMAIN

If this macro is defined the main function in sctsdl.c will be removed.

XPMCOMM

Enable the possibility for an executable to communicate via the Postmaster.

XPRSPRIO

Use priorities on process instance sets.

XPRSSIGPRIO

Use first priorities on process instance sets and then priorities on signal instances.

XSDLENVUI

Enable the possibility to communicate with a user-defined UI.

XSIGLOG

Call the xSignalLog and xProcessLog functions.

XSIGPRIO

Use priorities on signal instances.

XSIGPRSPRIO

Use first priorities on signal instances and then priorities on process instance sets.

XSIMULATORUI

Enable the possibility to communicate with the simulator UI.

XTENV

As XENV but call xInEnv at specified times (next event time is out parameter from function xInEnv).

XTRACE

Compile with the textual trace enabled.

Code Optimization

XCONST

The majority of the xIdNode structs can be made const by defining CONST as const. This is only possible in applications (not simulations).

XCONST_COMP

This should normally be defined as const if XCONST is const. It is used to introduce const in the component declarations within the xIdNode structs.

XNOCONTSIGFUNC

Do not include functions to calculate the expressions in continuous signals. This saves also one function pointer in the xIdNode for the states. If this switch is defined, continuous signals cannot be used.

XNOENABCONDFUNC

Do not include functions to calculate the expressions in enabling conditions. This saves also one function pointer in the xIdNode for the states. If this switch is defined, enabling conditions cannot be used.

XNOEQTIMERFUNC

Do not include function to compare the parameters of two timers. This saves also one function pointer in the xIdNode for the signals. If this switch is defined, timers with parameters cannot be used.

XNOREMOTEVARIDNODE

Do not include xIdNodes for remote variable definitions.

XNOSIGNALIDNODE

Do not include xSignalIdNodes for signals and timers.

XNOSTARTUPIDNODE

Do not include xSignalIdNodes for start up signals.

XNOUSEOFOBJECTIDENTIFIER

The type Object_identifier and all operations on that type are removed.

XNOUSEOFOCTETBITSTRING

The types Bit_string, Octet, Octet_string and all operations on these types are removed.

XNOUSEOFSERVICE

All data and code needed to handle services are removed.

XNOUSEOFREAL

The type real and all operations on real are removed.

XOPT

Defines XOPTSIGPARA, XOPTDCL, XOPTFPAR, XOPTSTRUCT, XOPTLIT, and XOPTSORT.

For more information see these macros.

XOPTCHAN

Do not include xIdNodes for channels, signal routes, and gates. Information in services and processes about connections to signal routes and gates are also removed.

Note:

If this compilation switch is defined all outputs must either be sent TO a process or the receiver must be possible to calculate during code generation.

XOPTDCL

Do not include xIdNodes for variables.

XOPTFPAR

Do not include xIdNodes for formal parameters.

XOPTLIT

Do not include xIdNodes for literals.

XOPTSIGPARA

Do not include xIdNodes for signal parameters.

XOPTSORT

Do not include xIdNodes for newtypes and syntypes.

XOPTSTRUCT

Do not include xIdNodes for struct components.

XPRSOPT

Optimize memory for process instances. All memory for a process instance can be reused, but signal sending to a stopped process, who's memory has been reused by a new process, cannot be detected. The new process will in this case receive the signal.

XSYNTVAR

If this compilation switch is defined, xVarIdNodes are inserted for the Present components for optional struct components. This feature is only needed by the Validator and by LINK. It should not be defined otherwise.

Definitions of Minor Features

XBREAKBEFORE

Should be used mainly if the MONITOR or GRTRACE switches are defined. It will make the functions and struct components for SDT references available and is also used to expand the macros XAT_FIRST_SYMBOL, XBETWEEN_SYMBOLS, XBETWEEN_SYMBOLS_PRD, XBETWEEN_STMTS, XBETWEEN_STMTS_PRD, XAFTER_VALUE_RET_PRDCALL, and XAT_LAST_SYMBOL to suitable function calls. These functions are used to interrupt a transition between symbols during simulation.

XCASEAFTERPRDLABELS

See XCASELABELS below. The SDL symbols just after an SDL procedure call have to be treated specially, as the symbol number (=case label) for these symbols are used as the restart address for the calling graph. Normally this macro should be defined. If SDL procedure calls are transformed to proper C function calls, and SDL return is translated to a C return, and nextstate in a procedure is NOT translated to a C return (i.e. the process will be hanging in the C function representing the SDL procedure) then it is not necessary to define XCASEAFTERPRDLABELS.

XCASELABELS

The function implementing the behavior of a process, procedure, or service contains one large switch statement with a case label for each SDL symbol in the graph. This switch is used to be able to restart the execution of a process, procedure, or service at any symbol. In an application most of these label can be removed (all except for those symbols that start a transition, i.e. start, input, continuous signal). The macro XCASELABELS should be defined to introduce the case labels for all SDL symbol. This means that XCASELABELS should be defined in a simulation but not in an application.

XCONNECTPM

If XCONNECTPM is defined the SDL simulation will try to connect itself to the postmaster. This is necessary if GR trace (XGRTRACE), communicating simulations (XPMCOMM), or communication with the TTCN suite (XITEXCOMM) is to be used. The XCONNECTPM feature is normally only used in simulations.

XCOUNTRESETS

Count the number of timers that are removed at a reset operation. This information is used by the textual trace system (XTRACE) to present this information. The information is really only of interest at a stop action when more then one timer might be (implicitly) reset. XCOUNTRESETS should not be defined in an application.

XENVSIGNALLIMIT

This macro is used to determine the number of signals sent to the environment that, during simulation, should be saved in the input port of the env process instance. Such signals can be inspected with the normal monitor commands for viewing of signals. This macro is only of interest in a simulation and has the default value 20.

XERRORSTATE

Insert the data structure to represent an "error" state that can be used if no path is found out from a decision. This should normally be defined if XEDECISION is defined.

XFREESIGNALFUNCS

Insert free functions for each signal, timer, or startup signal that contains a parameter of a type having a free function. These signal free functions can the be used to free allocated data within a signal. This macro should be defined if Master Library is used.

XFREEVARS

Insert free function calls for all variables of a type with free function, just before stop or return actions. This means that free actions are performed on allocated data referred to from variables is before the object ceases to exist. This macro should be defined.

XIDNAMES

This macro is used to determine if the SDL name of an SDL object should be stored in the xIdNode for the object. This character string is used for communication with the user in for example the monitor. Normally this macro should not be used in an application. Sometime it might be useful for target debugging to define XIDNAMES, as it is then fairly easy to identify objects by just printing the SDL name from a debugger. On average this seems to cost approximately 5% more memory.

XNRINST

This macro should be defined if process instance numbers are to be maintained. The instance number is the number in the monitor printout Test:2, identifying the individual instances of the process instance set Test in this case. XNRINST is normally only used in a simulation.

XOPERRORF

Include the function xSDLOpError in sctsdl.c. This function is used to print run-time errors in ADT operators.

XPRSSENDER

Store the value of sender also in the xPrsNode. The normal place is in the latest received signal. This is only needed in a simulation as sender might be accessed from the monitor system after the transition is completed and the signal has been returned to the pool of available memory.

XREADANDWRITEF

Include the functions for basic Read and Write. This is needed mainly in simulations.

XREMOVETIMERSIG

Allow the removal of timer signals for not-executing PIds. This is needed only in simulations to implement the monitor commands set-timer and reset-timer.

XSIGPATH

If this macro is defined then the functions xIsPath and xFindReceiver will return the path of signal routes, channels, and gates from the sender to the receiver, as out parameters. This information can then be used in the monitor system, for example, to produce signal logs. This macro should normally not be defined in an application.

XSYMBTLINK

The XSYMBTLINK macro is used to determine if a complete tree should be built from the xIdNodes of the system. If XSYMBTLINK is defined then all xIdNodes contains a Parent, a Suc, and a First pointer. The value of the Parent pointer is generated directly into the xIdNodes. Suc and First, however, are calculated in the yInit function by calling the xInsertIdNode function. The Suc and First pointers are needed by the monitor system, but not in an application, i.e. XSYMBTLINK should be defined in a simulation but not in an application.

XTESTF

This macro is used to include or remove test functions for syntype (or newtypes) with range conditions. The yTest function is used by the monitor system and by the functions to test index out of bounds in arrays and to test subranges. This means that XTESTF should be defined if the monitor is used or if XERANGE or XEINDEX is defined.

XTRACHANNELSTOENV

When using partitioning of a system a problem during the redirection of channels is that the number of channels going to the environment is not known at code generation time, which means that the size of the data area used for the connections is not known. This problem is solved in two ways.

Either the function handling redirections allocates more memory, which is the default, or the user specifies how many channels that will be redirected (which could be difficult to compute, but will lead to less need of memory).

In the first case (allocation of more memory) the macros:

#define XTRACHANNELSTOENV 0
#define XTRACHANNELLIST

should be defined like above. This is the standard in scttypes.h. If the user wants to specify the number of channels himself then

#define XTRACHANNELSTOENV 10
#define XTRACHANNELLIST ,0,0,0,0,0,0,0,0,0,0

i.e. XTRACHANNELSTOENV should be the number of channels, while XTRACHANNELLIST should be a list of that many zeros.

XTRACHANNELLIST

See XTRACHANNELSTOENV just above.

Static Data, Mainly xIdNodes

XBLO_EXTRAS

All generated struct values for block, block type, and block instance structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xBlockIdStruct must be updated as well. Normally this macro should be empty.

Example 497

#define XBLO_EXTRAS ,0

XBLS_EXTRAS

All generated struct values for block substructure structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xBlockSubstIdStruct must be updated as well. Normally this macro should be empty.

Example 498

#define XBLS_EXTRAS ,0

XCOMMON_EXTRAS

All generated struct values for xIdNode structs contain this macro after the common components. This means that it is possible to insert new components in all xIdNodes by defining this macro. Normally this macro should be empty.

Example 499

To insert a new int component with value 0 the following definition can be used:

#define XCOMMON_EXTRAS ,0

XLIT_EXTRAS

All generated struct values for literal structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xLiteralIdStruct must be updated as well. Normally this macro should be empty.

Example 500

#define XLIT_EXTRAS ,0

XPAC_EXTRAS

All generated struct values for package structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xPackageIdStruct must be updated as well. Normally this macro should be empty.

Example 501

#define XSYS_EXTRAS ,0

XPRD_EXTRAS

All generated struct values for procedure structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xPrdIdStruct must be updated as well. Normally this macro should be empty.

Example 502

#define XSYS_EXTRAS ,0

XPRS_EXTRAS

(PREFIX_PROC_NAME)

All generated struct values for process, process type, and process instance structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xPrsIdStruct must be updated as well.

Example 503

#define XPRS_EXTRAS(PREFIX_PROC_NAME) \
,XCAT(PREFIX_PROC_NAME,_STACKSIZE)

XSIG_EXTRAS

All generated struct values for signal, timer, RPC_signal, startup signal structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xSignalIdStruct must be updated as well. Normally this macro should be empty.

Example 504

#define XSIG_EXTRAS ,0

XSPA_EXTRAS

All generated struct values for signal parameter structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xVarIdStruct must be updated as well (Note that variables, formal parameters, signal parameters, and struct components are all handled in xVarIdStruct.) Normally this macro should be empty.

Example 505

#define XSPA_EXTRAS ,0

XSRT_EXTRAS

All generated struct values for newtype and syntype structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xSortIdStruct must be updated as well. Normally this macro should be empty.

Example 506

#define XSRT_EXTRAS ,0

XSRV_EXTRAS

All generated struct values for service, service type, and service instance structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xSrvIdStruct must be updated as well. Normally this macro should be empty.

Example 507

#define XSRV_EXTRAS ,0

XSTA_EXTRAS

All generated struct values for state structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xStateIdStruct must be updated as well. Normally this macro should be empty.

Example 508

#define XSTA_EXTRAS ,0

XSYS_EXTRAS

All generated struct values for system, system type, and system instance structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xSystemIdStruct must be updated as well. Normally this macro should be empty.

Example 509

#define XSYS_EXTRAS ,0

XSYSTEMVARS

This macro gives the possibility to introduce global variables declared in the beginning of the C file containing the implementation of the SDL system unit.

XSYSTEMVARS_H

If extern definitions are needed for the data declared in XSYSTEMVARS, this is the place to introduce it. These definitions will be present in the .h file for the system unit (if separate generation is used).

XVAR_EXTRAS

All generated struct values for variables, formal parameters, and struct components structs contain this macro last in the struct. By defining this macro new components can be inserted. Note that the type xVarIdStruct must be updated as well (Note that signal parameters also uses the type xVarIdStruct). Normally this macro should be empty.

Example 510

#define XVAR_EXTRAS ,0

Data in Processes, Procedures and Services

PROCEDURE_VARS

The struct components that are needed for each procedure instance. Example: state.

PROCESS_VARS

The struct components that are needed for each process instance. Example: state, parent, offspring, self, sender, inputport.

SERVICE_VARS

The struct components that are needed for each service instance. Example: state

YGLOBALPRD_YVARP

This macro is used to declare the yVarP pointer (which is a pointer to the yVDef struct for the process) in a procedure defined outside of a process. As a global procedure never can access process local data, it is suitable to let yVarP be a pointer to a struct only containing the components defined in the macro PROCESS_VARS.

YGLOBALSRV_YVARP

This macro is used to declare the yVarP pointer (which is a pointer to the yVDef struct for the process) in a service type defined outside of a process. As a global service type never can access process local data, it is suitable to let yVarP be a pointer to a struct only containing the components defined in the macro PROCESS_VARS.

YPAD_TEMP_VARS

Local variables in the PAD function for a process or service. Example: temporary variables needed for outputs, create actions.

YPAD_YSVARP

Declaration of the ySVarP pointer used to refer to the received signal. Normally ySVarP is void *.

YPAD_YVARP

(VDEF_TYPE)

This macro is used within a process and in a service defined within a process. It should be expanded to a declaration of yVarP, which is the pointer that is used to access SDL variables in the process. yVarP should be of type VDEF_TYPE *, where VDEF_TYPE is the type of the yVDef struct for the process. If the pointer to the yVDef struct is passed as parameter to the PAD function, yVarP can be assigned its correct value already in the declaration.

YPRD_TEMP_VARS

Local variables in the function implementing the behavior of an SDL procedure.

YPRD_YVARP

(VDEF_TYPE)

This macro is used within a procedure defined in a process. It should be expanded to a declaration of yVarP, which is the pointer that is used to access SDL variables in the process. yVarP should be of type VDEF_TYPE *, where VDEF_TYPE is the type of the yVDef struct for the process. If the pointer to the yVDef struct is passed as parameter to the procedure function, yVarP can be assigned its correct value already in the declaration.

Some Macro Used Within PAD Functions

BEGIN_PAD

(VDEF_TYPE)

BEGIN_PAD is a macro that can be used to insert code that is executed in the beginning of the PAD functions. VDEF_TYPE is the yVDef type for the process.

BEGIN_START_TRANSITION

(STARTUP_PAR_TYPE)

This macro can be used to introduce code that is executed at the beginning of the start transition. STARTUP_PAR_TYPE is the yPDef struct for the startup signal for this process.

CALL_SERVICE

This macro is used in the PAD function of a process that contains services. It should be expanded to a call to PAD function for the service that should execute the next transition (ActiveSrv).

CALL_SUPER_PAD_START

(PAD)

During the start transition of a process all inherited PAD functions up to and including the PAD function containing the START symbol have to be called. The reason is to initialize all variables defined in the process. This macro is used to perform a call to the inherited PAD function (the macro parameter PAD). Usually this macro is expanded to something like:

yVarP->RestartPAD = PAD; PAD(VarP);

followed by either a return or a goto NewTransition depending on execution model.

CALL_SUPER_PRD_START

(PRD, THISPRD)

This macro is used in the same way as CALL_SUPER_PAD_START (see above) but for the start transition in a procedure. THISPRD is the executing procedure function, while PRD is the inherited procedure function.

CALL_SUPER_SRV_START

(PAD)

This macro is used in the same way as CALL_SUPER_PAD_START (see above) but for the start transition in a service. PAD is the inherited PAD function.

LOOP_LABEL

The LOOP_LABEL macro should be used to form the loop from a nextstate operation to the next input operation necessary in the OS where OS tasks does not perform return at end of transition (most commercial OS). This macro is also suitable to handle free on received signals and the treatment of the save queue. In an OS where SDL nextstate is implemented using a C return (the Master Library for example) the LOOP_LABEL macro is usually empty.

LOOP_LABEL_PRD

Similar to LOOP_LABEL but used in procedures with states.

LOOP_LABEL_PRD_NOSTATE

Similar to LOOP_LABEL but used in procedures without states. This macro is in many circumstances expanded to nothing.

LOOP_LABEL_SERVICEDECOMP

Similar to LOOP_LABEL but used in the PAD function for a process containing services.

SDL_OFFSPRING

Should return the value of offspring.

SDL_PARENT

Should return the value of parent.

SDL_SELF

Should return the value of self.

SDL_SENDER

Should return the value of sender.

START_SERVICES

This macro is used in the PAD function of a process that contains services. It should be expanded in such a way that the start transitions for all of the services are executed.

XEND_PRD

This is a macro generated at the end of a function that represents the behavior of a procedure. It needs not to be expanded to anything. To define it as

return (xbool)0;

might remove a compiler warning that the end of a value returning function might be reached.

XPRSNODE

Should usually be expanded to the type xPrsNode.

XNAMENODE

How to reach the xPrsIdNode from a PAD function. Normally this is yVarP->NameNode.

XNAMENODE_PRD

How to reach the xPrdIdNode from a PRD function. Normally this is yPrdVarP->NameNode.

XNAMENODE_SRV

How to reach the xSrvIdNode from a PAD function. Normally this is ySrvVarP->NameNode.

YPAD_FUNCTION

(PAD)

The function heading of the PAD function given as parameter.

YPAD_PROTOTYPE

(PAD)

The function prototype of the PAD function given as parameter.

YPRD_FUNCTION

(PRD)

The function heading of the PRD function given as parameter.

YPRD_PROTOTYPE

(PRD)

The function prototype of the PRD function given as parameter.

yInit Function

BEGIN_YINIT

This macro is placed in the beginning of the yInit function in the file containing code for the system. It can be expanded to variable declarations and initialization code.

XPROCESSDEF_C

(PROC_NAME, PROC_NAME_STRING, PREFIX_PROC_NAME, PAD_FUNCTION, VDEF_TYPE)

This macro can be used to introduce code for each process instance set in the system.

Parameters:

  • PROC_NAME
    the name of the process without prefix.
  • PROC_NAME_STRING
    the name of the process as a character string.
  • PREFIX_PROC_NAME
    the name of the process with prefix.
  • PAD_FUNCTION
    the PAD function for this process instance set.
  • VDEF_TYPE
    the yVDef struct for this process.

XPROCESSDEF_H

(PROC_NAME, PROC_NAME_STRING, PREFIX_PROC_NAME, PAD_FUNCTION, VDEF_TYPE)

This macro can be used to introduce extern declaration (placed in the proper .h file) for each process instance set in the system.

Parameters:

  • PROC_NAME
    the name of the process without prefix.
  • PROC_NAME_STRING
    the name of the process as a character string.
  • PREFIX_PROC_NAME
    the name of the process with prefix.
  • PAD_FUNCTION
    the PAD function for this process instance set.
  • VDEF_TYPE
    the yVDef struct for this process.

xInsertIdNode

In the yInit function the function xInsertIdNode is called for each IdNode. In an application this is not necessary, and xInsertIdNode can be defined as

#define xInsertIdNode(Node)

The function xInsertIdNode is needed if XSYMBTLINK, XCOVERAGE, or XMONITOR is defined.

YINIT_TEMP_VARS

This macro is placed in all yInit functions and can be expanded to local variables needed within the yInit function.

Implementation of Signals and Output

ALLOC_SIGNAL

ALLOC_SIGNAL_PAR

(SIG_NAME, SIG_IDNODE, RECEIVER, SIG_PAR_TYPE)

These macros are used to allocate a data area for a signal to be sent. ALLOC_SIGNAL is used if the signal has no parameters, while ALLOC_SIGNAL_PAR is used if the signal has parameters. The resulting data area should be reference by the variable mentioned by the macro OUTSIGNAL_DATA_PTR (see below).

Parameters:

  • SIG_NAME
    the name of the signal without prefix.
  • SIG_IDNODE
    the xSignalIdNode of the signal.
  • RECEIVER
    the receiver given in the TO clause, or calculated. In a NO_TO output, RECEIVER is xNotDefPId.
  • SIG_PAR_TYPE
    the yPDef type of the signal. If the signal has no parameters this macro parameter is XSIGNALHEADERTYPE (see below).

INSIGNAL_NAME

This macro should be expanded to the identification of the currently received signal. It is used to distinguish between signals when several signal is enumerated in the same input symbol.

OUTSIGNAL_DATA_PTR

This should be the pointer referring to be signal data area while building the signal during an output. It should be assigned its value in ALLOC_SIGNAL or ALLOC_SIGNAL_PAR, and will then be used during assignment of signal parameters and in the SDL_2OUTPUT macro just below.

SDL_2OUTPUT

SDL_2OUTPUT_NO_TO

SDL_2OUTPUT_COMPUTED_TO

SDL_ALT2OUTPUT

SDL_ALT2OUTPUT_NO_TO

SDL_ALT2OUTPUT_COMPUTED_TO

(PRIO, VIA, SIG_NAME, SIG_IDNODE, RECEIVER, SIG_PAR_SIZE, SIG_NAME_STRING)

These six macros are used to send the signal created in ALLOC_SIGNAL or ALLOC_SIGNAL_PAR. The SDL_ALT versions of the macros are used if the directive /*#ALT*/ has been given in the output. The version without suffix is used for an output TO, while the suffix _COMPUTED_TO is used for an output without to but it was possible to compute the receiver during code generation time. The suffix _NO_TO indicates an output without to, where the receiver cannot be calculated during code generation time.

Parameters:

  • PRIO
    the priority of the signal specified in a #PRIO directive.
  • VIA
    the via list given in the output.
  • SIG_NAME
    the name of the signal without prefix
  • SIG_IDNODE
    the xSignalIdNode for the signal.
  • RECEIVER
    the receiver given in the TO clause, or calculated. In a NO_TO output, RECEIVER is xNotDefPId.
  • SIG_PAR_SIZE
    the size of the yPDef struct of the signal. If signal without parameters SIG_PAR_SIZE is 0.
  • SIG_NAME_STRING
    the name of the signal as a character string.

SDL_THIS

In an output TO THIS in SDL, the RECEIVER parameter in the ALLOC_SIGNAL and SDL_2OUTPUT macros discussed above will become SDL_THIS.

SIGCODE

(P)

This macro makes it possible to store a signal code (signal number) in the xSignalIdNode for a signal. The macro parameter P is the signal name without prefix.

SIGNAL_ALLOC_ERROR

This macro is inserted after the ALLOC_SIGNAL macro and the assignment of parameter values to the signal. It can be used to test if the alloc was successful or not.

SIGNAL_ALLOC_ERROR_END

This macro is inserted after the SDL_2OUTPUT macro.

SIGNAL_NAME

(SIG_NAME, SIG_IDNODE)

This macro should be expanded to an identification of the signal given as parameter. Normally the identification is either the xSignalIdNode for the signal or an int value. If the id is an int value it is suitable to insert defines of type #define signal_name number. A file containing such defines can be generated using the Generate Signal Numbers feature in Cadvanced/Cbasic.

Parameters:

  • SIG_NAME
    the name of the signal without parameters
  • SIG_IDNODE
    the xSignalIdNode for the signal.

SIGNAL_VARS

The struct components that are needed for each signal instance. Example: sender, receiver, signal type.

TO_PROCESS

(PROC_NAME, PROC_IDNODE)

This macro is used as RECEIVER in the ALLOC_SIGNAL and SDL_2OUTPUT macros if the signal is sent to a process instance set in SDL.

Parameters:

  • PROC_NAME
    the name of the receiving process without prefix.
  • PROC_IDNODE
    the xPrsIdNode of the receiving process.

TRANSFER_SIGNAL

TRANSFER_SIGNAL_PAR

(SIG_NAME, SIG_IDNODE, RECEIVER, SIG_PAR_TYPE)

These macros are used as alternative for the ALLOC_SIGNAL macros (see these macros above) if the directive #TRANSFER if given in the output.

  • SIG_NAME
    the name of the signal without prefix.
  • SIG_IDNODE
    the xSignalIdNode of the signal.
  • RECEIVER
    the receiver given in the TO clause, or calculated. In a NO_TO output, RECEIVER is xNotDefPId.
  • SIG_PAR_TYPE
    the yPDef type of the signal. If the signal has no parameters this macro parameter is XSIGNALHEADERTYPE (see below).

XNONE_SIGNAL

The representation for a none signal.

XSIGNALHEADERTYPE

This macro is used to indicate a yPDef struct for a signal without parameters. Such a signal has no generated yPDef struct. It is suitable to let XSIGNALHEADERTYPE be the name of a struct just containing the components in SIGNAL_VARS.

XSIGTYPE

Depending on the representation of the signal type that is used (xSignalIdNode or int) this macro should either be xSignalIdNode or int.

Implementation of RPC

ALLOC_REPLY_SIGNAL

ALLOC_REPLY_SIGNAL_PAR

ALLOC_REPLY_SIGNAL_PRD

ALLOC_REPLY_SIGNAL_PRD_PAR

(SIG_NAME, SIG_IDNODE, RECEIVER, SIG_PAR_TYPE)

These macros are used to allocate the Reply signal in the signal exchange in an RPC. The suffix _PAR is used if the reply signal contains parameters. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

Parameters:

  • SIG_NAME
    the reply signal name without prefix.
  • SIG_IDNODE
    the xSignalIdNode for the reply signal.
  • RECEIVER
    the receiver of the reply signal. The macro XRPC_SENDER_IN_ALLOC or XRPC_SENDER_IN_ALLOC_PRD are used as actual parameter. The suffix _PRD is used if the implicit RPC transition is part of a procedure.
  • SIG_PAR_TYPE
    the yPDef type for the reply signal. If the reply signal does not contain any parameters the macro name XSIGNALHEADERTYPE is generated as actual parameter.

REPLYSIGNAL_DATA_PTR

REPLYSIGNAL_DATA_PTR_PRD

This should be a reference to the data area for the reply signal that is allocated in the ALLOC_REPLY_SIGNAL macro. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

SDL_RPCWAIT_NEXTSTATE

SDL_RPCWAIT_NEXTSTATE_PRD

(PREPLY_IDNODE, PREPLY_NAME, RESTARTADDR)

These macros are used to implement the implicit nextstate operation in the caller of an RPC. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

Parameters:

  • PREPLY_IDNODE
    the xSignalIdNode for the reply signal.
  • PREPLY_NAME
    the name without prefix for the reply signal.
  • RESTARTADDR
    the restart address (symbol number) for the implicit input of the reply signal.

SDL_2OUTPUT_RPC_CALL

(PRIO, VIA, SIG_NAME, SIG_IDNODE, RECEIVER, SIG_PAR_SIZE, SIG_NAME_STRING)

Send the call signal of an RPC.

Parameters:

  • PRIO
    priority of signal.
  • VIA
    the via list, which in this case always is (xIdNode *)0, i.e. no via list.
  • SIG_NAME
    the RPC call signal name without prefix.
  • SIG_IDNODE
    the xSignalIdNode for the RPC call signal.
  • RECEIVER
    the receiver of the call signal. This is either expressed as an ordinary TO-expression or using the macro XGETEXPORTINGPRS (see below) in case of no explicit receiver specified in the call.
  • SIG_PAR_SIZE
    the size of the yPDef struct for the call signal. If the call signal has no parameters this parameter will be 0.
  • SIG_NAME_STRING
    the name of the RPC call signal as a character string.

SDL_2OUTPUT_RPC_REPLY

SDL_2OUTPUT_RPC_REPLY_PRD

(PRIO, VIA, SIG_NAME, SIG_IDNODE, RECEIVER, SIG_PAR_SIZE, SIG_NAME_STRING)

These macros are used to send the RPC reply signal. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

Parameters:

  • PRIO
    priority of signal.
  • VIA
    the via list, which in this case always is (xIdNode *)0, i.e. no via list.
  • SIG_NAME
    the RPC reply signal name without prefix.
  • SIG_IDNODE
    the xSignalIdNode for the RPC reply signal.
  • RECEIVER
    the receiver of the reply signal. This is expressed using the macro XRPC_SENDER_IN_OUTPUT or XRPC_SENDER_IN_OUTPUT_PRD.
  • SIG_PAR_SIZE
    the size of the yPDef struct for the reply signal. If the reply signal has no parameters this parameter will be 0.
  • SIG_NAME_STRING
    the name of the RPC reply signal as a character string.

XGETEXPORTINGPRS

(REMOTENODE)

This macro should be expanded to an expression that given the remote procedure given as actual macro parameter (more exactly the IdNode for the remote procedure), returns one possible exporter of this remote procedure. Usually this macro is expanded to a call of the library function xGetExportingPrs.

XRPC_REPLY_INPUT

XRPC_REPLY_INPUT_PRD

Macros that can be used for special processing needed to receive an RPC reply signal. The macros are usually expanded to nothing.

XRPC_SAVE_SENDER

XRPC_SAVE_SENDER_PRD

These macros can be used to save the sender of a received RPC call signal, for further use when the reply signal is to be sent. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

XRPC_SENDER_IN_ALLOC

XRPC_SENDER_IN_ALLOC_PRD

These macros are used to obtain the receiver of the reply signal (from the sender of the call signal) in the ALLOC_REPLY_SIGNAL macros. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

XRPC_SENDER_IN_OUTPUT

XRPC_SENDER_IN_OUTPUT_PRD

These macros are used to obtain the receiver of the reply signal (from the sender of the call signal) in the SDL_2OUTPUT_RPC_REPLY macros. The suffix _PRD is used if the implicit RPC transition is part of a procedure.

XRPC_WAIT_STATE

The state number used for a RPC wait state. XRPC_WAIT_STATE is usually defined as -3.

Implementation of View and Import

XGETEXPORTADDR

(REMOTENODE, EXPORTER, IS_DEF_EXPORTER)

This macro should be expanded to an expression that returns the address of the exported variable. Usually the function xGetExportAddr is called.

Parameters:

  • REMOTENODE
    the IdNode for the remote variable.
  • EXPORTER
    the value of the optional PId expression. If no PId expression is given this parameter is SDL_NULL.
  • IS_DEF_EXPORTER
    has the value (xbool)1 if a PId expression was found in the import statement, otherwise it is (xbool)0.

SDL_VIEW

(PID_EXPR, HAS_EXPR, VAR_NAME_STRING, REVEALED_LIST, SORT_SIZE)

This macro should be expanded to an expression that returns the address of the viewed variable. Usually the function SDL_View is called.

Parameters:

  • PID_EXPR
    the value of the optional PId expression. If no PId expression is given this parameter is SDL_NULL.
  • HAS_EXPR
    has the value (xbool)1 if a PId expression was found in the view statement, otherwise it is (xbool)0.
  • VAR_NAME_STRING
    the name of the viewed variable as a character string.
  • REVEALED_LIST
    the list of the revealed variables.
  • SORT_SIZE
    the size of the sort of the revealed variable.

Implementation of Static and Dynamic Create and Stop

ALLOC_STARTUP

ALLOC_STARTUP_PAR

(PROC_NAME, STARTUP_IDNODE, STARTUP_PAR_TYPE)

Allocate the data area for a startup signal and let the pointer mentioned in the macro STARTUP_DATA_PTR refer to this data area. The suffix _PAR is used if the startup signal contains parameters.

Parameters:

  • PROC_NAME
    the name without prefix for the created process.
  • STARTUP_IDNODE
    the xSignalIdNode for the startup signal of the created process.
  • STARTUP_PAR_TYPE
    the yPDef for the startup signal of the created process.

ALLOC_STARTUP_THIS

Allocate the data area for a startup signal and let the pointer mentioned in the macro STARTUP_DATA_PTR refer to this data area. This macro is used in a create THIS operation.

INIT_PROCESS_TYPE

(PROC_NAME, PREFIX_PROC_NAME, PROC_IDNODE, PROC_NAME_STRING, MAX_NO_OF_INST, STATIC_INST, VDEF_TYPE, PRIO, PAD_FUNCTION)

This macro will be call once for each process instance set in the yInit function. It should be used to initiated common features for all instances of a process instance set.

Parameters:

  • PROC_NAME
    the name without prefix for the process instance set.
  • PREFIX_PROC_NAME
    the name with prefix for the process instance set.
  • PROC_IDNODE
    the xPrsIdNode for the process instance set.
  • PROC_NAME_STRING
    the name as character string for the process instance set.
  • MAX_NO_OF_INST
    the maximum number of instances of this process instance set.
  • STATIC_INST
    the number of static instances of this process instance set.
  • VDEF_TYPE
    the yVDef type for this process instance set.
  • PRIO
    the priority for process instance set.
  • PAD_FUNCTION
    the PAD for this process instance set.

SDL_CREATE

(PROC_NAME, PROC_IDNODE, PROC_NAME_STRING)

This macro is used to create (a create action) a process instance.

Parameters:

  • PROC_NAME
    the name without prefix for the process instance set.
  • PROC_IDNODE
    the xPrsIdNode for the process instance set.
  • PROC_NAME_STRING
    he name as character string for the process instance set.

SDL_CREATE_THIS

This macro is used to implement create this.

SDL_STATIC_CREATE

(PROC_NAME, PREFIX_PROC_NAME, PROC_IDNODE, PROC_NAME_STRING, STARTUP_IDNODE, STARTUP_PAR_TYPE, VDEF_TYPE, PRIO, PAD_FUNCTION, BLOCK_INST_NUMBER)

This macro is called in the yInit function once for each static process instances that should be created of a process instance set.

Parameters:

  • PROC_NAME
    the name without prefix for the process instance set.
  • PREFIX_PROC_NAME
    the name with prefix for the process instance set.
  • PROC_IDNODE
    the xPrsIdNode for the process instance set.
  • PROC_NAME_STRING
    the name as character string for the process instance set.
  • STARTUP_IDNODE
    the xSignalIdNode for the startup signal for the process instance set.
  • STARTUP_PAR_TYPE
    the yPDef type for the startup signal for the process instance set.
  • VDEF_TYPE
    the yVDef type for the process instance set.
  • PRIO
    the priority for the process instance set.
  • PAD_FUNCTION
    the PAD function for the process instance set.
  • BLOCK_INST_NUMBER
    if this process instance set is part if a block instance set then this macro is the block instance number for the block instance set that this process belongs to. Otherwise this macro parameter is 1.

SDL_STOP

This macro is used to implement the SDL operation stop (both in processes and in services).

STARTUP_ALLOC_ERROR

This macro is inserted after the ALLOC_STARTUP macro and the assignment of parameter values to the signal. It can be used to test if the alloc was successful or not.

STARTUP_ALLOC_ERROR_END

This macro is inserted after the SDL_CREATE macro.

STARTUP_DATA_PTR

This macro should be expanded to a temporary variable used to store a reference to the startup signal data area. It should be assigned in the ALLOC_STARTUP macro and will be used to assign the actual signal parameters (the fpar values) to the startup signal.

STARTUP_VARS

This macro can be used to insert additional general components in the startup signals. In all startup signal yPDef structs SIGNAL_VARS will be followed by STARTUP_VARS.

Implementation of Timers, Timer Operations and Now

ALLOC_TIMER_SIGNAL_PAR

(TIMER_NAME, TIMER_IDNODE, TIMER_PAR_TYPE)

Allocate a data area for the timer signal with parameters.

Parameters:

  • TIMER_NAME
    the name without prefix of the timer.
  • TIMER_IDNODE
    the xSignalIdNode for the timer.
  • TIMER_PAR_TYPE
    the yPDef for the timer.

DEF_TIMER_VAR

DEF_TIMER_VAR_PARA

(TIMER_VAR)

There will be one application of this macro in the yVDef type for the process for each timer declaration the process contains. These declarations can be used to introduce components (timer variables) in the yVDef struct to track timers. The parameter TIMER_VAR is a suitable name for such a variable. The suffix _PARA is used if the timer has parameters.

INIT_TIMER_VAR

INIT_TIMER_VAR_PARA

(TIMER_VAR)

These macros will be inserted in start transitions, during initialization of process variables. This makes it possible to initialize the timer variables that might be inserted in the DEF_TIMER_VAR macro. The parameter TIMER_VAR is the name for such a variable. The suffix _PARA is used if the timer has parameters.

INPUT_TIMER_VAR

INPUT_TIMER_VAR_PARA

(TIMER_VAR)

These macros will be inserted at an input operation on a timer signal. This makes it possible to update the timer variables that might be inserted in the DEF_TIMER_VAR macro. The parameter TIMER_VAR is the name for such a variable. The suffix _PARA is used if the timer has parameters. Note that if a timer signal is received in an input * statement, no INPUT_TIMER_VAR will be present in this case.

RELEASE_TIMER_VAR

RELEASE_TIMER_VAR_PARA

(TIMER_VAR)

These macros will be inserted at a stop. This makes it possible to perform cleaning up of the timer variables that might be inserted in the DEF_TIMER_VAR macro. The parameter TIMER_VAR is the name for such a variable. The suffix _PARA is used if the timer has parameters.

SDL_ACTIVE

(TIMER_NAME, TIMER_IDNODE, TIMER_VAR)

This macro is used to implement the SDL operation active on a timer. Note that active on timers with parameters is not implemented in the Cadvanced/Cbasic SDL to C Compiler.

Parameters:

  • TIMER_NAME
    the name without prefix of the timer.
  • TIMER_IDNODE
    the xSignalIdNode for the timer.
  • TIMER_VAR
    the timer variable that might be inserted in the macro DEF_TIMER_VAR.

SDL_NOW

This is the implementation of now in SDL.

SDL_RESET

(TIMER_NAME, TIMER_IDNODE, TIMER_VAR, TIMER_NAME_STRING)

This macro is used to implement the SDL operation reset on a timer without parameters.

Parameters:

  • TIMER_NAME
    the name without prefix of the timer.
  • TIMER_IDNODE
    the xSignalIdNode for the timer.
  • TIMER_VAR
    the timer variable that might be inserted in the macro DEF_TIMER_VAR.
  • TIMER_NAME_STRING
    the name of the timer as a character string.

SDL_RESET_WITH_PARA

(EQ_FUNC, TIMER_VAR, TIMER_NAME_STRING)

This macro is used to implement the SDL operation reset on a timer with parameters. Before this macro a timer signal with the timer parameters in the reset operation is created.

Parameters:

  • EQ_FUNC
    the name of the generated equal function that can test if two timer instance are equal or not.
  • TIMER_VAR
    the timer variable that might be inserted in the macro DEF_TIMER_VAR.
  • TIMER_NAME_STRING
    the name of the timer as a character string.

SDL_SET

(TIME_EXPR, TIMER_NAME, TIMER_IDNODE, TIMER_VAR, TIMER_NAME_STRING)

SDL_SET_WITH_PARA

(TIME_EXPR, TIMER_NAME, TIMER_IDNODE, TIMER_PAR_TYPE, EQ_FUNC, TIMER_VAR, TIMER_NAME_STRING)

SDL_SET_DUR

(TIME_EXPR, DUR_EXPR, TIMER_NAME, TIMER_IDNODE, TIMER_VAR, TIMER_NAME_STRING)

SDL_SET_DUR_WITH_PARA

(TIME_EXPR, DUR_EXPR, TIMER_NAME, TIMER_IDNODE, TIMER_PAR_TYPE, EQ_FUNC, TIMER_VAR, TIMER_NAME_STRING)

SDL_SET_TICKS

(TIME_EXPR, DUR_EXPR, TIMER_NAME, TIMER_IDNODE, TIMER_VAR, TIMER_NAME_STRING)

SDL_SET_TICKS_WITH_PARA

(TIME_EXPR, DUR_EXPR, TIMER_NAME, TIMER_IDNODE, TIMER_PAR_TYPE, EQ_FUNC, TIMER_VAR, TIMER_NAME_STRING)

These six SDL_SET macros are used to implement the SDL operation set on a timer. The suffix _WITH_PARA indicates the set of a timer with parameters. In this case the SDL_SET macro is preceded by an ALLOC_TIMER_SIGNAL_PAR macro call, plus the assignment of the timer parameters. The suffix _DUR is used if the time value in the set operation is expressed as:

now + expression

In this case both the time value and the duration value (the expression above) is available as macro parameter. The suffix _TICKS is used if the time value in the set operation is expressed as:

now + TICKS(...)

where TICKS is an operator returning a duration value. In this case both the time value and the duration value (the TICKS expression above) is available as macro parameter.

Parameters:

  • TIME_EXPR
    the time expression.
  • DUR_EXPR
    the duration expression (only in _DUR and _TICKS).
  • TIMER_NAME
    the timer name without prefix.
  • TIMER_IDNODE
    the xSignalIdNode for the timer.
  • TIMER_PAR_TYPE
    the yPDef struct for the timer (only in _WITH_PARA)
  • EQ_FUNC
    the function that can be used to test if two timers have the same parameter values (only in _WITH_PARA).
  • TIMER_VAR
    the name of the timer variable that might be introduced in the macro DEF_TIMER_VAR.
  • TIMER_NAME_STRING
    the name of the timer as a character string.

TIMER_DATA_PTR

This should be the pointer referring to be timer data area while building
the timer. It should be assigned its value in ALLOC_TIMER_SIGNAL_PAR, and will then be used during assignment of signal parameters and in the SDL_SET macro

TIMER_SIGNAL_ALLOC_ERROR

This macro is inserted after the ALLOC_TIMER_SIGNAL_PAR macro and the assignment of parameter values to the timer. It can be used to test if the alloc was successful or not.

TIMER_SIGNAL_ALLOC_ERROR_END

This macro is inserted after the SDL_SET macro.

TIMER_VARS

The struct components that are needed for each timer instance. Example: sender, receiver, timer type.

As timers are signals as well, after the timer signal has been sent, TIMER_VARS has to be identical to SIGNAL_VARS, except that new component may be add last in TIMER_VARS.

XTIMERHEADERTYPE

This macro is used to indicate a yPDef struct for a timer without parameters. Such a timer has no generated yPDef struct. It is suitable to let XTIMERHEADERTYPE be the name of a struct just containing the components in TIMER_VARS.

Implementation of Call and Return

ALLOC_PROCEDURE

(PROC_NAME, PROC_IDNODE, VAR_SIZE)

Allocate a data area (yVDef) for the called procedure.

Parameters:

  • PROC_NAME
    the name of procedure with prefix.
  • PROC_IDNODE
    the xPrdIdNode of the called procedure
  • VAR_SIZE
    the size of the yVDef struct for the procedure.

ALLOC_THIS_PROCEDURE

Allocate a data area (yVDef) for a procedure when call THIS is used.

ALLOC_VIRT_PROCEDURE

(PROC_IDNODE)

Allocate a data area (yVDef) for the called procedure when calling a virtual procedure. The PROC_IDNODE parameter is the xPrdIdNode for the call procedure.

CALL_PROCEDURE

CALL_PROCEDURE_IN_PRD

(PROC_NAME, PROC_IDNODE, LEVELS, RESTARTADDR)

These macros are used to implement a call operation in SDL. The yVDef struct has been allocated earlier (in ALLOC_PROCEDURE) and the actual parameters have been assigned to components in this struct. The suffix _IN_PRD indicates that the procedure call is made in a procedure.

Parameters:

  • PROC_NAME
    the name of procedure with prefix, which is the same as the name of the C function representing the behavior of the procedure.
  • PROC_IDNODE
    the xPrdIdNode of the called procedure.
  • LEVELS
    the scope level between the caller and the called procedure.
  • RESTARTADDR
    the restart address the symbol number for the symbol after the procedure call.

CALL_PROCEDURE_STARTUP

CALL_PROCEDURE_STARTUP_SRV

These two macros are only of interest if the PAD functions are left via a return at the end of transitions. In that case any outstanding procedure must be restarted when the process becomes active again.

CALL_THIS_PROCEDURE

(RESTARTADDR)

This macro is used to implement a call THIS operation in SDL. RESTARTADDR is the restart address the symbol number for the symbol after the procedure call.

CALL_VIRT_PROCEDURE

CALL_VIRT_PROCEDURE_IN_PRD

(PROC_IDNODE, LEVELS, RESTARTADDR)

These macros are used to implement a call operation on a virtual procedure in SDL. The yVDef struct has been allocated earlier (in ALLOC_VIRT_PROCEDURE) and the actual parameters have been assigned to components in this struct. The suffix _IN_PRD indicates that the procedure call is made in a procedure.

Parameters:

  • PROC_IDNODE
    the xPrdIdNode of the called procedure.
  • LEVELS
    the scope level between the caller and the called procedure.
  • RESTARTADDR
    the restart address the symbol number for the symbol after the procedure call.

PROCEDURE_ALLOC_ERROR

This macro is inserted after the ALLOC_PROCEDURE macro and the assignment of parameter values to the procedure parameters. It can be used to test if the alloc was successful or not.

PROCEDURE_ALLOC_ERROR_END

This macro is inserted after the CALL_PROCEDURE macro.

PROC_DATA_PTR

This macro should be expanded to a temporary variable used to store a reference to the procedure data area. It should be assigned in the ALLOC_PROCEDURE macro and will be used to assign the actual procedure parameters (the fpar values).

SDL_RETURN

The implementation of return in SDL.

XNOPROCATSTARTUP

If this macro is defined then all the code discussed for the macro CALL_PROCEDURE_STARTUP (just above) is removed.

Implementation of Join

Joins in SDL are normally implemented as goto:s in C, but in one case a more complex implementation is needed. This is when the label, mentioned in the join, is in a super type.

XJOIN_SUPER_PRS

(RESTARTADDR,RESTARTPAD)

XJOIN_SUPER_PRD

(RESTARTADDR,RESTARTPRD)

XJOIN_SUPER_SRV

(RESTARTADDR,RESTARTSRV)

These macros represent join to super type in processes, procedures, and services, in that order.

Parameters:

  • RESTARTADDR
    The restart address in the super type.
  • RESTARTPAD, RESTARTPRD, RESTARTSRV
    The PAD function for the super type.

Implementation of State and Nextstate

Note:

Implicit nextstate operations in RPC calls are treated in the RPC section.

ASTERISK_STATE

The state number for an asterisk state. ASTERISK_STATE is usually defined as -1.

ERROR_STATE

The state number used for the error state. ERROR_STATE is usually defined as -2.

START_STATE

The state number for the start state. START_STATE should be defined as 0.

START_STATE_PRD

The state number for the start state in a procedure. START_STATE_PRD should be defined as 0.

SDL_NEXTSTATE

(STATE_NAME, PREFIX_STATE_NAME, STATE_NAME_STRING)

Nextstate operation (in process or service) of the given state.

Parameters:

  • STATE_NAME
    the name without prefix of the state.
  • PREFIX_STATE_NAME
    the name with prefix for the state. This identifier is defined as a suitable state number in generated code and is usually used as the representation of the state.
  • STATE_NAME_STRING
    the name of the state as a character string.

SDL_DASH_NEXTSTATE

Dash nextstate operation in a process.

SDL_DASH_NEXTSTATE_SRV

Dash nextstate operation in a service.

SDL_NEXTSTATE_PRD

(STATE_NAME, PREFIX_STATE_NAME, STATE_NAME_STRING)

Nextstate operation (in procedure) of the given state.

Parameters:

  • STATE_NAME
    the representation of the state.
  • PREFIX_STATE_NAME
    the name with prefix for the state. This identifier is defined as a suitable state number in generated code and is usually used as the representation of the state.
  • STATE_NAME_STRING
    the name of the state as a character string.

SDL_DASH_NEXTSTATE_PRD

Dash nextstate operation in a procedure.

Implementation of Any Decisions

An any decision with two paths are generated according to the following structure:

BEGIN_ANY_DECISION(2)
DEF_ANY_PATH(1, 2)
DEF_ANY_PATH(2, 0)
END_DEFS_ANY_PATH(2)
BEGIN_FIRST_ANY_PATH(1)
statements
END_ANY_PATH
BEGIN_ANY_PATH(2)
statements
END_ANY_PATH
END_ANY_DECISION

BEGIN_ANY_DECISION

(NO_OF_PATHS)

Start of the any decision. NO_OF_PATHS is the number of paths in the decision.

BEGIN_ANY_PATH

(PATH_NO)

A path (not the first) in implementation part of the any decision. PATH_NO is the path number.

BEGIN_FIRST_ANY_PATH

(PATH_NO)

The first possible path in implementation part of the any decision. PATH_NO is the path number.

DEF_ANY_PATH

(PATH_NO, SYMBOLNUMBER)

Definition of a path in the decision.

Parameters:

  • PATH_NO
    the path number.
  • SYMBOLNUMBER
    the symbol number for the first symbol in this path.

END_ANY_DECISION

The end of the any decision.

END_ANY_PATH

End of one of the paths in the implementation section.

END_DEFS_ANY_PATH

(NO_OF_PATHS)

End of the definition part of the any decision. NO_OF_PATHS is the number of paths in the decision.

Implementation of Informal Decisions

The implementation of informal decisions are similar to any decisions.

BEGIN_FIRST_INFORMAL_PATH

(PATH_NO)

The first possible path in implementation part of the informal decision. PATH_NO is the path number.

BEGIN_INFORMAL_DECISION

(NO_OF_PATHS, QUESTION)

Start of the any decision.

Parameters:

  • NO_OF_PATHS
    the number of paths in the decision.
  • QUESTION
    the question charstring.

BEGIN_INFORMAL_ELSE_PATH

(PATH_NO)

The else path in implementation part of the any decision. PATH_NO is the path number.

BEGIN_INFORMAL_PATH

(PATH_NO)

A path in implementation part of the any decision. PATH_NO is the path number.

DEF_INFORMAL_PATH

(PATH_NO, ANSWER, SYMBOLNUMBER)

Definition of a path in the decision.

Parameters:

  • PATH_NO
    the path number.
  • ANSWER
    the answer string.
  • SYMBOLNUMBER
    the symbol number for the first symbol in this path.

DEF_INFORMAL_ELSE_PATH

(PATH_NO, SYMBOLNUMBER)

Definition of the else path in the decision.

Parameters:

  • PATH_NO
    the path number.
  • SYMBOLNUMBER
    the symbol number for the first symbol in this path.

END_DEFS_INFORMAL_PATH

(NO_OF_PATHS)

End of the definition part of the informal decision. NO_OF_PATHS is the number of paths in the decision.

END_INFORMAL_ELSE_PATH

End of the else paths in the implementation section.

END_INFORMAL_DECISION

The end of the informal decision.

END_INFORMAL_PATH

End of one of the paths in the implementation section.

Macros for Component Selection Tests

The macros in this section handles testing the validity of for example a component selection of a choice or #UNION variable. Also tests for optional components in structs and for de-referencing of pointers is treated here.

XCHECK_CHOICE_USAGE

(TAG,VALUE,NEQTAG,COMPNAME,CURR_VALUE,TYPEINFO)

XSET_CHOICE_TAG

(TAG,VALUE,ASSTAG,NEQTAG,COMPNAME,CURR_VALUE,
TYPEINFO)

XSET_CHOICE_TAG_FREE

(TAG,VALUE,ASSTAG,NEQTAG,FREEFUNC,COMPNAME,
CURR_VALUE,TYPEINFO)

The CHOICE macros are used to test and to set the implicit tag in a choice variable. The XSET_CHOICE_TAG and XSET_CHOICE_TAG_FREE set the tag when some component of the choice is assigned a value. The FREE version of the macro is used if the choice contains some component that has a Free function. The XCHECK_CHOICE_USAGE is used to test if an accessed component is active or not.

Parameters:

  • TAG
    The implicit tag component
  • VALUE
    The new or expected tag value
  • ASSTAG
    The assignment function for the tag type
  • NEQTAG
    The equal test function for the tag type
  • FREEFUNC
    The Free function for the Choice type
  • COMPNAME
    The name of the selected component as a char string
  • CURR_VALUE
    The current value of the tag type
  • TYPEINFO
    The type info node for the tag type.

XCHECK_OPTIONAL_USAGE

(PRESENT_VAR,COMPNAME)

This macro is used to check that a selected optional component is present. The PRESENT_VAR parameter is the present variable for this component, while COMPNAME is the selected components name as a char string.

XCHECK_UNION_TAG_USAGE

(TAG,VALUE,NEQTAG,COMPNAME,CURR_VALUE,TYPEINFO)

XCHECK_UNION_TAG

(TAG,VALUE,ASSTAG,NEQTAG,COMPNAME,CURR_VALUE,
TYPEINFO)

XCHECK_UNION_TAG_FREE

(TAG,VALUE,ASSTAG,NEQTAG,FREEFUNC,COMPNAME,
CURR_VALUE,TYPEINFO)

The UNION macros are used to test tag in a union variable. The XCHECK_UNION_TAG and XCHECK_UNION_TAG_FREE check the tag when some component of the union is assigned a value. The FREE version of the macro is used if the union contains some component that has a Free function. The XCHECK_UNION_USAGE is used to test if an accessed component is active or not.

Parameters:

  • TAG
    The tag component
  • VALUE
    The expected tag value
  • ASSTAG
    The assignment function for the tag type
  • NEQTAG
    The equal test function for the tag type
  • FREEFUNC
    The Free function for the UNION type
  • COMPNAME
    The name of the selected component as a char string
  • CURR_VALUE
    The current value of the tag type
  • TYPEINFO
    The type info node for the tag type.

XCHECK_REF

XCHECK_OWN

XCHECK_OREF

(VALUE,REF_TYPEINFO,REF_SORT)

These macros are used to implement a test that Null pointers (using the Ref, Own, or ORef generator) are not de-referenced. These macros are inserted before each statement containing a Ref/Own/ORef pointer de-referencing. In case of an ORef pointer it is also checked that the ORef is valid, i.e. that it refers to an object owned by the current process.

Parameters:

  • VALUE
    This is the value of the pointer.
  • REF_TYPEINFO
    The typeinfo node for the Ref sort.
  • REF_SORT
    The C type that corresponds to the Ref instantiation newtype.

XCHECK_OREF2

(VALUE)

Checks that a ORef pointer is a valid pointer, i.e. NULL, or that it refers to an object owned by the current process.

Debug and Simulation Macros

XAFTER_VALUE_RET_PRDCALL

(SYMB_NO)

A macro generated between the implementation of a value returning procedure call (implicit call symbol) and the symbol containing the value returning procedure call. SYMB_NO is the symbol number of the symbol containing the value returning procedure call.

XAT_FIRST_SYMBOL

(SYMB_NO)

A macro generated between an input or start symbol and the first symbol in the transition. SYMB_NO is the symbol number of the first symbol in the transition.

XAT_LAST_SYMBOL

A macro generated immediately before a nextstate or stop operation.

XBETWEEN_STMTS

XBETWEEN_STMTS_PRD

(SYMB_NO, C_LINE_NO)

A macro generated between statements in a task. The suffix _PRD indicates that these statements are part of a procedure.

Parameters:

  • SYMB_NO
    the symbol number of the next statement.
  • C_LINE_NO
    line number in C of this statement.

XBETWEEN_SYMBOLS

XBETWEEN_SYMBOLS_PRD

(SYMB_NO, C_LINE_NO)

A macro generated between symbols in a transition. The suffix _PRD indicates that these symbols are part of a procedure.

Parameters:

  • SYMB_NO
    the symbol number of the next symbol.
  • C_LINE_NO
    line number in C of this statement.

XDEBUG_LABEL

(LABEL_NAME)

This macro gives the possibility to insert label at the beginning of transitions. Such labels can be useful during debugging. The LABEL_NAME parameter is a concatenation of state name and the signal name. The * in state *; and input *; will cause the name ASTERISK to appear.

XOS_TRACE_INPUT

(SIG_NAME_STRING)

This macro is generated at input statements and can, for example, be used to generated trace information about inputs. The SIG_NAME_STRING parameter is the name of the signal in the input.

YPRSNAME_VAR

(PRS_NAME_STRING)

This macro is generated among the declarations of variables in the PAD function for a process. It can, for example, be used to declare a char * variable containing the name of the process. Such a variable can be useful during debugging. The PRS_NAME_STRING parameter is the name of the process as a character string.

YPRDNAME_VAR

(PRD_NAME_STRING)

This macro is generated among the declarations of variables in the PRD function for a procedure. It can, for example, be used to declare a char* variable containing the name of the procedure. Such a variable can be useful during debugging. The PRD_NAME_STRING parameter is the name of the procedure as a character string.

Utility Macros to Be Inserted

The following sequence of macros should be inserted. Most of them concern removal of struct components (in IdNodes) that are not used due to the combination of other switches used.

#define NIL 0
#define XXFREE xFree
#define XSYSD xSysD.

#if defined(XPRSPRIO) || defined(XSIGPRSPRIO) ||
defined(XPRSSIGPRIO)
#define xPrsPrioPar(p) , p
#else
#define xPrsPrioPar(p)
#endif

#if defined(XSIGPRIO) || defined(XSIGPRSPRIO) ||
defined(XPRSSIGPRIO)
#define xSigPrioPar(p) , p
#define xSigPrioParS(p) p;
#else
#define xSigPrioPar(p)
#define xSigPrioParS(p)
#endif

#ifdef XTESTF
#define xTestF(p) , p
#else
#define xTestF(p)
#endif

#ifdef XREADANDWRITEF
#define xRaWF(p) , p
#else
#define xRaWF(p)
#endif

#ifdef XFREEFUNCS
#define xFreF(p) , p
#else
#define xFreF(p)
#endif

#ifdef XFREESIGNALFUNCS
#define xFreS(p) , p
#else
#define xFreS(p)
#endif

#define xAssF(p)
#define xEqF(p)

#ifdef XIDNAMES
#define xIdNames(p) , p
#else
#define xIdNames(p)
#endif

#ifndef XOPTCHAN
#define xOptChan(p) , p
#else
#define xOptChan(p)
#endif

#ifdef XBREAKBEFORE
#define xBreakB(p) , p
#else
#define xBreakB(p)
#endif

#ifdef XGRTRACE
#define xGRTrace(p) , p
#else
#define xGRTrace(p)
#endif

#ifdef XMSCE
#define xMSCETrace(p) , p
#else
#define xMSCETrace(p)
#endif

#ifdef XTRACE
#define xTrace(p) , p
#else
#define xTrace(p)
#endif

#ifdef XCOVERAGE
#define xCoverage(p) , p
#else
#define xCoverage(p)
#endif

#ifdef XNRINST
#define xNrInst(p) , p
#else
#define xNrInst(p)
#endif

#ifdef XSYMBTLINK
#define xSymbTLink(p1, p2) , p1, p2
#else
#define xSymbTLink(p1, p2)
#endif

#ifdef XEVIEW
#define xeView(p) p,
#define xeViewS(p) p;
#else
#define xeView(p)
#define xeViewS(p)
#endif

#ifdef XCTRACE
#define xCTrace(p) p,
#define xCTraceS(p) p;
#else
#define xCTrace(p)
#define xCTraceS(p)
#endif

#ifndef XNOUSEOFSERVICE
#define xService(p) , p
#else
#define xService(p)
#endif

#if !defined(XPMCOMM) && !defined(XENV)
#define xGlobalNodeNumber() 1
#endif

#define xSizeOfPathStack 50

#ifndef xOffsetOf
#define xOffsetOf(type, field) \
((xptrint) &((type *) 0)->field)
#endif
#define xToLower(C) \
((C >= `A' && C <= `Z') ? \
(char)((int)C - (int)'A' + (int)'a') : C)

#ifndef xDefaultPrioProcess
#define xDefaultPrioProcess 100
#endif

#ifndef xDefaultPrioSignal
#define xDefaultPrioSignal 100
#endif

#ifndef xDefaultPrioTimerSignal
#define xDefaultPrioTimerSignal 100
#endif

#ifndef xDefaultPrioContSignal
#define xDefaultPrioContSignal 100
#endif

#ifndef xDefaultPrioCreate
#define xDefaultPrioCreate 100
#endif

#define xbool int

#ifndef MAX_READ_LENGTH
#define MAX_READ_LENGTH 5000
/* max length of input line */
#endif

The xDefaultPrio macros above should, of course, be defined to the suitable default values.

Other macros that should be defined are.

SDL_NULL

a null value for the type PId.

xNotDefPId

which is used as RECEIVER parameter in the SDL_2OUTPUT macros. Please see also the section were signals are treated.


62 The ADT Library

This chapter provides information about the library of Abstract Data Types (ADT) that comes with the SDL suite. The data types provide services that are often needed in SDL systems.

The ADT library is mainly intended for usage together with the Cadvanced/Cbasic SDL to C Compiler and the ordinary simulation, validation, and applications kernels. Some of the ADTs are, however, also possible to use together with OS integrations (Cadvanced) and with Cmicro. If this is the case it is indicated in the description of the ADT.


General

The ADT library currently contains the following:

  • A package, ctypes, that contains a number of sorts and generators to simplify an integration with C data types
  • A data type that provides handling of text files and I/O operations as SDL operator calls
  • A data type to generate random numbers from a number of distributions
  • A data type that implements linked lists
  • Data types for byte, unsigned, long int and so on (provided only for backward compatibility; use package ctypes instead)
  • A data type that makes it possible to define PId literals for static process instances as synonyms
  • A data type that provides a number of general purpose operators that may be used to reduce the complexity of an SDL system

These data types are delivered in source code. Feel free to change and adapt these data types for your own needs.

Important!

There is no commitment from Telelogic to support the ADTs described in this chapter. Telelogic has used the ADTs in internal projects with successful results.

The files that are contained in the ADT library are located in the subdirectory <installation directory>/include/ADT. (In Windows, replace / in the path above with \)

Note: Conformance with earlier releases

The ADTs in Telelogic Tau 4.4 are backward compatible with the ADTs in earlier releases, in the sense that you only need to include the new 4.4 versions of the ADTs to obtain the same behavior.
However, it is important to remember that the ADTs and the code generators you use, must be from the same version of Telelogic Tau.


Integration with C Data Types

The package ctypes presented below contains a number of types and generators that is intended to directly support C data types in SDL. The package ctypes can also be used in OS integrations and with Cmicro. However, usage of C pointers (generator Ref) might cause problems, due to potential memory leaks and potential memory access protection between OS tasks.

The file ctypes.sdl is a SDL/PR version of this package suitable to use in an include statement in an SDL/PR system, while ctypes.sun is a SDL/GR version of the package.

In an SDL/GR system it is only necessary to insert a use clause, i.e.

use ctypes;

at a proper place. The Organizer will then by itself include the ctypes package, for example when the system is to be analyzed. To use the ctypes package in an SDL/PR system the following structure should be used.

/*#include `ctypes.sdl'*/

use ctypes;
system example;
...
endsystem;

The ctypes package consists of the following newtypes, syntypes, and generators:

SDL
C

 syntype ShortInt

 short int, short

 syntype LongInt

 long int, long

 syntype UnsignedShortInt

 unsigned short int,
unsigned short

 syntype UnsignedInt

 unsigned int, unsigned

 syntype UnsignedLongInt

 unsigned long int,
unsigned long

 syntype Float

 float

 newtype Charstar

 char *

 newtype Voidstar

 void *

 newtype Voidstarstar

 void **

 generator Carray

 array type

 generator Ref

 pointer type

All the newtypes and syntypes introduce type names for "standard types" in C.

Some of the types and generators are briefly described below.

Charstar

In Charstar there is a literal and some operators included:

LITERALS
Null;
OPERATORS
cstar2cstring : Charstar -> Charstring;
cstring2cstar : Charstring -> Charstar;
cstar2vstar : Charstar -> Voidstar;
vstar2cstar : Voidstar -> Charstar;
cstar2vstarstar : Charstar -> Voidstarstar;

Note that the operators cstar2cstring and cstring2cstar are not available when using Cmicro.

The operators are all conversion routines to convert a value from one type to another. Note that Charstar and Charstring are not the same types even if they both corresponds to char * in C. Note also that freeing allocated memory for Charstar is the responsibility of the user, as there is not enough information to handle this automatically (as for Charstring). For more information about how to free memory, see the Ref generator below.

Voidstarstar

The Voidstarstar type has all the properties of the Ref generator (see below). This means that *>, &, +, and - can be used and that the following literal and operators are defined:

LITERALS
Null,
Alloc;
OPERATORS
vstarstar2vstar : Voidstarstar -> Voidstar;
vstar2vstarstar : Voidstar -> Voidstarstar;

Carray

The generator Carray has the following parameters:

GENERATOR Carray (CONSTANT Length, TYPE Itemsort)

where Length is an integer giving the number of elements of the array (index from 0 to Length-1), and Itemsort gives the type of each element in the array. A Carray in SDL is translated to an array in C. Indexing a Carray variable in SDL follows the same rules as for ordinary SDL Arrays.

Ref

The generator Ref has the following definition:

GENERATOR Ref (TYPE Itemsort)
LITERALS
Null,
Alloc;
OPERATORS
"*>" : Ref, Itemsort -> Ref;
"*>" : Ref -> Itemsort;
"&" : Itemsort -> Ref;
make! : Itemsort -> Ref;
free : in/out Ref;
"+" : Ref, Integer -> Ref;
"-" : Ref, Integer -> Ref;
Ref2VStar : Ref -> Voidstar;
VStar2Ref : Voidstar -> Ref;
Ref2VStarStar : Ref /*#REF*/ -> Voidstarstar;
DEFAULT Null;
ENDGENERATOR Ref;

procedure Free; fpar p Voidstarstar;
external;

Instantiating the Ref generator creates a pointer type on the type given as generator parameter. The literals and operators have the following behavior:

  • Null: The NULL value (= 0) for the pointer type. This is also the default value for a pointer variable.
  • Alloc: An operator without parameters that returns a new allocated data area with the size of the Itemsort.
  • *>: This is the extract! and modify! operator and can be used to reference the value referenced by a pointer. If p is a pointer type, p*> is the value the pointer refers to. Comparing with C, p*> is the same as *p. If p is a pointer to a struct, then p*>!a is the same as (*p).a.
  • &: The & operator corresponds to the C operator with the same name. It can be used to take the address of a variable. Comparing with C, &p and &(p) in SDL is the same as &p in C.
  • make!: The make! operator, which as usual in SDL has the syntax (. .), is a short hand for creating memory and initializing it to a given value. The statement:
    a := (. 2 .);
    has the same meaning as
    a := Alloc, a*> := 2;
  • free: The Free operator is used to deallocate memory referenced by a Ref pointer. If the component type contains automatically handled pointers (Charstring, Octet_string, Bit_string, Bags, Own pointers, and so on) the memory for these components is also deallocated.
  • +, -: These operator have the meaning of pointer arithmetics in exactly the same way as in C. For example, p+1 (if p is of a pointer type) will add the Itemsort size to the value p. The + and - operators are mostly used to step through an array in C.
  • ref2vstar, vstar2ref, ref2vstarstar: These operators are conversion operators, that can be used to cast between pointers and void * and void **.
  • procedure Free: NOTE: Old feature provided for backward compatibility. Use operator free above instead.
    This external procedure is closely connected to the Ref generator. It should be used to deallocate memory allocated by the Alloc operator. Free should be passed the pointer variable that references the data area to be released. The variable should be casted to Voidstarstar. After calling Free the pointer variable will have the value Null.
    Example: Free(Ref2VStarStar(variable_name))
    Apart from the difficult syntax for calling the Free procedure it has another problem, it does not free components inside the referenced data area as the free operator above does.

The SDL Analyzer can allow implicit type conversion of pointer data types created by the Ref generator; see "Implicit Type Conversions.


Abstract Data Type for File Manipulations and I/O

The ADT TextFile

In this section an SDL abstract data type, TextFile, is discussed where file manipulations and I/O operations are implemented as operations on the abstract data type. This ADT can be used also in OS integrations and in Cmicro if the target system has support for files in C.

This data type, which you may include in any SDL system, makes it possible to access, at the SDL level, a subset of the file and I/O operations provided by C.

The implementation of the operators are harmonized with the I/O in the monitor, including the Simulator Graphical User interface. All terminal I/O, for example, will be logged on the interaction log file if the monitor command Log-On is given.

The data type defines a "file" type and contains three groups of operations:

  1. Operations to open and close files
  2. Operations to write information onto a file
  3. Operations to read information from a file.

The operations may handle I/O operations both on files and on the terminal (file stdin and stdout in C).

Note:

This data type is not intended to be used in the SDL Validator!

Purpose

The TextFile data type supplies basic file and I/O operations as abstract data type operations in SDL, whereby I/O may be performed within the SDL language. The operations may handle I/O both on the terminal and on files and are harmonized with the I/O from the monitor, from the trace functions, and from the functions handling dynamic errors.

To make the data type available you include the file containing the definition with an analyzer include in an appropriate text symbol:

Example 511 : Including an ADT File

/*#include 'file.pr' */

Remember that all file systems are operating system specific. Any rules in your file system apply.

Summary of Operators

The following literals are available in the data type FileName:

SYNTYPE FileName = Charstring
ENDSYNTYPE;

SYNONYM NULL FileName = `NULL';
SYNONYM stdin FileName = `stdin';
SYNONYM stdout FileName = `stdout';
SYNONYM stderr FileName = `stderr';

The following literals and operators are available in the data type TextFile:

NEWTYPE TextFile
LITERALS
NULL, stdin, stdout, stderr;

OPERATORS
GetAndOpenR : FileName -> TextFile;
GetAndOpenW : FileName -> TextFile;
OpenR : FileName -> TextFile;
OpenW : FileName -> TextFile;
OpenA : FileName -> TextFile;
Close : TextFile -> TextFile;
Flush : TextFile -> TextFile;
IsOpened : TextFile -> Boolean;
AtEOF : TextFile -> Boolean;
AtLastChar : TextFile -> Boolean;

PutReal : TextFile, Real -> TextFile;
PutTime : TextFile, Time -> TextFile;
PutDuration : TextFile, Duration -> TextFile;
PutPId : TextFile, PId -> TextFile;
PutInteger : TextFile, Integer -> TextFile;
PutBoolean : TextFile, Boolean -> TextFile;
PutCharacter : TextFile, Character -> TextFile;
PutCharstring : TextFile, Charstring -> TextFile;
PutString : TextFile, Charstring -> TextFile;
PutLine : TextFile, Charstring -> TextFile;
PutNewLine : TextFile -> TextFile;
"//" : TextFile, Real -> TextFile;
"//" : TextFile, Time -> TextFile;
"//" : TextFile, Duration -> TextFile;
"//" : TextFile, Integer -> TextFile;
"//" : TextFile, Charstring -> TextFile;
"//" : TextFile, Boolean -> TextFile;
"//" : TextFile, PId -> TextFile;
"+" : TextFile, Character -> TextFile;

GetReal : TextFile, Charstring -> Real;
GetTime : TextFile, Charstring -> Time;
GetDuration : TextFile, Charstring -> Duration;
GetPId : TextFile, Charstring -> PId;
GetInteger : TextFile, Charstring -> Integer;
GetBoolean : TextFile, Charstring -> Boolean;
GetCharacter : TextFile, Charstring -> Character;
GetCharstring : TextFile, Charstring -> Charstring;
GetString : TextFile, Charstring -> Charstring;
GetLine : TextFile, Charstring -> Charstring;
GetSeed : TextFile, Charstring -> Integer;

GetReal : TextFile -> Real;
GetTime : TextFile -> Time;
GetDuration : TextFile -> Duration;
GetPId : TextFile -> PId;
GetInteger : TextFile -> Integer;
GetBoolean : TextFile -> Boolean;
GetCharacter : TextFile -> Character;
GetCharstring : TextFile -> Charstring;
GetString : TextFile -> Charstring;
GetLine : TextFile -> Charstring;
GetSeed : TextFile -> Integer;
ENDNEWTYPE TextFile;

The operators may be divided into three groups with different purpose:

  1. Operators that, together with the literals, are used for handling files.
  2. Operators suited for writing information to files.
  3. Operators intended for reading information from files.

The next three subsections provide the necessary information for using these operators. The data type itself will be discussed together with the operators for handling files.

File Handling Operators

First in this subsection each operator and literal will be discussed in detail and then some typical applications of the operators will be presented.

Caution!

The operators GetAndOpenR and GetAndOpenW do not work with the Application library. The operators GetPId and PutPId (and the // operator to write PIds) can be used with the Application library, but they will use a different output format.

Operator Behavior

The type TextFile is implemented using the ordinary C file type FILE. A TextFile is a pointer to a FILE.

typedef FILE * TextFile;

The literal NULL represents a null value for files. This literal is translated to TextFileNull() in the generated C code by an appropriate #NAME directive and is then implemented using the macro:

#define TextFileNull() (TextFile)0

All variables of the type TextFile will have this value as default value.

The literals stdin and stdout represent the standard files stdin and stdout in C, which are the files used in C for I/O to the terminal. The file stdin is used for reading information from the keyboard, while stdout is used for writing information on the screen.

The standard operators assignment and test for equality is implemented in such a way that A:=B means that now A refers to the same file as B, while A=B tests if A and B refer to the same file.

FileName

The data type FileName is used to represent file names in the operators GetAndOpenR, GetAndOpenW, OpenR, OpenW, and OpenA. It has all Charstring literals and the special synonyms NULL, stdin (input from the keyboard), stdout (output to the screen), and stderr (output to the screen from which the SDL suite was started). As FileName is a syntype of Charstring, the usual Charstring operators are defined for this type.

Caution!

The synonyms stdin, stdout, stderr in some circumstances hide the literals with the same names according to SDL scope rules. If that is the case, please insert a qualifier <<type textfile>> before the literal name.

GetAndOpenR - GetAndOpenW

The operators GetAndOpenR and GetAndOpenW are used to open a file with a name prompted for on the terminal. GetAndOpenR opens the file for read, while GetAndOpenW opens the file for write. The operators take the prompt as parameter (type charstring), print the prompt on the screen (on stdout), and read a file name from the keyboard (from stdin). An attempt is then made to open a file with that name. If the open operation was successful, a reference to the file is returned by the GetAndOpenR or GetAndOpenW operator, otherwise NULL is returned. After a successful open operation you may use the file for reading or writing.

If you type <Return>, - or the file name stdin at the prompt in GetAndOpenR a reference to stdin is returned by the operator. GetAndOpenW will, in the same way, return a reference to stdout if the prompt is answered by <Return>, - or the file name stdout.

Note:

To work properly in the Simulator Graphical User Interface, the prompt string should be terminated with: ": ", i.e. colon space.

OpenR - OpenW - OpenA

The operators OpenR, OpenW, and OpenA are used to open a file with a file name passed as parameter. OpenR opens the file for read, while OpenW opens the file for write and OpenA opens the file for append. An attempt is made to open a file with the name given as a parameter. If the open operation was successful, a reference to the file is returned by the OpenR, OpenW, or OpenA operator, otherwise NULL is returned. After a successful open operation you may read, write or append on the file.

Close

The operator Close is used to close the file passed as parameter. Close always returns the value NULL. This operator should be used on each file opened for write after all information is written to the file to ensure that any possibly buffered data is flushed.

Note:

Always close a file variable before assigning it to a new file, otherwise data may be lost.

Flush

Output to files is usually buffered, and is therefore not immediately written on the physical output device. The operator Flush forces the output buffer of the file that is passed as parameter to be written on the physical output device. It is equivalent to C function fflush.

IsOpened

The operator IsOpened may be used to determine if a TextFile is open or not. It may, for example, be used to test the result of the Open operation discussed above. The test IsOpened(F) is equivalent to
F /= NULL.

AtEOF

The operator AtEof may be used to determine if a TextFile has reached the end of file or not. This operator could be used in order to determine when to stop reading input from a file. The test AtEof(F) is equivalent to feof(F).

Note:

AtEof first becomes true when attempts are made to read behind the
end-of-file. Operator AtLastChar becomes true when the last character of the file has been read, and is usually more useful than AtEof.

AtLastChar

The operator AtLastChar may be used to determine if a TextFile has reached the end of file or not. This operator is useful in order to determine when to stop reading input from a file. The test AtLastChar(F) returns true if there are no more characters to be read from the file.

Examples of Use

Three typical situations when you want to write information are easily identified:

  1. The information is to be printed on the screen.
  2. The information is to be printed on a file with a given name.
  3. You want to determine at run-time where the information is to be printed.

Example 512 : ADT for File I/O, Print to Screen

If the information is to be printed on the screen, you may use the following structure:

DCL F TextFile;
TASK F := stdout // 'example';

Declare a variable of type TextFile and assign it the value stdout. You may then use it in the write operators discussed under "Write Operators" .

Example 513 : ADT for File I/O, Print to File

If the information is to be printed on a file with a given name, you may use the following structure:

DCL F TextFile;
TASK F := OpenW('filename');
TASK F := F // 'example';

The difference from the above is that the operator OpenW is used to open a file with the specified name. This outline may be complemented with a test if the OpenW operation was successful or not.

Example 514 : ADT for File I/O, Accessing Text File

If you want to be able to determine at run-time where the information should be printed, you should define a TextFile as in the examples above, and then use the following structure.

Figure 553 : Accessing a TextFile

If you answer the question by hitting <Return> or by typing stdout, the information will be printed on screen (stdout). If you type the name of a file, the information will be printed on that file.

If you want to open the file for read instead of write, you may use almost identical structures.

Write Operators

Operator Behavior

The write operators PutReal, PutTime, PutDuration, PutInteger, PutBoolean, PutCharacter, and PutCharstring all take a TextFile and a value of the appropriate type as parameters. The operators print the value passed as parameter on the file referenced by the TextFile parameter and then return the TextFile. The Put* operators will print the values in the same format as the monitor uses for the command Examine-Variable, and will append a space after each printed value.

The operator PutString takes a TextFile and a Charstring parameter and prints the string on the TextFile. PutString prints the string as a C string, not using the format for SDL Charstring. This means that no ' is printed. PutString returns the TextFile given as parameter as result.

The infix write operator "//" takes as parameters a TextFile and a value of type Boolean, Charstring, Integer, PId, Real, Time, or Duration. TextF // Val prints the value `Val' to the TextFile referenced by `TextF', and returns value `TextF'. Character strings are printed without enclosing `''. All // operators except the one for Charstring append a space to the file, after the value is written.

The infix write operator "+" takes as parameters a TextFile and a Character. "+" behaves just as "//", but it has its special name in order to avoid type conflicts with Charstring.

The operator PutNewLine takes a TextFile as parameter, prints a carriage return (actually a "\n") on this file, and returns the TextFile as operator result.

The different Put operators are equivalent to the // operators, and they are mainly present for backward compatibility reasons.

There is a function named xPutValue in the implementation of the data type TextFile. This function may print a value of any type that may be handled by the monitor system, but may only be accessed from in-line C code and not from SDL. A detailed description of the xPutValue function may be found under "Accessing the Operators from C" .

Example 515 : ADT for File I/O, Print to File

To print a line according to the following example, where 137 is the value of the variable NoOfJobs:

Number of jobs: 137 Current time: 137.0000

You could use the following statements, assuming that the TextFile F is already opened:

TASK
F := F // `Number of jobs: ` // NoOfJobs;
TASK
F := F // `current time: ` // Now;
TASK
F := PutNewLine(F);

Read Operators

Operator Behavior

The read operators GetReal, GetTime, GetDuration, GetInteger, GetBoolean, GetCharacter, GetCharstring, and GetSeed are used to read values of the various sorts.

The operator GetSeed is used to read appropriate values to initialize random number generators (odd integers in the range 1 to 32767).

There are two versions of each Get operator: one that only takes as parameters a TextFile, and the other that takes as parameters a TextFile and a Charstring which is used as prompt. All Get operators behave differently depending on if the value should be read from the terminal (stdin) or from a file.

If the value should be read from the terminal, the Get operators with the prompt parameter may be used. This prompt is printed on the screen, and then an attempt to read a value of the current type is made. If a Get operator with only the TextFile parameter is used, a default prompt is used, that depends on the type that is to be input. If the operation is successful, the read value is returned as a result, otherwise the message "Illegal value" is printed and the user is given a new chance to type a value.

Note:

To work properly in the Simulator Graphical User Interface, the prompt string should be terminated with: ": ", i.e. colon space.

If the value should be read from a file, it is recommended to use the Get operators without the prompt parameter, as it is not used. It is assumed that a value of the correct type will be found.

There are several Get operators for reading character strings:

GetString reads a sequence of characters until the first white space character, and is equivalent to fscanf (f, "%s").

GetLine reads a sequence of characters until the end of line is reached. It is equivalent to fgets, but the end-of-line character will not be part of the string.

GetCharstring reads a sequence of characters on a single line that is enclosed by single quotes (`). This operator is mainly present for backward compatibility reasons.

There is a function named xGetValue in the implementation of the data type TextFile, which may read a value of any type that may be handled by the monitor system. This function can only be accessed from in-line C code and not from SDL. A detailed description of the xGetValue function may be found under "Accessing the Operators from C" .

Example 516 : ADT for File I/O, Read from File

TASK
Mean := GetReal (F),
A(1) := GetReal (F),
A(2) := GetReal (F),
A(3) := GetReal (F);

Accessing the Operators from C

In some circumstances it may be easier to use C code (in #CODE directives) rather than SDL to implement an algorithm. SDL implementations for linear algorithms sometimes become unnecessarily large and complex, as SDL for example lacks a loop concept. Consider the SDL graph in Figure 553. This graph could be replaced by a TASK with the following contents:

'Open file F' /*#CODE
#(F) = GetAndOpenW("LFile : ");
while ( ! IsOpened(#(F)) )
#(F) = GetAndOpenW("LIllegal name. File : "); */

which is more compact and gives a better overview at the SDL level.

#(F) is an SDL directive telling the SDL to C compiler to translate the SDL variable F to the name it will receive in the generated C code.

To simplify the use of in-line C code, #NAME directives are introduced on all identifiers defined in this data type. The same names are used in C as in SDL.

Note:

Upper and lower case letters are significant in C (but not in SDL).
Note also the additional L in the Charstring literals, for example "LIllegal name. File : ". This first character is used in the implementation of the SDL sort Charstring and should always be L in a charstring literal.

From in-line C, two functions xGetValue and xPutValue are also available to read and write values of any type. These functions have the following prototypes:

extern void xGetValue(
TextFile F,
SDL_Charstring Prompt,
xSortIdNode SortId,
void * Result,
char * FunctionName );

extern void xPutValue(
TextFile F,
xSortIdNode SortId,
void * Value,
char * FunctionName );

Parameter
Interpretation

 TextFile F
The file to read from or to print to.

 In xGetValue:
SDL_Charstring Prompt
Is used as prompt in exactly the same way as for the ordinary Get operators.

 xSortIdNode SortId
A reference to the xIdNode that represents the SDL sort to be read or printed
For the predefined SDL sorts you may use variables named xSrtN_SDL_Real, xSrtN_SDL_Integer, and so on, as parameter.
For user-defined sorts, you may use similar variables named ySrtN_#(SortName), where SortName should be replaced by the sort name.
 void * Result
void * Value
The address to the variable where the result should be stored, or the address to the variable that should be printed.

 char * FunctionName
A string specifying the name of an appropriate function. This name will be given if an error is detected during reading or printing.

Note:

xGetValue and xPutValue will not work together with the Application library.

To handle, for example, I/O of an SDL struct, the ideas presented below may be used.

Example 517 : ADT for File I/O of an SDL Struct

NEWTYPE SName STRUCT
a, b Integer;
ENDNEWTYPE;

DCL
FIn, FOut TextFile,
SVar SName;

TASK 'Put SVar on FOut' /*#CODE
xPutValue( #(FOut), ySrtN_#(SName),
&(#(SVar)), "PutSName" ); */;

TASK 'Get SVar from FIn' /*#CODE
xGetValue( #(FIn), "Value : ",
ySrtN_#(SName),&(#(SVar)), "LGetSName"); */;


Abstract Data Type for Random Numbers

One important feature, especially in performance simulations, is the possibility to generate random numbers according to a number of distributions, like for example the negative exponential distribution and the Erlang distribution. It is also important that the random number sequences are reproducible, to be able to run a slightly modified version of a simulation with the same sequence of random numbers.

In this section an SDL abstract data type according to the previous discussion is presented. This data type may be included in any SDL system. This ADT can also be used in OS integrations and in Cmicro. It is, however, necessary to check that the typedef for the RandomControl, see below, refers to an unsigned 32-bit type.

Purpose

The SDL RandomControl data type allows you to generate pseudo-random numbers. A number of distributions are supported, including the negative exponential distribution and the Erlang distribution. In performance simulations, which is the main application area for this data type, the most important need for random numbers is in connection with Time and Duration values. It is, for example, interesting to draw inter- arrival times in job generators, and service lengths in servers. Distributions returning positive real numbers are thus most meaningful.

The basic mechanism behind pseudo-random number generation is as follows. A sequence of bit-patterns is defined using a formula of type:

The function f should be such that the sequence of elements seen as numbers should be "random", and the number of element in the sequence, before it starts to repeat itself, should be as large as possible.

To obtain a new random number is thus a two step process:

  1. Compute and store a new bit-pattern from the old bit-pattern
  2. Interpret the new bit-pattern as a number, which is returned as the new random number.

In this data type, 32 bit patterns, implemented in C using the type unsigned long, are used together with the formula:

The result returned by the operator Random, which is the basic random number generator, is this bit-pattern seen as a number between 0 and 1, and expressed as a float.

The data type RandomControl may be included in any SDL system using an analyzer include statement, where the file containing the definition of the data type is included. Example:

/*#include 'random.pr' */

As the C standard functions log and exp are used in the random.pr file, it is necessary to link the application together with the library for math functions, i.e. to have -lm in the link operation in the makefile. See "Makefile Options" . To use the entry -lm in the link list seems to be a fairly standard way to find the library for math functions. If this does not work, or you want more details, please see the documentation for your C compiler.

Available Operators

The type RandomControl, introduced by this data type, is in C implemented as the address of an unsigned long.

typedef unsigned long * RandomControl;

Note that you have check that unsigned long is a 32 bit type, otherwise you have to change the typedef.

The reason for passing the address to the bit-pattern (that is to the unsigned long), is that this bit-pattern has to be updated by the random functions.

Below the operators provided in this data type are listed. There are, for many of the operators, several versions with different sets of parameters and/or result types to support different usage of the operator.

Random : RandomControl -> Real;
Random : RandomControl -> Duration;
Random : RandomControl -> Time;

Erlang : Real, Integer, RandomControl -> Real;
Erlang : Real, Integer, RandomControl -> Duration;
Erlang : Real, Integer, RandomControl -> Time;
Erlang : Duration, Integer, RandomControl -> Real;
Erlang : Duration, Integer, RandomControl -> Duration;
Erlang : Duration, Integer, RandomControl -> Time;
Erlang : Time, Integer, RandomControl -> Real;
Erlang : Time, Integer, RandomControl -> Duration;
Erlang : Time, Integer, RandomControl -> Time;

HyperExp2 :
Real, Real, Real, RandomControl -> Real;
HyperExp2 :
Real, Real, Real, RandomControl -> Duration;
HyperExp2 :
Real, Real, Real, RandomControl -> Time;
HyperExp2 :
Duration, Duration, Real, RandomControl -> Real;
HyperExp2 :
Duration, Duration, Real, RandomControl -> Duration;
HyperExp2 :
Duration, Duration, Real, RandomControl -> Time;
HyperExp2 :
Time, Time, Real, RandomControl -> Real;
HyperExp2 :
Time, Time, Real, RandomControl -> Duration;
HyperExp2 :
Time, Time, Real, RandomControl -> Time;

NegExp : Real, RandomControl -> Real;
NegExp : Real, RandomControl -> Duration;
NegExp : Real, RandomControl -> Time;
NegExp : Duration, RandomControl -> Real;
NegExp : Duration, Rando mControl -> Duration;
NegExp : Duration, RandomControl -> Time;
NegExp : Time, RandomControl -> Real;
NegExp : Time, RandomControl -> Duration;
NegExp : Time, RandomControl -> Time;

Uniform : Real, Real, RandomControl -> Real;
Uniform : Real, Real, RandomControl -> Duration;
Uniform : Real, Real, RandomControl -> Time;
Uniform : Duration, Duration, RandomControl -> Real;
Uniform :
Duration, Duration, RandomControl -> Duration;
Uniform : Duration, Duration, RandomControl -> Time;
Uniform : Time, Time, RandomControl -> Real;
Uniform : Time, Time, RandomControl -> Duration;
Uniform : Time, Time, RandomControl -> Time;

Draw : Real, RandomControl -> Boolean;

Geometric : Real, RandomControl -> Integer;
Geometric : Real, RandomControl -> Duration;
Geometric : Real, RandomControl -> Time;
Geometric : Duration, RandomControl -> Integer;
Geometric : Duration, RandomControl -> Duration;
Geometric : Duration, RandomControl -> Time;
Geometric : Time, RandomControl -> Integer;
Geometric : Time, RandomControl -> Duration;
Geometric : Time, RandomControl -> Time;

Poisson : Real, RandomControl -> Integer;
Poisson : Real, RandomControl -> Duration;
Poisson : Real, RandomControl -> Time;
Poisson : Duration, RandomControl -> Integer;
Poisson : Duration, RandomControl -> Duration;
Poisson : Duration, RandomControl -> Time;
Poisson : Time, RandomControl -> Integer;
Poisson : Time, RandomControl -> Duration;
Poisson : Time, RandomControl -> Time;

RandInt : Integer, Integer, RandomControl -> Integer;
RandInt : Integer, Integer, RandomControl -> Duration;
RandInt : Integer, Integer, RandomControl -> Time;

DefineSeed : Integer -> RandomControl;
GetSeed : Charstring -> Integer;
Seed : RandomControl -> Integer;

Random (RandomControl)

The operator Random is the basic random generator and is called by all the other operators. Random uses the formula

to compute the next value stored in the parameter of type RandomControl. The result from Random is a real random number in the interval 0.0 < Value < 1.0.

Erlang (Mean, N, RandomControl)

The operator Erlang provides random numbers from the Erlang-N distribution with mean Mean. The first parameter Mean should be > 0.0, and the second parameter N should be > 0.

HyperExp2 (Mean1, Mean2, Alpha, RandomControl)

The HyperExp2 operator provides random numbers from the hyperexponential distribution. With probability Alpha it return a random number from the negative exponential distribution with mean Mean1, and with the probability 1-Alpha it returns a random number from the negative exponential distribution with mean Mean2. Mean1 and Mean2 should be > 0.0, and Alpha should be in the range 0.0 <= Alpha <= 1.0.

NegExp (Mean, RandomControl)

The operator NegExp provides random numbers from the negative exponential distribution with mean Mean. Mean should be > 0.0.

Uniform (Low, High, RandomControl)

The operator Uniform is given a range Low to High and returns a uniformly distributed random number in this range.
Low should be <= High.

Draw (Alpha, RandomControl)

The Draw operator returns true with the probability Alpha and false with the probability 1-Alpha. Alpha should be in the range
0.0 <= Alpha <= 1.0.

Geometric (p, RandomControl)

The operator Geometric returns an integer random number according to the geometric distribution with the mean p/(1-p). The parameter p should be 0.0 <= p < 1.0.

Caution!

Since the range of feasible samples from the distribution is infinite and the result type is integer, integer overflow may occur.

Poisson (m, RandomControl)

The operator Poisson returns an integer random number according to the Poisson distribution with mean m. The parameter m should be >= 0.0.

Caution!

Since the range of feasible samples from the distribution is infinite and the result type is integer, integer overflow may occur.

RandInt (Low, High, RandomControl)

This operator RandInt returns one of the values Low, Low+1,..., High-1, High, with equal probability. Low should be <= High.

DefineSeed (Integer) -> RandomControl

Each RandomControl variable, which is used as a control variable for a random generator, has to be initialized correctly so the first bit-pattern used by the basic random function is a legal pattern. This DefineSeed operator takes an integer parameter, which should be an odd value in the range 1 to 32767, and creates a legal bit-pattern. This first value is usually referred to as the seed for the random generator. Using the same seed value, the same random number sequence is generated, which means that the random number sequences are reproducible.

Seed (RandomControl) -> Integer

The Seed operator returns random numbers that are acceptable as parameters to the operator DefineSeed. If many RandomControl variables are to be initialized, the Seed operator may be useful.

GetSeed (Prompt) -> Integer

The GetSeed operator, which is implemented in the data type TextFile (see "The ADT TextFile" ), may be used to read an integer value that is acceptable as parameter to the DefineSeed operator.

Using the Data Type

To use the abstract data type for random number generation you must:

  • Include the definition of the data type using an analyzer include. Usually it is appropriate to include the data type in a text symbol in the system diagram.
  • Define a suitable number of RandomControl variables, one for each random number sequence that is to be used.
  • Initialize the RandomControl variables, either in the variable declaration or in a TASK often placed in the start transition of the process. The operator DefineSeed should be used to initialize a RandomControl variable.
  • Use the RandomControl variables in appropriate random number operators.

Note:

SDL variables can only be declared in processes and will be local to the process instances.

To have global RandomControl variables you may, however, define synonyms of type RandomControl and use them in random generator operators.

Example 518 : Using RandomControl, DefineSeed

SYNONYM Seed1 RandomControl =
DefineSeed(GetSeed(stdin, 'Seed1 : '));

TASK Delay := NegExp(Mean1, Seed1);

This is correct according to SDL as operators only have IN parameters and therefore expressions are allowed as actual parameters. In C it is also an IN parameter and cannot be changed. But as a RandomControl value is an address it is possible to change the contents in that address.

The SDL to C Compiler will, for synonyms that cannot be computed at generation time, allocate a variable and initialize it according to the synonym definition at start-up time. Note that this will be performed before any transitions have been executed.

A typical application of RandomControl synonyms are together with the Seed operator. The Seed operator is used to generate values suitable to initialize RandomControl variables with.

Example 519 : Using RandomControl, Seed

SYNONYM BasicSeed RandomControl =
DefineSeed(GetSeed(stdin, 'Seed : '));

DCL S1 RandomControl :=
DefineSeed(Seed(BasicSeed));
DCL S2 RandomControl :=
DefineSeed(Seed(BasicSeed));

The variety of operators with the same name makes it possible to directly use operators in many more situations. This is called overloading of operators. If, for example, there were only the NegExp version:

NegExp : Real, RandomControl -> Real;

then explicit conversion operators would have been necessary to draw, for example, a Duration value from the negative exponential distribution. The code to draw a Duration value would then be something like:

RealToDuration(NegExp(Mean, Seq))

We have instead introduced several operators with the same name and purpose, but with different combinations of parameter types and result type. So for the NegExp operator discussed above, there is also a version:

NegExp : Real, RandomControl -> Duration;

which is exactly what we wanted.

There is, however, a price to be paid for having overloaded operators. It must be possible for the SDL Analyzer to tell which operator that is used in a particular situation. It then uses all available information about the parameters and what the result is used for. Consider Example 520 below.

Example 520 : Overloaded Operator

TIMER T;
DCL
Mean, Rand Real,
D Duration,
Seq RandomControl :=
DefineSeed(GetSeed('Seed : '));

TASK Rand := NegExp(Mean, Seq);
TASK D := NegExp(Mean, Seq);
TASK D := NegExp(TYPE Real 1.5, Seq);

DECISION NegExp(Mean, Seq) >
TYPE Duration 10.0;
(true) : ....
ELSE :
ENDDECISION;
SET (Now + NegExp(Mean, Seq), T);

  • The first two applications of NegExp are no problem, as the parameter type is given by the type of the Mean variable, and the result type is given by the variable that result is assigned to.
  • In the third NegExp call, the value 1.5 has to be given a qualifier, that is, TYPE Real, as the literal 1.5 may be of type Real, Duration, or Time.
  • In the fourth example it is the result type that cannot be determined if the literal 10.0 was not given with a qualifier.
  • In the fifth example the only + operator that takes Time as left parameter and returns Time (SET should have a Time value as first parameter) is:
"+" : Time, Duration -> Time;
defined in the sort Time. So, both the type for the parameter and the result are possible to determine for the NegExp operator in this example.

Most of these problems can be avoided by using SYNONYMS or variables instead of literal values. This is in most cases a better solution than to introduce qualifiers.

Example 521 : Using SYNONYMS

If, for example, the synonyms:

SYNONYM MeanValue Real = 1.5;
SYNONYM Limit Duration = 10.0;

were defined, the third and fourth NegExp call would cause no problem:

TASK D := NegExp(MeanValue, Seq);
DECISION NegExp(Mean, Seq) > Limit;
(true) : ....
ELSE :
ENDDECISION;

Trace Printouts

Trace printouts are available for the functions in this abstract data type. By assigning a trace value greater or equal to nine (9) using the monitor command Set-Trace, each call to an operator in this data type causes a printout of the name of the operator.

Note:

Each operator returning a random number will call the basic operator Random at least once.

Accessing the Operators from C

The operator for random number generation may be used directly in C by using the name given in the appropriate #NAME directive. Please look at the random.pr file for the #NAME directives.


Abstract Data Types for List Processing

The abstract data types defined in this "package" are intended for processing of linked lists. Linked lists are commonly appearing in applications and are one of the basic data structures in computer science. With these data types, you can concentrate on using the lists and do not have to worry about the implementation details, as all list manipulations are hidden in operators in the data types.

Note:

This data type is not implemented in a way that makes it possible to be used in the SDL Validator. It can be used in OS integrations and with Cmicro, but it is not recommended, due to the risk for memory leaks.

Purpose

Definitions

A queue is a list in which the members are ordered. The ordering is entirely performed by the user. The available operations make it possible to access members of the queue and insert members into or remove members from any position. Furthermore, the operators suppress the implementation aspects. That is, the fact that the queue is implemented as a doubly linked list with a queue head. The operators also prevent the unwary user from trying to access, for instance, the successor of the last member or the predecessor of the first member.

The entities which may be members of a queue are called object instances. An object instance is a passive entity containing user defined information. This information is described in the object description.

In SDL these definitions are implemented using sorts called Queue, ObjectInstance, and ObjectDescr, where ObjectDescr should be defined by the user. ObjectDescr should have the structure given in the example below (Example 522).

The data types for list processing may be included in any SDL system using Analyzer #include statements, where the files containing the definitions of the data types are included. The definitions should be placed in the order given in the example below:

Example 522 : Including ADT for List Processing

/*#include 'list1.pr'*/
NEWTYPE ObjectDescr /*#NAME 'ObjectDescr'*/
STRUCT
SysVar SysTypeObject;
/* other user defined components */
ENDNEWTYPE;
/*#include 'list2.pr'*/

The file list1.pr contains the definition of the sort Queue (and the help sorts ObjectType and SysTypeObject), while the file list2.pr contains the definition of the type ObjectInstance.

Available Sorts

When the data types for list processing are included, two new sorts, Queue and ObjectInstance, are mainly defined, together with the type ObjectDescr defined by the user. The user can declare variables of type Queue and type ObjectInstance, but should never declare a variable of type ObjectDescr.

Variables of the sorts Queue and ObjectInstance are references (pointers) to the representation of the queue or the object instance. In both sorts there is a null value, the literal NULL, which indicates that a variable refers to no queue or no object instance. The default value for Queue and ObjectInstance variables is NULL.

A variable of sort ObjectInstance can refer to a data area containing the components defined in the struct ObjectDescr. The example below shows how to manipulate these components.

Example 523 : ADT for List Processing, Struct ObjectDescr

/*#include 'list1.pr'*/
NEWTYPE ObjectDescr /*#NAME 'ObjectDescr'*/
STRUCT
SysVar SysTypeObject;
Component1 Integer;
Component2 Boolean;
ENDNEWTYPE;
/*#include 'list2.pr'*/

DCL O1 ObjectInstance;

TASK
O1 := NewObject; /* see next section */

TASK
O1!ref!Component1 := 23,
O1!ref!Component2 := false;

TASK
IntVar := O1!ref!Component1,
BoolVar := O1!ref!Component2;

A component is thus referenced by the syntax:

ObjectInstanceVariable ! ref ! ComponentName

Caution!

You should never directly manipulate the component SysVar in the struct ObjectDescr. It contains information about if and how the object instance is inserted into a queue and should only be used by the queue handling operators.

Assignments and test for equality may be performed for queues and for object instances. The assignments:

Q1 := Q2; O1 := O2;

mean that Q1 now refers to the same queue as Q2 and that O1 now refers to the same object instance as O2. Assignment is thus implemented as copying of the reference to the queue (and not as copying of the contents of the queue). The same is true for object instances.

The test for equality is in the same way implemented as a test if the left and right hand expression reference the same queue or the same object instance (and not if two queue or object instances have the same contents).

Due to the order in which the sorts are defined, a component of sort Queue can be a part of the ObjectDescr struct, while components of type ObjectInstance cannot be part of ObjectDescr.

If you want several different types of objects in a queue, with different contents, the #UNION directive (see "Union" ) may be used according to the following example:

Example 524 : Unions and Queues

NEWTYPE Ob1 STRUCT
Comp1Ob1 integer;
Comp2Ob1 boolean;
ENDNEWTYPE;

NEWTYPE Ob2 STRUCT
Comp1Ob2 character;
Comp2Ob2 charstring;
ENDNEWTYPE;

NEWTYPE Ob /*#UNION*/ STRUCT
Tag integer;
C1 Ob1;
C2 Ob2;
ENDNEWTYPE;

NEWTYPE ObjectDescr /*#NAME 'ObjectDescr'*/
STRUCT
SysVar SysTypeObject;
U Ob;
/*#ADT (X)*/
ENDNEWTYPE;

The components may now be reached using:

O1 ! ref ! U ! Tag
O1 ! ref ! U ! C1 ! Comp1Ob1
O1 ! ref ! U ! C2 ! Comp2Ob1

Available Operators

Operators in the Sort Queue

In the sort Queue, the following literals and operators are available:

null
NewQueue

Cardinal : Queue -> Integer;
DisposeQueue : Queue -> Queue;
Empty : Queue -> Boolean;
FirstInQueue : Queue -> ObjectInstance;
Follow :
Queue, ObjectInstance, ObjectInstance -> Queue;
IntoAsFirst : Queue, ObjectInstance -> Queue;
IntoAsLast : Queue, ObjectInstance -> Queue;
LastInQueue : Queue -> ObjectInstance;
Member : Queue, ObjectInstance -> Boolean;
Precede :
Queue, ObjectInstance, ObjectInstance -> Queue;
Predecessor : ObjectInstance -> ObjectInstance;
Remove : ObjectInstance -> ObjectInstance;
Successor : ObjectInstance -> ObjectInstance;

Operators in the Sort ObjectInstance

In the sort ObjectInstance, the following literals and operators are available:

null
NewObject

DisposeObject: ObjectInstance -> ObjectInstance;

The operators defined in the sorts Queue and ObjectInstance have the behavior described below. All operators will check the consistency of the parameters. Each queue and object instance parameter should, for example, be /= null. If an error is detected the operator will cause an SDL dynamic error that will be treated as any other dynamic error found in an SDL system.

NewQueue: -> Queue

The literal NewQueue is used as an operator with no parameters and returns a reference to a new empty queue. The data area used to represent the queue is taken from an avail stack maintained by the list processing sorts. Only if the avail stack is empty new dynamic memory is allocated.

Cardinal: Queue -> Integer

This operator takes a reference to a queue as parameter and returns the number of components in the queue.

DisposeQueue: Queue -> Queue

This operator take a reference to a queue as parameter and returns all object instances and the data area used to represent the queue to the avail stack mentioned in the presentation of NewQueue. DisposeQueue always returns the value null.

Note:

Any references to an object instance or to a queue that is returned to the avail stack is now invalid and any use of such a reference is erroneous and has an unpredictable result.

Empty: Queue -> Boolean

This operator takes a reference to a queue as parameter and returns false if the queue contains any object instances. Otherwise the operator returns true.

FirstInQueue: Queue -> ObjectInstance

This operator takes a reference to a queue as parameter and returns a reference to the first object instance in the queue. If the queue is empty, null is returned.

Follow: Queue, ObjectInstance, ObjectInstance -> Queue

Follow takes a reference to a queue and to two object instances and inserts the first object instance directly after the second object instance. It is assumed and checked that the second object instance is a member of the queue given as parameter, and that the first object instance is not a member of any queue prior to the call.

Note:

The operator Member is used to check that the second object instance is member of the queue.

IntoAsFirst: Queue, ObjectInstance -> Queue

This operator takes a reference to a queue and to an object instance and inserts the object instance as the first object in the queue. The queue given as parameter is returned as result from the operator. It is assumed and checked that the object instance is not a member of any queue prior to the call.

IntoAsLast: Queue, ObjectInstance -> Queue

This operator takes a reference to a queue and to an object instance and inserts the object instance as last object in the queue. The queue given as parameter is returned as result from the operator. It is assumed and checked that the object instance is not a member of any queue prior to the call.

LastInQueue: Queue -> ObjectInstance

This operator takes a reference to a queue as parameter and returns a reference to the last object instance in the queue. If the queue is empty, null is returned.

Member: Queue, ObjectInstance -> Boolean

This operator takes a reference to a queue and to an object instance and returns true if the object instance is member of the queue, otherwise it returns false.

Precede: Queue, ObjectInstance, ObjectInstance-> Queue

Precede takes a reference to a queue and to two object instances and inserts the first object instance directly before the second object instance. It is assumed and checked that the second object instance is a member of the queue given as parameter, and that the first object instance is not a member of any queue prior to the call.

Note:

The operator Member is used to check that the second object instance is member of the queue.

Predecessor: ObjectInstance -> ObjectInstance

This operator takes a reference to an object instance and returns a reference to the object instance immediately before the current object instance. If the object instance given as parameter is the first object in the queue, null is returned. It is assumed and checked that the object instance given as parameter is a member of a queue.

Remove: ObjectInstance -> ObjectInstance

Remove takes a reference to an object instance and removes it from the queue it is currently a member of. A reference to the object instance is returned as result from the operator. It is assumed and checked that the object instance given as parameter is a member of a queue.

Successor: ObjectInstance -> ObjectInstance

This operator takes a reference to an object instance and returns a reference to the object instance immediately after the current object instance. If the object instance given as parameter is the last object in the queue, null is returned. It is assumed and checked that the object instance given as parameter is a member of a queue.

NewObject: -> ObjectInstance

The literal NewObject is used as an operator with no parameters and returns a reference to a new object instance, which is not member of any queue. The data area used to represent the object instance is taken from an avail stack maintained by the list processing sorts. Only if the avail stack is empty new dynamic memory is allocated.

DisposeObject: ObjectInstance -> ObjectInstance

This operator take a reference to an object instance as parameter and returns it to the avail stack mentioned above. DisposeObject always returns the value null.

Note:

Any references to an object instance that is returned to the available stack are now invalid and any use of such a reference is erroneous and has an unpredictable result.

Examples of Use

In this section a number of examples will be given to give some indications of how to use the list processing "package". The following sort definitions are assumed to be included in the system diagram:

/*#include 'list1.pr' */

NEWTYPE ObjectDescr /*#NAME 'ObjectDescr'*/
STRUCT
SysVar SysTypeObject;
Number Integer;
Name Charstring;
ENDNEWTYPE;

/*#include 'list2.pr' */

Example 525 : Creating a Queue

To create a new queue and insert two objects in the queue, so that the first object has Number = 23 and Name = 'xyz' and the second object has Number = 139 and Name = 'Telelogic', you could use the following code (assuming appropriate variable declarations):

TASK
Q := NewQueue,
O1 := NewObject,
O1!ref!Number := 23,
O1!ref!Name := 'xyz',
Q := IntoAsFirst(Q, O1),
O1 := NewObject,
O1!ref!Number := 139,
O1!ref!Name := 'Telelogic',
Q := IntoAsLast(Q, O1);

Example 526 : Removing from Queue

To remove the last object instance from a queue, assuming the queue is not empty, you could use the following code:

TASK
O1 := Remove(LastInQueue(Q));

Example 527 : Looking in Queue

You may look at the component Name in the first object instance in the queue in the following way:

TASK
O1 := FirstInQueue(Q),
StringVar := O1!ref!Name;

or if the reference to O1 is not going to be used any further

TASK
StringVar := FirstInQueue(Q)!ref!Name;

Example 528 : Searching in Queue

The result of the following algorithm is that O1 will be a reference to the first object instance that has the value IntVar in the component Number. If no such object is found O1 is assigned the value null.

TASK O1 := FirstInQueue(Q);
NextObject:
DECISION O1 /= null;
(true) :
DECISION O1!ref!Number /= IntVar;
(true):
TASK O1 := Successor(O1);
JOIN NextObject;
(false):
ENDDECISION;
(false):
ENDDECISION;

Example 529 : Removing Duplicates from Queue

The algorithm below removes all duplicates from a queue (and returns them to the avail stack). A duplicate is here defined as an object instance with the same Number as a previous object in the queue.

TASK O1 := FirstInQueue(Q);
NextObject:
DECISION O1 /= null;
(true) :
TASK O2 := Successor(O1);
NextTry:
DECISION O2 /= null;
(true):
DECISION O1!ref!Number = O2!ref!Number;
(true):
TASK Temp := O2,
O2 := Successor(O2),
Temp := DisposeObject (
Remove(Temp));
(false):
TASK O2 := Successor(O2);
ENDDECISION;
JOIN NextTry;
(false):
TASK O1 := Successor(O1);
JOIN NextObject;
ENDDECISION;
(false) :
ENDDECISION;

Connection to the Monitor

Trace printouts are available for the operators in this abstract data type. By assigning a trace value greater or equal to eight (8) using the monitor command Set-Trace, each call to an operator in this data type causes a printout of the name of the current operator. Note that some of the operators may call some other operator to perform its task.

You may use the monitor command Examine-Variable to examine the values stored in a variable of type ObjectInstance. By typing an additional index number after the variable Queue the value of the ObjectInstance at that position of the queue is printed.

Accessing List Operators from C

The sorts Queue, ObjectInstance, and ObjectDescr, and all the operators and the literals NewQueue and NewObject have the same name in C as in SDL, as #NAME directives are used. The literal null is the sort Queue and is translated to QueueNull(), while the literal null in sort ObjectInstance is translated to ObjectInstanceNull().

In C you access a component in an ObjectInstance using the -> operator:

OI_Var -> Component

As an example of an algorithm in C, consider the algorithm in Example 528. A reference to the first object instance that has the value IntVar in the component Number is computed:

#(O1) = FirstInQueue(#(Q));
while ( #(O1) != ObjectInstanceNull () ) {
if ( #(O1)->Number == #(IntVar) ) break;
#(O1) = Successor(#(O1));
}


Abstract Data Type for Byte

In this section an abstract data type for byte, i.e. unsigned char in C, is presented. This ADT can be used also in OS integrations and with Cmicro. However, please see the note below.

Note:

This ADT is only provided for backward compatibility, as the new predefined data type Octet should be used instead of Byte.

Purpose

The purpose of this data type is of course to have the type byte and the byte operations available directly in SDL.

The data type becomes available by including the file containing the definition with an analyzer included in an appropriate text symbol.

Example 530 :

/*#include 'byte.pr' */

Available Operators

The following operators are available in this data type:

BAND: byte, byte -> byte

Bitwise and. Corresponds to C operator &

BOR: byte, byte -> byte

Bitwise or. Corresponds to C operator |

BXOR: byte, byte -> byte

Bitwise exclusive or. Corresponds to C operator ^

BNOT: byte -> byte

Unary not. Corresponds to C operator ~

BSHL: byte, integer -> byte

Left shift of the byte parameter the number of steps specified by the integer parameter. Corresponds to C operator <<

Implementation:

(byte)( (b << i) & 0xFF )

BSHR: byte, integer -> byte

Right shift of the byte parameter the number of steps specified by the integer parameter. Corresponds to C operator >>

Implementation: ( b >> i)

BPLUS: byte, byte -> byte

Byte plus (modulus 0xFF). Corresponds to C operator +

BSUB: byte, byte -> byte

Byte minus (modulus 0xFF). Corresponds to C operator -

BMUL: byte, byte -> byte

Byte multiplication (modulus 0xFF). Corresponds to C operator *

BDIV: byte, byte -> byte

Byte division. Corresponds to C operator /

BMOD: byte, byte -> byte

Byte modulus. Corresponds to C operator %

BHEX: charstring -> byte

This operator transforms a charstring ('00' - 'ff' or 'FF') into a byte. The string may be prefixed with an optional '0x'.

I2B: integer -> byte

I2B transforms an integer in range 0 - 255 into a byte.

B2I: byte -> integer

B2I transforms a byte into an integer.


Unsigned (and Similar) Types

There are three files called:

unsigned.pr
unsigned_long.pr
longint.pr

where three SDL sorts implemented in C as unsigned, unsigned long, and long int may be found. All these types are in SDL implemented as syntypes of integer. For more information please see the definitions of the data types.

Note:

These ADTs are only provided for backward compatibility, as is recommended to use the types in the package ctypes instead. The package ctypes is discussed first in this chapter.


How to Obtain PId Literals

This section describes a way to obtain PId literals for static process instances. PId literals will make it possible to simplify the start-up phase of an SDL system, as direct communication (OUTPUT TO) may be used from the very beginning. It is otherwise necessary to start sending signals without TO, as the only PId values known at the beginning are the Parent - Offspring relations.

Note:

This ADT cannot be used in OS integrations or with Cmicro. There are, however, a special version for OS integrations that can be found in the directory for the OS integration, and a special version for Cmicro that can be found in the Cmicro installation directory.

Note:

PId literals cannot be created for processes within block types or system types.

Purpose

In SDL the only way to obtain a PId value is to use one of the basic functions Self, Parent, Offspring, or Sender. Such values may then, of course, be passed as parameters in signals, in procedure calls and in create operations.

During system start-up there is no way to obtain the PId value for a static process instance at the output that starts a communication session. The receiver of the first signal must therefore be implicit, by using an output without TO.

To be able to handle outputs without TO, in SDL-92 types and in separate generated units, complete knowledge about the structure of channels and signal routes must be known at run-time. The same knowledge is also necessary if we want to check that there is a path from the sender to the receiver in an output with TO. As the information needed about channels and signal routes requires substantial amounts of memory, it would be nice, in applications with severe memory requirements, to be able to optimize this.

To remove all information about channels and signal routes from a generated application means two things:

  1. Output without TO cannot be used in SDL-92 types or in separate generated units.
  2. It is not possible to check that there is a path between the sender and the receiver at an output with TO.

The second limitation is no problem as this is the way we probably want it in a running application (during debugging the test ought to be used, but not in the application).

The first limitation, that output without TO cannot be used, is however more difficult. In an SDL system not using the OO concepts (block type, process type, and so on) and not using separate generation there are no problems, but otherwise such outputs are necessary at the system start-up phase to establish communication between processes in different blocks. The purpose of this abstract data type is to provide a way to establish PId literals and thereby to be able to avoid outputs without TO.

The Data Type PIdLit

Caution!

The PIdLit data type should only be used in the way described here to introduce synonyms referring to static process instances. Other usage may not work!

If you are using this data type in a system that is to be validated using the SDL Validator there are two additional requirements:

  • Only process types with the number of instances equal to (N,N) for N>0, may be referenced in PId_Lit operators.
  • No process type with the number of instances equal to (N,N) for N>0, may contain a Stop symbol, independently if a PId_Lit operator is used for the process type or not.

The data type PIdLit contains the following operators:

PId_Lit : xPrsIdNode -> PId;
PId_Lit : xPrsIdNode -> PIdList;
PId_Lit : xPrsIdNode, Integer -> PId;

In the file containing the data type (pidlist.pr) there is also a synonym that you may use to access the environment:

SYNONYM EnvPId PId = ...;

The type xPrsIdNode corresponds to the C type xPrsIdNode, which is used to refer to the process nodes in the symbol table tree built up by a generated application.

Use the first version of PId_Lit to obtain a synonym referring to the process instance of a process instance set with one initial instance.

Use the second version of PId_Lit to obtain a synonym of array type referring to the process instances of a process instance set with several initial instances.

Use the third version of PId_Lit to obtain a synonym referring to one of the process instances of a process instance set with several initial instances.

To introduce PId literals implemented as SDL synonyms, follow the steps below:

  1. Include the file pidlist.pr, which contains the implementation of the PIdList type, among the declarations in the system:
/*#include 'pidlist.pr' */

  2. Identify which process instance sets that should have PId literals.
  3. Introduce #NAME directives for these process instance sets.
  4. Insert a #CODE directive among the declarations in the system. If. however, separate generation is not used, this #CODE directive need not be included.
/*#CODE
#HEADING
extern XCONST struct xPrsIdStruct
yPrsR_ProcessName1;
extern XCONST struct xPrsIdStruct
yPrsR_ProcessName2;
extern XCONST struct xPrsIdStruct
yPrsR_ProcessName3;
*/

There should be an external definition for each process instance set identified in step 2. ProcessNameX should be replaced by the name introduced in the #NAME directives for the processes.
  5. For each process instance set that should have PId literals, introduce the following synonym definition in the system diagram.
    If the process type has one initial instance:
SYNONYM Name1 PId =
PId_Lit(#CODE('&yPrsR_ProcessName1'));

If the process type has several initial instances:
SYNONYM Name2 PIdList =
PId_Lit(#CODE('&yPrsR_ProcessName2'));

If the process type has several initial instances, but only one of them should be possible to refer to by a synonym:
SYNONYM Name3 PId =
PId_Lit(#CODE('&yPrsR_ProcessName3'), No);
where No should be the instance number, that is, if No is 2, then the synonym Name3 should refer to the second instance of the process type.
Of course, you may choose the names of the synonyms, but the string in the #CODE directive should be the xPrsIdNode variables in the extern definitions discussed in step 4 above.
  6. You may now use the synonyms of type PId that you defined in step 5 in expressions of PId type, for example as a receiver in the TO clause in an output. The synonym EnvPId, which refers to an environment process instance, can be used in the same way.
    Synonyms of type PIdList may be indexed (as an array) by an integer expression to obtain a PId value and may then be used in the same way as the synonyms of type PId. Indexes should be in the range 1 to the number of initial instances.

Example 531 : PIdList Data Type

OUTPUT Sig1 TO Name1;
OUTPUT Sig2 TO Name2(2);
OUTPUT Sig3 TO Name2(InstNo);
OUTPUT Sig4 TO EnvPId;
DECISION (Name3 = Sender);
TASK PId_Variable := Name2(1);
where InstNo is an integer variable or synonym and PId_Variable is a variable of type PId.

Note:

Note that no index check will be performed when indexing a PIdList synonym.


General Purpose Operators

Introduction

The abstract data type IdNode described in this section introduces a number of operators that may be used to simplify an SDL system. The simplifications will give both reduced code size and higher speed of execution for your application, as well as make debugging easier. This ADT cannot be used in OS integrations or with Cmicro.

The operators may be grouped into two groups:

  • "Almost SDL operations", that is, operators that are easy to understand in an SDL context, but which are not available in SDL. Examples are the possibility to enumerate all active instances of a certain process instance set, or to count the number of signals in an input port.
  • Operators that handle implementation aspects. An example is an operator to reuse memory in avail lists.

Caution!

Be very careful using these operators, as you will then not be designing true SDL systems.

If the SDL description is a goal in itself you should not use the operators. If the SDL system is just a means to obtain something else, an application for example, the operators may be very useful.

Type IdNode

This abstract data type becomes available by inserting the analyzer include:

/*#include 'idnode.pr'*/

This abstract data type file introduces three SDL sorts called PrsIdNode, PrdIdNode, and SignalIdNode in SDL. These sort correspond to the types xPrsIdNode, xPrdIdNode, and xSignalIdNode in C, which are used to represent the symbol table in the generated application. The symbol table, which is a tree, will contain the static information about the SDL system during the execution of the generated program.

Is is possible to refer to processes, procedures, and signals (among others) using the following the names:

yPrsN_ProcessName or &yPrsR_ProcessName
yPrdN_ProcedureName or &yPrdR_ProcedureName
ySigN_SignalName or &ySigR_SignalName

where ProcessName, ProcedureName, and SignalName should be replaced by the name of the process, procedure, or signal with prefix, or by the name given to the unit in a #NAME directive. To obtain a name of a unit with prefix the directive #SDL may be used:

yPrsN_#(ProcessName) or &yPrsR_#(ProcessName)

To avoid problems when separate generation is to be used, the &yPrsR_... syntax is recommended.

The #SDL directive is not always possible to use. It will look for an entity with the specified name in the current scope unit (where the #SDL directive is used) and outwards in the scope hierarchy. So, for example, if the reference for a process is to be used in a process defined in another block, a #SDL directive cannot be used for the referenced process. The name of the referenced process ought then to be given in a #NAME directive.

If separate generation is used there may be more problems to access these references. The variables will be defined in the compilation unit where the entity they represent is defined.

  • The xPrsIdNode for a process will be defined in the file containing the code for the block enclosing the process.
  • The xPrdIdNode for a procedure will be defined in the file containing code for the enclosing unit.
  • The xSignalIdNode for a signal will be defined in the file containing code for the enclosing system, block, or process.

A reference is visible in the compilation unit (file) where it is defined and in all subunits to the unit, as a compilation unit will include the .h file of all its parent units.

Problems occur when we want to use a reference in a place where it is not visible, for example using an xPrsIdNode for a process defined in a separate block, in a process in another block. All references are, however, extern, which makes it possible for a user to introduce an appropriate extern definition (in a #CODE directive) himself in the compilation units where it is needed.

Example 532

/*#CODE
#HEADING
extern XCONST struct xPrsIdStruct yPrsR_ProcessName;
*/

To know the name of the referenced process, a #NAME directive ought to be used.

Note:

Such extern definitions introduce dependencies between otherwise independent compilation units. It is your responsibility completely to maintain these dependencies.

Available Operators

GetIdNode: PId -> PrsIdNode;

This operator takes a PId value and returns a reference to the PrsIdNode that represents the process type. PrsIdNode values are not useful for anything except as parameters to the operators discussed here.

Kill: PId -> PId;

The Kill operator can be used to stop another process instance. In SDL a process instance may only stop itself. This operator has exactly the same effect as if the process instance given as parameter executed a stop operation. The Kill operator always returns the value null.

KillAll: PrsIdNode -> Integer;

This operator takes a reference to an PrsIdNode representing a process type and will kill all the instances of the specified process type. The effect is the same as if all the instances executed stop operations. The operator returns the number of "killed" process instances.

FirstPId: PrsdNode -> PId;

See "SucPId: PId -> PId;" (next).

SucPId: PId -> PId;

This operator, together with FirstPId, are intended to be used to enumerate all process instances of the process type referenced by the PrsIdNode given as parameter to FirstPId. FirstPId should be given a reference to an PrsIdNode for a process type and returns the first (last created) process instance. SucPId should be given a PId value and will return the next PId for the given process type.

Note:

During the enumeration of the process instances, no action that stops any instance of the enumerated process type may be executed.
This means, for example, that the complete enumeration should take place in one transition and that Kill operations should not be used in the enumeration.

InputPortLength: PId -> Integer;

This operator returns the number of signals in the input port of the given process instance.

InputPortLength: PId, SignalIdNode -> Integer;

This operator returns the number of signals, of the signal type given as IdNode parameter, that are present in the input port of the given process instance. The SignalIdNode parameter should refer to a SignalIdNode that represents a signal or a timer.

NoOfProcesses: PrsIdNode -> Integer;

This operator should be given a reference to an PrsIdNode representing a process instance set and will return the number of active instances of this instance set.

IsStopped: PId -> Boolean;

The operator may be used to determine if a PId value refers to a process instance that is active or has executed a stop operation.

Broadcast: PrsIdNode, SignalIdNode, PId -> Integer;

This operator may be used to send one signal (without parameters) to each active process instance of a specified process instance set. The value of the third parameter, of type PId, will be used as sender in the signals. The result of the operator is the number of signals that are sent during this operation, i.e. the number of active process instances of the specified type.

Note:

When you use this operator you hide signal sending in an expression in, for example, a task. This will decrease the readability of your SDL description, and should be well documented, at least with a comment.

FreeAvailList: PrsIdNode -> Integer and PrdIdNode -> Integer and SignalIdNode -> Integer

Note:

The FreeAvailList operator has no meaning in the SDL Validator. It can be used but will in the Validator be a null action.

The operator takes a reference to an IdNode (of one of the three type above) that represents a process, a procedure, or a signal and returns the memory in the avail list for the specified IdNode to the free memory by calling the sctOS function xFree. The function xFree uses the C standard function 'free' to release the memory. The FreeAvailList operator requires thus that free really releases the memory in such a way that it can be reused in subsequent memory allocations. Otherwise the operator is meaningless.

FreeAvailList is intended to be applied for reusing memory allocated for processes, procedures, and signals used only during a start-up phase. If the system, for example, contains a process used only during start-up, that is, all instances of this process perform stop actions early during the execution and no more processes will be created later, then the memory for these instances can be reused.

Caution!

This operator should only be used as one of the last resorts in the process of minimizing the memory requirements of an application.

Connection to Monitor

In the trace output, operators like Kill and Broadcast will produce trace messages exactly in the same way as the equivalent Stop operation and the sequence of Output operations.


Summary of Restrictions

The table below summarizes the restrictions concerning the usability of the various Abstract Data Types that are delivered with the SDL suite.

Sim.
Real-Time Sim.
Perf. Sim.
Sim. with env.
Appl.
with
Cadv.
Valid.

 list1, list2
3
3
3
3
3
?

 file
3
3
3
3
*
*

 random
3
3
3
3
3
*

 pidlist
3
3
3
3
3
*

 idnode
3
3
3
3
3
3

 byte
3
3
3
3
3
3

 longint
3
3
3
3
3
3

 unsigned
3
3
3
3
3
3

 unsigned_long
3
3
3
3
3
3

Table Legend:

3 Compatible

? Incompatible

* Meaningless combination, or restrictions. See the respective section for more information.


63 The Performance Library

This chapter presents an overview of a method for performance simulation projects using the Performance Library. The Performance Library is available as an optional product.

The method is in no way complete or described in all details. The intention is not to describe the method itself in depth, but rather to present an application area for the SDL suite. For more details about performance simulations in general, please refer to the literature in that field.


A Performance Simulation Project

To develop a performance simulation and use it to obtain estimates about a particular system involves a number of steps. The SDL suite may be helpful in many, but not all, of these steps.

The major activities in a performance simulation project are:

  1. Collect information about the behavior of the system to be simulated and define the purpose of the simulation, that is, what estimates should be the result of the project?
  2. Create a performance model for the system. This is often expressed as a queuing network. As the behavior of a system is usually too complex to be simulated in all details, simplifications have to be made.
    This modeling phase is the most critical phase in the complete project. A good performance model leads to relevant results, while a bad model leads to nonsense. The key question is what simplifications and abstractions you may make and still obtain relevant results from simulations of the model.
  3. Describe the performance model in detail in SDL and simulate it, using the library Simulation, until the SDL model behaves satisfactorily.
  4. Execute the generated simulation a number of times to collect statistical data from the model.
    You will normally need 10,000 to 50,000 samples (of for example a queue length or a waiting time) to obtain any significance in the data. This means that program executions will be fairly long. There are two ways to execute the performance simulation:
    • Use the library Simulation and start by performing the monitor commands "Set-Trace 0" and "Go", or
    • Use the library PerformanceSimulation. It is specially designed to execute performance simulations and does not include the monitor system. It will execute the performance simulation in the order 10 to 15 times faster than executing it using the library Simulation.
  5. During the execution of the performance simulation, the best way to handle data measured in the system is to write the data on file. You may then analyze the data files using packages or programs for statistical analysis to obtain, for example, mean value, variance and confidence intervals for these estimates. (The SDL suite does not provide means for statistical analysis.)
  6. To validate these estimates it is common practice to compare the simulation results with results from mathematical methods applied on the system (simplified versions of the system). Queuing theory and the theory for queuing networks are the most relevant mathematical methods for such activities.

Some of these steps will discussed in more detail in the following subsections. For other aspects please see literature about performance simulations.


The Performance Model

Let us first state that a description of the functional behavior of a system and a performance model of the same system are (usually) not the same, even if both models can be expressed in SDL. The two models describe two different aspects of the same system. This is why there is a modeling phase in the development of the performance simulation.

Queuing Models

Most performance models can be viewed as queuing models or queuing networks, where a queuing network is an interconnected system of queuing models. A typical model for a queue would look like:

Figure 554 : A queue model

The model contains jobs that need some service from the server. The jobs may have to wait in a queue for the service. The basic properties of this model are:

  • The service time for a job. This can be modeled as a property of the job or of the server, depending on the system to be simulated.
  • The queue discipline, that is, the order in which jobs are inserted into the queue and removed from the queue to get service. Typical disciplines are, to mention a few:
    • FCFS (First Come - First Served)
    • Priority order according to the priority of the jobs
    • Priority order with pre-emption.
  • The inter-arrival time for jobs, or more generally: when new jobs are entered into the queue. The creation of new jobs is usually modeled in job-generators described as separate objects.

The queue model is a general model that may be used as an abstraction in many situations, for example to model programs (jobs) that are to be executed by the CPU in a computer (server). The queue is then the scheduled list of jobs that are in a "ready to execute" state. The queuing discipline is usually complex, involving for example priorities, pre-emption and cyclic execution of jobs.

Another quite different example would be a port, where ships (jobs) are coming for loading or unloading (the service). To perform loading or unloading the ship needs a crane (the server).

The systems that we want to simulate are usually not simple enough to be modeled by just one queue. However, models using interconnected queues-servers, connected in such a way that jobs leaving one server are inserted into the queue of another, have the power to describe many interesting real systems. An example of a simple queuing network model is given in Figure 555.

Figure 555 . Simple queuing network

Each node in the network consists of one or several servers. The network also contains places where jobs are entered into the system and places where jobs are leaving the system.

Measurements

In a queue model or a queuing network model it is of interest to estimate for example:

  • For jobs: total time in system, total waiting time
  • For servers: load
  • For queues: average and maximum queue length.

Such estimates can be obtained in two ways, using mathematical theories like queuing theory, or by measurements in simulations. With the mathematical theories, rather complicated models can be analyzed, usually more complicated than a nonspecialist thinks is possible. You should investigate this possibility before taking the decision to implement a simulation program.


Implementation of the Model

Mapping of Queue Models to SDL

A queuing network model may easily be described in SDL. Appropriate mapping rules are, for example:

  • A server is implemented as a process and the queue as a variable in the server process.
  • Jobs are described as data objects, that is, as passive entities that can be inserted into queues.
  • Job generators are implemented as processes.
  • Signals, with jobs as parameters, are used to send the jobs from job generators to servers and from servers to other servers.

Abstract Data Types for Queues and Random Numbers

In the implementation of the model there will be extensive use of queues and jobs and of queue manipulations, for example inserting a job into a queue. The 62 The ADT Library provides an abstract data type specially designed for this purpose. See "Abstract Data Types for List Processing" .

The ADT library also contains an abstract data type that can be used to generate random numbers. This data type can, for example, be used to draw job lengths and inter-arrival times according to a given distribution. See "Abstract Data Type for Random Numbers" .

Random numbers are, in most situations in a performance simulation, used to model time intervals (for example service time required for a job) or to model a number of something (the number of jobs to be generated by a job generator at a certain time). The abstract data type for random numbers therefore contains the possibility to generate random numbers according to distributions returning non-negative values, for example:

  • Negative exponential distribution
  • Erlang distribution
  • Hyperexponential distribution
  • Uniform distribution
  • Poisson distribution.

Implementation of Job Generators and Servers

To give a better understanding of job generators and servers, two process graphs are presented in Figure 556 and Figure 557, showing simple but typical processes.

A job generator sets a timer, and when the timer time expires, it generates a new job, sends it into the queuing system and sets the timer again. The time value in the set statements is usually Now + some random time interval. Note that the data types Queue and ObjectInstance are defined in the abstract data types for queue handling that are included in the ADT library (see "Abstract Data Types for List Processing" ).

Figure 556 : A job generator

Figure 557 : A server with a queue

The most important observation concerning the server process, is that the act of giving service is modeled by letting the server process wait in the state Busy. It is thus only the time needed for the service that is modeled. Otherwise the process is rather straight forward. The variable Job is used to refer to the job that is currently given service and the variable Q is used to store other jobs waiting for service. The queuing discipline will be implemented in the details in the tasks "Next to be served in Q", "Insert Job in Q" and "Remove Job from Q".

I/O and Performance Simulations

A performance simulation uses I/O mainly for two things:

  1. Writing measurements on file
  2. Prompting for parameters to the simulation.

A specially designed abstract data type for the purpose of simplifying I/O is included in the ADT library (see "Abstract Data Type for File Manipulations and I/O" ). With this data type it is possible to open files and to perform read and write operations in SDL.

It is, of course, interesting to parameterize a performance simulation on, for example, seed values for random generators, mean values for inter-arrival times and service times.

These values should be read at simulation start-up time. In SDL the concept of external synonyms can be used for such a purpose. As synonyms can only be defined in processes, not in instances, it is difficult to handle cases when the process instances should have different values for a certain simulation parameter. In such cases the abstract data type for I/O operations can be useful.

The second category of I/O mentioned above is printing of measurement data. There are basically two different types of measurements that have to be handled in a performance simulation.

  1. Data concerning jobs such as waiting times.
    It is usually best to store this type of data in the job itself, until the job leaves the system, when the appropriate values are printed on a file.
  2. Queue lengths and other related data.
    Such data is easiest to handle by introducing measurement processes that with regular time intervals print the queue lengths on file.

The best way to obtain the queue lengths is, in most situations, to let the measurement process view (or import) the appropriate queue variables. Otherwise a signal interface must be implemented only for measurement purposes.

The reason for printing all measurement data on file is that it is difficult to compute the relevant statistical entities at simulation time. If only the mean values are of interest, these are simple to compute, but if variances and confidence intervals are to be computed it is better to let a professional statistical tool perform the job.

Note that data series produced from a simulation contains dependent data. If, for example, a job has been subject to a long waiting time, then the probability is high that the next job will also have a long waiting time.

Exit from a Simulation

The appropriate way to terminate the execution of a performance simulation is to call the function SDL_Halt(). It is best performed by introducing the call in a #CODE directive in a task symbol (see "Including C Code in Task - Directive #CODE" ). SDL_Halt is a function in the run-time library with the following prototype:

void SDL_Halt (void);

Execution with the Library Performance Simulation

As mentioned earlier, you may use the library PerformanceSimulation to speed up the execution of a performance simulation. This library has the same properties as the library Simulation, except that it does not contain the monitor system, which may increase the execution speed by a factor of 10 to 15.

Use the library Simulation to debug and verify the simulation model. Then select the library PerformanceSimulation in the make dialog in the Organizer (see "Make" ) and press the button Make. The thereby generated performance simulation may be executed from the OS as an ordinary program.


64 Integration with Operating Systems

This chapter describes how to integrate code generated by the Cadvanced SDL to C Compiler with operating systems.

The different integration models (Light Integration, Threaded Integration and Tight Integration) are explained in the introduction.

There is a separate annex for each supported RTOS where the OS specific parts are described.

Important!

You are free to reuse the integrations supplied by Telelogic or modify them to your needs. The OS integrations are tested by Telelogic but Telelogic does not guarantee that they will perform in your specific target environment (hardware, CPU, RTOS version etc.). Please refer to "RTOS integrations for information about host and target environments where the integration types have been developed and tested.

Light and Threaded integrations

The Light and Threaded integrations are included in the delivery.

The standard product support and maintenance agreement only includes support for the Light and Threaded integrations available from Telelogic if no changes have been made to the integrations.

Tight Integration

The Tight integration is meant to serve as a template, to be adapted to your needs. It is available for you as a free download from the Telelogic Support web site.

The standard product support and maintenance agreement does not assist in adapting to your target environment.
Customer specific OS integrations
All OS integration models can be supported, enhanced and customized by using Telelogic's Professional Services.
Other integrations
Telelogic has developed a large number of integrations based on the company's vast experience of integrating with all operating systems on the market.


Introduction

The code that is generated by the Cadvanced SDL to C compiler is designed to run on different platforms. This is done by letting all platform dependent concepts be represented by C macros that can be expanded appropriately for each environment. There are also types used in the generated code that have to be defined. Integration, as referred to in this chapter, is the process of adapting the generated code to a certain platform.

This chapter describes the different models that are supported in Telelogic Tau.

Note:

Throughout this chapter, annexes excluded, VxWorks terminology has been used whenever there are differences between operating systems. Particularly, this means that the term task has been used on several occasions. The corresponding term would be thread for Win32 and Solaris, process for OSE Delta, and task for Nucleus.

Different Integration Models

With Cadvanced, there are three different run-time models, called Light Integration, Threaded Integration and Tight Integration. Tight integrations are then divided into two submodels, the Standard model and the Instance-Set model. All models use the same generated code.

You will find descriptions of the different models below, as well as guidelines for choosing between them.

Light integration

The simplest case is called a Light integration because only a minimum of interaction with the operating system is required; a Light integration could even run on a target system without any OS at all.

The complete SDL system runs as a single OS task. Scheduling of SDL processes is handled by the standard kernel, running a complete state transition at a time (no preemption). Worst case scheduling latency is thus the duration of the longest transition.

Communication between SDL processes is handled by the kernel; communication between the SDL system and the environment is handled in the two user supplied functions xInEnv() and xOutEnv(). These functions are platform dependent. See Figure 558.

Figure 558 : Signalling in the Light Integration Model.

An SDL process sends one internal and one external signal. xOutEnv() must be written to call the OS send primitive. Thick borders denote OS tasks.

Other properties of a Light Integration:

  • The scheduling order can be controlled by process priorities and/or signal priorities as set by the #PRIO directive.
  • An SDL system can be partitioned, i.e. split into several executables. Each partition has its own kernel/scheduler and set of environment functions. Partitioning is explained in "Partitioning" .
  • It is easy to "go to target": Write the environment functions and recompile the standard kernel with a cross compiler.

Threaded Integration

The main difference between a Light integration and a Threaded integration is that any part of the SDL system can execute in its own thread in a Threaded integration. A thread in a Threaded integration can execute one or several SDL processes or even blocks. How the different SDL objects should be mapped to threads is specified in the Deployment Editor. The user can specify thread-specific parameters like: STACKSIZE, PRIORITY, MAXMESSAGEQUEUESIZE and MAXMESSAGESIZE in the Deployment Editor. The Deployment Editor works together with the Targeting Expert to generate a Threaded integration.

Note:

A Threaded integration can only be generated using the Deployment Editor and the Targeting Expert, i.e. the make feature in the Organizer CANNOT be used.

Communication and execution control in one thread is handled by the SDL kernel and not the OS kernel. See Figure 559. This model shows the default Threaded integration where OS semaphores are the only OS primitives used in the signal sending. The xMainLoop() function is the entry point for each thread.

Figure 559 : Signalling in Threaded Integration.

SDL Kernel functions are used for sending signals within or between threads. Thick borders denote threads.

Semaphores are used frequently in Threaded to protect globally accessible data like input queues and export queues. Semaphores are also used in the start-up to synchronize the execution of newly created threads. We must ensure that no thread is allowed to start executing until ALL threads have been created in the start-up phase.

Communication with external threads (Threads not made from SDL specifications) is handled by the environment functions in the same way as for a Light integration. There is though one major difference and that is that it is possible in a Threaded to send signals directly to an SDL process with the SDL_Output() function. The SDL_Output() function is "thread-safe" because of the use of OS semaphores.

Variations of Threaded Integration

There are two different implementation of signal sending between threads in Threaded. The default model send signals in the same way as in a Light integration but the input queues are protected by OS semaphores. In the alternative model, the signals are sent/received by OS_Send and OS_Received. In the alternative model there is no use for OS semaphores. Which model to use can be decided at compilation time by setting the compilation switch THREADED_ALTERNATIVE_SIGNAL_SENDING.

Threaded Default

The sender of an SDL signal "takes" a semaphore before accessing the receivers input queue. The signal is then linked into the input queue and the semaphore is "given" back.

The receiver is normally "waiting" for a semaphore. When a signal is sent, the semaphore is "released" by the sender. To send a signal, two semaphores are normally needed. One semaphore is protecting the input queue and the other is used for synchronizing the sender and the receiver. In Solaris, where we use POSIX threads and semaphores they are called: xInputPortMutex and xInputPortCond.

One OS feature that is needed in Threaded is a "Conditional Wait". We are only allowed to wait for a signal until the first internal timer expires. In POSIX, there is a primitive called pthread_cond_wait() and in Windows there is a similar concept called WaitForSingleObject() where a time-out can be specified. In VxWorks and OSE, the only concept where you can specify a time-out is OS_Receive. For synchronization between the sender and receiver we are sending a small OS_Message (the character `c') in these two RTOS.

Threaded using OS Send and OS Receive

In this alternative implementation we are sending the signals using OS_Send and OS_Receive. Signals are now sent to OS_Message queues. The sender sends the pointer to the SDL signal in an OS_Message to the receiver's OS_Queue. When the signal is received, the SDL signal is unpacked and linked in to the receivers input queue. The advantage with this implementation is that there is now synchronization between the sender and the receiver. Any number of threads can send signals at the same time to a specific receiver without having to wait for a semaphore.

Tight integration

We also provide an alternate run-time model, which is called a Tight integration because the generated code interacts directly with the underlying operating system when creating processes, sending signals, etc.

The SDL processes run as separate OS tasks as explained below. Scheduling is handled by the OS and is normally time-sliced, priority based and preemptive.

Communication takes place using the inter-process communications mechanisms offered by the OS, normally message queues. This applies to signals sent between SDL processes as well as signals sent to or received from the environment. There are no environment functions, as illustrated in Figure 560.

Figure 560 : Signalling in the Tight Integration Model.

An SDL process sends one internal and one external signal. OS primitives are always used. The SDL system is not an entity of its own. Thick borders denote OS tasks.

Other properties of a Tight Integration:

  • There is a single timer task which handles all SDL timers.
  • SDL Simulators cannot be tightly integrated with an RTOS.
  • Execution trace is available in textual or MSC format.1

Variations on Tight integration

Tight integrations come in two varieties, the Standard model and the Instance-Set model. Consider an SDL system with processes as outlined in Figure 561.

Figure 561 : A partial SDL system

This system will be used for explaining the different models of Tight Integration.

Tight Standard

In the standard model of a Tight integration every SDL process instance is mapped to its own OS task. Tasks are created and destroyed dynamically as SDL process instances are created and terminated.

The example system will initially run as five OS tasks (four for Prs1, and one for Prs2). Up to 13 tasks may be created as needed.

Tight Instance-Set

In the Instance-Set model of a Tight integration every SDL process instance set is mapped to its own OS task. Tasks are created statically when the SDL system is initialized and are never destroyed. Thus there may be OS tasks that have no SDL process instances to run.

The example system will run as three OS tasks regardless of the number of process instances (one task each for Prs1, Prs2 and Prs3).

Choosing between Light, Threaded and Tight Integration

Choosing between the three integration models depends on many factors. Some of them are related to properties of the SDL system, others relate to the target environment. Important factors to consider are:

  • The trade-off between performance and scheduling latency.
  • How complex interaction the system has with the environment.
  • Whether an operating system will be used or not.
  • Memory management

Performance vs. scheduling latency

Generally, the Light integration model provides better performance than a Tight integration, but worst-case scheduling latency is the duration of the longest state transition.

A Tight integration is normally preferable when low scheduling latency is important. On the other hand, performance suffers from the overhead associated with OS scheduling and inter-process communications.

Another consideration is that blocking calls (either inlined in SDL code or as part of environment functions) will completely stop execution of a Light integration for the duration of the call. Making blocking calls in a Tight integration will only stop the thread making the call.

The Threaded integration is in a sense a combination of the other two integration models. An application part that makes blocking calls can be mapped to a separate OS thread. Other parts, where fast inter-process communication is important, can be mapped to another OS thread. Internally in this thread, signal exchange will be handled in the same way as in a Light integration.

Environment interaction

If interaction with the environment is simple then a Light integration is the best choice, especially if the system sends many signals and receives few. You can generate templates for the environment functions from the SDL suite and just add code for converting between the signal representation and the actual environment hardware or software.

If interaction with the environment is complex then a Tight integration is probably the easiest to use, since you only need to interface to the operating system queues. This is the case if you need process behavior in the interaction (for example, to establish a communications session before sending the signal).

Other cases where a Tight integration might be the best choice are

  • when the environment consists of many OS tasks written in other languages than SDL
  • when external processes send signals directly to SDL processes rather than to the SDL system in general
  • when there are many signals passing to and from the environment

In a Threaded integration, the integration with the environment should normally be handled in the environment functions in the same way as for a Light integration. It is possible though in Threaded to send signals directly to an SDL process with the SDL_Output() function without involving the xInEnv() function.

Operating system issues

If you will not use an OS at all then you have to select a Light integration. In addition, you will have to provide some simple functions for getting system time and handling memory allocation (depending on compiler and libraries, standard C library functions can often be used).

If you use an OS that takes care of load balancing between CPUs then you should select a Tight integration, because load balancing normally uses threads as the load unit to distribute.

If you want to distribute your SDL System over several nodes (CPUs) you should use the Threaded integration together with the TCP/IP feature.

Considerations when choosing between Tight and Threaded

Overall, Telelogic recommends using the Threaded integration mode, unless there are specific technical reasons to prefer one of the other integration models.

The two most important reasons for choosing the Threaded model are:

  1. The Threaded integration out-perform a Tight Integration in most situations, e g implementation of Timers and creation of tasks is about 100% faster in Threaded.
  2. In Threaded you are not limited to two partitioning models. Any mapping between SDL objects and threads can be specified in the Deployment editor.

For a more comprehensive list of the differences between Threaded and Tight see the following sections.

Advantages of Threaded

  • The default model is very simple to implement for a new OS. A working prototype should normally take 2-3 days.
  • The Threaded model can be used together with the TCP/IP feature.
  • The Threaded model is supporting all partitioning models (1 process instance/1 or many process instance-set/1 or many blocks/1 entire system mapped to one Thread.
  • The user can easily specify Thread specific parameters like: stack size, Thread priority, Thread message queue size and maximum message size for each Thread.
  • The Thread specific code for all supported OS is placed in one file.

Advantages of Tight

  • Simple mapping od SDL concepts to OS primitives.
  • Simple interactions with environment (at least in the default model), by direct call to the OS message passing primitives.
  • Support textual and MSC-pr textual trace in console window when executing.

Disadvantages of Threaded

  • Slightly more difficult to interact with the environment. An external function/thread must use the SDL_Output function when sending signals to an SDL process.

Disadvantages of Tight

  • Very difficult and time consuming to support a new OS.
  • Can only support two partitioning models.
  • Very inefficient Timer model.
1

The MSC trace will be printed on standard output. To see the trace in an MSC diagram, copy the text into a file and read it into the MSC Editor.


Common Features

This section describes the parts of the integration that are common to the different models, but also some important differences.

Note:

Many of the data structures and macros described in this section are described in more detail in 61 The Master Library. That chapter is, however, focused on a Light Integration. Some things, especially the listings of data structures, are not correct in every detail for Tight Integrations but should still be very useful.

The Use of Macros

A source file generated by an SDL to C compiler is independent from the choice of integration model and operating system. Instead of system calls, it uses macros that have to be defined elsewhere when the system is built. Each SDL concept is represented by one or more C macros. These macros will have different definitions for different integration models and operating systems. Telelogic Tau provides a number of integration packages for this purpose. In a Light Integration, many macros are expanded into functions of the standard kernel. A Tight Integration has lower level macros that are defined in separate files for each operating system, and finally expanded into OS primitives or certain OS dependent constructions.

Below is an example of generated code for signal sending. Code in capital letters are the SDL suite macros. The bracketed numbers indicate corresponding lines of code. For a description of the different macros, see 61 The Master Library.

SDL symbol: Output
Generated code before macro expansion:

[1] ALLOC_SIGNAL(sig2, ySigN_z3_sig2,
TO_PROCESS(Env, &yEnvR_env),
XSIGNALHEADERTYPE)
SIGNAL_ALLOC_ERROR
[2] SDL_2OUTPUT_COMPUTED_TO(
xDefaultPrioSignal,
(xIdNode *)0, sig2,
ySigN_z3_sig2,
TO_PROCESS(Env, &yEnvR_env),
0, "Sig2")
SIGNAL_ALLOC_ERROR_END

Generated code after macro expansion for a Light Integration:

[1] yOutputSignal = xGetSignal
((&ySigR_z3_sig2),
(*(&yEnvR_env)->
ActivePrsList !=
(xPrsNode) 0 ?
(*(&yEnvR_env)->
ActivePrsList)->Self :
xSysD.SDL_NULL_Var),
yVarP->Self);
[2] SDL_Output (yOutputSignal,
(xIdNode *) 0);

File Structure

Note:

The source file and examples for Tight Integration are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

The Generated Files

An integration uses one or more of four files that can be generated by the Code Generator. All integrations require the C source file <systemname>.c, whereas the interface file <systemname>.ifc is optional. For a Tight Integration the signal number file <systemname>.hs may be used, and for a Light Integration the file sctenv.c, representing the environment, can be used.

The source file uses the highest level set of macros, that are defined in the different integration packages.

The Integration Packages

The files containing the necessary macro definitions and support functions are organized as shown in Figure 562. For each operating system there is one package for the Light Integration, and one for the Tight Integration. Although the files in different packages may have the same name they do not necessarily contain the same code. The principles for Tight Integration packages are described more thoroughly in "Tight Integration" . Details about each operating system can be found in the annexes.

Figure 562 : File structure for the RTOS integrations

There is also an INCLUDE directory containing source files common to all supported operating systems. These files are described in "File Structure" . Below are some additional comments on these files:

  • scthooks.h:
    This file contains macro hooks into the system. These hooks are used for customizing a Tight Integration, for example by adding external tasks. See the examples to find out how this is done.
    All the hook macros are initially empty.
  • sctcommon.h:
    This file contains general macros for all Tight Integrations
  • sctos.c:
    This file contains functions that are operating system and/or compiler dependent, like allocation and free of dynamic memory.
  • sctpred.h and sctpred.c:
    This is the header and source file where all the SDL predefined datatypes are implemented.
  • sctsdl.c:
    This file contains SDL support functions, the timer task and the timer support functions. It is non-OS-specific and calls many second level OS-specific macros defined in sct<RTOS>.h.
  • scttypes.h:
    This file contains the general datatype definitions for signals, IdNodes, etc. It also contains the macro definitions found in generated code. Note that this file is non-OS-specific. This means that if a call to an OS-specific primitive is needed, then a second level of macro is defined, according to the following model.
    In the generated code:
ALLOC_SIGNAL_PAR(ok, ySigN_z3_ok, TO_PROCESS(Env, &yEnvR_env), yPDef_z3_ok)

In scttypes.h:
#define ALLOC_SIGNAL_PAR(SIG_NAME, SIG_IDNODE, \
RECEIVER, SIG_PAR_TYPE) \
RTOSALLOC_SIGNAL_PAR(SIG_NAME, SIG_IDNODE, \
RECEIVER, SIG_PAR_TYPE)

In sct<RTOS>.h:
#define RTOSALLOC_SIGNAL_PAR(SIG_NAME,SIG_IDNODE,\
RECEIVER, SIG_PAR_TYPE) \
yOutputSignalPtr = \
xAlloc(sizeof(xSignalHeaderRec)+ \
sizeof(SIG_PAR_TYPE)); \
yOutputSignalPtr->SigP = yOutputSignalPtr+1; \
yOutputSignalPtr->SignalCode = SIG_NAME; \
yOutputSignalPtr->Sender = SDL_SELF;

The Examples directory contains a simple SDL system that also uses an external process (a separate OS task). For each supported operating system there is an implementation of this, demonstrating how to hook into the integration package. Further description of the example can be found in "A Simple Example" .

Naming Conventions

Names of variables, datatypes and support functions in generated code and package files often start with one of the letters x, y and z.

The general rules (there are some exceptions) are:

  • Names and objects starting with an `x' represent general datatypes and support functions in the kernel.
    Examples: extern XCONST struct xVarIdStruct, xInputSignal, xFindReceiver
  • Names starting with a `y' are names of IdNodes representing SDL variables, process states, channels, blocks, datatypes for signals, PAD functions, etc. in generated code.
    Examples: extern XCONST struct xVarIdStruct yVarR_z012_okmess, ySigR_z3_ok, yPAD_z01_pr1
  • Names and objects starting with a `z' are SDL variables, SDL names, process state names, etc. in generated code.
    Examples: #define z010_idle 1, z012_okmess

The Symbol Table

All signals, blocks, processes, channels, etc. in an SDL system have a corresponding representation in the symbol table described in 61 The Master Library. This symbol table consists of nodes (IdNodes) each representing one entity of the system. The IdNodes are pointers to structs. See the following example:

extern XCONST struct xPrsIdStruct yPrsR_z02_dynpr1;
#define yPrsN_z02_dynpr1 (&yPrsR_z02_dynpr1)

The N_ and the R_ just before z02_dynpr1 indicate if it is a node (N_) or a record (R_).

Memory Allocation

The xAlloc function is always used when allocating dynamic memory. The function is placed in the sctos.c file, but in the Tight Integrations the body of the function is found in the sct<RTOS>.h file.

Start-up

The yInit function is called during start-up of the SDL system. It is responsible for creating all static processes and for initializing SDL synonyms.

Implementation of SDL Concepts

SDL Processes

An SDL process consists of three parts in generated code: Instance set common data, instance specific data and dynamic behavior.

Instance set common data

Variables and structures that are common to all instances of a process are stored in a record of the type xPrsIdStruct, defined in scttypes.h. This record is referenced by a node in the symbol table.

Instance specific data

Variables and structures of the process instance are declared via the macro PROCESS_VARS. This macro is defined in different ways in the Light and the two models of Tight Integration. It contains state information, local variables, pointers to parent and offspring, etc. One important entry is the RestartAddress, pointing out which transition to execute when the PAD function runs (see below).

Dynamic behavior

The dynamic behavior of an SDL process is implemented in a PAD function (Process Activity Definition). The PAD function is used somewhat differently in the different integration models:

  • In the Light Integration the scheduler calls the PAD function of the process. The PAD function then returns to the scheduler when the transition is finished.
  • In the Standard Model Tight Integration the PAD function is called when the process is started and does not return until process termination. It then contains a main loop where one iteration corresponds to one transition.
  • The Instance Set Model Tight Integration contains a mix of the two.

Below is the code for ending a transition, before and after macro expansion for a Light Integration.

SDL symbol: Nextstate
Generated code before macro expansion:

/*-----
* NEXTSTATE -
* #SDTREF(SDL,/ti/RTOS/MANUAL/SDL/simple.spr(1),
143(55,100),1)
------*/
#ifdef XCASELABELS
[1] case 6:
#endif
[2] XAT_LAST_SYMBOL
[3] SDL_DASH_NEXTSTATE

Generated code after macro expansion for a Light Integration:

/*-----
* NEXTSTATE -
* #SDTREF(SDL,/ti/RTOS/MANUAL/SDL/simple.spr(1),
143(55,100),1)
------*/

[1] case 6:

[2] xGRSetSymbol (-1);
[3] SDL_NextState (VarP, yVarP->State);
return;

Signal Queues

Basically, every process has at least one signal queue.

  • In a Light Integration each process instance has an input queue.
  • In the Standard Model Tight Integration there is an input queue and a save queue for each instance.
  • In the Instance Set Model Tight Integration there is an input queue and a save queue for every instance set. These two queues are shared by all the instances.

All signals that are sent to a process arrive in the input queue. The save queue is used to keep signals that cannot be handled in the current state but should be saved for future use. This is tightly connected to the SDL Save concept, but is also used in the implementation of timers. For a Light Integration there are no save queues. Instead, all signals that should be saved will remain in the input queue until they can be received.

Process Priorities

The use of process priorities requires some caution. Priorities can be set with the #PRIO directive in the SDL suite, but there is no mapping of priorities for different platforms. The generated code will use exactly the values specified in the SDL system. This will not be a problem in a Light Integration, but for Tight Integrations the result may not be the expected.

Example 533 : Process priority problems

Assume that Process1 has its priority set to 100 using the #PRIO 100 directive and Process2 has #PRIO 50. These priority values will be used as-is by the underlying scheduler.

In the SDL Suite simulators and Light integrations, the highest priority is 0. In VxWorks, 0 is the highest priority, whereas in pSOS the highest priority is 255.

Thus the simulated system, a Light integration for any operating system and a Tight integration for VxWorks will all run Process2 at a higher priority than Process1. In contrast, a Tight integration for pSOS will run Process1 at a higher priority than Process2!

Process Creation

Regardless of the integration model there are a number of things that have to be done when an SDL process instance is created. The structs that represent the instance have to be created. It needs a representation in the symbol tree and a signal queue, except in the Instance Set Model of Tight Integration where the signal queue belongs to the instance set. A start-up signal is also always allocated and sent to the process.

SDL symbol: SDL Static Create
Generated code before macro expansion:

/**********************************************************
SECTION Initialization
**********************************************************/

extern void yInit XPP((void))
{
int Temp;
........
INIT_PROCESS_TYPE(pr1,z01_pr1,yPrsN_z01_pr1,"z01_pr1",
SDL_INTEGER_LIT(2),SDL_INTEGER_LIT(2),
yVDef_z01_pr1, xDefaultPrioProcess,
yPAD_z01_pr1)
#ifdef SDL_STATIC_CREATE
[1] for (Temp=1; Temp<=SDL_INTEGER_LIT(2); Temp++) {
[2] SDL_STATIC_CREATE(pr1,z01_pr1,yPrsN_z01_pr1,
"pr1",ySigN_z01_pr1,
yPDef_z01_pr1,yVDef_z01_pr1,
xDefaultPrioProcess,yPAD_z01_pr1,1)
}
#endif

Generated Code after macro expansion for a Light Integration:

/**********************************************************
SECTION Initialization
**********************************************************/
extern void
yInit ()
{
int Temp;
..........
[1] for (Temp = 1; Temp <= 2; Temp++) {

[2] SDL_Create (xGetSignal ((&ySigR_z01_pr1),
xSysD.SDL_NULL_Var, xSysD.SDL_NULL_Var),
(&yPrsR_z01_pr1), 1);
}

SDL Signals

Signal Sending

In generated code a signal sending is handled by two macros: ALLOC_SIGNAL (or ALLOC_SIGNAL_PAR for a signal with parameters) and SDL_2OUTPUT_xxxx (there are different macros depending on how the SDL output was defined, e.g. with or without an explicit TO).

SDL symbol: Output
Generated code before macro expansion:

[1] ALLOC_SIGNAL(go,ySigN_z03_go,TO_PROCESS(p,yPrsN_z09_p),
XSIGNALHEADERTYPE)
SIGNAL_ALLOC_ERROR
[2] SDL_2OUTPUT_COMPUTED_TO(xDefaultPrioSignal,(xIdNode*)0, go,
ySigN_z03_go,TO_PROCESS(p, yPrsN_z09_p), 0, "Go")
SIGNAL_ALLOC_ERROR_END
XBETWEEN_SYMBOLS(4, 579)

Generated code after macro expansion for a VxWorks Tight Integration:

[1] yOutputSignalPtr = xAlloc(sizeof(xSignalHeaderRec));
[1] yOutputSignalPtr->SignalCode = 2;
[1] yOutputSignalPtr->Sender = yVarP->Self;
[2] Err = msgQSend (xTo_Process ((&yPrsR_z09_p)),
[2] (char*)*&yOutputSignalPtr,
[2] sizeof(xSignalHeaderRec) + 0, 0, 0);
[2] xFree ((void **) &yOutputSignalPtr);
[2] if (Err == (-1)) {
[2] taskLock ();
[2] printf ("Error during %s found in VXWORKS
[2] function %s. Error code %s\n", "OUTPUT",
[2] "msgQSend", strerror ((*__errno ())));
[2] taskUnlock ();
[2] }

In this example the signal is called go and has no parameters. The SDL_2OUTPUT_COMPUTED_TO macro indicates that it was sent without an explicit TO.

SDL Procedures

An SDL procedure is represented by a function similar to a PAD function. Before a procedure is called there are two support functions that need to be called: xGetPrd and xAddPrdCall.

The xGetPrd function allocates an xPrdStruct for the called procedure and returns an xPrdNode pointing to the struct.

The xAddPrdCall function adds the new procedure call in the calling process' ActivePrd list (an element in the xPrsStruct).

The procedure is called with a pointer to the instance data of the calling SDL process. This is because the procedure must be able to use internal variables in the calling process.

Before a procedure returns to the caller it performs an xReleasePrd call. This function removes the call from the ActivePrd list.

SDL Timers

SDL timers are represented by signals. All active timer signals are kept in a sorted list, either within the single task of a Light Integration or in a certain timer task in a Tight Integration. When a timer expires, the signal representing it is sent to the SDL process that set it.

SDL symbol: SET Timer
Generated code before macro expansion:

/*-----
* SET T1
* #SDTREF(SDL,/ti/RTOS/MANUAL/SDL/dynpr1.spr(1),
119(55,25),1)
------*/
#ifdef XCASELABELS
[1] case 2:
#endif
[2] SDL_SET_DUR(xPlus_SDL_Time(SDL_NOW,
[3] SDL_DURATION_LIT(5.0, 5, 0)),
[4] SDL_DURATION_LIT(5.0, 5, 0), t1, ySigN_z021_t1,
yTim_t1, "T1")

Generated code after macro expansion for a Light Integration:

/*-----
* SET T1
* #SDTREF(SDL,/ti/RTOS/MANUAL/SDL/dynpr1.spr(1),
119(55,25),1)
------*/

[1] case 2:

[2] SDL_Set (xPlus_SDL_Duration (SDL_Now (),
[3] SDL_Duration_Lit (5, 0)), xGetSignal
[4] ((&ySigR_z021_t1), yVarP->Self,
yVarP->Self));


Light Integration

A Light Integration is a stand-alone executable which can be generated with or without a simulator. An executable that should run under UNIX can use the precompiled kernels. Only the environment functions need to be written by the user.

PAD Functions

The PAD function is called by the scheduler when its process is in turn to execute a transition. The scheduler calls the PAD function with a symbol table node of the type xPrsNode, pointing to the instance specific data of the instance that is scheduled.

Start-Up

A Light Integration starts when the generated main function is called. The start-up phase works like this (pseudocode shown in italics):

void main( void )
{
xMainInit();
Code from #MAIN
xMainLoop();
}

void xMainInit( void )
{
xInitEnv();
Init of internal structures
}

You must supply the xInitEnv() function to initialize external code and hardware, etc. (this is of course application dependent). This function is placed in the same program module (environment module) as the xInEnv() and xOutEnv() functions. The xMainLoop() function contains an eternal loop, which constitutes the scheduler itself. See below:

void xMainLoop (void)
{
while (1)
{
xInEnv(...)
if (a timer has expired)
send the corresponding timer signal
else if (a process can execute a transition)
{
remove the signal from the input port
set up Sender in the process to Sender of the signal
call the PAD function for the process
}
}
}

Connection to the Environment

Signals going in and out of the SDL system are handled in the two user written functions xInEnv and xOutEnv. There is a template file for writing these two function in the standard distribution. This file can be found at <installation directory>/sdt/
sdtdir/<your platform os version>sdtdir/INCLUDE/
sctenv.c.

Running a Light Integration under an External RTOS

Since there are some fundamental differences between different RTOS we can only give a general idea of how to generate a Light Integration under an external RTOS here. Typical things that may be different in different RTOS:

  • If you are allowed to have a main function in your application.
  • If your start-up function must be specified in a configuration file.
  • If the cross compiler requires additional OS-specific header files to be included.
  • If it is possible to run the application in a simulated target environment.
  • Syntax for the makefile.

General Steps

The normal steps to create a Light Integration under an external RTOS can be summarized as follows:

  1. Copy the source and header files for an application kernel from the installation of the SDL suite. The files are residing in the following directory:
    <installation directory>/sdt/
    sdtdir/<your host and os version>sdtdir/INCLUDE    .
  2. Generate an <application>.c file with the SDL to C Compiler.

Note:

The code generator option Cadvanced must be used.

  3. Generate an environment header file (an option in the Organizer Make dialog).
  4. Edit the sctenv.c template file to handle your in and out environment signals. Include the generated <application>.ifc file (the environment header file).
  5. Create a makefile or edit the generated makefile. Write entries for the kernel source files, the environment file and the application file.
  6. Set the appropriate compilation switches for your RTOS and your compiler.
  7. Compile the application and the kernel file to create a relocatable object file.
  8. Download.


Threaded Integration

Introduction

The first part of this section is about the Threaded integration. The second part is about the TCP/IP feature. With the Threaded and TCP/IP features you can partition an SDL system into several threads that can execute in a distributed environment.

Implementation Details for Threaded

The main areas where a Threaded differs from a Light integration are:

  • Symbol table structures and global variables
  • Process creation
  • Signal sending

Symbol Table Structures and Global Variables

Each thread has a global variable of type xSystemData in Threaded. In Light, there is only one global variable of this type for the entire system. In Threaded this variable is initialized in yInit() and is one of the parameters in the macro for creating a new thread.

The data structure xSystemData has a couple of new entries:

...
#ifdef THREADED
xInputPortRec xNewSignals;
THREADED_THREAD_VARS
#endif
...

The entry xNewSignals is used when a new signal is received. The signal is first linked into the receiver's xNewSignals queue before it is handled in the receiver's xMainLoop().

The entry THREADED_THREAD_VARS is a macro that contains different thread variables like the semaphore handles xInputPort.

Global variables are declared in the macro THREADED_GLOBAL_VARS:

#elif THREADSOLARIS
.....
#define THREADED_GLOBAL_VARS \
pthread_mutex_t xListMutex; \
pthread_mutex_t xExportMutex; \
sem_t xInitSem; \
int xNumberOfThreads; \
int QueueCounter; \
int xInitPhase; \
pthread_attr_t Attributes ;
#endif /* THREADED_ALTERNATIVE_SIGNAL_SENDING */
#endif

Process Creation

There are three macros related to the creation of threads in a Threaded:

  • THREADED_START_THREAD(F, SYSD, THREAD_STACKSIZE, THREAD_PRIO, THREAD_MAXQUEUESIZE, THREAD_MAXMESSIZE)
    This macro is used if there is only one thread to be created for all instances (Instance Set) of an SDL process (or another SDL object). The parameters are:

Parameters | Explanation
F | The entry point of the thread, i.e. the SDL kernel function xMainLoop()
SYSD | A variable of type xSystemData
THREAD_STACKSIZE | The stacksize for the thread is specified in the Deployment Editor
THREAD_PRIO | The thread priority specified in the Deployment Editor
THREAD_MAXQUEUESIZE | The maximum number of messages/signals in the input queue of the thread, as specified in the Deployment Editor. This parameter is only used if the alternate signal sending model is used.
THREAD_MAXMESSIZE | The maximum size of a message/signal. This parameter is ignored at the moment in both implementation models. The maximum size of a message/signal in the alternate signal sending model is always the size of the pointer to an SDL signal (sizeof(xSignalNode).

Note:

Thread parameters for individual threads can be specified in the Deployment Editor. If no values are specified, default values will be used.

  • SDL_CREATE(PROC_NAME, PROC_IDNODE, PROC_NAME_STRING)
    This macro is used for creation of dynamic processes (processes created during run-time).
    It is defined exactly the same way in Threaded as in Light. It will call the SDL kernel function SDL_Create().
    SDL_Create() will create a new thread if, for instance, there should be one thread for each instance of an SDL process. See the following extract from the SDL_Create() function:
...................
#ifdef THREADED
if (PrsId->SysD == 0) {
THREADED_START_THREAD(xMainLoop, StartUpSig->Receiver.LocalPId->PrsP->SysD, PrsId->ThreadParam->ThreadStackSize, PrsId->ThreadParam->ThreadPrio, PrsId->ThreadParam->MaxQueueLength, PrsId->ThreadParam->MaxMesSize);
}
#endif
....................
Please note that the thread parameters are taken from the xPrsIdNode for the process.
SDL_STATIC_CREATE(PROC_NAME, PREFIX_PROC_NAME, PROC_IDNODE, PROC_NAME_STRING, STARTUP_IDNODE, STARTUP_PAR_TYPE, PRIV_DATA_TYPE, PRIO, PAD_FUNCTION, BLOCK_INST_NUMBER)
This macro is used for creating static processes (processes that are created at system start-up). It will be called from the yInit() function and is mapped to the SDL kernel function SDL_Create() in the same way as in the SDL_CREATE macro.

The xMainLoop() function is the entry point for the thread. First in this function is the macro

THREADED_THREAD_BEGINNING(SYSD)

The main purpose of this macro is to wait for the start-up semaphore xInitSem. No thread is allowed to start executing until ALL static processes/threads have been created.

Sending Signals

In the default model, signals are sent in the same way as for a Light integration except that they are first linked into the xNewSignals queue.

In the xMainLoop() function, the xNewSignals queue is checked for new entries. If a new signal is available, it is sent to the process itself with the SDL_Output() function. See the following extract from the xMainLoop() function:

........

THREADED_LOCK_INPUTPORT(((xSystemData *)SysD))
while (((xSystemData *)SysD)->xNewSignals.Suc != (xSignalNode)&((xSystemData *)SysD)->xNewSignals)
SDL_Output(((xSystemData *)SysD)->xNewSignals.Suc xSigPrioPar(((xSystemData *)SysD)->xNewSignals.Suc->Prio), 0);
THREADED_UNLOCK_INPUTPORT(((xSystemData *)SysD))

.........

The Alternative Signal Sending Model.

In the alternative signal sending model, an OS message/signal is sent containing a pointer to the SDL signal. For this, a message queue must be created for each thread at thread creation. How this is done differs from OS to OS. See : Signalling in Threaded Integration.

The sender sends the pointer to the SDL signal with the OS_Send primitive. The receiver receives the message, extracts the pointer to the SDL signal and links it into the xNewSignal queue. After this, the signal is handled in the same way as in the default model.

New Macros

The same source files are used in a Threaded integration as in a Light. The only SDL kernel source files that are affected by the Threaded integration are scttypes.h, sctsdl.c and sctos.c.

Most of the OS specific code is found in the scttypes.h file. The following macros are new for Threaded:

MACRO NAME | Explanation
THREADWIN32 | Main macro for Threaded Windows integration
THREADSOLARIS | Main macro for Threaded Solaris integration
THREADVXWORKS | Main macro for Threaded VxWorks integration
THRAEDOSE | Main macro for Threaded OSE integration
THREADED_ALTERNATIVE_SIGNAL_SENDING | Main macro for using the alternative signal sending model.
THREADED_POSIX_THREADS | Main macro for the Threaded integration model defining the kernel specifics
THREADED | Internal macro used only in the kernel source files
THREADED_TRACE | Enabling textual execution trace
THREADED_OSTRACE | This macro is mapped to a printf statement.
THREADED_ERROR | Enabling textual error printout when calling OS primitives.
THREADED_ERROR_VAR | Defines a variable used in THREADED_ERROR_RESULTS.
THREADED_ERROR_RESULT | Stores the return result after calling an OS primitive.
THREADED_ERROR_REPORT | Checks the value of the return variable and if ERROR makes a printout.
THREADED_ERROR_REPORT_NULL | Checks the value of the return variable and if ERROR makes a printout.
THREADED_ERROR_REPORT_NEG | Checks the value of the return variable and if ERROR makes a printout.
THREADED_ERROR_REPORT_OPEN_NEG | Checks the value of the return variable and if ERROR makes a printout.
THREADED_ERROR_REPORT_WAIT_NEG | Checks the value of the return variable and if ERROR makes a printout.
THREADED_GLOBAL_VARS | Global variable defines.
THREADED_GLOBAL_INIT | Initialization of global variables like semaphores.
THREADED_THREAD_VARS | Definitions of thread variables.
THREADED_THREAD_INIT | Initialization of thread variables.
THREADED_THREAD_BEGINNING | Wait for xInitSem to be released.
THREADED_LOCK_INPUTPORT | Protect the input queue by taking the semaphore.
THREADED_UNLOCK_INPUTPORT | Releasing the semaphore for the input queue.
THREADED_WAIT_AND_UNLOCK_INPUTPORT | Wait for next message/signal to arrive or the next internal timer to expire.
THREADED_SIGNAL_AND_UNLOCK_INPUTPORT | Send a signal and release the semaphore for the input queue.
THREADED_LISTREAD_START | Protect global active and available lists with a semaphore before reading it.
THREADED_LISTWRITE_START | Protect global active and available lists with a semaphore before writing to it.
THREADED_LISTACCESS_END | Release the semaphore protecting a global active or available list.
THREADED_EXPORT_START | Protect export and import actions by taking a semaphore
THREADED_EXPORT_END | Release the semaphore after export and import actions.
THREADED_START_THREAD | Start a new thread.
THREADED_STOP_THREAD | Terminate a thread.
THREADED_AFTER_THREAD_START | Synchronize the start-up of newly created threads.
THREADED_SEND_OUTPUT | Send messages/signals. Used in both models.

Textual and MSC Trace in Threaded

Textual SDL Trace, similar to the Textual Trace in Telelogic Tau Simulator, can be turned on by selecting the flag SDL trace (will set the flag THREADED_XTRACE) in the Target Library/Kernel window in Targeting Expert.

On-line MSC trace is possible when running an application under a softkernel on Windows or UNIX. Select the flag MSC trace (will set the flag THREADED_MSCTRACE) in the Target Library/Kernel window in Targeting Expert.

API for interfacing a Threaded Integration

An API is available with a number of useful functions/MACROS that will facilitate the work of sending/receiving signals between external processes/threads and an SDL Threaded Application.

The following functions and MACROS are available:

SDL_PId xThreadedRegExtTask()

This function will return an SDL PId representing the calling External process/thread. It works in the following way:

  1. Get a ThreadId for the calling process/thread.
  2. Allocate and assign an SDL struct (xPrsIdRec) representing the external process/thread.
  3. Call the SDL kernel function xGetPId() to get an SDL_PId.
  4. If MSC trace is on it will generate an entry for the process/thread in the MSC diagram.
  5. Allocate and initialize an SDL "system data record" for the external process/thread.
  6. Create a queue for the calling process/thread.
  7. Assign the "system data record" entry in the SDL_PId.
  8. Return the SDL_PId.

xSignalNode xThreadedReceiveSDLSig(SDL_PId)

This function will wait for an SDL signal indefinitely. When a signal arrives the signal will be taken out of the queue and return the signal. If MSC trace is on the signal will also be traced in the MSC diagram.

xSignalNode xThreadedReceiveSDLSig_WithTimeOut(SDL_PId, SDL_Duration)

This function will work in the same way as xThreadedReceiveSDLSig() except that it will only wait for the specified time.

THREADED_ASSIGN_SDL_SIG_PARAMS(sigptr,signame,paramno,param)

This macro will use the macro token operator ## to concatenate the sigptr, signame, paramno into a simple assignment of the signal parameter with the specified number.

Note:

This macro should only be used with simple datatypes where assignments can be done using the simple assignment operator "="

THREADED_GET_SDL_SIG_PARAM(sigptr,signame,paramno,param)

This macro will assign the user's param the value of the signal parameter with the specified number.

Note:

This macro should only be used with simple datatypes where assignments can be done using the simple assignment operator "="

SDL_Output()

This is the standard SDL kernel function that should be used when sending signal into a Threaded Application. The following must be done before a signal can be sent from an external process/thread into a Threaded Application.

  1. Use the xThreadedRegExtTask/xThreadedRegExtTask_WithQueue function to get an SDL_PId.
  2. Call the SDL kernel function xGetSignal with the following parameters: signalId, Receiver, Sender.
  3. Assign signal parameters using the API macro THREADED_ASSIGN_SDL_SIG_PARAMS()
  4. Call the SDL_Output function with the SDL signal.

For an example see Annex 6: Building a Threaded Integration

THREADED_START_EXTTASK

This macro is normally empty. It is called after all static SDL threads are created in the THREADED_AFTER_THREAD_START macro (last in generated c file for application).

By defining this macro to user can make the application start external tasks.

THREADED_SIMPLE_EXAMPLE

If this flag is defined the external tasks in the simple example will be started.

Implementation Details for Different RTOS

VxWorks

The Threaded integration for VxWorks is developed and tested using a Solaris Softkernel in Tornado 2.

The following vxWorks header files are used:

#ifdef THREADVXWORKS

#include "errno.h"
#include "vxWorks.h"
#include "semLib.h"
#include "msgQLib.h" /* msgQCreate msgQDelete msgQSend msgQReceive *//* msgQNumMsgs */
#include "taskLib.h" /* taskSpawn */
#include "semaphore.h" /* POSIX semaphores */
#endif

The following VxWorks primitives have been used:

VxWorks primitives | Explanation
sem_init(..), sem_wait(..), sem_post(..), sem_destroy(..), | POSIX semaphores are frequently used, e.g. to protect the input queue, to synchronize start-up...
msgQCreate(..), msgQReceive(..), msgQSend(..), msgQDelete(..) | Message queues are used in both models in VxWorks. The message queue is created in the THREADED_START_THREAD MACRO.
taskSpawn(..), taskDelete(..), taskSuspend(..) | taskSpawn is used for creating a thread. The name entry is not used. taskSuspend is only used by the "Main" thread. It is called from the macro THREADED_AFTER_THREAD_START.
taskIdSelf() | Used in taskDelete() and taskSuspend()

Thread Parameters | Default values
DEFAULT_STACKSIZE | 800
DEFAULT_PRIO | 100
DEFAULT_MAXQUEUESIZE | 250
DEFAULT_MAXMESSIZE | sizeof(xSignalNode)

Solaris

The Threaded integration for Solaris is developed and tested in the following environment:

Sun Solaris 2.6 with Sun WorkShop compiler cc version 5.0.

Included header files for Solaris:

#elif THREADSOLARIS
#include <pthread.h>
#include <semaphore.h>
#ifdef THREADED_ALTERNATIVE_SIGNAL_SENDING
#include <mqueue.h>
#include <signal.h>
#include <time.h>
#endif /* THREADED_ALTERNATIVE_SIGNAL_SENDING */
#endif

The following Solaris primitives have been used:

Solaris primitives
Explanation
sem_init(..),
sem_wait(..), sem_post(..),
pthread_mutex_init(..),
pthread_mutex_lock(..),
pthread_mutex_unlock(..),
pthread_mutex_destroy(..)

pthread_cond_init(..),
pthread_cond_wait(..),
pthread_cond_timedwait(..),
pthread_cond_signal(..),
pthread_cond_destroy(..)
The sem_.. primitives are only used in the start-up to synchronize static processes/threads.

The pthread_mutex_.. primitives are used to protect the input queues and other queues.

The pthread_cond_... primitives are used to synchronize sender and receiver in the default model.
pthread_attr_init(..),
pthread_attr_setstacksize(..),
pthread_attr_setschedpolicy(..),
thread_attr_setdetachstate(..),
pthread_attr_setscope(..)
The pthread_attr_.. primitives are used to set the attributes of a thread before it is created.
mq_open(..),
mq_close(..),
mq_receive(..),
mq_unlink(..),
mq_send(..)
These primitive are only used in the alternative signal sending model.
pthread_create(..),
pthread_exit(..),
These primitives are used when a thread is created and when it terminates.
timer_settime(..),
timer_delete(..)
These primitives are used for setting a timer before the mq_receive() is called in the alternative signal sending model. The time-out for the timer is the duration for the next internal SDL timer to expire. When the timer expires the signal_handler function sets the error message to EINTR.

Thread Parameters | Default values
DEFAULT_STACKSIZE | 15000
DEFAULT_PRIO | 10
DEFAULT_MAXQUEUESIZE | 128
DEFAULT_MAXMESSIZE | sizeof(xSignalNode)

OSE

The Threaded integration for OSE have been developed and tested with an OSE Softkernel (version 4.3) on Solaris 2.6 using the gcc compiler (version 2.95).

The following OSE header file is include:

#ifdef THREADOSE
#include "ose.h"
#endif /* THREADOSE */

The following OSE primitives have been used:

OSE Primitives | Explanation
create_sem(..), wait_sem(..), signal_sem(..), | These primitives are used for protecting input queues, other queues and for synchronizing start-up
receive(..), receive_w_tmo(..), send(..) | These primitive are used for receiving/sending signals in both models. Receive/send is also used to pass the start-up parameter xSysD to a new thread, since OSE does not support start-up parameters in the create_process primitive.
alloc(..), free_buf(..) | These primitives are used for allocating and returning OSE signals.
start(..) | This primitive is used for starting a newly created thread.
kill_proc(..) | This primitive terminates a thread
stop(..) | This primitive stop the execution of a thread. Used in the THREADED_AFTER_THREAD_START macro.
current_process() | Used in the kill_proc() and stop() calls.
create_process(..) | This primitive is used for creating Threads.

Thread Parameters | Default values
DEFAULT_STACKSIZE | 1024
DEFAULT_PRIO | 8
DEFAULT_MAXQUEUESIZE | 1024
DEFAULT_MAXMESSIZE | sizeof(xSignalNode)

Declaration of xMainLoop().

The declaration and definition of the thread's entry point (xMainLoop()) is special in OSE:

Declaration in scttypes.h;

.......
#elif THREADOSE
extern OSENTRYPOINT xMainLoop;
#else
extern void xMainLoop XPP((xSystemData *));
#endif

Definition in sctsdl.c:
......
#elif THREADOSE
OS_PROCESS(xMainLoop)
#else
#ifndef XNOPROTO
void xMainLoop (xSystemData * SysD)
#else
void xMainLoop (SysD)
xSystemData * SysD;
#endif
#endif
..............

Definition of NIL.

NIL is defined in the OSE kernel and must not be redefined in the SDL kernel.
#ifndef THREADOSE
#define NIL 0
#endif /* THREADOSE */

Forward declaration of xSignalNode.

The xSignalNode must have forward declaration very early in the scttypes.h file since it is used in the union SIGNAL definition.

.............
typedef struct xSignalStruct *xSignalNode;
union SIGNAL
{
SIGSELECT sigNo;
xSignalNode SDLSig;
xSystemDataPtr SysD;
};

.....
Further down in the scttypes.h file.

.....
#ifndef THREADOSE
typedef struct xSignalStruct *xSignalNode;
#endif /* THREADOSE */
.....

Windows

The Threaded integration for Windows is developed and tested on Windows 2000 Professional with the Borland C++ compiler, version 5.02.

The following header files for Windows are included:

#ifdef THREADWIN32
#include "limits.h"
#include "windows.h"
#include "dos.h"
......

The following Windows primitives are used in the Threaded integration:

Windows primitives | Explanation
CreateSemaphore(..), ReleaseSemaphore(..), WaitForSingleObject(..), CloseHandle(..) | These primitives are used for protecting input queues, other queues and synchronization in start-up. One extra semaphore, xInitQueue, is used when a newly created thread is creating his own input queue.
PeekMessage(..) | This primitive is used in the THREADED_THREAD_BEGINNING macro in the alternative signal sending model. This primitive force the thread to create a message queue. It is used together with the xInitQueue semaphore.
GetMessage(..), PostThreadMessage(..), | These primitives are used for receiving/sending messages in the alternative signal sending model.
SetTimer(..), KillTimer(..) | These primitives are used to set an OS timer that will signal the thread when it expires. The timeout of this timer is the duration until the next internal SDL timer expires for this thread. The window message will be set to WM_TIMER if the OS timer expires.
CreateThread(..), ExitThread(..) | These primitives are used for creating and terminating threads.
SetThreadPriority(..) | This primitive is used for setting the priority of the thread.
SuspendThread(..) | Called by the "main" thread in the macro THREADED_AFTER_THREAD_START
GetCurrentThread() | Used in the SuspendThread macro.

Thread Parameters | Default values
DEFAULT_STACKSIZE | 0 (Automatically resized by OS)
DEFAULT_PRIO | THREAD_PRIORITY_NORMAL
DEFAULT_MAXQUEUESIZE | 1024
DEFAULT_MAXMESSIZE | sizeof(xSignalNode)

Signal Sending over TCP/IP

Introduction

For applications using the Threaded integration model, a plug-in module for TCP/IP communication is available. The module supports signal sending between distributed SDL applications via a TCP/IP connection. ASCII Encoding/Decoding is used for the conversion between signal and transport format. The module is delivered as C source code which is integrated and built together with code generated by the CAdvanced SDL to C Compiler.

The TCP/IP adapter supports the four operating systems for which Threaded integrations are available. These are Windows, Solaris, VxWorks and OSE.

Architecture

The TCP/IP functions are called from the environment functions xInitEnv and xOutEnv. The functions are included by setting the XENV_INC flag to "tcpipcomm.h". The tcpipcomm.h file contains #define directives that translates macros in the environment file to function calls in the TCP/IP adapter.

When a signal is sent to the environment using the xOutEnv function, xSendSignal is called. A connection is set up with a remote server. The signal destination is specified using a user-implemented function. When the connection is accepted, the signal is encoded into ASCII format and sent via a TCP/IP socket. The session is then closed.

From xInitEnv, a thread is started which polls a socket for incoming connections. When a connection from a remote client is accepted, a new thread is started, which receives and decodes data for one signal. When the signal is decoded, it is inserted in the signal queue of the SDL system. The thread finishes its execution after the connection is closed.

An executing SDL system thus acts as a server when signals are received from the environment and as a client when a signal should be sent to the environment.

The environment file of an SDL application may not be modified if the TCP/IP adapter is to be used. Making modifications may override the TCP/IP signal sending functionality. If you want to use the TCP/IP adapter together with other external code from an environment file, please consult "Configuration" .

File Structure

The TCP/IP adapter consists of four files, located in $sdtdir/tcpip/.

  • tcpipcomm.c should be compiled and linked with the generated C code
  • tcpipcomm.h is a C header file which is included from the generated environment file
  • tcpipthr.h and tcpipsock.h are header files that are included from tcpipcomm.c and tcpipcomm.h.

The tcpip directory is referenced relative to the $sdtdir variable.

Hint: Using TCP/IP with a new $sdtdir

If you use an $sdtdir that is different from the default $sdtdir (in the SDL suite installation directory), be sure to copy the tcpip directory to the new location. Otherwise, you may encounter problems in finding the TCP/IP files at compilation.

Note: Pointers as Signal Parameters

Distributed components execute in separate memory spaces. Care must be taken so that pointers are not sent as signal parameters over TCP/IP and used in a remote component.

Routing of Signals

For each signal that is sent from your SDL application, you must specify a destination in the form of an IP address (or host name) and a TCP port number. This information should be accessed from a routing function which is called when a signal is sent from the SDL application.

The routing function is made accessible from the TCP/IP adapter by setting the flag XROUTING_INC to the name of a routing header file. This is a plain C header file where the macro XFINDDEST(OUTSIG, SIGNAME, IP, PORT) is defined as a function. OUTSIG and SIGNAME are in parameters. IP and PORT are out parameters.

OUTSIG should be declared as xSignalNode*. From this parameter, signal data such as parameters can be accessed. SIGNAME holds the name of the signal and is declared as char*. In many cases, the signal name is sufficient routing information. The IP and PORT variables should be set to the host address and port number. IP should be declared as char* and PORT as int*.

The routing function should be implemented in a C file which is compiled and linked together with the application. The server IP address should be given as char*, e.g. "255.255.255.255" (dotted decimal notation) or "server.the_company.com" (hostname notation). The server port number should be given as int, e.g. 8888.

On the server side, the IP address is inherent to the host that the application resides on. The port number on which a server should listen for incoming connections should be specified using the flag XSERVPORT.

Note: Usage of Port Numbers

Generally, TCP port numbers below 1024 are reserved by operating system services or internet applications. For instance, the port numbers 21 and 23 are used by FTP and port number 80 is used by HTTP. If a port number is occupied, you will get an error message at start-up and the server thread will not start. It is recommended that you select port numbers larger than 1024 for your SDL application.

Example 534 : TCP/IP Adapter Routing Settings

This example shows a situation where different signals should be directed to different recipients. An SDL system is partitioned into three components (i.e. executable files) using the Threaded integration model. From component 1, two different signals can be sent. Sig1 should be sent to component 2 and Sig2 should be sent to component 3.

Component 2 resides on a host called "host2". It uses port number 7001 for listening for incoming connections, which means that XSERVPORT is set to 7001 (XSERVPORT=7001). Component 3 resides on "host3" and listens on port number 7001 (XSERVPORT=7001). Please note that the ports are not in conflict since the hosts are different.

For component 1, a routing function is implemented. The flag XROUTING_INC is set to "router.h". The routing header file has the following contents:

#define XFINDDEST(OUTSIG, SIGNAME, IP, PORT)\ xGetDestination(OUTSIG, SIGNAME, IP, PORT)

The routing C file, router.c, contains the implemented function:

#include "stdlib.h"

void xGetDestination(xSignalNode *sig, char *sigName, char *IPAddr, int *Port)
{
if (strcmp(sigName, "Sig1") == 0)
{
strcpy(IPAddr, "host2\0");
(*Port)= 7001; /* Dereferencing */
}
else if (strcmp(sigName, "Sig2") == 0)
{
strcpy(IPAddr, "host3\0");
(*Port)= 7001;
}

return;
}

router.c is then compiled and linked together with the generated code, the coder library and the TCP/IP adapter. This example shows a fairly trivial routing scenario. The routing is based only on the name of the signal. The xSignalNode pointer is not used.

Error Handling

The TCP/IP adapter contains basic error handling. Error checks are performed when encoding/decoding, socket and thread functions are invoked. If THREADED_ERROR is defined, an error message is printed on stdout with the name of the function where the error occurred. A platform-dependent error code is included in the error message. For a description of the error code, consult the User's Manual of your target operating system.

An error implies that the function where the error occurred exits. Clean-up is performed, which means that the application can continue its execution.

A special case to consider is when an error occurs in the server thread function, which runs statically during the execution. The thread exits and must be restarted manually.

If THREADED_TRACE is defined, the execution of the TCP/IP adapter is logged onto stdout when signals are encoded, sent, received and decoded.

Example 535 : TCP/IP Adapter Error Message

An error occurs when a signal should be sent via the TCP/IP adapter. The following is logged on stdout:

ERROR xSendSignal/SCM_CONNECT: 146

The target platform is Solaris. The error code indicates that the connection was refused, probably because a server can not be found at the specified address. xSendSignal exits and the application continues its execution.

Configuration

The TCP/IP adapter is configured using compilation flags. The basic configuration can be done using the TCP/IP Connection Wizard in the Targeting Expert.

Including the TCP/IP adapter

The TCP/IP adapter requires environment files, environment header files and ASCII encoding/decoding for correct operation. These options are activated when the TCP/IP Signal Sending check box is enabled in the Targeting Expert's TCP/IP Connection Wizard.

Server Port Number

For a component that receives signals, a TCP port number must be specified. The server thread uses this port number to listen for incoming connections.

The port number is set in a text box in the TCP/IP Connection Wizard. You can also set the port manually by setting the flag XSERVPORT to the desired value. If no port number is specified, the port number is set to 5000 by default.

Routing

You must manually implement a routing function, so that a destination is specified for every SDL signal that is sent to the environment. The function must be declared in a C header file. The file is specified in a text box in the TCP/IP Connection Wizard or by setting the flag XROUTING_INC to the header file name.

The routing function implementation should be placed in a C file that is compiled and linked with the other code. It is specified using either the text box in the TCP/IP Connection Wizard or by including it in the compiler settings manually. See Example 534 for an example of how a routing function is implemented.

Using the TCP/IP Adapter with Other Environment Functionality

The TCP/IP adapter header file (tcpipcomm.h) is included from the environment file of a component. The file tcpipcomm.h contains #define statements for macros in the environment functions that invoke TCP/IP functions.

If you want to use other functionality in parallel with the TCP/IP adapter, these macros can be defined outside tcpipcomm.h. By setting the flag XEXTENV_INC to the header file you wish to use, your header file is included from tcpipcomm.h. This enables you to insert your code without modifying tcpipcomm.h. Please note that the XEXTENV flag can not be set in the TCP/IP Connection Wizard. It must be set manually.

Before using the XEXTENV_INC flag, look carefully at the #define statements in tcpipcomm.h. These must be valid for proper operation of the TCP/IP adapter.

Hint: Using External env Code with the TCP/IP Adapter

When combining the TCP/IP adapter with other environment functions, always preprocess the environment file to verify that the code is expanded as expected.

Example 536 : External Code in Combination with the TCP/IP Adapter

A file called mycomm.h contains declarations of functions that should be used in parallel with the TCP/IP adapter. From the xInitEnv function, an initialization function should be called (InitComm()). From the xInEnv function, a function for polling communication (ReadComm()) should be invoked.

In mycomm.h, the following is inserted:

#define XENV_INIT Initcomm();\
xInitSignalSender();\
xInitSignalReceiver();
#define XENV_IN_START ReadComm();

xInitsignalSender and xInitSignalReceiver are taken from tcpipcomm.h, which contains the following:

#ifndef XENV_INIT
#define XENV_INIT xInitSignalSender();\
xInitSignalReceiver();
#endif
#ifndef XENV_IN_START
#define XENV_IN_START
#endif

The #defines in tcpipcomm.h are overridden. Still, the original calls are invoked, which ensures that the TCP/IP adapter executes properly.

Using Thread Parameters

Some thread parameters in the TCP/IP adapter can be set to fine-tune performance of your Threaded SDL application. The TCP/IP adapter threads do not use OS queues. Two parameters can be set: Thread Priority and Thread Stack Size. These are set manually using flags. They can not be set using the TCP/IP Communication Wizard.

The server wait thread uses the following flags:

XSERVTHRPRIO
XSERVTHRSTACK

The signal receiver threads use the following flags:

XRECVTHRPRIO
XRECVTHRSTACK

Set the flags to values that are specific to the target platform used.


Tight Integration

Note:

The source file and examples for Tight Integrations are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

Note:

This presentation is focused on the general principles and models used in a Tight Integration. When specific RTOS primitives are needed in the presentation, examples from the VxWorks implementation are used. The implementation and RTOS calls used in other integrations are covered in separate annexes to this chapter, one for each supported RTOS.

There are two models of Tight Integration. In the Standard Model one SDL process instance is mapped to one OS task. In the Instance Set Model an entire instance set (all instances of a process) is mapped to one OS task. Scheduling between OS tasks is managed by the RTOS scheduler; this means that preemption is normally used, though only on an instance set level in the Instance Set Model. SDL semantics are preserved in a Tight Integration, for example setting a timer implies an automatic reset first.

The start-up of a system, i.e. creation of static processes, initialization of synonyms and creation of an environment task and a timer task, is handled by a generated initialization function called yInit. Normally this function is called from another initialization function, where some additional initializations take place before the yInit function is called.

Timers in the system are handled by one central timer task. This task receives messages1, each containing a request to set a timer, and will send messages back as the timers expire.

Common Features

File Structure

The files related to the tight integration concept are placed in the following directory in the installation: <installation directory>/sdt/sdtdir/RTOS/<operating system>/TightIntegration/. The same files are used for both the Standard Model and the Instance Set Model.

Each RTOS directory contains the following files:

  • sct<RTOS>.h:
    This file contains the second level of macros (see the comments for scttypes.h in "The Integration Packages" ). All macros are using OS-specific calls or types.
  • sct<RTOS>.c:
    This file contains OS-specific support functions.
  • sdt2<RTOS>.c:
    Most RTOS require that signals/messages are represented with an integer value. This is the source file for a utility program for generating signal identities. Each signal will be assigned an integer value. The output will be a file with the suffix .hs. This file is automatically included in the application.
    In the SDL suite, the .hs file can also be generated by the SDL to C Compiler by turning on the option Generate signal number file in the Make dialog. The .hs file is included in the application if the compilation switch XINCLUDE_HS_FILE is set.

The SDL_PId Type

The SDL_PId (SDL Process ID) type has different meanings in the Standard and the Instance Set Models. In the Standard Model it represents the message queue, while it represents the process instance in the Instance Set Model. This is because the entire instance set will have the same message queue in the last case.

#ifdef X_ONE_TASK_PER_INSTANCE_SET
typedef xEPrsNode SDL_PId;
#else
typedef MSG_Q_ID SDL_PId;
#endif

Signals

The signal header consists of a struct with information needed to handle the signal inside an SDL system. The signal header struct is defined in the RTOS-specific file sct<RTOS>.h.

typedef struct xSignalHeaderStruct *xSignalHeader;
typedef struct xSignalHeaderStruct {
int SignalCode;
xSignalHeader Pre, Suc;
SDL_PId Sender;
void *SigP;
#ifdef X_ONE_TASK_PER_INSTANCE_SET
SDL_PId Receiver;
#endif
#ifdef XMSC_TRACE
int SignalId;
int IsTimer;
#endif
} xSignalHeaderRec;

The signal header stores SignalCode, in this case an integer, two pointers Pre and Suc used when saving the signal in the save queue, and Sender, holding the SDL_PId of the sending SDL process. In the Instance Set Model there is an extra parameter Receiver, necessary to make a distinction between the SDL processes in an instance set task.

If the signal contains parameters they are allocated in the same function call. Example:

OutputSignalPtr = xAlloc (sizeof (xSignalHeaderRec) + sizeof(yPDef_z05_s2));

The second parameter to the xAlloc function is a struct representing the signal parameters of the signal. In this case, with one integer, it is defined in the following way:

typedef struct {
SIGNAL_VARS
SDL_Integer Param1;
} yPDef_z05_s2;

The macro SIGNAL_VARS is in most RTOS empty.

There is an extra element in the SignalHeader defined as a void pointer. This pointer SigP is set to point to the parameter area.

OutputSignalPtr->SigP = OutputSignalPtr+1;

This pointer is used in the Signal-Free-Function to address the parameter-part of either a signal-structure as also a timer-signal-structure.

Note:

The SDL signal parameters are always named Param1, Param2, etc.

Assignment of the signal parameter is done in generated code and not in a macro. Example:

SIGNAL_ALLOC_ERROR
yAssF_SDL_Integer(((yPDef_z05_s2*)
OUTSIGNAL_DATA_PTR)->Param1 ,yVarP->z023_param1,
XASS);

The macro OUTSIGNAL_DATA_PTR macro is defined:

#define OUTSIGNAL_DATA_PTR (yOutputSignalPtr->SigP)

After expansion of the whole expression the code will be:

((yPDef_z05_s2 *) ((xSignalHeader) yOutputSignalPtr + 1))->Param1 = yVarP->z023_param1;

Signal reception

The support function xInputSignal is used for receiving signals in both models of Tight Integration. The implementation and the parameters are different though.

Timer Signals

A timer signal is defined similarly to an ordinary signal but will contain some additional elements representing time-out time, etc. The timer header struct looks like this:

typedef struct xTimerHeaderStruct *xTimerHeader;
typedef struct xTimerHeaderStruct {
int SignalCode;
xTimerHeader Pre, Suc;
SDL_PId Sender;
void *SigP;
#ifdef X_ONE_TASK_PER_INSTANCE_SET
SDL_PId Receiver;
#endif
#ifdef XMSC_TRACE
int SignalId;
int IsTimer;
#endif
SDL_Time TimerTime;
int TimerToSetOrReset;
xbool (* yEq)();
xbool TestParams;
xTimerHeader Param;
} xTimerHeaderRec;

Note:

An ordinary signal is identical to the first part of a timer signal. This makes it possible to type-cast between the two types as long as only elements in the common part of the headers are used.

Time

When the System time is required, for example when using NOW, the macro SDL_NOW is used. The macro is in turn mapped to the function SDL_Clock() (in sctos.c). This function is implemented differently depending on the RTOS representation of time. In VxWorks it returns the result of calling the RTOS function tickGet. SDL_Time is normally implemented as int or unsigned long int.

Mapping Between SDL Time and RTOS Time

The macro SDL_DURATION_LIT specifies the mapping between the SDL time in seconds and the local RTOS representation of time. In VxWorks the system time is given in ticks and the translation is defined as follows:

#define SDL_DURATION_LIT(R,I,D) \
((I)*1000 + (D)/1000000)

R is the real type representation of the time in seconds. I and D are the integer and decimal parts of an integer type representation of the time. I is in seconds and D in nanoseconds. The code generator will generate all three numbers but either R, or I and D will be used depending on the RTOS.

Timers

All timer activity in the SDL system is handled by a dedicated timer task. The timer task accepts requests in the form of messages (in VxWorks). It then keeps the requests for setting a timer sorted in a timer queue and uses some OS mechanism to wait for the first request to time out. The mechanism used can be either an OS timer, or a timeout in the waiting for new requests. When a request times out, the timer task sends a signal back to the task that first sent the request. The function calls and OS signaling involved in setting and waiting for an SDL timer can be viewed in Figure 563.

Figure 563 : Function calls and OS signaling when setting and waiting for a timer.

UML notation is being used, thus the full arrowheads represent function calls and the half arrowheads represent messages. Parameters have been left out, except for the name of the timer in the ResetTimer request. Note that a reset is performed first, as required in the SDL specification.

To be able to implement the full semantics of SDL timers a number of support functions have been implemented:

  • xSDLActive
    Checks whether an SDL timer is active and returns true or false. The function passes the question on to the timer task in the form of a request.
  • xSDLActiveInTimerTask
    Called by the timer task upon request. Checks if an SDL timer is active and returns true or false.
  • xSDLReset
    Resets an SDL timer by sending a request to the timer task. While waiting for a reply all new signals to the calling task are saved in the save queue. In the case of an Instance Set Model Tight Integration this means that no instance of the process can execute a transition until a reply is received. If the reply states that the timer couldn't be found it might be in the save queue or the input queue of the task because it has recently expired. If so, it is simply removed. SDL semantics require that a reset is always performed implicitly prior to setting a timer.
  • xSDLResetInTimerTask
    Called by the timer task when a request has been made for resetting a timer. Checks the timer queue to see if the timer to reset is there. If the timer is found, it is removed and the data area it holds is freed. A message is sent back to the task that made the request, telling whether the timer was found or not.
  • xSDLSet
    Called by the timer task when a request has been made for setting a timer. This function sorts the request into the timer queue.

Addressing SDL Processes

There are two ways to address SDL processes from an external task. Either the xFindReceiver function can be called to find an arbitrary receiver, or the file pidlist.pr can be used to provide a list of the SDL processes and then address the receiver explicitly via the input queue ID of its OS task.

The xFindReceiver Function

When sending a signal into the SDL system where the receiver is not known a support function called xFindReceiver can be used. This function takes the following parameters:

  • The ID of the signal
  • The sender ID (in this case an SDL_PId representing the environment)
  • An optional VIA-list.

The following files are needed to get access to SDL types, signal numbers and signal parameter types: scttypes.h, <system_name>.hs and <system_name>.ifc.

Example of how to use the xFindReceiver function:

#include "scttypes.h"
#include "<system_name>.ifc"
#include "<system_name>.hs"

void MyExtTask(void) {

xSignalHeader yOutputSignalPtr;
int Err;

/*Allocate signal header and signal parameter
buffer */
yOutputSignalPtr =
(xSignalHeader)xAlloc(sizeof(xSignalHeaderRec)
+ sizeof(yPDef_go);

/*Setup signal header */
yOutputSignalPtr->SignalCode = go;
yOutputSignalPtr->Sender = xEnvPId;

/*Give value 100 to integer parameter */
((yPDef_go *)(yOutputSignalPtr+1))->Param1 = 100;

/*Send signal from environment */
Err = msgQSend(xFindReceiver(go, xEnvPrs, 0),
(char*) yOutputSignalPtr,
sizeof(xSignalHederRec)+sizeof(yPDef_go),
0 ,0);
}

The following types, signal definitions and global variables are used in the example:

  • xEnvPId: An SDL PId representing the environment, from scttypes.h
  • xEnvPrs: A PrsNode representing the environment, from scttypes.h
  • xSignalHeader: A datatype representing an SDL signal, from scttypes.h
  • yPDef_go: A datatype representing the signal parameter types, from <system_name>.ifc
  • go: An SDL signal, from <system_name>.ifc

The File pidlist.pr

An alternative way to get the PId for the Receiver is to use an ADT defined in the ADT library called pidlist.pr. This file defines an ADT called PidList and an operator called PId_Lit. With this ADT it is possible to directly address any static process instance in the system, both from internal SDL processes and from external OS-tasks. You can find more information about this feature in "How to Obtain PId Literals" .

Note:

If you need the pidlist.pr ADT in a Tight Integration then you must use the version in the
<installation directory>/sdt/sdtdir/RTOS/SDL/
directory.

The Standard Model

In the Standard Model of the Tight Integration each SDL process is implemented as an OS task. Preemption and the use of process priorities is only limited to what the OS supports.

Processes

Process Creation

An SDL process is created in the following way (in the VxWorks integration):

  1. A start-up signal is allocated.
  2. A message queue is created. Some operating systems create the message queue automatically when the task is created. This is explained for each operating system in the annexes to this chapter.
  3. The task is created with the message queue ID as a start-up parameter. In the case of VxWorks, the task will have a name starting with VXWORKSPAD_. This is a function which will first initialize some internal variables and then call the PAD function.
  4. A function (xAllocPrs) is called to create a representation of the new instance in the global symbol tree.
  5. The start-up signal is sent. When this signal is received in the task the start transition of the process is executed.

Process Termination

The following actions are carried out when a process terminates:

  1. The save queue and the message queue are emptied.
  2. The save queue is deleted.
  3. A message is sent to the xTimerTask with a request to remove all active timers of the process.
  4. xFreePrs is called to free the PrsNode.
  5. The message queue is deleted. In some operating systems this is done automatically when the task is deleted.
  6. The task is deleted.

PAD functions

Each PAD (Process Activity Definition) function will contain an eternal loop with an OS receive statement. When a process instance is created it is the PAD function that is called in the OS Create primitive.

The start-up and execution of a PAD function works like this:

  1. The support function xInputSignal is called. This function will wait for the start-up signal, that is always received first, and then return to the PAD function.
  2. The PAD function goes to the label Label_Execute_Transition. This label is the start of a code block containing a switch statement that evaluates the process variable RestartAddress. The code under each different case then represents a transition. At the end of this block the process variable State is updated and execution continues at Label_New_Transition.
  3. In Label_New_Transition a new call is made to xInputSignal and execution then continues at Label_Execute_Transition.

The structure of a PAD function is described below (with pseudo-code shown in italics):

void yPAD_z01_pr1 (void *VarP)
{
Variable declarations
xInputSignal is called to receive the start-up signal
...........
goto Label_Execute_Transition;
...........
Label_New_Transition:
xInputSignal is called to receive a signal

Label_Execute_Transition:
Local declarations
switch (yVarP->RestartAddress) {
case 0:
Execute the start transition
Update the process state variable
goto Label_New_Transition;
case 1:
Execute the transition
Update the process state variable
goto Label_New_Transition;
...........
}
...........
}

Scheduling

Since each SDL process is implemented as an OS task, scheduling between processes will be handled completely by the OS.

Start-up

Start-up of a Standard Model Tight Integration can be described as follows (pseudocode is shown in italics):

MyMain() {
/* initialization of semaphores etc */
yInit();
Give startup semaphores
taskSuspend(Mymain);
}

yInit() {
Create the timer task
Create an environment task or only an environment queue
for(i=1;i<=NoOfStaticProcessTypes;i++){
for(j=1;j<=NoOfStaticInstancesOfEachProcesstype;
j++){
Allocate a startup signal
Create a message queue
Create a task
Call xAllocPrs
Send the startup signal
}
}
Assign SDL synonyms
}

The semaphore is used for synchronizing start-up of static processes. No static process is allowed to execute its start transition before all static processes are created, because a start transition can have signal sending to other static instances.

The MyMain function is placed among other support functions in the file sctsdl.c.

The yInit function is generated by the code generator and placed last in the generated file for the system.

The Instance Set Model

The Instance Set Model is based on the same principles as the Standard Model with the difference that the instance set is the basic unit rather than the process instance.

Processes

Both the instances and the instance sets are represented in the symbol table. In addition to the three parts that always make up an SDL process there is also an extra struct for the instance set, defining for example the input queue which is common to all the instances. Further, there is a PAD function for each instance, but also for the instance set.

Process Representation

An SDL_PId is represented by an xEPrsNode, pointing to an xEPrsStruct. An xEPrsNode also represents a process instance in the symbol table both in the Standard Model and the Instance Set Model.

typedef struct xEPrsStruct {
xEPrsNode NextPrs;
SDL_PId Self;
xPrsIdNode NameNode;
int BlockInstNumber;
xPrsNode VarP;
} xEPrsRec;

Instance Set Data

The datatype xPrsInstanceSetVars is only used in the Instance Set Model. It defines common data for all instances of the set, like the save queue and the size of the instance data.

typedef struct {
xSignalHeader SaveQ;
xSignalHeader CurrentInSaveQ;
xSignalHeader yInSignalPtr;
char name[100];
unsigned PrsDataSize;
} xPrsInstanceSetVars.

PAD functions

In the Instance Set Model there is a PAD function for each process instance but also for each instance set. The instance set PAD functions will be called at system start-up and contain an eternal loop in the same fashion as PAD functions in the Standard Model. Instance PAD functions are only called to execute transitions.

Process Creation

All instance sets, even for dynamic processes, are created at system start-up. Since the OS task and the signal queues are created with the instance set, the creation of an instance requires less labor than in the Standard Model. For the instance set creation the macro INIT_PROCESS_TYPE is used.

Process Termination

The instance set task is never terminated. Termination of a process instance will not remove the save queue, the input queue and the task. This is done at system termination. All queues, including the active timer queue, are emptied of messages to the terminated process though.

Signal queues

The message queue id of the receiver's instance set is accessed through NameNode in the receiver's xEPrsStruct and the variable PROCID.

Example from xSDLResetInTimerProcess:

Err=msgQSend ((MSG_Q_ID) (yInSignalPointer->Sender)
->NameNode->PROCID, (char *) yInSignalPointer,
sizeof (xTimerHeaderRec), 0, 0);

In this case the receiver is the same as the original sender.

Signal sending

A support function xHandle_Sig is used when sending signals, instead of the macro RTOSSEND as in the Standard Model. This difference is shown in bold in the code below:

#ifdef X_ONE_TASK_PER_INSTANCE_SET
#define SDL_2OUTPUT(PRIO, VIA, SIG_NAME, SIG_IDNODE,\
RECEIVER, SIG_PAR_SIZE, SIG_NAME_STRING)\
XOS_TRACE_OUTPUT(SIG_NAME_STRING) \
XMSC_TRACE_OUTPUT(RECEIVER, yOutputSignalPtr, \
SIG_NAME_STRING) \
xHandle_Sig(yOutputSignalPtr,SDL_SELF,SIG_PAR_SIZE,\
RECEIVER,(RTOSTASK_TYPE)RECEIVER-> \
NameNode->PROCID RTOSHANDLESIG_PAR);
#else
#define SDL_2OUTPUT(PRIO, VIA, SIG_NAME, SIG_IDNODE, \
RECEIVER, SIG_PAR_SIZE, SIG_NAME_STRING)\
XOS_TRACE_OUTPUT(SIG_NAME_STRING) \
XMSC_TRACE_OUTPUT(RECEIVER, yOutputSignalPtr,\
SIG_NAME_STRING) \
RTOSSEND(&yOutputSignalPtr, RECEIVER,SIG_PAR_SIZE)
#endif

Scheduling

Scheduling between instance sets is handled by the operating system. Within the instance sets, however, scheduling is based on the signal queue. When the instance set PAD function is executing, it takes the first signal in the input queue and calls the PAD function of the addressed SDL process. The instance PAD function then executes one transition and returns control to the scheduling loop of the instance set PAD function.

Integrating with external code

You can easily integrate the SDL system with external code, for example written in C. Just use the hooks described below for inserting C statements in the main() function of the SDL system.

The hooks are in the form of #define macros located in a file called scthooks.h. A file called scthooks.h_template with empty macros can be found in the INCLUDE directory. Use this file as a template for your own application. You will find usage examples in the Examples directory.

HOOK_GLOBAL_DECLARATIONS

This hook lets you declare function prototypes etc. at file scope.

HOOK_MAIN_DECLARATIONS

This hook lets you declare variables for use in the main() function.

HOOK_MAIN_START_OF_CODE

Any code inserted here will execute first in the main() function.

HOOK_MAIN_AFTER_PROCESS_RELEASE

Any code inserted here will execute as soon as all static processes have been created and are allowed to run.

HOOK_MAIN_AFTER_SIGNAL_RECEPTION

The main() function of the SDL system enters an infinite loop after having created all static processes. This loop is used to receive signals sent to the environment queue.

Use the HOOK_MAIN_AFTER_SIGNAL_RECEPTION to insert code for processing these signals.

1

SDL signals will be implemented as messages in VxWorks.


Limitations for Integrations

In general, the same restrictions as for the SDL to C Compiler apply, but Tight integrations have some further restrictions. The detailed limitations for Light and Tight integrations are listed in the Release Guide.


A Simple Example

This section describes an example system named Simple. The annexes show how to integrate the example with different operating systems.

The example demonstrates the following techniques:

  • How to integrate an SDL system with an operating system
  • How to make the environment communicate with the SDL system in a Light integration
  • How to make an external process written in C communicate with the SDL system in a Tight integration
  • How to use the special Tight Integration version of the ADT pidlist.pr .

The Simple System

Figure 564 : System Simple

The SDL representation of Simple consists of a single block Bl1. Seen from the outside, the system accepts the signal Go and responds after about five seconds by sending the signal Ok. The signal Go may be sent twice to the system.

Block Bl1

Figure 565 : Block Bl1

Block Bl1 has two processes. The static process Pr1 and the dynamic process DynPr1. DynPr1 is created by Pr1 and can send the signal Terminating back to its parent. Pr1 handles all the interaction with the environment, through the signals Go and Ok.

Process Pr1

Figure 566 : Process Pr1

Process Pr1 is a static process with two instances. It has two states, Idle and Wait. In the Idle state the process waits for the signal Go with an integer parameter representing the instance number of this instance. It then prints the instance number to the standard output, creates one instance of DynPr1 and enters the Wait state. In the Wait state it waits for the signal Terminating from the created instance of DynPr1, sends Ok back to the environment and goes back into the Wait state. Since the Terminating signal will only be received once, the process is going to remain in the Wait state forever.

Process DynPr1

Figure 567 : Process DynPr1

The dynamic process DynPr1 has no instances at system start and a maximum of two instances. Each instance of Pr1 creates one instance of DynPr1. DynPr1 sets the timer t1 to five seconds, waits for a timeout, sends the signal Terminating to its creator and finally terminates.

Connection to the Environment

The environment is handled in different ways depending on the integration model. See below for details.

Building and Running a Light Integration

This section will take you through the general steps required to build a Light Integration for the Simple example. The procedure works the same for most operating systems. Please also check the annexes for important information about your operating system.

General Steps for a Light Integration

  1. Create a working directory and an INCLUDE directory below it.

Note:

 $(sdtdir) = <installation
directory>/sdt/sdtdir/<machine dependent dir>

where <machine dependent dir> is sunos5sdtdir on SunOS 5, hppasdtdir on HP, and wini386 in Windows.

  2. Copy all files from $(sdtdir)/RTOS/Examples/Simple/<selected RTOS>/LightIntegration to the working directory.
  3. Copy the following files to the INCLUDE directory:
$(sdtdir)/INCLUDE/sctlocal.h
$(sdtdir)/INCLUDE/sctpred.c
$(sdtdir)/INCLUDE/sctsdl.c
$(sdtdir)/INCLUDE/sctos.c
$(sdtdir)/INCLUDE/sctpred.h
$(sdtdir)/INCLUDE/scttypes.h
  4. Open the system file $(sdtdir)/RTOS/Examples/Simple/simple.sdt
  5. Change the destination directory to your working directory
  6. Set the options Lower Case and Generate environment header file.
  7. Select the Cadvanced SDL to C Compiler and generate an application.
  8. Edit the makefile supplied with the example to fit your environment. Normally you will only have to point out the directory where the RTOS is installed.
  9. Use the makefile to build an executable.
  10. Download the executable to target or run it under a kernel simulator ("soft kernel").

Result From Running the System

The output when running the example should be:

Signal Go received in Pr1:Instance1
Signal Go received in Pr1:Instance2
Signal Ok received with the following parameter:1
Signal Ok received with the following parameter:2

The xInEnv Function

This is where the start-up signal Go is sent. In a real system xInEnv may be used for polling hardware devices for data. The code looks like this:

xSignalNode S;
static int SendGo = 0;

if(SendGo<=1){
if(SendGo==0) {
S = xGetSignal(go, pr1[1], xEnv );
((yPDef_go *)(S))->Param1 = startinstance1;
}
else {
S = xGetSignal(go, pr1[2], xEnv );
((yPDef_go *)(S))->Param1 = startinstance2;
}
SDL_Output( S, xSigPrioPar(xDefaultPrioSignal)
(xIdNode *)0 );
SendGo++;

The signal Go is sent the first and the second time xInEnv is called. The parameters startinstance1 and startinstance2 are integer constants defined in the SDL system, as integer SYNONYM's. They are made available by generating and including the file simple.ifc.

The xOutEnv Function

The code in xOutEnv for receiving the signal Ok looks like this:

if ( ((*S)->NameNode) == ok ) {
printf("Signal Ok received with the following
parameter:%lu\n",
((yPDef_ok *)(*S))->Param1);
xReleaseSignal( S );
return;

The signal Ok also has an integer parameter, the value of this should be 1 if it is sent by Pr1 instance one and 2 if it is sent by instance two.

Building and Running a Tight Integration

This section will take you through the general steps required to build a Tight Integration for the Simple example. The procedure works the same for most operating systems. Please also check the annexes for important information about your operating system.

Note:

The source file and examples for Tight Integrations are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

General Steps for a Tight Integration

  1. Create a working directory and an INCLUDE directory below it.

Note:

 $(sdtdir) = <installation
directory>/sdt/sdtdir/<machine dependent dir>

where <machine dependent dir> is sunos5sdtdir on SunOS 5, hppasdtdir on HP, and wini386 in Windows.

  2. Copy all files from $(sdtdir)/RTOS/Examples/Simple/<selected RTOS>/TightIntegration to the working directory.
  3. Copy all files from $(sdtdir)/RTOS/Examples/Simple/<selected RTOS>/TightIntegration/INCLUDE to the INCLUDE directory.
  4. Open the system file $(sdtdir)/RTOS/Examples/Simple/simle.sdt
  5. Change the destination directory to your working directory.
  6. Set the options Lower Case, Generate environment header file and Generate signal number file.
  7. Select the Cadvanced SDL to C Compiler and generate an application.
  8. Edit the makefile supplied with the example to fit your environment. Normally you will only have to point out the directory where the RTOS is installed.
  9. Use the makefile to build an executable.
  10. Download the executable to target or run it under a kernel simulator ("soft kernel").

Result From Running the System

The output when running the example depends on what kind of trace has been enabled. If you set XMSC_TRACE it should be similar to the following:

System_Init_Proc: instancehead process Environment;
msc RTOS_Trace;
Pr11: instancehead process Pr1;
Pr12: instancehead process Pr1;
Pr11: condition Idle;
Pr12: condition Idle;
Pr11: in Go,0 from MyExtTask3;
Signal Go received in Pr1:Instance1
dynpr14: instancehead process dynpr1;
Pr11 : create dynpr14;
Pr11: condition Wait;
Pr12: in Go,1 from MyExtTask3;
Signal Go received in Pr1:Instance2
dynpr15: instancehead process dynpr1;
Pr12 : create dynpr15;
Pr12: condition Wait;
dynpr14: set T1,2 (5000); /* #SDTNOW(269) */
dynpr14: condition wait;
dynpr15: set T1,3 (5000); /* #SDTNOW(276) */
dynpr15: condition wait;
dynpr14: timeout T1,2; /* #SDTNOW(5284) */
dynpr14: out Terminating,4 to Pr11;
dynpr14: endinstance;
Pr11: in Terminating,4 from dynpr14;
Pr11: out Ok,5 to MyExtTask3;
Ok received in MyExtTask with paramer = 1
dynpr15: timeout T1,3; /* #SDTNOW(5463) */
dynpr15: out Terminating,6 to Pr12;
dynpr15: endinstance;
Pr12: in Terminating,6 from dynpr15;
Pr12: out Ok,7 to MyExtTask3;
Ok received in MyExtTask with paramer = 2

Setting the XOS_TRACE flag should result in the following output:

** Process Pr1:9901455 created **

** Process Pr1:9901456 created **

** Process instance 9901455 **
Pr1: nextstate Idle

** Process instance 9901456 **
Pr1: nextstate Idle

** Process instance 9901455 **
Pr1: input signal Go
Signal Go received in Pr1:Instance1
Pr1: process dynpr1:9901458 created
Pr1: nextstate Wait

** Process instance 9901456 **
Pr1: input signal Go
Signal Go received in Pr1:Instance2

** Process instance 9901458 **

DynPr1: Set timer T1
Process instance 9901459
DynPr1: nextstate wait

** Process instance 9901458 **
DynPr1: input signal T1
DynPr1: signal Terminating sent
DynPr1: stopped

** Process instance 9901455 **
Pr1: input signal Terminating
Pr1: signal Ok sent
Pr1: dash nextstate
Ok received in MyExtTask with parameter = 1

** Process instance 99014516 **
DynPr1: input signal T1
DynPr1: signal Terminating sent
DynPr1: stopped

** Process instance 99014513 **
Pr1: input signal Terminating
Pr1: signal Ok sent
Pr1: dash nextstate
Ok received in MyExtTask with parameter = 2

Standard Model

In the standard model each instance of the Pr1 and the DynPr1 processes will be represented by an OS task (in all four tasks). The environment is represented by a task called MyExtTask. This task is external to the SDL system.

Instance Set Model

In the instance set model there will be two OS tasks, one each for Pr1 and DynPr1. The environment is represented by a task called MyExTask, just as in the standard model. This task is external to the SDL system.

How Signals are Sent to and from the Environment

There is an external task called MyExtTask which is written in C. It sends the signal Go into the SDL system and receives the signal Ok back by using services in the operating system.

The HOOK_MAIN_AFTER_PROCESS_RELEASE macro in scttypes.h is used to create MyExtTask as soon as the SDL system allowed to run.

The source code for the external task is placed in the file MyExtTask.c. This file is specific to the selected operating system because it calls the operating system directly.


Tight Integration Code Reference

This section explains data types, procedures and macros used in a Tight Integration (Light Integrations are explained in the Master Library).

General Macros

XPP(x)

The macro XPP is used in function declarations to specify the function parameters. It is defined like this:

#define XPP(x) x

if function prototypes according to ANSI C can be used.

xptrint

The following type is also always defined:

#define xptrint unsigned

where xptrint should be an int type with the same size as a pointer.

xPrsNode and xPrdNode

typedef struct xPrsStruct *xPrsNode;
typedef struct xPrdStruct *xPrdNode;

xPrsNode and xPrdNode are pointers to structs holding instance data for an instance of a process or a procedure. Note that some parts of the structs are OS-dependent.

xInputAction, xNotInSignalSet ...

These defines specify the different ways of handling a signal.

Macros to Exclude Unnecessary Code

The following macros are defined to exclude unnecessary code for IdNode variables etc.:

#define XNOSTARTUPIDNODE
#define XOPTSIGPARA
#define XOPTDC
#define XOPTFPAR
#define XOPTSTRUCT
#define XOPTLIT
#define XOPTSORT
#define XNOUSEOFSERVICE
......

Macros to activate Signal-Free-Functions

The following macro must be defined to activate the Signal-Free-Functions. This is necessary if signals and timers with string parameter (dynamic allocated) are used - to avoid memory leaks.

#define XFREESIGNALFUNCS

If strings not are used as parameters in signals this flag should not be set cause it does lead to some performance deterioration. (Normally this define is set in the make-file).

For timer string parameters the define

#define XTIMERSWITHSTRINGPARAMS

must be set.

The following macro must be defined to activate the Signal-Free-Functions. This is necessary if signals and timers with string parameter (dynamic allocated) are used - to avoid memory leaks.

#define XFREESIGNALFUNCS

Default Priorities

One group of macros defines default priorities for processes and signals:

#ifndef xDefaultPrioProcess
#define xDefaultPrioProcess RTOSPRIODEFAULT
#endif

#ifndef xDefaultPrioSignal
#define xDefaultPrioSignal RTOSPRIODEFAULT
#endif
...

Macros to Implement SDL

First in this section is a macro defining the symbol table root:

xIdNode xSymbolTableRoot;

XPROCESSDEF_C and XPROCESSDEF_H

These macros define the start-up function for a PAD function. It is this function that is called in the task creation. As mentioned before this function will after some variable initializations call the PAD function. The definition of the start-up function varies in different RTOS, that is why there is a second OS-specific macro here.

STARTUPSIGNAL, ALLOCPRSSIGNAL, etc.

Each signal in an application is assigned a unique integer value. The values 31992 through 32000 are reserved for internal signals like the start-up signal.

Variables in the PAD Function

PROCESS_VARS, PROCEDURE_VARS

These macros define the elements in the xPrsStruct and xPrdStruct respectively.

YPAD_YSVARP

This macro defines a variable representing a pointer to a signal's parameter area.

YPAD_YVARP

This macro defines the variable yVarP which represents the process instance data.

LOOP_LABEL, LOOP_LABEL_PRD, LOOP_LABEL_PRD_NOSTATE

These three macros define the eternal loop inside processes, procedures and procedures without a state.

START_STATE

Each state in a process and procedure is represented as an integer. The Start state will always have the value 0.

Using OSE Trace Features

Note:

Telelogic has noticed that the OSE-trace feature can make the application crash in some situations. This seems to happen when a SDL process (OSE-task) sends a signal immediately before terminating. If you come across this problem, first check if the application works correctly when generated without OSE-trace.


Annex 1: Integration for OSE Delta

Introduction

This annex briefly describes the OSE Delta models and primitives used in the SDL suite OSE tight integration. The presentation is focused on the differences from the OSE classic model described in the previous annex.

One section describes how to set up and run a simple test example in both a light and tight integration.

Note:

Third-party products referred to in this manual may have limitations that have impact on the usability of Telelogic Tau. Please consult the supplier's support organization or the third-party product's technical reference documentation for up-to-date information about such limitations.

Principles

This integration is developed with OSE Delta Soft Kernel 3.2 and tested on a Sun workstation with SunOS Release 5.6.

The main differences between the OSE Delta and the OSE Classic model are:

  • The OSE Delta model uses three semaphores to avoid synchronization problems in SDL start transitions.
  • The timer is implemented in systimer.c, which is supplied by ENEA. This is not accurate and is only for demonstration purposes. You will have to supply a suitable timer implementation for the target environment.

Running the Test Example: Simple

Note:

The source file and examples for Tight Integrations are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

Prerequisites

This test example is developed as an OSE Delta application on a Sun workstation. The makefile and compilation switches are set up for the application to run under an OSE Simulator for OS68. If you are using another configuration of OSE you probably need to edit the provided makefile.

Figure 568 : File structure for the Simple example

Light Integration

Limitations for the Light Integration

Please see the Release Guide.

Building a Light Integration

Please see the "Building and Running a Light Integration" for instructions.

Tight Integration

Limitations for the Tight Integration

Please read the Release Guide for details about limitations that apply to all systems using Tight Integration.

Building a Tight Integration

Please see the "Building and Running a Tight Integration" for instructions.

How Signals are Sent to and from the Environment.

The signal Go is sent from an external task MyExtTask. The code for this task is placed in the program file MyExtTask.c. This is the same as used for OSE Classic.


Annex 2: Integration for VxWorks

Introduction

This annex describes briefly the VxWorks models and primitives used in the SDL Suite VxWorks tight integration. The presentation is focused on the differences from the general model described earlier in this chapter.

One section describes how to set up and run a simple test example in both a light and tight integration.

Note:

Third-party products referred to in this manual may have limitations that have impact on the usability of Telelogic Tau. Please consult the supplier's support organization or the third-party product's technical reference documentation for up-to-date information about such limitations.

Principles

This integration is developed with VxWorks Tornado 1.0 version and tested under VxSim version 5.3 on a Sun workstation with SunOS 4.1.4.

The main differences between VxWorks and the general model are:

  • The VxWorks msgQReceive copies the Signal into a buffer when it is received. The sender makes free of the signal immediately after it has been sent and the receiver allocates a buffer (signal) before a receive statement.
  • An extra optimization flag XOPTSIGNALALLOC has been introduced for the VxWorks tight integration. When freeing a signal's memory, we place it in an availlist so that subsequent signal memory allocation calls can check to see if suitable sized memory already exists which may be reused. Otherwise memory is allocated as normal.

Running the Test Example: Simple

Note:

The source file and examples for Tight Integrations are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

Prerequisites

This test example is developed as a VxWorks Tornado application on a Sun workstation. The makefile and compilation switches are set up for the application to run under an VxSim target simulator. If you are using another configuration of VxWorks you probably need to edit the provided makefile.

Figure 569 : File structure for the Simple example

Note:

A VxWorks application is not allowed to contain a main function. The name of the generated main is changed to "root" with the compilation switch -DXMAIN_NAME=root.

Light Integration

Limitations for the Light Integration

Please see the Release Guide.

Building a Light Integration

Please see the "Building and Running a Light Integration" for instructions.

Tight Integration

Limitations for the Tight Integration

Please read the Release Guide for details about limitations that apply to all systems using Tight Integration.

Building a Tight Integration

Please see the "Building and Running a Tight Integration" for instructions.


Annex 3: Integration for Win32

This annex briefly describes integration with Win32. The presentation is focused on the differences from the general model described earlier in this chapter.

Note:

Third-party products referred to in this manual may have limitations that have impact on the usability of Telelogic Tau. Please consult the supplier's support organization or the third-party product's technical reference documentation for up-to-date information about such limitations.

Principles

This integration is developed using the Microsoft 32-bit C/C++ Compiler Version 11.00.7022 and tested on NT 4.0, NT 3.51 and Windows 95 platforms. The integration is also compiled with Borland C++ 5.2 for Win32 and tested on NT 4.0, NT 3.51 and Windows 95 platforms.

The main differences between integration with Win32 and the general model are:

  • Threads are created with the Win32 primitive CreateThread(). The thread is then automatically given an input queue the first time it calls a USER or GDI function
  • xAlloc is implemented with Win32 function HeapAlloc().
  • xFree is implemented with Win32 function HeapFree().
  • The timer implementation uses the Win32 GetTickCount() function.

Running the Test Example: Simple

Note:

The source file and examples for Tight Integrations are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

Prerequisites

This test example is developed as a Win32 console application on a PC. The makefiles and compilation switches are set up for the application to compile using either the Borland or the Microsoft compiler listed above. There is a separate makefile for each compiler.

Figure 570 : File structure for the Simple example

Light Integration

Limitations for the Light Integration

Please see the Release Guide.

Building a Light Integration

Please see the "Building and Running a Light Integration" for instructions.

There are different makefiles provided for Borland compilers and Microsoft compilers.

Tight Integration

Limitations for the Tight Integration

Please read the Release Guide for details about limitations that apply to all systems using Tight Integration.

Building a Tight Integration

Please see the "Building and Running a Tight Integration" for instructions.

There are different makefiles provided for Borland compilers and Microsoft compilers.

Note:

The command line length limitation for the Borland compiler can sometimes be exceeded. If this happens, you should define the DEFINE MACROS at the beginning of the sctwin32.h file.

Compiler Flags

The following defines (#ifdef) are used in this integration:

  • WIN32_INTEGRATION: Ensures that the sctwin32.h file is included in each C file. Must be set in all cases.
  • XOS_TRACE: Gives a textual trace for most of the SDL events by using printf to some device. This flag should not be used together with XMSC_TRACE.
  • XMSC_TRACE: Will give a textual trace in the format of MSC/PR Z.120 by using printf. This trace is possible to view in the MSC Editor included in Telelogic Tau. This flag should not be used together with XOS_TRACE.
  • XMSC_EDITOR: Used together with the XMSC_TRACE flag, the MSC trace is automatically displayed in the MSC Editor. Note that you must have the Organizer open on your machine.
  • X_ONE_TASK_PER_INSTANCE_SET: States that the Instance Set Model is used. The Standard Model is otherwise chosen by default.
  • XERR: When this flag is defined, the return status of all Win32 function calls will be printed.
  • XINCLUDE_HS_FILE: Includes the system signal header file which is required for tight integrations. This file maps signal names to integers.
  • XRTOSTIME: Should always be set for all tight integrations.
  • XUSING_SCCD: This should be set when using the preprocessor SCCD to ensure that the windows header files are not included on the preprocessor pass. The files are included though on the compiler pass and this ensures that the preprocessed C files only contain the expanded the SDL suite macros. It also helps greatly to speed up the process. Note that this flag only works with the Microsoft compiler and should not be used with any other compiler.
  • XWINCE: This flag allows you to compile the integration for Microsoft WinCE target systems. This flag should not be used together with the MSC trace flags.


Annex 4: Integration for Solaris 2.6

Introduction

This annex describes briefly the Solaris 2.6 model and primitives used in the SDL Suite Solaris 2.6 tight integration. The presentation is focused on the differences from the general model described earlier in this chapter.

One section describes how to set up and run a simple test example for a tight integration.

Note:

The Solaris 2.6 tight integration is fully POSIX compliant. For this reason it will not work with earlier versions of Solaris.

Note:

Third-party products referred to in this manual may have limitations that have impact on the usability of Telelogic Tau. Please consult the supplier's support organization or the third-party product's technical reference documentation for up-to-date information about such limitations.

Principles

This integration is developed using cc:WorkShop Compilers 4.2 with Solaris 2.6 running on a workstation.

The main differences between the Solaris 2.6 integration and the general model are:

  • In the file sctsolaris.h, the macros which contain the Solaris 2.6 specific function calls are implemented. The file sctsolaris.c contains the Solaris 2.6 integration specific functions.
  • The Solaris 2.6 integration is fully POSIX compliant. SDL processes are mapped to POSIX threads using the pthread_create() function and POSIX queues are created for each thread using mq_open(). The threads are suspended when its corresponding queue is empty.

Running the Test Example: Simple

Note:

The source file and examples for Tight Integrations are not included in the standard delivery. They are available as free downloads from Telelogic Support web site.

Prerequisites

This test example is developed as a Solaris 2.6 application on a workstation. The makefile and compilation switches are set up for the application to run under Solaris 2.6 using the cc:WorkShop Compilers 4.2 compiler.

Figure 571 : File Structure for the Simple example.

Light Integration

Limitations for the Light Integration

Please see the Release Guide.

Building a Light Integration

Please see the "Building and Running a Light Integration" for instructions.

Tight Integration

Limitations for the Tight Integration

Please read the Release Guide for details about limitations that apply to all systems using Tight Integration.

Building a Tight Integration

Please see the "Building and Running a Tight Integration" for instructions.

Compiler Flags

The following defines (#ifdef) are used in this integration:

  • SOLARIS_INTEGRATION: Ensures that the sctsolaris.h file is included in each C file. Must be set in all cases.
  • XOS_TRACE: Gives a textual trace for most of the SDL events by using printf to some device. This flag should not be used together with XMSC_TRACE.
  • XMSC_TRACE: Will give a textual trace in the format of MSC/PR Z.120 by using printf. This trace is possible to view in the MSC Editor included in Telelogic Tau. This flag should not be used together with XOS_TRACE.
  • XMSC_EDITOR: Used together with the XMSC_TRACE flag, the MSC trace is automatically displayed in the MSC Editor. Note that you must have the Organizer open on your machine.
  • X_ONE_TASK_PER_INSTANCE_SET: Should be defined when the alternative runtime model is to be used.
  • XINCLUDE_HS_FILE: Includes the system signal header file which is required for tight integrations. This file maps signal names to integers.
  • XRTOSTIME: Should always be set for all tight integrations.


Annex 5: Generic POSIX Tight Integration

Introduction.

Note:

The Generic POSIX integration is based on the Solaris integration. For a description and instructions on how to generate and run the example see "Annex 4: Integration for Solaris 2.6" .


Annex 6: Building a Threaded Integration

Introduction

This Tutorial, on how to create a Threaded integration, is developed on a Windows machine and is intended to be run under a Windows OS.
If you want to use this example on another machine and for another OS, please remember to choose the appropriate integration and compiler for your OS in the Targeting Expert.

Preparations

The same SDL source files for the example Simple, that is used in the Light integration example will be used in this tutorial.

Copy the Source files for the Example: Simple

  1. Create your own test directory and enter it.
  2. Copy the SDL source files for the example Simple:
    cp <installation>/sdt/sdtdir/RTOS/Example/Simple/*.s*
  3. Copy the environment file from the Win32/ThreadedIntegration directory:
    cp <your Installation>/sdt/sdtdir/RTOS/Examples/Simple/Win32/ThreadedIntegration/MyExtTask.c
  4. Start the SDL suite and open the system file for the Simple example.

Partition the system using the Deployment Editor

  1. Create a new deployment diagram and call it Simple.
  2. Edit the deployment diagram according to the figure below, see : Signalling in Threaded Integration.

Figure 572 Deployment Diagram for the example Simple

  3. Make sure that you got the multiplicity right on the aggregation line from the component to thread.
    To check this you can double click on the line. The right value should be:
    • 1 - On aggregation line from component to thread Pr1.
    • * - On aggregation line from component to thread DynPr1.
      The multiplicity on the aggregation lines specifies how the component should be mapped to threads.
    • A `*' means that each instance of the component should be mapped to an individual thread.
    • A name means that the entire component should be mapped to a thread.
      In our example this means that there should be one thread for all instances of Pr1 and one thread for each instance of DynPr1.
  4. Double-click the component symbol. In the Symbol Details window specify that the integration model should be Threaded, see : Signalling in Threaded Integration.

Figure 573 Symbol Details for the Component Simple

  5. Double-click the thread symbol for Pr1. Specify the following Thread Parameters for the Thread P1:
    Thread Stack Size = 2048
    Thread Priority = 8
    Queue Size = 128
    Max Signal Size = 1024
  6. Double-click the object symbol and specify that the stereotype should be Process and that the qualifier (for Pr1) should be:
    • Simple/Bl1/Pr1.
      Make the appropriate specifications for the object Symbol for DynPr1(Qualifier = Simple/Bl1/DynPr1).
  7. Save the deployment diagram.
  8. Select the deployment diagram in the Organizer and open the Targeting Expert from the Generate menu.
  9. Choose the integration: Threaded Integrations->Win32 threaded.
  10. You will be prompted if you want to generate the sdl_cfg.h file. Select No!
  11. Disable the Generation of Environment Function by deselecting Environment Functions in the Environment section of the window.
  12. Click on the Compiler/Linker/Make line in the Partitioning Diagram Model. You should now see the following in the Targeting Expert window, see:: The Compile/Linker/Make Window in Targeting Expert.

Figure 574 : The Compile/Linker/Make Window in Targeting Expert.

  13. Define the following flag: THREADED_SIMPLE_EXAMPLE in the Compiler description/Options window. This flag will start the External threads in the simple example.
  14. Define the following Compilation flags:
    • THREADED_XTRACE,
    • THREADED_MSCTRACE
      by selecting the flags: SDL trace and MSC trace in the Target library/Kernel window
  15. Add the MyExtTask.c file as a new source file.
    Click on the Source Files entry in the window and add the MyExtTask.c file in the source file list.
    Save the settings. You are now prompted again to generate configuration file, this time select Yes.
  16. You should now be back in the Analyze/Generate code window and be ready to generate the application.
    Do a full Make and if you have followed the instructions the Targeting Expert will now analyze, generate code, generate makefile, compile and link the application.
  17. Run the application simple.sct. Please note that you have to traverse down in the generated directory structure to find the application.
    You will find the application in a subdirectory similar to this path:
    • <your test directory>/Simple._DPE981536368/Simple._DPE1/Simple._DPE2/Win32_threaded/....

The output you should see when you run the application should be as follows:

Figure 575 Textual SDL trace for Simple example.

Figure 576 MSC trace for Simple Example


65 The Cmicro SDL to C Compiler

The Cmicro SDL to C Compiler translates your SDL system into a C program that you can compile together with the Cmicro Library and the SDL Target Tester target library. The Cmicro Library and the SDL Target Tester target library is not available as a pre-linked library but is delivered as source to enable scaling of the kernel. The scaling is dependent upon the SDL system characteristics. This chapter is a reference manual for the Cmicro SDL to C Compiler.

  • In 66 The Cmicro Library, you will find information about how to customize your own libraries for specific purpose, such as application generation for target computers. The chapter also describes the structure of the generated C code and the internal data structures in the generated C code. The Cmicro Library is only of use when compiled with the code which is generated by the Cmicro SDL to C Compiler.
  • In 67 The SDL Target Tester, you will find a reference to the features, which enables testing in a host-target environment. The SDL Target Tester is applicable for the Cmicro SDL to C Compiler and the Cmicro Library only.


Application Area for the Cmicro SDL to C Compiler

The application area for the Cmicro SDL to C Compiler is:

  • Generation of applications, including embedded system applications with real time characteristics (Configuration: Cmicro Library and generated C code running on target).
  • Generation of target debug applications, including embedded system applications with real time characteristics (Configuration: Cmicro Library, generated C code and SDL Target Tester running on target).

In this part of the chapter, the general behavior of the Cmicro SDL to C Compiler, as seen from the users point of view, is discussed.

Highly Optimized Code for Target

The generated code in combination with the Cmicro Library is highly optimized, which is unavoidable for microcontrollers and real-time applications. Some optimizations have been possible only by introducing restrictions in the use of SDL. Other optimizations have been possible by generating more compact code. For the restrictions in the use of SDL please see "SDL Restrictions" . Details regarding the output of the Cmicro code generation can be found in "Output of Code Generation" .

Target Debug

With the generated code it is possible to debug the application on the target using the Cmicro Library and the SDL Target Tester library. The parts of the Cmicro code generation which are used for the SDL Target Tester are also highly optimized. Please see 67 The SDL Target Tester.


Overview of the Cmicro SDL to C Compiler

The SDL Analyzer, which can be invoked from the Organizer, contains an SDL parser, an SDL semantic checker, and - among other code generators - the Cmicro SDL to C Compiler.

Many options can be chosen from the user which affect the analysis of the SDL system. Furthermore, a lot of error checks are performed automatically before code generation starts. This makes it possible to improve written SDL specifications before any run-time testing must be done.

The options that the user may choose for analysis and the error checks that are performed by the analyzer are described in 54 The SDL Analyzer.

At some places the Cmicro SDL to C Compiler can be used in exactly the same way as the Cadvanced/Cbasic SDL to C Compiler can be used. At some other places the use of this C Code Generator, or what this C Code Generator produce, is different.

The Cmicro SDL to C Compiler generally can process the same input as the Cadvanced/Cbasic SDL to C Compiler can. The differences are explained within this chapter.

The differences in the output of the both code generators are described within the subsection "Output of Code Generation" .

The overall differences of the both code generators are described in the section "Differences between Cmicro and Cadvanced" .

The following subsections describe how the Cmicro SDL to C Compiler might be used.


Generated Files

The C files, which are generated by the Cmicro SDL to C Compiler, can only be used in connection with the Cmicro Library and the SDL Target Tester. It is not possible to validate and simulate the SDL system with the C code generated by Cmicro as this code is only suitable for target applications. To simulate and validate the SDL system within the SDL suite, the user has to choose the Cbasic SDL to C Compiler. In order to view the process of generating C applications see the Organizer's Make dialog in 2 The Organizer.

The SDL Analyzer, which contains the Cmicro SDL to C Compiler can also be started as a stand-alone tool. For more information about this possibility please see 54 The SDL Analyzer.

There are several steps that must be carried out before the generated C files can be compiled and linked together with the Cmicro Library. The user should follow the procedures that are documented in the section "Targeting using the Cmicro Package" .

In the following subsections the different files that are generated are explained.

Generated Configuration File

The first file that is generated from the Cmicro SDL to C Compiler is called sdl_cfg.h. It is used to scale the Cmicro Kernel depending on what characteristics the SDL system has. This is called automatic scaling and automatic dimensioning facility.

The file contains a header, process ID declarations, and then a #define or a /*NOT define ... */ for each of the flags that the Cmicro SDL to C Compiler can generate automatically.

Example 537 : The Header of an sdl_cfg.h

/* Program generated by SDL suite.Cmicro <version> <date> */

#ifndef XSCT_CMICRO
#define XSCT_CMICRO
#endif

/* "sdl_cfg.h" file generated for system <systemname> */

#define XMK_CFG_TIME <GenerationTime>

The XMK_CFG_TIME macro is used internally when compiling and executing with the SDL Target Tester takes place. With this macro, a rough consistency check for the generated files is done. The <GenerationTime> of the different files that are generated is compared in the Library and by the SDL Target Tester. If there is an inconsistency, compilation errors will occur.

The rest of the file sdl_cfg.h is about the automatic scaling and automatic dimensioning of the SDL system. It may look for example like:

Example 538 : The Tail of an sdl_cfg.h

#define MAX_SDL_PROCESS_TYPES <N>
#define XMK_USED_ONLY_X_1
#define MAX_SDL_TIMER_TYPES <X>
#define MAX_SDL_TIMER_INSTS <Z>
#define XMK_HIGHEST_SIGNAL_NR 4
/* NOT #define XMK_USED_TIMER */
/* NOT #define XMK_USED_DYNAMIC_CREATE */
/* NOT #define XMK_USED_DYNAMIC_STOP */
/* NOT #define XMK_USED_SAVE */
#define XMK_USED_SIGNAL_WITH_PARAMS
/* NOT #define XMK_USED_TIMER_WITH_PARAMS */
/* NOT #define XMK_USED_SENDER */
/* NOT #define XMK_USED_OFFSPRING */
/* NOT #define XMK_USED_PARENT */
/* NOT #define XMK_USED_SELF */
/* NOT #define XMK_USED_PWOS */
/* NOT #define XMK_USED_INITFUNC */

For a first rough understanding of the meaning of the different flags: The SDL system from above contains <N> process types (using SDL'88 terminology), all the processes are declared in the form (0,1) or (1,1). There are <X> timers declared (in this case, <X> must be 0, because XMK_USED_TIMER is undefined, and the system uses an amount of <Z> signals. The system does not use any create or stop (XMK_USED_DYNAMIC_CREATE and XMK_USED_DYNAMIC_STOP are undefined). In this way all the other flags have special meaning.

For explanations about the different flags the user should refer to "Automatic Scaling Included in Cmicro" .

Generated C File

Assumed, that the user selected "No separation" in the Organizer's Make Dialog, and no partitioning is used, then the Cmicro SDL to C Compiler will generate one C file per SDL system. This file contains all the characteristics of the SDL system including all the declarations that the SDL system itself needs. For an explanation of this file see "Output of Code Generation" .

Generated Environment Header File

There is one file generated from the Cmicro SDL to C Compiler that contains all the definitions and declarations that are necessary to implement the environment functions xInEnv and xOutEnv.

The file is generated only if the option Environment header file in the Targeting Experts is switched on.

The file is called <systemname>.ifc and it contains a header, the type definitions used on system level (newtypes, syntypes, synonyms), the signal IDs and the structure type definitions for the parameters of the signals.

Example 539 : The Header of an <systemname>.ifc file

#ifndef X_IFC_z_env01
#define X_IFC_z_env01
#define XMK_IFC_TIME <GenerationTime>

The XMK_IFC_TIME macro is used internally when compiling and executing with the SDL Target Tester takes place. With this macro, a rough consistency check for the generated files is done. The <GenerationTime> of the different files that are generated is compared in the Library and by the SDL Target Tester. If there is an inconsistency, compilation errors will occur.

Caution!

As there are defines generated that contain no prefixes, there might be compiler warnings like Illegal redefinition of macro. Such redefinitions should never be ignored because fatal errors during run-time may occur. The user should introduce a prefix for signals or sorts with different meaning on SDL level, in order to map these names to unambiguous identifiers in C.

More explanation about the environment header file is given in 66 The Cmicro Library.

Sorts

Followed by the header the section about sorts follows. The sorts are generated according to the documentation in 56 The Cadvanced/Cbasic SDL to C Compiler.

Signal IDs and Parameter Structures

Next, the definitions for signals follows, which consists of:

  • A C comment with a comment explaining if the signal is IN or OUT as seen from SDL
  • An optional declaration of a C structure type definition (if the signal carries parameters)
  • The definition of the signal ID

For easy interpretation: For an SDL signal without parameters, going from the environment to SDL, like:

signal SIn;

the following is generated into the .ifc file:

/* SIn IN */
#define SIn <X>

For an SDL signal with parameters, going from SDL to the environment, like

signal SOut (integer, mystruct, boolean);

the following is generated into the .ifc file:

/* SOut OUT */
typedef struct {
SIGNAL_VARS
SDL_Integer Param1;
mystruct Param2;
/* mystruct declared in the section */
/* declaring sorts */
SDL_Boolean Param3;
} yPDef_<UniquePrefix>_SOut;

typedef yPDef_<UniquePrefix>_SOut *yPDP_<UniquePrefix>_SOut;
#define yPDP_SOut yPDP_<UniquePrefix>_SOut
#define yPDef_SOut yPDef_<UniquePrefix>_SOut
#define SOut <X>

At least the signal ID (here: SOut) and the name of the structure (here: yPDef_SOut) must be used in the xOutEnv C function in this case.

The code generation of structure types and signal IDs is (except the C comment about IN or OUT) independent from the direction the signal goes.

Process IDs

At last the process ID declarations are generated as #define values in C, like:

#define XPTID_<auto-prefix>_MyProcess 0

where the first process in the system is the value of 0 assigned, the second process gets the value 1, and so on. Due to the implementation of SDL'92 object orientation in the Cmicro SDL to C Compiler, there is also an automatic prefix generated. Using this prefix in the user's environment functions, it is possible to distinguish between several processes with the same name. Please refer to "Generation of Identifiers" for more information.

Generated Make File

The Cmicro SDL to C Compiler generates a file that contains production rules for the C program. This file can be used together with "make" facility only. The file is called <systemname>.m.

Additionally there is an ASCII file called <systemname>_gen.m which gives a list of all the generated files. This files is used by the Targeting Expert to generate a makefile. Please see "Generated Makefile" .

Generated Symbol File

The generated symbol file is used to store symbolic information about the SDL system. The file has meaning for the host part of the SDL Target Tester only and is called <systemname>.sym. It is used for SDL Target Tester purposes only and is described within "The Host Symbol Table" .

Generated Kernel Group File

The generated kernel group file contains information about process names. This file is especially used in integrations, when OO is used and processes are instantiated. Using the information from this file, it is possible to distinguish between several process instantiations with the same name.


Implementation

In this section the implementation details are discussed. These details are meaningful for understanding how a generated Cmicro application does work.

Time

For host simulation, with the predefined integration settings, a time unit represents one second. In target applications, time is to be implemented by the user (see subsection "Defining the SDL System Time Functions in mk_stim.c" ).

Real Time

If real time is used, then there will be a connection between the clock in the executing program and the wall clock. For applications the user must provide the connection with the wall clock, normally the hardware timer.

Note:

The C standard function time used as the real time clock returns the time in seconds. The implementation of the clock can be changed by re-implementing the function xmk_NOW in mk_stim.c.

Scheduling

The Cmicro Kernel does not use a process ready queue. It processes the signals in the order of their appearance. To do this, there is a signal queue which stores the signals sent to any process (either internally or externally). There are different ways to influence the scheduling when using the Cmicro SDL to C Compiler:

  • assigning priorities to processes
  • assigning priorities to signals
  • any combination of process and signal priorities

Assigning Priorities to Processes - Preemptive Scheduling

It is possible to assign priorities to process types (using SDL'88 terminology). The processes' priorities are assigned when designing the SDL system. They are assigned using the #PRIO directive.

There are some things to be kept in mind when using process priorities:

  • Priorities have to begin with zero.
  • Priorities have to be consecutive.
  • All instances of a type have the same priority (SDL'88 terminology).
  • Priority decreases with increasing numbers (zero is the highest priority level).
  • The default priority is to be in the range of zero to the lowest priority number.

The Cmicro Kernel handles process priorities by collecting all signals sent to processes of the same priority in a separate queue. Thus, there is a queue for each priority level.

While the SDL system is running the kernel checks for signals in the queues with decreasing priority. This check takes place whenever an SDL output appears or a process performs an SDL nextstate operation. Because of the kernel checking for signals whenever an output takes place, it is possible to have preemptive scheduling.

Assume, there are two process types lowprio and highprio. Let process type lowprio have the priority one and process type highprio have the priority zero.

If an instance of process type lowprio performs an output to process type highprio, there appears a signal in a queue of a higher priority level (zero is the highest priority level available, process lowprio has priority one) which leads to the kernel immediately working on the signal sent to the process highprio. The transition of process lowprio will not end until process highprio has finished its transition invoked by the signal.

This way of scheduling is implemented using recursion.

Note:

Process priorities are available only when using a compiler which can handle recursion.

There is basically no restriction on the number of priority levels, but the target and compiler used will of course limit the depth of recursion.

As a general recommendation process priorities should not be assigned one per process type, but the process types should be grouped according to their purposes and these groups should then be assigned a priority level.

Assigning Priorities to Signals

The signals in the queue(s) are normally ordered according to their appearance (FIFO-strategy). By assigning priorities to signals this ordering is user definable. The directive #PRIO is used to assign a priority to signals.

Priority increases with decreasing numbers, but there is no restriction to use consecutive numbering.

Whenever a signal is sent, it is inserted into the signal queue(s) according to its priority.

Assume, there is a process performing two signal outputs, first_sig and second_sig. Using the standard FIFO-strategy signal first_sig would be worked on before signal second_sig. But with signal priorities and signal first_sig assigned priority fifty and signal second_sig assigned priority twenty, signal second_sig would be in front of signal first_sig in the queue and thus would be worked on before signal first_sig.

For more details please refer to "Assigning Priorities - Directive #PRIO" .

Combinations of Signal/Process Priority

Every combination of signal and process priorities may be used. In this way it is possible to adapt the scheduling to the users' needs.

Note:

Without process priorities a transition once started will have to be finished before the next transition can be dealt with. This is valid regardless of the time it will need to finish a transition.

Synonyms

External Synonyms

External synonyms can be used to parameterize an SDL system and thereby also a generated program. The values that should be used for the external synonyms must be included as macro definitions into the generated code, for instance by including another header file.

Using a Macro Definition

To use a macro definition in C to specify the value of an external synonym, the user should perform the following steps:

  1. Write the actual macro definitions on a file.

Example 540 : Macro Definition

#define synonym1 value1
#define synonym2 value2

The synonym names are the SDL names (without any prefixes).
  2. Introduce the following #CODE directive at the system level among the SDL definitions of synonyms, sorts, and signals, for example, but before any use of the synonyms.

Example 541 : #CODE Directive

/*#CODE
#TYPE
#include "filename"
*/

If this structure is used, the value of an external synonym can be changed merely by changing the corresponding macro definition and re-compiling the system.

Procedure Calls and Operator Calls

In SDL-92, value returning procedures and operator calls are introduced. This means, that an SDL procedure can be called within an expression. As the Cmicro SDL to C Compiler cannot handle procedures with states, it is not necessary to map such calls to a different scheme.

Example 542 : Procedure Call

TASK i := (call p(1)) + (call Q(i,k));

is translated to something like:
i = p(1) + Q(i,k);

Note:

The value returning procedure calls are transformed to C functions which return values.

Operators which are defined using operator diagrams, are as in the models in the SDL recommendation, treated exactly as value returning procedures.

Generation of PAD function

The code generation for the PAD function is different compared with Cadvanced, in the way that code that is common in process types is copied into the PAD function for instantiated processes. This is implemented in contrast to Cadvanced, where for each process type definition there is a C function generated once, that is called by the instantiated PAD function, for common code. This makes a difference when system partitioning and/or file separation is used.

Any

`Any' should not be used in applications using the Cmicro SDL to C Compiler, as it leads to an error message.

Calculation of Receiver in Outputs

The Cmicro SDL to C Compiler is a code generator using the semantics of SDL-92 with some restrictions. The behavior for output is according to the rules described in the following:

  • For an output without TO and without VIA in SDL, the Cmicro SDL to C Compiler calculates the receiver of the signal during code generation. If there is more than one possible receiving process type, then an error message will be printed out.
  • For an output without TO and without VIA in SDL, it is also possible to have one process type, but more than one receiving instance of the signal. The response is that any of the living possible receivers may be selected during execution time. If no receiver is found, the C function ErrorHandler will be called.
  • For an output with the VIA clause, the behavior of the Cmicro SDL to C Compiler is in principle the same as for an output without TO It computes the possible receivers in an output with the VIA clause and if there are several possible receivers, an error message is produced. The only difference between output with VIA and output without TO is that VIA can restrict the amount of possible processes.
  • If output with TO is used in the above cases, no ambiguity can occur. The addressing of the process is then performed by a run-time variable.
  • The possibility of specifying the name of a process when using OUTPUT TO is implemented. This is an SDL-92 feature. The Cmicro SDL to C Compiler behaves in the same way as when using implicit addressing (output without to).
  • The broadcast feature of SDL-92 (VIA ALL) is not implemented, because it is not a real broadcast and not very useful for Cmicro Applications.


Abstract Data Types

In this section the specialities and exceptions about abstract data types for Cmicro are discussed only. A complete documentation about the abstract data types is given in 56 The Cadvanced/Cbasic SDL to C Compiler.

General C Definitions

All the macros and external definitions for functions can be found in the file sctpred.h except for the PId sort which is handled in the file ml_typ.h.

The C functions for the handling of predefined sorts are defined in the file sctpred.c.

On UNIX these files can be found in $sdtdir/cmicro/kernel.

In Windows these files can be found in the Telelogic Tau installation under %SDTDIR%\cmicro\kernel.

Exceptions for SDL Predefined Types

A general exception existing for all the predefined types is that the user must configure which predefined types are to be compiled into the target C program. This is necessary to hold the target C program as small as possible. The configuration is to be performed with the help of the Targeting Expert, please view "Configure and Scale the Target Library" .

Caution!

Problems will occur during compilation when the configuration is not according to what the SDL system needs. The user should refer to the explanations about manual scaling in 66 The Cmicro Library.

External Synonyms

External synonyms are to be defined by the user in the following way.

For a synonym like

synonym xternal integer = EXTERNAL;

Cmicro expects to see xternal as a #define value that is to be defined by the user. This can be done for example in the following way:

synonym xternal integer = EXTERNAL;
/*#CODE
#TYPE
#ifdef XSCT_CMICRO
#define xternal 7
#endif
*/

This also means, that if xternal is not defined from the user, it will lead to compilation errors.

Charstring

Charstrings can be used either in the usual way as they are when using Cadvanced, or they can be used in a restricted way. The decision is up to the user and is a question of configuration. The user should be aware that some of the predefined sorts from ASN.1 are based on the implementation of SDL charstrings. This is discussed in subsection "Support of SDL Constructs" .

Time/Duration

The predefined data types Time and Duration are implemented in a more or less restrictive way. It is possible to specify a real value for Time and Duration on SDL level, like 23.45. The Cmicro Library uses only the integer part in front of the dot, 23 in this example. The mapping of SDL time units to time units in a target application is - in any case - up to the user.

UnionC

The #UNIONC directive is not recommended when using the Cmicro SDL to C Compiler because there is no support for checking the validity of the component selection. Both the #UNION directive and the CHOICE concept are a better alternative.

Predefined Generators Array, String, Powerset, Bag, Ref

These generators are implemented in Cmicro, but the user should be aware that the use of any of them requires that dynamic memory allocation is used in the target system. Generally, Cmicro tries to prevent the use of dynamic memory allocation whenever possible. The reasons for this are explained in 66 The Cmicro Library.

ctypes.sdl

This package can be used together with Cmicro with the following restriction.

There are two operators that are excluded when Cmicro C code is compiled. The operators are "CStar2CString" and "CharStar".

The reason for this is that with Cmicro it is possible to define an array of char in C instead of the predefined solution of Cadvanced (to use dynamic memory allocation). This is discussed in subsection "Support of SDL Constructs" .

byte.pr

This ADT can be used together with Cmicro in the same way as described for Cadvanced.

file.pr

This ADT is not useful for typical Cmicro applications (embedded systems usually do not provide a hard disk in Cmicro applications) and for that reason never has been tested. The ADT may however work with Cmicro.

idnode.pr

This ADT cannot be used together with Cmicro because it refers to Cadvanced code.

list1/list2.pr

This ADT cannot be used together with Cmicro because it refers to Cadvanced code.

long_int.pr

This ADT can be used together with Cmicro.

pidlist.pr

This ADT cannot be used together with Cmicro, generally.

Instead of pidlist.pr, the user may include the cm_pidlist.pr file. The use of this ADT is however restricted, because Cmicro implements a different scheduling algorithm. This means, that systems that are successfully simulated first, may contain problems when a Cmicro target application is build and executed.

It is therefore recommended not to use neither pidlist.pr nor cm_pidlist.pr, in order to achieve the best possible SDL conformity.

random.pr

This ADT cannot be used together with Cmicro because it refers to Cadvanced code.

unsigned.pr

This ADT can be used together with Cmicro.

unsigned_long.pr

This ADT can be used together with Cmicro.

Default Values

Default values are in principle generated in the same way as with the Cadvanced SDL to C Compiler. It is however possible to configure the default value setting, which is explained in 66 The Cmicro Library. The right configuration is essential to prevent illegal behavior.

Exceptions for Implementations of Operators

Read and Write Functions

The Cmicro SDL to C Compiler does not provide read and write functions. The reason is, that the Cmicro SDL to C Compiler mainly is used to build target applications, and not simulations. This is also a consequence of optimizing the target program. If the user uses the Q (question) operator, the Cmicro SDL to C Compiler ignores this.

Error Situations in Operators

In the C function used to implement operators (and literals), it is possible to define error situations and handle them as ordinary SDL run-time errors. The C library function ErrorHandler, with the following prototype

extern void ErrorHandler( xmk_OPT_INT errnum )

can be used for this purpose. xmk_OPT_INT is defined in ml_typ.h, normally as an ordinary C int. errnum may be one of the free values of error numbers. Please inspect ml_err.h in order to get a list of reserved values.

Example 543 : Error Handler in Operator

if ( strlen(C) <= 1 ) {
#ifdef XMK_USE_ERR_CHECK
ErrorHandler (ERR_N_InvalidStringLength);
#endif
return SDL_NUL;
} else
return C[1];

This is a simplified version of the test in the function for the operator First in the sort Charstring. Here the error situation is when we try to access the first character in a charstring of length 0. In this case the C function ErrorHandler is called and a default value is returned (NULL). By including the call to ErrorHandler between #ifdef XMK_USE_ERR_CHECK - #endif the function is only called to report the error, if error checks are turned on. The one parameter to the C function ErrorHandler should identify the error. The number must be given by the user.

Another possibility to route error messages to the host system is to use the C function xmk_PrintString of the SDL Target Tester, defined as:

extern void xmk_PrintString( char * )

Example 544 : Error Handler in Operator

if ( strlen(C) <= 1 ) {
#ifdef XMK_ADD_MICRO_TESTER
xmk_PrintString ("ERR:Invalid Stringlength");
#endif
return SDL_NUL;
} else
return C[1];

Access to Predefined Sorts based on Charstring

As already mentioned in earlier subsections, the user should be aware that some of the ASN.1 predefined sorts are based on the implementation of SDL charstrings. The user should also refer to subsection "Support of SDL Constructs" .

To avoid problems one should be aware that Charstring is implemented as char * in C and take the consequences thereof. There are a number of help functions (that implement the operators for the Charstring sort) supplied in the run-time library that might be helpful when handling Charstrings.

It is usually necessary to allocate dynamic memory when an operator returning a charstring value is implemented. There are two help functions that should be used in connection with allocation and de-allocation of dynamic memory. These are documented in "Dynamic Memory Allocation" .

Caution!

Do not use Charstring in SDL if you want to get a correct trace output with the SDL Target Tester, or if you want to use the Cmicro Recorder. In the last case, the use of charstring may lead to a fatal error when an SDL session is replayed.


Exceptions for Directives

Selecting File Structure for Generated Code - Directive #SEPARATE

The purpose of the separate generation feature is to specify the file structure of the generated program. Both the division of the system into a number of files and the actual file names can be specified. There are two ways this information can be given.

  • Normally this information is set up in the Organizer, using the command in 2 The Organizer. Here file names for the generated files can also be specified. In the Make dialog in the Organizer (see "Generated Files" ) it is possible to select full separate generation, user-defined separate generation, or no separate generation.
  • For an SDL/PR file that is generated by running the SDL Analyzer as a stand-alone tool, the same information can be entered by #-SEPARATE directives directly introduced in the SDL program. Full separate file generation, user-defined separate file generation, or no separate file generation can be set up in the command interface of a stand-alone Analyzer, see "Set-Modularity" .

The Cmicro SDL to C Compiler can generate a separate file for:

  • System (always separate)
  • Block
  • Process
  • Procedure

Note:

Instantiations cannot be separated. If #SEPARATE directives are used, they should be placed directly after the first semicolon in the system, block, process, or procedure heading; see the following example.

Example 545 : #SEPARATE Directive

system S; /*#SEPARATE 'filename' */
block B; /*#SEPARATE */
process type P1 inherits PType; /*#SEPARATE */
process P2 (1, ); /*#SEPARATE */
procedure Q; /*#SEPARATE */

In the example above the two versions of separate directive, with or without file name, are shown. As can be seen a file name should be enclosed between quotes. The Cmicro SDL to C Compiler will append appropriate extensions to this name when it generates code.

If no file name is given in the directive, the name of the system, block, process, or procedure will be used to obtain a file name. In such a case the file name becomes the name of the unit with the appropriate extension (.c .h) depending on contents. The file name is stripped of characters that are not letters, digits or underscores.

The possibility to set up full, user-defined, or no separation in the Organizer's Make dialog and in the user-interface of a stand-alone Analyzer (see "Generated Files" ), can be used in a simple manner to select certain default separation schemes. This setting will be interpreted in the following way:

  • No separation.
    The whole system will be generated into one file.
  • User defined separation.
    The system, each package, and each unit that the user has specified as separate will become a separate file.
  • Full separation.
    The system, each package, each block, block type, and process, and process type will become a separate file. Note that even in this case a procedure is separate only if the user has specified it as separate.

Independently if No, User defined, or Full separation has been selected, the Cmicro SDL to C Compiler will use the file name specified in the Edit Separation dialog or the #SEPARATE directive, for a file that is to be generated.

An Example of the Usage of the Separate Feature

In the following example a system structure and the #SEPARATE directives are given. The same information can easily be set up in the Organizer as well. This example is then used to show the generated file structure depending on selected generation options.

Example 546 : #SEPARATE Directive

system S; /*#SEPARATE 'Sfile' */
block B1; /*#SEPARATE */
process P11; /*#SEPARATE 'P11file' */
process P12;
block B2;
process P21;
process P22; /*#SEPARATE */

Applying Full Separate Generation

If Full separate generation is selected then the following files will be generated:

 Sfile.c

 Sfile.h

 B1.c

 B1.h

 P11file.c

 P12.c

 B2.c

 B2.h

 P21.c

 P22.c

The .c files contain the C code for the corresponding SDL unit and the .h files contain the module interfaces.

Applying Separate Generation

If User defined separate generation is selected then the following files will be generated:

 Sfile.c

 Sfile.h
Contains code for units S, B2, P21

 B1.c

 B1.h
Contains code for units B1, P12

 P11file.c
Contains code for unit P11

 P22.c
Contains code for unit P22

The user defined separate generation option thus makes it possible for a user to completely decide the file structure for the generated code. The comments on files and extensions given above are, of course, also valid in this case.

Applying No Separate Generation

If the separation option No is selected, only the following file will be generated:

Sfile.c

Contains code for all units

The comments on files and extensions earlier are valid even here.

Guidelines

Generally a system should be divided into manageable pieces of code That is, for a large system, full separate generation should be used, while for a small system, no separate generation ought to be used. The possibility to regenerate and re-compile only parts of a system usually compensate for the overhead in generating and compiling several files for a large system.

Note:

A file name has to be specified, using the Organizer Edit Separation command or the #SEPARATE directive, if two units in the system have the same name in SDL and should both be generated on separate files. Otherwise the same file name will be used for both units.

Assigning Priorities - Directive #PRIO

#PRIO for Processes

Priorities can be assigned to processes using the directive #PRIO. The process priorities will affect the scheduling of processes, see "Scheduling" . A priority is a positive integer, where low value means high priority. #PRIO directives should be placed directly after the process heading in the definition of the current process.

Example 547 : #PRIO Directive .

Process P1; /*#PRIO 0 */
Process P2(1,1); /*#PRIO 1 */

Process P3 : P3Type; /*#PRIO 0 */
Process P4(1,1) : P4Type; /*#PRIO 1 */

Processes that do not contain any priority directive will have a user defined default priority with the name xDefaultPrioProcess.

There are some things to be kept in mind when using process priorities:

  • Priorities have to begin with zero.
  • Priorities have to be consecutive (0,1,2,3,4,5).
  • All instances of a type have the same priority.
  • Priority decreases with increasing numbers (zero is the highest priority level).
  • The default priority is to be in the range of zero to the highest priority number, that is 0 or 1 in the example above.

#PRIO for Signals

Priorities can be assigned to signals using the directive #PRIO. The signal priorities will also effect the scheduling of processes, see "Scheduling" .

Signal priorities can be specified, either:

  • in the declaration of the signal
  • in SDL output

It is impossible to specify #PRIO in a SDL input. Cmicro will ignore any occurrence of #PRIO in SDL input.

Signal priorities do affect the SDL output and the SDL create actions only.

The following rules are to be considered here:

  • Signal priorities have to be in the range from 0 to 255.
  • Signal priorities do not have to be consecutive, as process priorities have to be.
  • If not specified otherwise (in SDL output) all instances of a signal have the same priority.
  • Signal priority decreases with increasing numbers (zero is the highest priority level).
  • The signal default priority is to be specified by the user (-xDefaultPrioSignal), and must in the range of 0 to 255. As a recommendation, this value should be set to 100, so that both higher, as well as lower priorities can be declared with #PRIO.
  • Signal priorities come after process priorities.
  • If no #PRIO is specified for a signal, neither in its declaration, nor in any output, Cmicro uses xDefaultPrioSignal for each occurrence of that signal in an output.
  • If #PRIO is specified only in the declaration of a signal, Cmicro uses this specified priority in each occurrence of that signal in an output.
  • If #PRIO is specified in a specific output of a signal, but not in its declaration, then the specified #PRIO value is taken from the output. If the signal is output without #PRIO, in that case -xDefaultPrioSignal will be used.
  • For dynamic process creation, an internal create signal is used. This signal carries the priority defined by XMK_CREATE_PRIO. As a general recommendation, this priority should be higher than any other signal priority.

The following example will give more explanations (note, that the values PA, PB are of sort pid):

Example 548 : #PRIO Directive .

Signal
S1, /*#PRIO 11 */
S2, /*#PRIO 22 */
S3,
S4; /*#PRIO 44 */

....
output S1 to PA
output S1 to PB; /*#PRIO 55*/
....
output S3 to PC;
output S3 to PD; /*#PRIO 66*/

Assuming the following C definition:

#define xDefaultPrioSignal 100

the following priorities will then be generated:

output S1 to PA --->use of prio 11
output S1 to PB--->use of prio 55
....
output S3 to PC--->use of prio 100
output S3 to PD--->use of prio 66

Modifying Outputs - Directive #EXTSIG, #ALT, #TRANSFER

There is no difference for the #EXTSIG, #ALT and #TRANSFER directives for Cmicro compared with Cadvanced, except that the use of it will sometime lead to a better performance. This is because if #EXTSIG for example is used in the case of an output to the environment, the user can prevent the Cmicro Kernel to be called (and the xOutEnv function to be executed).


Output of Code Generation

This section gives an overview of the code generated by the Cmicro SDL to C Compiler. This is useful, to make it possible to interpret the generated code. To know how the code is generated makes it quite easy to understand the program which is necessary and useful when testing and debugging erroneous executable programs.

Figure 577 : Structure of the generated C code

Not all the intricate details of the generated code are described here. The depth of description is sufficient to give the reader a reasonable understanding of the code generation algorithms. Explanations will illustrate what the code looks like, but not why.

The generated code contains several places where prefixes are generated, which consists of a prefix and unique numbering. The following prefix is generated for all objects: "z<nnn>_", where nnn is an incremental number.

Allowance for conditional compilation occurs in several places throughout the generated code. The generated C code is conditionally compiled, for example, for dynamic process creation (create symbol). A differentiation is made between conditional compilations generated by the Cmicro SDL to C Compiler (called automatic scaling, prefix XMK_USED_) and conditional compilations which are dependent on header files, which are to be modified by the user (called manual scaling, prefix XMK_USE_).

Note:

Generally speaking, the ordering of the following subsections corresponds to the ordering in which the code is generated.

Each compilation unit is compiled either in one a.c file or into two files, a.c and a.h.

Only the differences are shown, when comparing the output of SDL to C Compiler with the Cmicro SDL to C Compiler. The overall differences of the both code generators are described in the section "Differences between Cmicro and Cadvanced" .

Header of Generated C File

Code generation on the .c file for the current unit is started by generating the following header:

Example 549 : The Head of a Generated C File

/* Program generated by the SDL suite.Cmicro, version x.y */
#define XSCT_CMICRO

#define C_MICRO_x_y
#define XMK_C_TIME <GenerationTime>
#include "ml_typ.h"

The XSCT_CMICRO macro can be used by the user to distinguish between the different Code generators, for example within ADT bodies.

The C_MICRO_x_y macro can be used by the user to distinguish between different versions of the Cmicro SDL to C Compiler. This is usually not but might become necessary if the output of the Cmicro SDL to C Compiler is different.

The XMK_C_TIME macro is used internally when compiling and linking and executing with the SDL Target Tester takes place. With this macro, a rough consistency check for the generated files is done. The <GenerationTime> of the different files that are generated is compared in the Library and by the SDL Target Tester. If there is an inconsistency, compilation errors will occur.

The #include "ml_typ.h" is used to include all necessary declarations that the generated C code may use, including automatic scaling from sdl_cfg.h and predefined sorts.

SECTION Types and Forward References

As a difference to SDL to C compiler, this section contains the definitions for the process IDs and the forward declarations used in the generated C code.

Process IDs are generated as #define values in C, like:

#define XPTID_<UniquePrefix>_MyProcess 0

where the first process in the system is the value of 0 assigned, the second process gets the value 1, and so on. Please refer to "Generation of Identifiers" for more information.

The following forward references are generated:

extern XCONST XPDTBL yPDTBL_<UniquePrefix>_MyProcess;

Following this, the usual declarations are generated as described in 56 The Cadvanced/Cbasic SDL to C Compiler.

No synonym variables are generated when using Cmicro.

Symbol Tables

Symbol tables are only generated for the SDL Target Tester, and not into the generated C code. The symbol tables generated for the SDL Target Tester are described within 67 The SDL Target Tester.

Tables for Processes

Tables are used to represent the behavior of SDL objects, like processes and timers. It is not absolutely necessary to understand how these tables are generated and how the Cmicro Kernel works with them. The following subsections are only for those readers interested in the nature of the table structure.

Root Process Table

The root process table contains, for each of the defined SDL process types, a reference (i.e. a pointer) to the Process Description Table. The Cmicro Kernel is the main user of the root process table. Via this table, it can access all SDL process types and all SDL process instance data. The location of the generated root process table is directly before the yPAD-functions in the generated C file. The type definitions used in this table are located in the ml_typ.h module.

Figure 578 : Root process table

Example 550 : Code of Root Process Table

C-Type definition (ml_typ.h) :

extern xPDTBL yPDTBL [];/* for the Cmicro Kernel */
#define X_END_ROOT_TABLE/* Table-End Marker of yPDTBL*/

C constants (sdl_cfg.h):

#define MAX_SDL_PROCESS_TYPES <N>

/* <Process-type-id´s> Process Types are numbered */
/* from 0 to N-1(see chapter "Generating PID") */
#define XPTID_Process1Name 0
#define XPTID_Process2Name 1
#define XPTID_ProcessnName N-1

C code generation for the whole system:

XPDTBL yPDTBL [MAX_SDL_PROCESS_TYPES+1] =
{
yPDTBL_ Process1Name,
yPDTBL_ Process2Name,
......
yPDTBL_ ProcessnName,
X_END_ROOT_TABLE
}

Symbol Trace Table

In order to reduce the use of dynamic memory allocation, there is a table generated in the code which is used by the SDL Target Tester to store and retrieve test options, like switches, which define the trace.

The table is conditionally compiled and only included if the SDL Target Tester is contained in the target- executable.

The symbol trace table looks like:

Example 551 : Code for Symbol Trace Table

/*************************************************************
** Symbol trace table
*************************************************************/
#ifdef XMK_ADD_TEST_OPTIONS
XSYMTRACETBL *xSYMTRACETBL[MAX_SDL_PROCESS_TYPES+1] =
{
(XSYMTRACETBL_ENTRY *) NULL, /* for first Processtype */
(XSYMTRACETBL_ENTRY *) NULL, /* for second Processtype */
........
........
(XSYMTRACETBL_ENTRY *) NULL, /* for last Processtype */
X_END_SYMTRACE_TABLE /* table end marker */
};
#endif

More information can be obtained by reading 67 The SDL Target Tester.

Optimized Decision Trace information

An option to reduce the trace information for SDL decisions by showing only the first ten characters of the decision expression during trace. Setting the environment variable CMICRO_SHORT_DECISION_TRACE to any value prior to the Cmicro code generation is started, will have the effect on the generated C code that all xTraceDecision<parameter> statements will contain a parameter that is the first ten characters of the decision expression instead of the complete expression. This will reduce the trace information for systems that contain a lot of decisions.

Instance-Data-Struct

The struct is generated in the header-section of the generated C file.

Example 552 : Code Generation of type definition for each SDL process

typedef struct {
PROCESS_VARS
TypeName1 FPAR_var1;
TypeName2 FPAR_var1;
TypeName3 DCL_var1;
TypeName4 DCL_var2;
TypeName4 yExp_DCL_var2;
TypeName5 FPAR_var1;
} yVDef_ProcessName;

Instances of a given type are represented as a C array. The code generation of variables for each SDL process looks like:

Example 553

#define X_MAX_INST_ProcessName upperlimitofprocessinstances1

static yVDef_ ProcessName
yINSTD_ProcessName[X_MAX_INST_ProcessName];

A reference to this array is generated in the Process Description Table which is discussed in the subsection "Process Description Table" .

Process State Table

This table is generated for each process in the header-section of the generated C file. It contains information about the state of each process instance. The table contains ordinary SDL state values as well as the values XSTARTUP and XDORMANT. XSTARTUP is generated for each instance which is to be statically created (in (x, N) declarations, where x is > 0), XDORMANT is the value which is used to tag a process instance as sleeping. In the case of creation this instance can be reused.

Example 554 : Code for Process State Table

C typedef for the process state table (located in ml_typ.h):

typedef u_char xSTATE; /* see defines below */
#define XSTARTUP 0xff /* valid only if xSTATE is */
/* u_char else 0xffff */
#define XDORMANT 0xfe /* valid only if xSTATE is */
/* u_char, else 0xfffe */

C code generation for each process:

static xSTATE yPSTATETBL_znn_ProcessName                                 [X_MAX_INST_znn_ProcessName] =
{
<creation-tag> /* Instance 0 */
<creation-tag> /* Instance 1 */

<creation-tag> /* Instance M-1 */
};

where <creation-tag> is either XSTARTUP or XDORMANT.

Example 555 :

Code for a process type with 4 instances, 2 of which are to be created at SDL system start:

static xSTATE yPSTATETBL_znn_ProcessName [4] =
{
XSTARTUP, /* Create at SDL-system-start */
XSTARTUP, /* Create at SDL-system-start */
XDORMANT, /* Create later */
XDORMANT /* Create later */
};

A reference to this table is created in the Process Description Table, which is discussed in the subsection "Process Description Table" .

Transition Table

This is generated in the header-section of the generated C file. It contains all transitions of a process, including asterisk states, asterisk inputs and asterisk save.

The C typedef for the transition table (located in ml_typ.h) is as follows:

Example 556 : Code for Transition Table

typedef struct {
xINPUT SignalID; /* Input, Asterisk-Input. */
/* Input is Timer */

/* and/or ordinary Signal */
xSYMBOLNR SymbolNr; /* Symbolnumber to be used */
/* in yPAD-function */
} xTR_TABLE_ENTRY;

C code generation:

static XCONST xTR_TABLE_ENTRY yTRTBL_znn_ProcessName                                 [XMAX_TRANS_znn_ProcessName]= {
/* state_0-table */
input_1, SymbolNr,
input_2, SymbolNr,
XASTERISK,XSAVEID /* asterisk save */

input_N, SymbolNr,

/* state_1-table */
...............
...............
/* state_j-table */
input_1, SymbolNr,
input_2, SymbolNr,

input_N, trans_jN,
XASTERISK,XSAVEID /* asterisk save */
};

The SymbolNr shown above is used to select the right transition in the switch generated in the yPAD function.

Where the C define

XASTERISK is an ID defining all possible SDL Inputs (asterisk Inputs),

XSAVEID is a simple ID defined in ml_typ.h which can be compared by the SDL Kernel to detect signal-save.

And where:

#define XASTERISK -1
#define XSAVEID xSave

A reference to this table is created in the Process Description Table.

State Index Table

This is generated in the header section of the generated C file.

Example 557 : Code for State Index Table

C typedef (ml_typ.h):

typedef u_char xSTATE_INDEX;

C code generation (header of generated C file):

static xCONST xSITBL xSTATE_INDEX_znn_ProcessName                          [<count_transitions_of_ProcessName] =
{
0, /* i.e.a process with 3 states, but no asterisk states */
/* state_0 has 2 transitions */
2, /* state_1 has 5 transitions */
7, /* state_2 has 3 transitions */
10 /* table-end-index XI_TABLE_END */
};

The first value in the above table indicates the beginning of the first state in the Transition Table. If asterisk state definitions are not found in the process, this value is 0.

A reference to this table is created in the Process Description Table.

PID Table

These tables are used to store the values parent and offspring for each process. The reason an extra table is used to store this information is to simplify initialization. The Cmicro Kernel updates the values in the table according to the SDL rules.

Example 558 : Code for PID Table

C-type definition (ml_typ.h):

#ifdef XMK_USE_PID_ADDRESSING
typedef struct
{
#ifdef XMK_USE_SDL_PARENT
xPID Parent;
#endif

#ifdef XMK_USE_SDL_OFFSPRING
xPID Offspring;
#endif

} xPIDTable;
#endif

C code generation for each process:

/*-----------Process-PID-Values-------------*/
#ifdef XMK_USE_PID_ADDRESSING
static xPIDTable yPID_TBL_z00_P1[X_MAX_INST_z00_P1];
#endif

A reference to this table is created in the Process Description Table, which is discussed in the subsection "Process Description Table" .

Process Description Table

For each SDL process, an automatically initialized C structure is generated called process description table. This table is used in the Root Process Table to enable the Cmicro Kernel to access process type information as well as process instance data.

Inspect the following diagram to see which information is contained in the process description table:

Figure 579 : Process description table

Allocated to each SDL process type is one table yPDTBL_ProcessName.

The type definitions of this table are located in the ml_typ.h module.

Example 559 : Code for Process Description Table

C typedef for the process description table (ml_typ.h):

typedef struct {
#ifdef XMK_USE_PID_ADDRESSING
xPIDTable *pPIDTable; /* Table with */
/* Parent/OffspringValues */
#endif

xINSTD *pInstanceData ; /* Pointer to Instancedata*/
/* Vector */
xINSTDLEN DataLength ; /* Length of Instancedata */
/* for 1 Instance */
/* (used by SDL-BS) */
unsigned char MaxInstances ; /* Max.Number of Instances*/

#ifdef XMK_USE_TIMESLICE
/* Time-Slices can be individually specified by the user*/
/* The value stored in TimeSlice is measured in ticks */
/* The Cmicro Kernel has to be scaled to handle */
/* timeslicing */
xmk_T_TIMESLICE TimeSlice;
#endif

#ifdef XMK_USE_PREEMPTIVE
/* Process-Priority can be specified with #PRIO on the */
/* SDL-Level. It is available only, if the Cmicro */
/* Kernel is scaled to handle preemption. */
xmk_T_PRIOLEVEL PrioLevel;/*Priority of this processtype*/
#endif

xmk_T_TRANS_ADDRESS yPAD_Function ; /* Address of the */
/* yPADFunction */
xTRTBL TransitionTable ; /* Pointer to transition table */
xSITBL *StateIndexTable ; /* Pointer to state index table */
xSTATE *ProcessStateTable;/* Pointer to process state table */
} XPDTBL;

C code generation for each process:

#define X_MAX_INST_ProcessName 1

xPDTBL yPDTBL_ProcessName =
{
yPID_TBL_znn_<process:N>,
(xINSTD*) yINSTD_znn_ProcessName,
X_MAX_INST_znn_ProcessName,
(xmk_T_TRANS_ADDRESS) yPAD_znn_ProcessName,
yTRTBL_znn_ProcessName;
xSTATE_INDEX_znn_ProcessName,
yPSTATETBL_znn_ProcessName;
};

For each generated process description table, a new entry in the Root Process Table is generated.

Actions by Processes and Procedures

GR References

No code is generated to evaluate the graphical references during run-time of the SDL system. A large amount of memory is required to store and handle such information which normally proves too large for any real target system.

Alternatively, C comments are generated which make it possible to verify and debug the generated code as illustrated in the following example. The PR <position> indicates in which line number of the SDL/PR file the symbol can be found.

For processes :
/*************************************************************
** PROCESS <process-name>
** <<SYSTEM <system-name>/BLOCK <block-name>>
** #SDTREF(<reference>)
*************************************************************/

For signals :
/*************************************************************
** SIGNAL S1
** <<SYSTEM <system-name>/BLOCK <block-name>>
** #SDTREF(<reference>)
*************************************************************/

For yPAD-function
/*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
** Function for process <process-name>
** #SDTREF(<reference>)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/

For output :
/*-----
** OUTPUT <signal-name>
** #SDTREF(<reference>)
------*/

For nextstate :
/*-----
** NEXTSTATE <state-name>
** #SDTREF(<reference>)
------*/

Structure of Process and Procedure Functions

The basic structure of the generated C code for process and procedure definitions remains the same as for the SDL to C compiler although some modifications are evident.

The code generation for the PAD function is different compared with Cadvanced, in the way that code that is common in process types is copied into the PAD function for instantiated processes.

Procedures follow the same code generation as processes, with some small exceptions in macro naming conventions for variable declarations.

Each SDL process is represented in C by a C function called yPAD_ProcessName.

Example 560 : yPAD_ProcessName

/* Function for process ProcessName */
#ifndef XNOPROTO
extern YPAD_RESULT_TYPE yPAD_ProcessName ( YPAD_ANSI_PARAM )
#else
extern YPAD_RESULT_TYPE yPAD_ProcessName ( YPAD_KR_PARAM )
YPAD_KR_DEF
#endif
{
local variable section
State-input-selection
{
start-transition including nextstate
transition-1 including nextstate
transition-2 including nextstate
.......
transition-n including nextstate
}
pad-end-section
}

/* Function for procedure ProcedureName */
#ifndef XNOPROTO
extern YPRD_RESULT_TYPE yPAD_ProcedureName ( YPRD_ANSI_PARAM )
#else
extern YPRD_RESULT_TYPE yPAD_ProcedureName ( YPRD_KR_PARAM )
YPRD_KR_DEF
#endif
{
local variable section
section representing procedure body
}

Local Variables Section

The following defines are generated in the local variables section for processes.

Example 561

YPAD_YSVARP /* used for signal variable pointers */
YPAD_YVARP(yVDef_z00_P1)/* used for process variables */
YPAD_TEMP_VARS /* used for temporary variables */
YPRSNAME_VAR("P1") /* can be used for printf */
BEGIN_PAD /* used for some preparations */
/* to handle signals, or Integration*/
/* of any Realtime operating system */

After expansion by the C preprocessor:

yVDef_z00_ProcessName *yVarP
=(yVDef_z00_ProcessName *)pRunData;
unsigned char *yOutputSignal;
unsigned char *ySVarP;

(void) printf(("PROCESS:%s\n", "ProcessName"));

if((P_MESSAGE != ((void *) 0))
&& (P_MESSAGE->mess_length > 4))
{
ySVarP = (unsigned char *) P_MESSAGE->mess_ud.pt_ud;
}
else
{
ySVarP = (unsigned char *) P_MESSAGE->mess_ud.ud;
}

The following defines are generated in the local variables section for procedures:

YPRD_YVARP(yVDef_znnn_ProcedureName)
/* used for procedure variables */

YPRD_TEMP_VARS
/* used for temporary variables */

YPRDNAME_VAR("ProcedureName")
/* can be used for printf */

State - Input Selection

The selection of the appropriate SDL transition which is to be executed in the current state with the current signal in the input port goes in principle over the transition table, described in previous chapters. With this table, the Cmicro Kernel can evaluate a symbol number, which is local to a process, a unique numbering of the different possible transitions. This numbering algorithm begins at 0 (which corresponds to the start symbol) and continues until all symbols for this particular process type have been numbered.

The appropriate transition is selected by the following switch:

switch (XSYMBOLNUMBER) {
{
case 0:. start-transition
nextstate;

case 1: transition-1
nextstate;
}

After pre-compiling it:

switch (_xSymbolNumber_ )
{
.....
}

Start Transition

The start transition is included into the body of the generated yPAD function and has the same layout as transitions, with the following exceptions:

Assignment of initialization values to all local variables in the processes and procedures (if any) is executed. All DCL variables are filled with their default-values.

The start transition is selected by the special case-value zero in the switch-statement of the yPAD function.

Note:

FPARS in dynamic process creation are not contained in this version of the Cmicro Package.

Transitions

The transitions are translated in the order they are found and are only translated to the sequence of actions they consist of. The translation of actions are discussed in the subsection "Translation of Actions" following a few lines below.

PAD-End-Section

Each yPAD function is finished with:

END_PAD (yPAD_ProcessName);

The main reason for this is to make it possible to integrate other real-time operating systems.

Note:

Some compilers produce a warning if there is no return at the end of the yPAD function. Other compilers produce a warning "unreachable code", if there is a return at the end of the yPAD function. For this reason, a function returning macro END_PAD exists which can be expanded in accordance with the particular compiler used.

Translation of Actions

Translation of Output

SDL output statements are translated to the following basic structure:

  • allocate the data area for the parameters of the signal to be output
  • assign signal parameters
  • send the signal, parameters will be copied
  • release the data area for the parameters of the signal.

There are a lot of different output macros generated. The main reason for this is that for each output situation an optimized code is to be generated.

One differentiation is made for signals without parameters and signals with parameters. For a signal without parameters, suffix _NPAR is used for the macro generated and for a signal with parameters, suffix _PAR is used. The relevant output macro can then be expanded to a simpler output C function called xmk_SendSimple, if no signal priority is used.

Another differentiation is made for signals which are sent to the system's environment or which are sent internally in the SDL system. The suffix _ENV is appended to the macros which are shown here, if the signal should go to the system environment.

The different directives which can be used within the SDL suite to modify outputs are discussed in subsection "Modifying Outputs - Directive #EXTSIG, #ALT, #TRANSFER" .

The other different output situations which are handled, will be described in the next subsections.

Output without TO and without VIA

If the user specifies output SignalName without TO and VIA in SDL, the Cmicro SDL to C Compiler calculates the receiver of the signal. It is also possible to have more than one receiver for the signal. During execution time, any possible receiver that are alive may be selected otherwise if no receiver can be found, the C function ErrorHandler will be called. The following code is generated:

ALLOC_SIGNAL_ppp(SignalNamewithoutPrefix,
SignalNamewithPrefix,
SignalParameterTypeStructureName)

ordinary assignment of Signal Parameters, if there are some...

SDL_OUTP_ppp(Priority,
SignalNamewithoutPrefix,
SignalNamewithPrefix,
TO_PROCESS(ProcessNamewithoutPrefix,
ProcessNamewithPrefix),
SignalParameterTypeStructureName,
"SignalNamewithoutPrefix")

Note:

The ppp above stands for either PAR or NPAR for a Signal with or without parameters.

After expansion, the user will find a C function call to the xmk_SendSimple function or the xmk_Send function.

Priority is generated as xDefaultPrioSignal if no priority is specified for the signal with #PRIO.

TO_PROCESS is expanded to a function call if there is at minimum one (x, N) declaration in the system, where N is > 1. This function returns one of the possible receivers of the signal.

TO_PROCESS selects an active instance of the given process type It does not check for different types as receivers.

TO_PROCESS is expanded so that the pid is passed directly to one of the C functions xmk_Send*, if there are only (x,1) declarations in the system.

If the environment is the receiver of the signal, then the following code is generated:

ALLOC_SIGNAL_ppp(SignalNamewithoutPrefix,
SignalNamewithPrefix,
SignalParameterTypeStructureName)
ordinary assignment of Signal Parameters, if there are any...
SDL_OUTP_ppp_ENV(Priority,
SignalNamewithoutPrefix,
SignalNamewithPrefix,
ENV,
SignalParameterTypeStructureName,
"SignalNamewithoutPrefix")

Note:

The ppp above stands for either PAR or NPAR for a Signal with or without parameters.

After expansion, the user will find that ENV is passed to one of the C functions xmk_SendSimple or xmk_Send. ENV is a special value used inside the Cmicro Kernel to detect which signals are to be passed to the C function xOutEnv.

Output with TO clause

If the user specifies the output SignalName to pid in SDL, the Cmicro SDL to C Compiler generates the following code:

ALLOC_SIGNAL_ppp(SignalNamewithoutPrefix,
SignalNamewithPrefix,
SignalParameterTypeStructureName)
ordinary assignment of Signal Parameters, if there are some...
SDL_OUTP_ppp(Priority,
SignalNamewithoutPrefix,
SignalNamewithPrefix,
pid-variable,
SignalParameterTypeStructureName,
"SignalNamewithoutPrefix")

Note:

The ppp above either stands for PAR or NPAR for a Signal with or without parameters.

Expansion reveals a C function call to the xmk_SendSimple function or the xmk_Send function.

Priority is generated as xDefaultPrioSignal, if no priority is specified for the signal with #PRIO.

Possible generated values for pid variable are SDL_SENDER, SDL_PARENT, SDL_OFFSPRING and SDL_SELF or an SDL pid variable. These values are passed to the xmk_Send* functions. The name of a process as specified in SDL may also be given.

Output with VIA clause

The Cmicro SDL to C Compiler computes the possible receivers in an output with the VIA clause. If there are several possible receivers, an error message is produced.

If there is exactly one receiver, the same code is generated as for SDL output without to.

List of Generated Output Macros

  • ALLOC_SIGNAL_NPAR
    Allocating memory for signal without parameters
  • ALLOC_SIGNAL_PAR
    same for signals with parameters
  • TO_PROCESS
    Macro used to evaluate a receiver process instance, if necessary in the case of (x, N) declarations, where N > 1.
  • SDL_OUTP_NPAR
    Output internally in the SDL system for signal without parameters
  • SDL_OUTP_PAR
    same for signal with parameters
  • SDL_OUTP_NPAR_ENV
    Output to the system environment for signal without parameters
  • SDL_OUTP_PAR_ENV
    same for signal with parameters
  • SDL_ALTOUTP_NPAR
    #ALT for an output internally in the SDL system for signal without parameters
  • SDL_ALTOUTP_PAR
    same for signal with parameters
  • SDL_ALTOUTP_NPAR_ENV
    #ALT for an output to the system environment for signal without parameters
  • SDL_ALTOUTP_PAR_ENV
    same for signal with parameters
  • EXT_SignalName
    if #EXTSIG is used in output
  • TRANSFER_SIGNAL
    #TRANSFER is used in output

Translation of Create

The create action in SDL is translated to the following C code:

ALLOC_STARTUP_ppp(ProcessNamewithoutPrefix,
ProcessNamewithPrefix,
"ProcessNamewithoutPrefix, 0);

....assignment of start-up values (cannot be used in this version of the Cmicro Package)
SDL_CREATE(ProcessNamewithoutPrefix,
ProcessNamewithPrefix,
"ProcessNamewithoutPrefix, 0,
VariableofCreatedProcess,
PriorityofCreatedProcess,
yPAD-functionNameofCreatedProcess);

PriorityofCreatedProcess is generated as
xDefaultPrioProcess, if no priority is specified with #PRIO.

Translation of Set

The translation of set is restricted in a few areas in order to produce efficient code for a micro controller. For example, the SDL duration expressed by a real value in the context of timers is not implemented. The reason for this is that controllers do not have floating point operations or floating point operations are not used in order to increase the performance. For timers, such a high resolution is not necessary in most applications. The Cmicro Package uses a long value in its standard implementation to represent absolute time.

In order to make the examples below more readable, it is assumed that at least one timer with parameter is used in the system (macro XMK_USED_TIMER_WITH_PARAMS is defined in the generated file sdl_cfg.h). If the macro is not defined, then the handling for timers with parameters is not included.

Example 562

If the following is specified in SDL/PR:

Timer TimerName;
......
Set (now + durationvalue, TimerName) ;

or

Set (now + 22222, TimerName) ;

then the following code is generated:

SDL_SET_DUR \
(xPlus_SDL_Time(SDL_NOW,SDL_DURATION_LIT(22222.0,22222,0)),
SDL_DURATION_LIT(22222.0, 22222, 0),
TimerName,
TimerNamewithPrefix,
yTim_timer2,
"TimerNamewithoutPrefix")

Example 563

If the following is specified in SDL/PR:

Timer TimerName := TimerGroundValue ;---> see Note:!

then the following code is generated:

SDL_SET_TICKS
(xPlus_SDL_Time(SDL_NOW, TICKS(SDL_INTEGER_LIT(22222))),
TICKS(SDL_INTEGER_LIT(22222)),
TimerName,
TimerNamewithPrefix,
yTim_timer2,
"TimerNamewithoutPrefix")

The code after expansion then contains a function call to

xmk_TimerSet (TIMEEXPR,TimerNamewithPrefix,0).

TIMEEXPR is the result of the evaluation of now plus duration value.

#define SDL_SET_DUR(TIME_EXPR, DUR_EXPR, TIMER_NAME,         TIMER_IDNODE, TIMER_VAR, TIMER_NAME_STRING) \
xmk_TimerSet(TIME_EXPR, TIMER_IDNODE,0);

#define SDL_SET_TICKS(TIME_EXPR, DUR_EXPR, TIMER_NAME,         TIMER_IDNODE, TIMER_VAR, TIMER_NAME_STRING) \
xmk_TimerSet(TIME_EXPR,TIMER_IDNODE,0);

Example 564

If a timer with parameter is defined in SDL/PR:

Timer TimerName (integer);
...
set (now+1, TimerName (4711));

then the following code is generated:

SDL_SET_DUR_WITH_1IPARA(xPlus_SDL_Time(SDL_NOW,
SDL_DURATION_LIT(1.0, 1, 0)),
SDL_DURATION_LIT(1.0, 1, 0), TimerName,
TimerNamewithPrefix,
yPDef_z262_twp1,
yTim_TimerName,
"TimerName",
SDL_INTEGER_LIT(4711))

The code after expansion then contains a function call to

xmk_TimerSet (TIMEEXPR,TimerNamewithPrefix,4711).

Restrictions in the Use of Timers

  • Timers with parameters are restrictively supported in Cmicro. There might be only one parameter of sort "integer". This implementation has been chosen to achieve the highest efficiency.
  • Duration values as real values are not supported in this version of the Cmicro Package, i.e. this:
set (now + 5.5, TimerName)

is not allowed (the real part is discarded i.e. 5.5 (= 5).

Translation of Reset

If the user specifies in SDL/PR:

Reset (TimerName) ;

then the following code is generated:

SDL_RESET(TimerNamewithoutPrefix,
TimerNamewithPrefix,
yTim_TimerName)

The code after expansion contains a function call to xmk_TimerReset (TimerNamewithPrefix).

For a timer with one integer parameter, the following macro call is generated:

SDL_RESET_WITH_1IPARA(TimerNamewithoutPrefix,
TimerNamewithPrefix,
TimerParStruct,
yTim_TimerName,
TimerValue)

Note:

Timers with parameters are supported with the restriction that only one integer parameter is allowed.

Translation of Call

As SDL procedures are implemented with the restrictions explained within subsection "SDL Restrictions" , the following explanatory C code (to a procedure called ex_proc) is generated:

ex_proc (....C parameters ...);

All necessary parameters are routed via the C function call stack.

Translation of Call to a Procedure Returning Value / Operator Diagram

Operator diagrams and procedures returning values are - considering the call - handled in the same way please see the following explanatory example:

Example 565 : Procedure Call

TASK i := (call p(1)) + (call Q(i,k));

is translated to something like:
i = p(1) + Q(i,k);

Note:

The value of returning procedure calls are transformed to C functions returning values.

Translation of Nextstate

The nextstate operation is generated at the end of each transition contained in the yPAD function, as follows:

  • If the process performs simple nextstate operation:
SDL_NEXTSTATE(State1, z000_State1, "State1")

after preprocessing:
return (z000_State1);

  • If it performs a nextstate, which is defined as a dash state:
SDL_DASH_NEXTSTATE

which is defined as:
return (XDASHSTATE);

Translation of Stop

A stop action is translated to:

SDL_STOP

which is defined as

return (XDORMANT);

which is good code saving. The Cmicro Kernel then enters the new state value into the Process State Table.

Note:

This table contains ordinary SDL state values as well as the values XSTARTUP and XDORMANT. XSTARTUP is generated for each instance which is to be statically created (in (x, N) declarations, where x is > 0). XDORMANT is the value which is used to tag a process instance as sleeping. In the case of creation this instance can be reused.

Translation of Return

#ifdef XFREEVARS
FREE_PROCESS_VARS ()
#endif

SDL_RETURN

The macro definitions are:

#define SDL_RETURN \
if (_xxptr != (unsigned char*) NULL) \
{ \
XMK_MEM_FREE ((unsigned char *)_xxptr); \
} \
return ;

where xxptr is the pointer to the procedure instance data, as given via the C function call parameter list. Note, that the memory previously allocated directly before the procedure call is freed at the end of the procedure, not outside of the procedure.

Translation of SDL Expressions

In this section some of the translation rules for expressions are described. For more information see "Translation of Sorts" where for example the translation rules for literals and operators in the predefined abstract data types are given.

Now

SDL now is translated to the macro SDL_NOW which is expanded to the C function xmk_NOW. This function is exported by the module mk_stim.c.

Self, Parent, Offspring, Sender

The definitions for self, parent, offspring, sender are:

#ifdef XMK_USED_SELF
#define SDL_SELF xRunPID
#endif

#ifdef XMK_USED_PARENT
#define SDL_PARENT pRunPIDTable->Parent
#endif

#ifdef XMK_USED_OFFSPRING
#define SDL_OFFSPRING pRunPIDTable->Offspring
#endif

#ifdef XMK_USED_SENDER
#define SDL_SENDER P_MESSAGE->send
#endif

All the variables above are of type xPID. All variables are maintained by the Cmicro Kernel. xRunPID is a global variable which contains the pid of the SDL process which is currently running. P_MESSAGE is a pointer to the signal instance which is currently worked on.

Timer Active

An SDL timer active expression is translated to:

SDL_ACTIVE(TimerName, TimerName,
yTim_TimerName)

which is expanded to:

xmk_TimerActive(TimerName)

A conditional expression in SDL is translated to a conditional expression in C.

Init Function

An explicit initialization function is not generated by the Cmicro SDL to C Compiler in any case.

The structure of the SDL system is not generated into the C code. What is seen in the generated code, is the behavior of the SDL system. Variables of processes are initialized during the start transition of a process and no information about the structure of the SDL system is available during run-time in the generated code.

An initialization function is generated only in that case if synonyms are used within SDL, which require an initialized C variable.

All this results in a more compact executable.

For example, the following use of an SDL synonym results in a generated initialization function:

synonym a integer := /*#CODE anyUserFunction () */

The following C code is then generated within the C function yInit:

yAssF_SDL_Integer(a, anyUserFunction (), XASS);

yInit is called by the Cmicro Kernel if the define

XMK_USED_INITFUNC

is generated into the file sdl_cfg.h, which is done in the case above.

Initialization of Synonyms

The Cmicro SDL to C Compiler allows SDL synonyms to be implemented as C macros and C variables.

Initialization is implemented within the C function yInit which is conditionally compiled.

Function main

The C function main is not automatically generated by the Cmicro SDL to C Compiler. This is unnecessary because the main function usually is provided from the user or the predefined main function can be used. Instead of an automatically generated main function, the user must supply the function body of main, for target applications. Guidelines can be found in the subsection "Implementation of Main Function" .


Symbol Table File

The structure of an SDL system can be represented by a tree diagram. In SDL the root of the tree is represented by the SDL system followed by blocks, block substructures, processes and procedures1. Channels, channel substructures and signal routes are also represented in the tree. This tree is static, which means it cannot be modified during the run-time of an SDL system.

The SDL to C Compiler generates code so that this static structure is present in the generated code. This is good for debugging purposes.

The Cmicro SDL to C Compiler generates code so that this static structure is not present in the generated code, in order to spare memory. To enable debugging of the generated code, C comments are generated. Please consult the subsection "GR References" .

A symbol table is necessary for the SDL Target Tester running on the host or the development system.

For more information consult 67 The SDL Target Tester.

1

In SDL-92 several SDL systems can exist in parallel.


Generation of Identifiers

Processes and Process IDs (PID)

In order to implement the environment functions, it is important to notice that process IDs in Cmicro are generated into the sdl_cfg.h file, which must be included by the user's environment C module. These IDs are coded like it is described in "Generated Configuration File" . More explanations are given in the following.

Since process IDs might become ambiguous, especially in block type and process type instantiations in SDL'92, the names of process IDs that are to be used in the environment functions are to be given a prefix. Using this prefix within the environment functions (xInEnv), it can be guaranteed that different process IDs (equates to "instance sets" in SDL'92) with the same name can be distinguished, which is necessary in order to send signals to the right process instance within the SDL system. On the other hand, prefixes are not necessary when all the process instance sets within the system have a different name. The Cmicro SDL to C Compiler uses an algorithm to calculate the prefixes in the most convenient way.

For example, if a process named "myprocess" exists only once within the SDL system, there will be no automatic prefix generated, e.g. the full process ID is

#define XPTID_myprocess 0

If, as another example, the process "myprocess" exists twice, for example once within a block called "myfirstblock" and once more within a block called "mysecondblock", the Cmicro SDL to C Compiler then creates two definitions which guarantee that the processes can be distinguished:

#define XPTID_myfirstblock_myprocess 0
#define XPTID_mysecondblock_myprocess 1

In this way, by adding scope names (block names), prefixes are always generated in a way so that no naming conflicts occur. Of course, for process and block type instantiations, the name of the instance is being used to generate this unambiguous prefix.

SDL process types (process instance sets in SDL'92), as well as SDL process instances are numbered consecutively beginning with zero. The ordering of these numbers is the same as the ordering of the processes in the SDL/PR file.

The values 250 to 255 are reserved for internal purposes and must not be used for process type numbering. The Targeting Expert checks this rule automatically. For small systems this does not create any problems.

The Cmicro Kernel assumes the above definitions.

In the generated C code, the SDL values self, sender, parent and offspring, and variables of this type are represented by the typedef xPID. The intention is to have unique numbering of processes and their instances in the whole SDL system. This becomes necessary because of the Cmicro Code no longer containing the structure of the SDL system (system, block...). The typedef xPID is defined as

  • unsigned char or unsigned int
    if there are only (x,1) declarations in the system no distinction between instances is necessary. This is automatically detected. See the flag XMK_USED_ONLY_X_1 in the section "Automatic Scaling Included in Cmicro" .
  • unsigned int or unsigned long
    if there is at minimum one (x, N) declaration in the system, where N > 1, instances need to be distinguishable from each other.

There are a few macros defined to extract the process type number or the process instance number from a variable of the type xPID and to build an xPID variable from a process type number and a process instance number, the users do not have to think about the internal representation:

Example 566 : Macros to extract process type or instance number

processtype = EPIDTYPE(xPID_variable)
processinstance = EPIDINST(xPID_variable)
xPID_variable = GLOBALPID(processtype, processinstance)

Signals and Timers

SDL signals and timers are numbered automatically by the Cmicro SDL to C Compiler so that they have a unique number over the complete system. Timers are represented by the values 1, 2, 3.... MT to the last timer of the MT timers in the system. After that follow ordinary SDL signal numbers beginning with MT+1, MT+2, MT+3... MT + MS.

When using the standard Cmicro Package, as delivered, then the values 0 and 251 to 255 are reserved for internal purposes. If the upper limit of 250 signals and timers is being reached, then the signal ID type has to be changed from unsigned char to unsigned int, thus allowing more than 60000 signals/timers to be handled. All these changes will be done if the flag XMK_USE_MORE_THAN_250_SIGNALS is set.

Caution!

The Cmicro SDL to C Compiler does not check for the upper limit of 250 signals being reached for a generated SDL system. Instead the Targeting Expert will check the amount of signals and timers in the SDL system and will inform the user.

Example 567 :

C code generated for signals and timers:

#define znnn_SignalName 1
#define znnn_SignalName 2

Where znnn_ is the automatically generated prefix which is required to cope with the SDL scope rules. Remember, that processes in SDL can have the same name as signals, states etc. Prefixing, however, ensures uniquely named SDL objects in the generated C Code.

Example 568 :

A system with 2 signals S1 and S2, and a timer TIMER1:

#define z049_TIMER1     1
#define z050_S1         2
#define z051_S2         3

When it comes to connecting the environment to the SDL system, the automatic numbering of signal IDs and timer IDs may not be required. If the user wants to prevent the automatic numbering of signals, then it is possible to #include a file containing all the signal and timer numbers. The file may contain something like:

#undef SignalOrTimerName
#define SignalOrTimerName AnyValueAccordingToKernelRules

States

SDL states are consecutively numbered from 1 through to N for each process type. The values 0, and 250 to 255 are reserved for internal purposes in the Cmicro Package. This restriction incurs no foreseeable difficulty as processes should never have more than 50 States as a recommendation.

If there are even more states per process the flag XMK_USE_HUGE_TRANSITIONTABLES must be set.

The following C code generation is supplied for the header-section of the generated C file(s).

For each SDL process:

#define znnn_State1Name 1
#define znnn_State2Name 2
....
#define znnn_State3Name 3

Example 569 :

For a process with 2 states S1 and S2:

#define z020_S1
#define z021_S2

These values are used in the state-index-table and in the generated C functions, wherever a nextstate is referenced.


SDL Restrictions

General

The Cmicro SDL to C Compiler handles SDL concepts according to the definition of SDL-92. In addition to the restrictions of all the SDL to C Compilers, the following additional restrictions are introduced for the Cmicro SDL to C Compiler:

  • Inheritance of procedures
  • Procedures with states
  • Remote Procedure Calls
  • Nested procedure call data scope
  • Export / Import
  • View / Reveal
  • Enabling condition / Continuous signal
  • Service and priority input and output
  • Channel substructure
  • Declaring an infinite number of process instances (x, ) or ( , )
  • FPARS when creating a process
  • Omission of parameters in a signal input
  • Output via all
  • Timers duration values cannot be real
  • Timers with more than one parameter
  • Timers with another parameter than sort integer
  • The any expression
  • Only the list of ADT and packages that are explained in the subsection "Exceptions for SDL Predefined Types" and the subsection "Exceptions for Implementations of Operators" are handled correctly with Cmicro.

The following restrictions are additional regarding the packages that are delivered together with the SDL suite.

sdth2sdl

It is impossible to read in header files created with Cadvanced and use them in Cmicro and the other way around. The reason is that it is impossible to mix up C code between Cadvanced/Cbasic and Cmicro.

Combining Cadvanced / Cmicro C Code

Mixing C code from different C Code Generators is not possible as the different code generators use their own run-time model and run-time data structures. Trying to mix up the C code will lead to compilation errors.

Light and Tight Integrations

The Light and Tight Integrations delivered with the SDL suite are only available for Cadvanced but not applicable to Cmicro. There are light and tight integrations for Cmicro but these are not part of the product.

Restrictions in Combination with SDL Target Tester

Scope Rules / Qualifiers

If the SDL Target Tester is to be used, then the scope rules of SDL are handled in a restrictive fashion. No information is generated for the system, block, block substructure, channel and signalroute. After applying the Cmicro SDL to C Compiler, all the structuring information is lost.

This means that it is impossible to address two different processes with the same name in different blocks. In order to avoid problems, give all processes, signals and timers in the system a different (unique) name.

Predefined Sorts

The predefined sort charstring and all the predefined sort that are based on the implementation of charstring (like predefined sorts from ASN.1) cannot be handled, if the SDL Target Tester is to be used. All predefined sorts which are generated into pointers in C cannot be used. In order to get a detailed description, please see in 67 The SDL Target Tester.

Analyzer Restrictions

The restrictions in the SDL Analyzer, which also affects the Cmicro SDL to C Compiler, are summarized in 54 The SDL Analyzer.


66 The Cmicro Library

The Cmicro Library consists of a configurable SDL kernel together with all the necessary SDL data handling functions. The collection of C functions and C modules make up the so called SDL machine.

The Cmicro Library is used in combination with the C code generated by the Cmicro SDL to C Compiler. For information on the generator see 65 The Cmicro SDL to C Compiler.

The scaling facilities in Cmicro mean that it is useful for both micro controller and real-time applications. The Targeting Expert will help to scale and configure the generated code and the library. Please view 59 The Targeting Expert.

The SDL Target Tester offers the ability to target tests and debug Cmicro code. Please see 67 The SDL Target Tester.


Introduction

The Cmicro Library is required for handling the SDL objects that have been generated from SDL into C with the Cmicro SDL to C Compiler. This means that the C code which was generated with the Cmicro SDL to C Compiler cannot be used without the Cmicro Library. It also means that the C code generated with Cadvanced cannot be used together with the Cmicro Library and vice versa.

The Cmicro Library is a collection of C functions and C modules which consists of:

  • The non preemptive Cmicro Kernel
  • The preemptive Cmicro Kernel
  • All functions which are necessary to handle SDL data
  • Utility functions

Note:

The Cmicro preemptive kernel is only available if the according license is available.

Furthermore the Cmicro Library can be instrumented with SDL Target Tester functionality.

Before the Cmicro Library can be used, some adaptations and configurations must be made. The Targeting Expert is a tool which helps in configuring the application, node, component and the SDL Target Tester.

In this chapter, the C source code of the Cmicro Library and the generated C code of an application are described. Although a separate chapter is dedicated to the SDL Target Tester (see 67 The SDL Target Tester), a few features are outlined here. The following topics are discussed:

  1. The section "Differences between Cmicro and Cadvanced" helps in taking care of compatibility between different C code generators. There are things which must be observed in SDL diagrams.
  2. The section "The SDL Scheduler Concepts" gives information about how the SDL scheduler works. This is also of interest for creating SDL specifications with the most highest conformity because the different SDL schedulers work differently.
  3. The section "Targeting using the Cmicro Package" presents all the steps that must be carried out for doing targeting with Cmicro.
  4. The section "Compilation Flags" presents a complete list of all the flags that the Targeting Expert recognizes. The different flags are explained in detail.
  5. The section "Adaptation to Compilers" must usually be read before the C code generated by the Cmicro SDL to C Compiler and Cmicro Library can be compiled to form an executable. This section outlines the steps that must be carried out for introducing a C compiler which is not in the available list. The Targeting Expert offers an easy to use feature to add a new compiler. Please view "Compiler Definition for Compilation" .
  6. The section "Bare Integration" gives detailed information on how to adapt the generated SDL system to the environment. Communication with handwritten C code, as well as communication between SDL and the operating system or a naked machine, is described here.
  7. The section "File Structure" explains the functionality of the different C files delivered with Cmicro.
  8. The section "Functions of the Basic Cmicro Kernel" contains a list of C functions that are usually included in a target executable plus a short description.
  9. The section "Functions of the Expanded Cmicro Kernel" contains a list of C functions that are usually not included in a target executable. The functions listed in this section can usually be left out because they have meaning for special forms of integration in target systems only. The functions include a short description.
  10. The section "Technical Details for Memory Estimations" presents some information to the user which enables him to roughly estimate the consumption of memory in the target system. A self defined benchmark test is included, too.

Pay extra attention to the subsection "Automatic Scaling Included in Cmicro" , which contains important information on the differences to the Cadvanced Library.

If examples of generated code are given, they are always shown in ANSI style. In addition, only the important parts of the code are shown to increase readability in the examples.


Differences between Cmicro and Cadvanced

General

This description deals with the differences between the generated C code of the Cadvanced SDL to C Compiler and the Cmicro SDL to C Compiler and the run-time libraries. There are differences because the main application area for the code generators differ.

Some of the differences discussed in the following are of interest for SDL users, while others are not.

SDL Restrictions

The Cmicro SDL to C Compiler has more SDL restrictions than the Cadvanced SDL to C Compiler. The additional restrictions are described in the subsection "SDL Restrictions" .

Furthermore, there are restrictions within the Cmicro Library that may affect the user's SDL system design. These restrictions are listed in the following. More technical information can be found in the section "Generation of Identifiers" .

  • The run time model in Cmicro is such that there are global variables used in the generated C code and the Cmicro Library. The code generation uses "Auto initialization in C" quite extensively because the C compiler then can produce code that is more efficient than if initialization would take place within a generated C function (like yInit).
  • The run-time model of the preemptive kernel requires function recursion from the C compiler.

Scheduling

First, it must be emphasized that both schedulers conform fully with SDL, although the schedulers introduce a different behavior.

Cadvanced uses a process ready queue together with signal queues in order to schedule processes. Cmicro does not use a process ready queue but all scheduling is derived from one physical queue. This physical queue represents all SDL process input ports. Logically, or seen from SDL, each SDL process has its own input port.

Another difference is the preemptive scheduler of Cmicro, if it is used.

Thus, different execution of processes will occur.

It is also a question of SDL design whether the differences between Cadvanced and Cmicro can be externally recognized.

If no SDL process assumes a particular real-time behavior from its communicating partner process then the behavior - as seen from a black box view - is always the required one.

Generation of Files

The Cmicro SDL to C Compiler generates some more files. This is of interest when implementing build scripts, makefiles and so on.

It is important that after each change in the SDL system the Cmicro Library is re-compiled. The reason for this is the automatic scaling facility. Please view "Automatic Scaling Included in Cmicro" .

Environment Handling Functions

The main differences arise when considering the environment handling functions. However, this only has consequences if the SDL environment is the same in both cases (if Cadvanced is used for simulation only and Cmicro for targeting, then the environment functions are to be implemented twice in any case).

Instead of including scttypes.h as in Cadvanced, for Cmicro the following include statements are to be introduced in the header of the environment module:

#include "ml_typ.h"
#include "<systemname>.ifc"

In general (for Cmicro as well as Cadvanced) four C functions are used to represent the SDL environment, namely

  • xInitEnv,
  • xInEnv,
  • xOutEnv,
  • xCloseEnv.

The functions have the same general meaning for Cadvanced and Cmicro, but there are a few differences so that it is necessary to implement the environment twice.

For Cmicro, each of the above C functions is compiled only if it is required (selected by XMK_USE_xInitEnv, XMK_USE_xInEnv...)

Differences occur in the declaration of the C functions xInEnv() and xOutEnv().

The xInEnv() function of Cmicro carries no parameters.

The xOutEnv() function of Cmicro carries a few parameters which represent the signal which is to be output to the environment, including the signal parameters. It is recommended that the definition of the C function xOutEnv() should be written twice, once for Cadvanced and once for Cmicro.

The environment functions can also be generated with the help of the Targeting Expert.

Another difference is that signals and processes are identified in different ways. Cmicro does not use identifications like xIdNode. Instead, it uses fixed C defines to identify signals and processes. This is beneficial in reducing the amount of memory but has the consequence that each access to any signal and any process is to be implemented differently. Process type IDs are generated into the file sdl_cfg.h, signal IDs and type definitions are generated into the <systemname>.ifc file. The chapter about the Cmicro SDL to C Compiler gives more details on how identifiers are generated and can be used.

Including C Code in SDL by User

C code may be included in SDL by the user in the following cases:

  • In order to connect SDL to the environment in a way other than via the C functions xInEnv() / xOutEnv()
  • To use C constructs, which do not exist in SDL
  • To use existing C code (e.g. C library functions)
  • To implement the body of ADTs
  • In an SDL task.

If any C code or C identifiers are used, then users must use the right identifiers and functions.

Generated C Code

Of course, the generated C code is different when comparing Cmicro with Cadvanced. It would take too much room to list all the details in this subsection. In any case these differences are of interest for certain technical reasons only and not for pure SDL users.

To compare the different code generator outputs, the user should refer to the subsection "Output of Code Generation" .

General Recommendations Regarding Compatibility

In order to reach full compatibility between Cadvanced and Cmicro, the following general recommendations should be followed:

  • In general, C code should not be used in SDL diagrams.
  • If there is no option other than to use C code, the C code should be written as compatible as possible, i.e. the C code should be written without using any C code generator or compiler specific commands. Also the C code should be placed at dedicated locations, and should not be distributed over the SDL diagrams.
  • If it is not possible to reach full compatibility, then the C code must be written twice. A switch, which is used when invoking the C compiler, selects C code either for Cadvanced or for Cmicro. The macro XSCT_CMICRO will help to distinguish automatically.


The SDL Scheduler Concepts

In this section, the concepts of the Cmicro SDL scheduler are outlined, with particular emphasis on basic SDL, the handling of the queue, scheduling, signals, timers, states etc. To obtain information about data in SDL, especially ADTs, please consult 56 The Cadvanced/Cbasic SDL to C Compiler. Here both predefined and user defined ADTs are outlined.

Signals, Timers and Start-Up Signals

Data Structure for Signals and Timers

Each signal that is either an ordinary SDL signal, a timer or the start-up signal used for the dynamic process creation, is represented by three structures:

  • A C structure defining the entries in the queue
  • A C structure defining the header of each signal
  • A generated C structure representing the parameters of the signal

The first and the second is defined in ml_typ.h, the third is defined in the generated code as yPDef_SignalName. Some structure components are conditionally compiled, which is used to scale the system. Please view the following C structure:

typedef struct
{
#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xPID rec; /* Receiver process */
#endif

xmk_T_SIGNAL signal; /* Signalcode */

#ifdef XMK_USE_SIGNAL_PRIORITIES
xmk_T_PRIO prio; /* Priority */
#endif

#ifdef XMK_USE_SIGNAL_TIME_STAMP
xmk_T_TIME time_stamp;/* Timestamp */
#endif

#ifdef XMK_USE_SENDER_PID_IN_SIGNAL
xPID send /* Sender process */
#endif

#ifdef XMK_USED_SIGNAL_WITH_PARAMS
xmk_T_MESS_LENGTH mess_length;
union
{
void *ParPtr;
#if (XMK_MSG_BORDER_LEN > 0)
unsigned char ParCopy[XMK_MSG_BORDER_LEN];
#endif
} ParUnion;
#endif

} xmk_T_MESSAGE;

  • signal:
    represents a C constant which uniquely identifies the signal or timer across the complete system.
  • rec and send:
    represents the PID values of the receiver and sender of the signal. See the subsection "Processes and Process IDs (PID)" for details. These are conditionally compiled.
  • prio:
    is used to store the priority of the signal. This is specified by using the directive #PRIO in the SDL diagram. It is compiled only, if signals with priority are stipulated by the user.
  • timestamp:
    is used to store a timestamp, which is set when the SDL signal is put into the queue (output time). This component is also conditionally compiled.
  • mess_length:
    represents the amount of parameter bytes in the signal.

Three different cases are to be considered concerning signals with parameters:

  • If the signal has no parameters, then mess_length is set to 0 and ParPtr is a NULL pointer.
  • If the signal parameters are larger than XMK_MSG_BORDER_LEN (*) bytes, then mess_length is set to the number of bytes and ParPtr is undefined.
  • If more than XMK_MSG_BORDER_LEN (*) bytes of parameters are to be transferred, then mess_length defines the amount of bytes used for the parameters and ParPtr points to a dynamically allocated area.

Note:

This margin of XMK_MSG_BORDER_LEN bytes can of course be modified by the user to prevent dynamic memory allocation for any signal in the queue, or in contrast, to always use dynamic memory allocation. See the file ml_mcf.h to modify this.

The second structure, which encapsulates the above one, is used to administrate the signals in the queue, as required by the FIFO handling and SDL save construct:

typedef struct _T_E_SIGNAL
{
xmk_T_MESSAGE Signal;
struct _T_E_SIGNAL *next;

#ifdef XMK_USED_SAVE
xmk_T_STATE SaveState;
#endif /* XMK_USED_SAVE */
} T_E_SIGNAL ;

  • next:
    is a pointer which refers to the next entry of the queue. This is used by the Cmicro Kernel to get the next signal after the current one has been worked on.
  • SaveState:
    contains either a dummy state value XEMPTYSTATEID or the state in which the process saved the signal. This is necessary to compare when the signal is to be consumed after state changes in the receiver process. It is used only if save is used anywhere in the SDL system.

As already mentioned, the above structure is used for ordinary SDL signals, timers and the start-up signal for the dynamic process creation.

No differentiation is made between signals and timers, except that signals and timers have a different identification (signal in the xmk_T_SIGNAL structure).

When a process is to be created, a start-up signal is sent. The start-up signal is tagged by a special priority value and a special id.

Dynamic Memory Allocation

Dynamic memory allocation is in principle not necessary with Cmicro. There are SDL systems which can live without any dynamic memory allocation and there are SDL systems that require dynamic memory allocation from the user's point of view. The users should in general try to prevent any dynamic memory allocation due to the problems this introduces. Soon or later memory leaks will occur.

Cmicro offers its own dynamic memory allocator. Please view "Dynamic Memory Allocation" for getting more information on this.

In the following subsections, the exceptions for when Cmicro uses dynamic memory allocation are listed.

Signals and Signal Parameters

In order to cope with efficiency, dynamic memory allocation should not be done, whenever possible. Cmicro offers two principles of memory allocation for signal instances, namely:

  1. Signal instances are allocated from a static memory pool only.
    The static memory is allocated during compilation. The pool's size is predefined with the XMK_MAX_SIGNALS macro. To enable this configuration, the macro XMK_USE_STATIC_QUEUE_ONLY is to be set. This principle has the disadvantage that if there is no free memory in the static memory pool, a fatal error occurs. The user is however given the possibility to react on this error situation because the ErrorHandler C function is called.
  2. As another principle, it is possible to first take memory from the static memory pool. If no more memory is available in that pool, further signal instances are created from the dynamic memory pool.

    Caution!

    This configuration is not available when the preemptive scheduling mechanism is used.

    To enable the configuration, the macro XMK_USE_STATIC_AND_DYNAMIC_QUEUE must be set. The static memory pool's size is still predefined with the XMK_MAX_SIGNALS macro.

When signal instances are allocated from the static memory pool, the allocation procedure is the most efficient.

When the second principle is used, the execution speed will of course dramatically slow down because dynamic memory allocation happens. This change in the behavior of the Cmicro Kernel may cause problems in a real-time environment and the user should keep this in mind.

The static memory pool above is implemented as a predefined array in C. The array is dimensioned with the XMK_MAX_SIGNALS macro.

Dynamic memory is requested with the xAlloc C function and released again with the xFree C function. The body of both these C functions must in any case be filled out appropriately by the user in all cases.

Signal parameters are to be allocated dynamically, if the amount of parameter bytes exceeds a predefined constant. If the amount of signal parameters is below or equal this predefined constant, the parameter bytes are put into the signal's header.

The default value for this predefined constant XMK_MSG_BORDER_LEN is 4 bytes. Dynamic memory allocation only occurs if a signal carries more than XMK_MSG_BORDER_LEN bytes, where the latter is defined as 4.

If the user defines XMK_MSG_BORDER_LEN as 0, then for each signal, which has parameters, the C function xAlloc() is called.

If the user defines XMK_MSG_BORDER_LEN to 127, then

  • for signals which have 127 parameter bytes or less, the parameters are copied into the xmk_T_SIGNAL structure.
  • for signals which have more than 127 parameter bytes, the parameters are copied into an allocated area (using the C function xAlloc()).

Due to this mechanism, the allocation of signal parameters is also very fast. Releasing the memory is performed automatically by calling the xFree C function.

Predefined Sorts

Some of the predefined sorts require dynamic memory allocation. The sorts are

  • charstring
  • any ASN.1 sort that is based on charstring
  • predefined Generators like Array (without a specified upper limit), String, Powerset, Bag, Ref

SDL Target Tester

If the SDL Target Tester is used, there are some more allocations from the dynamic memory pool. The SDL Target Tester allocates one block of dynamic memory in the start phase. This block is never de-allocated again. The size of the block depends on the amount of process types in the system. Another dynamic memory allocation takes place when a binary frame is to be sent to the host machine. The blocks that are allocated here are de-allocated again after the frame is put into the physical transmitter buffer.

Overview for Output and Input of Signals

Output and input of signals is performed according to the rules of SDL. To get detailed information about the implementation of output and input, please consult the subsection "Output and Input of Signals" .

Signal instances are sent using the C function xmk_Send() or xmk_SendSimple(). The function takes a signal and puts it into the input port of the receiving process instance.

Figure 580 : Queueing - sending side

There is no process ready queue. Physically, the queues of the different processes of the system are represented by just one queue. There are different principals to create signal instances which the user can choose between. The principals are explained within the subsection "Signals and Signal Parameters" .

From an abstract point of view, it does not matter, if there is one physical queue for all the signal instances in the system, or if there is one physical queue for all the signal instances sent to one process instance. The fact that Cmicro uses one physical queue for all signals in the system only, has no effect on SDL users and conforms to the semantic rules of SDL. The scheduling simply depends on the ordering of signals in the queue. In the case of a preemptive Cmicro Kernel scaled this way, there is one linked list of signals per priority level all using the array mentioned above. See the subsection "Scheduling" for details.

Figure 581 : Queueing - receiving side

When working on a signal, the Cmicro Kernel decides between four different constellations:

  • The receiving process instance is active. In its current state the signal is to be saved. The Cmicro Kernel tags the signal as "saved" and works on the next signal.
  • The receiving process instance is active and there is a transition to be executed receiving the current signal. The Cmicro Kernel fires the transition.
  • The receiving process instance is active but there is no transition to be executed for that signal in the current process state. The signal is in accordance with SDL rules implicitly consumed by the process.
  • The receiving process instance is not active, i.e. either not yet created or already stopped. The signal will be discarded and the C function ErrorHandler(), discussed within the subsection "User Defined Actions for System Errors - the ErrorHandler" , will be called.

In any case, except when being saved, the signal will be removed from the queue and returned to the list of free signals.

After performing the nextstate operation, the input port is scanned in accordance with the rules of SDL to find the next signal which would cause an implicit or explicit transition.

There is no specific input function. This functionality is contained in the Cmicro Kernel.

Timers and Operations on Timers

With the delivered timer model, all timer management entities fully conform to SDL. This means that more memory is required to implement this timer.

For each timer, there is a C structure defined in ml_typ.h.

typedef struct _TIMER
{
struct _TIMER *next ;

xmk_T_SIGNAL Signal ;
xmk_T_TIME time ;
xPID OwnerProcessPID ;

} TIMER ;

xmk_T_TIME is defined as a long value.

Figure 582 : Handling of timers (timer model 1)

The component

  • next is used to refer to the next entry;
  • signal is the timer identification;
  • time is used to store the absolute time when the timer should expire;
  • OwnerProcessPID is used to refer to the process PID for which the timer was set.

As can be seen above, timers are implemented as a forward linked list.

  • An array of timers is allocated during compile time
  • The size of the array is calculated by the Cmicro SDL to C Compiler as the required maximum. It is defined by the macro MAX_SDL_TIMER_INSTS. This is also valid for multiple process instances, so that there is always enough memory to handle all timer instances which are possible. (If the user wishes to reduce the occupied RAM memory for timers, he must evaluate the maximum amount of timer instances required during run-time and modify the above define by hand).
  • The timer which expires first is always put to the front of the linked list (increasing performance).
  • The time value is stored as absolute time from the start of the SDL system.

Processes

Data Structure for Processes

Each process is represented by structures and tables containing SDL information, for example, tables containing transition definitions and a structure representing the variables of the process. The typedef for variables is generated in the generated code and named yVDef_ProcessName. For each process instance, there is one array element defined statically during compile time.

The structures and tables for processes are described in detail in the subsection "Tables for Processes" .

Scheduling

The Cmicro Kernel supports in principle the following scheduling policies:

  • Non Preemptive Scheduling:
    Transitions in SDL cannot be interrupted.
  • Preemptive Scheduling with Process Priorities:
    Transitions in SDL can be interrupted by any external or internal output. This could be a signal coming from the environment, i.e. an interface driver.
  • In addition, signal priorities can be used to specify the ordering of signals in the signal queue. Signal priorities are discussed in each of the subsections mentioned above.

General Scheduling Rules

  • All of the above policies basically operate on the SDL queue. Physically, the Cmicro Kernel uses one array for all process queues in the system. From the SDL point of view, the implementation conforms to SDL because each SDL process virtually has its own queue in the implementation.
  • signal priorities can be used in all cases.
  • process priorities are given priority treatment.
  • If no signal priorities are assigned, then the ordering of signals depends on their arrival (FIFO strategy).
  • In order to increase the performance, there is no process ready queue implemented. The scheduling of processes is fully derived from the SDL queue.

Further explanation of the scheduling is in the next subsection.

Non Preemptive Scheduling

The Cmicro Kernel takes the first signal from the queue and if the signal is not to be saved the appropriate SDL transition is executed until a nextstate operation is encountered. Outputs in SDL transitions as well as SDL create operations are represented by signals, where create signals are given priority treatment no matter whether signal priorities are used or not. This guarantees that there will not be any problems when a signal is sent to a process just before the process has been dynamically created.

The ordering of signals in the queue can be affected by using signal priorities (#PRIO directive for signals).

Whenever an output takes place, the Cmicro Kernel inserts the signal into the queue according to its priority. High priority signals are inserted at the queue's head, low priority signals at the queue's end. Create signals are still given priority treatment.

Note:

The priority of a create signal in the standard delivery is set to one.
This, as well as all the default signal priorities, is user-definable in the file ml_mcf.h (generated by the Targeting Expert). In this way it is possible to define signals with a higher priority then the create signal. The user should remember not to do so!

Figure 583 : Non preemptive scheduling

Figure 584 : Scheduling for Create

A signal (this is either an ordinary SDL signal, a timer signal or the internal start-up signal in the event of SDL create) with the highest priority is always put in front of the SDL queue, a signal with the lowest priority is always put at the end of the SDL queue.

Figure 585 : Signal priorities

For applications, which do not have time critical requirements, the non preemptive scheduling policy is the correct one to implement. The Cmicro Kernel memory requirements are also reduced when the non-preemptive scheduling policy is implemented. For example, for an interface with a very high transmission rate, the preemptive scheduling policy is better suited in order to increase the reaction time on external signals coming from the environment.

On starting the SDL system, processes are statically created according to their order of priority.

Preemptive Scheduling with Process Priorities

Note:

The Cmicro preemptive kernel is only available if the according license is available.

Figure 586 : Preemptive scheduling

SDL assumes the start transitions of all statically created processes are already finished at system start-up (a transition takes no time according to SDL semantics). To simulate this, the Cmicro Kernel starts all statically created processes in the order of their priority before working on any signal. Preemption is disabled during the start-up phase of the system. There are two C functions namely xmk_DisablePreemption and xmk_EnablePreemption which can be used to prevent the Cmicro Kernel from performing a context switch. In this way it is possible to affect the scheduling from within the SDL system (using the #CODE directive).

The preemptive scheduling policy is absolutely necessary if an application consists of a mixture of processes, of which some have to react very quickly to external events, while others require enough time for processing. The Cmicro Kernel does all things necessary to schedule such a mixture of processes.

Users only have to specify a high priority for processes which have to react after a short time. This can be done with the #PRIO directive for processes. If no #PRIO directive is specified, then a process is given the default value, which is specified by the user in the file ml_mcf.h (please view the subsection "Compilation Flags" ).

The highest priority is represented by the value zero. The numbering has to be consecutive with the priority decreasing with increasing numbers. Processes with the same priority are on the same priority level. The default process priority must be in the range of zero to the lowest priority value used in the system. Assume the following priority levels:

Figure 587 : Priority levels

In the figure above there are signals queued for processes on four different priority levels. These would be worked on in this order:

According to their priorities the signals on priority level zero are consumed first, afterwards those of level one, two and last three. This is relevant only, if no signals are sent during the transitions executed because of the signals.

Rules

  • At system start, SDL processes are statically created in accordance with their defined priority. During their start transitions it is possible for processes to send signals or create other processes but no preemption will take place until the start-up phase is completed, i.e. all static processes have completed the transition from start state to first state.
  • Processes running on a priority level never interrupt other processes running on the same priority level, thus two instances of the same type never run at one time.
  • A higher priority level is entered, if a signal results in a process with a higher priority running.
  • A lower priority level is entered, if all signals on the currently active priority level are consumed so that still no process is running on this priority level.
  • Global variables are used to store some information concerning processes. The Cmicro Kernel is responsible for the storing and reloading of these, if a preemptive kernel is implemented.

Note:

If C variables are to be used in the SDL application, i.e. (x, N) declarations are used where N > 1 these variables are only available once and not once per process instance.

Restrictions

In order to produce portable C code, this version of the Cmicro Kernel uses recursive C function calls. A few C compilers available on the market do not support recursion. If such a C compiler is required, the user cannot use preemptive scheduling with process priorities.

Create and Stop Operations

No dynamic memory allocation occurs if an SDL create operation is performed. No freeing of memory occurs if an SDL stop operation is performed.

Data of a process instance is represented by the following typedef structs:

  • A typedef struct representing PID values (parent and offspring) stored for an instance
  • A typedef struct representing SDL states of an instance
  • A typedef struct representing SDL data of an instance

The reason for using such a structure is to make it possible for the Cmicro Kernel to operate on the PID structure and the table with SDL states, so that no code needs to be generated in the application to update such variables.

An array of N elements for each of these typedef structs is generated, where N is the maximum number of process instances. The maximum number is to be specified in the process declaration header in the SDL diagram.

After performing a stop action, old PID values might exist in variables of other processes. The synchronization between processes to prevent situations where signals are sent to dead processes is left to the discretion of the user. If a process sends a signal to a non existent process, where nonexistent means either "never created" or "is dead", the ErrorHandler is called and the signal is discarded (SDL conform).

When the Cmicro Kernel stops a process, the input queue assigned to the process stopped will be removed. No interpretation error occurs for the signals which existed in the queue before the process was stopped.

Note:

It is also possible for the user to implement dynamic memory allocation for process instance data. Some C defines are to be redefined in this case.

Output and Input of Signals

The actions to perform an output in the generated code are as follows:

  • A struct variable is initialized with the type of the signal parameters, not using memory allocation.
  • The struct variable is then filled, parameter per parameter in generated code.
  • One of the xmk_Send* functions is called with a pointer to the location of the struct variable. There are several xmk_Send* functions in order to use the most effective one in SDL output.

Within the xmk_Send*- functions there are a few checks performed. For example, if the receiver is a NULL-PID, then the ErrorHandler is called.

Next, the environment C function xOutEnv is called. This function is to be filled out by the user. The function decides if the signal should be sent to the environment. The information necessary can be extracted from the signal ID, the priority or the receiver of the signal. If xOutEnv has "consumed" the signal, xmk_Send* returns immediately.
xOutEnv has to copy the parameters of the signal to the receiver of the signal in the environment because after returning, the parameters will no longer exist.

If the signal is not environment bound, then the signal is sent to an internal SDL system process and xmk_Send* inserts the signal into the queue. This is done according to the priority of the signal (see subsection "Assigning Priorities - Directive #PRIO" .

If the signal carries no parameters, or if the signal parameters are represented by less than or equal to XMK_MSG_BORDER_LEN bytes, no dynamic memory allocation occurs and possible parameters are transferred directly by copying them into the signal header.

If more than XMK_MSG_BORDER_LEN bytes parameters are to be transferred dynamic memory allocation occurs. A pointer in the signal header then points to this allocated memory area. Freeing is done after consumption of the signal at the receiver process after executing the nextstate operation or after the signal was consumed by the environment.

In order to implement this strategy, each signal carries a field "data length" in its header, to detect if a pointer is transferred or a copy of the parameters.

Note:

There are several possibilities to send signals to the environment by not using xOutEnv. The user should have a look at the #EXTSIG, #ALT and #TRANSFER directives which can be used in SDL Output. The one most similar to SDL, however, is the one which simply uses the C function xOutEnv.

At the receiver's side, when the input operation is to be performed, it is checked if the signal is to be saved or discarded. In the case of save, the next signal contained in the queue is checked and worked on. If on the other hand the signal is to be discarded, in the case of an "implicit transition", i.e. no definition is present to handle that signal in the current state, the signal is then deleted from the input port of the process and, using the SDL Target Tester, the user is notified.

Otherwise, the signal leads to the execution of the transition. After performing the nextstate operation, the signal is deleted from the input port of the process and scheduling continues according to the rules of the scheduler again.

In the case of a so scaled preemptive Cmicro Kernel, the signal remains active in the input port until the nextstate operation is executed, although other processes can interrupt the running one (preemption).

Nextstate Operation

The nextstate operation is implemented by a return (return value) statement in the generated code. Several return values are possible to control the action to be taken by the Cmicro Kernel. The PAD function representing the SDL process can return any of the following (PAD means "Process Activity Description").

The return-value either expresses

  • An ordinary SDL state change, the value is a C constant representing the SDL state as a simple integer (generated as #define),
  • no SDL state change, indicated by the value SDL_DASH_STATE,
  • SDL process stop operation, indicated by the value SDL_STOP.

After recognizing the action to be taken, the Cmicro Kernel either writes the process state variable or stops the SDL process.

The signal which was just being worked on is deleted from the input port. This includes the freeing of the memory area allocated for the signal, if memory was previously allocated.

Decision and Task Operations

No action is to be performed by the Cmicro Kernel for decisions and tasks, except those to trace these actions for the SDL Target Tester.

For SDL decisions and SDL tasks, C assignments and C function calls are implemented. Function calls are used in the case of an ADT or where simple C data operations (i.e. =, >, >=, ==) cannot represent the SDL operation wanted.

Note:

Function calls, however, are not necessarily generated, i.e. if the user defines C macros/defines instead of C functions for an ADT. Please consult the subsection "Abstract Data Types" .

Procedures

There are some special topics regarding procedures in SDL. The most important are:

  • The location of data and how to access data
  • Scope and visibility rules
  • Procedures with states
  • Recursivity
  • Who can call a procedure

Note that procedures with states and remote procedure calls are not supported within the Cmicro Package.

It is possible to use global procedures (SDL'92) which makes it possible to specify a procedure once, by allowing several processes to call it.

Recursion is allowed, but should be introduced only if an algorithm cannot be designed alternatively. In most cases, algorithms and recursivity are subjects for an ADT.

Procedures returning values are also implemented. The return value in SDL is mapped to a return value in C. Procedures not returning values are mapped to C functions returning void.

The remaining part is the location of procedure data and the access to procedure data. Here another restriction exists, namely that it is not possible to access data of the father procedure of a procedure without declaring this explicitly.

Data, which belongs to a process is always located as a global array in C (for x, N process declarations, where N is >1). Data which belongs to a procedure is always allocated on a C stack for the called procedure.

Procedure Calls

An SDL procedure call is implemented as a direct function call in C. Each formal parameter is passed as a C parameter to the function. Access to global data of the calling process is possible only if the procedure is not a global procedure. The C code generated for a local procedure uses global C variables of the surrounding process.

Data which is declared locally within a procedure is also allocated on the C stack.

No dynamic memory allocation is performed as procedures with states are not handled.

The following example shows the mapping for procedures returning values.

Example 570 : Procedure Call

TASK i := (call p(1)) + (call Q(i,k));

is translated to something like:

i = p(1) + Q(i,k);

Note:

The value returning procedure calls are transformed to C functions returning values.

An SDL procedure can be called more than once. No conflicts occur if using a preemptive Cmicro Kernel.

Procedure Body

For each SDL procedure, there is one C function generated. The Procedure body can contain the same SDL actions as the process body. The same code generation is performed with the exception of a few statements declaring temporary variables.

Within global procedures, no objects of the calling process can be used without declaring them via formal parameters. Another restriction is that each output in a global procedure must be specified with to PID.

Blocks, Channels and Signal Routes

No C code is generated for blocks, channels and signal routes, except the C comment, which tells the user the location of processes and procedures.


Targeting using the Cmicro Package

Directory Structure

At first it is necessary to know the directory structure the Cmicro Package is stored in.

On UNIX, the Cmicro Package is contained in $sdtdir/cmicro.

In Windows, the Cmicro Package is contained in %SDTDIR%\cmicro.

cmicro
+-- include
+-- kernel
+-- mcod
+-- template
+-- commlink
+-- tester

Furthermore all files, which are used when targeting Cmicro, are definitely stored in this directory tree. Otherwise the files are generated by the Cmicro SDL to C Compiler or by the Targeting Expert.

Prerequisites

Before starting the targeting with Cmicro it is necessary to have an SDL system designed and already tested with the help of the Simulator.

This means targeting begins when the first testing phase is finished.

All steps of targeting will be discussed in the following sub-sections.

Different Steps in the Work Flow

All the different operation steps listed here will completely supported by the Targeting Expert (see 59 The Targeting Expert).

  1. To start the Targeting Expert, select the entry Targeting Expert in the Organizer's Generate menu.
  2. Select pre-defined integration settings or <user defined> for a new integration. See "Pre-defined Integration Settings" .
    • select the Code Generator Cmicro (if not automatically done)
    • select the compiler (if not automatically done)
      The Cmicro SDL to C Compiler will automatically be invoked and generates the following files (assumed that separation is not selected):

 sdl_cfg.h

 the automatic configuration
<systemname>.c
the SDL system

 <systemname>.ifc

 the environment header file

 <systemname>_gen.m

 the sub-makefile (Targeting Expert)

 <systemname>.xrf

 the X-References (not used)

 <systemname>.sym

 the symbol file (SDL Target Tester)

  3. Specify the compiler, linker and make settings (if not automatically done).
    Please view "Configure Compiler, Linker and Make" .
  4. Configure and scale the generated C code and the Cmicro Library.
    • For information about the compilation flags and their interdependencies please view "Compilation Flags" .
    • For more details how to use the Targeting Expert please view "Configure and Scale the Target Library" .
  5. Copy template files.
    Several files of the Cmicro Package are delivered as template files. This is done because lots of things can only be done by the user as they must fit to the user's SDL system. The template files give easy to use C functions including help to adapt them to the user's needs.
    All the files mk_stim.c, mk_user.c and mk_cpu.c should be copied into the project's directory tree (generated by the Targeting Expert). All these files are stored in the template directory.
    If the SDL Target Tester should also be used it is necessary to copy the files mg_dl.c and the files describing the preferred communications link (e.g. the file 8051_v24.[ch] if an 8051 micro controller and a V.24 interface should be used) into the project directory, too. The file mg_dl.c is stored in the template directory and the communications link files are stored in template/commlink if contained in the Cmicro Package delivery. Please view the sub-section "The Communications Link's Target Site" to get information about how to create an own communication link.
    Please view also "Source Files" to get information on how to add more files to the list of files to be compiled. The Targeting Expert will automatically add these files to the makefile.
  6. Full make the complete system.
    It is probably necessary to do an environment connection first (see "Connecting the SDL Environment" ).
  7. Download and execute the executable.
    The following sections in the Targeting Expert's manual (59 The Targeting Expert) should be checked to find out how these steps can be eased:
    • "Download Application"
    • "Test Application" (which is probably the target executable itself)

Connecting the SDL Environment

From the Cmicro Package's point of view the SDL environment is represented in template C functions. A short overview of this C functions is given here. For further information please view "Bare Integration" .

  • xInitEnv():
    This function is given as a template in the file env.c. It needs to be filled any time it is necessary to initialize specific hardware components on the target.
  • xCloseEnv():
    xCloseEnv() is given as a template in env.c, too. It is only necessary to fill this function if the SDL system can perform a system stop.
  • xInEnv():
    xInEnv() is basically generated by the Targeting Expert into the file env.c. This means that all the signals coming from the environment are already inserted into the C code of this function.

Note:

All the modifications of env.c should only be done between the comments /* BEGIN User Code */ and /* END User Code */. All the other modifications will be lost when re-generating the env.c file.

  • xOutEnv():
    For all the signals to the environment the Targeting Expert generates the C function xOutEnv() into the file env.c. All the signals to the environment are included into the C code.

Note:

All the modifications of env.c should only be done between the comments /* BEGIN User Code */ and /* END User Code */. All the other modifications will be lost when re-generating the env.c file.

  • User Defined Actions for System Errors - the ErrorHandler:
    The Cmicro Package supports the handling of detected errors by calling the C function ErrorHandler() in the module mk_user.c.
    The user needs to redirect the error messages to his target hardware. I.e. display the errors on the hardware.

The compilation and linkage of the environment functions can be prevented by using the flags given in "Compilation Flags" .

Different Forms of Target Integration

Different forms of target integration, that is, integrating generated C code, are distinguished:

  • Bare Integration: There is no operating system available on the target machine. The main() function of Cmicro can be used.
  • Light Integration: An operating system is used and the complete SDL system executes in one operating system task. The SDL task communicates with the environment by using the communication resources of the operating system.
  • System partitioning: An operating system is used, the SDL system may execute in different CPUs, or the processes of the SDL system execute in different OS tasks.
  • Tight Integration: An operating system is used, the SDL system executes in one CPU, and the processes of the SDL system execute in different tasks.

Bare and Light integration represent the most easiest form of integration.

Bare integration is described in "Bare Integration" .

Light integration is described in "Light Integration" .

Tight integration can be performed with Cmicro, but the complexity makes it difficult to describe the integration in this section. It is a generic solution available, which guides thought the integration.

Please contact Telelogic local sales office/Professional Services for further information.


Compilation Flags

Compilation flags are used to decide the properties of the Cmicro Library and the generated C code. Both in the Cmicro Library and in the generated code #ifdef's are used to include or exclude parts of the code.

The switches used can be grouped:

  1. Flags defining the compiler
  2. Flags defining the properties of a compiler
  3. Flags defining the properties of the Cmicro Library
  4. Flags defining the implementation of a property

The first two groups are discussed in "Adaptation to Compilers" .

The remaining two groups are discussed under "Manual Scaling" and "Automatic Scaling Included in Cmicro" .

Flag naming conventions:

    • XMK_ADD_: include optional parts
    • XMK_USED_: automatically include parts of the Cmicro SDL to C Compiler. Note: Do not switch off by hand.
    • XMK_USE_: manual scalings
    • XMK_MAX_: manual scalings

Use the default settings of these flags in order to reduce potential problems.

Manual Scaling

Users are able to scale some features of the Cmicro Library and the Cmicro Kernel in order to optimize the generated code. All the flags discussed in this section are used throughout the complete SDL system, therefore it is not possible to define flags for processes separately.

Note:

The whole SDL system must always be generated.

The manual scalings have to be done in the file ml_mcf.h. They are divided into the following groups:

  1. Cmicro Kernel/Library
    • Kernel
    • Signals
    • Timers
    • Error checks
  2. Support of SDL Constructs
    • Predefined sorts
    • Size of variables
    • Use of memory
  3. SDL Environment
  4. SDL Coder
  5. SDL Target Tester
    • Initialization
    • Trace
    • Record and Play
  6. Communication Link and Compiler

In the following subsections, the way to configure the Cmicro Package by hand and all the available flags are described.

The user is asked to use the Targeting Expert to configure the Cmicro Package. A description of how to use the targeting Expert can be found in "Targeting Work Flow" .

To configure the Cmicro Package by hand, the user has to modify the file ml_mcf.h.

To use a Cmicro Package feature just define it in ml_mcf.h like

#define FLAG_NAME_AS_DESCRIBED_BELOW

Sometimes a flag just carries a value. In this case the user has to modify the value in ml_mcf.h

#define FLAG_CARRYING_VALUE VALUE

Cmicro Kernel/Library

Kernel

General

  • XMK_USE_KERNEL_INIT
    When this flag is defined, the Cmicro Kernel memsets all variables of the SDL processes to 0 before the process is created. This is useful to spare some ROM memory but has the disadvantage of a longer process creation phase. The ROM used by the yDef_SDL_* functions can be spared in this case where the initialization with 0 is appropriate.

Initial setting
set

  • XMK_USE_SDL_SYSTEM_STOP
    Normally, it is unnecessary to have an SDL system stop in micro controller applications. An SDL system stop occurs if no living process in the SDL system exists and all queues are empty. This occurs if all process instances have executed an SDL stop and no create process action is open (create signal in any queue).
    Defining XMK_USE_SDL_SYSTEM_STOP means that the C function main returns correctly with exit(...). To avoid this overhead in the Cmicro Kernel, the user should not define the above flag.

Default setting
unset

  • XMK_SYSTEM_INFO
    If this flag is set, some functions available to get information about the SDL system during runtime. See "Functions to get System Information"

Initial setting
unset

  • XMK_USE_NO_AUTO_SCALING
    When this flag is defined, automatic scaling of SDL features is prevented. An example of flag usage is implementing a change to the SDL system which does not require re-compilation of the Cmicro Library. Note that if the number of processes, signals or timers is changed, the Cmicro Library must be re-compiled. The definitions contained in sdl_cfg.h are overwritten in ml_typ.h.

Initial setting
unset

  • XMK_USE_KERNEL_WDTRIGGER
    If this flag is defined, the Cmicro Kernel calls the C function WatchdogTrigger before executing a transition. This function is present as a template in the Cmicro Library source files.

Initial setting
unset

Kernel Limits

  • XMK_USE_HUGE_TRANSITIONTABLES
    Per default the Cmicro Package can handle up to 252 different transitions per process. If the SDL system exceeds this size, it is necessary to set this flag. See "Transition Table" for further information.

Initial setting
unset

  • XMK_USE_MORE_THAN_250_SIGNALS
    Per default the Cmicro Package is designed to handle up to 250 user defined signals. When using larger SDL systems it is necessary to define this flag. This results in larger RAM and ROM occupation and should only be done if necessary (see xmk_T_SIGNAL).

Initial setting
unset

  • XMK_USE_MORE_THAN_256_INSTANCES
    Per default the Cmicro Package handle up to 256 instances per process type. If the system uses more than 256 instances per type it is necessary to set this flag.

Initial setting
unset

  • XMK_USE_PAR_GREATER_THAN_250
    Per default the Cmicro Package is able to handle signal parameters up to a length of 250 octets. If greater signal parameters are used (at least once) this flag needs to be set. Please view xmk_T_MESS_LENGTH in ml_typ.h for further information.

Initial setting
unset

Signal Structure

  • XMK_USE_SENDER_PID_IN_SIGNAL
    When this flag is defined a sender pid is included in each signal instance. It is possible to omit the sender pid if the system contains no to SENDER or to PARENT addressing.

Initial setting
set

  • XMK_USE_RECEIVER_PID_IN_SIGNAL
    When this flag is defined a receiver pid is included in each signal instance. It is possible to omit the receiver pid if the user writes a C function xRouteSignal() which is given as a template in mk_user.c. Each signal type is then mapped to a unique receiver. It is recommended to define this flag in small systems where unique receivers exist for each signal type. It is important to note that in the case of dynamically created processes an internal create signal is used. If there are any (x, N) where N > 1, declarations in the system, the create signal cannot contain the receiver pid. The receiver pid is necessary for correct creation of processes. Never leave it out when using dynamic process creation.

Initial setting
set

  • XMK_MSG_BORDER_LEN
    The value of this macro gives the length of signal parameters carried inside the signal. Note: If the parameter length exceeds this value a memory allocation is performed and the signal parameters are copied into this buffer. The pointer to the allocated buffer is carried inside the signal's structure (see ml_typ.h for the typedef xmk_T_SIGNAL).

Initial value
4

Signal Handling

  • XMK_USE_xmk_SendSimple
    This flag enables the output C function xmk_SendSimple() defined in the Cmicro Kernel. If the SDL system contains several signals without parameters and priorities, it is useful to set this flag in order to select the more optimal output C function, xmk_SendSimple(), in the Cmicro Kernel.

Initial setting | set
Reset | XMK_USE_SIGNAL_PRIORITIES

  • XMK_USE_SAFE_ADDRESSING
    Setting this flag includes a special entry in the signal queue which ensures the handling of sender and offspring in the start transition.

Initial setting
unset

Signal Queue

  • XMK_USE_STATIC_QUEUE_ONLY
    Create signals only from the static memory. The static memory is predefined with XMK_MAX_SIGNALS.

Initial setting | set
Reset | XMK_USE_STATIC_AND_DYNAMIC_QUEUE

  • XMK_USE_STATIC_AND_DYNAMIC_QUEUE
    Create signals from the static memory which is predefined with XMK_MAX_SIGNALS. If more signals have to be inserted memory is allocated from the dynamic memory pool.

Initial setting | unset
Reset | XMK_USE_STATIC_QUEUE_ONLY

  • XMK_MAX_SIGNALS
    In the Cmicro Package, the SDL queue is physically implemented as one queue for all processes. The define discussed in this section represents the maximum amount of signals in the static signal instance memory pool (see "Dynamic Memory Allocation" for more information). It may be difficult to evaluate the maximum entries required during run-time because this totally depends on how the SDL system is specified, and target hardware performance. It is for example, impossible to state how much time hardware requires to process an SDL signal.
    By examining the SDL system it can be determined which processes have a long transition time and which processes send or receive more than one signal. Estimate by trying out worst case situations. A first estimation is also possible by calculating:
    maximum amount of process instances * 3
    For a more exact estimation the user should use the profiler contained in the SDL Target Tester to obtain the necessary information on how many entries are used during run time.
    Another method of helping to determine the maximum amount of signals required by the system is to use the exception handling mechanism offered by the ErrorHandler, i.e. when the queue is full and another signal is to be inserted then the ErrorHandler function is called.

Initial value
20

Note:

Using dynamic memory allocation does not prevent the user from estimating the required memory for the queue. Sooner or later problems arise (e.g. memory fragmentation) if dynamic memory management is used frequently. For this reason the Cmicro Package avoids where possible the use of dynamic memory management.

Light Integration

  • XLI_LIGHT_INTEGRATION
    If this flag is set, some functionality is included to make a light integration easier.

Initial setting | unset
Automatic set | XMK_USE_INTERNAL_QUEUE_HANDLING XLI_LIGHT_INTEGRATION

  • XMK_USE_INTERNAL_QUEUE_HANDLING
    This flag make additional functions for queues the handling available which are needed for light integrations.

Initial setting | unset
Reset | XLI_LIGHT_INTEGRATION

  • XLI_INCLUDE
    The value of this is the name of the header file which is included in ml_typ.h when XLI_LIGHT_INTEGRATION is set. This file contains the definitions of the light integration macros. See "Define the macros which are needed in the task function."

Initial setting
"li_os_def.h"

Tight Integration

The complexity of a tight integration is very high. But there is a generic solution available, which guides you through the integration.

Please contact Telelogic local sales office/Professional Services for further information about this solution.

  • XTI_USE_INTERNAL_OUTPUT
    For more information about this contact local Professional Services

Initial setting
unset

  • XTI_USE_LOCK_IN_CREATE
    For more information about this contact local Professional Services

Initial setting
unset

Error Handler

  • XMK_USE_MAX_ERR_CHECK
    When this flag is defined, additional error checks are included in the generated code of the Cmicro Library. For further details, see the appropriate section on "errors and warnings". For example the Cmicro Kernel calls the ErrorHandler if a signal is sent to an undefined process (i.e. undefined pid value).

Initial setting | set
Reset | XMK_USE_MIN_ERR_CHECK XMK_USE_NO_ERR_CHECK

  • XMK_USE_MIN_ERR_CHECK
    In comparison to XMK_USE_MAX_ERR_CHECK this flag only includes a basic set of error checks.

Initial setting | unset
Reset | XMK_USE_MAX_ERR_CHECK XMK_USE_NO_ERR_CHECK

  • XMK_USE_NO_ERR_CHECK
    When this flag is defined, all error checks are excluded. It is recommended not to use this flag until the post testing phase of the implementation, where it can be reasonably assumed that no errors remain. For further details see the appropriate section on "errors and warnings".

Initial setting | unset
Reset by | XMK_USE_MAX_ERR_CHECK XMK_USE_MIN_ERR_CHECK

  • XMK_USE_MON
    If the target executable runs on an environment with monitor functions, the module ml_mon.c can be included to have access to functions like xxmonhexasc() etc.

Initial setting
unset

  • XMK_ADD_PRINTF
    When this flag is defined some additional printf C function calls are compiled giving users more information about the internal work of the system. The printf function can be switched on separately for Cmicro Kernel, SDL Target Tester and SDL application. At a lower level, it can be switched on separately for each C module. Look at the defines in ml_typ.h, which are all named as XMK_ADD_PRINTF_*.
    This flag must be undefined when compiling for the target, except in the case where there is a stdio implemented on the target. For correct compilation, the user must also set XMK_ADD_STDIO. If the user wishes to implement user specific printf functionality then this flag need not be set.

Initial setting | unset
Automatic set | XMK_ADD_STDIO

Reactions on Warnings

  • XMK_WARN_ACTION_HANG_UP
    If this flag is defined, the default behavior, if a warning is detected during SDL execution, is defined as "program hang up".
    The user might choose this reaction when there is no output device (like printf) available in the SDL program environment.
    The user should notice that a warning can lead to an illegal system behavior. As an example, this might come true for an implicit signal consumption. The system then hangs but the user might perhaps not be able to see the reason why this occurs. As a result, it is recommended to trace for warnings also.

Initial setting | set
Reset | XMK_WARN_ACTION_PRINTF XMK_WARN_ACTION_USER

  • XMK_WARN_ACTION_PRINTF
    By defining this flag, the user chooses that in the case of a warning, a printf function call with an appropriate error text should occur. Please see XMK_WARN_ACTION_HANGUP also.

Initial setting | unset
Reset | XMK_WARN_ACTION_HANG_UP XMK_WARN_ACTION_USER

  • XMK_WARN_ACTION_USER
    By defining this flag, the user chooses that in the case of a warning, a user defined function should be called. The user's function name must then be specified with XMK_WARN_USER_FUNCTION. Please see XMK_WARN_ACTION_HANGUP also.

Initial setting | unset
Reset | XMK_WARN_ACTION_HANG_UP XMK_WARN_ACTION_PRINTF

  • XMK_WARN_USER_FUNCTION
    If the flag XMK_WARN_ACTION_USER is defined, then the user must define the name of a C function with this macro. Please see XMK_WARN_ACTION_HANGUP also.

Initial setting
user_function()

Reaction on Errors

  • XMK_ERR_ACTION_HANG_UP
    If this flag is defined, the default behavior, if a fatal system error is detected during SDL execution, is defined as "program hang up".
    The user might choose this reaction when there is no output device (like printf) available in the SDL program environment.
    The user should notice that if a fatal system error is ignored, this usually leads to an illegal system behavior. As an example, this might come true for any use of null pointer values, for which there is an error check. It is strongly recommended to trace for system errors and warnings.

Initial setting | set
Reset | XMK_ERR_ACTION_PRINTF XMK_ERR_ACTION_USER

  • XMK_ERR_ACTION_PRINTF
    By defining this flag, the user chooses that in the case of a system error, a printf function call with an appropriate error text should occur. Please see XMK_ERR_ACTION_HANGUP also.

Initial setting | unset
Reset | XMK_ERR_ACTION_HANG_UP XMK_ERR_ACTION_USER

  • XMK_ERR_ACTION_USER
    By defining this flag, the user chooses that in the case of an system error, a user defined function should be called. The user's function name must then be specified with XMK_ERR_USER_FUNCTION. Please see XMK_ERR_ACTION_HANGUP also.

Initial setting | unset
Reset | XMK_ERR_ACTION_HANG_UP XMK_ERR_ACTION_PRINTF

  • XMK_ERR_USER_FUNCTION
    If the flag XMK_ERR_ACTION_USER is defined, then the user must define the name of a C function with this macro. Please see XMK_ERR_ACTION_HANGUP also.

Initial setting
user_function()

Timer Scaling

If there are timers used within the SDL system, the timers have to be scaled.

  • XMK_USE_TIMER_SCALE
    The timer units can be scaled within the Cmicro Kernel. This means that the factor given with XMK_USE_TIMER_SCALE_FACTOR is used.

Initial setting
unset

  • XMK_USE_TIMER_SCALE_FACTOR
    The factor modifies the expiration of timers. Is a value of 1 given here, it means that the expiration time is un-modified. A value of 100 increase the expiration time with a factor of 100 with other words the timer needs 100 times longer.

Initial value
100

  • XMK_TIMERPRIO
    An expired timer is handled like a signal inside the Cmicro Kernel and inserted into the signal queue. In this way there has to be a priority level if signal priorities are used. The XMK_TIMERPRIO gives the priority for all expired timers. This default value can lay between 0 and 250.

Initial value
100

Timer queue

  • XMK_USE_GENERATED_AMOUNT_TIMER
    The code generator evaluates the amount of timers that are declared in the system. The result of this evaluation is then, after code generation, defined with XMK_MAX_TIMER_INST in the file sdl_cfg.h. Timer instances are, usually, implemented as a C array with Cmicro. If the XMK_USE_GENERATED_AMOUNT_TIMER flag is set, then the timer array is dimensioned with the evaluated amount (XMK_MAX_TIMER_INST).
    When timers with parameters are in the system, the automatically generated value XMK_MAX_TIMER_INST can be used to pre-define one timer instance of a timer declaration. If there are then more timers to be instantiated, dynamic memory allocation must take place. This cannot be evaluated by the code generator.
    As a result, if there are timers with parameters in the system, the user should think about how many timer instances there could be during execution and should decide upon the maximum amount by himself. In this way, memory consumption and performance can be balanced.

Initial value
set

  • XMK_MAX_TIMER_USER
    This macro is used for internal purposes. The meaning of it is the opposite of XMK_USE_GENERATED_AMOUNT_TIMER.
    The flag is set when XMK_USE_GENERATED_AMOUNT_TIMER is not set. The flag XMK_MAX_TIMER_USER is unset if XMK_USE_GENERATED_AMOUNT_TIMER is set.

Initial value

unset

  • XMK_MAX_TIMER_USER_VALUE
    If XMK_MAX_TIMER_USER is set, the value XMK_MAX_TIMER_USER_VALUE becomes meaningful. With this value, the user may specify how many timer instances should be predefined during compilation time. The predefined timer instances offer the advantage that no dynamic memory allocation is to be done for them. If the predefined amount of timer instances is exceeded, then dynamic memory allocation will occur. As a result, it is up to the user how he balances static and dynamic memory for timer instances by changing this value.

Initial value

20

Execution Time

  • XMK_USE_CHECK_TRANS_TIME
    When this flag is defined the time duration for each executed transition is checked against a predefined duration. If the executed duration is longer than the predefined duration set by the XMK_TRANS_TIME flag, the ErrorHandler() is called. The flag is only available when using a non preemptive Cmicro Kernel. No additional hardware is necessary as the evaluation is based on the SDL time value NOW which is provided by the same hardware source as for the system clock.

Initial setting | unset
Automatic set | XMK_TRANS_TIME

  • XMK_TRANS_TIME
    This macro specifies the time duration that a transition execution time is compared with. The value must be in the target system time units, e.g. if the target's system step is 0,002 sec, the value 100 specifies a duration of 0.2 sec.

Initial value | 20
Depend on | XMK_USE_CHECK_TRANS_TIME

Signal Priorities

In the standard configuration of the Cmicro Kernel no signal priorities are used. So each signal sent is inserted at the end of the signal queue.

  • XMK_USE_SIGNAL_PRIORITIES
    When this flag is defined, the header of each signal which is sent via the SDL queue has an additional entry, namely "priority". This is used to modify the ordering of signals in the queue.
    This flag should be used in combination with using the #PRIO directive. It works for all the different scheduling methods.
    If signal priorities are enabled, signal handling xmk_SendSimple has to be switched of.

Initial setting | unset
Automatic set | xDefaultPrioSignal XMK_CREATE_PRIO
Reset | XMK_USE_xmk_SendSimple

  • xDefaultPrioSignal
    If a signal has not got a priority assignment within the SDL system, it is handled with the default value xDefaultPrioSignal. A value between 0 (highest priority!) and 250 should be entered.

Initial value | 100
Depend on | XMK_USE_SIGNAL_PRIORITIES

  • XMK_CREATE_PRIO
    Create signals can not be assigned a signal priority within the SDL system. As these signals are also handled over the signal queue, a default priority is necessary when signal priorities are selected (i.e. XMK_USE_SIGNAL_PRIORITIES is defined). A value between 0 (highest priority!) and 250 should be entered.

Initial value | 1
Depend on | XMK_USE_SIGNAL_PRIORITIES

Preemption

Normally, the Cmicro Kernel is configured so that the simple scheduling policy is used, i.e. transitions of SDL processes are non interruptible.

Note:

The Cmicro preemptive kernel is only available if an according license is available.

  • XMK_USE_PREEMPTIVE
    Usually the Cmicro Kernel is configured to "non preemptive". This means, that each transition must execute to its end, before the next transition can be processed.
    This means, that the nextstate symbol of a process is executed, before the next SDL input can be handled. On the other hand, "preemptive scheduling" is useful, if an SDL process must directly execute when an external event from an interrupt source is detected and sent to the SDL system. In this case, an executing transition is possibly suspended, and another transition can be executed.
    The kernel makes decisions based on the defined priority of processes when to schedule to another process. If the receiver of a signal which has been received from the environment (or a process inside the SDL system) has a higher priority than the currently executing process, the new signal is treated immediately.

Initial setting | unset
Automatic set | MAX_PRIO_LEVELS xDefaultPrioProcess XMK_USE_RECEIVER_PID_IN_SIGNAL
Reset | XMK_USE_CHECK_TRANS_TIME

  • MAX_PRIO_LEVELS
    This defines the amount of process priority levels in the SDL system. It is of relevance only, if preemption is selected and must be equal to the lowest process priority plus 1. The lowest priority has the highest value.

Initial value | 1
Depend on | XMK_USE_PREEMPTIVE

Caution!

A run-time error occurs if this definition is wrong. If the error checks are enabled, a check is made by the Cmicro Kernel and the C function ErrorHandler() is called if the check fails.

  • xDefaultPrioProcess
    If there is an SDL process with no process priority assigned to it, this process will be handled with the xDefaultPrioProcess. It is mandatory that the xDefaultPrioProcess is in the range of 0 to (MAX_PRIO_LEVELS -1).

Initial value | 0
Depend on | XMK_USE_PREEMPTIVE

SDL Target Tester

Initialization

  • XMK_ADD_MICRO_TESTER
    This is the main flag to enable or disable the SDL Target Tester. Use this flag if the addition of the SDL Target Tester features is wanted. The following features are selected by this flag:
    • Trace into a file.
    • Trace into a buffer on target side.
    • Trace via a serial interface.
    • the Cmicro Recorder

Initial setting | unset
Automatic set | XMK_USE_MAX_ERR_CHECK
Reset when unset | XMK_ADD_MICRO_COMMAND, XMK_USE_DEBUGGING, XMK_ADD_PROFILE, XMK_ADD_MICRO_ENVIRONMENT, XMK_WAIT_ON_HOST, XMK_ADD_SDLE_TRACE, XMK_ADD_SIGNAL_FILTER, XMK_USE_COMMLINK, XMK_ADD_MICRO_TRACER, XMK_ADD_TEST_OPTIONS, XMK_USE_SIGNAL_TIME_STAMP, XMK_ADD_MICRO_RECORDER

  • XMK_WAIT_ON_HOST
    During the start up of the target executable (see xmk_MicroTesterInit() in the module mk_main.c), the target can wait for the host's run-time configuration. If this is not needed, the XMK_WAIT_ON_HOST flag has to be undefined.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_ADD_PROFILE
    This flag is to be defined if the profiler is to be used. With the profiler, it is possible:
    • to trace the SDL queue concerning it's traffic load,
    • to trace the number of timers which exist in parallel
      (not included in this version of the Cmicro Package).
    • to trace the execution time process transitions
      The profiler can be used independently from the SDL Target Tester functions. By using a debugger the following values may be inspected:
int xmk_max_q_cnt,
representing queue-dimensioning, and
int xmk_act_q_cnt,
representing the maximum traffic load of the queue at any time during the execution.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_USE_DEBUGGING
    If the debugging functions should be included to the target executable, this flag needs to be defined.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_ADD_MICRO_COMMAND
    This flag adds the command interface of the SDL Target Tester (please view 67 The SDL Target Tester).

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_ADD_MICRO_ENVIRONMENT
    To allow the signal exchange with the external environment connected to the SDL Target Tester, this flag needs to be defined.
    The external environment can be a GUI application or a cmdtool for example.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

Trace

Trace Scaling

  • XMK_ADD_MICRO_TRACER
    This flag enables the trace of the SDL execution and trace of system events to any device.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER
Reset when unset | XMK_USE_SIGNAL_TIME_STAMP

  • XMK_ADD_SDLE_TRACE
    This flag enables the trace of SDL symbols in the SDL Editor.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_USE_COMMLINK
    If this flag is defined the trace via the specified communications link is enabled. The trace is handled with the SDL Target Tester's data link layer. See the module mg_dl.c for further information.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_USE_AUTO_MCOD
    Is this flag defined, the host get a further message for the message coder. Depending on this flag the Targeting Expert insert the entry `USE_AUTO_MCOD yes' into the sdtmt.opt file. The entrys LENGTH_, ENDIAN_, and ALIGN_ are ignored. For more information view 67 The SDL Target Tester.

Initial setting
set

  • XMK_ADD_SIGNAL_FILTER
    This flag conditionally compiles the signal filtering mechanism of the SDL Target Tester (please view 67 The SDL Target Tester). With the signal filter, it is possible to specify that some signals should be traced while others are not.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_ADD_TEST_OPTIONS
    By defining this flag the symbol trace of the target can be configured. See function main() in module mk_user.c.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER

  • XMK_USE_SIGNAL_TIME_STAMP
    Defining this flag means that in the header of each signal which is sent via the SDL queue, there is an additional entry "time-stamp". When using the standard Cmicro Library, the Cmicro Kernel sets the time-stamp to NOW, if an SDL signal is inserted into the queue.
    This time-stamp is especially used by the Cmicro Recorder (XMK_ADD_MICRO_RECORDER) in order to enable the replay of an SDL session in simulated real-time.
    In other cases, the user is free to modify the type of time-stamp implementation.

Initial setting | unset
Depend on | XMK_ADD_MICRO_TESTER
Reset when unset | XMK_ADD_REALTIME_PLAY

  • XMK_MAX_PRINT_STRING
    The user can add his own trace messages to the standard trace of the SDL Target Tester. This message will be handled like a string. The maximum size of these strings are defined with XMK_MAX_PRINT_STRING.

Initial value
40

Buffers

  • XMK_MAX_RECEIVE_ENTRIES
    If the ring buffer is used this flag gives the amount of entries for the receiver buffer.

Initial value
20

  • XMK_MAX_RECEIVE_ONE_ENTRY
    This flag gives the size of one entry of the receiver buffer. The message received here are SDL Target Tester commands or the Cmicro Recorder's play data. I.e. as a rule over the thumb a value of 12 + maximum signal parameter size must be given here.

Initial value
100

  • XMK_MAX_SEND_ENTRIES
    When the Cmicro Tracer is used the target executable writes the trace data into a ring buffer (view ml_buf.c). The recommended amount of entries given here depends of the used communications link. I.e. if using a slow communications link like V.24 this amount should be increased.

Initial value
20

  • XMK_MAX_SEND_ONE_ENTRY
    When the Cmicro Tracer is used the target executable writes the trace data into a ring buffer (view ml_buf.c). The size of one entry depends on the SDL system. As a rule over the thumb a value of 12 + maximum signal parameter size must be given here.

Initial value
100

Recorder and Play

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

  • XMK_ADD_MICRO_RECORDER
    This flag adds the functions of the record mode of the Cmicro Recorder (please view 67 The SDL Target Tester).

Initial setting | unset
Depend on | XMK_ADD_MICRO_TRACER
Reset when unset | XMK_ADD_REALTIME_PLAY

  • XMK_ADD_REALTIME_PLAY
    When defining this flag, the replay of a recorded session can be performed in simulated real-time.

Initial setting | unset
Automatic set | XMK_USE_SIGNAL_TIME_STAMP
Depend on | XMK_ADD_MICRO_RECORDER

Support of SDL Constructs

Predefined Sorts

Character Strings

  • XRESTUSEOFCHARSTRING
    This flag must be seen in combination with XNOUSEOFCHARSTRING, which forbids the use of SDL charstrings. If this flag is set, SDL charstrings are only supported in a restricted way. I.e. constant character buffers are used in this implementation.
    As a third possible way XRESTUSEOFCHARSTRING and XNOUSEOFCHARSTRING should both be undefined to enable a full support of SDL charstrings.

Initial setting | set
Reset by | XNOUSEOFCHARSTRING

Caution!

The Cmicro Recorder is not able to handle SDL charstrings within signal parameters.

  • XNOUSEOFCHARSTRING
    The use of SDL charstrings is not possible. This can be selected for systems witch do not use SDL charstrings.

Initial setting | set
Reset by | XRESTUSEOFCHARSTRING

  • XMK_MAX_SDL_CHARSTRING
    This macro gives the maximum length of charstring if XNOUSEOFCHARSTRING is defined.

Initial value
50

Predefined Sorts

  • XNO_LONG_MACROS
    The setting of this flag prevents the use of predefined generators (please view "sctpredg.h, sctpred.h and sctpred.c" ). This can be done to reduce the target's memory size. But must be done for some specific compilers as these are not able to handle long macro definitions. Please view the appropriate compiler section in ml_typ.h ("Adaptation to Compilers" )

Initial setting
set

  • XNOUSEOFREAL
    This flag allows using real values in SDL if it is undefined.

Initial setting
set

Note:

Every multiplication of an integer value with an integer value is mapped to a multiplication of a real value with a real value. This is done because an overflow cannot be detected when using integer values.

ASN.1 Sorts

  • XNOUSEOFASN1
    If this flag is undefined it is allowed to use ASN.1 data types. It is recommended not to use ASN.1 data types if possible, because the functions that are necessary to handle these types occupy much memory.

Initial setting | set
Depend on | XNOUSEOFCHARSTRING

  • XNOUSEOFOCTETBITSTRING
    If this flag is undefined it is allowed the use of ASN.1 data type octetbitstring. It is recommended not to use ASN.1 data types if possible, because the functions that are necessary to handle these types occupy much memory.

Initial setting | set
Depend on | XNOUSEOFASN1

  • XNOUSEOFOBJECTIDENTIFIER
    If this flag is undefined it is allowed the use of ASN.1 data type objectidentifier. It is recommended not to use ASN.1 data types if possible, because the functions that are necessary to handle these types occupy much memory.

Initial setting | set
Depend on | XNOUSEOFASN1

Error Checks

  • XEREALDIV
    If this flag is defined, then a C function is used to perform division of real values, otherwise a C macro is used. The flag should be set for allowing better error checks, but may be unset for optimizing the target program code, as the checks occupy a lot of memory.

Initial setting
set

  • XEINTDIV
    If this flag is defined, then a C function is used to perform division of integer and octet values, otherwise a C macro is used. The flag should be set for allowing better error checks, but may be unset for optimizing the target program code, as the checks occupy a lot of memory.

Initial setting
set

  • XEINDEX
    If this flag is defined, then additional error checks are introduced that check the index of array at each position an array element is accessed. The flag should be set for allowing better error checks, but may be unset for optimizing the target program code, as the checks occupy a lot of memory.

Initial setting
set

  • XEFIXOF
    If this flag is defined, then additional error checks are introduced that check the conversion from real to integer. The flag should be set for allowing better error checks, but may be unset for optimizing the target program code, as the checks occupy a lot of memory.

Initial setting
set

  • XECSOP
    Setting this flag includes an error check for predefined ADT operators, as the checks occupy a lot of memory.

Note:

This flag should be used for testing purposes but uses lots of code size within the target.

Initial setting
set

  • XERANGE
    XTESTF
    These flags define that an SDL syntype is to be checked against its defined range. If the flags are not set, the code to perform this check is left out. The flag should be set for allowing better error checks, but may be unset for optimizing the target program code, as the checks occupy a lot of memory.

Initial setting
set

Size of Variables

  • X_COMPACT_BOOL
    This flag defines that an SDL boolean is translated to unsigned char, when it is set. Otherwise each SDL boolean is translated to integer. Usually this flag should be left set, as it is in the default setting. An exception might become true when a C compiler can handle integer values more efficient than char values.

Initial setting
set

  • X_SHORT_REAL
    When this flag is defined, then each SDL real value is translated to a float in C. If it is not defined, Cmicro assumes SDL real values are C double values. The user must take care that at no place in the SDL system there is a real value used that exceeds the maximum range of the appropriate C type.

Initial setting
set

  • X_LONG_INT
    By defining this switch, the SDL predefined sorts, integer and natural are translated to long, otherwise these are translated to integer. The user must take care that at no place in the SDL system there is a real value used that exceeds the maximum range of the appropriate C type.

Initial setting
unset

Use of Memory

Memory Management

  • XMK_USE_SDL_MEM
    If this flag is defined, then the Cmicro Kernel can use the dynamic memory management functions contained in the ml_mem module (xmk_Malloc(), xmk_Calloc() and xmk_Free()). This is necessary if the compiler in use has no malloc/free or if the user wishes to modify the standard behavior of these functions, i.e. using a best fit, instead of first fit searching algorithm. The user should refer to "Dynamic Memory Allocation Functions - Cmicro" also.

Initial setting | unset
Reset when unset | XMK_USE_memshrink

  • XMK_USE_MIN_BLKSIZE
    By setting this define it is possible to organize the dynamic memory allocation in a similar way as arrays in C. If all the allocated blocks in the memory occupy the same space then no fragmentation problems occur.

Initial setting
unset

  • XMK_USE_memshrink
    If this flag is defined, then the xmk_Memshrink() function of the ml_mem module can be used. This function delivers the opportunity to free the unused space of a memory block that was requested previously with xmk_Malloc() or xmk_Calloc().

Initial setting | unset
Depend on | XMK_USE_SDL_MEM

  • XMK_USE_memset
    If this flag is defined, then the memset() function of the ml_mem module is compiled.

Initial setting
unset

  • XMK_USE_memcpy
    If this flag is defined, then the memcpy() function of the ml_mem module is compiled.

Initial setting
unset

  • XMK_CPU_WORD_SIZE
    For allocating memory the pointer to the end of the allocated memory must be dividable by XMK_CPU_WORD_SIZE. This value is set to 8 as default, but should be decreased to 4, 2 or even 1 if the CPU's layout allows it.

Initial value | 8
Depend on | XMK_USE_SDL_MEM

  • XMK_MEM_MIN_BLKSIZE
    The requested block size is rounded to a value of XMK_MEM_MIN_BLKSIZE, if the XMK_MEM_MIN_BLKSIZE is greater than the requested block size.

Initial value | 64
Depend on | XMK_USE_MIN_BLKSIZE

  • XMK_MAX_MALLOC_SIZE
    If the Cmicro memory functions (xmk_Malloc(), xmk_Calloc() and xmk_Free()) are used, the buffer that is used for dynamic memory allocation is to be initialized with xmk_MemInit(). The size of the buffer can be given here.

Initial value | 1024
Depend on | XMK_USE_SDL_MEM

String Functions

  • XMK_USE_strcpy
    If this flag is defined, then the strcpy() function of the ml_mem module is compiled.

Initial setting
unset

  • XMK_USE_strncpy
    If this flag is defined, then the strncpy() function of the ml_mem module is compiled.

Initial setting
unset

  • XMK_USE_strcmp
    If this flag is defined, then the strcmp() function of the ml_mem module is compiled.

Initial setting
unset

  • XMK_USE_strlen
    If this flag is defined, then the strlen() function of the ml_mem module is compiled.

Initial setting
unset

SDL environment

  • XMK_USE_xInitEnv
    This flag enables the C function xInitEnv() which is generated as a template in file env.c by the Targeting Expert.

Initial setting
set

  • XMK_USE_xInEnv
    This flag enables the C function xInEnv() which is generated as a template in file env.c by the Targeting Expert.

Initial setting
set

  • XMK_USE_xOutEnv
    This flag enables the C function xOutEnv() which is generated as a template in file env.c by the Targeting Expert.

Initial setting
set

  • XMK_USE_xCloseEnv
    This flag enables the C function which is generated as a template in file env.c by the Targeting Expert.

Initial setting
set

  • XMK_USE_SEND_ENV_FUNCTION
    This flag make it possible to use an alternative function to send signals to the environment. This is needed if the used compiler does not support re-entrant functions. The disadvantage of this implementation exists in the missing error checks. See "Alternative Function for sending to the Environment"

Initial setting
unset

  • XMK_ADD_STDIO
    The Cmicro Package is mainly intended for target implementation. However on some occasions the user may wish to use OS features. Normally this flag is undefined when compiling for the target system but may be defined if stdio is available and required on the target system.
    Defining XMK_ADD_STDIO without setting XMK_ADD_PRINTF allows the user to exclude the default printfs of the Cmicro Library and instead implement user defined printfs.

Initial setting | unset
Reset when unset | XMK_ADD_PRINTF

Automatic Scaling Included in Cmicro

The flags described in this section are automatically generated into the file sdl_cfg.h by the Cmicro SDL to C Compiler. The purpose is to exclude parts of the C code in order to reduce the generated code. Features or functions which are not required in the SDL description produce no (or only a small) overhead in the generated code.

If the user does not wish to employ automatic scaling facilities, for example if test and debugging proves too difficult, then simply define the flags XMK_USE_NO_AUTO_SCALING.

All the flags discussed in this section are used on the whole SDL system i.e. it is not possible to define flags for processes separately.

The Targeting Expert will use these flags, too, to optimize and ease the manual scaling.

  • XMK_USED_ONLY_X_1
    If this flag is generated as defined, then there is no process defined in the system, where N is > 1 in the process declaration (x, N). This allows memory to be saved as the overhead for process addressing in the system is reduced. The need for numbering of process instances is also eliminated.
  • XMK_USED_DYNAMIC_CREATE
    If this flag is generated as defined, the SDL system uses the dynamically created process feature of SDL. (It only requires one create-symbol in the SDL system to enable this flag to be set). This of course constitutes a bigger Cmicro Kernel.
  • XMK_USED_DYNAMIC_STOP
    If this flag is generated as defined, the SDL system uses the dynamic process stop feature of SDL. (It only requires one stop-symbol in the SDL system to enable this flag to be set). This of course constitutes a bigger Cmicro Kernel.
  • XMK_USED_SAVE
    If this flag is generated as defined, the SDL system uses the save feature of SDL. Using save means that there has to be additional overhead in each signal stored in the SDL queue (each signal is tagged as save or not save).
    The save construct, although a useful construct for manipulation of the SDL FIFO queue mechanism, unfortunately imposes a large code overhead. The user should avoid the utilization of this construct where possible.
  • XMK_USED_TIMER
    If there is a minimum of one timer declaration in the system, then this flag is generated as defined. If no timer declarations exist in the SDL system, the timer handling functions are excluded.

Note:

It is possible to implement a user defined timer model by un-defining these flags and defining some other macros.

  • XMK_HIGHEST_SIGNAL_NR
    This define gives the amount of signals and timers used in the SDL system in sum. It is used to scale internal buffers of the Cmicro Package.
  • XMK_USED_SIGNAL_WITH_PARAMS
    If no signals with parameters are defined in the SDL system, then this flag is generated as defined which reduces the overall code size.

Note:

It is not recommended in each case (because it is not SDL conform), but is possible to send parameters via global parameters by using C code in SDL.

  • XMK_USED_TIMER_WITH_PARAMS
    This define is generated if there is at least on timer with parameter used in the system. If this is the case, additional functionality for this construct is added when the kernel is compiled. The timer operations will result in producing more overhead, both symbol by symbol and overhead in the kernel compared with the case if there are no timers with parameters defined.
  • XMK_USED_SENDER, XMK_USED_PARENT, XMK_USED_OFFSPRING, XMK_USED_SELF
    The above flags are generated as defined if the user uses the appropriate addressing construct within SDL, that is sender, parent, offspring or self.
    If "to" in output actions is not used, none of the above flags is generated as defined.
    The define XMK_USE_PID_ADDRESSING depends on the above flags.
  • XMK_USED_PWOS
    If procedures without states are contained in the SDL system, this flag is defined. Procedures with states are not supported by the Cmicro Package.

Automatic Dimensioning in Cmicro

Some resources of the Cmicro Library are automatically dimensioned. These are described in the following subsections.

  • MAX_SDL_PROCESS_TYPES
    The Cmicro SDL to C Compiler counts the amount of process types in the system and generates this define. This is used to dimension some tables used in the generated code, the Cmicro Kernel and the SDL Target Tester.
  • MAX_SDL_TIMER_TYPES
    The Cmicro SDL to C Compiler counts the amount of timer types in the system and generates this define. This is used to dimension some tables used in the generated code, the Cmicro Kernel and the SDL Target Tester.
  • MAX_SDL_TIMER_INSTS
    The Cmicro SDL to C Compiler counts the amount of instances of timers in the system and generates this define. This is used to dimension some tables used in the generated code, the Cmicro Kernel and the SDL Target Tester.


Adaptation to Compilers

In this section the steps are explained that must be carried out in order to deal with a new C compiler which is not yet in the list of available compilers.

The following parts may be modified manually:

  • In mk_stim.c, there are template functions as templates which have to be modified to adapt another hardware/compiler to the SDL system time (Now).
  • In mk_cpu.c, there are templates for functions which represent hardware access. Those are required if the preemptive Cmicro Kernel is used.

The following parts can be added by using the Targeting Expert:

  • A compiler specific header file user_cc.h which will automatically be included in ml_typ.h. Please view "Compiler Definition for Compilation" .
  • An entry in the Targeting Expert's configuration files. Please view "Compiler Definition for Compilation" .

List of Available C Compilers in ml_typ.h

C compilers are to be selected by the user by choosing from an available list with the help of the Targeting Expert.

The Targeting Expert will generate a C define into the ml_mcf.h file. When compiling Cmicro sources, the right C compiler section in ml_typ.h is selected by using a #ifdef <compilername> construct.

The following <compilername> defines are currently defined in ml_typ.h:

Compilation switch | Meaning
_GCC_ | The GNU C++ compiler for workstations
GNU80166 | The GNU UNIX C compiler for Siemens 80C166 microcontrollers
TCC80166 | The BSO/Tasking DOS C compiler for Siemens 80C166 microcontrollers
TCC80C196 | The BSO/Tasking DOS C compiler for INTEL 80196 microcontrollers
IARC51 | The Archimedes/IAR UNIX C compiler for INTEL 8051 microcontrollers
IARC6301 | The Archimedes/IAR DOS C compiler for Hitachi 6301 microcontrollers
KEIL_C51 | The Franklin/Keil DOS C compiler for INTEL 8051 microcontrollers
KEIL_C166 | The Franklin/Keil DOS C compiler for Siemens 80166 microcontrollers
TMS320 MSP58C80 | The Texas Instruments DOS C compiler for TMS 320C2x/C5x microcontrollers
IARC7700 | The Archimedes/IAR DOS C compiler for Melps 7700 microcontrollers
HYPERSTONE | Hyperstone 5.07 C compiler with HyRTK real-time kernel
MCC68K | The MicroTech DOS C compiler for Motorola 68k microprocessors
MICROSOFT_C | The Microsoft C++ compiler
BORLAND_C | The Borland C++ compiler
ARM_THUMB | The Thumb compiler for ARM microcontrollers
ICC_HC12 | The ICC12 5.0 Compiler for HC12 microcontrollers

If none of these compiler flags is defined during compilation the file user_cc.h (generated by the Targeting Expert) will be included in ml_typ.h.

The remaining part of the code of the Cmicro Library should be compilable without performing any modifications. If there are problems with adapting a new compiler or hardware please contact Cmicro technical support.

The user may however decide to define his own C compiler. This is explained in the following subsection.

Introducing a new C Compiler

Adding a new C Compiler to the Project

The first alternative to add a new user defined C compiler, is to add that compiler to a user's project. This can be achieved with the Targeting Expert.

  • Give the C compiler a name for using it within Cmicro. The name should as a recommendation be in the notation of C macros, that is, it should be 8 to approximately 16 characters long in uppercase letters.
  • Below the Targeting Expert's Edit menu there is a choice called "Add a new C Compiler" by which the new C compiler can be defined.
  • It is also possible to remove the user defined C compiler later on by using this menu.

These changes are not stored within the Telelogic Tau installation, but within the user's project directory (which is the target directory that was chosen when the Targeting Expert was started).

Do the C Compiler Adaptations

  • Create a new file with the name user_cc.h. If a C compiler is selected, which is not in the list of available C compilers in the Cmicro product, the user_cc.h is included automatically. This can easily be done by using the Targeting Expert's Edit menu "Edit compiler section".
  • Take care that the right path names are specified when the C compiler is invoked. There usually should be something like a "-I." option which must point to the path in which user_cc.h is stored.

Description of user_cc.h

The things that are to be defined by the user are:

  • Is the compiler able to handle function prototypes, as defined in ANSI-C?

Yes

 #undef  XNOPROTO
 #define XPP(x)     x
 #define PROTO(x)   x
No

 #define XNOPROTO
 #define XPP(x)
 #define PROTO(x)

  • Is the controller faster in accessing character values or integer values?

char

 #define xmk_OPT_INT char
integer

 #define xmk_OPT_INT integer

  • Does the compiler support variables stored in registers?

Yes

 #undef  X_REGISTER
 #define X_REGISTER >register<
No

 /* Nothing to do for X_REGISTER */

>register< is the compiler specific command to store variables in registers.
  • Default setting:
    #define xptrint unsigned long
    This setting should work for the very most compilers In a few cases it is necessary to define xptrint as unsigned int.
  • Default setting:
    #define xint32 long
    This setting should work for the very most compilers. In a few cases it is necessary to define xint32 as int.
  • Is the compiler able to handle the C keyword const in the correct way?

Yes

 #define XCONST const
No

 #undef XCONST

In general, the compilers which are able to produce ROM-able code, can handle the keyword const. Compilers may generate false object code, if using const.
  • Is it a UNIX system for which code is to be compiled for?

Yes

 #define XMK_UNIX
No

  • Is it an MS Windows system for which code is to be compiled for?

Yes

 #define XMK_WINDOWS
No

  • Critical paths must be enabled and disabled:
#undef XMK_END_CRITICAL_PATH
#define XMK_END_CRITICAL_PATH \
if (xmk_InterruptsDisabled) \
{\
xmk_InterruptsDisabled--;\
if (!xmk_InterruptsDisabled) \
{ ENABLE; }}

#undef XMK_BEGIN_CRITICAL_PATH
#define XMK_BEGIN_CRITICAL_PATH \
DISABLE;\
xmk_InterruptsDisabled++;
ENABLE and DISABLE are the compiler specific command to allow/prevent interrupts and must be filled.
  • A #include of <stdio.h>, if supported by the compiler (not all the target compilers do). Write:
#ifdef XMK_ADD_STDIO
#include <stdio.h>
#endif

  • Which include header files must be added?
    For example, for the IARC51:
#define "io51.h"
is used. For the GNU80166:
#include <string.h>
#include <stdlib.h>
#include <stdarg.h>
#include <c166.h>
is used.
  • The include header files containing the prototypes for dynamic memory allocation and string and memory functions must be added. This subsection should look like this for allowing the user to select either the memory functions from the C compiler or from Cmicro:
#ifdef XMK_USE_SDL_MEM
#include "ml_mem.h"
#else
#include "string.h"
#endif /* XMK_USE_SDL_MEM */

It must be checked if malloc(), free(), calloc() etc. are really prototyped in string.h, on other compilers it might be stdlib.h. Cmicro always calls xAlloc() and xFree() which are given as examples in the mk_cpu.c file below the template directory. For more information on dynamic memory allocation please view the subsection "Dynamic Memory Allocation" .

Defining the SDL System Time Functions in mk_stim.c

The following functions exist in the module mk_stim.c:

  • void xmk_InitSystime(void)
    Initialize the hardware registers to support the system time
  • void xmk_DeinitSystime(void)
    Give up to use the system time. This normally cannot happen, but in some applications, where the SDL system is stopped and restarted again during run-time, it may prove useful.
  • void xmk_SetTime(xmk_T_TIME)
    This function sets the system-time to the given value. Called by Cmicro Kernel in the case when an overrun in the time value is detected.
  • xmk_T_TIME xmk_NOW(void)
    This is the most important C function to handle SDL system-time. This function returns the absolute time, which is by default defined as a long value (xmk_T_TIME).

Usually, the above functions are conditionally compiled. To make the functions available in the target system, at least one timer in SDL must be declared. The functions are not included if there is no timer declared but duration, time or now is used in SDL. This will lead to compilation errors.

To make timers in SDL operable, absolute time must be implemented. This can be reached by using a hardware free running counter or by using a timer interrupt service routine, which clocks a global variable containing the absolute time.


Bare Integration

This section deals with functions that must be adapted by the user in order to connect the SDL system to the environment i.e. connection to target hardware, and the environment.

Implementation of Main Function

The user may decide to implement his own main() function body when it comes to target application in a bare integration. A default main() function is included in the template file mk_user.c.

The implementation of a first main function looks like this:

Example 571

main ()
{
xmk_InitQueue();
xmk_InitSDL ();
xmk_RunSDL ();
}

Of course this example does nothing in order to start the SDL Target Tester. The only possible way to get a very simple trace output is to define:

#define XMK_ADD_PRINTF

in ml_mcf.h with the help of the Targeting Expert. This will include calls to the C function xmk_printf() at several places in the generated C code and the Cmicro Library. The xmk_printf() function is available as an example in the file mk_cpu.c.

The user can use the main() functions delivered with the Cmicro Kernel to have full access to all Cmicro features. This delivered main() function is a template and can be modified to add or remove functionality.

Integrating Hardware Drivers, Functions and Interrupts

There is no extra handling for hardware drivers, hardware functions and interrupt service routines. It is necessary to implement an interface in the user's application. Hardware drivers, hardware functions and interrupt service routines are seen from the SDL system as the environment. The user has to implement the interface between the SDL system and the environment as it is described in the following subsections.

Critical Paths in the Cmicro Library

As with every real time application the Cmicro Library has to deal with critical paths.

Figure 588 : Critical paths

These are well defined in the source code using two macros namely XMK_BEGIN_CRITICAL_PATH and XMK_END_CRITICAL_PATH (see file ml_typ.h/compilersections).

The macros are expanded to compiler specific calls which disable/enables interrupts. The calls are counted using an internal variable, thus after having called XMK_BEGIN_CRITICAL_PATH n times XMK_END_CRITICAL_PATH has also to be called n times, to enable the interrupts again.

In the Cmicro Library these macros are used to disable/enable interrupts only. The application should take care not to handle interrupts without using these macros or at least evaluating the internal counter.

Caution!

When it comes to implementing the interrupt handling routines it is of the greatest importance to know about the Cmicro Library's handling of critical paths. Unpredictable results may result from a careless implementation!

Initializing the Environment / Interface to the Environment

xInitEnv()

There is one C function called xInitEnv() available as a template in the generated file env.c. The user should fill this module out appropriately, thus implementing connection to the environment (drivers, interrupt service routines and so on).

Receiving Signals from the Environment

There are two possibilities to send signals into the SDL system. In all cases, the user has to specify an SDL input symbol in the process which has to consume the signal. The possibilities are:

  1. Polling external events.
    This is done by the C function xInEnv(), which is called by the Cmicro Kernel after each transition.
  2. Directly sending signals into the SDL system.
    For example directly in an interrupt service routine. This is possible by using the XMK_SEND_ENV() function. This function directly operates on the SDL queue.

Caution!

For each signal sent into the system, the user must ensure that the addressed receiver process instance exists. Each pid value is checked for consistency by the Cmicro Kernel. In the case of an inconsistency the ErrorHandler() is called with an error message.

xInEnv()

Parameters:

In/Out: -no-
Return: -no-

In the case when no interrupt service routine is available to handle an external event, the Cmicro Kernel can poll external events. The user must use the C function xInEnv() in the file env.c generated by the Targeting Expert.

For example, a hardware register can then be checked in order to establish if its value has changed since the last call.

If an external signal is detected, then one of the xmk_Send*() functions is to be called thus enabling the signal to be put into the SDL queue.

Note:

There is a file called <systemname>.ifc, which is generated by the Cmicro SDL to C Compiler. It is necessary to include this file together with ml_typ.h before defining xInEnv(). This is necessary to have access to all the objects that are generated by the Cmicro SDL to C Compiler. The user should also make sure that this file is generated, because the analyzer's make menu contains an option for this.

Example 572 : xInEnv()

Assume, a hardware register where the value 0 is the start-value and where any other value means: data received. Two signals, namely REGISTER_TO_HIGH, and REGISTER_TO_LOW are to be defined in the SDL system, with a process receiving these. Then the user supplied C code should look like this (the <p> below stands for the automatically generated prefix, see the file sdl_cfg.h):

void xInEnv (void)
{
XMK_SEND_TMP_VARS
static state = 0;
/* state, to detect changes in the */
/* hardwareregister */

/* BEGIN User Code */
if ((state==0) && (hw_register != 0))
/* END User Code */
{
XMK_SEND_ENV (REGISTER_TO_HIGH,
xDefaultPrioSignal,
0,
NULL,
/* BEGIN User Code */
GLOBALPID(XPTID_<p>_ReceiverName,0));
state = 1;
/* END User Code */
return;
}

/* BEGIN User Code */
if ((state==1) && (hw_register == 0))
/* END User Code */
{
XMK_SEND_ENV (REGISTER_TO_LOW,
xDefaultPrioSignal,
0,
NULL,
/* BEGIN User Code */
GLOBALPID(XPTID_<p>_ReceiverName,0));
state = 0;
/* END User Code */
return;
}

return;
} /* END OF SAMPLE */

Caution!

The function xInEnv() contained in the file env.c is generated by the Targeting Expert. To make sure that changes done by the user will not be lost when generating again it is allowed to modify this file only between the comments /* BEGIN User Code */ and
/* END User Code */.

Furthermore it is not allowed to remove these comments or to add similar at other places which could especially happen when copy and paste is used during editing.

XMK_SEND_ENV()

Parameters:

In/Out: xPID Env_ID

xmk_T_SIGNAL sig

#ifdef XMK_USE_SIGNAL_PRIORITIES
xmk_T_PRIO prio
#endif

#ifdef XMK_USED_SIGNAL_WITH_PARAMS
xmk_T_MESS_LENGTH data_len,
void xmk_RAM_ptr p_data
#endif

#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xPID Receiver
#endif

Return: -no-

It is possible to send signals directly into the SDL system by calling the C function XMK_SEND_ENV(), no matter whether preemption is used or not. No conflict occurs, if an interrupt service routine uses a XMK_SEND_ENV() function parallel to the C function xInEnv().

This function is to be called when a signal is to be sent into the SDL system, e.g. within the users xOutEnv function. It must be called with one more parameter than the xmk_Send function, which is the first parameter Env_ID. This parameter must be set to ENV by the user.

The macro internally uses some variables which are to be declared before the macro can be used. For example in the xOutEnv function the XMK_SEND_TMP_VARS macro must be introduced for declaring these variables.

The function is implemented as a macro in C.

Use the template in the previous subsection to see details how to use the XMK_SEND_ENV() functions.

Sending Signals to the Environment

There are several possibilities to send signals to the environment:

  1. Using simple SDL output.
    The Cmicro Kernel is involved in the output operation.
  2. Using the #EXTSIG directive in the SDL output.
    The user can define his own output operation, like writing to a register in a single in-line-assembler command.
  3. Using the #ALT directive in the SDL output.
    A variant of alternative 2.

Alternative 1 is the most SDL like alternative because it does not use non SDL constructs, like directives. This alternative should be selected, where possible because it makes the diagrams more SDL like and MSCs more readable.

Alternative 2 and 3 are probably the alternatives with higher performance.

Alternative 1 is described below. Alternative 2 and 3 are already well described in 65 The Cmicro SDL to C Compiler.

xOutEnv()

Parameters:

In/Out:
xmk_T_SIGNAL xmk_TmpSignalID

#ifdef XMK_USE_SIGNAL_PRIORITIES
xmk_T_PRIO xmk_TmpPrio
#endif

#ifdef XMK_USED_SIGNAL_WITH_PARAMS
xmk_T_MESS_LENGTH xmk_TmpDataLength,
void xmk_RAM_ptr xmk_TmpDataPtr
#endif

#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xPID xmk_TmpReceiverPID
#endif

Return: xmk_OPT_INT

The function xOutEnv() exists as a template in the generated module env.c.

Each time an SDL output occurs, the generated C code calls the C function xmk_Send or xmk_SendSimple. After performing some checks, and if the signal is to be sent to the environment, the C function xOutEnv() is called with all the parameters necessary to represent the signal. The parameters are explained in the following.

With the parameter xmk_TmpSignalID, the signal ID is to be specified.

With the xmk_TmpPrio parameter, the signal's priority is to be specified (if conditionally compiled). If the XMK_USE_SIGNAL_PRIORITIES is not defined, the signal priorities which are specified with #PRIO in the diagrams is just ignored. The use of signal priorities is not recommended because this violates SDL. A few bytes can be spared if signal priority is not used. See also XMK_USE_SIGNAL_PRIORITIES.

With the parameter xmk_TmpDataLength, the number of bytes of signal parameters is to be specified. The number of bytes is evaluated by using a sizeof (C struct) construct. If the signal carries no parameters, this value is set to 0.

With the xmk_TmpDataPtr parameter, a pointer to the memory area containing the parameter bytes of the signal is given. The memory area is not treated as dynamically allocated within this function. Because the function copies the parameter bytes, the caller may use any temporary memory (for example memory allocated from the C stack by declaring a C variable). This parameter should be set to NULL if no parameter bytes are to be transferred (if conditionally compiled).

The parameters xmk_TmpDataLength and xmk_TmpDataPtr are compiled conditionally. The XMK_USED_SIGNAL_WITH_PARAMS is automatically generated into the sdl_cfg.h file, from the Cmicro SDL to C Compiler. For tiny systems, if there are no SDL signals with parameters specified, this is undefined. It will reduce the amount of information which is to be transferred for each signal, with a few bytes. See also XMK_USED_SIGNAL_WITH_PARAMS.

With the last parameter xmk_TmpReceiverPID, the PID of the receiving process is to be specified (if conditionally compiled). The parameters xmk_TmpDataLength and xmk_TmpDataPtr are compiled conditionally, see also XMK_USE_RECEIVER_PID_IN_SIGNAL.

If XMK_USE_RECEIVER_PID_IN_SIGNAL is not defined, the user must implement the C function xRouteSignal which is responsible to derive the receiver from the signal ID in that case. Using xRouteSignal is recommended only if the last few bytes must be spared for transferring of signals.

Note:

There is a file called <systemname>.ifc, which is generated by the Cmicro SDL to C Compiler. It is necessary to include this file together with ml_typ.h before defining xOutEnv(). This is necessary to have access to all the objects that are generated by the Cmicro SDL to C Compiler. The user should also make sure that this file is generated, because the analyzer's make menu contains an option for this.

Evaluate the Signals's Sender

The sender of the signal can be retrieved by the global variable xRunPID of type xPID. Users should remember, that in a system with only (x,1) process declarations, this pid represents the process type of the sender. In a system in which multiple process instances of the same process type appear, this pid represents the process type plus the process instance of the sender. Probably it is required to make decisions depending on the sender of the signal. The user can evaluate the process type of the sender by using the C expression EPIDTYPE(xRunPID), i.e.:

Example 573 : Evaluating the Process Type

unsigned char ptype;
ptype = EPIDTYPE(xRunPID);

Remember also, if it is required to signal to a specific pid in the environment, this requires dynamic signalling where a process in the environment establishes communication to a process in the system or the other way around.

Checking the Signal's Receiver

Under normal circumstances it is not necessary to check the receiver in xOutEnv() as the Cmicro Kernel calls xOutEnv() only, if the environment is recognized as the signal's receiver.

Caution!

The users have to ensure that signals to the environment are consumed in the environment by returning XMK_TRUE in xOutEnv().

Signal Parameters

If the signal to be sent to the environment contains parameters, it is necessary to copy these parameters to the data area of the environment as the signal and its parameters are deleted after signal consumption.

For each signal carrying parameters, there is a typedef struct generated into the <systemname>.ifc file. Please view Example 574.

Return Values of xOutEnv()

The user must ensure that signals which are to be sent to the environment are consumed by the environment. In xOutEnv() this is done by returning the values XMK_TRUE or XMK_FALSE.

    • XMK_TRUE
      The signal has been consumed by the environment.
    • XMK_FALSE
      The signal is NOT consumed by the environment.

An Easy Example

Assume, for example, a process which has to send a signal with parameters to the environment. The code the user has to write into the xOutEnv()-function, looks as follows:

Example 574 : xOutEnv()

xmk_OPT_INT xOutEnv (xmk_T_SIGNAL xmk_TmpSignalID,
xmk_T_PRIO xmk_TmpPrio,
xmk_T_MESS_LENGTH xmk_TmpDataLength,
void * xmk_TmpDataPtr,
xPID xmk_TmpReceiverPID )

{
xmk_OPT_INT xmk_TmpResult = XMK_FALSE;

switch (xmk_TmpSignalID)
{
case SDL_Signal1 :
{
/* BEGIN User Code */
int temp;
temp = (yPDef_z4_SDL_Signal1*)xmk_TmpDataPtr->Param1
UserFunction(temp);
/* END User Code */
xmk_TmpResult = XMK_TRUE; /* signal is */
/* consumed */
}
break ;

case SDL_Signal2 :
{
/* BEGIN User Code */
char g;
int k;
g = (yPDef_z5_SDL_Signal2*)xmk_TmpDataPtr->Param1;
k = (yPDef_z5_SDL_Signal2*)xmk_TmpDataPtr->Param2;
UserFunction2( g, k );
/* END User Code */
xmk_TmpResult = XMK_TRUE; /* signal is */
/* consumed */
}
break ;

default :
xmk_TmpResult = XMK_FALSE;/* signal is NOT */
/* consumed */
/* and to be handled */
/* by the Cmicro Kernel */
break ;
}
return( xmk_TmpResult );
}

Caution!

The function xInEnv() contained in the file env.c is generated by the Targeting Expert. To secure that changes done by the user will not be lost when generating again it is allowed only to modify this file between the comments /* BEGIN User Code */ and /* END User Code */.
Furthermore it is not allowed to remove these comments or to add similar ones at other places.

Inter-Processor-Communication

Note:

If inter-processor-communication is to be performed, the user has to define a unique protocol between the communicating processors. In small applications with a restricted range, it might be enough to copy C structures, but usually this causes problems when it comes to redesigning the hardware.

Closing the Environment / the Interface to the Environment

xCloseEnv()

Parameters:

In/Out: -no-
Return: -no-

There is one C function called xCloseEnv() available as a template in the generated C module env.c.

The user should fill this function out appropriately thus realizing disconnection from the environment (drivers, interrupt service routines and so on). Disconnection can make sense if a re-initialization or a software reset is to be implemented.

The SDL_Halt function is mapped to xCloseEnv() in Cmicro.

SDL System Time Implementation

Included in the Cmicro Kernel, there are some template functions for the implementation of SDL system time. All these functions are contained in the module mk_stim. The functions xmk_NOW() or xmk_SetTime() must be implemented newly if a new method for accessing the hardware system time is to be implemented. In many cases, the standard C library function time() is available, which is used in most of the C compiler adaptations that are already been made.

It is necessary though to implement a function which makes the variable SystemTime topical. This will be an interrupt service routine in most cases.

Please view "Defining the SDL System Time Functions in mk_stim.c" .

Getting the Receiver of a Signal - Using xRouteSignal

Parameters:

In/Out: xmk_T_SIGNAL sig
Return: xPID

The user can remove the receiver's xPID from the signal structure by resetting the flag "XMK_USE_RECEIVER_PID_IN_SIGNAL" . In this case, the function xRouteSignal() has to be filled as the Cmicro Kernel needs to know which process likes to receive the current signal.

Example 575 : Function xRouteSignal()

/*
** the <p> below stands for the automatically generated prefix
*/

xPID xRouteSignal ( xmk_T_SIGNAL sig )
{
/*
** Please insert appropriate code here to map
** Signal ID's to Process - Type - ID's
** (XPTID_ProcessName in generated code).
** Keep in mind that this function might be
** called from within a critical path.
** Include <systemname>.ifc to get signal names
** and process' XPTID
*/
switch (sig)
{
/*
** S D L T i m e r s ...
*/
case SDL_Timer1: return (XPTID_<p>_ProcessName_A)
break;
case SDL_Timer2: return (XPTID_<p>_ProcessName_B)
break;
case SDL_Timer3: return (XPTID_<p>_ProcessName_A)
break;
case SDL_TimerN: return (XPTID_<p>_ProcessName_C)
break;

/*
** O r d i n a r y S D L S i g n a l s ...
*/
case SDL_Signal1: return (XPTID_<p>_ProcessName_B)
break;
case SDL_Signal2: return (XPTID_<p>_ProcessName_A)
break;
case SDL_Signal3: return (XPTID_<p>_ProcessName_A)
break;
......

case SDL_SignalN : return (XPTID_<p>_ProcessName_C)
break;

default: ErrorHandler (ERR_N_NO_RCV);
return (xNULLPID)
break;
}
}

Dynamic Memory Allocation

General

Dynamic memory allocation in real life always introduces problems, which are:

  • The memory occupation cannot be evaluated by the user, so that it is impossible to configure the dynamic memory. If all objects are allocated statically and if the memory occupation exceeds the available memory, this results in errors during compilation/linking, or at least a memory map file can be viewed.
  • If dynamic memory allocation is used, then, after the program has executed for a time, usually memory leaks are the result. Memory leaks are fatal because there might be enough memory, but it is even impossible to allocate one more block.
  • If there is no more free dynamic memory available, then it is up to the user to decide how to continue in the program. In any case, the program should be terminated, started again or any similar reaction is to be programmed.

Normally, Cmicro tries to prevent any use of dynamic memory allocation, but there are the following exceptions, in which this is impossible:

  • When a signal with too many parameters is to be sent to another process. See "Signals, Timers and Start-Up Signals" .
  • When an SDL sort is used requiring dynamic memory management, like the charstring sort.
  • If the SDL Target Tester is used, because there is dynamic memory allocation in the start-up phase and for each transmit buffer.

There are at least two possibilities to implement dynamic memory allocation namely:

  • The dynamic memory management from the C Compiler or operating system can be used.
  • The dynamic memory management from Cmicro can be used.

When it comes to targeting, the user decides upon the dynamic memory allocation manager. In the following, the both possibilities are explained.

Dynamic Memory Allocation Functions - Compiler or Operating System

If the C compiler, that the user is using in the target environment, provides dynamic memory allocation functions, it is possible to use these functions. A few steps must be carried out to include the dynamic memory allocation functions of the C compiler or operating system, which are:

  • The user must introduce his own C compiler section, please refer to the subsection "Introducing a new C Compiler" .
  • In the new C compiler section, the correct header files must be introduced with #include. The user should refer to the manuals of the C compiler or operating system.
  • The SDL Target Tester, Cmicro Library and Cmicro Kernel always allocate dynamic memory by using the functions in the file mk_cpu.c.
  • The file mk_cpu.c below the Cmicro template directory must be copied into the user's project directory. Any modifications should be performed on the private copy of mk_cpu.c.
  • The mk_cpu.c file contains two C functions called xAlloc() and xFree(). Within these functions, the user should call the appropriate dynamic memory allocation functions of the C compiler or operating system.

Dynamic Memory Allocation Functions - Cmicro

Below the Cmicro kernel directory there is a C module ml_mem.c that implements a dynamic memory allocator. The C module ml_mem.c can be used for managing memory dynamically for SDL systems, but it is not forbidden to use this module within handwritten C code also.

The module cannot be used if partitioning is to be used. In that case compilation errors will occur. Please refer to "Dynamic Memory Allocation" for an explanation which parts in SDL are to be dynamically allocated. The module provides C functions for initialization, allocation, de-allocation, and getting some information about the current memory status.

There is only one memory pool. The memory pool is to be declared by the user and initialized with the C function xmk_MemInit before the memory pool can be used. Allocations may be performed by calling xmk_Malloc() or xmk_Calloc(). An allocated block is de-allocated again by calling xmk_Free(). So far, the principle behavior is the same as the usual malloc(), calloc() and free() functions from compilers. But the memory pool can probably be cleaned with a Cmicro specific function. There are additional functions which can be used to query the amount of free or occupied space.

Before the memory management functions of Cmicro can be used, a few adaptations are to be made which are explained in the following.

Adaptations That Are to Be Made

Some adaptations are to be made by the user, which are necessary to include the right functions, scale buffers and memory management and take care for general adjusting like alignment of the CPU.

  • For general use of the Cmicro memory management functions the user should set the flag XMK_USE_SDL_MEM in ml_mcf.h with the help of the Targeting Expert. This will make the basic memory allocation functions available. The ml_mem.c module must of course be compiled an linked together with the application.
  • Adjust the alignment that the CPU is using. There is a macro definition in ml_mem.c called CPU_WORD_SIZE. The right setting of this macro is basically important for making the dynamic memory allocation functions do work. With this flag, it is possible to define the word size of the target CPU. The value is predefined in ml_mem.c but it could be the case that the predefined value is inappropriate for the target system. If the CPU_WORD_SIZE value must be redefined, this could be done in ml_mcf.h in the user's section. The predefined value for UNIX compilers is 8, the predefined value for ARM_THUMB C compiler 4, otherwise a default value of 1 (no alignment) is used.
  • Here is a recommendation: The user should use an alignment of 4 (32 Bit) if it is not sure what type of alignment the C compiler / CPU produces. This will work for most cases, but of course probably not if the CPU is 64 Bit CPU. For small systems, this might not be appropriate, because there is an extra overhead of 3 bytes per allocated block. For a CPU like 8051 and derivatives a CPU_WORD_SIZE of 1 is appropriate.
  • It is possible to introduce a minimum block size per each allocated block. This decreases the risk of getting memory leaks after a while because blocks of the same size can be put together again. If the mechanism of a minimum block size is to be used, then the define XMK_USE_MIN_BLKSIZE is to be used. With the define XMK_MEM_MIN_BLKSIZE the user may define the minimum block size per each allocated block. If the XMK_MEM_MIN_BLKSIZE is not defined from the user, a minimum block size of 64 is predefined.
  • The ml_mem.c module contains profiler that keeps track on how many blocks are allocated, how much memory is free and furthermore. The user must define XMK_ADD_PROFILE in order to get the complete functionality. If the SDL Target Tester is used, the flag is automatically predefined.

xmk_CleanPool()

Parameters:

In/Out: -no-
Return: size_t

This C function returns the amount of occupied memory. It is available only if XMK_USE_SDL_MEM and XMK_SYSTEM_INFO are set.

xmk_GetOccupiedMem()

Parameters:

In/Out: -no-
Return: size_t

This C function returns the net amount of occupied memory. It is available only if XMK_USE_SDL_MEM and XMK_SYSTEM_INFO are set.

xmk_GetFreeMem()

Parameters:

In/Out: -no-
Return: size_t

Returns the amount of free memory in sum, which means that the overhead from each block is included. It is available only if XMK_USE_SDL_MEM and XMK_SYSTEM_INFO are set.

xmk_EvaluateExp2Size()

Parameters:

In/Out: size_t
Return: size_t

This function is either used from Cmicro's dynamic memory allocation functions xmk_Malloc() and xmk_Calloc() or it may be used directly from the user.

It is available only if XMK_USE_MIN_BLKSIZE is set.

The function is declared as:

size_t xmk_EvaluateExp2Size ( size_t GivenLength )

The function evaluates from the given length a length value, which is in any case a 2 exp N value. This is used to reduce the risk of memory leaks that occur in dynamic memory management systems. It may be used for the memory functions of this module but also for the memory functions of an operating system or C compiler. If the minimum block size is in any case greater than the greatest block that is requested in the target system, then there is no risk for memory leaks. The return result is either the minimum specified with XMK_MEM_MIN_BLKSIZE, but might be also one of the following values:

64,128,256,512,1024,2048,4096,8192,16384,32768,65536

The ?Memory Command

The SDL Target Tester offers a command that allows the user to inspect the status of the dynamic memory. Unfortunately this command can be used only, if the dynamic memory management from Cmicro is used (by setting the XMK_USE_SDL_MEM flag in the Targeting Expert).

The command allows the user to check the following:

  • Is the dynamic memory correctly initialized after system start-up?
  • How is the dynamic memory pool configured?
  • At any time during SDL target system execution:
    • what was the greatest block that was allocated?
    • how many blocks are currently in the pool?
    • what is the maximum amount of blocks that have ever been in the pool?
    • physical address of the memory pool (the address of the
    • first block of structure xmk_T_MBLOCK (see ml_mem.c)

The command presents the following output to the user:

M-STATE:Memory pool size incl.overhead =4096
M-STATE:Current memory fill =136
M-STATE:Current amount of blocks in pool =2
M-STATE:Peak hold: Amount of blocks =29
M-STATE:Peak hold: Largest block =2048
M-STATE:Overhead per block (in bytes) =20
M-STATE:Minimum block size =0
M-STATE:Memory pool address (hex) =28478
M-STATE:(Probably there are memory leaks)

The command is available only if XMK_USE_SDL_MEM and XMK_ADD_PROFILE are set.

User Defined Actions for System Errors - the ErrorHandler

Parameters:

In/Out: int ErrorNo
Return: void

Errors, warnings and information can be generated and detected in many places and situations during the lifetime of an SDL system. By fully utilizing the Analyzer, several dynamic error sources can be eliminated at the design stage of development.

Some errors or warnings go undetected by the Analyzer, for example resource errors or real time errors such as memory, performance, or illogical use of SDL.

These errors and warnings are detectable by the Cmicro Kernel and the SDL Target Tester. For a complete list of errors, warnings and information, please view the following subsection "List of Dynamic Errors and Warnings" .

As a general rule, for each error and warning there should be an appropriate reaction in the function ErrorHandler() in the mk_user module.

The ErrorHandler() is, as a default implementation, implemented like this:

In the case of a warning message, either:

  • The actions defined via the flag XMK_WARN_ACTION_HANG_UP are carried out (see "Reactions on Warnings" ).
  • The actions defined via the flag XMK_WARN_ACTION_PRINTF are carried out.
  • The actions defined via the flag XMK_WARN_ACTION_USER and XMK_WARN_USER_FUNCTION are carried out.

In the case of an error message, either:

  • The actions defined via the flag XMK_ERR_ACTION_HANG_UP are carried out (see "Reaction on Errors" )
  • The actions defined via the flag XMK_ERR_ACTION_PRINTF are carried out.
  • The actions defined via the flag XMK_ERR_ACTION_USER and XMK_ERR_USER_FUNCTION are carried out.

For more explanations on these flags, please view "Reactions on Warnings" and "Reaction on Errors" . If printf is used, the C module ml_mon.c below the cmicro/kernel directory must be compiled also.

Errors are numbered easily by an integer value. If the user's target allows the use of printf, then use the C function xmk_err_text contained in the ml_err module. It is easier to specify error handling in this module rather than directly modifying the ErrorHandler function.

Example 576 : Default implementation of ErrorHandler()

void ErrorHandler ( int ErrorNo )
{
...
...
...

ErrorClass = xmk_GetErrorClass (xmk_TmpErrorNumber);
#ifdef XMK_WARN_ACTION_HANGUP
if (ErrorClass==XMK_WARNING_CLASS)
while (1);
#endif /* ... XMK_WARN_ACTION_HANGUP */

#ifdef XMK_ERR_ACTION_HANGUP
if (ErrorClass==XMK_FATAL_CLASS)
while (1);
#endif /* ... XMK_ERR_ACTION_HANGUP */

#ifdef XMK_WARN_ACTION_PRINTF
if (ErrorClass==XMK_WARNING_CLASS)
xmk_MonError (stderr, xmk_TmpErrorNumber);
#endif /* ... XMK_WARN_ACTION_HANGUP */

#ifdef XMK_ERR_ACTION_PRINTF
if (ErrorClass==XMK_FATAL_CLASS)
xmk_MonError (stderr, xmk_TmpErrorNumber);
#endif /* ... XMK_ERR_ACTION_HANGUP */

#ifdef XMK_WARN_ACTION_USER
if (ErrorClass==XMK_WARNING_CLASS)
XMK_WARN_USER_FUNCTION( xmk_TmpErrorNumber );
#endif /* ... XMK_WARN_ACTION_USER */

#ifdef XMK_ERR_ACTION_USER
if (ErrorClass==XMK_FATAL_CLASS)
XMK_ERR_USER_FUNCTION( xmk_TmpErrorNumber );
#endif /* ... XMK_ERR_ACTION_USER */

...
...
...

} /* END OF SAMPLE */

Example 577 : ErrorHandler()

void ErrorHandler ( int ErrorNo )
{
/* The user could implement the 3 functions
** fatalerror, warning, and information
*/
switch (ErrNo)
{
case ERR_N_UNKNOWN
fatalerror(ErrNo);
break;

case .....
.....
break;

default: warning(ERR_N_UNKNOWN); break;
}
} /* END OF SAMPLE */

List of Dynamic Errors and Warnings

Cmicro Kernel Errors

  • ERR_N_CREATE_NO_MEM
    This error can happen in the case of using dynamic process creation. When a parent process tries to create another process, the Cmicro Kernel tries to allocate an entry in the queue for the insertion of an internal create signal.
    The error occurs when full queue capacity has been reached.
    Help: Change the size of the signal queue by modifying the macro XMK_MAX_SIGNALS in ml_mcf.h.
  • ERR_N_CREATE_INSTANCE
    This error happens if there is no dormant instance of a process type which can be (re)used. The Cmicro Package uses fixed upper process instance limits (x, N), where N is to be specified as an integer value. In the C code, all the data of one process instance is represented by one element of an array of the size N.
    The error occurs if all instances (i.e. all array elements), of this process type are currently active and the parent tries to create another instance of that type.
  • ERR_N_SDL_DISCARD
    A signal was sent to a process not existing (either not yet created or already stopped). The signal is therefore discarded.
  • ERR_N_DIVIDE_BY_ZERO
    A division by zero has been detected in the generated SDL code, which is an SDL user error. Possibly, it is helpful to produce an execution trace to localize the error. Normally, it is possible to find such problems within the simulation.
  • ERR_N_NO_FREE_SIGNAL
    It is impossible to allocate one more signal instance from the static memory pool. Depending on how the user has defined the signal handling (XMK_USE_STATIC_QUEUE_ONLY and XMK_USE_STATIC_AND_DYNAMIC_QUEUE), this must be treated either as a warning or as a fatal error.
    It has to be treated as a fatal error, when the macro XMK_USE_STATIC_QUEUE_ONLY is set.
    It can be treated as a minor warning, when the macro XMK_USE_STATIC_AND_DYNAMIC_QUEUE is set.
    The output operation fails, if it is impossible to allocate one more signal.
    Help: Change the size of the signal queue by modifying the macro XMK_MAX_SIGNALS in ml_mcf.h or change the size of predefined dynamic memory pool (the memory pool, that is used when the xAlloc C function is called).
  • ERR_N_PARAMETER_MEM_ALLOC
    The output operation fails as a signal with parameters is to be sent but not enough free memory is available for allocation of the signal parameters.
    If the signal parameter's length is greater than the value of XMK_MSG_BORDER_LEN (see "Compilation Flags" ) the parameters are inserted in a memory area which has to be allocated. This allocation fails because there is no more memory available.
    Help: If using the Cmicro Library's memory functions (flag XMK_USE_SDL_MEM): The size of the memory for allocation can be increased by incrementing the value XMK_MAX_MALLOC_SIZE .
  • ERR_N_SYSTEM_SIGNAL
    This error can only happen, if a non specified system signal is sent. Internally, some signals are predefined as system signals. System signals are given priority treatment. For example, for the dynamic process creation, there is a system signal called XMK_CREATE_SIGNALID which is automatically defined in ml_mcf.h according to the setting of XMK_USE_MORE_THAN_250_SIGNALS.
    To prevent this error situation happening it is strongly recommended not to send an SDL signal with equal or higher priority than that of a system signal (please see the subsection "Scheduling" ).
  • ERR_N_NO_CONT_PRIO
    This error occurs when process priorities are not numbered according to the rules of the preemptive Cmicro Kernel. The numbering must begin from zero incremented consecutively to an upper limit. All numbers between zero and the upper limit-1 are to be used within a #PRIO directive, no number may be omitted. (See MAX_PRIO_LEVELS and xDefaultPrioProcess in section "Preemption" .
  • ERR_N_NO_COR_PRIO
    When the preemptive Cmicro Kernel is selected, the macro MAX_PRIO_LEVELS has to be set correct. As described in MAX_PRIO_LEVELS in section "Preemption" , this macro has to contain the amount of process priority levels.
  • ERR_N_xRouteSignal
    The function xRouteSignal, which is to be filled by the user when signals do not contain a receiver pid, detects an error or was not able to handle the current signal which is to be routed. See "Bare Integration" .
  • ERR_N_NO_REC_AVAIL
    If the user is using implicit addressing (output without to) and there are several possible receivers of one type, the Cmicro Kernel tries to assign one of them to this signal. This assignment may fail if there is no possible receiver. If there is more than one, then the first one found will be used in the output of the C function xmk_Send*.
  • ERR_N_NO_FREE_TIMER
    The error occurs when an SDL process tries to start an instance of a timer and either the timer is unknown or there is no memory available to start a timer instance. To eliminate the first source of error check the SDL compilation. For the second case increase the memory assigned to timers by increasing the value of XMK_TIMERPRIO.
  • ERR_N_PID_INDEX
    The Cmicro Kernel uses PIds as index values. Each SDL process in the generated system is numbered by a system-wide unique number. There is an error detected when the index is out of range. This problem most probably lies in the environment which tries to send a signal to a non existing process.
  • ERR_N_SEND_TO_NULLPID
    An SDL application tries to send to a NULL - PID. This case normally cannot arise as the Analyzer performs appropriate checks in the dynamic analyses pass. If it occurs, it is most probably that either something is wrong with the environment signalling or possibly with initialization of pid variables.
  • ERR_N_TRANS_TIME
    The maximum execution time for one SDL transition was exceeded. This error can only happen if no preemption is used and if the administration of the transition-execution-time is switched on. See "XMK_USE_CHECK_TRANS_TIME" .
  • ERR_N_xOutEnv
    The C function xOutEnv() does not handle all necessary signals. It should handle all signals which are sent to the environment. Please view "Return Values of xOutEnv()" .
  • ERR_N_INIT_SDL_MEM
    If the Cmicro Library's memory functions are used, (XMK_USE_SDL_MEM is defined) the memory for alloc() and malloc() has to be initialized. This error occurs if a malloc() takes place before the memory is initialized. See "ml_mem.c"
  • ERR_N_SDL_DECISION_ELSE
    An SDL decision without any ELSE branch leads to a fatal error.
  • ERR_N_SDL_RANGE
    The index of an SDL array has crossed the range of the SDL array. The definition of the array has to be checked within SDL.
  • ERR_N_NO_RCV
    If the flag XMK_USE_RECEIVER_PID_IN_SIGNAL is undefined the function xRouteSignal() has to be filled by the user. See "Getting the Receiver of a Signal - Using xRouteSignal" . This error code means that there is no receiver defined for the current signal.
  • ERR_N_SDL_IMPLICIT_CONSUMPTION
    The receiver process is not expecting the current signal in his current state, so the signal was implicitly consumed.
  • ERR_N_PREDEFINED_OPERATOR_CALL
    An error occurred in the call to one of the predefined operators. Unfortunately it is not possible to find out what the reason for this error is without either simulating the system or using the SDL Target Tester or any trace possibility introduced by the user. The error message occurs if a range in the memory is crossed.
  • ERR_N_INIT_QUEUE
    The SDL signal queue is not correctly initialized. The error occurs if the user has forgotten to call the C function xmk_InitQueue(). This function must be called before xmk_InitSDL() may be called.
    Please view the section "Implementation of Main Function" .
  • ERR_N_MEM_PARAM
    This error occurs if the user tries to call to the xmk_Malloc() C function with a wrong parameter. It is not allowed to request a memory block of the size 0.
  • ERR_N_MEM_NO_FREE
    There is no free block in the memory pool of the Cmicro Memory Management (see "Exported from ml_mem.c" ). This error can only be detected if the Cmicro Memory Management is used (see the flag "XMK_USE_SDL_MEM" ).
    The size of the dynamic memory, i.e. the amount of blocks available can be modified by modifying the flag XMK_MAX_MALLOC_SIZE
  • ERR_N_MEM_ILLMBLOCK
    A call to the xmk_Free() function of the Cmicro Memory Management (see the file "Exported from ml_mem.c" ) occurred and the given block is an invalid block.
    This error can only be detected if the Cmicro Memory Management is used (see the flag "XMK_USE_SDL_MEM" ).
  • ERR_N_NO_FREE_SIGNAL_DYN
    This error is detected when a new signal is to be allocated dynamically and there is no more free memory available. The Cmicro Kernel starts to create signal instances by using memory allocation in the case that the define XMK_USE_STATIC_AND_DYNAMIC_QUEUE is defined and there is no available signal instance in the predefined pool of static signal instances (see XMK_MAX_SIGNALS).
  • ERR_N_NO_FREE_TIMER_DYN
    This error is detected when memory for a new timer instance is to be allocated dynamically and there is no more free memory available. The error only occurs if timers with parameters are used. The Cmicro Kernel starts to create timer instances by using memory allocation in the case that timers with parameters are used in SDL (XMK_USED_TIMER_WITH_PARAMS is defined in sdl_cfg.h) and the amount of statically predefined timer instances (XMK_MAX_TIMER_USER defined with Targeting Expert) is being reached.
  • ERR_N_NULL_POINTER_VALUE_USED
    This error occurs within the macros that are generated in order to check null pointer access. These error checks are generated for variables of sort ref, own and oref. If the error occurs, the further behavior of the SDL system is unpredictable.
  • ERR_N_UNDEFINED_ERROR
    This error message is implemented to serve the C switch statement in use with a default branch. It should not occur during system execution.

SDL Target Tester Errors

  • ERR_N_INDEX_SIGNAL
    Under normal circumstances this error should not occur. It is an error detected by the SDL Target Tester when a signal id is out of range. This is only used if signal trace options are modified or asked for.
  • ERR_N_ILLEGAL_CMD
    An illegal command was sent to the SDL Target Tester command interface module. This error situation arises due to careless implementation of the function interface and should not occur under normal circumstances.
  • ERR_N_TESTER_MESSAGE
    An illegal message was sent to the SDL Target Tester and it is not able to decode the message. A possible error source is an inconsistency in the underlaying protocol on the communications interface.
  • ERR_N_LINK_SYNC
    It was not possible to receive the sync byte of the data link frame of the Cmicro Protocol.
  • ERR_N_LINK_DEST_BUFFER
    A message which is to be decoded is too large for the destination buffer. Possible error sources are an inconsistency in the data definition or the length of information received is wrong.
  • ERR_N_LINK_ENC_LENGTH
    An attempt was made to send more than the allowed maximum amount of bytes.
  • ERR_N_LINK_ENC_MEMORY
    There is not enough, or no free memory to encode a data link frame of the Cmicro Protocol.
  • ERR_N_LINK_NOT_IMPL
    A feature of the data link which is not implemented has been used, for example an attempt to send more than the maximum amount of allowed bytes.
  • ERR_N_DATA_LINK
    There is an error on the data link detected.
  • ERR_N_DECODE_METHOD
    There is no decoding method defined for a given frame of the Cmicro Protocol.
  • ERR_N_RING_WRITE_LENGTH
    There is a ring buffer overflow detected in the data link module.
  • ERR_N_TRACE_OUTPUT
    The signal parameter length is greater than the size which can be transmitted.
  • ERR_N_RECORD_OUTPUT
    The signal parameter length is greater than the size which can be transmitted.
  • ERR_N_RECORD_MAX_EXCEEDED
    The debit counter used for the SDL Target Tester's record is overflown.
  • ERR_N_RECORD_STATE
    The received message cannot be handled in the current recorder state.
  • ERR_N_RECORD_CANNOT_CONT
    Because a fatal system error is detected the record session cannot be continued.


Light Integration

A light integration is to be performed if the SDL system including the Cmicro Library should execute within just one operating system task.

The SDL system usually communicates with the environment by using a mailbox or message queue or something similar, which is provided from the operating system. Within the SDL system, the Cmicro scheduler is used. This means that signals that are sent internally in the SDL system are not sent via the mailbox/message queue from the operating system.

Model

The execution model for an SDL system in a light integration can be sketched with the following meta code:

/* In the user's initialization task do : */
Initialize memory
Initialize time
Initialize mailbox(es) or message queue(s)
Initialize other resources
Make the SDLTask an operating system task
Wait until the SDLTask has finished initialization
Continue with creating other operating system tasks

The model for what the SDL task does in a light integration can be sketched with something like:

Initialize SDL Target Tester
Initialize Cmicro SDL queue
Initialize Cmicro Trace options (if wanted)
Initialize SDL and execute start transitions of the process instances which are to be created statically

Forever do
{
if there is a signal to be consumed
{
Get the next message from the OS queue,
without suspending the SDL Task
}
else, if there are only saved signals
{
evaluate the remaining duration for the
timer that will expire next

if there is at least one active timer
{
listen on the operating system queue for the
remaining duration, by using a blocking
function call
}
else
{
listen forever to the operating system queue
by using a blocking function call
}
If a message was received, format the message
and send it as an SDL signal to the SDL system
}
If a timeout occured (remaining duration),
then check all the timers. For each timer that
has been expired there will be one signal
put into the SDL queue

process SDL signal
}

Procedure to Implement the Model

This subsection gives the user the details that he must know for the implementation of the given model. He has to deal with some special macros which must be defined and used. Their names have the prefix XLI_.

The user must execute the following steps:

  1. Create the module with the C main() function.

This module has to contain the C main() function, corresponding to the first meta code in the section before. The module should include ml_typ.h and the interface file (e.g component.ifc). In this module the definitions of other external tasks can take place. The main function should handle the following steps:

  • initialize the memory if required
  • initialize the hardware timer
  • initialize OS resources (semaphore, message queues,...)
  • start the necessary OS tasks, this means also to start the task which represents the SDL state machine.
  • wait until all tasks are started
  • Set XLI_LIGHT_INTEGRATION

To set this flag the Targeting Expert can be used. Choose your integration and choose "Support light integration" below Target Library and kernel tab. When the box is chosen three things will happen.

  • the compiler flag XLI_LIGHT_INTEGRATION will be set
  • the compiler flag XMK_USE_INTERNAL_QUEUE_HANDLING is automatically set
  • The macro XLI_INCLUDE is set with the name in the edit line (default is 'li_os_def.h')

This header file is included in ml_typ.h and must contain a definition of XLI_SDL_TASK_FUNCTION. With the help of this macro, the main function known from the standard Cmicro kernel will be mapped to the OS task function. The body of this function is located in mk_user.c.

  3. Define the macros which are needed in the task function.

The task function is corresponding to the second meta code of the model. The following macros can be defined in the header file:

  • XLI_TEMP_TASK_VARS

If temporary variables are needed in the task function, they can be declared at this place. It is inserted at the top of the task function.

  • XLI_TEMP_QUEUE_VARS

If temporary variables for the communication resources are needed, they can be defined within this macro. It is expanded at the top of the function which queries the queue.

  • XLI_OS_TASK_INIT

Any preparations in the task function can be done with this. It follows XLI_TEMP_TASK_VARS at the start of the task function.

  • XLI_CREATE_OS_QUEUE

Here the communication resources for the OS task can be created (which ones that will be used depends on the user and the used OS). In the further part of the document the term queue will be used instead of communication resources.

  • XLI_START_OS_TASK_SYNC

If a synchronization between the OS tasks is needed, this should be defined with XLI_START_OS_TASK_SYNC.

  • XLI_GET_NEXT_MESSAGE_FROM_OS_QUEUE

The function xmk_RunSDL() represents the continuous repeating part of the meta model. Inside of it xmk_QueryOSQueue() is called and it is responsible for the query of the OS queue. If the SDL queue contains signals, XLI_GET_NEXT_MESSAGE_FROM_OS_QUEUE is used to read nonblocking from the OS queue. The task function should not be suspended.

  • XLI_LISTEN_ON_OS_QUEUE_WITH_TIMEOUT(TIMEOUT)

If the SDL queue is empty, but at least one timer is active, XLI_LISTEN_ON_OS_QUEUE_WITH_TIMEOUT(TIMEOUT) is used to read from the OS queue with a time-out. The OS queue should be queried as long as the next timer expire. The duration is given with the parameter TIMEOUT.

  • XLI_LISTEN_ON_OS_QUEUE_NO_TIMEOUT

If there is no signal in the SDL queue and there is no timer active XLI_LISTEN_ON_OS_QUEUE_NO_TIMEOUT is used to query the OS queue while the next OS message arrives. The SDL task should be suspended.

  • XLI_CALL_xInEnv

The content of XLI_CALL_xInEnv is executed after an OS message arrives. It should pass on the content of the received OS message (a signal with parameter) to the SDL system. Normally xInEnv is called to send the signal to the SDL system. The user has to define a data structure which transports the signals from the OS to the SDL system. The name for the data structure can be assigned with XMK_xInEnv_PARTYPE. The name for the parameter of xInEnv can be assigned with XMK_xInEnv_PARNAME.

  • XLI_END_OS_TASK_SYNC

This can be defined with something that sign up the other non-SDL tasks about ending of the SDL task.

  4. Initialize the environment.

This is usually done in xInitEnv(), but probably outside SDL, depending on the needs of the user.

  5. Adaptions for sending signals from the SDL task to any other OS task.

Usually, users must fill out the function xOutEnv() for sending signals to the environment (another operating system task). It is up to the user what kind of communication is to be used in this direction.

Note:

All necessary resources, e.g. the receivers queue, must have been created before they are used.

  6. Adaptions for receiving signals from any other OS task and translation of the signal parameters.

In the SDL task, it is necessary to format the incoming parameters after the message was read from the message queue. Afterwards the signal can be sent to the SDL system with XMK_SEND_ENV.

Note:

All necessary resources must have been created before they are used.

  7. Implement timers in SDL.

It should be possible to implement hardware timers, like it is described in "Defining the SDL System Time Functions in mk_stim.c" . A usual way is to increment a global variable (of type xmk_T_TIME) by using an operating system task or similar. A time overrun is automatically detected by the Cmicro Kernel.

  8. System shutdown.

There is no default way to shutdown, but usually it is enough to implement the xCloseEnv function and call it at an appropriate place.

  9. Cmicro Target Tester

The next thing that is remaining is the SDL Target Tester. The instructions which have been given for bare integration, are still valid. The easiest way to use the SDL Target Tester in a light integration is to dedicate a communication interface exclusively for the SDL Target Tester.

Note:

The Target Tester can only used for tracing.

  10. Compile and link

The added files must be registered as source files in the Targeting Expert. Please view "Source Files" to get information on how to add more files to the list of files to be compiled. The Targeting Expert will automatically add these files to the makefile.

  11. Save the settings and press Full Make.


File Structure

Description of Files

The Cmicro Library Functions and Definitions

sdl_cfg.h

This file is automatically generated by the Cmicro SDL to C Compiler into the directory which is currently active. It contains compilation flags used for the automatic scaling of the Cmicro Library and the generated C code. The file must not be edited by the user.

Caution!

The file sdl_cfg.h always carries the same name, for each SDL system generated and is stored in the currently active directory (project or working directory). Inconsistencies arise if several systems are to be generated in the same directory. To avoid this situation, it is recommended to use different working directories for each SDL system. Otherwise, unpredictable results at run-time could result, as some required automatic scalable features may/may not have been compiled.

ml_typ.h

This file is the central header file in the Cmicro Package. It contains

  • more #includes
  • defines, which are of global interest and Cmicro Library internal defines
  • typedefs which are of global interest and Cmicro Library internal typedefs
  • external declarations which are of global interest and Cmicro Library internal external declarations

sctpredg.h, sctpred.h and sctpred.c

These files contain all definitions necessary to handle SDL data, for example predefined sorts. sctpred.h is included in ml_typ.h.

ml_err.h

This header file defines all error numbers used by the Cmicro Kernel, the Cmicro Library and the SDL Target Tester.

ml_mem.c

This file contains the dynamic memory management functions from Cmicro. It contains among other functions the C functions xmk_Malloc(), xmk_Calloc() and xmk_Free(). Possible reasons to use this module are:

  • Compiler does not support dynamic memory management.
  • Dynamic memory management of the compiler does not meet the requirements of the application. This may be the case, if the user wants to use "best fit" instead of "first fit", the first of which is normally not supported. It is possible to adapt the memory management to ones needs.
  • User wants to use other mechanisms of ml_mem.c, like profiling. Please view "Dynamic Memory Allocation" .

ml_mon.inc

This file is included by the ml_mon.c file. It exists only for internal purposes and in order to maintain all the defined errors in the system in a better way.

ml_mon.c

This file contains some help functions which are useful in producing screen outputs. It contains C functions for buffer printouts, SDL PId printouts, displaying error messages, and the display of the current scalings used in the executable. The file should usually be included when compiling the kernel.

ml_*.h

Other header files which contain extern declarations of modules of the Cmicro Library.

The Cmicro Kernel

mk_main.c

This file represents the main-interface to the SDL user. It contains functions which are to be called by the SDL user to integrate the Cmicro Kernel in his application.

  • an SDL initialization function xmk_InitSDL()
  • an SDL system execution function xmk_RunSDL()

For SDL Target Tester, there are some more functions to be called during initialization. Please view 67 The SDL Target Tester.

Note:

The SDL queue must in any case be initialized before the SDL system is going to execute. The initialization function is called xmk_InitQueue() and is exported from the mk_queu.c module.

mk_user.c

This module is not in the Kernel directory, but in the Template directory. It contains function templates or examples which are to be filled out by the user:

main()

The C main function contains by default the full access to all Cmicro features.

ErrorHandler()

Central error handling routine is called each time an errors occurs.

WatchdogTrigger()

Handling of a hardware watchdog.

In earlier versions of the Cmicro Package the functions xInitEnv(), xInEnv(), xOutEnv() and xCloseEnv() were include in mk_user.c, too. These functions will now be generated by the Targeting Expert and stored in the file env.c.

mk_sche.c

This file is the heart of the Cmicro Kernel. It exports those functions which are used in the mk_main module and it uses those functions of other modules which represent the SDL model. The module serves with all the different scheduling policies described later in the subsection "Scheduling" .

mk_outp.c

This file contains the SDL operation OUTPUT which is represented by a few functions. There is a C function xmk_Send() representing the SDL output operation. In addition, there is a C function xmk_SendSimple() which is used when a signal contains no parameters and has no explicitly defined priority. This results in a more compact argument list thus reducing the generated C Code.

mk_queu.c

This module contains the data type "SDL queue" and defines all operations on the SDL queue. The queue handling covers all the aspects of the SDL semantics as far as signals are concerned. There is one function xmk_InitQueue() which must be called in the user's main() function before the SDL system is going to execute.

mk_tim1.c

This file contains the SDL operations on timers such as set, reset, active, and some help functions used by the Cmicro Kernel. The timer model is described within the subsection "Timers and Operations on Timers" . The Cmicro Kernel has to initialize all timers, test for expired timers and reset all timers of a process, when a process instance stops.

mk_stim.c

This file contains some functions which are to be filled up by the user. This is the reason why it is in the Template directory. The functions are used by the Cmicro Kernel to get the system time used in SDL. The contents of this file should be seen as a template. No provision for the connection to hardware timers is provided in the delivered source, as the timer used is application dependent. The user is required to fill out the appropriate functions for the provision of SDL system time. Please view "Defining the SDL System Time Functions in mk_stim.c"

mk_cpu.c

This file also contains some hardware specific functions which should be seen as templates. It is also in the Template directory.

mk_*.h

Other header files contain extern declarations of modules of the Cmicro Library. The contents and details of the various header files only need to be known if the user wishes to modify parts of the Cmicro Library.


Functions of the Basic Cmicro Kernel

The list in the following section gives an overview of the functions exported by each module of the Cmicro Library in order to understand the module structure. The functions declared as static are not considered here.

If there is a reference to xmk_RAM_ptr, this can be replaced with a * (star) usually. This means that for example the declaration

xmk_T_CMD_QUERY_QUEUE_CNF xmk_RAM_ptr qinfo

can be replaced with

xmk_T_CMD_QUERY_QUEUE_CNF *qinfo

which means to refer to a pointer to an object of the type xmk_T_CMD_QUERY_QUEUE_CNF.

Exported from env.c

xInitEnv

Parameters:

In/Out: -no-
Return: -no-

This function is called by the Cmicro Kernel during initialization of the
SDL system. The user may include initialization of the environment here.

xInEnv

Parameters:

In/Out: -no-
Return: -no-

This function is called by the Cmicro Kernel continuously to retrieve signals polled from the environment. Use the Cmicro Kernel function xmk_Send* to put signals into the system. The use of this function is not absolutely necessary in the case where the Cmicro Kernel is scaled to preemption and all external Events are put into the SDL system via an Interrupt Service Routines.

xOutEnv

Parameters:

In/Out: xmk_T_SIGNAL sig,
xmk_T_PRIO prio,
unsigned char data_len,
void *p_data,
xPID Receiver

Return: xmk_OPT_INT

This function is called by the Cmicro Kernel if an SDL signal is to be sent to the environment.

Note:

The user has several possibilities to send signals to the environment. Please refer to the subsection about the "Functions of the Expanded Cmicro Kernel" .

The function must return with XMK_TRUE, if the Signal was sent to the environment, otherwise it must return with XMK_FALSE.

xCloseEnv

Parameters:

In/Out: -no-
Return: -no-

This function is called by the Cmicro Kernel during the exit phase of the
SDL system. The user may include de-initialization of the environment here.

Exported from mk_user.c

xSDLOpError

Parameters:

In/Out: char *xmk_String1 - SDL ADT operators name
char *xmk_String2 - The reason for failure
Return: -no-

This is a function which is to filled up by the user. The function is an central error handling function for ADTs. It is compiled only if XECSOP was defined in ml_mcf.h.

ErrorHandler

Parameters:

In/Out: int ErrorNo - the given error number
Return: -no-

This is a function which is to be filled out by the user. The Cmicro Kernel as well as the SDL application are the main clients of this function.

The user may distinguish between the different errors and define a specific reaction.

The different errors defined in the file ml_err.h below the Cmicro Kernel directory.

WatchdogTrigger

Parameters:

In/Out: -no-
Return: -no-

Description:
If selected this function is called by the Cmicro Kernel each time an SDL transition is executed

Caution!

Be sure, that the time-out used for the Watchdog is longer than the longest SDL Transition (in the case of non preemptive Cmicro Kernel). If the preemptive Cmicro Kernel configuration is used, then the Watchdog Trigger should not be used because the execution time of transitions cannot be calculated.

xRouteSignal

Parameters:

In/Out: xmk_T_SIGNAL xmk_TmpSignalID - Signal ID
Return: xPID Process - PID or xNULLPID
if no receiver is defined for the given
signal.

Description:
This function is called by the Cmicro Kernel, if SDL signals have no receiver. (undef XMK_USE_RECEIVER_PID_IN_SIGNAL) This might be useful in very small systems in order to spare some RAM memory.The following restrictions apply:

  • The SDL System must not contain anything other than the following process declaration. (x,1)
  • For each Signal in the SDL System, there is to be only one Receiver process (no signal may be sent to more than one process type).
  • no dynamic process creation is used (Create-Symbol is not used)

Note:

Timers are represented as signals, that's because xRouteSignal also has to map timers to the receiver process

Hint:

Each signal and timer is represented by a system wide unique integer number.

Exported from mk_main.c

xmk_InitSDL

Parameters:

In/Out: -no-
Return: -no-

This C function is called by the user before calling the C function xmk_RunSDL() and implements the initialization of the whole SDL system, namely Timer, Queue, Processes.

xmk_RunSDL

Parameters:

In/Out: -no-
Return: -no-

This function operates endlessly unless XMK_USE_SDL_SYSTEM_STOP is activated. Then the function is returned if the signal queue is empty or no process is alive. Before processing signals, SDL time-outs are checked and the C function xInEnv is called.

xmk_MicroTesterInit

Parameters:

In/Out: -no-
Return: -no-

This function is used to tell the target configuration to the SDL Target Tester. First the communication interface is initialized, then the startup message is sent to the host. After that the target waits for a "go forever" message from the host.

xmk_MicroTesterDeinit

Parameters:

In/Out: -no-
Return: -no-

This function is responsible for closing the communication interface to the host after the system has ended.

Exported from mk_sche.c

xmk_StartProcesses

Parameters:

In/Out: -no-
Return: -no-

This function implements the start-up phase of the SDL system. All static process-instances are created. This means executing the start-transition of all process-instances to be created. For each created process-instance, the first state is set. If configured right, the values SDL_SELF, SDL_PARENT and SDL_OFFSPRING are correctly initialized (only necessary if no semantic check was performed, i.e. if the Analyzer is not used).

xmk_ProcessSignal

Parameters:

In/Out: -no-
Return: -no-

This function processes an SDL signal and remains in an internal loop, until a signal has been processed or until no signal remains in any input-port in the SDL system.

xmk_CreateProcess

Parameters:

In/Out: ProcessID - ID of the process type
Return: xmk_T_INSTANCE - created Instance number ID

This function tries to create an instance of the given process-type. This can fail, either if the create signal cannot be allocated (no more memory) or if there is no free process instance of that type. E.g. if there is no instance in the DORMANT state.

The return value contains the process instance number ID, if one more process instance could be allocated. The return value is set to xNULLINST if the creation failed for some reason.

The process instance number is not the same as the process ID. The process ID is calculated from the process ID type plus the process ID instance number.

The generated C code does not use the return value, because the SDL offspring and the parent pid value are stored in the pid tables of the process instance.

xmk_IsAnyProcessAlive

Parameters:

In/Out: -no-
Return: xmk_T_BOOL

This function checks for any active instance of a process type by searching for instances not in the state XDORMANT.

The function returns with XMK_TRUE, if there is an active instance. It returns with XMK_FALSE if there is no instance active within the system.

xmk_IfExist

Parameters:

In/Out: xPID - Process ID of the process to be checked
Return: xmk_T_BOOL

This function checks if the given PID is valid or not. The return value is XMK_TRUE if the given PID is valid. If an instance with this PID does not exist, it returns with XMK_FALSE.

xmk_CheckNullPointerValue

Parameters:

In/Out: void*
Return: -no-

This function checks whether there is a pointer value in the SDL system that is used but has no value. The ErrorHandler is called with the right error message then. The error must be caught in the user's ErrorHandler in order to implement the right reaction on this fatal situation.

xmk_InitPreemptionVars

Parameters:

In/Out: -no-
Return: -no-

The variables used in preemption are initialized.

xmk_DisablePreemption

Parameters:

In/Out: -no-
Return: -no-

The variable which stores the preemption status is incremented. A value greater than zero means it is not allowed to perform a context-switch at the moment.

xmk_EnablePreemption

Parameters:

In/Out: -no-
Return: -no-

The variable which stores the preemption status is decremented if preemption was disabled. If the variable's value is zero after it is decremented, the function xmk_CheckIfSchedule() is called.

xmk_FetchHighestPrioLevel

Parameters:

In/Out: -no-
Return: xmk_T_PRIOLEVEL

This function searches for signals in the priority queue levels. This is done with decreasing priority in order to find the highest priority level at which signals exist. The return value is the highest priority level that contains a signal to process.

xmk_CheckIfSchedule

Parameters:

In/Out: -no-
Return: -no-

It is checked whether a context switch is admissible. If this is the case the current priority-level is compared with the highest priority-level where a signal exists. Supposing the highest level is higher than the current, a context-switch is performed using xmk_SwitchPrioLevel(). This is repeated until the current priority-level is the highest level.

xmk_SwitchPrioLevel

Parameters:

In/Out: xmk_T_PRIOLEVEL NewPrioLevel
Return: -no-

The global variables for the current priority-level are stored. Afterwards, the function xmk_ProcessSignal() is called in order to deal with the signals on the higher priority level. After returning from this function call the variables for the current priority-level are restored.

With the NewPrioLevel the next prio-level to deal with is specified.

xmk_KillProcess

Parameters:

In/Out: xPID Process ID
Return: xmk_T_BOOL

This function sets a process instance into the state XDORMANT, removes all signals directed to it from the queue and resets the local instance data. The return values are XMK_TRUE if the call was successfully and XMK_FALSE if the process was non-existent, currently running or already in the XDORMANT state.

Exported from mk_outp.c

xmk_SendSimple

Parameters:

In/Out:
#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xmk_T_SIGNAL sig
xPID Receiver
#else
xmk_T_SIGNAL sig
#endif

Return: -no-

This is a simple SDL output function which needs a maximum of only 2 Parameters. Most SDL systems consist of a lot of "normal" Signals without any parameters and no priority. It makes sense to use this simple function whenever possible to spare program code. The signal is put into the linked list of signals by using a default priority.

With the first parameter sig, the signal ID of the signal that is to be sent is specified. With the (optional) second parameter, the receiver process ID is specified. If XMK_USE_RECEIVER_PID_IN_SIGNAL is not defined, the user must implement the C function xRouteSignal() which is responsible to derive the receiver from the signal ID in that case. Using xRouteSignal() is recommended only if the last few bytes must be spared for transferring of signals.

xmk_Send

Parameters:

In/Out:
xmk_T_SIGNAL sig

#ifdef XMK_USE_SIGNAL_PRIORITIES
xmk_T_PRIO prio
#endif

#ifdef XMK_USED_SIGNAL_WITH_PARAMS
xmk_T_MESS_LENGTH data_len
void xmk_RAM_ptr p_data
#endif

#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xPID Receiver
#endif

Return: -no-

This is, compared to the xmk_SendSimple function, a complete SDL output function which needs all possible signal parameters.

With the parameter sig, the signal ID is to be specified.

With the prio parameter, the signal's priority is to be specified (if conditionally compiled).

With the data_len, the number of bytes as the signal's parameters is to be specified. The number of bytes is evaluated by using a
sizeof (C struct) construct. If the signal carries no parameters, this value must be set to 0 (if conditionally compiled).

With the p_data parameter, a pointer to the memory area containing the parameter bytes of the signal is given. The memory area is not treated as dynamically allocated within this function. Because the function copies the parameter bytes, the caller may use any temporary memory (for example memory allocated from the C stack by declaring a C variable). This parameter should be set to NULL if no parameter bytes are to be transferred (if conditionally compiled).

With the last parameter Receiver, the PID of the receiving process is to be specified (if conditionally compiled).

If the XMK_USE_SIGNAL_PRIORITIES is not defined, the signal priorities which are specified with #PRIO in the diagrams is just ignored. The use of signal priorities is not recommended because the violation of SDL. A few bytes can be spared if signal priority is not used.

The XMK_USED_SIGNAL_WITH_PARAMS is automatically generated into the sdl_cfg.h file, from the Cmicro SDL to C Compiler. For tiny systems, if there are no SDL signals with parameters specified, this is undefined. It will reduce the amount of information which is to be transferred for each signal with a few bytes.

If XMK_USE_RECEIVER_PID_IN_SIGNAL is not defined, the user must implement the C function xRouteSignal() which is responsible to derive the receiver from the signal ID in that case. Using xRouteSignal() is recommended only if the last few bytes must be spared for transferring of signals.

XMK_SEND_ENV

Parameters:

In/Out: xPID Env_ID

xmk_T_SIGNAL sig

#ifdef XMK_USE_SIGNAL_PRIORITIES
xmk_T_PRIO prio
#endif

#ifdef XMK_USED_SIGNAL_WITH_PARAMS
xmk_T_MESS_LENGTH data_len,
void xmk_RAM_ptr p_data
#endif

#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xPID Receiver
#endif

Return: -no-

This function is to be called when a signal is to be sent into the SDL system, e.g. within the users xOutEnv() function. It must be called with one more parameter than the xmk_Send() function, which is the first parameter Env_ID.

The macro internally uses some variables which are to be declared before the macro can be used. For example in the xOutEnv function the XMK_SEND_TMP_VARS macro must be introduced for declaring these variables.

The function is implemented as a macro in C.

xmk_Determine_Receiver

Parameters:

In/Out: xmk_T_PROCESS proc_type - process type ID
Return: xPID - process PID

This function is used in the context of SDL output in generated C code. The function determines if any instance with the given process type-ID is available to receive the signal. If no instance can be found, xNULLPID is returned.

Exported from mk_queu.c

xmk_InitQueue

Parameters:

In/Out: -no-
Return: -no-

This function initializes the signal queue. It must be called before any other Cmicro Kernel function, e.g. before xmk_InitSDL(). All relevant pointers are initialized. All signal-elements are put into the free-list. The SAVE-state of all signals is set to false.

xmk_FirstSignal

Parameters:

In/Out: -no-
Return: xmk_T_MESSAGE*

The first signal in the current queue which is the one with the highest priority, is copied to the pointer of the currently treated signal and returned to the caller.

The function returns a pointer to the first signal in the queue or NULL, if there are no signals in the queue.

xmk_NextSignal

Parameters:

In/Out: -no-
Return: xmk_T_MESSAGE*

The signal following the current signal is copied to the current signal. If there are no more signals, NULL is returned.

xmk_InsertSignal

Parameters:

In/Out: xmk_T_MESSAGE xmk_RAM_ptr p_Message
Return: -no-

This function puts a signal into the queue. The position depends on only the signal priority, if specified.

With the parameter p_Message a pointer to the signal which is to be inserted is given.

xmk_RemoveCurrentSignal

Parameters:

In/Out: -no-
Return: -no-

The signal which was currently processed is removed from the queue and inserted into the list of free signals.

xmk_RemoveSignalBySignalID

Parameters:

In/Out: xmk_T_SIGNAL SignalId
Return: -no-

This function is not used if timers with parameters are in the system (XMK_USED_TIMER_WITH_PARAMS macro is defined).

Signals of a given signal-code sent to the current process are removed from the queue and inserted in the list of free signals. The signal currently being processed must not be removed, as it is necessary for the current actions. It is only removed after processing is complete.

With the parameter SignalID, the signal ID of the signals which are to be removed for the currently active process instance is specified.

xmk_RemoveTimerWithParameter

Parameters:

In/Out: xmk_T_SIGNAL SignalId
In : SDL_Integer TimerParValue
Return: -no-

This function is only compiled if timers with parameters are in the system (XMK_USED_TIMER_WITH_PARAMS macro is defined).

This function has the same purpose as the above xmk_RemoveSignalBySignalID but, in addition, must look to the timer's parameter.

xmk_IsTimerInQueue

Parameters:

In/Out: xmk_T_SIGNAL TimerID
#ifdef XMK_USED_TIMER_WITH_PARAMS
In : SDL_Integer TimerParValue
#endif
Return: -no-

This function checks if the given timer is in the signal queue. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is checked also.

xmk_RemoveSignalsByProcessID

Parameters:

In/Out: xPID ProcessID - PID of Process
Return: XMK_TRUE - Signal removed
XMK_FALSE - no Signal removed

All signals addressed to a specific process are removed by calling this Function.

With the parameter ProcessId, the PID of the process for which all the signals are to be removed from the queue is specified.

xmk_AllocSignal

Parameters:

In/Out: -no-
Return: xmk_T_MESSAGE xmk_RAM_ptr

According to the principle chosen by the user (the user has to choose between XMK_USE_STATIC_QUEUE_ONLY and XMK_USE_STATIC_AND_DYNAMIC_QUEUE), and if possible, an initialized signal instance is returned. The signal instance is then either taken from the static memory pool or from the dynamic memory pool.

Allocation from the dynamic memory pool takes place by calling the xAlloc C function.

If XMK_USE_STATIC_QUEUE_ONLY is set, the ErrorHandler is called with the error "ERR_N_NO_FREE_SIGNAL". This indicates that no more memory is available to create one more signal instance, and the user may react appropriately in the ErrorHandler C function.

Otherwise, if XMK_USE_STATIC_AND_DYNAMIC_QUEUE is set, and if it is impossible to allocate one more instance from the predefined static memory pool, the ErrorHandler is called with the error "ERR_N_NO_FREE_SIGNAL". This indicates that dynamic memory allocation is started now, and the user may react appropriately in the ErrorHandler C function (for example, he might want to print out a warning message). If it is impossible to allocate one more signal from the dynamic memory pool, the ErrorHandler is called with the error "ERR_N_NO_FREE_SIGNAL_DYN". The user may then also decide what to do in the ErrorHandler C function.

A pointer to the signal that was allocated is returned usually, or NULL, if there is no space left to allocate one more signal.

xmk_FreeSignal

Parameters:

In/Out: xmk_T_MESSAGE xmk_RAM_ptr p_Message
Return: -no-

The given signal is de-allocated again.

If the signal was allocated from the static memory pool, it is returned to that pool by initializing it and inserting it into the free list at the first position.

Otherwise, if the signal was allocated from the dynamic memory pool, it will be returned to that pool (by calling the xFree C function).

The parameter p_Message must point to the signal that is to be initialized.

xmk_TestAndSetSaveState

Parameters:

In/Out: xmk_T_STATE State
Return: xmk_T_BOOL

This function checks whether a signal's SAVE-state is set or not. In testing, the SAVE-state is set to TRUE or FALSE.

With the parameter State, the value of the process' current state is to be specified.

The function returns with XMK_TRUE, if the given state equals the signal's SAVE-state, but returns with XMK_FALSE if the given state differs from the signal's save state.

xmk_QueueEmpty

Parameters:

In/Out: -no-
Return: -no-

This function tests whether there is at least one signal remaining in the queue(s) or not.

The function returns XMK_TRUE, if there are no signals in the queue, but returns XMK_FALSE if there is at least one signal in the queue. It does not matter if the signal is a saved signal or not.

When the Cmicro Kernel is configured for preemption, all the queues of the different priority levels are checked.

Exported from mk_tim1.c

xmk_InitTimer

Parameters:

In/Out: -no-
Return: -no-

All initialization of timers is performed within this function, which is called during SDL system start. It initializes some pointers and the free list of timers.

xmk_TimerSet

Parameters:

In/Out: xmk_T_TIME time
xmk_T_SIGNAL sid
#ifdef XMK_USED_TIMER_WITH_PARAMS
In : SDL_Integer TimerParValue
#endif
Return: -no-

This function activates an instance of a timer with the given "signal ID" value and the given time. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is used also (the value is set to 0 outside this function call if it is not a timer with parameter).

Working principles:

  • If a timer instance of this type is already running, this will be
    deactivated i.e. reset and then set.
  • If no free timer is available, the ErrorHandler() is called.
  • If all is satisfactory, a timer instance is created for the currently running process.

The first parameter time specifies the time at which the timer should expire. The call to SDL now is performed in generated C code.

The second parameter sid specifies the ID of the timer that is to be started.

If a timer instance of this type is already running, this will be deactivated. If no free timer is available, the ErrorHandler is called. After all these checks a timer instance is created for the currently running process.

xmk_TimerReset

Parameters:

In/Out: xmk_T_SIGNAL sid
#ifdef XMK_USED_TIMER_WITH_PARAMS
In : SDL_Integer TimerParValue
#endif
Return: -no-

This function resets the timer with the given "signal ID" value, if it is active and set by the currently running process. If an active timer instance is found, then the timer is inserted into the free-list. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is used also (the value is set to 0 outside this function call if it is not a timer with parameter).

The parameter sid specifies the ID of the timer which is to be reset.

xmk_TimerActive

Parameters:

In/Out: xmk_T_SIGNAL sid
#ifdef XMK_USED_TIMER_WITH_PARAMS
In : SDL_Integer TimerParValue
#endif
Return: xmk_T_BOOL

This function checks if a timer with the given 'Signal-ID' value is active in the current running process. If timers with parameters are used, the TimerParValue, which is conditionally compiled, is used also (the value is set to 0 outside this function call if it is not a timer with parameter).

The parameter sid specifies the ID of the timer which is to be checked if it is active.

The function returns with XMK_TRUE if the timer is active in the process that is currently running, it returns XMK_FALSE otherwise.

xmk_ChkTimer

Parameters:

In/Out: -no-
Return: -no-

The main intention of this function is to check, if any of the timers which are in the list of active timers is expired. There is a list of active timers in which the active timers are stored in the order of their expiry.

This means that the timer that expires first stands in front of the list.

If a timer was recognized as expired, a timer signal is sent to the owning process instance, the timer is removed from the list of active timers and restored into the list of free timers.

If there is no timer that can expire, the function returns immediately.

Another task for this function is to check if the global system time is overrun. If this case occurs, the xmk_ChkTimer() function will readjust the global system time (by calling xmk_SetTime() from mk_cpu.c) and will readjust all the timers in the active list.

xmk_ResetAllTimer

Parameters:

In/Out: xPID pid
Return: -no-

All active timers of the given process instance are reset. This will occur if a process instance stops.

With the pid parameter the process instance is addressed.

Exported from mk_stim.c

xmk_InitSystime

Parameters:

In/Out: -no-
Return: -no-

This function initializes the hardware timer and is to be filled out by the user.

xmk_DeinitSystime

Parameters:

In/Out: -no-
Return: -no-

This function de-initializes the hardware Timer and is to be filled out by the user.

xmk_SetTime

Parameters:

In/Out: xmk_T_TIME time
Return: -no-

This function sets the system time to the given value time and is to be filled out by the user.

xmk_NOW

Parameters:

In/Out: -no-
Return: xmk_T_TIME

This function is used by

  • the Cmicro Kernel to calculate if a timer has expired and this is only the case if absolute time is used by the selected timer model.
  • SDL applications to retrieve the current time

The current SDL system time is returned.

The function is to be filled out by the user.

Exported from ml_mem.c

xmk_MemInit

Parameters:

In/Out: char* _mem_begin
char* _mem_end
Return: -no-

This function is to be called by the user, before dynamic memory management can be used. The user has to specify the beginning and the end of the area to be used for dynamic memory management. The function should be called before the first call to xAlloc(), e.g. as the first statement in the user's main() function.

xmk_Malloc

Parameters:

In/Out: unsigned long rsize
Return: void *

This function allocates one block of memory from the dynamic memory pool. It uses a first fit policy.

xmk_Calloc

Parameters:

In/Out: unsigned long RequestedSize
Return: void*

This function allocates one block of memory from the dynamic memory pool. It is the same as xmk_Malloc() but sets the allocated block to zero.

xmk_Free

Parameters:

In/Out: void *mem
Return: void

This function is the counterpart of xmk_Malloc(). A memory block is de-allocated again.

xmk_Memshrink

Parameters:

In/Out: void *pMemBlock
unsigned long NewSize
Return: -no-

This function is an extension of the compared with the standard of dynamic memory management supported by usual C compilers. It allows the user to shrink down a memory area which was previously requested with xmk_Malloc().

memset

Parameters:

In/Out: char *p
char val
int length-
Return: -no-

This function is a template for the memset() implementation.

Caution!

Take care when the preemption policy is utilized.

memcpy

Parameters:

In/Out: char *dest
char *source
int length
Return: -no-

This function is a template for the memcpy() implementation.

Caution!

Take care when the preemption policy is utilized.

Exported from ml_mon.c

xmk_GetErrorClass

Parameters:

In/Out: xmk_T_ERR_NUM EightBitNumber
Return: int

This function returns the error class assigned to the given error number given by the caller. The error class can be one of XMK_FATAL_CLASS or XMK_WARNING_CLASS. This can be used to classify the predefined error and warning messages and to react properly if such a message occurs.

xmk_MonError

Parameters:

In/Out: FILE *fp
int nr
Return: -no-

This function is used to evaluate an ASCII error text from an errornumber given by the caller. The first parameter fp must contain a pointer to a valid (i.e. file is opened) file descriptor, for example it could be stdin, stdout, or a file which was opened with fopen. The second parameter nr contains one of the possible error numbers defined in ml_err.h.

xmk_MonPID

Parameters:

In/Out: char *ostring
xPID pid
Return: -no-

Used for test purposes, free use.

xmk_MonHexSingle

Parameters:

In/Out: char *p_text
unsigned char *p_adress
int length
Return: -no-

Used for test purposes, free use.

xmk_MonHex

Parameters:

In/Out: char *p_text
unsigned char *p_adress
int length
Return: -no-

Used for test purposes, free use.

xmk_MonHexAsc

Parameters:

In/Out: -no-
Return: -no-

Function for test purposes, free use.

xmk_MonConfig

Parameters:

In/Out: -no-
Return: -no-

Function for test purposes, free use.

Exported from mk_cpu.c

xmk_PutString

Parameters:

In/Out: char * Param1
Return: -no-

A template for how to print out a character string. The character string must be terminated with "\0".

The function must return immediately, i.e. may not be blocking on the output device. If the user does not care about this restriction, the correct function of other program parts cannot be guaranteed.

xmk_GetChar

Parameters:

In/Out: -no-
Return: int

This function checks if the user has pressed a key on the keyboard (unblocked). The function must return immediately, i.e. may not be blocking on the input device. If the user does not care about this restriction, the correct function of other program parts cannot be guaranteed.

xmk_printf

Parameters:

In/Out: char* format
format string
other parameters
Return: -no-

This function is called from any place in the Cmicro Library, Cmicro Kernel or generated C code, if the printf functionality is compiled with at least one of the XMK_ADD_PRINTF* defines.

The function must return immediately, i.e. may not be blocking on the output device. If the user does not care about this restriction, the correct function of other program parts cannot be guaranteed.

The function can be used for ANSI C compilers only, because optional argument lists are used like in the printf function of the standard C library.

The return value has no meaning and is introduced just for compatibility with printf.

xAlloc

Parameters:

In/Out: xptrint Size
Return: void *

This function is called from any place in the Cmicro Library, Cmicro Kernel, SDL Target Tester or generated C code, if memory is to be allocated dynamically. The user may choose between the dynamic memory allocation functions from the C compiler or operating system or the dynamic memory allocation functions from Cmicro.

The return value points to the allocated buffer or is NULL if the operation was unsuccessful.

xFree

Parameters:

In/Out: void **
Return: -no-

This is the counterpart of xAlloc(). The function is called when a memory block that has been allocated with xAlloc() can be de-allocated again. The parameter is the address of the pointer to the allocated buffer.

Example 578 Using the xFree function

unsigned char *ptr;
ptr = xAlloc(100);
xFree (&ptr); /* NOTE: Not xFree(ptr); */


Functions of the Expanded Cmicro Kernel

The expanded Cmicro Kernel offers additional functionality that is usually not necessary for target applications. Extended functionality is for example required by the SDL Target Tester, but may also be required from the user if it comes to target integration.

It is not absolutely necessary to have knowledge of these functions but knowledge of the functions proves useful when it comes to debugging and testing an application.

Functions for Internal Queue Handling

Exported from mk_queu.c

xmk_SaveSignalsOnly

Parameters:

In/Out: -no-
Return: xmk_T_BOOL

This function tests whether there only are SAVE signals contained in the queue. This can be used in integrations with operating systems.

The function returns XMK_TRUE, if there are SAVE signals only in the queue, otherwise it returns XMK_FALSE.

Exported from mk_tim1.c

xmk_NextTimerExpiry

Parameters:

In/Out: xmk_T_TIME * RemainingTime
Return: xmk_T_BOOL

This function looks for the remaining time of the timer that expires next. This is useful for operating system integration. If there is no active timer, the function returns XMK_FALSE and the returned parameter RemainingTime is set to 0.

If there is an active timer, the function returns with XMK_TRUE and the returned parameter RemainingTime contains the time at which the timer expires next. XMK_TRUE means there is a timer active and the remaining time is returned in the parameter. XMK_FALSE means that there is no timer active and returned parameter is set to 0.

Functions to get System Information

Exported from mk_sche.c

xmk_GetProcessState

Parameters:

In/Out xPID pid
Return: xmk_T_STATE

The function evaluates the current SDL state of the SDL process pid with the given process PID and returns it to the caller. During the SDL system start-up, one possible return value might be XSTARTUP. This means that a process will be started during system start-up. During normal execution and system start-up, the return value XDORMANT may be returned. This means that an SDL process instance is either stopped or has never been created dynamically (created).

xmk_SetProcessState

Parameters:

In/Out: xPID pid,
xmk_T_STATE state
Return: xmk_OPT_INT

The function sets the SDL-state of the process pid that is addressed with the first parameter to the given value state within the second parameter. Note, that the value is not checked, because Cmicro does not store any information about this in the generated transition tables.

xmk_GetProcessInstanceData

Parameters:

In/Out: xPID pid
Return: void *

The function returns the address of the process instance data of the given process-PID, or XNOTEXISTENT, if the pid is not existent.

xmk_QueryQueue

Parameters:

In/Out: xmk_T_CMD_QUERY_QUEUE_CNF * qinfo
Return: -no-

This function evaluates the current SDL-Queue-State and returns some information to the caller:

  • information about the size of the Q (maximum amount of entries)
  • information about traffic load, measured until now. (Users can directly use this to scale the queue. This information is valuable in the case, where the maximum traffic load is reached during execution.)
  • Information about the number of entries that are currently in the queue.
  • A pointer to the physical address of the queue.

Exported from mk_tim1.c

xmk_QueryTimer

Parameters:

In/Out: xmk_T_CMD_QUERY_TIMER_CNF *tinfo
Return: -no-

This function evaluates the current state of the SDL-Timer handling and returns it to the caller. The following information is contained in the C structure that is returned:

  • Information about the size of the timer list entries.
  • Information about traffic load, measured until now. (Users can directly use this to scale the timer list. This is valuable in the case, when the maximum traffic load is reached during execution)
  • The current number of entries in the timer list.
  • A pointer to the physical address of the timer list.

xmk_FirstTimer

Parameters:

In/Out: -no-
Return: xmk_T_TIMER *

The function returns a pointer to the first active timer. If there is no active timer in the queue, NULL will be returned.

xmk_NextTimer

Parameters:

In/Out: -no-
Return: xmk_T_TIMER *

The function returns a pointer to the next active timer in the list of active timers. If there is no or one active timer in the queue, NULL will be returned.

Exported from ml_mem.c

xmk_GetOccupiedMem

Parameters:

In/Out: -no-
Return: size_t

This function returns the currently occupied amount of memory from the pool. The pool size is defined with XMK_MAX_MALLOC_SIZE.

xmk_GetFreeMem

Parameters:

In/Out: -no-
Return: size_t

This function returns the amount of available memory from the pool. This means that it returns the difference between the size of the pool (XMK_MAX_MALLOC_SIZE) and the currently occupied memory.

xmk_CleanPool

Parameters:

In/Out: -no-
Return: int

This function reinitialize the memory pool to free memory leaks. The memory pool can only be cleaned if there are no allocated blocks left.

Alternative Function for sending to the Environment

Exported from mk_outp.c

xmk_EnvSend

Parameters:

In/Out:
xmk_T_SIGNAL sig

#ifdef XMK_USE_SIGNAL_PRIORITIES
xmk_T_PRIO prio
#endif

#ifdef XMK_USED_SIGNAL_WITH_PARAMS
xmk_T_MESS_LENGTH data_len
void xmk_RAM_ptr p_data
#endif

#ifdef XMK_USE_RECEIVER_PID_IN_SIGNAL
xPID Receiver
#endif

Return: -no-

This function is an alternative to the standard function XMK_SEND_ENV for putting signals into the SDL system in external C code. The function is useful when signals are to be sent in interrupt service routines directly. The function is shorter than XMK_SEND_ENV, but performs not so many error checks. It is especially not checked, if the receiver process ID exist. Usually there is also no call to functions which produce trace output because this would lead to problems in interrupt service routines. But for some error situations like either

  • no free signal available
  • no more memory available

the ErrorHandler() C function, which is to be implemented by the user, is called.

With the parameter sig, the signal ID is to be specified.

With the prio parameter, the signal's priority is to be specified (if conditionally compiled).

With the data_len, the number of bytes as the signal's parameters is to be specified. The number of bytes is evaluated by using a sizeof (C struct) construct. If the signal carries no parameters, this value must be set to 0 (if conditionally compiled).

With the p_data parameter, a pointer to the memory area containing the parameter bytes of the signal is given. The memory area is not treated as dynamically allocated within this function. Because the function copies the parameter bytes, the caller may use any temporary memory (for example memory allocated from the C stack by declaring a C variable). This parameter should be set to NULL if no parameter bytes are to be transferred (if conditionally compiled).

With the last parameter Receiver, the PID of the receiving process is to be specified (if conditionally compiled).

If XMK_USE_SIGNAL_PRIORITIES is not defined, the signal priorities which are specified with #PRIO in the diagrams is just ignored. The use of signal priorities is not recommended because the violation of SDL. A few bytes can be spared if signal priority is not used.

The XMK_USED_SIGNAL_WITH_PARAMS is automatically generated into the sdl_cfg.h file, from the Cmicro SDL to C Compiler. For tiny systems, if there are no SDL signals with parameters specified, this is undefined. It will reduce the amount of information which is to be transferred for each signal with a few bytes.

If XMK_USE_RECEIVER_PID_IN_SIGNAL is not defined, the user must implement the C function xRouteSignal() which is responsible to derive the receiver from the signal ID in that case. Using xRouteSignal() is recommended only if the last few bytes must be spared for transferring of signals.


Technical Details for Memory Estimations

Allocating Dynamic Memory

Introduction

This section shows when and how dynamic memory allocation is used in the Cmicro Package. It shows,

  • how dynamic memory is allocated
  • how to estimate the memory requirements for an application

The Cmicro Package uses a form of dynamic memory management for the following objects:

  • processes
  • signals
  • timer
  • some of the predefined sorts like charstring, ASN.1 sorts and generators

However, real dynamic memory management is used only in one case, namely for SDL signals, if a signal carries parameters with more than a few bytes.

This means that the Cmicro Kernel has its own memory management to handle processes, signals, and timers. This is done in such a way that each of these 3 objects are managed separately. For each of these 3 objects, a separate fixed memory area is reserved during compilation time, i.e. the area that handles processes cannot be reused to handle timers. This seems to be a restriction but in many micro controller applications users have to fix an upper limit of processes, signals and timers which can be handled in parallel during run time.

Processes

Processes are handled without dynamic memory allocation functions. The user has to specify an upper limit of process instances in the SDL diagram separately for each SDL process. For each process instance, there is a variable which is statically allocated.

Signals with and without Parameters

Cmicro signals are both ordinary SDL signals as well as timer signals. Where timers are implemented without parameters and can therefore be regarded as signals without parameters.

  • No malloc/free for timers
  • No malloc/free for signals without parameters
  • No malloc/free for signals with parameters if less than or equal to XMK_MSG_BORDER_LEN bytes parameters are to be transferred.
  • malloc and free are used for signals with parameters if more than XMK_MSG_BORDER_LEN bytes parameters are to be transferred.
  • XMK_MSG_BORDER_LEN bytes is a macro defined in the manual configuration file ml_mcf.h. It can be set to any value, i.e. zero or the maximum number of signal parameters to be handled in the system.

Timers

For timers, no malloc and free functions are used. The Cmicro SDL to C Compiler evaluates the amount of timers in the system and generates a C constant, which is then used in the Cmicro Kernel to define an array for timers.


67 The SDL Target Tester

The SDL Target Tester is a tool which can be used to find errors and illegal or unwanted behavior within a target system. It allows the programmer to follow and to reproduce the execution flow of the SDL system (running on the target) on the host.

The strength of the SDL Target Tester is the minimum amount of storage it occupies on the target. With the exception of certain traces, the SDL Target Tester's memory requirements do not increase proportionally with system size. That means, that the memory amount is a compiler specific constant. If the memory is scarce it is also possible to reduce the memory by reducing the functionality.

In order to use the SDL Target Tester, the system must be developed with the Cmicro SDL to C Compiler (see 65 The Cmicro SDL to C Compiler) and the Cmicro Library (see 66 The Cmicro Library).

The host and target systems can be connected by any type of communications link, as any kind of communications drivers can easily be connected to the SDL Target Tester system.


Introduction

The SDL Target Tester offers the following features:

  • Tracing of internal and external SDL events with the Tracer
  • Generating MSC Traces with the Tracer
  • Trace of system errors
  • Debugging facilities
  • Profiling
  • Open interface to connect other tools
  • Scalable functionality
  • Error reproduction using the Recorder

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

The SDL Target Tester will be executed in a distributed fashion, i.e. some parts of the SDL Target Tester run on a host machine, while other parts run together with the Cmicro Kernel and the SDL application on the target machine, for example a micro controller. A prerequisite is a communications link between the host and target systems.


The SDL Target Tester - An Overview

Prerequisites

The SDL Target Tester is an optional part of the Cmicro Package and is delivered when specifically ordered. It is an addition to the Cmicro Library and contains the following parts:

  • the host tool chain (see "Using the SDL Target Tester's Host" )
  • the target library (see "The Target Library" )

The SDL Target Tester's host executable is a tool chain which consists of the executables sdtmt, sdtmtui, sdtmpm and sdtgate and sockgate. The sdtgate module contains the V.24 and sockgate the TCP/IP implementation for connecting host and target. All open interface functionality is utilized here.

The target library is mandatory when the SDL Target Tester is ordered. It must be used together with the Cmicro Library on the target. By using the open interface, it is possible to connect user specific tools to the SDL Target Tester's target library.

This diagram gives an overview of the SDL Target Tester functionality:

Figure 589 : Functionality of the SDL Target Tester

The following components, as seen from the user's point of view, represent the SDL Target Tester:

  • The Cmicro Tracer - trace of SDL and system events.
  • The Cmicro Recorder - recording and replaying SDL sessions.
  • The command and debug interface.

The Cmicro Tracer is introduced in the subsection "Following the Execution Flow - The Cmicro Tracer" .

The Cmicro Recorder is introduced following the subsection "Reproduction of Errors - The Cmicro Recorder" .

The command and debug interface is introduced in the subsection "Commands for the Host and Debugging Facilities" .

The following subsections give an overview of how to use the SDL Target Tester. A detailed description of the necessary preparations and adaptations will be given in the sections itself.

  • "Using the SDL Target Tester's Host" "
  • "Graphical User Interface"
  • "The Target Library"
  • "Connection of Host and Target"
  • "More Technical Descriptions" .

These sections follow after the introduction subsections.

Following the Execution Flow - The Cmicro Tracer

General

The Cmicro Tracer transmits information about the execution flow of the SDL system on the target. Information traced includes the signals sent and received by processes and the SDL states and symbols entered in execution flow. A filter can be defined so that only partial trace information is created for particular process instances or for particular SDL constructs. The tracer can be connected with the MSC Editor on the host, thus allowing observation of dynamic signal trace between processes in the system or from the environment to the system on the target.

Tracing SDL Events

The following SDL events can be traced.

State | The SDL nextstate operation
Input | The SDL input operation
Save | The SDL save operation
Output | The SDL output operation
Create | The SDL create operation
Stop | The SDL stop operation
Static Create | Used at system start, appears for each statically created process
Dynamic Create | Used at start of a dynamically created process
Decision | Trace of SDL action decision
Task | Trace of SDL action task
Procedure | Trace of SDL procedure call
Set | Trace of SDL action: Set timer
Reset | Trace of SDL action: Reset timer
Signalparams | Used to switch on/off trace of signal parameters
Implicit consumption | Trace of SDL implicit transition
Discard | Trace of SDL discard

For each symbol in each process in the system the trace can be separately switched on or off.

Please consult the subsection "The API on Target" for information about how to set the different options.

Tracing Other Events

The following system events can be traced.

Schedule | Used to trace scheduling events.
Error | Used to trace System errors, which are detected either within the generated code, within the Cmicro Kernel or within the SDL Target Tester.
Showprio | Used to trace the event, when the scheduling changes to a different priority level.

Each system event can be separately switched on or off.

Please consult the subsection "The API on Target" for information about how to set the different options.

Display of Traces in the MSC Editor

By using the SDL Target Tester, it is possible to create Message Sequence Charts with the MSC Editor. Two modes are of special interest:

  • Generating an MSC trace during an SDL session.
  • Conversion of a binary file into the MSC format.

The first case, however, only makes sense if the host has enough time to handle and display all the traces created during the run-time of the SDL system. Alternatively there might be SDL systems which do not have these timing constraints. For example, the SDL system may wait until the MSC trace is completed.

The second possibility does not need that much processor power on the host site. In practice, this method is more useful.

The method with using the Cmicro Recorder is the one with the best real-time properties. In comparison to the trace, the Cmicro Recorder stores only a reduced subset of information in a compact format.

Reproduction of Errors - The Cmicro Recorder

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

General

Using the Cmicro Recorder, the user can "record" the actions taken within an SDL system running on the target and save these to a file on the host machine. This file can later be "played" in order to run the system through the same state changes, so that the same actions are performed. In this way error situations, perhaps recorded by a client or a developer at another location, can be reproduced. In the following, a general description is given. A more detailed description of the internal procedures can be found in the subsection ""Type and Amount of Stored Information" ". The subsection ""General Restrictions on Record and Play" "may also provide more information about how it works.

Recording an SDL Session

Use of the Cmicro Recorder makes sense whenever an SDL system is executed in real-time on the target in combination with a host.

The amount of information transferred via the communications link and stored into a file on the hard disk is kept small and compact, so that the real-time properties are not influenced. Only information is stored, which is necessary in order to replay an SDL session later. It is the communication of the environment to the SDL system, and the expiration of timers, which is recorded.

Caution!

The real-time properties, and correspondingly the behavior of the SDL system may be affected when recording. The user has to ensure that there is enough time to process the functions of the Cmicro Recorder, and to transfer all the information via the communications link. In general, it is a good idea to use a high performance communications link with a large transmit buffer and a host machine, which is able to handle all recorded events at any time during the SDL execution.

It is not possible to receive information about the inner events of the recorded SDL system, by using the recorder only. The purpose of the Cmicro Recorder has nothing to do with the purpose of the Cmicro Tracer. The user also has to use the Cmicro Tracer if he wants to get information about internal events. Additional information is then transmitted via the communications link and stored into a file which can be displayed dynamically or later on. The performance of the communications link dictates whether real-time trace is possible. The more information traced via the link, the higher the performance should be.

The record mode must be switched on within the target (by using the C function interface on target), and on the host - see subsection "Record a Session" ).

Re-Playing an SDL Session

After producing a file with the record mode, the file can be replayed in order to run the SDL system in the same order through the same system states.

When the end of file is reached which is indicated with <Play mode off> to the target, the SDL system is able to react on ordinary environment signals coming from the real environment (if programmed by the user).

The play mode must be switched on within the target by using the SDL Target Tester Command Recorder-Play. No environment signals may be handled by the user in the C function xInEnv during the play.

Reaching the Erroneous System State

Sometimes, when a file is replayed, the erroneous situation can directly be viewed at another device, i.e. if the SDL system runs in an emulator with breakpoints set, or if there is, for instance, an LC display connected to the SDL environment.

In this case, it is not necessary to compare output files. In other cases, it might be of interest to do so as described later.

Comparing the Results

A comparison of two executions is possible, when two files containing the same type and amount of information are compared.

The procedure goes as follows:

  • Change the format from binary into ASCII for both files (command "Convert-File" ).
  • Use UNIX diff or an ASCII editor with options in order to evaluate the differences.

Commands for the Host and Debugging Facilities

The command interface and the debugging facilities are very helpful in finding errors produced within the target.

For instance, after an SDL interpretation error has occurred, it is possible to suspend the SDL system and to inspect the global state by viewing the signal queue(s). After the queue size has been re-dimensioned, the queue can be inspected again on the host site during a target execution.

There are several commands to check that timers are correctly processed.

The ability to set breakpoints during real-time execution and to execute a single step also helps to find an error situation.

The amount of trace information can dynamically be defined via commands. A differentiation is made between the information on the communications link and the information displayed.


Using the SDL Target Tester's Host

Introduction

The SDL Target Tester on host site is a tool chain consisting of the parts: GUI (sdtmtui), the logical part (sdtmt), the communications link gateway (sdtgate or sockgate) and the glue between these components the Cmicro Postmaster (sdtmpm). Sometimes, e.g. when the SDL Target Tester uses the MSC Editor, a further tool is executed called Cmicro Link (sdtmlnk).

The SDL Target Tester's host site is the tool, which allows communication with the target via a communications interface (see "The Communications Link's Host Site" ) to read or write to files (sdtmt), display information on the screen (sdtmtui) and/or the MSC Editor. It allows tracing of SDL and system events and has the ability to record and replay events to reproduce error situations.

Host features:

  • Trace of SDL and system events
  • Symbols and processes can be selected and filtered in order to reduce the amount of information
  • Record and replay of SDL executions (error reproduction)
  • Execution trace into file, to screen and to MSC Editor
  • Files can be read in later and displayed either on screen or on the MSC Editor
  • Small SDL Debugger

It is important to know that the host works independently from the target. The communication between both is built up automatically by the host if you start to communicate with the target. Thus, the host part of the SDL Target Tester remains the same executable when changing the target hardware! Only some adaptations in the configuration file sdtmt.opt have to be made, see "Preparing the Host to Target Communication" .

The graphical user interface is described in "Graphical User Interface" .

Different Ways of Using the SDL Target Tester

The standard method for using the SDL Target Tester is to connect a host with a target machine. A communications link implemented by the user must exist between host and target. The target can be seen as a remote system, where the SDL Target Tester running on the host machine can be considered a controlling unit. This is described in Figure 590.

Figure 590 : SDL Target Tester used for target control

The second way to use the SDL Target Tester is as a front-end for a host simulation. Therefore, a host simulation for the SDL System is built with the Targeting Expert. As described in Figure 591 the Gateway used for connection to the target is replaced by the host simulation.

Figure 591 : SDL Target Tester used for host simulation

Another way to use the host software is to use it purely as a conversion tool. This is of interest if a binary file has been written during earlier sessions with the target. The following picture shows the SDL Target Tester as a conversion tool:

Figure 592 : Sdtmt used for file conversion

Furthermore, by using the commands Output-NPAR and Output-PAR the SDL environment of the target or host simulation can be simulated with the host site.

Preparing the Host to Target Communication

After implementing the parts in the target, which are necessary to have a communication between host and target, the appropriate device on the host site is to be selected. This can be done in the file named

sdtmt.opt.

The Targeting Expert should be used to generate or modify sdtmt.opt (see "Configure the Host (Cmicro only)" ).

The Default Communications Link of Sdtmt

There is a V.24 interface implementation to transfer data between target and host. This is delivered as an additional executable called sdtgate.

The sdtgate default implementation uses the following protocol:

  • XON/XOFF protocol possible
  • 8 Bit data
  • One start bit
  • One stop bit
  • No parity
  • All data is transmitted as binary.
  • Control characters are masked and de-masked.
  • Binary protocol: Cmicro Protocol.

There is also a socket interface implementation to transfer data between target and host. This is delivered as an additional executable called sockgate.

The sockgate default implementation uses the following protocol:

  • All data is transmitted as binary.
  • Control characters are masked and de-masked.
  • Binary protocol: Cmicro Protocol.

Communication Setup on the Host System

If sdtmt is invoked, it searches for the configuration file sdtmt.opt. This file is mandatory!

Each line beginning with a '#' is treated as a comment.

It contains information on target options such as:

  • Target timer's scale and unit.
    These entries affect only the text trace.
  • Target data types' endian, alignment and size

Caution!

The file needs to be updated if another target system is connected, or if you change from a host simulation to your real target.

The file sdtmt.opt should have the following entries in order to configure the communications link:

  • USE_GATE:
    The path and the name of the used gate executable has to be specified here. In the delivered version of the SDL Target Tester, two executables called sdtgate and sockgate are included. They handle the V.24 and the socket interface on the host system.
    In case of a host simulation, the name of the executable which contains the simulated SDL system is inserted instead of the gateway.
  • GATE_CHAR_PARAM_, GATE_INT_PARAM_
    When the gate is forked by sdtmt these values are handed over to the gateway to configure the interface.
    • V.24
      Select the device: GATE_CHAR_PARAM_1 <devicename>
      On UNIX <devicename> might be /dev/ttya or /dev/ttyb (Please ask your system administrator).
      In Windows <devicename> might be COM1 or COM2
      Select the appropriate baud rate: GATE_INT_PARAM_1 19200
      All other GATE_... entries are not used with V.24 implementation.
    • Socket
      Select the device: GATE_CHAR_PARAM_1 <IP-address>
      <IP-address> has to be given in the standard format 192.168.1.4 or localhost.
      Select the socket port number: GATE_INT_PARAM_1 12345
      All other GATE_... entries are not used with Socket implementation.
  • UNIT-NAME, UNIT-SCALE
    The target's timer scale is multiplied with the value of UNIT-SCALE and displayed in units UNIT_NAME in the SDL Target Tester. The default values are "sec" and "1".
  • USE_AUTO_MCOD
    Switch on or of the use of the automatic message coder configuration on the host. Valid values are "yes" and "no".
    If the value is "no" you have to use the values described in the following to configure the message coder.
    If the value is "yes" the message coder will be configured by the target itself. Therefore it sends its configuration in a message at startup.The following values will be ignored in that case.

Note:

The target has to be compiled with the flag XMK_USE_AUTO_MCOD defined

  • LENGTH_
    The length (in octets) of the C basic types within the target must be given here. See the compiler manual for further information (header file limits.h).
  • ALIGN_
    The alignment for each C basic type must be given here.
    Alignment is the distance (counted in bits) from the first bit of a character to the named basic type. The Character is stored at an address dividable by four. See Figure 593.
    Allowed values are 8, 16, 32

Figure 593 : Target's alignment types

  • ENDIAN_
    The order of the C basic types within the target's memory must be given here. See the microcontroller data sheets and Figure 594 to get further information.
    Allowed values are: 1, 12, 21, 14, 41, 23, 32, 18, 81

Figure 594 : Definitions of the target's endian

Example 579 : sdtmt.opt

USE_GATE $(sdtdir)/sdtgate (on UNIX)
USE_GATE $(sdtdir)\sdtgate.exe (in Windows)
GATE_CHAR_PARAM_1 COM2
GATE_CHAR_PARAM_2 0
GATE_CHAR_PARAM_3 0
GATE_INT_PARAM_1 9600
GATE_INT_PARAM_2 0
GATE_INT_PARAM_3 0

UNIT-NAME sec
UNIT-SCALE 0.001

USE_AUTO_MCOD no

LENGTH_CHAR 1
LENGTH_SHORT 2
LENGTH_INT 4
LENGTH_LONG 4
LENGTH_POINTER 4
LENGTH_FLOAT 4
LENGTH_DOUBLE 8
ALIGN_CHAR 8
ALIGN_SHORT 16
ALIGN_INT 32
ALIGN_LONG 32
ALIGN_POINTER 32
ALIGN_FLOAT 32
ALIGN_DOUBLE 32
ENDIAN_CHAR 1
ENDIAN_SHORT 12
ENDIAN_INT 14
ENDIAN_LONG 14
ENDIAN_POINTER 14
ENDIAN_FLOAT 14
ENDIAN_DOUBLE 18

Invoking the SDL Target Tester's Host

Command Line Options of the SDL Target Tester

Option | Description
-h | Show a short help on the command line options.
-v | Show the version of the SDL Target Tester without opening it.
-t <targetdir> | Change the working directory to <targetdir>.

Invocation from the Organizer

There are two ways to invoke the SDL Target Tester from the Organizer with the actual project.
First you can use the menu Tools > SDL >Target Tester UI.
The other way is to add the following lines into the file
org-menus.ini. For more information, see 12 The Telelogic Tau Public Interface.

[MENU]
Name=&Cmicro
[MENUITEM]
ItemName=&Tester
Separator=0
StatusbarText=Start Target Tester
ProprietaryKey=1
AttributeKey=0
Scope=ALWAYS
ConfirmText=
ActionInterpretation=OS_COMMAND
BlockCommand=0
FormattedCommand=sdtmtui -t%v

Note:

Since code generation and compilation for Cmicro is only possible with the Targeting Expert, and the Organizer does not know about the directory where the Targeting Expert generates all files, you will be prompted automatically to enter the right directory.

In host simulation mode, internally, the -s flag is used additionally. The output of the Tester then contains some more helpful information that cannot be given in target debug mode.

Invocation from the Command Line or Desktop

Before using the SDL Target Tester described in the sections below, it is assumed, that a communications link between host and target exists (see "Connection of Host and Target" ), that the target executable has included the SDL Target Tester and that the trace is switched on within the target.

Several files have to be read from the user's current working directory.

On UNIX, the SDL Target Tester's host simply needs to be started from the working (project) directory.

  1. Change the current directory to the project directory (assuming that this directory is ~/cmicro_project).
    cd ~/cmicro_project
  2. Now, type
    sdtmtui

Note:

If the command sdtmtui is not found, the $path variable needs to be set up correctly. The user should ask his system administrator or the person that is responsible for the Telelogic Tau environment.

In Windows it is recommended that you create a new shortcut to the SDL Target Tester in the Window's Start menu or on the desktop. The shortcut must contain the following entries in its properties sheet:

  • Target:
    <tauinstdir>\bin\wini386\sdtmtui.exe -t<targetdirectory> -
  • Entry Start in:
    <tauinstdir>\bin\wini386\

Note:

The user should ask his system administrator about adding new links to the Start menu or the desktop.

The SDL Target Tester's host site is started when you double-click the SDL Target Tester icon.

The SDL Target Tester's host tool chain responds by showing the SDL Target Tester window:

Figure 595 : SDL Target Tester window

In the text area of the UI the following is displayed at startup:

Welcome to SDL Target Tester Version 4.4.0

Opening file: D:\...\sdtmt.opt
Starting "D:\...\component_sct_mdebcom.exe" ...
Done.

Starting in SCMADEBCOM mode.

Reading symbols file ...done

The SDL-System in D:\...\component.sym contains these processes:
DoorMonitor max. 1 instance(s)
DoorController max. 4 instance(s)
Controller max. 1 instance(s)
PanelController max. 1 instance(s)
Central max. 1 instance(s)

8 process instances in sum
Amount of signals :19
Amount of timers :4

After the target is reset its whole configuration is shown:

Example 580 : Target's Start-up / Configuration Message

The current target configuration is:

Compiled Cmicro KERNEL Features:
Preemption is not active
Signal Priorities are used
Receiver PId in signals are used
Sender PId in signals are used
Sending Signals the simple way is not used
Pid addressing is possible
SDL System Stop can not be used
Additional errorchecks are switched ON
Timer handling is implemented
Timers with parameters are not used
Dynamic create is implemented
Save is not implemented
Dynamic stop is not implemented
Only single instance processes NO

Compiled SDL Target Tester Features:
Host commands can be used
Profiling can be used
Debugging can be used
Trace is implemented
Signalfilter can be set
Time stamps are implemented
Recorder can not be used
Realtime play can not be used
Trace is currently switched ON
Auto MessageCoder is ON

Selected TARGET Modes:
Recorder is currently switched OFF
Player is currently switched OFF

Message Coder configuration: (size in octetts)
-------------------------------------------------------
SDL process ID's (xPID) : 4
SDL state ID's (xmk_T_STATE) : 1
SDL signal ID's (xmk_T_SIGNAL) : 1
SDL time values (xmk_T_TIME) : 4
Message length (xmk_T_MESS_LENGTH ) : 1
-------------------------------------------------------

SDL Data Type sizes (octetts):
-------------------------------------------------------
Boolean : 1 | Bit : 1 | Character : 1
Charstring :Ptr | Integer : 4 | Natural : 4
Real : 8 | PId : 4 | Duration : 4
Time : 4 | Null : 4 | Octet : 1
Octetstring: 12 | ObjId : 16
-------------------------------------------------------

Target was generated at: Mon Jan 01 12:00:00 2001

SDL System ready for configuration.

Start with "Go-Forever".

Note:

Within the target's configuration message the timestamp (seconds since the 1st of January 1970) of the generated C file is sent to the host, too.
If this timestamp is not equal to the one in the symbols file (.sym) a message box is displayed giving hints as to what has to be done.

Getting a Target Trace

After the start-up message is received the target is ready to be traced.

The command Go-Forever starts the SDL system in the target and the static create trace messages will be sent.

When a process instance executes actions within a transition, trace information describing the different actions is either printed on the screen, on the MSC Editor or written into a file specified by the user. The amount of information printed can be selected using the trace commands in the monitor system. All trace information is self explanatory. This trace example was created from the AccessControl:

Example 581 : Trace for the AccessControl

*** STATIC CREATE
* PId : DoorMonitor:0
* TASK LastOffspring :=
*** NEXTSTATE Idle

*** STATIC CREATE
* PId : Controller:0
* TASK NextDoor :=
* OUTPUT of Allocate to DoorMonitor:0
* Prio : 100
* Now : 0.000000 sec
* Param(s) : 1
* SET MyTimer
* Time : 10.000000 sec
* Value : 0
*** NEXTSTATE WaitAllocated

*** STATIC CREATE
* PId : PanelController:0
* OUTPUT of Display to ENVIRONMENT
* Prio : 100
* Now : 0.000000 sec
* Param(s) : 1
*** NEXTSTATE Idle

*** STATIC CREATE
* PId : Central:0
* TASK NextFree :=
*** NEXTSTATE Idle

Debugging - A Few Guidelines

The following few guidelines may help to understand the different possibilities when searching for a specific command.

Breakpoints

A lot of error situations may occur when the system is downloaded for the first time. Possibly the basic functions needed to allow the SDL system to run the target do not work. Possibly the compiler adaptations are wrong. The initialization of the environment may be incomplete. The compiler may generate faulty object code. The memory of the target may be exceeded, i.e. either variables, constants, program code, stack or dynamic allocated memory. Also, real-time requirements may not be fulfilled.

Breakpoints can greatly help to discover such situations. The breakpoint logic is especially useful as it has only a negligible impact on the systems real-time performance.

Setting Breakpoints

Does a specific process instance (pid) receive a specific signal?

BPI processname nr signalname

Does a specific process instance (pid) go into a specific state (does it end any transition, which leads to that state)?

BPS processname nr statename

Trace Scaling

The target's trace can be scaled. Sometimes it is necessary to omit trace altogether.

This may be necessary to reduce the amount of trace messages via the communications link, but can also be used to expand the view of some details.

Switch off the trace of signal parameters

Tr-Params 0

or switch it on again.

Tr-Params 1

The main interest may be lay on the work of one special process. This process can be explicitly defined with

Tr-Process processname nr

The trace for all other processes will be switched off.

Corresponding to this command the scope view can be set to a specific signal

Tr-Signal signalname

If the trace of the whole SDL system should be reduced, e.g. the trace of TASKs and DECISIONs is of no interest

Tr-Detail 4

switches the trace of these symbols off.

The command Tr-Detail can be used with five levels, for further information see "Tr-Detail" .

Record a Session

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

See "Invoking the SDL Target Tester's Host" to start-up the SDL Target Tester. When the target's start-up message is displayed in the text area, the target must be configured to record a session, i.e. the Recorder must be switched on in the target.

If the user wants to replay a recorded session in real-time mode he must be sure that the target executable is compiled with signals including time stamps (see "XMK_USE_SIGNAL_TIME_STAMP" ).

The user has to do several things

  1. Open an output file by using the command
    Output-File filename
  2. Switch the Cmicro Recorder on by using
    Recorder-On
  3. Start the SDL system with
    Go-Forever

As with a standard trace the target's messages are displayed in the text area. The user can now use the target as if the SDL Target Tester is not involved. All traces and recorded messages are stored into the output file.

  4. To end the session the Cmicro Recorder should be stopped:
    Recorder-Off
  5. And the output file has to be closed:
    Close-File

Re-Play a Recorded Session

Before replaying a session it is required to record a session by following the steps listed in "Record a Session" .

First the target has to be reset. The start-up message reappears.

Now the user can start the replay with the commands

  1. Input-File filename
    where filename is the name of the file written during a recording session (this file must contain Cmicro Tracer messages as well as Cmicro Recorder information).
  2. Switch the play mode on:
    Recorder-Play
  3. If desired switch the real-time play mode on:
    Recorder-Realtime
    Remember: the target has to be compiled using this feature.
  4. Start the target:
    Go-Forever

The target now starts by tracing the static creates and in accordance with the design of the SDL system the first transitions are executed and traced.

Now the SDL Target Tester's host inserts all the signals coming from the environment so that the recorded session will be replayed in the same order.

Note:

The real environment is not being polled during the replay session.

Restrictions of the SDL Target Tester

The SDL Target Tester has a few restrictions:

  • Only values of the following SDL data types are displayed in readable form: Bit, Boolean, Char, Charstring, Integer, Natural, Octet, Real, PId, Duration and Time.
    Syntypes, Structures, Enumeration Types and Arrays which contain only SDL-data types can be decoded correctly.
  • Complex data types, e.g. Array of Structures indexed by syntype may be decoded wrong due to alignment.
  • If the SDL Target Tester encounters a unknown data type, decoding is interrupted. The first unknown data type is printed to the screen and the rest of the parameters is displayed as a hexadecimal buffer.
  • Record and play mode may not be entered together.
  • During the play mode only certain commands are allowed. The available commands are marked with an asterisk.
  • Any SDL sort that is implemented as pointer in C (like Charstring, Object_Identifier, Ref, Own, etc.), cannot be handled in trace, record or play mode. This comes as a result of the implementation of trace (explained in 66 The Cmicro Library). The trace does not distinguish if there is a buffer containing a pointer to be traced or not, because there is no symbol information generated into the target system for efficiency.


SDL Target Tester Commands

Syntax of SDL Target Tester Commands

Command Names

Command names are entered character by character on the keyboard. Each command consists of ASCII characters, terminated by a carriage return. A command is interpreted, after the carriage return is given. Commands may have parameters. Command names may be abbreviated by giving sufficient characters to distinguish it from other command names. The command names are interpreted from left to right. There is no distinction between upper and lower case letters.

Consider, as an example, the command ?Breaklist. The command may be entered as "?b". However, if only `?' is typed, sdtmt will respond with the error message:

Command was ambigous, choose one from:
< list of commands >

since the command cannot be distinguished from, for example, the ?Queue command. As additional information a list of all commands which would fit to the entered command and which are allowed in the current context is given.

Command Parameters

A parameter is separated from the command name by one or more spaces. The same is applicable to the separation of two parameters. There is no distinction between upper and lower case letters.

Each parameter is mandatory from a syntactical point of view and must be specified. No parameters may be left out.

If the parameter list following a command name is not complete, a dialog window is opened to enter the missing parameter(s).

Specifying more parameters than the command can handle, sdtmt prompts

**ERR:Extra parameters specified in command.

If the type of any parameter, which was entered, does not match the expected one, then sdtmt responds with an appropriate error message according to the expected type. Type

help commandname

or refer to the manual.

Abbreviation of SDL Names

Command parameters that are SDL names, may also be abbreviated, as long as the abbreviation is unique. If a name is equal to the first part of another name, as for example Wait and Wait_For_Me, then any abbreviation of Wait is ambiguous. However, if all characters of the shorter name are given (Wait in this example), this is considered as an exact match and the short name will be selected.

Errors in Commands

If an error is detected in a command name or in one of its parameters, an appropriate, self explanatory error message is displayed on the screen. The command will be ignored.

Input and Output of Data Types

<Processtype Instance>

Process type is an ASCII string identifying the SDL name of the process. Process names must be unique for all processes within the system. It is also possible to use the decimal value of the process type. The decimal value can be found by looking into the symbol file, which is also automatically generated.

The separator for process type and instance is a blank.

Instance

The value of the instance number is a decimal value beginning from 0 for the first instance of a process type. If the SDL System contains only (x, 1) declarations on SDL level, then the user has to specify "0" in any case.

Note:

There is a difference between the notation in the simulator and in the SDL Target Tester concerning instance numbering. The simulator always uses the value one as the first instance number whereas the SDL Target Tester begins numbering these at zero!

Caution!

If no symbol file was specified, then neither process type nor instance is checked within sdtmt! If the target is compiled without error checks, that might lead to a fatal error in the target system.

Symbols

Symbols are read in from a file called <systemname>.sym. There are a lot of error checks within the SDL Target Tester's host site which only work if a symbol file has been loaded.

Help

SDL Target Tester gives the user some quick help when entering:

help

A complete list of commands will be displayed on the screen. Commands, which are available in the current mode, are marked with an asterisk. If a command is entered which is not available in the current context the SDL Target Tester responds with:

Sorry. The current mode of sdtmt does not allow you to enter that command.
The command has been ignored.

To get a short explanation, type:

help <commandname>

for instance type:

help help

To get a complete list of commands, type:

help *

Most of the commands marked with the type "Remote" can only be executed (in the target) if the flag XMK_ADD_MICRO_COMMAND is defined in the file ml_mcf.h. See "Manual Scaling" .

Alphabetical List of Commands

??

Parameters:

(None)

Type: Local

Open a dialog with a list of all allowed commands. By pressing the OK-Button the selected command is copied to the Input line.

Active-Timer

Parameters:

<Processtype Instance> <Timername> <Timerparameter>

Type: Remote

Check, if a specific timer is set by a process, and has not been expired.

Note:

The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog.

?All-Processes

Parameters:

(None)

Type: Remote

Note:

This command is obsolete. Use ?Process-State * * instead.

BA

Parameters:

(None)

Type: Remote

This command requests to clear all the breakpoints in the break list.

BC

Parameters:

<breakpoint number>

Type: Remote

This command requests to clear the given breakpoint number from the breakpoint list. The breakpoint number depends on the total number of defined breakpoints.

BP

Parameters:

<Processtype Instance> <SignalName> <StateName>

Type: Remote

This command sets a breakpoint on the input and the state of a process. Execution is halted only if the given input in the given state is detected.

No parameter is optional. These combinations are allowed:

processname nr * statename ->Use command BPS
processname nr signalname * ->Use command BPI
processname nr * *
processname nr signalname statename

BPI

Parameters:

<Processtype Instance> <SignalName>

Type: Remote

This command sets a breakpoint on the input of a given process. Execution is halted on any input of the signal in this process.

It is not mandatory to provide a parameter. These combinations are allowed:

processname nr *
processname nr signalname
processname *
processname signalname

BPS

Parameters:

<Processtype Instance> <StateName>

Type: Remote

This command sets a breakpoint on the state of a given process. Execution is halted if the given state is reached.

No parameter is optional. These combinations are allowed:

processname nr statename
processname *
processname statename
processname nr *

?Breaklist

Parameters:

(None)

Type: Remote

This command requests the current breaklist from the target and displays it on the screen as it was entered. If a symbol file has been specified during the invocation of sdtmt, then process IDs, signal IDs and state IDs are displayed with their symbolic value.

Change-Directory

Parameters:

<directoryname>

Type: Local

The working directory of the current SDL Target Tester session is switched to <directoryname>.

Close-File

Parameters:

<filename>

Type: Local

The current output/input file (including binary trace) with the name <filename> will be closed when using this command. (See "Output-File" and "Input-File" )

?Coder

Parameters:

(None)

Type: Local

After invoking this command the current settings of the Target Message Coder TMCOD are display in the text area. The settings given here have to be previously made in the configuration file sdtmt.opt or have been sent by the target itself. See "Preparing the Host to Target Communication" .

Continue

Parameters:

(None)

Type: Remote

This command can be used to continue processing, i.e. after a breakpoint was h. Notification is given when the command cannot be processed within the target system.

Convert-File

Parameters:

<input filename> <output filename>

Type: Local

This command converts the trace messages of the target (stored in the <input filename>) into readable ASCII trace. This ASCII trace is stored into the <output filename>.

Create

Parameters:

<Parent-Processtype Instance> <Child-Processtype>

Type: Remote

This command creates an SDL process of the given type
<Child-Processtype>. The creating process must be specified in <Parent-Processtype Instance>. If there is a free process instance, which is currently dormant, it will be created and the start transition will be executed. This can be seen in the trace.

If the system is under a break condition, the command will be ignored as it is not possible to send signals (dynamic creation uses signal mechanism).

Note:

Please specify the <Parent-Processtype Instance> according to the SDL system. There is no check if the parent is specified correctly from the semantic point of view.

Disable-Timer

Parameters:

(None)

Type: Remote

This command disables the processing of timers.

The command affects the SDL timers only! However, timers which are already expired and are in the queue will be input as normal. Keep in mind that the disabling of timers changes the system behavior.

Display-Off

Parameters:

(None)

Type: Local

The ASCII trace into the text area is switched off.

Display-On

Parameters:

(None)

Type: Local

The ASCII trace into the text area is switched on.

Enable-Timer

Parameters:

(None)

Type: Remote

This command enables the processing of timers again, if it was previously disabled with the command Disable-Timer. Due to the fact that time (and so the system time) cannot be stopped, it might happen that all the timers set earlier may expire at the same time this command is entered. This may cause illegal system behavior, i.e. a queue overflow and the call of the ErrorHandler or another illegal behavior.

?Errors

Parameters:

<const>

Type: Remote

Query last occurred error. The target system traces the last error within the SDL execution and stores it. The result will be displayed on the screen, both as a decimal value and as ASCII text with an explanation of the error situation.

If the value <const> is not equal to zero, further information about the error is given from this manual (the on-line Help Viewer is started).

Especially, when the SDL system is executed for the first time in a new hardware environment, the command may help in finding problems. It is also useful after a long execution of the SDL system, as any error situation arising may be detected. All the errors, warnings and information, which are handled by the ErrorHandler are explained in the section "User Defined Actions for System Errors - the ErrorHandler" .

Exit-Single-Step

Parameters:

(None)

Type: Local

The single step mode (which has been entered with Single-Step) is finished.

Get-Configuration

Parameters:

(None)

Type: Remote

The target responds with its configuration. Compiled features are displayed in the text area as well as the current settings (e.g. trace on/off).

Go-Forever

Parameters:

(None)

Type: Remote

After initializing the target (for example switching the recorder mode on) the target is started with this command. It is necessary that the target is compiled with the flag XMK_WAIT_ON_HOST.

Help

Parameters:

[<commandname> or *]

Type: Local

A complete list of commands will be displayed on the screen. Commands available in the current mode of the SDL Target Tester are marked with an asterisk.

Example 582

Type

Command>help <commandname> ,

to get a short explanation of one or several commands, e.g.

help help

which is the same as

he he

Example 583

A list of all commands beginning with b can be requested by typing:

help b

A complete list of commands can be requested by typing:

help *

Input-File

Parameters:

<filename>

Type: Local

The file named <filename> is opened to get the stored trace information (binary format). This command must be used if, for example, a recorded session should be replayed. The file <filename> must contain trace information in binary format.

Line

Parameters:

(None)

Type: Local

The command displays the line status of the communications interface. It can be used for checking if characters, frames and XONs / XOFFs have been received/transmitted and the kind of device that is actually connected.

?Memory

Parameters:

(None)

Type: Local

If the Cmicro Memory Management is selected (the flag XMK_USE_SDL_MEM must be defined, please view "Use of Memory" ) this command offers the advantage of checking currently allocated memory.

News

Parameters:

(None)

Type: Local

The SDL Target Tester Release's news are displayed in the text area.

Next-Step

Parameters:

(None)

Type: Remote

This command performs one step (one transition) if single step is active. The Single-Step command must be given prior to this.

Nextstate

Parameters:

<Processtype Instance> <Statename>

Type: Remote

This command sets the state of the given process instance to the value of <Statename>. <Statename> must be one of the states which are defined for the corresponding process type in SDL. Normally, that only makes sense if the system is under break condition or is idle.

Output-File

Parameters:

<filename>

Type: Local

All the target's trace information is stored as binary data into the file <filename>. This command can be used to store the information of a recording session in binary format.

Output-NPAR

Parameters:

<Receiver-Processtype Instance> <Signalname>

Type: Remote

An Output from the environment without any parameters is sent into the SDL system.

Output-PAR

Parameters:

<Receiver-Processtype Instance> <Signalname> <Signal Parameter>

Type: Remote

An output from the environment into the SDL system with a signal including parameters is sent into the SDL system. The
<Signal Parameter> has to be given as a buffer of hexadecimal values. See Example 584.

Example 584 : Output with parameters

Output-PAR Process_A 0 Signal_1 "00-12-a3"

Signal `Signal_1' is sent to the instance 0 of process type `Process_A'. `Signal_1' contains parameters with the length of three octets and the values 0x00, 0x12 and oxa3. The ordering of the parameter octets must fit into the signal's parameter structure and the target's memory layout (alignment, endian etc.).

Options-File

Parameters:

<filename>

Type: Local

The options file <filename> is read in so that the message coder can be initialized. By default the options file sdtmt.opt (see "Preparing the Host to Target Communication" ) is read in when the SDL Target Tester is started.

Page-File

Parameters:

<filename> <EventsPerPage>

Type: Local

The file <filename> containing trace information (in binary format) is read in and displayed as ASCII trace in the text area. The constant decimal value <EventsPerPage> gives the amount of trace information to be displayed until the user confirms the next page.

Print-Conf

Parameters:

(None)

Type: Local

This command gives all configuration information together, see the commands -?Coder and Line.

?Process-Profile

Parameters:

<Processtype Instance>

Type: Remote

The profiling of one process instance can be requested with this command. The result is the transition execution time of the longest transition and the last transition of the specified process instance. The flag XMK_ADD_PROFILE must be set when compiling the target executable to have access to this command in the target.

Please view the section "Initialization" .

?Process-State

Parameters:

<Processtype Instance>

Type: Remote

Query the state of the given process(es).

The amount of queried process instances can be configured:

  • If you specify a valid process instance (?Process-State P1 0), the current state of this instance is printed.
  • If you enter a process type and * (?Process-State P1 *) you get the states of all instances of this type.
  • If you enter ?Process-State * * all possible Process instances of the system are queried.

Depending on the traffic load on the communications interface the responses may be delayed.

Caution!

The results printed on the screen may be inconsistent. That depends on what the SDL system is doing during the query procedure. The results will be correct, however, if the whole SDL system is idle.

?Queue

Parameters:

(None)

Type: Remote

Some characteristics of the queue will be displayed. The command is very useful for determining the queue's dimensions. There is a peak hold, which shows the maximum number of entries in the queue since the system's start.

Example 585

After typing the command, information is printed on the screen, which may look like:

Current Queue state:
Queue size dimensioned to:Max.20 entries
Peak hold :1 entry/entries
Currently :0 entry/entries in queue
Queue memory located at :36a40010,x

The explanation for this is: a maximum of 20 entries in the queue can be handled by the system. Since system start, there was never more than one entry being used. Currently, no signal instance has been detected in any process input port. The last value displays the physical memory allocation of the queue, which helps in debugging.

Recorder-Delay

Parameters:

<duration>

Type: Local

If a recorded session should be replayed it is possible to insert each environment signal with a delay of <duration> seconds. This feature can be used instead of the real-time play (Recorder-Realtime).

Recorder-Off

Parameters:

(None)

Type: Remote

Switches the Cmicro Recorder off. This command may be specified any time during a recording session. It can be used in order to reduce the amount of information sent via the communication interface.

Recorder-On

Parameters:

(None)

Type: Remote

Switch Cmicro Recorder to record mode. It is not a good idea to enter this command when the SDL system is not idle. (Furthermore, the question is, whether it makes sense to start a record session in the middle of an SDL execution or from the start-up of the SDL system.) It may not be relevant to start a recording session after the system has started.

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

Recorder-Play

Parameters:

(None)

Type: Remote

The Cmicro Recorder's play mode will be set. This command can be entered in a few states of the Cmicro Kernel only. Notification is given if necessary. The same explanation as for Recorder-on apply.

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

Recorder-Realtime

Parameters:

(None)

Type: Local

The play mode of the SDL Target Tester is started as real-time play. It is necessary to compile the target with signals including time stamps.

The SDL Target Tester's host sends all environment signals with the recorded time stamp into the target while replaying. Without using this command all signals are inserted with time 0 which leads to an immediate execution in the target.

Reinitialize

Parameters:

(None)

Type: Remote

This command tries to reinitialize the system. The reinitialization may fail, if the hardware drivers cannot be reinitialized again. Furthermore, all global auto variables in the user's C program parts cannot be reinitialized. However, if there is a clean implementation of driver initialization and de-initialization, and initialization of global variables, the command will work well.

Remove-All-Signals

Parameters:

<Processtype Instance>

Type: Remote

Remove all signals of the given receiver from the signal queue.

Remove-Command

Parameters:

(None)

Type: Local

For each command, which is sent to the target, the host waits for an explicit acknowledgment. The last command can be removed, so that the host does not wait for that acknowledgment. That can be used when the communication is hanging for any reason, for example, when the command could not be sent to the target, or was not received by the target, or the acknowledgment could not be received by the host.

Remove-Queue

Parameters:

(None)

Type: Remote

All signal instances in the queue will be removed. The signal queue will be empty.

Remove-Signal

Parameters:

<Processtype Instance> <Signalname>

Type: Remote

Remove a specific signal of the given receiver from the queue.

Note:

E.g. when a breakpoint is hit the signal which led to the current transition still remains in the signal queue. This means the first signal in the queue cannot be removed.

Reset-All-Timers

Parameters:

<Processtype Instance>

Type: Remote

This command resets all SDL timers of the given process instance.

Reset-Timer

Parameters:

<Processtype> <Instance> <Timername> <Timerparameter>

Type: Remote

This command resets a specific SDL timer of the given process instance and with a specific timer value.

Note:

The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog.

Resume

Parameters:

(None)

Type: Remote

Resume Cmicro Kernel, after a suspend has been accepted. The same explanations as for the Suspend command apply.

Run-Cmd-Log

Parameters:

<filename>

Type: Local

The initialization commands in the log file <filename> will be executed.

Caution!

In principle it is possible to use all kinds of commands in this command log file. But the correct execution cannot be guaranteed because there are to many interactions between the SDL Target Tester, the Gateway (sdtgate.exe), the target and the Organizer.

E.g. the MSC Editor can only be started from a command log file if the requested performance of the host machine is supported.

Caution!

It is still possible to use debugging commands in this log file, too. But the user has to think about the usefulness as all commands will be executed directly after one another without getting the correct timestamp of execution.

Scale-Timers

Parameters:

<factor>

Type: Remote

Scale time when setting a timer.

Often there is a need to simulate time during an SDL execution. By specifying this command, it is possible to make SDL timers run faster or slower. The command is applied on newly set timers only, i.e. if a timer is already running then it remains unaffected from the time scale. Due to this fact, the command should only be given at the start of the SDL system.

In record mode the scaled time will be stored. This results in time being scaled in play mode. It is impossible to scale time manually in play mode!

Set-Timer

Parameters:

<Processtype Instance> <Time value> <Timername> <Timerparameter>

Type: Remote

Set an SDL Timer for the given process instance with the given time value in units. The time value is a float value re-calculated to the target's timer ticks. Please view "UNIT-NAME, UNIT-SCALE" .

.

Note:

The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog.

Example 586 Setting a timer without parameters

set <Processtype> <Instance> 4711 < timername> 0

set <Processtype> <Instance> 1.456 <timername> 0

Shutdown

Parameters:

(None)

Type: Remote

The command tries to shutdown the system, which means normally to exit the main program. The user can define the actions on exit within the target. The same explanations as for the reinitialization command apply.

Single-Step

Parameters:

(None)

Type: Remote

This command switches the single step mode on. Either Next-Step or Continue may follow.

Note:

Timers are checked normally during single step and may expire, as documented for the Disable-Timer and Enable-Timer commands. It may be better to disable the timers (with Disable-Timer) before going into single step.

Start-Cmd-Log

Parameters:

<filename>

Type: Local

All the initialization commands will be written to the log file <filename>. Please view the command "Run-Cmd-Log" , too.

Start-Gateway

Parameters:

(None)

Type: Local

This command is used to start the communication in the default implementation of the sdtgate or a host simulation.

Start-MSC-Log

Parameters:

<level> <"Diagramname">

Type: Local

The MSC Editor is started and the target's trace messages will be displayed in the MSC Editor. The <level> specifies the amount of MSC symbols:

0 - Basic Message Sequence Chart
1 - like level 0 but with the trace of states
2 - like level 1 plus the trace of actions
4 - Basic Message Sequence Chart to file
5 - like level 0 but with the trace of states to file
6 - like level 1 plus the trace of actions to file

Start-SDLE-Trace

Parameters:

<Processtype> or
*

Type: Remote

The trace on SDL symbol level is started for the specified process. The Organizer has to be running and the target needs to be compiled with the flag XMK_ADD_SDLE_TRACE (see "Trace" ).

Start-Trace-Log

Parameters:

<filename>

Type: Local

A log file containing the whole ASCII trace of the SDL Target Tester will be written.

Stop

Parameters:

<Processtype Instance>

Type: Remote

This command stops an SDL Process according to the SDL semantics, no matter if the system is suspended or under break condition. The command is, after it is received, directly executed within the target. All signals which are in the queue for this process are removed, including create signals.

Stop-Cmd-Log

Parameters:

<None>

Type: Local

The write of initialization commands will be stopped. Please view the command "Run-Cmd-Log" , too.

Stop-Gateway

Parameters:

(None)

Type: Local

This command is used to stop the XON communication in the default implementation of the sdtgate.

Stop-MSC-Log

Parameters:

(None)

Type: Local

The trace on the MSC Editor is stopped.

Stop-SDLE-Trace

Parameters:

<None>

Type: Local

The trace on SDL symbol level is stopped.

Stop-Trace-Log

Parameters:

<None>

Type: Local

The trace to the trace log file is stopped. The file is closed.

Suspend

Parameters:

(None)

Type: Remote

Disables the Cmicro Kernel from scheduling. The transition currently running will not be affected and will be ended first, before the command is accepted. The suspended SDL system cannot process any signals, neither internal signals nor signals coming from the environment. This may lead to a queue overflow. It is recommended to disable the timers to prevent this.

System

Parameters:

<systemname>.sym

Type: Local

The automatically generated symbol file <systemname>.sym is loaded. The symbolic names for process types and Signal IDs can only be used if this file is read in.

Additional error checks can be performed within the SDL Target Tester's host if this file is read in.

T32-Command

Note:

The Lauterbach TRACE32 specific commands are only available if the according license is available.

Parameters:

<"command">

Type: local

The <"command"> can be any TRACE32 PRACTICE command like go, break or do.

T32-Configure

Parameters:

<none>

Type: local

To display symbolic names in the TRACE32's analyzer it is necessary to have all the symbolic names like Process-Types and Signals on TRACE32 side. Executing this command means to send all the symbolic names to the TRACE32.

T32-Generate-Cmm

Parameters:

<filename.cmm>

Type: local

The SDL Target Tester will generate a TRACE32 command file (.cmm) containing all the symbolic names of Process-Types, Process-Instances, Timers, Signals and States. This file can be used to configure the TRACE32 when using a Cmicro executable without SDL Target Tester or can even be used to configure from other command files.

?Timer-Table

Parameters:

(None)

Type: Remote

Some characteristics of the current timer tables are displayed. The command is useful in order to inspect the state of the SDL system, or to see if it is hanging.

Example 587

After typing the command, information is printed on screen which may look like:

Current Timer states:
SDL NOW :9147,d
Timer dimensioned to :6
Currently :0 timer(s) active
Timer memory location at :36bf0014,

Where SDL NOW represents the amount of units since system start. The value of 6 shows the maximum number of timer instances in the system. The third line is self explanatory. The last line gives the physical memory allocation of the timer linked lists which may ease debugging.

Tr-Detail

Parameters:

<level>

Type: Local

Define Trace detail. The command is applied locally within the SDL Target Tester's host and it works on ASCII traces to the text area only.

Output to either a file or to the MSC Editor will not be affected by this command. Thus if the target is configured correctly no inconsistency can occur and no information stored in a file or in the MSC Editor will be incomplete.

Five levels are defined (0-5). The higher the level, the more SDL events are traced. Different events are assigned the levels depicted in the following table:

Trace subject | L.1 | L.2 | L.3 | L.4 | L.5
PRINT STRING | * | * | * | * | *
TASK | - | - | - | - | *
DECISION | - | - | - | - | *
PROCEDURE | - | - | - | - | *
SET | - | - | - | * | *
RESET | - | - | - | * | *
ACTUAL RESET | - | - | - | - | -
STOP | - | - | - | * | *
STATE | - | * | * | * | *
STATIC CREATE | - | - | - | * | *
DYNAMIC CREATE | - | - | - | * | *
CREATE | - | - | - | * | *
SAVE | * | * | * | * | *
TIMER | * | * | * | * | *
INPUT | * | * | * | * | *
OUTPUT | - | - | * | * | *
DISCARD | * | * | * | * | *
IMPLICIT CONSUMPTION | * | * | * | * | *

Tr-Params

Parameters:

<const>

Type: Local

The trace of signal parameters can be switched on or off. This command has an influence on the display in the text area only.

<const> can take the values:

0 - to switch trace off or
1 - to switch the trace of signal parameters on

Tr-Process

Parameters:

<Processtype Instance> <Bitmask> or
ENV <Bitmask> or
* <Bitmask>

Type: Remote

This command defines which processes in the system are traced. It is applied in the target (remote command), so that the traffic load on the communications interface can be reduced interactively.

This trace command works for all instances of the given process type. No differentiation is possible between different instances of one type.

Tr-Signal

Parameters:

<signalname> <flag>

Type: Remote

This command defines the trace for one or all signals in the system. It is applied in the target (remote command), so that the communications interface's traffic load can be reduced interactively.

The signal name is the one from the SDL system. No qualifiers are possible, which means, that signal names have to be unique for the whole SDL system. The flag may be 0 (trace off) or any other value (trace on). If an asterisk is specified for signal name, then flag is applied to all signal types. The command works for SDL output only.

Tr-Off

Parameters:

(None)

Type: Remote

The command switches the SDL Target Tester's tracer off within the target. The current option settings stored in the target will not be affected. After this command is received within the target, the trace is immediately suspended and can only be resumed with the command Tr-On. The output trace that has been written is interrupted.

Note:

The user has to consider misinterpretation of the trace because of missing traces after resuming the trace via Tr-On.

Tr-On

Parameters:

(None)

Type: Remote

This command switches the Cmicro Tracer on, if it is compiled within the target. None of the current option settings concerning trace within the target will be affected.

Unit-Name

Parameters:

<unitname>

Type: Local

The timer unit's name can be assigned with this command, e.g. if the target's system time is `milliseconds' and the Unit-Scale is dimensioned to 1000, the <unit> should be named as `sec'.

Unit-Scale

Parameters:

(realvalue)

Type: Local

The target's system time, which is received with the trace data, is multiplied by this constant factor to get a "readable" system time. See Unit-Name too.


Graphical User Interface

This section describes the appearance and functionality of the graphical user interface of the SDL Target Tester (sdtmtui). Some user interface descriptions common to all tools in Telelogic Tau can be found in 1 User Interface and Basic Operations. These general descriptions are not repeated in this chapter.

Starting the SDL Target Tester UI

The SDL Target Tester UI is automatically started from the Cmicro Postmaster. When the UI is started the definition file for the button groups (see "The Button Area" ) is read in. The default name of this file is sdtmt.btn.

The Main Window

The main window provides a text area (which displays output from the monitor system), an input line (used for entering and displaying textual command line input to the monitor system) and a button area (with buttons for execution of monitor commands).

Figure 596 : The Main window

The Text Area

The text area displays all text output from the monitor system, including user prompts, error messages and command results.

Commands cannot be entered in this area, but a command given on the input line or through the use of the command buttons is echoed after the displayed prompt:

Command>

The Input Line

The input line is used for entering and editing monitor commands from the keyboard. For information on available monitor commands, see "Syntax of SDL Target Tester Commands" .

The last commands entered on the input line are saved in a history list. This list can be traversed by using the <Up> and <Down> keys on the input line.

When <Return> is pressed anywhere on the input line, the complete string is saved in the history list and is moved to the text area. The command is then executed.

Parameter Dialogs

If a command entered on the input line requires additional user input (i.e. parameter values), the information will automatically be prompted for in a dialog:

  • Parameter values of enumeration type are presented in lists, from which the value can be selected (see Figure 597).

Figure 597 : A typical selection dialog

The value can also be entered or edited on the text input line below the list in the dialog. For those commands that take an optional variable component, the component must be entered on the text input line after the selected variable name. It will not be asked for in a dialog.
  • Other parameter values are asked for in simple text input dialogs.

Each parameter dialog has an OK button for confirming the value and a Cancel button for cancelling the command.

The Button Area

The button area is used for entering monitor commands by clicking the left mouse button on a command button. Each button corresponds to a specific monitor command. The buttons are divided into groups, roughly corresponding to the different types of commands listed in "SDL Target Tester Commands" . Each group is shown as a module in the button area. Any number of button modules may reside in the button area. If the modules do not fit in the button area, a vertical scroll bar is added.

The definition of the buttons and button groups are stored in a button definition file (see "Button and Menu Definition File" ). New buttons can be added and existing ones deleted or redefined by using the Group menu in a button module.

If a button's definition contains parameters, the parameter values are prompted for in dialog boxes before the command is executed, in the same way as described for commands entered from the input line. See "Parameter Dialogs" .

When no more parameter values are requested, the string shown on the input line is saved in the history list and moved to the text area. The command is then executed.

A Button Module

Figure 598 : A button module

Each button module consists of a title bar and a number of command buttons arranged in rows and columns. The title bar displays:

  • A collapse/expand toggle button. Click this to collapse (so that only the title bar is visible) and expand the module.
  • The group name of the button module.
  • A Group button, providing a menu with commands affecting the buttons in the module.

The Group button contains the following menu choices:

Add

This menu choice opens a dialog where you may add one or several new buttons to the button module. You should specify a label of the new button and a command that is to be executed when the button is clicked. Click OK or Apply, to add the button to the end of the module. For the syntax of a button definition, see "Button and Menu Definitions" .

Figure 599 : Adding a new button

Note:

Several buttons are allowed to have the same name within the same module. When you edit the button definition or delete the button, it is always the first occurrence that will be deleted or modified.

Edit

This menu choice opens a dialog where you can select a button to edit, that is, its label and definition. You edit the button in a similar way as described in "Add" .

Note:

If several buttons have the same button label, it is always the first button found that will be edited, regardless of the selection.

Delete

This menu choice opens a dialog where you can select one or several buttons to be deleted.

Note:

If several buttons have the same button label, it is always the first button found that will be deleted, regardless of the selection.

Rename Group

This menu choice opens a dialog where you can edit the name of the current button module.

Delete Group

Select this menu choice deletes to delete the current module from the button area. You will be asked to confirm the operation.

The Default Button Modules

The following tables list the default buttons in the button modules and the corresponding monitor command. See "SDL Target Tester Commands" for more information.

Note:

The buttons in the button modules are specified in the button definition file. If the default button file is not used, the button modules may differ from those described here. See "Button and Menu Definitions" for more information.

The Environment Module

Button | SDL Target Tester command
Send without params | Output-NPAR
Send with params | Output-PAR

The Execute Module

Button | SDL Target Tester command
Go-Forever | Go-Forever

The Examine Module

Button | SDL Target Tester command
Queue | ?Queue
Process | ?Process-State
Last Error | ?Errors
Timers | ?Timer-Table
Process List | ?All-Processes
Active | Active-Timer
Profile | ?Process-Profile

The Change Module

Button | SDL Target Tester command
Set Timer | Set-Timer
Reset Timer | Reset-Timer
Create | Create
Stop | Stop
Nextstate | Nextstate
Remove Q | Remove-Queue
Remove S | Remove-Signal
Remove all S | Remove-All-Signals
Scale Timers | Scale-Timers

The Configure Text Trace Module

Button | SDL Target Tester command
ON | Display-On
OFF | Display-Off
Detail Level | Tr-Detail
Show Params | Tr-Params 1
Hide Params | Tr-Params 0

The Configure Target Trace Module

Button | SDL Target Tester command
ON | Tr-On
OFF | Tr-Off
Signal | Tr-Signal
Process | Tr-Process
NO Symbols | Tr-Process * B'00000000000000000000000000000000'
ALL Symbols | Tr-Process * B'111111111111111111111111111111111'

The SDL & MSC Trace Module

Button | SDL Target Tester command
Start MSC | Start-MSC-Log
Stop MSC | Stop-MSC-Log
Start SDL | Start-SDLE-Trace
Stop SDL | Stop-SDLE-Trace

The File Trace Module

Button | SDL Target Tester command
Binary Infile | Input-File
Binary Outfile | Output-File
Close binaries | Close-File
ASCII Outfile | Start-Trace-Log
Close ASCII | Stop-Trace-Log
Page File | Page-File
Convert File | Convert-File

The Recorder Module

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

Button | SDL Target Tester command
Recorder off | Recorder-Off
Record | Recorder-On
Play | Recorder-Play
Delay | Recorder-Delay
Real-time | Recorder-Realtime
Input recfile | Input-File recfile.trc
Output recfile | Output-File recfile.trc
Close recfile | Close-File recfile.trc

The Systemcontrol Module

Button | SDL Target Tester command
Single-Step | Single-Step
Next-Step | Next-Step
Exit-Single-Step | Exit-Single-Step
Reinit | Reinitialize
Shutdown | Shutdown
Resume | Resume
Disable Timer | Disable-Timer
Enable Timer | Enable-Timer
Suspend | Suspend

The Breakpoint Module

Button | SDL Target Tester command
Break input | BPI
Break nextstate | BPS
Break all | BP
View Breakpoints | ?Breaklist
Clear all | BA
Continue | Continue

The Configuration Module

Button | SDL Target Tester command
Unit scale | Unit-Scale 1.0
Unit name | Unit-Name "milliseconds"
Target | Get-Configuration

The Communication Module

Button | SDL Target Tester command
Start Gateway | Start-Gateway
Coder Config | ?Coder
Interface State | Line

The Menu Bar

This section describes the menu bar of the SDL Target Tester main window and all the available menu choices in the default configuration.

The menu bar contains the following fixed menus:

  • File Menu
  • View Menu
  • Buttons Menu
  • Help Menu
    (See "Help Menu" .)

The menu bar can also contain additional menus listed in a menu definition file (see "Button and Menu Definition File" ). The following menus are defined in the delivered version of this file:

  • Execute Menu
  • Environment Menu
  • Breakpoint Menu
  • Examine Menu
  • Change Menu
  • Trace Display Menu
  • Trace File Menu
  • Trace Target Menu
  • Recorder Menu
  • Config Menu
  • Commands Menu

File Menu

The File menu contains the following menu choices

  • Open
    (See "Open" .)
  • Set Directory
  • Exit
    (See "Exit" .)

Set Directory

This menu choice opens a dialog where you can enter the path to your current project directory.

View Menu

The View menu contains the following menu choices:

  • Find
  • Find Next (F3)
  • Find Selection
  • Copy from Text Area
  • Paste into Command Line
  • Line Numbering
  • Clear Text Area

Find

This menu choice opens a dialog where you can search for text.

Figure 600 : The Find dialog

It is possible to use regular expressions for finding text or to select to find a process, signal or timer belonging to the SDL system.

Find Next

This menu choice will search again for text already found.

Find Selection

This menu choice will search for text currently selected in the SDL Target Tester's text area.

Copy from Text Area

This menu choice will copy the text selected in the SDL Target Tester's text area.

Paste into Command Line

The menu choice will paste the content of the clipboard to the command line.

Line Numbering

This menu choice toggles line numbering in the SDL Target Tester's text area. Line numbering allows a better overview.

Clear Text Area

This menu choice will clear the complete text area of the SDL Target Tester.

Buttons Menu

The Buttons menu contains the following menu choices:

  • Load
  • Append
  • Save
  • Save As
  • Expand Groups
  • Collapse Groups
  • Add Group

For more information on the UI's button definition file, mentioned in the menu commands below, see "Button and Menu Definition File" .

Load

This menu choice opens a dialog where you can specify a new button definition file. This will override the current button definitions. All buttons and modules currently in the button area are deleted and replaced by the buttons and modules defined in the new file.

Append

This menu choice opens a dialog where you can specify to append the contents of a new button definition file into the current button definitions. Buttons with new labels are added to the button area, while buttons with already existing labels in the same module will be duplicated (possibly with different definitions).

Save

This menu choice saves the current button and module definitions in the button definition file under its current file name.

Save As

This menu choice opens a dialog where you can save the current button and module definitions in a new button definition file.

Expand Groups

This menu choice expands all modules in the button area.

Collapse Groups

This menu choice collapses all modules in the button area.

Add Group

This menu choice opens a dialog where you can specify the of a new button module to add. The new module will be added after the last module in the button area. It is also possible to add several modules.

Execute Menu

Item | SDL Target Tester command
Start Gateway | Start-Gateway
Go-Forever | Go-Forever
Single-Step | Single-Step
Reinit | Reinitialize
Disable-Timer | Disable-Timer
Next-Step | Next-Step
Shutdown | Shutdown
Enable Timer | Enable-Timer
Exit-Single-Step | Exit-Single-Step
Resume | Resume
Suspend | Suspend

Environment Menu

Item | SDL Target Tester command
Send with params | Output-PAR
Send without params | Output-NPAR

Breakpoint Menu

Item | SDL Target Tester command
Break Input | BPI
View Breakpoints | ?Breaklist
Break Nextstate | BPS
Clear all | BA
Break all | BP
Continue | Continue

Examine Menu

Item | SDL Target Tester command
Queue | ?Queue
Timers | ?Timer-Table
Active | Active-Timer
Process | ?Process-State
Process List | ?All-Processes
Profile | ?Process-Profile
Last Error | ?Errors

Change Menu

Item | SDL Target Tester command
Set Timer | Set-Timer
Stop | Stop
Remove Signal | Remove-Signal
Reset Timer | Reset-Timer
Nextstate | Nextstate
Remove all S | Remove-All-Signals
Create | Create
Remove Q | Remove-Queue
Scale Timers | Scale-Timers

Trace Display Menu

Item | SDL Target Tester command
Display on | Display-On
Display off | Display-Off
Trace Detail | Tr-Detail
Show Params | Tr-Params 1
Hide Params | Tr-Params 0
Start MSC | Start-MSC-Log
Stop MSC | Stop-MSC-Log

Trace File Menu

Item | SDL Target Tester command
Binary Infile | Input-File
ASCII Outfile | Start-Trace-Log trace.asc
Page File | Page-File
Binary Outfile | Output-File
Close ASCII | Stop-Trace-Log
Convert File | Convert-File
Close Binaries | Close-File

Trace Target Menu

Item | SDL Target Tester command
Trace on | Tr-On
Trace off | Tr-Off
Trace Process | Tr-Process
Trace Signal | Tr-Signal

Recorder Menu

Item | SDL Target Tester command
Recorder off | Recorder-Off
Delay | Recorder-Delay
Output recfile | Output-File recfile.trc
Record | Recorder-On
Realtime | Recorder-Realtime
Close Recfile | Close-File recfile.trc
Play | Recorder-Play
Input recfile | Input-File recfile.trc

Config Menu

Item | SDL Target Tester command
Unit scale | Unit-Scale
Unit name | Unit-Name
Target | Get-Configuration
Coder-Config | ?Coder
Interface state | Line

Commands Menu

Item | SDL Target Tester command
Quick Info | Help
Info | Help *
Remove cmd | Remove-Command

Button and Menu Definition File

In the SDL Target Tester UI, the button definition information is stored on file (per default this file is named sdtmt.btn), i.e. definitions of button groups and button commands in the main window's button area. Furthermore it is possible to define menu entries.

At start-up of the UI, the file is determined in the following way. If the file name does not contain a directory path, the files are searched for in the following directories:

  • The current directory
  • The Telelogic Tau installation directory

Once the file has been found, it is read and the contents of the corresponding window is set up. If the file cannot be found, the corresponding window area becomes empty and a file selection dialog is opened to enter the required file name.

The text file can contain comment lines starting with the `#' character. Empty lines are discarded.

Note:

When a file is read, no checks are made upon the relevance or correctness of the definitions contained in the file.

Button and Menu Definitions

The button and menu definitions are stored in a definition file with the default extension .btn. The definitions are divided into groups where each group defines a button module in the main window's button area or a menu in the menu bar.

Syntax

In the file, a button group has the following syntax:

:[DISPLAY_AS] <entry name>
<item label>
<definition>
<button label>
<definition>
. . .

The [DISPLAY_AS] prefixes the button group's or menu's name <entry name> and can take three different keywords:

  • COLLAPSED
    A button group is created, initially collapsed.
  • No keyword
    A button group is created, initially expanded.
  • MENU
    A new menu is created.

The <item label> is either the label of the button in a button module or the label of an menu item.

The <definition> is the SDL Target Tester command that will be executed when the button is pressed/the menu item is selected. The syntax of a button definition is the same as when entering a command textually to the monitor.

Missing parameters at the end of the command will open dialogs for those parameters.

After all there is no limit in the amount of buttons in a button group or the amount of items in a menu entry except the visibility and usability of the buttons/items.

Comparing with the Simulator there is a simple rule of ordering the buttons shown in Figure 601. A new button row is added only if the previous row has got 3 buttons.

Figure 601 : Ordering of the buttons in a button group


The Target Library

General

The target library is a mandatory part of the SDL Target Tester. The SDL Target Tester is of no use without the functions and definitions contained within.

In order to use the options of SDL Target Tester's host site, the target library must be configured accordingly.

A lot of defines make it possible to reduce the SDL Target Tester's functions within the target, so that memory requirements can be reduced when necessary.

In the following sections are explanations of the file structure and the application program interface (API) within the target.

File Structure

The following picture explains the file structure for the SDL Target Testers target library.

Figure 602 : Files of the Cmicro Library

Description of Files

sdl_cfg.h

This file is generated automatically by the Cmicro SDL to C Compiler into the directory which is currently active. It contains compilation flags used for the automatic scaling of the Cmicro Library and the generated C code. The file must not be edited by the user.

Caution!

This file always carries the same name for each SDL system generated and is stored into the currently active directory. A conflict will occur if the user tries to generate several systems into the same directory.

Therefore be sure to use different working directories for each SDL system. Otherwise, unpredictable results during run-time of the generated code will occur, as some automatic scalable features may not re-compiled.

ml_typ.h

This file is the central header file in the Cmicro Package. It contains

  • more #includes
  • defines which are of global interest and Cmicro Library internal defines
  • typedefs which are of global interest and Cmicro Library internal typedefs
  • extern-declarations which are of global interest and Cmicro Library internal extern declarations

tmcod.h

tmcod.h is an automatically generated file of the Target Message Coder Generator (TMCOD). All the SDL Target Tester command tags and the corresponding parameter structures are defined here. It is strongly recommended not to modify this file.

mt_cmd.c

This file is part of the command interface on the target site. The commands received via the communications link will be performed by this file.

mt_cod.c

This is the module which exports the functions to encode / decode any message from the Cmicro Protocol.

mt_opt.c

This module exports the functions which allow the user to define options regarding the tracer, recorder and player components.

Options may be specified to reduce the traffic load of the system, This is important when a slow communications interface is involved and the user wants to test in real-time.

mt_play.c

This file is part of the Cmicro Recorder and it contains all the functions for the play mode.

mt_rec.c

This file is part of the Cmicro Recorder and it contains all the functions for the record mode.

mt_tsdl.c

This module exports functions to trace SDL actions. These functions are mainly for the use of the Cmicro Kernel and Tester.

Functions to trace either into RAM, into a file or via a V.24 interface are delivered.

The module is common for all these trace methods. The functions exported are called directly by the Cmicro Kernel if the SDL Target Tester or part of the SDL Target Tester is involved when executing the SDL system.

mt_tsys.c

This module contains the functions which handle the trace of system events such as scheduler events or the trace of system errors.

mt_*.h

These header files contain the external definitions of the corresponding .c files.

The API on Target

General

The C application program interface (API) can be used both by SDL processes and / or by any other C function on the target.

The simplest method, however, is to set some options before initializing the SDL system and hold these options during the whole run-time. A more comfortable method is to set some options before initializing the SDL system and then change the options in an SDL process, when a specific situation is detected. By using this method it is possible to reduce the amount of information and to make it easier to find unwanted behavior or an erroneous situation in a trace. This can be achieved, for example, by writing the necessary C function call(s) into an SDL task symbol using the #CODE directive.

The following pages introduce the C function interface, which is used in the target to set the trace options.

Caution!

It is important to take care with function parameters. Any function return value should also be checked.

Initialization

void xmk_InitOptions ( void )

Initialization of the SDL Target Tester is absolutely necessary. It must be done before any other initialization, directly before the C function call xmk_InitSDL. The user should not remove this function call in the template main() function if one wants to use the SDL Target Tester.

Nothing happens before the C function xmk_OptionsSymbol is called, and xmk_TracerActive is set to XMK_TRUE.

Switch the Cmicro Tracer on / off

In order to get an execution trace it is first necessary to switch it on by assigning

xmk_TracerActive = XMK_TRUE

This should normally be done after the C function xmk_InitOptions.

The settings of functions whose names begin with xmk_Options* remains unaffected when changing the above flag.

The flag is not set by default.

Selecting SDL Symbols That are to Be Traced

xmk_OPT_INT xmk_OptionsSymbol ( unsigned char process-type-id,
long bitmask )

This function must be called in order to begin the trace. By default, no symbol is selected.

Select the trace for process-type-id and then set or un-set different symbols with the bit mask. If anything goes wrong the function will return XMK_ERROR, else XMK_OKAY.

It is possible to specify bit mask values for a specific SDL process, for all SDL processes, for the environment and for the kernel part of the Cmicro Library. The last possibility is necessary to allow the optional trace for system events like error trace and trace of scheduling events.

Allowed values for process-type-id:

0 | First process-type-id, XPTID_ from sdl_cfg.h
1 | Second.....
N-1 | Last... (N is the maximum number of process types)
xNULLTYPE | specify trace for all processes
any other value | The environment
MICROKERNEL | specify trace for Cmicro Kernel
ENV | Indicates the SDL environment

Allowed values for bit mask:

SDL symbols | System events
TSDL_STATE | TSYS_SCHEDULE
TSDL_INPUT | TSYS_ERROR
TSDL_SAVE | TSYS_SHOWPRIO
TSDL_OUTPUT |
TSDL_CREATE |
TSDL_STOP |
TSDL_STATIC_CREATE |
TSDL_DYNAMIC_CREATE |
TSDL_DECISION |
TSDL_TASK |
TSDL_PROCEDURE |
TSDL_RESULT |
TSDL_TIMER |
TSDL_SET |
TSDL_RESET |
TSDL_ACTUAL_RESET |
TSDL_SIGNALPARAMS |
TSDL_DISCARD |
TSDL_IMPLICIT_CONSUMPTION |

Selecting SDL Signals to Be Traced

xmk_OPT_INT xmk_OptionsSignal ( xmk_T_SIGNAL signal id,
unsigned char bitmask )

This function is optionally called because the trace of all SDL signals is switched on per default.

Select the trace for signal id. Then set or un-set different symbols with bit mask. If anything went wrong, the function will return XMK_ERROR, else XMK_OKAY.

It is possible to specify either "off" for all signals, "on" for all signals, "off" for a specific signal or "on" for a specific signal.

Allowed values for signal-id:

0 | First signal-id, #define from generated C code and <systemname>.ifc
1 | Second.....
N-1 | Last.....
XMK_ALLOW_NO | Specify trace for all processes
XMK_ALLOW_ALL | Specify trace for Cmicro Kernel

Allowed values for bitmask:

  • Any value in the range of 0x00 to 0xff.
  • A value != 0x00 switches the trace for the signal on.
  • A value == 0x00 causes the trace for the given signal(s) to be switched off.

Example to Set Trace Options

A simple method to set the trace options is to set them directly within the C function main, before the Cmicro Kernel is initialized. The user will find this example as a template in the file bare_ex.c delivered with the Cmicro Package, below the directory <sdtdir>/cmicro/template.

Example 588

#include "sdl_cfg.h"
#include "ml_typ.h"
... main ( ... ) {
extern int xmk_TracerActive ;
long bitmask = 0 ;
int result = XMK_OKAY ;

/* Initialize SDL Target Tester */
xmk_InitOptions ( );

/* Set all options ON */
result = xmk_OptionsSymbol (xNULLPID, 0xffffffff);
if (result != XMK_OKAY) ErrorInUsage ();

/* Set some options ON */
bitmask = TSDL_INPUT ;
bitmask = TSDL_STATE ;
bitmask = TSDL_OUTPUT ;

/* +---- Proces-Type - Id (see automatically */
/* | generated file *.ifc) */
/* V */
result = xmk_OptionsSymbol (0, bitmask );
if (result != XMK_OKAY) ErrorInUsage ();
result = xmk_OptionsSymbol (1, 0x00000000 );
if (result != XMK_OKAY) ErrorInUsage ();

/* S w i t c h o n t h e t r a c e */
xmk_TracerActive = XMK_TRUE ;
/* Template to set options to filter signals */
/* */
/* +---- Allow all Signals to be traced */
/* V */
xmk_OptionsSignal (XMK_ALLOW_NO, 0);
/* +---- Signal id is to be set correctly ! */
/* | according to the automatically */
/* | generated *.ifc - file */
/* V */
xmk_OptionsSignal (1, 0xff);
xmk_OptionsSignal (2, 0xff);
xmk_OptionsSignal (3, 0xff);
/* I n i t i a l i z e C m i c r o K e r n e l */
xmk_InitSDL ()

/* R u n C m i c r o K e r n e l */
if (xmk_RunSDL (0xff) != XMK_STOP);
exit (0);
}

Getting a Trace in SDL Tasks with C Code

The Cmicro SDL to C Compiler generates usable traces for SDL tasks only if it is a task containing at least one SDL assignment. Whenever C code is specified within a task symbol (by using the #CODE directive), the Cmicro SDL to C Compiler is not able to generate good trace information.

There are two C functions which enable a work-around:

  • xmk_PrintString (const char *) or
  • xmk_TSDL_Task (const char *)

in order to get a trace from C code. The trace output of a call like

xmk_PrintString ('Hello SDL world')

looks like:

USER: Hello SDL world

The strings have to be unique, in order to distinguish a trace of one process from another. Another difference between the above function is that the C function xmk_PrintString does not check if a trace is wanted or not. The trace will be done unconditionally via the SDL Target Tester's communications link.

Of course, the function may also be applied in non SDL program parts.

Using Record or Play Mode of the Cmicro Recorder

xmk_OPT_INT xmk_SetRecorderMode ( int mode )

This function must be called by the user in order to:

  • switch the record mode of the Cmicro Recorder on, or
  • switch the play mode of the Cmicro Recorder on, or
  • switch any function of the Cmicro Recorder off.

Allowed values for mode:

  • XMK_RECORDER_RECORD
  • XMK_RECORDER_PLAY
  • XMK_RECORDER_OFF

Environment Functions

xInEnv ()

void xInEnv ( void )

This function is called each time the Cmicro Kernel's main loop is entered. A more detailed description of the C function xInEnv() can be found in "xInEnv()" .

xOutEnv ()

int xOutEnv ( xmk_T_SIGNAL sig,
xmk_T_PRIO prio,
xmk_T_MESS_LENGTH data_len,
void *p_data,
xPID Receiver

This function is called each time the SDL system wants to output a signal to the environment. If the environment should be another system (e.g., an MS DOS PC), the signal can be sent directly by calling the C function xmk_Cod_Encode (which is described in the following section). A more detailed description of the C function xOutEnv can be found in "xOutEnv()" .

xmk_Cod_Decode ()

int xmk_Cod_Decode ( char *p_RAWBuffer, In
int *p_MessageClass, Out
int *p_MessageTag, Out
int *p_MessageLength, Out
char *p_dest, In/Out
int dest_len ) In

This function is free to be used on the target site. It decodes a given data link frame in the Cmicro Protocol format into the different pieces of data. MessageClass may be in the range from F3h to FFh. The value Fh in the higher nibble is used to synchronize the data stream if synchronization fails and 0h to 2h in the lower nibble is used by the SDL Target Tester itself. MessageTag may be of any value. p_struct is a pointer to a C structure which is to be transferred via the communications link. Struct_length is the result of the sizeof operator being applied to this structure.

The function is the counterpart to the C function xmk_Cod_Encode.

xmk_Cod_Encode ()

int xmk_Cod_Encode ( int MessageClass,
int MessageTag,
char *p_data,
int length )

This function is free to be used on the target site: It encodes the given information into a data link frame of the Cmicro Protocol format and sends it via the communications interface. MessageClass may be in the range from F3h to FFh, the value Fh in the higher nibble is used to synchronize the data stream if synchronization fails and 0h to 2h in the lower nibble is used by the SDL Target Tester itself. MessageTag may be of any value. p_struct is a pointer to a C structure which is to be transferred via the communications link. Struct_length is the result of the sizeof operator being applied to this structure.

The function is the counterpart to the C function xmk_Cod_Decode.

Note:

The maximum amount of characters which can be transferred is restricted to 255 per default in this Cmicro Package version.

Compiling and Linking the Target Library

Some defines are to be set in order to compile and link the parts of the SDL Target Tester correctly. These defines can be set either on the command line when invoking make or in the header file ml_mcf.h. Be sure that for each configuration possibility all the defines are set appropriately.

The best way to select the compiler options for the SDL Target Tester is to use the Targeting Expert. Please view the section "Configure the SDL Target Tester (Cmicro only)" .

Here is a first idea of what has to be to set in the configuration file ml_mcf.h:

#define XMK_ADD_MICRO_TESTER
#define XMK_ADD_MICRO_TRACER
#define XMK_USE_V24
#define XMK_USE_COMMLINK

Scaling of SDL Target Tester Functionality

In order to reduce the amount of memory - e.g. if memory gets scarce within a progressing project - it is possible to reduce the SDL Target Tester's functionality on target site.

Removing the whole SDL Target Tester

It is quite simple to remove any functionality used by the SDL Target Tester by specifying:

#undef XMK_ADD_MICRO_TESTER

Removing the Cmicro Tracer

This is possible by specifying

#define XMK_ADD_MICRO_TESTER
#undef XMK_ADD_MICRO_TRACER

Removing the Cmicro Recorder (Inclusive Play Mode)

This is possible by specifying

#define XMK_ADD_MICRO_TESTER
#undef XMK_ADD_MICRO_RECORDER

Removing the Command and Debug Interface

This is possible by specifying

#define XMK_ADD_MICRO_TESTER
#undef XMK_ADD_MICRO_COMMAND

Partial functionality may be left out by un-defining one of the defines described under "Message Transfer and Presentation of Messages" .

Configuration of Buffers

Users must configure buffers used by the SDL Target Tester.

The reason behind this is that the SDL Target Tester uses an efficient way to handle those buffers. This is of great importance especially for micro controllers.

Additionally, these buffers must be consistently dimensioned. For instance, the message buffer of the communications link must be able to handle the largest parameter list of a signal from SDL. The same situation arises in the trace of SDL tasks and procedure names.

Caution!

If any buffer is dimensioned too small a run-time error may result.

The following defines are used to dimension buffers.

XMK_MAX_PRINT_STRING

This define restricts the amount of characters transferred via the communications link when using the C function xmk_PrintString. This function is used only by the user.

XMK_MAX_LEN_SYMBOL_NAME

This define is used to restrict the amount of characters transferred via the communications link for the SDL tasks and SDL procedure names.

The transmit and receive buffers of the default communications link software must be configured in the data link (dl) module using the following defines:

Transmitter buffer:

#define XMK_MAX_SEND_ONE_ENTRY 1000
#define XMK_MAX_SEND_ENTRIES 20

Receiver buffer:

#define XMK_MAX_RECEIVE_ONE_ENTRY 1000
#define XMK_MAX_RECEIVE_ENTRIES 20

where *_ONE_ENTRY is the dimensioning of one message, and *_ENTRIES is the maximum amount of entries in the message FIFO of the data link module. Note, that *_ONE_ENTRY must be greater than the greatest of the XMK_MAX_* defines above, plus a reserve of 6 bytes.


Connection of Host and Target

General

The following sections will detail the technical requirements and the technical implementation of the connection between host and target. The following items will be outlined:

  • "Structure of Communications Link Software"
  • "Default Implementation of Communications Link Software" as delivered.
  • How to implement user host executables, which are able to communicate with the SDL Target Tester's target library. This is described in the subsection "Open Interface" .

Structure of Communications Link Software

This is the structure for the communications link software, which is - in principle - applicable for host, as well as for target site:

Figure 603 : Structure of the communications link software

The following subsections describe the current implementation and how to implement a new communications link software.

Default Implementation of Communications Link Software

Message Transfer and Presentation of Messages

State Machine and Handshake

For all the commands and messages, there is a small state machine to handle the correct transfer of information. All messages, which have the suffix _REQ (request) in their name (message tag) are to be confirmed from the target with one of the _CNF (confirmation) messages. (See the file tmcod.h, where all message tags are defined).

For messages which take parameters, there is always (no exception) a special _CNF message which carries the response parameters back to the requestor. The requestor is usually the host.

For the messages, which do not carry parameters, a positive confirmation is done via the message CMD_OKAY_CNF.

If a message cannot be recognized or processed within the target, a negative confirmation CMD_ERROR_CNF is used in all cases.

Each _REQ message must be confirmed before the next one can be sent.

Messages with an _IND (indication) suffix are mostly sent from target to host in order to indicate a specific situation. For these messages, the sender is always the originator.

Message Formats

The following subsections give a complete list of messages which can be sent to and received from the target.

Each typedef shown below is packed into a data link frame in its target representation.

That means a memcpy (destbuffer,struct,sizeof(struct)) is performed to copy a structure to/from the data link frame.

On host site, it is therefore necessary to perform message encoding and message decoding.

Formats Concerning the Cmicro Tracer

All messages belonging to the Cmicro Tracer are part of the message class XMK_MICRO_TRACER (F1h).

  • Message tag: CMD_TTASK
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Task
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TTASK
Conditional compile:XMK_ADD_TTASK
Message description: The message is sent when a task symbol is entered in generated C Code and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TSET
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Set
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TSET
Conditional compile:XMK_ADD_TSET
Message description: The message is sent when a timer set is performed in generated C Code and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TRESET
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Reset
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TRESET
Conditional compile:XMK_ADD_TRESET
Message description: The message is sent when a timer reset is performed in generated C Code and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TSTOP
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Stop
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TSTOP
Conditional compile:XMK_ADD_TSTOP
Message description: The message is sent when an SDL process stop is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TSTATE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL State
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TSTATE
Conditional compile:XMK_ADD_TSTATE
Message description: The message is sent when an SDL nextstate is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TSTATIC_CREATE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Static create
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TSTATIC_CREATE
Conditional compile:XMK_ADD_TSTATICCREATE
Message description: The message is sent for each statically created SDL process for which the start transition is executed and for which the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TCREATE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Create
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TCREATE
Conditional compile:XMK_ADD_TCREATE
Message description: The message is sent when the SDL action create is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TDYNAMIC_CREATE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Dynamic create
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TDYNAMIC_CREATE
Conditional compile:XMK_ADD_TDYNAMICCREATE
Message description: The message is sent for each dynamically created SDL process, when its start transition is executed, and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TDECISION
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Decision
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TDECISION
Conditional compile:XMK_ADD_TDecisionValue
Message description: The message is sent when an SDL decision is executed and the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TSAVE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Save
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TSAVE
Conditional compile:XMK_ADD_TSAVE
Message description: The message is sent when a signal save is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TTIMER
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Timer
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TTIMER
Conditional compile:XMK_ADD_TTIMER
Message description: The message is sent when an SDL timer has expired and is input into the owner process and the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TINPUT
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Input
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TINPUT
Conditional compile:XMK_ADD_TINPUT
Message description: The message is sent when an SDL input is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TPROCEDURE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Procedure
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TPROCEDURE
Conditional compile:XMK_ADD_TNAME
Message description: The message is sent when an SDL procedure is entered and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TOUTPUT
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Output
Sent when :Execution of that SDL symbol
Direction :T->H
Typedefinition :xmk_T_CMD_TOUTPUT
Conditional compile:XMK_ADD_TOUTPUT
Message description: The message is sent when an SDL output is performed and the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TDISCARD
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Discard
Sent when :Execution of that SDL symbol
Direction :T->H
Typdefinition :xmk_T_CMD_TDISCARD
Conditional compile:XMK_ADD_TDISCARD
Message description: The message is sent when an SDL discard has been detected and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_PRINT_STRING
Messageclass :XMK_MICRO_TRACER
Meaning :User command Print string
Sent when :Execution of fct.xmk_PrintString()
Direction :T->H
Typedefinition :xmk_T_CMD_PRINT_STRING
Conditional compile:XMK_ADD_CPRINT_STRING
Message description: The message is sent unconditionally, when the C function xmk_PrintString is called by the user.
  • Message tag: CMD_TIMPLICIT_CONSUMPTION
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Implicit consumption
Sent when :Implicit consumption occurs
Direction :T->H
Typdefinition :xmk_T_CMD_TIMPLICIT_CONSUMTION
Conditional compile:XMK_ADD_TIMPLICIT_CONSUMPTION
Message description: The message is sent when an SDL implicit consumption is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
  • Message tag: CMD_TACTUAL_RESET
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of SDL Actual reset
Sent when :SDL timer is actually reset
Direction :T->H
Typedefinition :xmk_T_CMD_TACTUAL_RESET
Conditional compile:XMK_ADD_TACTUAL_RESET
Message description: The message is sent when an SDL timer is actually reset and the trace is set for this symbol. Furthermore, the trace must be active. An actual reset applies only if a timer was previously set and has not expired.
  • Message tag: CMD_TSYS_ERROR
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of system error
Sent when :Any kind of systemerror was detected
Direction :T->H
Typedefinition :xmk_T_CMD_TSYS_ERROR
Conditional compile:XMK_ADD_TERROR
Message description: The message is sent when a system error of any type has been detected and the trace is set for this event. Furthermore, the trace must be active.
  • Message tag: CMD_TSYS_SCHEDULE
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of system schedule event
Sent when :When scheduling is performed
Direction :T->H
Typedefinition :xmk_T_CMD_TSYS_SCHEDULE
Conditional compile:XMK_ADD_TSCHEDULE
Message description: The message is sent when the Cmicro Kernel begins scheduling and the trace is set for this event. Furthermore, the trace must be active.
  • Message tag: CMD_TSYS_SHOWPRIO
Messageclass :XMK_MICRO_TRACER
Meaning :Trace of system event : change priority level
Sent when :When changing to another prioritylevel
Direction :T->H
Typedefinition :xmk_T_CMD_TSYS_SHOWPRIO
Conditional compile:XMK_ADD_TSHOWPRIO
Message description: The message is sent when the Cmicro Kernel schedules from one priority level to another and the trace is set for this event. Furthermore, the trace must be active.
  • Message tag: CMD_TBETWEEN_SYMBOL
Messageclass :XMK_MICRO_TRACER
Meaning :Another symbol than input is executed
Sent when :Another symbol than input is executed
Direction :T->H
Typedefinition :xmk_T_CMD_TBETWEEN_SYMBOL
Conditional compile:XMK_ADD_SDLE_TRACE
Message description: With this command the process ID of the current executed process is sent and a system wide unique identifier. The SDL Target Tester can force the SDL Editor to highlight the current SDL symbol.
  • Message tag: CMD_TAT_FIRST_SYMBOL
Messageclass :XMK_MICRO_TRACER
Meaning :An Input symbol has bee executed
Sent when :An Input symbol is executed
Direction :T->H
Typedefinition :xmk_T_CMD_TAT_FIRST_SYMBOL
Conditional compile:XMK_ADD_SDLE_TRACE
Message description: Similar like CMD_TBETWEEN_SYMBOLS the currently executed SDL input symbol will be highlighted in the SDL Editor.

Formats Concerning the Cmicro Recorder

All messages belonging to the Cmicro Recorder are part of the message class XMK_MICRO_RECORDER (F2h).

  • Message tag: CMD_RECORD_COUNT_IND
Messageclass :XMK_MICRO_RECORDER
Meaning :Show recorded event counter to host
Sent when :When ENV->SDL stimuli detected
Direction :T->H
Typedefinition :xmk_CMD_RECORD_COUNT_IND
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: The message is sent when the Cmicro Recorder is active and is in record mode. It is sent together with, but always before CMD_RECORD_OUTPUT_ENV2SDL.
  • Message tag: CMD_RECORD_OUTPUT_ENV2SDL
Messageclass :XMK_MICRO_RECORDER
Meaning :Indicate stimuli ENV->SDL to host
Sent when :When ENV->SDL stimuli detected
Direction :T->H
Typedefinition :xmk_T_CMD_RECORD_OUTPUT_ENV2SDL
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: The message is sent when the Cmicro Recorder is active and is in record mode. It is sent after CMD_RECORD_COUNT_IND.
  • Message tag: CMD_RECORD_OUTPUT_SDL2ENV
Messageclass :XMK_MICRO_RECORDER
Meaning :unused
Sent when :-
Direction :T->H
Typedefinition :-
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: This message is currently unused and is never sent.
  • Message tag: CMD_PLAY_SECTION_REQ
Messageclass :XMK_MICRO_RECORDER
Meaning :Request next sections from host
Sent when :When current cnt reaches debit cnt
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent if the target has to put in the next stimuli (an environment signal).
  • Message tag: CMD_PLAY_COUNT
Messageclass :XMK_MICRO_RECORDER
Meaning :Transfer Debitcounter to target
Sent when :When target requests next sections
Direction :H->T
Typedefinition :xmk_T_CMD_PLAY_COUNT
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent if the target requests the next stimuli (an environment signal). It is also sent in the initialization phase of the play mode. Outside the initialization phase, it is always sent together with, but after CMD_PLAY_OUTPUT_ENV2SDL.
  • Message tag: CMD_PLAY_OUTPUT_ENV2SDL
Messageclass :XMK_MICRO_RECORDER
Meaning :Transfer stimuli ENV->SDL to target
Sent when :When target requests next sections
Direction :H->T
Typedefinition :xmk_T_CMD_PLAY_OUTPUT_ENV2SDL
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent together with CMD_PLAY_COUNT but always before CMD_PLAY_COUNT if the target request the next stimuli (an environment signal).
  • Message tag: CMD_PLAY_OUTPUT_SDL2ENV
Messageclass :XMK_MICRO_RECORDER
Meaning :unused
Sent when :-
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: This message is currently unused and is never sent.
  • Message tag: CMD_RECORDER_OFF
Messageclass :XMK_MICRO_RECORDER
Meaning :Switch off recorder
Sent when :When at end of replay session detected
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_MICRO_RECORDER
Message description: This message is sent if the host detected an end of file after the target has requested the next stimuli (an environment signal). It switches the Cmicro Recorder within the target off and execution returns from simulation to real-time.

Formats Concerning the Command and Debug Interface

All messages belonging to the Cmicro Commands are part of the message class XMK_MICRO_COMMAND (F0h).

  • Message tag: CMD_SUSPEND_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Suspend Cmicro Kernel
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CSUSPEND
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_RESUME_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Resume Cmicro Kernel
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CRESUME
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SYSTEM_REINIT_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Reinitialize SDL system
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CREINIT
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SYSTEM_SHUTDOWN_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Shutdown SDL system
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CSHUTDOWN
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SINGLE_STEP_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Go into single step
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CSINGLE_STEP
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_DISABLE_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Disable processing of timers
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CDISABLE_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_ENABLE_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Enable processing of timers
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CENABLE_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_NEXT_STEP_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Execute next step
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CNEXT_STEP
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SYSTEM_CONTINUE_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Continue system, if halted
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CCONTINUE
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SET_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Set breakpoint
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T__CMD_SET_BREAKPOINT_REQ
Conditional compile:XMK_ADD_CBREAK_LOGIC
Message description: This message is send if the user typed in the appropriate command.
  • Message tag: CMD_BREAK_INPUT_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Set breakpoint on SDL input
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_BREAK_INPUT_REQ
Conditional compile:XMK_ADD_CBREAK_LOGIC
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_BREAK_STATE_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Set breakpoint on nextstate
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_BREAK_STATE_REQ
Conditional compile:XMK_ADD_CBREAK_STATE
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_CLEAR_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Clear specified breakpoint from list
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_CLEAR_BREAKPOINT_REQ
Conditional compile:XMK_ADD_CBREAK_LOGIC
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_CLEAR_ALL_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Clear all breakpoints
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CBREAK_LOGIC
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_QUERY_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query the breakpoint list
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CBREAK_LOGIC
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_QUERY_ERROR_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query last error occured in system
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CQUERY_ERROR
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_NEXT_STATE_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Modify processstate to value
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_NEXT_STATE_REQ
Conditional compile:XMK_ADD_CNEXTSTATE
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_CREATE_PROCESS_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Create SDL process
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_CREATE_PROCESS_REQ
Conditional compile:XMK_ADD_CCREATE_PROCESS
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_TBUF_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query Tracebuffer
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CTBUF
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_KILL_PROCESS_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Kill process
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_KILL_PROCESS_REQ
Conditional compile:XMK_USE_CMD_KILL&XMK_ADD_CKILL_PROCESS
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_PCO_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Define PCO
Sent when :unused
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is currently not implemented and is never sent.
  • Message tag: CMD_QUERY_PROCESS_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query process state
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_QUERY_PROCESS_REQ
Conditional compile:XMK_ADD_CQUERY_PROCESS
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_QUERY_QUEUE_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query all queues
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CQUERY_QUEUE
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_RMQUEUE_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Flush all queues
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CRM_QUEUE
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SET_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Set SDL timer
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_SET_TIMER_REQ
Conditional compile:XMK_ADD_CSET_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_RESET_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Reset SDL timer
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_RESET_TIMER_REQ
Conditional compile:XMK_ADD_CRESET_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_QUERY_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query timertables
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:XMK_ADD_CQUERY_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_ACTIVE_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Query, if timer active
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_ACTIVE_TIMER_REQ
Conditional compile:XMK_ADD_CACTIVE_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_FLUSH_SIGNAL_BY_SID_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Flush signals with given ID
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_FLUSH_SIGNAL_BY_SID_REQ
Conditional compile:XMK_ADD_CFLUSH_SIGNAL_BY_SID
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_FLUSH_SIGNALS_BY_PID_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Flush signals of process
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_FLUSH_SIGNALS_BY_PID_REQ
Conditional compile:XMK_ADD_CFLUSH_SIGNALS_BY_PID
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_RESET_ALL_TIMERS_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Reset all timers
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_RESET_ALL_TIMERS_REQ
Conditional compile:XMK_ADD_CRESET_ALL_TIMERS
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_SCALE_TIMER_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Scale timers
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_SCALE_TIMER_REQ
Conditional compile:XMK_ADD_CSCALE_TIMER
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_START_SDL_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Starts the SDL system
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_START_SDL_REQ
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_OUTPUT_TO_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Sends a signal from the environment
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_OUTPUT_TO_REQ
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_OUTPUT_INTERNAL_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Sends an internal signal
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_GET_CONFIG_REQ
Messageclass :XMK_MICRO_COMMAND
Meaning :Gets the target's configuration
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_REC_OFF
Messageclass :XMK_MICRO_COMMAND
Meaning :Switch recorder off
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_REC_PLAY
Messageclass :XMK_MICRO_COMMAND
Meaning :Switch recorder to play mode
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_REC_RECORD
Messageclass :XMK_MICRO_COMMAND
Meaning :Switch recorder to record mode
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_TRACE_ON
Messageclass :XMK_MICRO_COMMAND
Meaning :Switch trace on in general
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_TRACE_OFF
Messageclass :XMK_MICRO_COMMAND
Meaning :Switch trace off in general
Sent when :User typed in command
Direction :H->T
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_TRACE_PROCESS
Messageclass :XMK_MICRO_COMMAND
Meaning :Modify traceoptions for process
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_TRACE_PROCESS
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_TRACE_SIGNAL
Messageclass :XMK_MICRO_COMMAND
Meaning :Modify traceoptions for signal
Sent when :User typed in command
Direction :H->T
Typedefinition :xmk_T_CMD_TRACE_SIGNAL
Conditional compile:-
Message description: This message is sent if the user typed in the appropriate command.
  • Message tag: CMD_BREAK_HIT_IND
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate breakpoint hit to host
Sent when :Breakpoint hit in target
Direction :T->H
Typedefinition :xmk_T_CMD_BREAK_HIT_IND
Conditional compile:XMK_ADD_CBREAK_LOGIC
Message description: This message is sent if one of the breakpoints defined in the breaklist has been hit. The SDL system is halted and waits on the next commands from that point on.
  • Message tag: CMD_ERROR_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Negative acknowledge on command
Sent when :A command couldn't be executed
Direction :T->H
Typedefinition :-
Conditional compile:-
Message description: This message is sent if the target was not able to respond to a command from the user.
  • Message tag: CMD_TBUF_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate Tracebuffercontents
Sent when :Response to user command
Direction :T->H
Typedefinition :-
Conditional compile:-
Message description: This message is currently not implemented and will never be sent.
  • Message tag: CMD_OKAY_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Command acknowledge
Sent when :Command correctly executed
Direction :T->H
Typedefinition :-
Conditional compile:unconditional
Message description: This message is sent from target to host as a response for all commands which do not carry parameters of any kind. It is used within the host library as a general confirmation of most messages.
  • Message tag: CMD_QUERY_PROCESS_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate process state
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_QUERY_PROCESS_CNF
Conditional compile:XMK_ADD_CQUERY_PROCESS
Message description: This message is sent as a reaction to the message CMD_QUERY_PROCESS_REQ. It carries information about the process state.
  • Message tag: CMD_QUERY_QUEUE_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate queue states
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_QUERY_QUEUE_CNF
Conditional compile:XMK_ADD_CQUERY_QUEUE
Message description: This message is sent as a reaction to the message CMD_QUERY_QUEUE_REQ. It carries information about the queue state.
  • Message tag: CMD_QUERY_TIMER_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate timer table
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_QUERY_TIMER_CNF
Conditional compile:XMK_ADD_CQUERY_TIMER
Message description: This message is sent as a reaction to the message CMD_QUERY_TIMER_REQ. It carries information about the timer tables.
  • Message tag: CMD_ACTIVE_TIMER_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate, if timer is active
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_ACTIVE_TIMER_CNF
Conditional compile:XMK_ADD_CACTIVE_TIMER
Message description: This message is sent as a reaction to the message CMD_ACTIVE_PROCESS_REQ. It carries information about the state of a timer according to SDL semantics.
  • Message tag: CMD_QUERY_BREAKPOINT_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate breaklist to host
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_QUERY_BREAKPOINT_CNF
Conditional compile:-
Message description: This message is sent as a reaction to the command CMD_QUERY_BREAKPOINT_REQ. It carries the breaklist from target to host.
  • Message tag: CMD_QUERY_ERROR_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate last error occured
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_QUERY_ERROR_CNF
Conditional compile:-
Message description: This message is sent as a reaction to the message CMD_QUERY_ERROR_REQ. It carries information about the last error which has occurred in the target.
  • Message tag: CMD_START_SDL_IND
Messageclass :XMK_MICRO_COMMAND
Meaning :Indicate ready for configuration
Sent when :Response to user command
Direction :T->H
Typedefinition :-
Conditional compile:-
Message description: This message is sent when the target is ready for configuration from the host. In this state the target's SDL system is not initialized.
  • Message tag: CMD_START_SDL_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :Confirm SDL system start
Sent when :Response to user command
Direction :T->H
Typedefinition :-
Conditional compile:-
Message description: This message is sent as a reaction to the message CMD_START_SDL_REQ.
  • Message tag: CMD_GET_CONFIG_IND
Messageclass :XMK_MICRO_COMMAND
Meaning :Send target's configuration
Sent when :Automatic at startup
Direction :T->H
Typedefinition :xmk_GET_CONFIG_IND
Conditional compile:-
Message description: This is the second message which shows the target configuration. This means the scaling configuration (ml_mcf.h) as well as run-time configuration.
  • Message tag: CMD_GET_DATA_CONFIG_IND
Messageclass :XMK_MICRO_COMMAND
Meaning :see description below
Sent when :Automatic at startup
Direction :T->H
Typedefinition :xmk_GET_DATA_CONFIG_IND
Conditional compile:XMK_USE_AUTO_MCOD
Message description: This is the first message which indicates the target's length, alignment and endians of the basic c-data types.
  • Message tag: CMD_GET_CONFIG_CNF
Messageclass :XMK_MICRO_COMMAND
Meaning :
Sent when :Response to user command
Direction :T->H
Typedefinition :xmk_T_CMD_GET_CONFIG_CNF
Conditional compile:-
Message description: This message is the reply message to the host's CMD_GET_CONFIG_REQ. It sends the same information as CMD_GET_CONFIG_IND.

Used Default Protocol

The data link part of the communications link is represented by the data link module and the coder module. The coder module ensures that each data link frame is encoded / decoded according to definitions of the default protocol.

  • The protocol delivered with the Cmicro Package is easy to modify.
  • It allows transfer of all the data necessary for each part of the SDL Target Tester
  • It allows the transfer of user defined data to be integrated.
  • No handshake procedure or retransmission request is implemented

Each frame of the Cmicro Protocol is seen from the physical layer as binary data.

Each frame consists of the following items:

  • Message Class
    Used to classify the information (is it SDL Target Tester or User defined data?). The codes F3h to FFh are free to use by the user, the other ones are reserved for the SDL Target Tester.
  • Message Tag
    Used to differentiate the different information either of the SDL Target Tester or the user defined data. For user defined data, the message tag is free to use. If more than 255 bytes are to be transferred, the most significant bit of the message tag is set, otherwise it is cleared. This means there are up to 128 free values for the message tag.
  • SYNC
    Fixed marker 0xaa is used to check if the receiver is synchronized with the sender. This is to detect problems in the start-up phase of host and target. This field of the message header is used in combination with the message class (>= F0h) to re-synchronize the data stream in the host's data link layer (sdtgate).
  • Message Length
    Used to store the information about how many bytes are to follow after the length information, excluding the CRC information. The message length is normally encoded in one octet, which means the following data has a maximum length of 255 octets. If there is more data the most significant bit of the message tag is used to indicate that the message length exceeds 255 octets. In that case the message length is encoded in 2 octets which makes it possible to transfer 65536 octets of data.
  • Data
    Free formatted data (user data or data for the SDL Target Tester).
  • Checksum
    Used to check if the frame is OK on the receiving site. The checksum is built beginning from tag1 to the last data byte by a modulo-8 operation. The sync byte is included in the CRC.

The following is an example of a coded Cmicro Protocol frame for a MS DOS PC, where the message tag is coded as CMD_TSTATIC_CREATE. Note this is only an example and the real coding may be different.

Example 589 : Coding for MS-DOS PC

Message-class | Message-tag | SYNC | Message- length | -any kind of data- | Checksum
0xF1 | 0x06 | 0xAA | 0x02 |  | 0x??

The functions described in "The API on Target" can be used to encode / decode these frames.

The Communications Link's Target Site

The Data Link Layer

General

The data link of the communications link usually handles the separately message transfer of information from host and to host.

The data link uses the services and functions of the physical layer in order to transmit and receive information.

The data link offers functionality that makes it possible to send and to receive messages via the physical layer assigned to the data link. This functionality can be used by all programs (if implemented so). Mainly it is the SDL Target Tester which uses the data link layer services in order to send and to receive messages. But the users may want to send and receive messages, too. This is possible by using the data link layer functions and by regarding the defined protocol used for each message.

The data link layer offers the following functionality:

  • Receive a message from any part of the system like kernel SDL processes or user defined C functions.
  • Store messages in a buffer.
  • If the physical layer is ready with the transfer of the last message, send the next message to the physical layer.
  • If the physical layer indicates a complete message, store it into the receiving buffer.
  • Deliver the messages, which have been stored within the receiving buffer to the requesting program parts.
  • Poll the physical layer.
  • Handle both directions in parallel.
  • CRC procedures (if necessary).

The data link layer is represented by the following functions, which are exported by the data link (mg_dl) module.

Data Link Functions Used by SDL Target Tester

The SDL Target Tester's target library uses the following C functions of the link and buffering file mg_dl.c. The body of each C function may be rewritten according to the users needs.

 xmk_DLInit
Initialization of data link

 xmk_DLQuery
Polling the receiver of data link

 xmk_DLRead
Reading a message from data link

 xmk_DLWrite
Writing a message to data link

 xmk_DLDeinit
Deinitialization of data link

These functions are fixed into the SDL Target Tester's data link layer and they handle the mapping and the access to the physical layer.

The Physical Layer

General

Any type of physical communications link can be used to connect host and target, e.g. it could be a V.24, a TCP/IP or a IEEE 488 interface or it could be any other serial or parallel interface.

The physical layer of the communications link normally handles the byte-wise transfer of messages from host to target and the other way around.

It uses the services of the underlaying hardware like interrupts, CPU registers or memory mapped I/O.

The physical layer offers functionality to the data link layer in order to make it possible to transfer any kind of information, including SDL Target Tester data and / or user data.

The physical layer offers the following functionality:

  • Receive a buffer which is to be transferred from the data link layer.
  • Send this buffer byte-wise via special hardware (or OS - system call) to the receiving system (either host or target).
  • If all characters of this buffer have been transmitted, request next buffer.
  • Receive characters from the sending system via special hardware (or OS - system call).
  • Collect characters until a message is complete; characters are stored within a temporary buffer.
  • If message is complete in temporary buffer, transfer it to the data link layer.
  • Handle both directions simultaneously.
  • CRC procedures (if necessary).

Physical Layer Functions Used by the Data Link Layer (Default)

As described above the data link layer of the SDL Target Tester's target library is shown in the files mt_cod.c and mg_dl.c. Please note that mg_dl.c is only a template with a default implementation for the connection between data link and physical layer.

Distributed with the SDL Target Tester's target library, there are several template files for the physical layer (TCP/IP and V.24 interfaces) contained in the cmicro/template/commlink directory in the installation directory. These template files are tested only for the specific hardware in the Cmicro Package test environments. An error free compilation or execution cannot be guaranteed for the user's target hardware.

There are physical layer templates for the following target hardware:

  • Intel 8051 derivatives -> 8051_v24.[ch]
    Franklin/Keil C51 and IAR C51 compilers
  • Siemens 80C166 -> 80166v24.[ch]
    BSO/Tasking 80C166 compiler
  • MS Windows NT/95 -> win32v24.[ch]
    Borland C++ 5.x compiler, Microsoft VC++ 6.00
  • MS Windows NT/95 -> win_sock.[ch]
    Borland C++ 5.x compiler, Microsoft VC++ 6.00
  • SunOS 5.x -> ux_sock.[ch]
    GNU gcc, Sun WorkShop compilers CC and cc
  • HP-UX 10.xx -> ux_sock.[ch]
    GNU gcc, HP compiler aCC and cc

For use in the target executable, one of the modules listed above is automatically included in mg_dl.c. Which physical layer module is included depends on the compiler selected and the flags set in ml_mcf.h (e.g. XMK_USE_V24 or XMK_USE_SOCKETS).

The template module mg_dl.c works as follows:

The function xmk_DLInit initializes the buffers used for the data link and calls the initialization of the physical layer (by default this is xmk_V24Init).

xmk_DLDeinit is the counterpart of xmk_DLInit and frees the interface device. This function is normally empty in microcontroller applications but has to be used on PCs, under Microsoft Windows or UNIX.

xmk_DLWrite is called when a complete frame should be sent to the host. There are two ways the connection to the physical layer can be handled.

  1. Blocked
    If a frame is to be sent it is necessary that the previous frame has already been completely sent. If not, the data link has to wait until the previous frame is sent. See the module mg_dl.c (for the compilers KEIL_C51 and IARC51) to get an idea of this connection.
  2. Unblocked
    If the frame should be sent, it is handed over to a ring buffer. Although the previous frame has not been sent completely, SDL can execute because the data link does not have to wait.
    One exception must be mentioned: If the transmitter's ring buffer (used for V.24 communication) is full (macro XMK_MAX_SEND_ENTRIES) the data link will still have to wait here. Also the size allowed for the ring buffer's entries must be great enough (to verify this see the macro XMK_MAX_SEND_ONE_ENTRY.

xmk_DLRead will be polled with each cycle of the SDL loop xmk_RunSDL (see module mk_main.c). If the transmitter and the receiver of the physical layer are not implemented as interrupt service routines (which is strongly recommended) the transmit and receive functions have to be called here (xmk_V24Receive and xmk_V24Send for the distributed V.24 templates). In addition for the V.24 interface the XON handshake has to be called here doing xmk_V24Handshake.

As in xmk_DLWrite there are two ways the receiver buffers can be handled in xmk_DLRead. It is also possible to use a ring buffer for the receiver's side. Similar as in xmk_DLWrite it is necessary to fill the macros XMK_MAX_RECEIVE_ONE_ENTRY and XMK_MAX_RECEIVE_ENTRIES with useful values.

Steps to Implement a Communications Link

Extension to the Template Makefile

In the distribution of the Cmicro Package there are several template makefiles.

On UNIX the existing makefile templates are called makeoptions.no_tester and makeoptions.with_tester.

In Windows the existing makefile templates are called makeno_t.opt and makew_t.opt.

The intention is to give one template makefile where the SDL Target Tester is not included (which means that there is no compilation of any SDL Target Tester C code), and to give one template makefile including the SDL Target Tester.

In the template makefiles that include the SDL Target Tester, it is necessary to define the communications link software by adding the name of the C module(s) that contain(s) this. This can be achieved by changing the list of the object files given in sctLINKTARGET_WITH_TESTER (e.g. 8051_v24.suffix). In addition, the compilation rules for this/these additional module(s) must be specified as well in the makefile.

Finally, the makefile name must be changed into makeoptions on UNIX, and into make.opt in Windows.

Note:

The makeoptions and make.opt files below the predefined kernel directories in <sdtdir>/SCMA* are not intended to be used for target or target debug applications.

Adapting the Data Link Layer

The data link layer for the SDL Target Tester on target site is represented by the module dl.c with the functions

    • xmk_DLInit()
    • xmk_DLRead()
    • xmk_DLWrite()
    • xmk_DLQuery()
    • xmk_DLDeinit()

Several ways to fill these functions are already given in mg_dl.c.

The data link layer can be build using a ring buffer for all the trace message or writing each message directly to the physical layer.

Furthermore the data link layer must be build to work together with the physical layers (E.g. ISR driven or not).

It is recommended to have a look into the distributed template mg_ dl.c which shows different ways.

  • For using the ring buffer, please follow the flag TCC80166.
  • For using no ring buffer, please follow the flags IARC51 or KEIL_C51.
  • For using an ISR driven physical layer, please follow the flags IARC51 and KEIL_C51.
  • For using a not ISR driven physical layer, please follow the flag TCC80166.

Adapting the Physical Layer

There are given tested physical layers for the micro controllers 8051 and 80166.

The structure of these physical layers should be taken and filled with the functions for the needed communications link. E.g. the function to write to a serial interface must be replaced by a function to write to an Ethernet interface.

The Communications Link's Host Site

The sdtgate is one executable of the SDL Target Tester's tool chain on host site. It is built to simplify the communication between the host and the target.

In this release of the SDL Target Tester, the sdtgate is built using a V.24 interface and the sockgate is build using a TCP/IP interface. But as you can see in this subsection, it will be very simple to implement any other communication interface as a new executable.

Communication between the SDL Target Tester Executables

The SDL Target Tester executables sdtmtui, sdtmt and sdtgate communicate with the help of the Cmicro Postmaster. The Cmicro Postmaster handles all the communication between the SDL Target Tester tool chain and is started automatically when the SDL Target Tester is invoked.

The Default V.24 Connection: Sdtgate

Fork Parameters for the Sdtgate

There are two groups of fork parameters handed over to the sdtgate.

The Sdtgate Device Specifications

Inside the SDL Target Tester configuration file sdtmt.opt there are 7 entries for the gateway executable.

Example 590 : On UNIX

USE_GATE <pathname>/sdtgate
GATE_CHAR_PARAM_1 /dev/ttya
GATE_CHAR_PARAM_2 0
GATE_CHAR_PARAM_3 0
GATE_INT_PARAM_1 9600
GATE_INT_PARAM_2 0
GATE_INT_PARAM_3 0

On UNIX, it muse be ensured that the device (/dev/ttya above) is accessible. Ask the system administrator if there are problems to open this device.

Example 591 : In Windows

USE_GATE <pathname>/sdtgate.exe
GATE_CHAR_PARAM_1 COM2
GATE_CHAR_PARAM_2 0
GATE_CHAR_PARAM_3 0
GATE_INT_PARAM_1 9600
GATE_INT_PARAM_2 0
GATE_INT_PARAM_3 0

USE_GATE gives the name of the used gate only.

Inside the delivered sdtgate for V.24 interface only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. For future developments there are 2 further string parameters and two further integer parameters which are handed over when forking the gate.

The delivered version of the sdtgate uses fixed values for parity, start bits, stop bits...

These are: databits = 8, startbits = 1, stopbits = 1, parity = none

Coding Rules

There are two coding rule pieces of information the gate needs to work.

These are the length of a character on the target in octets (normally 1) and the position of the character. This value is necessary for special micro controller memory layouts e.g. the MSP58C80 gets the character length of 2 octets but the used character is the lower octet only. In this case the character position is 1. Normally if the character size is 1 the character position is 0.

The TCP/IP Connection: Sockgate

The Sockgate Device Specifications

Like the sdtgate, the sockgate is using only 3 of the 7 entries for the gateway executable inside the SDL Target Tester configuration file sdtmt.opt.

Example 592 :

USE_GATE <pathname>/sockgate
GATE_CHAR_PARAM_1 207.46.138.0
GATE_CHAR_PARAM_2 0
GATE_CHAR_PARAM_3 0
GATE_INT_PARAM_1 9000
GATE_INT_PARAM_2 0
GATE_INT_PARAM_3 0

USE_GATE gives the name of the used gate only.

It must be ensured that the IP-address (207.46.138.0 above) is accessible.

Inside the delivered sockgate only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. The delivered version of the sockgate uses an address string (a valid IP-address) and a port number (valid between 1 and 65535).

Building an Custom Made Communications Link

All the C files and libraries necessary to re-build the default gateway sdtgate are delivered with the SDL Target Tester. The files for a custom built gateway are named usergate to distinguish between the custom and the delivered sdt- and sockgate.

The Modules Building a Usergate

The following files are part of the usergate:

cmicro
+ sdtmpm
| + hppa
| | + sdtmlib.a (HP-UX version)
| + sunos5
| | + sdtmlib.a (SunOS 5 version)
| + wini386
| + sdtmpmbcb.lib (Borland C++ Builder version)
| + sdtmpmcl.lib (Microsoft C++ 6.0 version)
| + sdtmpmcl5.lib (Microsoft C++ 5.0 version)
+ mcod
| + mcodfnc.[ch]pp
| + mcodlib.[ch]pp
| + mcod.h
+ sdtgate
| + mg_ctrl.[ch]
| + usergate.rc (Windows only)
| + hppa
| | + usergate.[ch] (HP-UX version)
| + sunos5
| | + usergate.[ch] (SunOS 5 version)
| + wini386
| + usergate.[ch] (Windows version)
+ template
+ mg_dl.[ch]
+ commlink
+ <interface>.[ch]

Files with suffix .h and .hpp are not listed but are still being used.

<interface> stands for the selected interface type.

On UNIX the module ux_v24.c is used (ux_sock.c for sockets).

In Windows the module win32v24.c is used (win_sock.c for sockets).

The purpose of each module is as follows:

  • mcodfnc.cpp
    This module delivers all functions to decode and encode the messages sent between the different executables of the SDL Target Tester tool chain. All functions are contained within a C++ class called ClassHostMessage.
    As these functions have to be suitable for the executables sdtmt and sdtmtui, no changes need be made by the user.
  • mcodlib.cpp
    This module is automatically generated by the Message Coding Generator (MCOD) and delivers a decode or encode strategy for each message that can be exchanged between the parts of the SDL Target Tester tool chain.
    No modifications can be done inside this module.
  • mcod.h
    Like mcodlib.cpp this file is generated by MCOD too. It contains all MessageTags for the communication between sdtmtui, sdtmt and sdtgate and no modifications are to be done here.
  • mg_ctrl.c
    In this module the reactions of the messages exchanged between the SDL Target Tester tool chain are invoked. Like mcodlib.cpp and mcodfnc.cpp there is no need to make any modification inside this module because the communication between the different parts of the tool chain depends on it.
  • usergate.rc (Windows only)
    This resource file is for use in MS Windows executables only. It just needs to be compiled and to be linked together with the other object files.
  • usergate.c
    This file handles all the initialization and communication of the sdtgate with the Cmicro Postmaster.
    This file is platform specific and needs to be modified in some cases, e.g. when using the V.24 or socket interface on MS Windows a Windows Message is generated when a character is received or completely sent. The reaction on the WM_COMMNOTIFY message can be removed here if another interface is used.
  • sdtmlib.a/sdtmpmbc.lib/sdtmpmcl.lib
    This library presents the connection to the Cmicro Postmaster.
  • <Interface>.c
    The last of the listed files needs some modifications if the communication interface is to be changed.
    There are eight functions inside this module
    • xmk_V24Init() and xmk_SocketInit()
      These functions are called only once after the sdtgate has been forked. All initialization of the communication device have to be done here.
      Errors should be given as plain text and will be sent to the user interface.
    • xmk_V24Deinit() and xmk_SocketDeinit()
      These functions may not need to be filled for the wanted communication interface. If it has to, all deinitialization can be done here. This function is called directly before exiting the gate.
    • xmk_V24Handshake()
      The V.24 RS-232 protocol describes the use of the XON - XOFF communication. In the SDL Target Tester's host - target communication XON characters sent only every second. If using another communication protocol (like RS-422/RS-485) this function must be left empty.
    • xmk_V24Receive() and xmk_SocketReceive()
      This function does several things.
      At first the communication interface is polled and all available characters are taken from the interface. Then the gate checks the received character stream for the correct sync field position, the length field is read and the amount of characters used to build one complete target message is sent to sdtmt, unless there are no complete messages left.
      The re-synchronization of the data stream is also done in this function if the sync field is not in the correct position.
    • xmk_V24Send() and xmk_SocketSend()
      If the gate gets a message from sdtmt which is to be transmitted to the target, this function is called.
      There are several ways to transmit the whole message. For instance, on Windows NT it is possible to hand over a character buffer to the serial interface. The rest of the transmission is being done by the interface itself.
    • xmk_ExtractControl() / xmk_MaskControl()
      These two functions are for use with an XON-XOFF protocol. If a message contains an XON or XOFF character, in front of this XON or XOFF an ESC is inserted in xmk_MaskControl() to differ this (XON/XOFF-) character from the control XON/XOFF.
      On the other hand if a message containing XON/XOFF characters is received, the function xmk_ExtractControl() removes all ESC from the data stream.
      These functions are called from xmk_V24Send() and xmk_V24Receive() only and the function calls should be removed if the new communication interface does not support the XON-XOFF protocol.

Compiler Settings

  • On UNIX:
    The following defines have to be made. The user can use the makefile makefile.template in the directory $sdtdir/cmicro/sdtgate as a template to compile and link his own gateway.
    • _GCC_
    • XMK_UNIX
    • SDTGATE
    • XMK_USE_V24 (for the default gateway sdtgate)
    • XMK_USE_SOCKETS (for the socket gateway)
  • In Windows:
    The source code for the sdtgate is tested only in combination with the Borland C++ 5.x compiler and the Microsoft C++ compiler 6.x on a Microsoft Windows NT/95 installation.
    The following defines have to be made. There is a Borland project file called usergate.ide that the user may use to compile and link his own gateway with the Borland compiler.
    • BORLAND_C or MICROSOFT_C
    • XMK_WINDOWS
    • SDTGATE
    • XMK_USE_V24 (for the default gateway sdtgate)
    • XMK_USE_SOCKETS (for the socket gateway)

Current Restrictions for Communications Link Software

SDL Restrictions

It is impossible to transfer pointer values via the communications link. An example may be the SDL predefined sort charstring which is by default implemented as a pointer in C.

To avoid problems, users must not use SDL sorts that are implemented as pointers (like charstring), whenever it is required to send / receive them via the communications link (e.g. Cmicro Tracer or Cmicro Recorder functionality). This means, that this kind of sorts should only be used in signals inside the SDL system but not at it's environment.

Message Length

The maximum length of the message length is restricted.

An explanation follows:

Each message is transferred as:

Header + Data + CRC

The length field contained in the header may represent the values from 0 to 255. If the MSB in the message tag is set to "1", then the length field is expected to be a 2 octet values, which makes it possible to represent the value from 256 to 65535.

However, the length field consisting of 2 octets is currently not implemented.

In fact, no message may be greater than 4 + 255 + 1 = 260 characters in total (1 character normally is equal to 1 Byte, which consists of 8 Bits).

Connection of a Newly Implemented Communications Link

The SDL Target Tester uses only a few C function calls in order to send and receive information via the communications link. From the C syntax point of view, users only have to implement the body of these functions and to link them together with the SDL Target Tester's target library into one executable program.

However, when considering timing constraints, critical paths, interrupts and similar things, users have to note the following.

Critical Paths

Critical paths occur in any type of software which uses interrupts. Especially the transfer of information between ordinary C code and interrupt service routines must be considered, e.g. for the communication from the physical layer (which may be implemented as an ISR) to the data link layer (which may be implemented as ordinary C functions).

Critical paths may occur at any place in the software which accesses global C variables.

The beginning of each critical path must be blocked with something like "disable interrupts" (see XMK_BEGIN_CRITICAL_PATH in the compiler section of ml_typ.h). The end of a critical path must be released with something like "enable interrupts" (see XMK_END_CRITICAL_PATH).

Timing Constraints

Often there are timing constraints to be considered within the target system. Timing problems must be prevented. Each ISR must be implemented with a few statements only, in order to make the execution time as short as possible.

Interrupts

C functions which should be compiled as ISRs by the C compiler in use are mostly

marked by a preprocessor directive or by a special C compiler keyword. The C compilers reference manual must be consulted in order to implement ISRs.

Open Interface

The open interface can be used to implement user host executables which are able to communicate with the SDL Target Tester at the target site. The SDL Target Tester at the target site is represented by the target library.

Using the Open Interface

In order to use the open interface in this way, the following are of interest:

  • Which messages can be sent to the target. This is described within the earlier subsection "Message Formats" .
  • Which messages are to be expected from the target. This is also described within "Message Formats" .
  • The format of these messages. Also described within the earlier subsection "Message Formats" .
  • The situations in which the messages may be sent. Please refer to the subsection "State Machine and Handshake" .
  • The situations in which a particular message may be received. Again, please refer to "State Machine and Handshake" .

It is not of great interest what the format of the data link frames is because it is possible either to use the existing protocol or to re-implement the protocol (e.g. it may be necessary in order to integrate the SDL Target Tester into an existing communication link's software).

The host site must send each message in target representation.

For instance, if the target system uses integers as 2 octet values with the ordering higher octet first, then the host must send an integer value with higher octet and then lower octet, irrespective of its own layout.

For the other direction (reception of messages at host site), the host must also map the information according to the relation between the target memory layout and its own internal representation.

Accessing the Data Link by User

The user can send information via the communication link by calling the C function xmk_DLWrite with appropriate parameters. The following example shows one possibility.

Example 593

#define HelloWorldTag <AnyValueAllowed>

char buffer [20];
char helloworld [15];
int length = 0;
int write_result ;
strcpy (helloworld, 'Hello World');

buffer [0] = 0x11;
length ++;
/* any value for Messageclass, except */
/* reserved values for SDL Target Teste */
/* reserved values begin from 250 to 255 */

buffer [1] = HelloWorldTag;
length ++;
/* any value for Messagetag */
/* Messagetag is made unique together */
/* with Messageclass, so that no */
/* conflict occurs. */

buffer [2] = strlen (helloworld);
length ++;
/* length of data for this message */
/* length is given without calculating */
/* the CRC field */

memcpy (buffer [3], helloworld, strlen (helloworld);
length += strlen (helloworld);
/* It is assumed, that no stringterminator */
/* is included in the message (the length */
/* can be calculated from Messagelength) */

buffer [length] = xmk_EvalChkSum (buffer, length);
/* Evaluate the checksum of current buffer */

write_result = xmk_DLWrite (buffer, 5 + strlen (helloworld));
/* transmit buffer via communications link */

The user can receive information from the communication link by calling the C function xmk_DLRead with appropriate parameters.

Example 594 : xmk_RunSDL ()

The following section is partially implemented within the module mk_main.c

p_data = xmk_DLRead () ;
if (p_data != (char *) NULL)
{
/* if anything received, decode it */
/* according to Cmicro Protocol */
result = xmk_Cod_Decode (p_data,
&MessageClass,
&Messagetag,
&MessageLength,
buffer,
sizeof (buffer));
if (MessageClass == XMK_MICRO_COMMAND)
{
result = xmk_HandleCmd ( Messagetag, (xmk_U_CMDS*) buffer );
return;
}

/*
** Received user message
*/
if (MessageClass != 0xF8)
{
ErrorHandler (-7777);
return ;
}

if (HelloWorldTag == Messagetag)
{
/* HelloWorldTag is used in this example to */
/* identify the hello world message */
/* The user can choose any value for the */
/* Message tag */
char helloworld [15];

memset (helloworld, 0, sizeof (helloworld));
memcpy (helloworld, buffer, MessageLength);
printf ('%s', helloworld);
}

The above examples assume that the Cmicro protocol (which is described in "Used Default Protocol" ) is used.

The Communications Link To Lauterbach Emulators

Note:

The gateway for the SDL Target Tester connection to the Lauterbach ICE, BDM or Simulator needs an according license.

This communications link delivers a communication with a target micro controller running on a Lauterbach ICE, BDM or Simulator using the Dual Ported RAM.

The connection is established via sockets between the gateway lautgate and the TRACE32.

Prerequisites on Host Site

Trace32

  • The TRACE32 configuration file config.t32 must have the following entries:
RCL=NETASSIST
PORT=20000
PACKLEN=1024
This file and the environment variable T32SYS are used by the gateway, too, and read in during the connection process to the TRACE32 sockets. So it is guaranteed that the same socket port and package length is used by the TRACE32 and the gateway.
  • To enable the Cmicro-specific configuration and menu entries, the commands
task.config.cmicro
menu.rp.cmicro
should be executed in the TRACE32's command line before starting work. This can of course be done from a command file.
  • As the gateway can only access the emulators RAM the whole target memory or at least the one to which the C structure CommBuffer is placed in, must be mapped to the emulators Dual ported RAM.

Gateway

The gateway executable for the connection with the Lauterbach emulator TRACE32 communicates with the emulator software and does not have access to the emulator hardware.

The emulator software is polled across a Windows socket port by the gateway. The polling cyclic is fixed to 100 milli seconds.

Like the default communications link solution (sdtgate) this gateway is used as one executable of the SDL Target Tester tool chain on host side.

The fork parameters for the gateway are (see sdtmt.opt):

  • USE_GATE
    gives the name of the used gateway only (including the path).
  • GATE_CHAR_PARAM_1
    The Internet address of the PC/workstation on which the TRACE32 executable is running must be given here. This means, the TRACE32 and the SDL Target Tester (including the Gateway) can be executed on different PCs/workstations or on the same PC/workstation. If executed on the same machine "localhost" should be given here.
  • GATE_CHAR_PARAM_2
    The target, the gateway has to communicate to must be given here. Possible values are:
ICE
BDM
Simulator

  • GATE_CHAR_PARAM_3
    The character parameter GATE_CHAR_PARAM_3 is not used in this gateway implementation.
  • GATE_INT_PARAM_1
    This parameter gives the amount of transmitter buffers in the target. The macro which specifies this parameter is called XMK_MAX_SEND_ENTRIES.
  • GATE_INT_PARAM_2
    This parameter gives the size of one transmitter buffer in the target and it must definitely be equal to the buffer size of the target called XMK_MAX_SEND_ONE_ENTRY.
  • GATE_INT_PARAM_3
    GATE_INT_PARAM_3 gives the size of the receiver buffer in the target (again from the target's point of view). This parameter must absolutely necessary be equal to the receiver buffer size called XMK_MAX_RECEIVE_ONE_ENTRY.

Adapting the Target Site

Selecting the Emulator Communication (in ml_mcf.h)

The emulator connection will be selected by setting the flag LAUTERBACH in the file ml_mcf.h. This is normally done by using the Targeting Expert.

Setting the correct Parameters (in ml_mcf.h)

  • XMK_MAX_SEND_ENTRIES
    The amount of transmitter buffers must be equal to the gateway's fork parameter GATE_CHAR_PARAM_1
  • XMK_MAX_SEND_ONE_ENTRY.
    The size of one transmitter buffer must be equal to GATE_CHAR_PARAM_2.
  • XMK_MAX_RECEIVE_ONE_ENTRY
    The size of one receiver buffer in the target must be equal to GATE_CHAR_PARAM_3.

Adapting the Makeoptions File

The list of C modules to be compiled and linked given in the file makeoptions (on UNIX) or respectively make.opt (in Windows) must be extended by the module laut_emu.c.

Besides this the compilation rule for laut_emu.c has to be defined.

Deviations in the Use of the SDL Target Tester

The following steps should be followed if starting the TRACE32 and the SDL Target Tester:

  1. It is necessary to start the TRACE32 executable at first as the emulator software is the master of the socket communication to the SDL Target Tester.
  2. The target executable must be loaded into the emulator.
  3. Now the SDL Target Tester can be started. The gateway is automatically forked if the parameter USE_GATE is set correct.
  4. Connect the SDL Target Tester to the emulator by typing
    Start-Gateway     in the command line.
  5. Start the Target within the emulator by executing a TRACE32 command. This can easily be done by typing
    T32-Command "go"     in the SDL Target Tester's command line.

After the start-up message is received, the target can be started with the command Go-Forever.

Specific Restrictions

There are several restrictions in the use of the Lauterbach Gateway like

  • The TRACE32 is the master of the socket connection to the SDL Target Tester and therefore the TRACE32 executable should not be finished before the SDL Target Tester is finished.
  • The target executable must be executed in the emulation RAM because the gateway has only access to this one.
  • Resetting the target must be performed by reloading it into the emulator. This is of cause not a restriction of the gateway, it is caused in the implementation of the Cmicro C code.

Trouble-shooting for the Lauterbach Gateway

  • The command Start-Gateway failed with error message "Initialization of Lauterbach ICE socket driver failed."
    • Check the value of GATE_CHAR_PARAM_1 in the file sdtmt.opt with the help of the Targeting Expert. The Internet address must fit with the PC on which the TRACE32 is running. This can be "localhost" if running on the same PC as the SDL Target Tester.
    • The TRACE32 is not yet started.
  • The command Start-Gateway failed with error message "No symbol of name `CommBuffer' got."
    • The target executable is probably not yet loaded into the ICE.
    • The target executable is not compiled including the SDL Target Tester.
  • Sometimes the gateway detects the error "Synchronization of target message failed."
    • Check the values GATE_CHAR_PARAM_1, GATE_CHAR_PARAM_2 and GATE_CHAR_PARAM_3 of the file sdtmt.opt against the values of XMK_MAX_SEND_ENTRIES, XMK_MAX_SEND_ONE_ENTRY and XMK_MAX_RECEIVE_ONE_ENTRY of the file ml_mcf.h
  • The trace on the SDL Target Tester runs in an infinite loop
    • Check the values GATE_CHAR_PARAM_1, GATE_CHAR_PARAM_2 and GATE_CHAR_PARAM_3 of the file sdtmt.opt against the values of XMK_MAX_SEND_ENTRIES, XMK_MAX_SEND_ONE_ENTRY and XMK_MAX_RECEIVE_ONE_ENTRY of the file ml_mcf.h
  • When starting the SDL Target Tester the wrong gateway is forked.
    • It should be ensured, that the shortcut which starts the SDL Target Tester is defined correctly, i.e. the path "Start in:" in the shortcut's properties must point to the correct directory.


More Technical Descriptions

The File Formats of Sdtmt

General

This section deals with the general file format of the different files which are written to or read by the SDL Target Tester's tool chain. The section is not of general interest, and need be read only when implementing and connecting other tools to the host. The format of the file containing symbols is described in the subsection "The Symbol Tables" .

<infile> and <outfile>

Physically, there is the same file format behind the input files and output files written by sdtmt. These files store the information as received via the communications interface in a 1:1 format. The trace of the SDL execution flow and the information from the record mode is simply copied into the file on the hard disk. The same header information is used as on the communications link. This has some advantages.

Without exception the format of the information stored in <infile> or <outfile> is exactly the same as the format of the Cmicro Protocol. Therefore these files are using the memory layout of the target system.

The reason for this is that binary files are always more compact than readable ASCII files.

The message decoder of the host must be active only when information is to be converted, for example if they are to be displayed. This can decrease the performance a little.

The Symbol Tables

The symbol tables which are used by the SDL Target Tester are automatically generated by the Cmicro SDL to C Compiler. Most of the intelligence to interpret SDL traces and recorded events is implemented on the host system. Normally, the host system has enough memory and performance to do the interpretation, whereas the target has not. This is the reason, why the symbol tables used by the Cmicro Package mainly reside on the host. However, some parts of the symbol table reside where the Cmicro Kernel physically is executed, i.e. within the target system.

The Target Symbol Table

The following table is generated by the Cmicro SDL to C Compiler. For each SDL process, there is one entry in the table representing a pointer to the different trace options for that process.

/******************************************************
** Symbol trace table
******************************************************/
#ifdef XMK_ADD_TEST_OPTIONS
XSYMTRACETBL *xSYMTRACETBL[MAX_SDL_PROCESS_TYPES+1] =
{
(XSYMTRACETBL_ENTRY *) NULL,
...........
..........
(XSYMTRACETBL_ENTRY *) NULL,
X_END_SYMTRACE_TABLE
};
#endif

The Host Symbol Table

Generated File <systemname>.sym

The host symbol table is generated by the Cmicro SDL to C Compiler into a file called <systemname>.sym. This file is to be specified when the host site is invoked (see subsection "Invoking the SDL Target Tester's Host" ).

In the following, the file format is described with EBNF like syntax:

SymbolFile ::= Header SymbolDescriptions
Header ::= HeaderComment Timestamp
HeaderComment ::= "Cmicro .sym file, version x.y"
Timestamp ::= "TIMESTAMP <GenerationTime>"
SymbolDescriptions ::= ( DescriptionLine ) ...
DescriptionLine ::= Depth Subject SDTReference
Depth ::= [0-9]+
Subject ::= SYSTEM IDs
| BLOCK IDs
| SIGNAL IDs
| PROCESS IDs
| START IDs
| INPUT IDs
| OUTPUT IDs
| NEXTSTATE IDs
| <to be continued>
SDTReference ::= "#SDTREF(<sdt-reference>)" LF
LF ::= "\n"

In the following an example is given that was produced with a simple "ping pong" SDL system:

Example 595

Cmicro .sym file, version 2.0
TIMESTAMP <GenerationTime>

1 SYSTEM <SystemName> #SDTREF(sdtref)
2 BLOCK <BlockName> #SDTREF(sdtref)
3 PROCESS <ProcessName> 0 1 #SDTREF(sdtref)
4 START 0 #SDTREF(sdtref)
4 INPUT 1 #SDTREF(sdtref)
4 INPUT 2 #SDTREF(sdtref)
4 OUTPUT 3 #SDTREF(sdtref)
4 NEXTSTATE State1 1 4 #SDTREF(sdtref)
4 OUTPUT 5 #SDTREF(sdtref)
4 NEXTSTATE - 0 6 #SDTREF(sdtref)
4 TASK 7 #SDTREF(sdtref)
4 STOP 8 #SDTREF(sdtref)
3 PROCESS <ProcessName> 1 1 #SDTREF(sdtref)
4 START 9 #SDTREF(sdtref)
4 INPUT 10 #SDTREF(sdtref)
4 ASSIGNMENT 11 #SDTREF(sdtref)
4 NEXTSTATE State1 1 12 #SDTREF(sdtref)
4 ASSIGNMENT 13 #SDTREF(sdtref)
4 DECISION 14 #SDTREF(sdtref)
4 OUTPUT 15 #SDTREF(sdtref)
4 STOP 16 #SDTREF(sdtref)
4 OUTPUT 17 #SDTREF(sdtref)
4 NEXTSTATE - 0 18 #SDTREF(sdtref)
4 DCL counter Integer #SDTREF(sdtref)
3 SIGNAL PING 1 #SDTREF(sdtref)
3 SIGNAL PONG 2 #SDTREF(sdtref)
3 SIGNAL PONG_SAY_BYE_BYE 3 #SDTREF(sdtref)
3 SIGNALROUTE SR1 #SDTREF(sdtref)
3 SIGNALROUTE SR2 #SDTREF(sdtref)

The first line, Cmicro .sym file, version x.y, gives some comment about the Cmicro symbol file version.

The TIMESTAMP <GenerationTime> value is used internally for consistency checks with the SDL Target Tester. With this time-stamp, a rough consistency check for the generated files is performed and warning messages are printed out in the case of an inconsistency.

The lines following the time-stamp information, contain in the first position an integer value indicating the depth of the structuring level in which the information is found in SDL. For example, the SDL system is in level 1, a block in the SDL system level is in level 2, and so on.

The next column in these lines describe the subject, e.g. if it is a system, block, channel, signal route, process, procedure, signal, start, input or output, or whatever.

For each subject there are IDs generated, these are used in the target executable program for generating trace information. The IDs begin with 0 (in the case above it is the start symbol of the first process) and end with the number of the last SDL symbol in the system.

The last column in the lines contains a #SDTREF reference, which points to the location of the subject in either SDL/GR or SDL/PR.

Internal Symbol Table Structure

The symbols of a trace can be found during the conversion of internal information into a displayable format.

The following three SDL objects are treated:

  • Processes
  • Signals/Timers
  • States

They are handled in the same way. Namely by building a linked list of symbols for processes, a linked list for signals and a linked list for states.

Cmicro Recorder

The information given in the following sections are valid both for host and target and there is no differentiation made between these.

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

Type and Amount of Stored Information

As already mentioned in earlier sections, using the Cmicro Recorder makes more sense in those cases where an SDL system is executed in real-time in the target.

That's why the amount of stored information is to be kept very small. Of course, this leads to the problem that not all types of errors can be found with the Cmicro Recorder but there is a good chance to find most of them. The information which the Cmicro Recorder produces at target site and which the Cmicro Recorder uses at host site cannot be configured in their dimension. The packets which are to be transmitted via the communications link are always the same. A technical description follows in the next section.

Record Mode

First, the SDL system executes the start transitions of all statically created processes. At the occurrence of a "counted" symbol, an internal counter variable is incremented (which was set to zero before going into the SDL start-up phase). The counter will simply be incremented until the first environment signal is sent from the environment to a process in the SDL system, or until the first timer expires within the SDL system.

These are special events for the Cmicro Recorder.

In that case, the Cmicro Recorder on the target site sends the following messages to the host:

Host <-------- <Counter value> ------------ Target
Host <-------- <Event> -------------------- Target

Both messages are stored in the <outfile> on the host.

The counter is reset to zero again and the procedure restarts by counting the "counted" symbols and sending the above messages to the host, either when an environment signal is sent from the environment to a process in the SDL system, or when the first timer expires within the SDL system.

The <outfile> is closed when the user terminates the record mode on the host site, i.e. it is not possible to close the file by ending the record mode on the target site. The record mode can be finished at any time.

After the record mode has been switched off, it is not allowed to switch the record mode or the play mode on again.

The <outfile> on the host now contains messages like this:

<trace event 1>
....
<trace event N>
<Counter value>
<Event>
<trace event N+1>
....
<trace event N+1+M>
<Counter value>
<Event>

As can be seen, the following sections are stored in the file whereas each section is optional:

For all events in the target
[Store trace section]
[Store Counter value section]
[Store Event section]

Counted Symbols

The occurrence of the following SDL symbols will be "counted" by an internal counter (a C integer variable):

STATE | The SDL nextstate operation
INPUT | The SDL input operation
SAVE | The SDL save operation
CREATE | The SDL create operation
STOP | The SDL stop operation
STATIC CREATE | Used at system start, appears for each statically created process
DYNAMIC CREATE | Used at start of a dynamically created process
DECISION | SDL decision
TASK | SDL task (not C Code)
OUTPUT | The SDL output operation (see remarks below)
PROCEDURE | SDL procedure call
SET | SDL action: Set timer
RESET | SDL action: Reset timer
DISCARD | SDL Discard
IMPLICIT CONSUMPTION - | SDL implicit transition

A special case is the SDL output operation:

If the output is from one process in the SDL system to another process in the SDL system or if the output is from one SDL process in the SDL system to the environment, the occurrence of this symbol is counted.

Otherwise if the output is from the environment to a process within the SDL system, the event is relevant for the Cmicro Recorder (as the timer expiry is).

C code in an SDL task is normally not counted when recording. The users are free to count C code by calling:

xmk_Record (CMD_TTASK) for the record mode and

C code written into an SDL Task (i.e. by using the #CODE directive)

xmk_Play (CMD_TTASK) for the play mode.

Play Mode

In play mode, the target accepts signals coming from the SDL environment only from the Cmicro Recorder. These signals are read from the file which was previously written to in record mode.

Caution!

No environment signals may be handled by the user in the C function xInEnv! At the beginning of xInEnv, there should be a statement like

if (xmk_RecorderMode == XMK_RECORDER_PLAY)
return (XMK_OKAY));

In addition, no signal may be sent by any other environment function (like ISRs) to the SDL system.

At the beginning of the play mode, the host reads the first <counter value> from the <infile> and sends it to the target.

Host -------- <Counter value> --------------> Target

The meaning of this is: Please execute the amount of "counted" symbols as indicated in the <counter value>. The target executes the start transitions of all statically created processes (start-up-phase). When preemption is used, it is possible that a transition which is not a start transition is executed. Each "counted" symbol increments a counter value which is compared against the debit, which was indicated by <counter value>.

If the current counter value reaches the debit counter value, then an environment signal (or timer expiry) plus the next <counter value> is requested by the Cmicro Recorder.

Host <------- <Request> --------------------- Target
Host ---------------- <Event> --------------> Target
Host -------- <Counter value> --------------> Target

If the target has requested the next <Event> and <Counter value>, the target is waiting for these messages only and is not able to handle other messages. This is not a restriction because the environment is disabled in play mode in the target.

If the end of file of <infile> has been reached, the host indicates the end of the play mode to the target. <Counter value> and <event> are always stored together in record mode. Therefore the end of file can only be reached after reading an EnvSig or Timer expiry.

Host -------- <Play mode off> --------------> Target

Note:

After the play mode has been switched off, it is not allowed to switch the record mode or the play mode on again.

General Restrictions on Record and Play

Of course, there are restrictions in the use of the Cmicro Recorder, especially for the play mode. However, there may be situations where the Cmicro Recorder does not help in finding the source of the problem. The user must decide when the Cmicro Recorder can be properly utilized.

Firstly, the user has to ensure the same configurations are used for hardware and software, in order to allow comparison between the results of a recorded session with the ones of the replayed session. This is only a general recommendation. It is possible that he even would like to compare two different hardware configurations, and the Cmicro Recorder should help him finding the differences between these. As a more general recommendation we would say: Compare only those configurations that are definitely comparable.

Secondly, starting and ending the record and the play mode must be as follows. Host and target are to be synchronized.

Restrictions when Starting Record

The target may not transfer information to the host until the host has become active.

Therefore, the SDL Target Tester's host site should be started first and the file to write in should be opened.

If the target is started (e.g. reset-button), it has to wait on sdtmt before transmitting information (see "XMK_WAIT_ON_HOST" ).

Restrictions when Ending Record

Ending the record session is to be done from the GUI (sdtmtui) by closing the <outfile>. The user can enter any exit commands at any time. He should pay attention to the exact time when he exits. If exit is performed in the middle of a running SDL transition in the target, then the traces following will not be stored! The last information may then be unpredictable.

Restrictions when Starting Replay

The target may not transfer information to the host, until the host has become active. The host may not transfer information to the target, before the target has become active.

Therefore the SDL Target Tester's host site should be started first and the file containing the recorded session should be opened.

If the target is started (e.g. reset-button) it has to wait for the host before transmitting information.

Restrictions when Terminating Replay

In principle, the play mode reaches the end when the last stimuli stored in the recorded file was read and sent to the target. Actually, the play mode should end when all the transitions which follow that stimuli have ended. This is a discrepancy which is solved as follows:

When the target has received the last stimuli from the recorded session, it enters the "recorder off" mode. The problem with this is, that timers are simulated during the play mode but are no longer simulated if changing to "recorder off" mode. Timers will expire as they have been set and it is the real-time that will be used to allow them expire instead of the simulated timer expiry in the Cmicro Recorder.

Real-time Play Mode

The host tries to replay the SDL environment events at the same absolute time values as they occurred during the record session, if so required by the user (real-time-play is switched on).

Internally, a time stamp is stored for each environment signal, which is compared within the target with the current value of SDL now. SDL now and the time stamps in the signals are calculated with the value 0 from system reset on. The target generates the SDL now values in any case.

Of course, the processing power of host and target together must be large enough to handle this. As a rule of thumb, the recorded environment signals may not be sent to the SDL system more often than one every few hundred microseconds. But that - of course - also depends on the communications link in use.

Restrictions when Using Preemption

There are some restrictions when the Cmicro Recorder is used in combination with preemption. The problem is that in a real-time execution, signals coming from the environment (this may be a hardware interface) can cause a preemption of a running SDL process by a new process with a higher priority. The preemption may occur at any time, which means at any machine instruction (see notes below). On the other hand, only SDL symbols are registered by the Cmicro Recorder.

This means that the play mode may produce a different system behavior other than the recorded one.

The only alternative to implement an exact reproduction of the recorded session would be the use of special debugger hardware (not a general solution).

Some Additional Comments

Real-time behavior cannot be expected in play mode. When considering the other direction, from SDL to the environment, it is not absolutely necessary to cut this connection off (C function xOutEnv). It may be a good idea to let this connection be as it is in record mode. For example, if there is a display driver in the environment, which is controlled by SDL, it would then be possible to see the reactions on the display in the same way as they have been observed in record mode.


Utility Functions

File Structure

Description of Files

The modules and functions described in this subsection are used to handle first in-first out buffering, ring buffering, message coding and other possibilities.

ml_buf.c

This module contains functions to handle first-in first-out buffers and ring buffers.

It is mainly used internally by the SDL Target Tester to write and read trace information into/from a first-in first-out buffer within the RAM.

These functions are also free for users.

Three functions are implemented representing the low level functions. Each entry has to be of the same size, because the handling is in principle similar to an array. The type of each entry is not relevant. In addition, the caller of the functions contained in this module defines the memory for the trace buffer as well as a control structure representing all the internal data and variables necessary to administrate the trace buffer.

As a result, users are free to have more than 1 instance of this buffer type.

ml_buf.h

This is the header file containing the external definitions of ml_buf.c.


Trouble-Shooting

What to Do if the SDL Editor Trace Does Not Work?

The SDL Target Tester gets the SDL Editor references from the generated file <systemname>.sym in the known form #SDTREF( ... ).

As it is possible to generate an SDL system and to test it on another platform it is possible that the paths contained in each #SDTREF() are not up to date if using the SDL Target Tester.

All the paths in <systemname>.sym must simply be updated.

What to Do if There Is a Warning of the Information/Message Decoder?

If the message decoder detects an error there will be a warning like the one shown in Example 596.

Example 596 : warning of the message decoder

**WARNING: There is an inconsitency in the information decoder.
This message will be suppressed form now on.
Message Class: 241,d
Message Tag : 5,d
Number of data bytes received=6
Number od data bytes decoded =5

***Received buffer (32 octets):
***f1 05 aa 06 00 00 00 00 - 01 04 ab ee ee ee ee ee
***ee ee ee ee ee ee ee ee - ee ee ee ee ee ee ee ee

This warning must be interpreted as follows:

  • In the Cmicro Package there are the following message classes:
    • Cmicro Tester commands = 0xf0 = 240
    • Cmicro Tester trace = 0xf1 = 241 (see Example 596)
    • Cmicro Recorder = 0xf2 = 242
  • The message tag can be found in the file "tmcod.h"
    In Example 596 the message tag 5 (decimal) is the message CMD_TSTATE. Furthermore there is a structure called xmk_T_CMD_TSTATE. This structure looks like
typedef struct
{
xPID process;
xmk_T_STATE state;
}
  • The shown buffer from above can be interpreted as:
    f1 -> Cmicro Tester trace
    05 -> CMD_TSTATE
    aa -> sync byte
    06 -> message data length 6 octets.
  • The message data contains the values xPID and xmk_T_STATE. In the Example 596 the xPID value is an unsigned int and the xmk_T_STATE is an unsigned char.

Note:

The kind of C basic type the xPID value is represented by, depends on the SDL system in use (single instance processes only or multiple instance processes). Please view the typedef of xPID in the file ml_typ.h.
The size of the C basic type depends on the microcontroller and compiler that is used.

By having a look to the C struct (xmk_T_CMD_TSTATE) which is represented by the 6 data octets received a value for xPID is found like 0x00000000 as an integer is given with the length 4 octets in this example.

Note:

The kind of C basic type the xmk_T_STATE value is represented by, depends on the SDL system in use, please view the flag "XMK_USE_HUGE_TRANSITIONTABLES" .
The size of the C basic type depends on the microcontroller and compiler in use.

Having a look to the fifth octet of the message data the value for xmk_T_STATE is 0x01, as the length of character is 1 and the alignment of character is 8. Please view "Preparing the Host to Target Communication" .

After all in this example there are 5 bytes (octets) decoded (4+1) and 6 received which leads to the inconsistency in the information decoder.

The user is asked to correct the settings in the file sdtmt.opt to support the SDL Target Tester's host site with the correct information about the target's memory layout.

Caution!

The Example 596 is an exception concerning the inconsistency in the information decoder.

The compiler used for this example only knows C structures with a size dividable by two which leads to a message data length of 6.

The value 0x04 in the example only represents a filler octet which does not need to be noticed.


68 SOMT Introduction

This chapter describes the techniques that the SOMT method is based on. It also gives a first brief description of the method and the activities it consists of.

Last in the chapter is a list of references, which are referred to throughout this volume.


Background

Object-oriented analysis is a well-known and popular technique for understanding a problem and analyzing a system. There are many different versions of object-oriented analysis published as different methods in various books. The Object Management Group (OMG) has agreed upon a standard language for object-oriented methods and tools - the Unified Modeling Language (UML) and its notation ([36], [37]).

SDL [23] and MSC [25], on the other hand, are standardized notations used for specification and design of systems. They have a solid foundation in terms of support for design, formal verification and code generation. Especially for distributed, reactive, real-time applications SDL and MSC has a successful track record.

The scope of this volume is to present a method that integrates object-oriented analysis and SDL design with a special focus on application areas where SDL is known to be suitable. The intention is of course to provide developers with the best of both worlds: The strength of the object oriented analysis in the early phases together with the strong back-end provided by SDL and SDL tools.

The method has been given the name SOMT (short for SDL-oriented Object Modeling Technique). As the name indicates the method is essentially an adaptation of OMT to the requirements given by the special application area of distributed, reactive, real-time systems together with the usage of SDL for the design.

Another object-oriented analysis method that has provided input to SOMT is the Objectory method by Jacobsson [18]. In particular, the idea of use cases that originated from this method has been incorporated into SOMT.

A special focus of SOMT is to provide solutions that can be directly applied in a development project. For instance, it provides guidelines about how to apply OMT in a way that enables a smooth transition between analysis and design.

The volume is focused on how to use the different notations and concepts of object-oriented analysis and SDL and does not provide a detailed description on the specific notations. It is therefore recommended that you are at least reasonably familiar with both the general concepts of object-oriented analysis, the OMT notation and SDL before reading this report. [20] is a good introduction to the OMT notation and there exist several text books on SDL, for example [26].

The rest of this document is structured as follows:

  • This chapter, SOMT Introduction, gives an overview of the SOMT method and introduces the different activities
  • 69 SOMT Concepts and Notations describes briefly the different concepts and notations that SOMT uses
  • 70 Requirements Analysis covers the requirements analysis activity
  • 71 System Analysis presents the system analysis activity
  • 72 From Analysis to Design discusses the steps and considerations when moving from analysis to design
  • 73 System Design moves on to system design
  • 74 Object Design deals with object design
  • 75 SOMT Implementation ends the SOMT activities with a description of the implementation activity
  • 76 SOMT Projects focuses on how to organize a SOMT project


Overview of the SOMT Method

The SOMT method provides a framework that shows how to use object-oriented analysis and SDL-based design together in a coherent way. The framework is based on describing the analysis and design of a system as a number of activities. Each activity deals with some specific aspects of the development process. The work done in the activities is centered around a number of models, that document the result of the activities. As an integral part of the SOMT method, guidelines are given for the transition between the different models. The activities and the main models used in SOMT are illustrated in Figure 604.

Figure 604 : SOMT activities and main models

As can be seen in Figure 604, SOMT consists of five major activities:

  • Requirements analysis. The purpose of the requirements analysis is to analyze the problem domain and the requirements on the system to be built, essentially by analyzing the system as a black-box in its intended environment.
  • System analysis. The purpose of the system analysis is to identify the architecture and most important objects that must be represented in the system to achieve the required functionality.
  • System design. The purpose of the system design phase is to precisely define the architecture of the system including the detailed interfaces between different parts. In the system design the architecture of the system is also analyzed in terms of implementation strategies and decomposition into work packages for different development teams
  • Object design. The purpose of the object design is to define in detail the functionality including the behavior of all objects.
  • Implementation. The purpose of this phase is to create the executing application that implements the requirements.

As seen above, SOMT uses a number of different models to describe different aspects of the system. In many cases there are relations between objects in the different models. One especially important relation is that in some cases one object can be seen as an implementation of another object. In SOMT this type of relation is called implink (short for implementation link) and corresponds to a design decision taken during the development. The creation and maintenance of implinks forms an important part of the SOMT method. Two points can be made:

  • Since the transition between different models is a creative process involving a number of engineering decisions, this is a manual, but tool supported, activity.
  • The major tool support is a Paste As functionality that will allow you to copy an object in one model and paste it into another model while automatically creating an implink. For example: an object model class from the analysis object model may be pasted as an SDL process type in the system design model.

Note that the Paste As functionality can be seen as an implementation of transformation rules between the different models, e.g. from object models to SDL design models.

Another important aspect of implinks is that they facilitate consistency checks between the different models.

It is important to note that even though the description in SOMT of the different activities is a sequential description, this does not mean that in practice these activities can or should be carried out in sequential order. On the contrary, depending on the size and complexity of the application, the different activities can be organized in a number of different ways. This is the topic of the 76 SOMT Projects.


Scope of the SOMT Method

The primary focus of the SOMT method is on system development using object oriented analysis and SDL design, with extra support for interface definitions in other notations like ASN.1 [22]. Nevertheless, an important issue in SOMT is the possibility to use the analysis part of SOMT together with design using other notations. Some examples:

  • The system to be built is composed of several different parts, where some parts are not suitable to design using SDL. A simple example might be where the system includes a window based user interface that is easier to design using a special purpose tool.
  • Another example is when the system includes a data base component. The analysis of the data is suitable to perform using object oriented analysis, but the data base component is preferably designed and implemented using a commercial data base tool.
  • Different parts of the system may be designed in different parts of the world and for some reason there has been a choice to use SDL-based development for some parts and other methods for other parts.

The scope of the support given by SOMT when using a design notation other than SDL is, as can be seen in Figure 605, basically:

  • The requirements and system analysis of the system are still valid.
  • Parts of the system design activity are still supported by SOMT.
  • The SDL-based design of components is of course supported.

Figure 605 : Using SOMT analysis and design together with
design using other methods/notations

How much of the system design part that is supported by SOMT is of course very much depending on the "XYZ" method used (see Figure 605). However, the support given by SOMT when using "external" components is at least the definition of the interface of the "external" components. This includes definitions of both static and dynamic aspects as will be seen in 73 System Design.


Requirements Analysis

The requirements analysis is the first activity in the SOMT method. The purpose of the activity is, as stated above, to capture and analyze the problem domain and the user requirements on the system to be built. For this purpose the system is viewed as a black-box and only the objects and concepts visible on the system boundary and outside the system are modeled.

There are five major models used in this phase:

  • A textual requirements model
  • A use case model
  • A requirements object model
  • A data dictionary
  • A system operation model

The textual requirement model is a conventional textual requirements specification. This may come from the customers as input to the development project or it may be created as part of the requirements analysis as a complement to the other models.

The use case model consists of a set of use cases, each described using structured text and/or using MSCs and HMSCs. The purpose of this model is to capture and validate requirements from a user's point of view to make sure that the system will solve the right problem.

The requirements object model is a conventional object model, i.e. one or more diagrams illustrating a number of objects and their relations (including inheritance and aggregation relations). State charts may also be included in the object model to provide high level descriptions of the behavior of important objects. The purpose of the model is two-fold:

  • To use context diagrams to describe the system and the external actors that interact with the system
  • To document all the concepts found during the requirements analysis and the relations between them in order to ensure that developers and users have a common understanding of the problem domain

The system operation model is a description of the atomic transactions the system must be able to perform. The system operations can be viewed as more detailed specifications of the events that are part of the use cases.

During the requirements phase a data dictionary is also created. The data dictionary is a list of the concepts identified in this phase together with brief explanations of the concepts. It is used and refined throughout all the development phases.


System Analysis

In the system analysis phase the system to be built is analyzed using an object-oriented method. The purpose of the phase is to describe the architecture of the system and identify the objects that are needed to implement the required functionality. The models used in this phase are:

  • An analysis object model, to describe the architecture of the system and represent the objects in the system
  • An analysis use case model where the interaction between some of the objects is described
  • Textual analysis documents to document decisions and architecture related requirements not suitable to be expressed in the object models and use cases

The analysis object model is a conventional object model, consisting of class diagrams and possibly state charts, that forms the input to the object design phase. The analysts should in this model be concerned with identifying the objects that must be present in the system. These objects may come from the requirements object model produced in the requirements analysis, or they may be added in this phase for different reasons. For example, objects may be needed to represent the control logic described by the use cases from the requirements analysis. The differences between the object model in the system analysis phase and the object model in the requirements analysis phase are:

  • The requirements analysis object model consists of objects visible on the border of the system and outside the system, e.g. users of the system, while the system analysis object model is focused on the internal object structure of the system.
  • The purpose of the object model in the requirements analysis is different from the purpose in the system analysis. The purpose in the requirements analysis is to describe the problem that the system is to solve, while the purpose in the system analysis is to describe the system itself.


System Design

The purpose of the system design is to define the implementation structure of the system and to identify overall design strategies. The models used in this activity are mainly:

  • A design module structure, describing the source modules of the design
  • An architecture definition, containing
    • SDL system/block diagrams that define the architecture of the resulting application
    • SDL interface definitions of the components of the system using signals or remote procedures
  • A design use case model, described by MSC and HMSC diagrams, to define the dynamic interfaces between the different components in the system
  • Textual design specifications, describing aspects of the components not suitable for formalization like user interface definitions and other non-functional requirements

The designer of the system will have several different aspects to cover within the system design activity:

  • The decomposition of the system into work items, maybe to be implemented by different development teams
  • Reuse aspects of the design


Object Design

The purpose of the object design is to create a complete and formally verified description of the behavior of the system. The models used in this phase are essentially SDL diagrams, in particular SDL process graphs that are used to define the behavior of active objects.

One very important aspect of this phase is usage of the Paste As concept that will take a user from object models to SDL diagrams. Essentially the designer of the system will in this phase have to consider two major aspects when creating the design model:

  • The representation of the analysis object model concepts in the design
    This involves issues like to decide for each object if it is an active or passive object.
  • The dynamic behavior of the design objects

The object design also includes a testing/verification task. The purpose of this is to verify that the requirements on the system, expressed e.g. in the design use cases from system design, are correctly implemented in the design.


Implementation

The implementation and testing activities are aimed at producing the final application, i.e. executable software and hardware. The activities in this phase are very much depending on the execution environment of the application but may include:

  • Using an automatic code generation tool to produce the code from the SDL design
  • Adapting the generated code (the running SDL system) to its environment i.e. regarding signal handling
  • Integrating the code to the hardware requirements by means of using real-time operating systems and cross-compilers to generate the executable for the hardware
  • Implementing and executing test cases in the target environment based on the design use cases from the system design activity


Summary

SOMT is a method specially designed to suit the development of distributed, reactive, real-time systems. It is based on well-established and industrial-strength techniques:

  • object models for analysis
  • SDL for design

SOMT recognizes not only a number of models to be made, but also the importance of having a glue between these models. Therefore, SOMT introduces the Paste As concept to provide a smooth and well-defined transition between the different models, e.g. between the analysis and design, enabling traceability using implinks.

The benefit for a development project is that the analysts and developers all can use the notations best suited for each phase of a development project. The object oriented analysis strength when analyzing requirements and creating conceptual analysis models is combined with the strong back-end given by SDL tools for design, verification and code generation.


References

  17. I. Jacobson, S. Bylund, P. Jonsson, S. Ehnebom, Using contracts and use cases to build plugable architectures, JOOP, May 1995.
  18. I. Jacobson et al, "Object-Oriented Software Engineering", Addison-Wesley, 1992.
  19. J. Rumbaugh, Getting Started, using use cases to capture requirements, JOOP, September 1994.
  20. J. Rumbaugh et al, "Object-Oriented Modeling and Design", Prentice Hall, Englewood Cliffs, NJ, 1991.
  21. J. Rumbaugh, OMT: The Development Process, JOOP, May 1995.
  22. ITU Recommendation X.680-683, Abstract Syntax Notation One (ASN.1), 1994.
  23. ITU Recommendation Z.100, Specification and Description Language (SDL), 1994.
  24. ITU Recommendation Z.105, SDL Combined with ASN.1 (SDL/ASN.1), 1995.
  25. ITU Recommendation Z.120, Message Sequence Charts (MSC).
  26. J. Ellsberger, D. Hogrefe, A. Sarma, "SDL - Formal Object-oriented Language for Communicating Systems", Prentice Hall Europe, 1997, ISBN 0-13-632886-5.
  27. A. Olsen, O. Færgemand, B. Møller-Pedersen, R. Reed, J.R.W. Smith, "Systems Engineering using SDL-92", North-Holland, 1994, ISBN 0-444-89872-7.
  28. F. Belina, D. Hogrefe, A. Sarma, "SDL with Applications from Protocol Specification", Carl Hansiger Verlag and Prentice Hall International, 1991, ISBN 0-13-785890-6.
  29. D. Coleman et al, "Object-oriented Development - The Fusion Method", Prentice-Hall, 1994.
  30. OMG, Common Object Request Broker: Architecture and Specification, Revision 2.0, Object Management Group, July 1995.
  31. Telelogic AB: Telelogic Tau 4.4 User's Manual, 1999.
  32. G. Booch, "Object Solutions - Managing the Object Oriented Project", Addison-Wesley, 1996.
  33. ISO Tree and Tabular Combined Notation ISO/IEC 9646-3 1992
  34. Unified Modeling Language, UML Notation Guide version 1.0, (document ad/97-01-09), Object Management Group, January 1997.
  35. David Harel, "Statecharts: a visual formalism for complex systems", Science of Computer programming (8), 1987.
  36. Unified Modeling Language, UML Notation Guide version 1.1 (document ad/97-08-05), Object Management Group, September 1997.
  37. Unified Modeling Language, UML Semantics version 1.1 (document ad/97-08-04), Object Management Group, September 1997.


69 SOMT Concepts and Notations

This chapter describes the major concepts and notations used in the SOMT method. The notations treated includes object models, state charts, SDL diagrams and Message Sequence Charts (MSCs). Note that the descriptions in this section only briefly describes the different notations. For a more thorough treatment, please consult a textbook on the specific notation.


Activities, Models and Modules

As seen in the previous chapter, the SOMT method describes object oriented analysis and design as a number of activities that produce one or more models. A model is here used in an abstract fashion to denote a collection of diagrams, text documents or whatever is needed in the particular model. The concept of a model is used to be able to discuss the results of an activity without going into detail of how the actual diagrams/documents are organized.

A module, on the other hand, is the concept used in SOMT to define how the diagrams/documents are organized. The major purpose of the modules is that they form units that should be fairly self-contained and that can be developed by themselves, maybe by different teams. A module is a container of e.g. diagrams and textual documents that has no semantics by itself but that forms a scope unit for names (if this is not given by the notation used). For example, if the Analysis Object Model is described in two modules that both contain a class called "Person", then these definitions do not refer to the same class. There will be two different "Person" classes, one in each module.

In practice it is beneficial to have a simple mapping between models and modules, either a one-to-one or, if a model is too large, a one-to many mapping where a model is decomposed into several modules.

The actual documentation produced according to SOMT is thus a collection of modules containing diagrams/documents that together form this particular projects representation of the SOMT models.


Implinks and the Paste As Concept

The SOMT method introduces a number of different models that are used to describe different aspects of the system. In particular there are three levels formed by:

  • The requirements that describe the problem and external requirements on a system
  • The system analysis describing the concepts used in the system
  • The system and object design that defines the structure and behavior of the system

One very common relation between objects in different models is that one object can be seen as an implementation of an object in another model. For example, an object in the object model created in the system analysis phase may be reintroduced in the design model as a process type or an ADT (abstract data type). Another example may be an object that was identified in the requirements analysis as something visible on the system boundary, and that later is reintroduced in the analysis object model and finally ends up as a signal in the SDL design. To represent this type of relations among objects the concept of implementation links (implinks) is used. An implink is a directed relation between two objects, usually (but not necessarily) in different models. Conceptually we get a picture as in Figure 606.

Figure 606 : Implinks between objects in different models

If used carefully, the implinks give a possibility to trace requirements all the way down into code. There are several situations where the implinks are very useful:

  • What if analysis. What are the consequences if a particular requirement is changed?
  • Consistency checking. Are all concepts in e.g. the system analysis model implemented?
  • Understanding design by following the links backwards from implementation to requirements. What is the purpose of a particular design object? What happens if we change it?

It is important to see that the act of creating an implink is a creative design action that encapsulates a design decision. The Paste As mechanism is a special concept used in SOMT to support the task of creating implinks. The idea is that an object in one model can be copied and then pasted as a new object in another model, see Figure 607. This action serves both to create the new object and to document the design step using an implink.

Figure 607 : Using Paste As to capture a design step from
the system analysis model to SDL


Consistency Checking

The SOMT method uses a number of models and notations and the checking of various aspects of the models is an important part of a development project. This checking can be formulated as a question of identifying "entities" or "concepts" in different models (or in one model), to identify some rules of how these entities should relate to each other, and finally to check that the models are consistent with respect to these rules. This type of checking is in this document called consistency checking. Three different types of consistency checking can be identified:

  • Checking the internal consistency within one model, e.g. checking that an SDL system is correct with respect to the syntactical rules for SDL
  • Checking that two models are consistent with respect to each other and some consistency requirement, e.g. checking that all classes in an object model are described in the data dictionary
  • Checking traceability aspects, i.e. checking that the entities in two models are correctly linked (using implinks) to each other. For example, checking that all objects in an analysis model are implemented in the design model

In some sense the checking of traceability aspects is a special case of the checking of the consistency between two models, but it is an important special case and it is given a special treatment in SOMT.

One general observation that can be made is that the identification of concepts/entities is very much depending on the particular notation used. Each separate notation will have to be treated separately following the particular rules that apply to this language. For formal languages like SDL, the concepts and procedures how to find the entities are well defined, while for other languages the rules are different, and for plain, informal text the entity identification will have to be explicitly done by the user. In SOMT there is a special possibility to "mark" words or phrases in text documents. The intention is that this marking means "this concept is important" or "this is a concept that I would like to for consistency checks".

In the rest of this volume, each activity of the SOMT method together with its associated models will be described in different chapters. Each of these chapters will also include a discussion on consistency rules that are relevant for this particular model.


Object Model Notation

The object model notation from Object Modeling Technique (OMT) and Unified Modeling Language (UML) is a commonly accepted graphical notation used for drawing diagrams that describe objects and the relations between them. The notation that is used in examples in this volume is shown in Figure 608 through Figure 613. For more details about other, more advanced OMT object model concepts, please consult [20], and for details about the UML notation see [36] and [37].

Class

The most important concept in an object model is the class definition. A class is a description of a group of similar objects that share the properties defined by the class. The object model notation for a class is exemplified in Figure 608, where the second class definition also shows how to define attributes and operations.

Figure 608 : A collapsed class symbol and a class symbol
with attributes and operations

In some cases it is necessary to reference classes from an external module. The notation used for this purpose is ExternalModule::Class.

Classes may inherit attributes and operations from other classes. The object model notation for this is shown in Figure 609.

Figure 609 : Inheritance between classes

Relations and Multiplicity

Classes may be physically or logically related to each other. This is shown in the object model by means of associations as shown in Figure 610. An association may have a name and/or the endpoints of the association may be labeled by the role of this endpoint.

Figure 610 : Associations between classes

Aggregation is special kind of association that has its own notation as shown in Figure 611.

Figure 611 : Aggregation

The endpoints of associations and aggregations may have a multiplicity as shown in Figure 612.

Figure 612 : Multiplicity of associations and aggregations

Module

In practise the complete requirements object model is often too big to fit into one diagram. To solve this problem it is possible to use multiple object model diagrams that can be organized into a module, which simply is a list of diagrams. It is important to notice that a class may be present in more than one diagram and still only represent one logical class.

Objects

Besides class definitions, object models may of course also contain objects and their relations. The relation that exists between objects are links, which corresponds to the associations for classes. The object symbol has one field containing the name of the object together with a reference to the class, and an attribute field where constant or default values can be assigned to the object attributes. See Figure 613.

Figure 613 : Objects related by links


State Chart Notation

The notation presented in this section is a subset of the notation for state charts presented by David Harel [35] which is used in the Unified Modeling Language (UML) [36] as well as in the Object Modeling Technique (OMT) [20].

A state chart model is suitable to use together with class and object models. The descriptions of the behavior of a class in a class diagram is collected into a state chart which describes the dynamic view of the model by means of states and transitions. The notation to use is presented below.

Notation

State

To describe state charts a state symbol is needed. The state symbol is divided into three compartments, State Name, State Variable and Internal Activity, which are all optional. The top compartment contains the optional name of the state. State symbols with the same name within the same context are considered to be the same. It is not necessary to name states and if several anonymous states exists; each anonymous state symbol is considered to be an individual state. Figure 614 shows a collapsed state and a state with state variables and events.

Figure 614 : A collapsed state symbol and a state symbol
with state variables and events

A state symbol may contain a State Variable compartment. This compartment highlights attributes of the class which are used or in some way affected by the behavior described in the state chart.

The third compartment is the Internal Activity compartment which describes the activities of the current state, activities that are done upon entering the state, activities taking place while in the state and activities executed when exiting the state. Each activity is described in the format:

event-name argument-list `/' action expression

Each event name may appear only once within a state symbol. The event names "entry", "exit" and "do" are reserved and they describe the following actions:

`entry' `/' action expression
An atomic action performed upon entering the state
`exit' `/' action expression
An atomic action performed upon exiting the state
`do' `/' action expression
An action performed during the state

Transition

The second necessary symbol for drawing state charts is the transition. The transition symbol is an arrow which connects two symbols of either type of state, start and termination, see Figure 615.

Figure 615 : The transition from state1 to state2 is triggered by the event
my_event and the condition that attr1 is less than attr2

The syntax for the transition symbol follows the format:

event-signature `[` guard-condition']` `/' action-expression `^' send-clause

The event-signature consists of the parts:

event-name `(` parameter `,' ... `)'

The guard-condition is a Boolean expression formed by the parameters of the triggering event together with possible attributes and links of the object described by the state chart.

The action-expression describes the action that is executed during the transition. The action may be described by procedures, affected attributes and links.

The send-clause has the format:

destination-expression `.' Destination-event-name `(` argument `.' ...')'

The destination-expression identifies the receiving object or a set of receiving objects.

The Destination-event-name is the name of an event that may be received by the receiving object(s).

Start and Termination Symbol

The start symbol denotes the starting point of a state machine described by a state chart and the termination symbol denotes the point of termination of a state machine. Figure 616 shows a simple state machine, describing the behavior of a door, including a start symbol and a termination symbol.

Figure 616 : A simple state chart with a start symbol and a termination symbol

Substates

States may be refined into nested diagrams of sub-states, or hierarchical states. The state represents a simplification of more complex behavior expressed in the nested diagram.

Figure 617 : A state chart with states and substates.

State Charts in SOMT

State Charts and SDL

Both State Charts and SDL process graphs are two notations used to express state machines. The two notations have both their advantages. State Charts are good for expressing high level functionality typically used in early activities like analysis. SDL is good for expressing detailed functionality as in design activities. SDL is also a formal notation, with well defined semantics, from which it is possible to generate code.

State Charts in Requirements Analysis

State charts might be used to express high level functionality of a system by focusing on the behavior of the system rather than the behavior of the system's parts. It might also be useful to express the behavior of complex actors that are interacting with the system.

State Charts in System Analysis

In the context of system analysis, state charts are useful to express the behavior of the system parts and how these parts interact dynamically. The architecture of the system is described in a class diagram named Logical Architecture. Using state charts in addition to the class diagram makes it possible to describe the dynamic properties and the behavior of the system or parts of the system. The behavior descriptions should be included in a set of documents called the Object Behavior Diagram which together with the Logical Architecture is part if the Analysis Object Model.

State Charts in System and Object Design

During the activities of System and Object Design, SDL process diagram is the preferred notation for describing the behavior of the system. The product of the Object Design activity should be a complete description of the system which enables code generation. State Charts, due to their weak semantics, may be useful to express a less detailed overview of rather complex behavior expressed in SDL.


Message Sequence Charts

A message sequence chart (MSC) is a high-level description of the message interaction between system components and their environment. A major advantage of the MSC language is its clear and unambiguous graphical layout which immediately gives an intuitive understanding of the described system behavior. The syntax and semantics of MSCs are standardized by ITU-T, as recommendation Z.120 [25].

There are various application areas for MSCs and within the system development process MSCs play a role in nearly all stages, complementing SDL on many respects. MSCs can e.g. be used:

  • To define the requirements of a system
  • For object oriented analysis and design (object interaction)
  • As an overview specification of process communication
  • For simulation and consistency check of SDL specifications
  • As a basis for automatic generation of SDL skeleton specifications
  • As a basis for specification of TTCN test cases
  • For documentation

Plain MSC

The most fundamental language constructs of MSCs are instances (e.g., entities of SDL systems, blocks, processes and services) and messages describing the communication events, see Figure 618.

Another basic language construct is the condition symbol which is drawn as a hexagon. A condition describes either a global system state referring to all instances contained in the MSC, or a state referring to a subset of instances (a non-global condition). The minimum subset is a single instance.

An MSC can reference another MSC using an MSC reference symbol. (Such a symbol can also reference a High-level MSC, explained later.) This symbol is drawn as a rectangle with rounded corners and has the name of the associated MSC stated inside it. MSC references can for example be used to have one MSC describing an initialization sequence and then reference this MSC from a number of other MSCs.

The reference symbol may not only refer to an MSC but can also contain MSC reference expressions that reference more than one MSC. This construct gives us a very compact MSC representation and it also provides an excellent means for reusability of certain MSCs.

The textual MSC expressions are constructed from the operators alt, par, loop, opt and exc:

  • An MSC reference with the keyword alt denotes alternative executions of MSC sections. Only one of the alternatives is applicable in an instantiation of the actual sequence.
  • The par operation defines parallel executions for MSC sections. All events within the parallel MSC sections will be executed (free merge) with the only restriction that the event order within each section must be preserved.
  • An MSC reference with a loop construct is used for iterations and can have several forms. The most general construct, loop<n,m>, where n and m are natural numbers, denotes iteration at least n and most m times. The operands may be replaced by the keyword inf, like in loop<n,inf>. This means that the loop will be executed at least n times. If the second operand is omitted, like in loop<n>, this will be interpreted as loop<n,n>. If both operands are omitted the interpretation will be loop<1,inf>.
  • The opt operation is an operator with one operand only. It is interpreted in the same way as an alt operation where the second operand is an empty MSC.
  • An MSC reference where the text starts with exc followed by the name of an MSC indicates that the MSC can be aborted at the position of the MSC reference symbol and instead continued with the referenced MSC. If the exception does not occur the events following the exc expression are executed. The exc operator can thus be viewed as an alternative where the second operand is the entire rest of the MSC. MSC references with exceptions are frequently used to indicate exceptional cases when using MSCs to formalize use cases.

Figure 618 : Example of a plain MSC

By means of inline operator expressions composition of event structures may be defined inside an MSC. Graphically, the inline expression is described by a rectangle with dashed horizontal lines as separators. The operator keyword alt, loop, opt, par or exc, placed in the upper left corner, are used with the same meaning as when used together with the MSC reference symbol.

Whether to use inline operator expressions or MSC reference symbols with an operator is a matter of taste. The same things can be expressed with both notations. Using inline expression several scenarios can be expressed in one single diagram, i.e. we just have one single file to handle. If we use MSC reference symbols to express e.g. exceptions and alternatives there is a need for us to handle several files. On the other hand, the diagram becomes less cluttered if we refer to other MSCs instead of trying to express all possible scenarios in it.

Figure 619 : A plain MSC with inline operator expression

For information about more plain MSC concepts, like e.g. timers, please consult the MSC standard Z.120.

HMSC

A high-level MSC (HMSC) provides a means to graphically define how a set of MSCs can be combined. Contrary to plain MSCs, instances and messages are not shown within an HMSC, but it focus completely on the composition aspects. You can get a picture of how an HMSC works in practice by comparing it with a road map. HMSCs, like normal road maps, may easily become quite complex if they are not structured in any way. Fortunately, HMSCs can be hierarchically structured, i.e. it is possible to refine HMSCs by other HMSCs. The power of the MSC language is considerably improved with the new concepts introduced with HMSCs. It is e.g. much easier to specify a main scenario together with all accompanying exceptions.

An HMSC is a directed graph where each node is either (see Figure 620):

  • A start symbol which denotes the start of an HMSC (there is exactly one start symbol in each HMSC).
  • A stop symbol which denotes the end of an HMSC.
  • An MSC reference used to point out another (H)MSC diagram which defines the meaning of the reference. The reference construct in HMSC can thus be seen as a placeholder for an MSC diagram or another HMSC diagram. Like a reference symbol in a plain MSC, an MSC reference symbol in an HMSC can contain references to several (H)MSCs through using MSC reference expressions and the operators alt, par, loop, opt and exc.
  • A condition symbol is used to set restrictions on how adjacent referenced MSCs can be constructed. An HMSC condition immediately preceding an MSC reference has to agree with the (global) initial condition of the referenced MSC according to name identification. All conditions on HMSC level are considered to be global, they refer to all instances contained in the MSC. They can be used to guard the composition of MSCs described by HMSCs.
  • A connection point which denotes that two crossing lines are actually connected. This symbol has no semantic meaning but is introduced only to simplify the layout of the HMSC.

Flow lines connect the nodes in the HMSC and they indicate the sequencing that is possible among the nodes in the HMSC. If there is more than one outgoing flow line from a node this indicates an alternative.

Figure 620 : Example of an HMSC


SDL

SDL (Specification and Description Language) is mainly used for specifying behavior of real-time systems. This section provides a small overview of the language. For further reading, we recommend [26], [27] and [28] as useful textbooks about SDL. The SDL language is standardized by ITU-T, as recommendation Z.100 [23].

An SDL system consists of the following components:

  • Structure
    • Hierarchical decomposition with system, block, and process as the main building blocks
    • Type hierarchies: inheritance, generalization and specialization are supported for hierarchical building blocks
  • Communication
    • Asynchronous signals with optional signal parameters
    • Remote procedure calls for synchronous communication
  • Behavior
    • Processes
  • Data
    • Abstract data types that can be inherited, generalized and specialized
    • ASN.1 data types according to Z.105 [24]. See "ASN.1"
  • Modularization
    • Components like block/process types, data types, and signals can be placed into packages that can be imported into a system, enabling separate development.

Structure

Figure 621 shows the hierarchical levels in SDL: system, block, process, procedure and service.

Figure 621 : The hierarchical decomposition of an SDL specification

A system must contain at least one block and a block must contain at least one process. Services can exist within a process, being executed one at a time, controlled by the received signals. Thus the incoming signal sets of services in one process must be disjoint. Using procedures is a way to structure the information within processes and services. Processes, services and procedures are described by a flow chart-alike notation, see "Behavior" .

The static structure of a system is defined in terms of blocks. Blocks communicate by means of channels.

The dynamic structure of an SDL system consists of a set of processes that run in parallel. A process is a finite state machine extended with data. Processes are independent of each other and communicate with discrete signals by means of signal routes.

Communication

Since SDL does not allow any use of global data, all information that has to be exchanged must be sent along with signals between processes, or between processes and environment. Signals are sent asynchronously, i.e. the sending process continues executing without waiting for an acknowledgment from the receiving process.

Signals travel through channels between blocks, and from one process to another via signal routes. See Figure 621.

Synchronous communication is possible via a shorthand, remote procedure call. This shorthand is transformed to signal sending with an extra signal for the acknowledgment. Remote procedures are often used when a process wants to offer services to other processes.

Behavior

The dynamic behavior in an SDL system is described in the processes. Processes in SDL can be created at system start or created and terminated dynamically at run time. More than one instance of a process can exist. Each instance has a unique process identifier (PId). This makes it possible to send signals to individual instances of a process. The concept of processes and process instances that work autonomously and concurrently makes SDL appropriate for distributed applications.

Figure 622 : Behavior described by an SDL process

A process must have one start symbol. Since a process is a state machine, a transition between two states is made only after a signal has been received. If there are no incoming signals the process is inactive in a state. In SDL a transition takes no time. To be able to model time, and to set time restrictions, there is a timer concept. Each process has its own set of timers that can be set to expire on different durations.

Data

The set of predefined sorts in SDL makes it possible to work with data in SDL in a traditional way:

  • Integer
  • Real
  • Natural
  • Boolean
  • Character
  • Duration
  • Time
  • Charstring
  • PId

More complex data sorts can be created by using arrays, strings and structs.

Abstract Data Types in SDL can be used for more than representing data, e.g:

  • Hide data manipulation
  • Hide algorithmic parts of a specification
  • Create an interface to external routines

Data manipulation is hidden in operators. For a more thorough description on how to use complex data structures with operators in practice, please see [31].

Structural Typing Concepts

The object-oriented concepts of SDL give you powerful tools for structuring and reuse. The concept is based on type definitions. All structural building blocks can be typed: system type, block type, process type and service type. An exception is the procedure that is a type in its original form.

Figure 623 : Package with type definitions

Type definitions may be placed outside the system in packages. Packages can be seen as libraries of frequently used functions. The structural typing concepts are shown in Figure 623. All types can inherit from other types of the same kind.

Figure 624 : A system diagram with block instantiation and communication

One of the major benefits of using an object oriented language is the possibility to create new objects by adding new properties to existing objects, or to redefine properties of existing objects. This is what is commonly referred to as specialization.

In SDL-92, specialization of types can be accomplished in two ways:

  • A subtype may add properties not defined in the supertype. One may, for example, add new transitions to a process type, add new processes to a block type, etc.
  • A subtype may redefine virtual types and virtual transitions defined in the supertype. It is possible to redefine the contents of a transition in a process type, to redefine the contents/structure of a block type, etc.

Figure 624 and Figure 625 describe adding and redefining properties in a system and in a block type while Figure 626 describes the same features in a process type diagram.

To be able to instantiate a type regardless the context (by means of channels), a special concept is needed: gates.

Since a channel always has to be connected to a signal route and the connection mechanism lies inside the process, a gate is necessary since it is a way to specify the connection in a transparent manner.

Figure 625 : An inherited block type diagram with process
specialization, instantiation and communication

In the inherited block type Control, the process ctrl is an instance of the process type Control.

Figure 626 : A specialized process type with added signals, a new
transition and a redefined transition

Graphical and Textual Notation

The SDL language supports two notations that are equivalent. Beside the graphical representation (SDL/GR), a textual phrase representation (SDL/PR) is standardized.


TTCN

TTCN (Tree and Tabular Combined Notation) is a special purpose notation to describe test suites [33]. TTCN is a language standardized by ISO for the specification of tests for communicating systems. TTCN has been developed within the framework of standardized conformance testing (ISO/IEC 9646).

With TTCN a test suite is specified. This is a collection of various test cases together with all the declarations and components it needs.

Each test case is described as an event tree. The tree is represented as an indented list in a table. The indentation represents progression with respect to time. See Example 597.

Example 597 : A TTCN test case

     Behavior Description               Constraint        Verdict
 1   DuToEnv? Display                   Enter_Card
 2    EnvToDu! Card                     Card1
 3     DuToEnv? Display                 Enter_Code
 4      EnvToDu! Digit                  digit1
 5       EnvToDu! Digit                 digit3
 6        EnvToDu! Digit                digit5
 7         EnvToDu! Digit               digit7
 8          DuToEnv? Unlock             nopar
 9           EnvToDu! Open              nopar
 10           DuToEnv? Display          Please_Enter
 11            EnvToDu! Close           nopar
 12             DuToEnv? Lock           nopar
 13              DuToEnv? Display       Enter_Card        PASS
 14        EnvToDu! Digit               digit1
 15         DuToEnv? Display            WrongCode
 16          DuToEnv? Display           Enter_Card        PASS

Each line consists of a line number, a statement, a constraint reference and a mandatory verdict. A statement can be:

  • An event
  • An action
  • A qualifier

The event statements are statements that can be successful dependent on the occurrence of a certain event, either:

  • Receive (represented by a "?")
  • Otherwise
  • Timeout

The action statements will always execute and will therefore always be successful:

  • send (represented by a "!")
  • implicit_send
  • assignment_list
  • timer_operation
  • goto

A qualifier is simply an expression that must be true if an event should match or an action should be performed.

In TTCN, the communication is asynchronous. The implementation under test, IUT, communicates with the environment via points of control and observation, PCOs. The interaction occurs at PCOs and are described by protocol data units, PDUs, embedded in abstract service primitives, ASPs.

At line 1 in s above, the ASP Display occurs at the PCO DuToEnv. The constraint Enter_Card determines exactly which ASP value is to be received.

The leaves in the tree are usually assigned a verdict.


ASN.1

ASN.1, described in [22], stands for Abstract Syntax Notation One. ASN.1 is a language for the specification of data types and values. ASN.1 is very popular for the specification of data in telecommunication protocols and services, especially in higher (i.e. application oriented) layers. Many telecommunication standards are based on ASN.1. Also TTCN is based on ASN.1. An example of an ASN.1 module is shown below.

Example 598 : An example of an ASN.1 module

ProtocolData DEFINITIONS ::=
BEGIN
- - contains data definitions for an example protocol

CheckSum ::= INTEGER (0..65535)

DataField ::= OCTET STRING (SIZE (0..56))

PDU ::= SEQUENCE {
sequenceNr INTEGER (0..255),
dataField DataField,
checksum CheckSum OPTIONAL }

END

A strong point of ASN.1 is that there are encoding rules that define how an ASN.1 data value is encoded to bits, the most well-known being the Basic Encoding Rules. From an ASN.1 data type definition, functions can be automatically generated that take care of the coding and decoding.

An ASN.1 definition can be imported into SDL as if it was a package. When an ASN.1 data type is imported into SDL, automatically a set of operators that is defined in Z.105 [24] is available for that type.

It is recommended to use ASN.1 for the specification of parameters of signals to/from the environment of the SDL system, especially when encoding rules are to be applied on such signals, or when a TTCN test suite is to be developed. In the latter case the ASN.1 definitions can be directly reused in the TTCN test suite.


70 Requirements Analysis

This chapter gives a thorough description of the different models in the requirements analysis activity as well as some guidelines on how to create these models. A recommendation on consistency rules that are relevant for the models in this activity is also included.

The chapter requires that you are at least reasonable familiar with the concepts concerning object models as well as the concepts concerning MSC diagrams.


Requirements Analysis Overview

The purpose of the requirements analysis is to establish an understanding of the application domain and to capture, formalize, analyze and validate the user requirements on the system to be built. For this purpose the system is viewed as a black-box and only the objects and concepts visible on the system boundary and outside the system are modeled.

The input to this activity can of course be very different depending on the application, from an extensive requirements specification provided by a customer to some more or less vague ideas not documented on paper. In any case the result of the activity should be the same: An understanding of the problem domain that the system is to be operating within and an understanding of the role the system is to fulfill in this environment, i.e. the requirements on the system to be built.

In many cases the requirements analysis can be divided into two activities:

  • A problem analysis
  • A system requirements analysis

The problem analysis concentrates on understanding the problem domain the system is going to operate in, without any reference to the system itself. The system requirements analysis focuses directly on the functional requirements on the system, viewed as a black box.

Figure 627 : Overview of the requirements analysis activity

An overview of the requirements analysis activity is depicted in Figure 627. As can be seen a number of models are used:

  • Textual requirements model as described in "Textual Requirements" . Some requirements are supplied as input to the activity, others may be produced within the activity.
  • Data dictionary, further described in "Data Dictionary" .
  • Use case model, described by text, plain MSCs, or plain MSCs in combination with HMSCs. The use case model shows the system and the actors interacting with the system. It is described in "Use Cases" .
  • Requirements object model using object model notation. This model includes both a problem domain model and context diagrams showing the system and the external actors that interact with the system. The requirements object model is described in "Requirements Object Model" .
  • System operations model, see "System Operations" .

The requirements analysis is a highly iterative process where the different tasks creating the different models are iterated over and over again but the following outline can give some guideline on how to structure the work:

  1. Study any textual requirements that are provided as input and other sources of information that are available, e.g. read text books about the problem domain and talk to potential users of the system. This may also include rewriting (or creating from scratch) the textual requirements to make them more complete or structured.
  2. While performing 1 above create a first version of the data dictionary, including lists of actors, use cases and important problem domain concepts.
  3. Create a first version of the requirements object model:
    • Use context diagrams to give an overview of the actors and the system.
    • Use an information model to describe the problem domain.
  4. Create a first version of the use case model.
    • Review and optimize the list of use cases found so far.
    • Describe the details of the most important use cases as text and/or MSCs. If the use cases are complex, HMSCs can be used in combination with plain MSCs. Start with the normal cases and leave the exceptional cases for the moment.
  5. Refine and extend the requirements object model and use case model until the use cases and their exceptions cover a sufficient part of the requirements. Add state charts to the requirements object model if the behavior of an object needs to be considered. When needed use system operations to define the details of the interactions between the actors and the system.


Textual Requirements

Conventional textual requirements are in most development projects an important input and result of the requirements analysis. In SOMT, the textual requirements model is simply one or more text documents. It is however important to include them within the scope of SOMT to get a possibility to create implinks from them to the other models in SOMT, and thus make it possible to trace the implementation of the requirements.

The source of the requirements may in some cases be the customers in which case the textual requirements form one of the inputs to the requirements analysis. In other cases the textual requirements are created by the development team as part of the requirements analysis.

Non-functional requirements are an example of a type of requirements that are important to capture, but may be difficult to formulate using the other models in the requirements analysis. The non-functional requirements may express properties about for example:

  • Performance issues like response time or number of transactions per second.
  • Reliability like the mean time between failure.

This type of requirements are most easily expressed in natural language and entered into the textual requirements model.

It is important to not only write down the requirements but also to analyze them. One aspect of this analysis is to mark all important concepts in the requirements that can be useful later when identifying objects and use cases.


Data Dictionary

The data dictionary is a textual list of all concepts that are defined during the analysis. The purpose of the data dictionary is to define a vocabulary that is common to all the members of the development team and to the customers and users of the system.

It is important to notice that the data dictionary is not a separate list of entities that is unrelated to the other models in the requirements analysis. Rather it can be seen as a different viewpoint on the same set of basic concepts that are used and defined in the use cases and in the requirements object model. For example all domain objects should be added to the data dictionary as soon as they are defined in the object model.

For each entity defined in the data dictionary at least the name of the entity and a brief explanation of the entity must be supplied.

Note that although the data dictionary is created in the requirements analysis it can be used during the entire development process and be updated when new concepts are found also in the other activities. The following Example 599 shows a part of a data dictionary for the access control system.

Example 599 : A part of a data dictionary description

NOUNS

Access control system - A system to control the access rights to an office. Unauthorized persons should not be able to enter without permission.

Card - Each employee working in the office has a card and a corresponding personal code.

Card reader - The hardware into which the employee enters the card. The cardreader reads the cardId.

Code - Each employee has a four digit personal code connected to the card. To enter the office the employee must type the code on the keypad.

Display - The hardware unit by which the system tells the employee what to do.

Door - Employees enter and exit the office by opening a door. The door is always kept locked and unlocks only when the employee enters the office with a valid card and code or when the employee is leaving the office by pressing the exit button. Each door provides a cardreader, keypad and display on the outside of the office and an exit button on the inside.

Keypad - The hardware unit used to type personal codes. The keypad has keys for the digits 0-9.

Employee - The holder of a position in the office. Every employee has a registered card with a personal code to get access to the office.

RELATION PHRASES

Card with code - Each employee in the office has a card with a a personal code.

Code consists of four digits - The personal code that every employee has got, consists of four digits.

Door provides local panel - Each door has a localpanel on the outside of the office. This localpanel is made up of a card reader, a display and a keypad.

Door provides exit button - Each door has an exit button on the inside of the office.

Registerfile contains employee identifications, cardnumbers and codes - The registerfile contains the data relevant to the access control system.

VERB PHRASES

Connection is lost - The connection between a door and the central controller can sometimes fail. In case of broken connection nobody can enter the office. It is, however, possible to leave the office.

Inform employee - The system gives the employee instructions by means of the display.

Enter office - A use case which describes the interaction between an employee and the access control system when the employee wants to enter the office.

Exit office - A use case which describes the interaction between an employee and the access control system when the employee wants to exit the office.
Validate card - The central controller validates a card with respect to info in the registerfile.

Validate code - The central controller validates the correctness of a code with respect to info in the registerfile.

In Example 599, the items in data dictionary are categorized into nouns, relation phrases and verb phrases. By categorizing the items, it may be easier to find the objects, attributes, operators, actors and use cases and also the relations between these entities in each model.


Use Cases

The most important problem to tackle when designing a new system is not to verify the correctness of the system or to get an optimized implementation. None of this matters if the system does not solve the right problem. User-centered requirements analysis using use cases is an approach to capture requirements from the user's point of view. The intention is of course that the users will be able to understand and validate the use cases, and thus confirm that they indeed define the right system to be built.

Consider a system that controls the access to a building, allowing users to enter the building through doors that can be opened by entering a card and a code into a card reader. Some typical use cases for this system may be:

  • "Register a new user"
  • "Open door"

An important term when discussing use cases is the notion of an "actor". An actor is an outside entity that interacts with the system. An actor can be a human being, a hardware unit, a computer program or anything else that can communicate with the system. Usually there is also made a distinction between the individual users of a system and the actors. An actor is not supposed to be an individual user, but rather represents one of the different "roles" individual users can play when interacting with the system.

Each use case describes essentially the possible sequences of events that take place when one or more actors interact with the system in order to fulfill the purpose of the use case. Note that the use case does not define one specific sequence of events, but rather a set of possible sequences.

A use case is thus simply a description, in one format or another, of a certain way to use the system. It has been found to be a very efficient way to capture a user's view of the system and the concept of use cases is now used in a number of object-oriented methods. The version used in SOMT is mainly a combination of the original use cases as described in [18] and the OMT version [19]. A difference is that, as will be seen below, SOMT puts some more effort in the formalization of the use cases to be able to use them for verification purposes during the object design.

In SOMT the use case model is in practise composed of three parts:

  • A list of actors
  • A list of use cases
  • The collection of use case descriptions

The list of actors should describe all actors that have been identified, why they use the system (or which service they provide to the system) and what their responsibilities are.

The list of use cases just gives a one-sentence description of each use case.

The lists of actors and use cases can either be separate documents or be a part of the data dictionary. The lists are particularly useful in the beginning of the requirements analysis when trying to identify the most important use cases and actors.

Two different formats are used to describe use cases in SOMT. One purely textual format and one format that uses MSC diagrams to define the use cases. Depending on the application (and the users) one or both of the notations can be used in a specific project. If the chosen approach is to describe the use cases by means of MSCs and they turn out to be very complex, it is possible to use a combination of plain MSCs and HMSCs to describe them. Most of the things that can be expressed with HMSCs can also be expressed by plain MSCs, so it is a matter of taste if you want to use HMSCs or not. HMSCs have certain advantages, especially if the system is complex:

  • They give a good overview of what is happening in the system and thereby facilitate understanding of the system behavior.
  • They make it easier to maintain the use case model.

The choice of notation for use cases is a matter of personal taste and the application at hand. There are four different possibilities:

  • Use only textual use cases.
  • Use only MSC use cases.
  • Give a brief textual description of the use case. Then give a complete formal MSC definition of the use case.
  • Give a complete detailed textual description of the use case, covering all exceptions etc. Then use MSCs to exemplify some of the more important cases.

Textual Use Cases

The textual format consists essentially of natural language text structured into a number of fields and is easiest introduced with an example. Consider the Enter building use case for the access control system that controls the doors of a building. This use case is depicted in Example 600.

Example 600 : Textual description of the Enter building use case

Use case name: Enter building
Actors: Regular user, Door
Preconditions: `Enter card' is displayed and doors are closed and locked
Postconditions: Same as preconditions
Description: A user enters a card into the cardreader. `Enter code' is displayed on the display. The user enters his code (4 digits) using the keyboard. The door is unlocked and `Door unlocked. Please enter.' is displayed. The user opens the door, enters the building and closes the door again. the door is locked again and `enter card' is displayed.
Exceptions: - If the user enters the wrong code then `Wrong code' is flashed for 3 seconds and then `enter card' is displayed.
- If the user does not open the door after it has been unlocked, then the door is locked again after 30 seconds and `Enter card' is displayed

As can be seen in the example, a use case has the following fields:

  • Name: The name of the use case.
  • Actors: A list of the actors involved in the use case.
  • Preconditions: A list of properties that must be true for this use case to take place.
  • Postconditions: A list of properties that are true when the use case is finished.
  • Description: A textual description of the "normal" sequence of events that describe the interaction between the actors and the system.
  • Exceptions: A list of exceptional interactions that complement the "normal" flow of events described in the Description field. If an exception leads to different postcondition properties compared to the "normal" sequence, this should be noted.

As with the textual requirements, it is important to analyze the textual use cases and clearly mark all important concepts in order to be able to use them when identifying classes and when performing consistency checks between the different models.

Message Sequence Charts

The second notation for use cases used in SOMT is Message Sequence Charts (MSCs). An MSC is a diagram that shows a number of communicating entities (called instances) and the messages that they exchange. Two MSCs that correspond to the "Enter building" use case are shown in Figure 628 and Figure 629. Figure 628 describes the normal case and Figure 629 describes one of the exceptions.

A comment to this use case: There is always a choice of how much to show in a use case. In this particular example there is of course a choice whether to show the interaction between the User and the Door that does not involve the system. There is of course such an interaction where the user opens and closes the door. What to do depends on the purpose of the use case. Is the purpose mainly to describe and understand the problem domain or is the purpose to define the precise requirements on the system? In this use case we have assumed that the purpose is to define the requirements so the interaction that does not directly involve the system is left out of the MSC.

Figure 628 : The "Enter_building" use case

Figure 629 : The exception "WrongCode" for the "Enter_building" use case

Identifying Use Cases

Often some use cases are found very easily from the purpose of the system, but in some cases it is more difficult. One strategy that works well, both as a means to find use cases and as a means to check that all important use cases have been found, is:

  1. Identify the actors.
  2. Identify the use cases needed by each actor.

These two tasks are discussed in the following sections.

Finding Actors

By reading the textual requirements model or discussing with customers, candidates for actors can be found through the answers to the following questions:

  • Which user groups need help from the system to perform a task?
  • Which user groups are needed by the system in order to perform its functions? These functions can be both:
    • Main functions
    • Secondary functions, such as system maintenance and administration
  • Which are the external hardware or other systems (if any) that use the system or are being used by the system in order to perform a task?

Now, we have a set of possible actors. From this, we have to decide if these candidates really are actors or if they are parts of the (software) system. By doing this, we identify the boundaries of the system. This step does not provide any final solutions and decisions taken here might be modified later.

If the actor represents a user, perhaps one, single user, try to keep the level of abstraction that comes with the actor concept. It might be the case that this specific user can perform some tasks that can be performed by other users and some unique tasks. Therefore, try to distinguish between the roles that the users can play, i.e. the actors, and the users themselves. See Figure 630.

Figure 630 : Example of difference between users and actors

Document all actors in a list, describe each actor by a name and describe briefly its role when interacting with the system. The description should contain the actors' responsibilities and the way the actor uses the system. During the process of identifying the actors these descriptions are most conveniently kept in the textual document that lists all actors. This can either be a separate document or a part of the data dictionary.

The set of actors may be due to changes after having started to describe the use cases. Especially the MSC diagrams are useful to pinpoint the problem of determining the actors. In practice this means that the activity of identifying use cases by defining actors and use cases should be performed iteratively.

Finding Use Cases

When you have defined a set of actors, it is time to describe the way they interact with the system.

Steps:

  1. For each actor, find the tasks and functions that he should be able to perform or tasks which the system needs the actor to perform. Search the textual requirements for verb phrases, these are possible candidates for use cases.
    • If possible, make the use cases as complete as possible, i.e. make one use case of a complex function rather than splitting it up into several use cases for each sub-function.
    • To begin with, concentrate on the normal cases. Leave the exceptional cases until a later stage.
  2. Name the use cases and enter them in a textual list of use cases.
    • The names should be informative and be accompanied with general descriptions of the use case functionality.
    • The naming should be done with care, the description of the use case should be descriptive and consistent. Example: the use case that describes when a person leaves deposit items to a recycling machine could either be named Receive deposit items or Returning deposit items, but the latter is preferable since it is usually better to give names that reflect the users point of view rather than the systems.
    • From the list of use cases, try to discard unnecessary use cases. A use case should represent a set of events that leads to a clear goal (or in some cases several distinct goals that could be alternative) for the actor or for the system.
  3. Describe the use cases using the textual use case format and/or give a formal description of the use cases using MSCs (combined with HMSCs if necessary). Use the terms in the requirements object model and data dictionary as much as possible. Focus to begin with on the normal cases.
  4. Refine the use cases by examining the exceptional cases that are possible for each use case.

Now, we have got a view of possible candidates for use cases. It is not sure that all of these need to be described in separate use cases; some of them may be modeled as exceptions to other use cases. Consider what the actor wants to do!

While finding (or specifying) the use cases, it might be the case that you have to make changes to your set of actors. All actor changes should be updated in the textual list of actors and use cases. The changes should be carried out with care, since changes to the set of actors affect the use cases as well.


Requirements Object Model

The purpose of the requirements object model is to document all the concepts found during the requirements analysis and the relations between these concepts. The benefits of establishing this type of model are obvious:

  • The developer and users get a common medium that can be used to check that they have a common understanding of the problem.
  • It can to a large extent be reused in the system analysis as a foundation of the system object model.
  • It is invaluable when new members of the development team are introduced into the problem domain.

As we have already seen there are different categories of concepts that can be described in the requirements object model. The two major types of requirements object model diagrams show either:

  • The logical structure of the data and information
  • The environment and context of the system, including the actors that use the system.

Finding the Objects

The classical question when discussing object models is: How do we find the objects?

The final answer to this question is yet to be found, but some obvious sources of information are:

  • The use cases
  • Textual requirements

The use cases are helpful in more than one way. They directly define the actors that interact with the system and these are of course obvious object candidates. They also describe what is to be entered into the system and what will come out of the system. This may be physical entities like the card in the access control system or abstract data like a data unit in a telecommunication protocol. In either case the entities that are transported in to or out from the system are likely candidates for the requirements object model.

If there exist textual requirements specifications a classical way to find the objects that may be useful is to study the requirements and note all nouns that are used. If a particular substantive is used in many places it may represent a concept that is worth including in the requirements object model.

Other possible sources of information that can be helpful in finding the objects include:

  • General domain knowledge from text books or experts
  • The physical environment the system will operate in

Finding Relations

After we think that we have found a sufficient number of objects, we want to relate these objects, or more generally, the classes. There are three different kinds of relations:

  • Aggregation - describing a "consists of" relation
  • Generalization or inheritance - describing a relation where one of the classes are generalized from the other class(es)
  • Association - describing how different classes (that are not closely related by aggregation or generalization) are related by means of information exchange

Relations can be found by

  • Searching the textual requirements for "relation phrases", for example: "card with code", "the central controller has access to the register file" and "each local panel consists of a display, a keypad, and a card reader"
  • Looking in the textual use case description

In order to increase to readability of the model, name the associations. If needed, you can also attach role names to each class in an association. Generalization and aggregation relations can also be named.

Finding Attributes and Operations

Closely related to the associations are the attributes. Attributes are entities (that could be classes of their own) that are considered to be individual for a class.For example: name, address and phone number could be three different attributes of the class person. This information can be found in:

  • The textual requirements
  • The use cases

Sometimes it is not easy to decide if an entity should be an attribute of a class or if it should be a class of its own and have an association to the other class. If the independent existence of a property is important, then it should be a class. Consider also possible future changes and extensions, this might also give a reason for making the entity a class of its own. Example: A card in the access control system could change owner after a reorganization.

Operations describe functionality of a class. Operations are often used to modify the attributes of a class. If an operator has features of its own (attributes that do not have to be known for the whole class), then it could be modeled as an individual class.

Operations can be found

  • By looking at the system operations and distributing the responsibilities to several classes
  • In the textual requirements
  • In the textual use cases

Information Modeling

The requirements object model forms a description of the problem domain in a graphical way using object model diagrams. The purpose of the requirements object model is to give an overview of the concepts used by experts in the problem domain when discussing various aspects of the problem. Notice that the object models give the overview of the concepts, more details should be defined in the data dictionary. In the requirements object model the focus is on classes and associations between classes.

Another way to view the requirements object model is that it at least should describe all concepts that are visible on the "outside" of a system. Note that this does not only include physical entities that a user can see but also the knowledge the user must have to be able to use the system.

As an example of a small requirements object model consider Figure 631 that shows a requirements object model for an access control system that describe the different kinds of persons that are of interest for the application area, how they relate to cards and codes and the structure of an office building.

Figure 631 : A requirements object model for an access control system

Context Diagrams

Context diagrams are intended to give a static overview of how the system will interact with its environment. This is accomplished by showing in a class diagram (if needed exemplified in instance diagrams) what external actors exist that will interact with the system. The context diagrams are obviously very closely linked with the use cases since they show all types of actors that are defined in the use cases. Actually, one of the major benefits with the context diagrams is thus that they in one (or a few) diagrams capture the static information that otherwise is hidden in the use cases. As an example, consider Figure 632 that shows a simple context diagram for the access control system.

Figure 632 : A context diagram for an access control system

Instance diagrams can be used to show specific configurations or examples as in Figure 633 which show a situation where there are three doors and two users.

Figure 633 : A context diagram using object instances instead of
classes to show an application example

An important aspect of the context diagrams is that they show where the borderline between the system and the environment is, event though it is shown in an abstract fashion.

Modeling Behavior

In some cases it is useful to give a description of the internal behavior of the most important objects that appear in the object model. Due to the simplicity of the notation State Charts is the preferred notation in the analysis activities. As an example consider the DoorLock object in Figure 631. A description of the behavior of this object is shown in Figure 634.

Figure 634 : An SDL state machine describing the behavior of the DoorLock object


System Operations

In the use cases a number of events can be found that form the elementary communication means that is used when the system and the actors interact. For example in the "Enter building" use case in Figure 628 there are several events, e.g. "enter card" and "enter digit". It is important to understand and document the events that are used in the use cases, since they define the interface between the system and its environment. This can be done in the requirements object model and in the data dictionary, but sometimes a more detailed definition is useful. This is the purpose of the system operations, a concept that originates from the Fusion method [29].

A system operation is a definition of what that system must do to handle an event. It defines declaratively the behavior of the system as a response to an event in terms of the changes of state and events that are output or returned. System operations are in SOMT defined using schemata containing structured text. As an example consider the system operation in Example 601 that defines the Enter card operation.

Example 601 : A system operation schemata for the enter card operation

Operation: EnterCard
Responsibilites: Informs the system of the fact that a card has been entered into one of the card readers
Inputs: Card identificatio Card reader identification
Returns: Enter code' is displayed
Modified objects: A `card' object,a `card reader' object
Preconditions: The door must be closed
Postconditions: The card identification is stored in a `card' object associated with the `cardReader' object with an id equal to the card reader identification that was an input to the operation

The different rows in the schemata has the following meaning:

  • Operation: The name of the system operation (equal to the name of the event that it handles).
  • Responsibilities: A short description of the operation.
  • Inputs: The data that is supplied as parameters.
  • Returns: The events that are returned to the outside of the system as a result of the operation.
  • Modified objects: The internal objects that are changed by the operation.
  • Preconditions: Predicates that define when definition of the operation given in this schemata is valid.
  • Postconditions: The postconditions for the operation define how the state of the system has changed due to the execution of the operation.

Note that in general more than one schemata is needed for each system operation: one schemata is needed for each possible variant of the preconditions.

The criteria for choosing to use the system operations in addition to the use cases are based on the estimated complexity of the operations/events in the use cases. If the events are simple there is no need for a more detailed description of them. If the events are complex, e.g. when they are parametrized with complex data structures or involve some complex algorithm, then system operations are useful as a means to define the details.


Consistency Checks

This section contains some consistency checks applicable to the models in the requirements analysis. The following list should be viewed as suggestions and must be adapted to the way the requirements analysis is performed in a particular project:

  • Check the use cases and requirements object model with actual users.
  • Reread the textual requirements and check that all important concepts are clearly marked as such.
  • Reread the textual use cases and check that all important concepts, like actors, are marked as such.
  • Check that all important concepts in the textual requirements model and in the use cases, and all entities in the requirements object model are added to the data dictionary.
  • Check that all important concepts in the textual requirements are modeled by the requirements object model.
  • Check that all actors in the use cases are modeled in the context diagram(s) and vice versa.
  • Check that all functional requirements in the textual requirements model are modeled by the use cases.
  • Check that all complex events in the use cases are described by system operations.
  • Check that the requirements object model follows the syntactic/semantic rules for object models.
  • Check that the MSC use cases follow the syntactic/semantic rules for MSCs.


Summary

The requirements analysis is an activity that is focused on understanding and documenting the problem domain and the requirements on the system. The major models produced are:

  • A textual requirements model
  • A use case model, where the different ways a system is to be used are defined
  • A requirements object model, i.e. a description of the objects needed to understand the problem domain and external requirements
  • System operations
  • The data dictionary, which is a list of concepts used in the problem domain and requirements


71 System Analysis

This chapter gives a thorough description of the different models in the system analysis activity as well as some guidelines on how to create these models. A recommendation on consistency rules that are relevant for the models in this activity and for the consistency between the models from the previous activity and this activity, is also included.


System Analysis Overview

While the purpose of the requirements analysis is to understand the problem to be solved and the requirements this puts on the system, the purpose of the system analysis is to understand the architecture of the system itself. Essentially the issue of the system analysis is to find out what objects are needed to implement the requirements on the system. This means that the system analysis to a large extent is an analysis of the information that is needed to be represented in the system and the structure of the system itself. Information is here used in a broad sense which includes not only the data to be manipulated in the system but also the containers for algorithms and interfaces.

The system analysis in SOMT is very similar to corresponding activities in other object-oriented analysis methods and the major input and outputs of this activity are illustrated in Figure 635.

Figure 635 : The major inputs and outputs of the system analysis activity

The main input to the system analysis is the requirements object model and use cases developed during the requirements analysis and the main output is another object model, the analysis object model that describes the logical architecture of the system. In addition to this model a use case model is also created in the system analysis to describe the dynamic aspects of the architecture and textual analysis documentation is used to document analysis results not suitable to be express as use cases or object models. The different models will be discussed in detail in the following sections, the analysis object model in "Analysis Object Model" and the use cases in "Analysis Use Case Model" .

The tasks to perform in the system analysis activity are thus essentially the following:

  1. Start defining an initial version of the analysis object model, in particular concentrating on creating an overall architecture of the application.
  2. Then start refining some of the most important requirements use cases to check that the architecture defined in the analysis object model will work.
  3. Continue by iterating between modifying/refining the analysis object model and creating more analysis use cases, either by refining requirements use cases or by describing particular mechanisms in the application.

In parallel with the tasks above it may also be necessary to study various aspects of the chosen architecture, e.g. with respect to non-functional requirements. These results can be documented in the textual analysis documentation.


Analysis Object Model

The intention with the analysis object model is that it is a means to describe the architecture, i.e. the main objects that need to be implemented in the completed system. The notations used are the same as for the requirements object model in the requirements analysis. An overview of the notations is given in "Object Model Notation" and in "State Chart Notation" .

At a first glance the requirements object model in the requirements analysis and the analysis object model in the system analysis seem similar but there are several reasons to distinguish between them. The major motivation is that the purpose of the models are different: The purpose of the requirements object model is to investigate and describe the problem that the system is to solve and the environment that the system is to operate in, while the purpose of the system analysis model is to analyze and define the architecture of the system itself. Another more pragmatic difference is that the requirements object model consists of objects visible on the border of the system and outside the system, e.g. users of the system, while the system analysis object model is focused on the internal object structure of the system.

In the same way as the requirements object model can be structured into a number of different diagrams, the analysis object model can naturally also be decomposed into more than one diagram. This is even more important than it was for the requirements object model since the analysis object model tends to be much larger than the requirements object model.

The Logical Architecture of the System

The major purpose of the analysis object model is to describe an object structure that defines the logical architecture of the application. It describes how the application at a certain level of abstraction can be considered to be divided into a number of subsystems or objects that together fulfil the requirements posed on the application.

For each class that is identified in the logical architecture the most important issue is to note the responsibilities of this class. Why is the class included into the architecture? What is it supposed to do? The responsibilities of an object of a specific class are described by answers to a set of questions:

  • What information or knowledge is the object responsible for maintaining?
    • This is described by the attributes of the class.
  • What should the object be able to do?
    • Described by the operations of the class.
  • What other objects does the object need to know to fulfill its responsibilities?
    • Defines associations and aggregations to other classes.
  • Are the responsibilities of objects of this class similar to that of other classes? Is it "the same as class ... except that..."?
    • Defines inheritance relations.

The result when identifying different objects and answering the questions above is one (or more) class diagrams that describe the architecture of the system. The responsibilities are described by the operations and attributes. The associations between the classes in the model represent needs for objects to be aware of other objects to be able to fulfil its task. As an example, consider Figure 636 that describes the architecture of the access control system.

Figure 636 : Object model diagram describing the system architecture

Note that object analysis model can be viewed as a refinement of the context diagrams in the requirements object model.

Finding the Objects

The objects in the analysis object model can come from several different sources. Some useful examples are:

  • objects from the requirements object model
  • objects from interfaces
  • objects from use cases

These different sources are described in the following sections.

Requirements Object Model as Source of Objects

The requirements object model is of course one of the major sources of objects for the analysis object model, in particular for the information modeling part. Since the requirements object model should contain most of the objects in the problem domain a lot of them will probably have to be represented in the system and should thus be part of the analysis object model. Note however, that in this case it is not the same object that is found in the requirements object model and the analysis object model. The object in the analysis object model is in this case a container of information about the "real" object that is modeled in the requirements object model. In many cases of course entire inheritance and/or aggregation hierarchies can be reused in the analysis object model as illustrated in Figure 637. Notice that the Guard object is not needed to be represented in the system and thus is not introduced in the analysis Object Model.

Figure 637 : Reuse of requirements object model in the analysis object model

The objects found in the requirements object model usually have one thing in common, they represent entities in the real world that the system needs to store information about.

An algorithm to find the information objects needed by the system based on the requirements object model can thus be phrased as follows.

  • For all objects in the requirements object model:
    • Decide if the system needs information about this object to fulfil its task.
    • If the answer is "yes" then add it to the analysis object model using Paste as to get the implinks and thus provide traceability back to the requirements object model.

Objects from Interfaces

Another useful way to find objects is to consider the interfaces that the system will have to the environment. It is often very useful to introduce a special kind of object that hides the specific features about how to access the interface from the rest of the system. In [18] these kind of objects are called interface objects. Where do we get the interface objects from? There are several different sources to search:

  • The application area itself, which in some cases make it obvious what interfaces must exist in the system.
  • The use cases from the requirements analysis can be searched for interface objects:
    • They may explicitly identify some interface, e.g. "The user enters a card into the card reader".
    • Since they define actors that communicate with the system, each actor must use some kind of interface when interacting with the system, even if it is not stated explicitly which interface that is used. So by starting with the actor we may analyze what interfaces he/she will need. If nothing else the actor itself may introduce an interface object.

One important motivation for introducing interface objects is to make modification of the system easier. If the hardware of an interface is changed, e.g. the card readers of an access control system, then the logic of how to handle them is encapsulated in one object. This makes it likely that this object is the only thing that needs to be changed in the software.

Performance requirements are another motivation to introduce interface objects. Very often the interfaces can be a bottleneck with respect to performance. By encapsulating the interface in one object providing high-level operations to the rest of the system it is possible to make an optimized implementation of this object, e.g. making special purpose hardware or enhance the performance.

As an example consider the access control system and specifically the Enter building use case described in text in Example 600. From this text we can directly find a number of interfaces: a card reader, a display, a door lock, etc. All of these are likely candidates to result in interface objects in the analysis object model. When describing the interface objects it is usually fruitful to use a communication style class diagram to show how they interact with the external actor and the relevant objects in the analysis object model. If the interaction is non-trivial it might also be a good idea to show the interaction pattern using one or more MSC use cases that describe the different ways this particular object interacts with its environment.

Objects from Use Cases

The use cases can be used as a tool to find the objects that are needed. The strategy is to take a use case and investigate how the functionality that is implied by the use case is distributed among the objects in the analysis object model. One way to do this is to produce an MSC that describes the interaction as described in "Analysis Use Case Model" . Check which interface objects are involved, which internal objects are modified or accessed and consider the question of introducing a special controller object to encapsulate the sequencing of the use case. Is there already a control object that might take on the responsibility, or is there a need to create a new control object to handle the logic of the use case?

Consider for example the Enter building use case described textually in Example 600 and using an MSC in Figure 628. Since this use case contains a sequence of steps the system needs to represent that essentially has to do with the state of one of the doors and the associated lock and other devices, a special control object DoorControl seems natural to introduce. This could give an object model diagram as in Figure 638.

Figure 638 : An object model diagram that introduces the DoorControl object

Notice that the objects in this object model correspond to the interface objects that more or less directly could be extracted from the use case text together with the new control object. It may in this context be useful to name the objects according to their function. The interface objects are in this example called "XXInterface" and the control objects "XXControl" or something similar.

Notice that this model also introduces associations between the interface objects and the control object. These associations represent the communication paths that are needed among the objects. In one way or another information will flow following these associations.

Another type of object that might be found when analyzing the use cases are DataServer objects. These objects define the access possibilities to (complex) data structures. There are several possible sources to search for these type of objects:

  • The object structures that come from the requirements object model represent information that has to be stored in the system. In many cases there is a need for a DataServer object that "owns" this information and that provides an access to it. So, investigating the objects from the requirements object model and how they are to be used is a way to identify DataServer objects.
  • A second source of information is given by the use cases, since they often express the need for some kind of computation that involves several, related objects. When there is a need for a more complex algorithm that operates on an object structure a DataServer object might be useful.

By once more analyzing the Enter building use case described in Example 600 we can see that there is a need for a checking mechanism that determines if the code a user enters is the correct code associated with the card he previously has entered. This indicates the need for a CardAndCodeDataServer object that is responsible for maintaining the information about cards and code. Furthermore we can see that a likely operation on this object is a Validate operation that tells if one particular combination of card and code is correct. This may give an object model as in Figure 639.

Figure 639 : An object model diagram introducing the
CardAndCodeDataServer object

Finding Attributes and Operations

As discussed above the attributes and operations are used as a means to describe the responsibilities of objects. They describe the purpose of introducing an object into the model by answering the questions:

  • What should the object be able to do?
  • What information or knowledge is the object responsible for maintaining?

In practise, the attributes can be found for example:

  • In the use cases
  • In the requirements object model (by keeping already described attributes)
  • In the textual requirements

Some useful sources of operations are:

  • The requirements object model (keeping the existing operations)
  • The analysis use case model (the messages in the MSC diagrams)

The MSC messages in the analysis use case model can often be considered for operations in the analysis object model. Consider the behavior patterns in the use case model as well, since they often describe the functionality on a more detailed level.

Finding Associations

As discussed above the associations are used to show how object of one class need to know other objects. Usually the associations are found when analyzing the responsibilities of the classes since the motivation for introducing an association is that it is needed by a particular object.

However, some other sources where it is useful to look for the associations are:

  • The requirements object model (preserving or modifying existing relations)
  • The textual requirements
  • The analysis use case model

In particular the last source, the use cases are important. The activity of finding associations in the analysis object model and the activity of constructing the analysis use case model are closely related.

Describing Object Behavior

Sometimes it is useful to describe the behavior of the objects presented in the Logical Architecture. The Analysis Use Case Model describes how objects of the Logical Architecture interact. State Charts describe how these objects reacts internally as a result of the interaction presented in the Analysis Use Case Model.

Figure 640 : A state chart describing the behavior of an object

It is not necessary to describe the behavior of every object in the Logical Architecture. The focus should be on objects with complex behavior and where complex data structures are dependent of the state of their object. Modeling the behavior of an object will lead to a better knowledge of how the object will function internally. "Which are the actions of the object?", and "what data structures are needed?" are some questions that may be answered. If an object is too complicated it might be necessary to divide its class into several smaller classes which should be reflected in the corresponding class diagram. In other words: the relationship between the Logical Architecture diagram and the Object Behavior diagram is bidirectional.

When creating a state chart, the Logical structure is the obvious source of information. It is necessary to consider the object's class specification when specifying its behavior. An operation on a class will lead to transitions in the behavior model. A transition may lead to an internal action or a sending of an event to an external object. A transition may also lead to value changes of the object's attributes. If these attribute changes are important they should be reflected in the state chart. The operations on the class may also be found in the Analysis Use Case Model together with the possible sending of events.

Architecture of Large Systems

For large applications it is also often necessary to divide the analysis model into more than one module, e.g. to facilitate an analysis by more than one team. One possible strategy for doing this is a recursive approach where we first make an architecture on a high level, where each class represents a subsystem. Then each subsystem is refined by a separate team. It is important to be vary careful about the responsibilities of the classes in the top-level architecture, as described by their attributes and operations, since they will form the input to the different analysis teams.

In this context it is useful to use aggregations to describe a "subsystem" or "is-composed-of" relation, i.e. to describe how the system is decomposed into parts that recursively are decomposed into smaller parts. As an example, consider Figure 641 that describes the structure of the access control system. In this example the system is composed of one or more DoorCtrls, one CentralCtrl and one OperatorCtrl. The OperatorCtrl is itself composed of a component handling remote communication (RemoteCom) and a UserInterface.

Figure 641 : Using aggregations to describe the access control system

Note that the usage of aggregation as a means to describe subsystem relations has an impact on the object structure. Since the assembly classes are used to represent aggregation of classes and not single objects, they should in general not have any "intelligence" by themselves. This implies that the operations provided by the aggregate classes in practise should be implemented by one or more of the parts classes that the aggregate class contain.

It is a good practise to make the decomposition into modules aligned with the top-level architecture. One top level module architecture of the upper level of the application, identifying the responsibilities of the subsystems. The leaf classes of this top level architecture are then defined in separate modules possible by different analysis teams. The top level module then forms an interface or contract between the analysis teams.

It is impossible to give any rules for how to find the best way to divide a system into subsystems, but most authors agree on some measures to tell if a certain decomposition is a good one. The following two rules are from [5] describing OMT guidelines for decomposition interpreted in the SOMT context:

  • The structure must be designed so that most interactions are within the subsystems and not across the boundaries.
  • A system should not be divided into too many subsystems, 20 is probably too many. It is better to use a hierarchy of subsystems instead.

The subsystems may be chosen based on several different approaches, but the major idea is to group together objects, that together provide a certain function to the rest of the system, into a subsystem which then can be used as an abstraction of the entire group of objects.


Analysis Use Case Model

The purpose of the analysis use case model is to show the dynamic view of how the functionality of the system is decomposed in the same way as the analysis object model describes the static view of the decomposition. This implies that the internal communication between the various parts of the system is the major concern for this activity. Two different types of use cases can be distinguished in the analysis use case model:

  • Refined requirements
  • Behavior pattern use cases

Refined Requirements

The analysis use cases that are refined requirements are simply the use cases from the requirements analysis refined to the analysis object model level. Each requirements use case is distributed among the objects from the analysis object model. The purpose of these use cases is mainly to document how the logical architecture as described in the analysis object model is capable of implementing the requirements that are expressed by the use cases. In practice this is done by taking each of the use cases defined in the requirements analysis and reformulate it in terms of the objects that are defined in the analysis object model. It is possible to use both the textual use case notation and the MSC notation to represent the use cases, but since the purpose of the analysis use case model is to show how the functionality is distributed among the objects the MSC notation is especially useful. As in the requirements analysis, HMSCs can be used to simplify the use case model.

Consider again the access control system with a logical architecture according to Figure 636 where the system is divided into a DoorCtrl, a CentralCtrl and an OperatorCtrl components. If we take the Enter building use case as defined by an MSC in Figure 628 and replace the system with the three components we get an MSC as shown in Figure 642.

Figure 642 : The Enter Building use case distributed over a logical architecture

In this MSC we can see that the original system instance is replaced by instances of DoorCtrl, CentralCtrl and OperatorCtrl. This use case deals mainly with the handling of user interaction at the door and since this is the responsibility of the DoorCtrl most of the action is performed by this component. Only the validation of the card and code is performed centrally.

It is easy to see that the strategy outlined above is extendable to allow a decomposition of a system into not only one level of components, but into a hierarchy of components. For each new level of decomposition all use cases that involve the decomposed components are taken as input to the validation of the new decomposition. The component that was decomposed is replaced by the new components and new versions of the use cases are created.

Behavior Patterns

When designing the object structure for a system there is often a need to document behavior patterns that involve one or more objects that participate to fulfill a common objective. Sometimes this can be described in the refined requirements use cases, but there are two advantages of creating special use cases for specific mechanisms and behavior patterns:

  • By describing detailed communication patterns in special use cases, the refined requirements use cases can be on a higher level of abstraction and are not made unnecessary complex.
  • By focusing special use cases on specific parts of the system, it is easier to understand and maintain the requirements of the involved object than if these where distributed among all the refined requirements use cases.

As an example consider the keyboard interface of the access control application. The purpose of the keyboard is to allow the user to enter a code consisting of four digits. In a refined requirements use case showing a user entering an office by pushing the digits on a keyboard this can be shown using an MSC reference symbol, as in Figure 643.

Figure 643 : Part of a refined requirements use case

What happens when the user enters a code is thus described in the MSC Enter_Code. We see that it is the user and the DoorControl object that are involved in this interaction.

However, there is of course a specific protocol for Keyboard objects that defines how they interact with the user and the DoorCtrl that is not shown on the abstraction level of the refined requirements use case. This may for example look like in Figure 644, which shows the behavior pattern use case Enter_Code.

Figure 644 : A behavior pattern use case showing the
protocol for Keyboard interface objects

Other examples of behavior patterns that may need special use cases are internal communication between different parts of a system using proxies (i.e. local dummy objects that are used instead of a remote object and hides the communication aspect from the user of the proxy), initialization protocols that describe how various objects are created and exchange information, and in general all other tactical solutions to problems that need a special explanation in the system analysis.


Textual Analysis Documentation

In many cases there is a need to express aspects of the architecture or architecture related requirements in a textual format as a complement to the more structured object models and use cases. This may for example be to record experiments performed to check performance aspects of the architecture or other non-functional requirements. Other examples may include documentation of risk assessments performed in the system analysis phase.

To satisfy this need SOMT allows different textual documents to be included among the analysis documentation.


Requirements Traceability

One important aspect in the system analysis is the relation between the models that are created in this activity and the requirements, both external requirements specifications and the models from the requirements analysis. Important questions are:

  • Have all requirements been implemented?
  • Which are the system analysis objects that implement one particular requirement?
  • Which are the requirements that are implemented by one specific object in the analysis object model?

To be able to answer this type of questions it is important to create and maintain descriptions of the dependencies between concepts among the requirements and system analysis concepts. As discussed in "Implinks and the Paste As Concept" the means to do this in SOMT is given by what is called implementation links (or implinks for short). An implink is an association between two concepts where one of the concepts implements the other. One example is the implinks that exist between objects in the requirements object model and the corresponding object in the analysis object model. Consider for example Figure 637 that illustrates how domain objects are modeled in the analysis object model. In this case there should for example be an implink between the Operator object in the requirements object model and the Operator object in the analysis object model.

Another example is the links between use cases on different levels. Links between the requirements use cases and the analysis use cases show that the requirements are handled on the system analysis level.

In particular when doing "what if..." analysis of the consequences a modification or extension of the system has, these type of links are invaluable. For example consider the case where we would like to specialize the concept of an Operator into RegularOperator and ChiefOperator where the chief operator has some special privileges that a regular operator does not have. We then look at the requirements object model and try to understand what consequences this modification will have. With an implink we immediately see that the analysis object OperatorInfo will have to be changed and with further links from this object we can get a good idea of the consequences caused by the modification.


Consistency Checks

This section provides a list of consistency checks that can be made on the models produced by the system analysis.

  • Check that all use cases from the requirements analysis have been refined to analysis use cases.
  • Check that all entities in the requirements object model are either represented in the analysis object model or not really needed by the application.
  • Check that the object model diagrams and MSCs conform to the static rules for each notation.
  • Check that the instances in the MSCs correspond to classes in the object model or to actors that interact with the system.
  • Check that the messages received by the instances in the MSCs correspond to operations on the corresponding classes. Note that for remote procedures there may be two messages in an MSC for one operation, one message for the request and one for the reply. In this case the reply message should not have any corresponding operation.


Summary

The system analysis is an activity that is focused on understanding the system to be built. The major tools to facilitate and document the understanding of the system are the analysis object model and the analysis use case model. The analysis object model is intended to capture the objects that are needed in order to describe a solution of the problem.

The analysis use case model describes how the objects in the analysis object model cooperate to fulfill the requirements posed on the system by the use cases from the requirements analysis.


72 From Analysis to Design

This chapter describes the differences between analysis and design activities. The aspects to cover when you are moving from object models to SDL, are also described.


From Analysis to Design - Overview

The task of moving from the analysis model of a system to a design of the system is a creative step that involves many design decisions to be taken. The reason is that the purpose of the analysis model is to give an abstract understanding of the system to be built, and an understanding of the concepts that are needed in order to describe a solution of the problem the system is to solve. The purpose of the analysis model is not to give a precise definition of how the problem is to be solved or to decide how the architecture and reuse issues are taken care of. These aspects are the purpose of the design activities. Both the system design and the object design are focussed on these type of questions that are necessary to solve in an efficient way in a development project.

The SOMT method introduces a specific concept to emphasize the task of moving from one model to another. It is particularly useful when moving from the analysis model, with its abstract view of the problem, to the design model, with its constructive precise definition of the system that solves the problem. This is the Paste As concept that was introduced in "Implinks and the Paste As Concept" .

During design the idea is to encapsulate the creative design action taken when moving from the analysis model to the design model into one visible action. From a pragmatic point of view the designer just takes an analysis object and pastes it as a design object. However by doing this simple action the designer documents a number of the design decisions that are involved in the design activity.

Figure 645 : The Paste As concept

One important aspect of the paste-as concept is the relation to traceability links between different models. When performing the paste-as action the designer not only creates design objects. He also creates a link between the analysis object and the design objects. This link defines in a precise and compact way the design decisions taken. The links are a vital part of the project documentation that is automatically created by the tools. The links can be inspected when understanding the system and can be used for a number of purposes, e.g.:

  • Verification that all analysis concepts are implemented
  • "What if" analysis, what happens if one analysis object is changed because of changed requirements


Analysis vs. Design

When comparing analysis to design there is always a question of where the borderline between the activities are. In practise the distinction between analysis and design is somewhat arbitrary. From a practical point of view the important decision is not to define exactly what to call a specific activity, but rather to decide where to document a decision: in the analysis documentation or in the design model. The most important input to guide this decision is to consider the purpose of the different models. The analysis model has a focus on the architecture and most important concepts in the system, abstracting away from implementation details. It is used to provide a means to understand the application as efficiently as possible. The SDL design, on the other hand, is a complete definition of all necessary details.

In the context of mapping object models to SDL in SOMT the trade-off between analysis and design, essentially is a matter of where to document a decision:

  • In the object model
  • In the SDL model

As an example of this type of question that either can be described in the analysis model or in the design model, consider the issue of the traversal direction of an association, i.e. is the association a one-way or two-way association.

If the choice is to be made in the object model a notation or convention is needed to make it possible to add the extra information. For the one-way/two-way associations a possible notation could be to use an arrow head to denote the direction of the association. Note that this is only an example. SOMT does not recommend this convention.

If the choice is to be documented in the SDL model there is a choice of how the designer expresses his/her choice:, either

  • During the Paste-As
  • Directly in the SDL model

The result is in both cases the same: The design choice is documented in the combination of the implink (that defines the relation to the analysis model) and in the SDL model (that defines the details of the design choice).

For the one-way/two-way association the Paste-As alternative would imply that the designer interactively entered information as a parameter to the Paste-As of a class to a SDL data type that defined weather an association would be visible in the SDL data type. The association would only be visible if the direction was from the given class (or it was a two-way association).

If the one-way/two-way design choice was to be expressed directly in SDL the designer would manually either include or not include the association in the SDL data type corresponding to the class.

SOMT makes a trade-off between the different alternatives to accomplish an as smooth as possible transition from the analysis model to the design model. The SOMT mechanism is based on the following:

  • The information that is naturally found in an analysis model is used as far as possible to deduce the mapping to SDL.
  • The Paste-As functionality is defined to encapsulate the major design choices, like if an object will be mapped to a process type, struct data type or to some other concept. Paste-As also provides a predefined default choice for all other, minor design choices that have to be made. The intention is that the default settings should be useful in many cases, but in general some of the default choices will have to be modified during the design process.
  • The designer will make the final design decisions directly in SDL. This implies that the SDL model is the artifact that documents most of the design choices.

The rationale behind this mechanism is mainly to be able to fulfil the objective of the analysis and design models as good as possible. The analysis model should define the high-level architecture and provide a sound basis for understanding the application as efficiently as possible. To facilitate this the analysis model should be as abstract as possible while still containing all relevant information. The implication is that design decisions that are not needed to understand the application as far as possible should be kept in the design model and that abstractions should be used as much as possible in the analysis.


Active vs. Passive Objects

One choice to be made when moving from analysis to design is to decide whether an analysis object is to be implemented as an active object or a passive object. An active object is one that has its own thread of control and that can exhibit an autonomous behavior without any other object acting upon it. An active object can be viewed as executing in parallel with other active objects. In a distributed system the active objects may execute on different hardware. In other cases the scheduling mechanisms and operating system creates an abstract interface on which the active objects are executing. One important implication of this is that when two different active objects interact, e.g. when invoking operations, this interaction is a communication between two parallel possibly distributed applications over some communication medium. The communication may be synchronous, e.g. in a client-server relation between objects; the client requests a service from the server and waits for a response from the server before continuing, or asynchronous, e.g. when peer entities are performing a common task using a specific protocol.

A passive object on the other hand does not have its own thread of control. It changes state only when it is being operated upon by another object. Typically a passive object is mainly an information container used in the system to store information about the outside world and the internal state. If the information handled by a system is complex then an entire structure of passive objects may be needed to model it. Often, particularly in distributed applications, there is a relation between the active objects and the passive objects in the sense that an active object "owns" a passive object. The passive object is part of the same thread of control as the active object and it is localized in the same place in the system structure. An example of this might be an active data base server object that handles the control of the access and operations on a data base defined by a number of passive objects. This is very similar to the notion of "container classes" that are used as abstractions of the classes that they contain.


Reuse Issues in the Design Models

Another aspect of objects is if a particular object class is subject to reuse or not. The reuse may be on different levels of ambition. The lowest level of reuse is when an object is reused within one subsystem in an application. This has no major implication on how to package the object definition. Since one subsystem is most often developed by a small group of individuals there are no special requirements on the packaging of the object. The next level is when an object class is found to be useful in different subsystems implemented by different development teams. This situation makes things a bit more complex, since the object definition now probably should be grouped together with other similar objects and put in a special package. This package is used by many of the development groups and there may even be a special team devoted to the development of this support package. In any case it needs its own version control, interface definitions etc.

The third level of reuse is when an object is found so general and useful that it can be used in more than one project for more than one application. In this case there is obviously an even stronger need for a packaging mechanism, since the object together with other related objects now must be seen as a separate product.

Designing an object that is suitable for reuse requires special care: already early in the design it is necessary to identify that an object might be suitable for future reuse. Then the object needs to be specially designed to make it as general (and reusable) as possible. Careful thinking is also required to identify the parts of the object that later might have to be redefined when reused. These parts have to be marked "virtual" in SDL. A rule of thumb is that it is worthwhile to design a reusable object when it is expected that the object can be reused at least three times.


Mapping Object Models to SDL

When moving from an analysis view of an application to a design of the application, one of the major tasks is to define the relation between analysis concepts and design concepts. There are two different ways to view this: either the design is seen as an elaboration and refinement of the analysis model or the design can be seen as a transformation of the analysis model. In practice both viewpoints are useful. When creating the design a transformation is performed from the object model developed in the analysis activity to the SDL design models. The concepts in the object model are mapped to suitable concepts in the SDL domain. However, when this mapping has been done the analysis model is used as an abstract view of the application where only the details relevant from an analysis perspective is present and the design is viewed as an elaboration and refinement of the analysis model.

When mapping object models to SDL there are several aspects to cover:

  • Mapping the structure of object models to the structure of SDL
  • Mapping the interfaces of objects to interface definitions in SDL
  • Mapping the classes in the object model to SDL definitions
  • Mapping existing state charts to SDL process definitions

The structure of an object model of interest for the mapping to SDL are of two kinds:

  • The aggregation structure in the class diagrams
  • The module structure that defines how the complete object model is divided into different modules

The aggregation structure in the object model is in general in SDL represented by the block hierarchy as described in "Architecture Definition" . The actual mapping between the object model and SDL involves creating the block structure based on the aggregation structure and is further discussed in "Mapping Aggregations of Active Objects" .

The module structure of the analysis model is one of the inputs to the definition of the design module structure. In SDL the major code structuring concept is the package and in general it is recommended to keep a simple mapping from the module structure of the analysis model to the packages in the SDL design. This is further discussed in "Design Module Structure" .

In SDL the interfaces of processes, blocks etc. are separated from the description of behavior or implementation of the block/process. This implies that in general there are two different mappings from classes in the object model to SDL, one to the interface definition and one to the process/block definition. Interfaces in SDL are defined using signals or remote procedure calls as described in "Static Interface Definitions Using SDL" and the mapping to these concepts is outlined in "Mapping Object Models to SDL Interface Definitions" .

The mapping of the classes in the object model to the corresponding SDL behavior definition is an issue of object design and is depending on if the object is an active or passive object. Active objects are mapped to SDL processes (or process types) and passive objects to data types. These different mappings are discussed in "Mapping Object Models to SDL Design Models" .


Summary

When moving from analysis to design, several decisions has to be made. These decisions should be documented and it should be possible to view the impact of such decisions. A way to achieve this is the Paste As functionality that produces links that could be traversed in order to do "what if" analysis or to do consistency checks between requirements and design.

When we start to design from our analysis models, several possible SDL mappings exist for entities in the object model and the use cases. The important decisions that have to be made concern issues like reuse and determining if objects should have autonomous behavior or not (active/passive objects).


73 System Design

This chapter gives a thorough description of the different models in the system design activity and some guidelines on how to create these models. A recommendation on consistency rules that are relevant for the models in this activity as well as for the consistency between models from previous activities and this activity, is also included.

The chapter requires that you are at least reasonable familiar with SDL.


System Design Overview

One of the most important issues of software development, if not the most important of all, is to define the architecture of the system. Define how the system is built up of smaller parts that in turn may be composed of even smaller parts until each part is manageable by itself. The architecture is proposed in the system analysis architecture but the precise definition of this structure is the major task of the system design activity.

The components of a system may have several different important functions to fulfill:

  • They act as a unit for work division. Different development teams can be responsible for different components.
  • They form a decomposition of the functionality. Each component may be responsible for one aspect of the total functionality of the system.
  • They act as distribution units. The components can define how the system is distributed in the physical world.
  • They may act as technology units. The design of the different components may use different notations and tools and, although SOMT has its main focus on SDL, the system design activity also takes other possibilities into account.

The major inputs to the system design activity are the analysis object model and the analysis use case model produced in the system analysis activity. The system design is the process that based on these inputs define in detail how the system is decomposed into components and to define the interfaces between the different parts. This is illustrated in Figure 646 that also shows the three major artifacts developed in the system design; the design module structure, the architecture definition and the design use case model. In addition to these formalized descriptions there is often a need to specify non-functional aspects of the components in a textual design documentation.

Figure 646 : Inputs and outputs of the System Design activity

The architecture is in the system design formalized primarily using SDL. In SDL the major structuring concept is the block and the notation is the block diagram. Seen from an object-oriented point of view a block is a container of objects. The block can either be directly described by the objects that it contains or it is decomposed into lower level blocks. The block structuring mechanism is discussed more in "Architecture Definition" .

Where the logical architecture defines the decomposition of logical functionality the design module structure defines the decomposition into work items. It defines the different modules the design teams can start working on and also provides a mapping from the logical architecture to design modules. In SDL the design modules are usually SDL packages. The design module structure also takes a slightly broader perspective of the system to be built and describes how existing frameworks, tools and components are incorporated into the development structure.

The deployment description is a way to describe the physical distribution structure of the SDL system. It is also the place where the implementation strategy for different parts of the system can be described.

There should be a simple (if possible one-to-one) mapping between the top levels of the architecture definition and some of the modules in the design module structure. The benefit gained from a simple mapping is that the design modules define the possibilities to divide the work on different development teams and the logical blocks comprise well-defined sets of functionality and responsibilities. If they do not map to each other there is an obvious risk for complex interfaces between the development teams.

As always when a system is decomposed into smaller parts one very important issue is how the interface between the parts are defined. In particular if the components are used as division of work load and designed by different development teams the interface definition is the means to communicate between the different groups and a common understanding of the interface is crucial. There are two aspects of the interface:

  • A static aspect, defining the operations or services that a block offers
  • A dynamic aspect, that defines how the different blocks cooperate to solve a common task

Both aspects are important and the definition of them is a vital part of the system design activity.

In SOMT the major concepts used to define the static interface are the SDL concepts signals and remote procedures, and the dynamic aspect is a continued usage of use cases. However, since there very often is a need to design parts of a system using other techniques than SDL or to use existing modules, other interface definitions techniques are also used in SOMT.

The major tasks to be performed in system design in an SDL based project can thus essentially be summarized as the following:

  1. Create an (incomplete) SDL system that is a starting point for the formalization of the architecture of the application. This is further discussed in "Architecture Definition" .
  2. Define the design module structure. Draw a diagram that illustrates the structure and create the necessary packages etc. as described in "Design Module Structure" .
  3. Define the physical distribution strategy for the SDL system, see "Deployment Description" .
  4. Define the static interfaces as discussed further in "Static Interface Definitions Using SDL" .
  5. Define the dynamic aspects of the interfaces by a continued use of use cases. See section "Design Use Case Model" .

There is, as we will see in "Object Design" on page 3753, a close relation between the system design activity and the object design activity in the sense that the object design activity is concerned with the representation and behavior of the objects and the system design deals with the distribution of the objects into blocks and defining the communication paths between the objects.

The rest of this chapter will discuss the system design activity. SDL will frequently be used to define the architecture and interfaces and examples of SDL diagrams will be used throughout the chapter. A complete presentation of the SDL language is however outside the scope of this document. For more information, please consult either the Z.100 standard itself [23], or a text book about SDL like [27].


Architecture Definition

When using SDL to design a system the architecture of the system is defined by the block diagrams. They define how the system is decomposed into blocks and how these blocks either form the leaves of the block hierarchy or are further decomposed into smaller blocks. Essentially this block structure is a formalization of the logical architecture from the system analysis.

As an example, consider once again the access control system. The system controls the doors of a building to unlock the doors when an authorized user wants to enter or exit the building. The task in system design is to define how to structure this system. One natural choice is a distributed structure where the control of each door is localized close to the door and a central controller keeps all common information about authorized users, cards and codes. Furthermore one special block is responsible for the handling of an operator panel. A logical architecture that described this was illustrated in Figure 641 on page 3715 in chapter 71, System Analysis. The SDL diagram that shows a beginning of a formalization of this architecture is depicted in Figure 647.

Figure 647 : The architecture of the Access Control system defined
by an (incomplete) SDL system diagram

In this diagram we can see the blocks CentralC, Door and OperatorC that are instances of the block types CentralCtrl, DoorCtrl and OperatorCtrl. CentralC contains the common information base about cards, codes etc. that are registered in the system. Door is the block responsible for the control of each door and OperatorC handles the operator communication. The diagram also shows how the blocks communicate using the channels DoorCh and OperatorCh. Note that there are five doors in the building in this case and that this is shown by defining Door to be a block instance set. The types DoorCtrl, CentralCtrl and OperatorCtrl are assumed to be defined in the packages BasicOperation and OperatorMan that are referenced in the USE clause in the top of the diagram.


Design Module Structure

The purpose of the design module structure is to show the actual components the application will be built from. The module structure should depict the actual source code modules etc. that the application will contain. A number of different aspects must be taken into account when defining the module structure:

  • The implementation strategy for each module: Some modules may be designed in SDL with automatic C code generation. Other modules may be manually designed and implemented in a programming language and yet other modules may need a hardware implementation.
  • Existing utility modules that can be reused in the new application
  • Existing architectural frameworks that can be reused in the application
  • Of-the-shelf utility modules that can be purchased and used in the application

Especially the reuse of existing architectural frameworks is very common and very beneficial. Most applications are not built from scratch, they are rather extensions/modifications of old applications and the design module structure is the place to show how this is done.

One notation that can be used in SOMT to describe the design module structure is object model instance diagrams, where the instances represent the different modules. Where relevant, the attribute field can be used to show what components of the logical architecture are contained in the modules. As an example consider a typical SDL application running on a small microprocessor where a proprietary real-time operating system is used. A possible module structure is shown in Figure 648.

Figure 648 : The module structure of the Access Control system using
an in-house real time operating system

In this example the top-level of the application is described in the SDL system AccessAppl which is defined using the types defined in the packages BasicOperation and OperatorMan, both of which uses common types defined in the UtilityTypes package. The application will run on the already existing real time operating system MyRTOS. To make the C code generated from the SDL system run on MyRTOS a C code module Adaptation is used that defines the necessary interfaces.

In this example it is very likely that some of the modules will be developed within the project (the AccessAppl and the modules it uses) while others are already existing (like the real time operating system) and some can be taken from previous projects and be modified to fit the current project (like the Adaptation module).

The most important aspect of the module structure is that it forms the basis for dividing the work load on different development teams. This is in many cases the major reason to decompose the system into design modules. However, another reason may be the issue of reuse.

The design for reuse can in this context be viewed as an activity that defines the design module structure based on other premises than the architecture as discussed so far in this chapter. Consider for example the access control system decomposed as in Figure 647, where the system is divided into three different parts according to essentially the physical distribution that is needed in the application. There may in this example exist concepts that can be used in more than one of the subsystems. Examples may include knowledge about some passive data structure, like the concept of a card, but also entire functionalities like the concept of time seen as a clock functionality.

The identification of these type of components is also a task of the system design. It is particularly important if the different subsystems are to be designed by different design teams. It is also important to identify common components to avoid duplicate work and lower the complexity of the individual subsystems.

The concept that is used to describe the different modules is the package. A package is essentially a container of SDL types, this may range from system types and block types over process types down to signals and data types. When a package is used by an SDL system the types defined in the package can be referenced from within the SDL system. For example, in the access control system we may decide that we need a package UtilityTypes (as in Figure 648) that defines the common data types needed in the different subsystems.

Another issue that needs to be handled in the system design is to analyze the consequences of the requirements on different configurations of the system. Are there any optional parts or functionality? In many cases the optional parts are captured by different modules in the system structure, but sometimes, like if there would be an optional requirements on a synchronized clock in all parts of the access control system, it is distributed over the different blocks in the system. If this is the case a package is the most useful concept to use to encapsulate the optional feature.

The discussion so far has been about reuse within one development project focused on one specific application. There is however also the issue of reuse outside the local project. When using an object-oriented approach to the analysis and design the objects tend to be fairly general and applicable in more than one project. If the objects in a particular part of the system are defined as types in a package this will form a good foundation for reusing the objects in future projects. This implies that there may be a reason to use a package structure that is different from the block structure of the system. The package structure reflects the decomposition into packages as defined by the possibility for reuse while the block structure defines the current system structure.


Deployment Description

The purpose of the deployment description is to define the physical distribution of the application and also define the practical details on how to build the different parts.

The specific objectives for a deployment description might vary during different activities: during design we are more concerned on describing on how to verify or validate the design, i.e. how to simulate the design in different ways, while in later activities it is desired to specify the final application build process for the application structure. It is therefor possible to have several deployment descriptions for one system.

There is a textual format for defining a deployment description - for more information, see "Build Scripts" on page 2550 in chapter 56, The Cadvanced/Cbasic SDL to C Compiler, in the User's Manual.

Example of a textual deployment description, i.e. build script:

set-kernel SCTAAPPLCLENV
set-env-header on
program UserPart
component system AccessControl / block LocalStation
make-template-file UserMake.tpm
generate-micro-c
program CentralPart
component system AccessControl / block CentralUnit
make-template-file CentralMake.tpm
generate-advanced-c


Static Interface Definitions Using SDL

SDL offers two major means to define the interfaces of a block:

  • Signals (for asynchronous communication)
  • Remote procedure (for synchronous communication)

When signals are used to define the interface to a block they define the communication items that can be sent to and from the block. A signal can represent a service to be carried and it contains all relevant data that is associated with the request. A useful way to structure the signals if one particular interface contains many signals is to define signal lists that group together related signals. Consider the CentralCtrl block above. This block has two interfaces, one to the Door blocks and one to the OperatorCtrl block. The interface to the Door blocks can in SDL be defined as in Figure 649.

Figure 649 : An interface definition using signals

When using signals to define the interface of a block we do not put any constraints on the execution strategies in the respective blocks, we only define the data that is transported. However, in some cases, especially when using a client-server based architecture, it is more convenient to define the interface using remote procedures instead of signals. As an example consider once more the CentralCtrl block. The major responsibility of this block is to store the cards with their associated code. Some possible operations on this data is to check weather a particular card is registered and what the code for a particular card is. A remote procedure definition of these operations is depicted in Figure 650.

Figure 650 : An interface definition using remote procedures

In addition to the signals/remote procedures that are used to define the interfaces in SDL there is of course also a need to define the data types that are visible in the interface. This issue is to a large extent the same as the issue of mapping passive objects to SDL data types. This is treated in more detail in section "Mapping a Passive Object" on page 3763.


Mapping Object Models to SDL Interface Definitions

When mapping object model concepts to SDL there are two aspects that need to be taken care of:

  • The design of the interface
  • The design of the object itself

In SOMT this implies that an analysis object is seen to have two different descriptions in the design model, one description of the interface and one description of the object itself. In the system design the focus is on the interface definition so we will save the mapping from object models to SDL object definitions until the next chapter ("Object Design" on page 3753). However, defining the relation between the object model concepts and the interfaces between the components of the system is a very relevant issue for this section.

Since the basic mechanism in SOMT to go from analysis to design is using the Paste-As mechanism (see "Implinks and the Paste As Concept" on page 3648) this is of course also used when defining the interfaces. As seen in the previous section interface definitions in SDL are defined using signals and/or remote procedure calls. Consequently this is what is produced when mapping a class to an SDL Interface.

As an example consider the DisplayInterface objects in Figure 651 that has one operation each.

Figure 651 : The DisplayInterface objects

When mapping these objects to SDL interface definitions we get in the first case the signal interface definition in Figure 652 (with the signal Display) and in the second case the remote procedure definition in Figure 653 (with a definition of the remote procedure Display2).

In SDL the natural way is to express interfaces by asynchronous signals, therefore this mapping has been chosen to be the default. (It can also be explicitly denoted with the word async within brackets, after the operation name.) If synchronous interface is preferred, this can be denoted by the word sync. This is an extension of the original class diagram notation.

Figure 652 : The signal interface from the DisplayInterface object in Figure 651

Figure 653 : The remote procedure interface given by the DisplayInterface2 object in Figure 651

It is of course also possible to have a mixed signal/remote procedure interface. In this case some of the operations are asynchronous and thus mapped to signals while other are synchronous and thus mapped to remote procedure definitions.


Design Use Case Model

The static interface definition alone is not enough to define how the blocks are supposed to cooperate to meet the requirements on the system. In the requirements and system analysis, use cases were used to describe the requirements on the system. This is continued in the system design to define the dynamic interface between the blocks in the system. Essentially the idea is to take each one of the use cases found in the system analysis and formalize this to a sufficient degree of detail that is consistent with the level of detail that is found in the static interface definitions. The degree of detail must be precise enough to make the design use cases act as detailed test specifications.

A benefit with the design use cases is the structured way in which they are constructed. It is easy to verify that all requirements as expressed by the requirements use cases and refined in the analysis use cases are handled by the design use cases and this gives a formal link between the requirements and the structure of the system that implements it.

In a development environment where the different blocks are developed by different teams they also form a necessary common definition of the responsibilities of their respective blocks and how their blocks are to together fulfill the requirements on the system.

From a practical perspective this puts some requirements on the notation used to describe the design use cases:

  • It must be precise and formal enough to allow an specification of test cases on a detailed level of abstraction.
  • It should be possible to automatically check the design use cases against the SDL design model.
  • There must be a well-defined way to transform the design use cases to executable test programs that can be executed in the target environment against the application.

There are two levels of testing of interest for the design use case model:

  • Module testing
  • System testing

Module testing is intended to test one specific part of the system and should check that this particular part of the system fulfills its requirements. The system testing is intended to test the integration of the different parts and check that they together fulfil the requirements on the total system.

The design use case models should form the basis for both kinds of testing.

Another aspect of testing is when in the development project it is performed. One of the benefits of SDL is that it is possible to test already on the design model, essentially testing against a simulation of the SDL system. In addition there is of course also a need to test the implementation in the target environment, but if the logics of the application already has been tested during design then the focus of the target testing can be on target integration issues and the risk for logical errors in the design is reasonably small. The design level testing is further discussed in "Design Testing" on page 3792.

In SOMT two different alternative notations are used:

  • MSC
  • TTCN

Usage of MSC

MSCs can be used in a way that is precise and formal enough and can automatically be checked against SDL design models. A benefit is that it is used also in requirements analysis and system analysis and is intuitive and easy to understand also for non-experts. Notice however that there is a difference between the analysis use cases and the design use cases. The fairly abstract messages exchanged between the instances in the analysis use cases must in the design use cases be refined to the level of the static interface definitions, this may include specifying parameter values that where left out and even replacing one message with a sequence of message exchanges. It may also often be necessary to have more than one design use case for each analysis use case, for example to handle a situation where the analysis use case has left out a parameter and there is a need to test more than one combination of parameters.

Consider again the access control system with a decomposition according to Figure 647 where the system is divided into a DoorCtrl, a CentralCtrl and an OperatorCtrl block. If we take the Enter building use case as defined on requirements level by an MSC in Figure 628 on page 3689 and refined to the analysis use case in Figure 635 on page 3704 in chapter 71, System Analysis. When further refining this to a design use case we get an MSC as shown in Figure 654 where some of the messages have been refined.

Note that an MSC describes both the requirements on the separate parts of the system and the requirements on the whole system. This implies that the same MSC can be used to define both module and system tests.

Figure 654 : The Enter building use case distributed over an architecture

It is easy to see that the strategy outlined above is extendable to allow a decomposition of a system into not only one level of blocks, but into a hierarchy of blocks. For each new level of decomposition all use cases that involve the decomposed block are taken as input to the validation of the new decomposition. The block that was decomposed is replaced by the new blocks and new versions of the use cases are created.

Usage of TTCN

TTCN is another notation that is suitable for formalizing use cases on the design level. The benefit of TTCN is that it is a special purpose language for test description including:

  • Facilities for describing constraints on complex data values
  • Preambles and postambles to show how to compose test cases
  • Possibilities to handle alternative outcomes of a test case
  • A special "verdict" construct to define the outcome of a test case

TTCN is also an established notation for test description so there is good tool support for executing TTCN test cases on target platforms.

The drawback is that it has not a particularly intuitive syntax, making it more difficult for non-experts to maintain, create and review TTCN test suites.

If TTCN is used to define both system and module testing each analysis use case will result in several TTCN test cases, one for each part of the system and then one for the entire system. As an example consider Example 602, that shows a test case testing the requirements from the Enter_Building use case on a DoorCtrl, and Example 603, that shows a test case testing the requirements from the Enter_Building use case on the entire AccessControl system.

Example 602 : A TTCN test case testing a DoorCtrl

 1  UsrPCO?Card                                     Card1
 2    UsrPCO?Display                                Enter_Code
 3      UsrPCO!Digit                                Digit1
 4        UsrPCO!Digit                              Digit1
 5          UsrPCO!Digit                            Digit1
 6            UsrPCO!Digit                          Digit1
 7              CentralPCO!Validate                 Validate_1
 8                CentralPCO?Accept                 AcceptOK
 9                  DoorPCO!Unlock                  Unlock!
 10                   UserPCO!Display               Please_Enter
 11                     DoorPCO?Open                Open1
 12                       DoorPCO?Close             Close1
 13                         DoorPCO!Lock            Lock1
 14                           UserPCO!Display       Enter_Card P

Example 603 : A TTCN test case testing the AccessControl system

 1  UsrPCO?Card                                     Card1
 2    UsrPCO?Display                                Enter_Code
 3      UsrPCO!Digit                                Digit1
 4        UsrPCO!Digit                              Digit1
 5          UsrPCO!Digit                            Digit1
 6            UsrPCO!Digit                          Digit1
 7              DoorPCO!Unlock                      Unlock!
 8                UserPCO!Display                   Please_Enter
 9                  DoorPCO?Open                    Open1
 10                   DoorPCO?Close                 Close1
 11                     DoorPCO!Lock                Lock1
 12                       UserPCO!Display           Enter_Card P

The choice between MSC and TTCN as design use case notation is very much influenced by application and development organization aspects:

  • It is more efficient if the same test definitions can be used both for design level testing and target testing, so the plans for how to perform the target level testing may have an implication for the choice of notation. If the target testing should be done using a TTCN environment then at least the system tests should be defined in TTCN also for the design level testing.
  • On the other hand, if the target tests are performed using an in-house test script notation implying that the same notation can not be used both in design and target testing, then MSC has the advantage of being a simpler notation and is already known and used in the previous activities.


Textual Design Documentation

The SDL architecture definition and the design use cases form a specification of the static and dynamic aspect of the components from a functional viewpoint. In many cases there is a need to extend this with more information that is not suitable to express in SDL or as use cases. An example may be a system that requires a user interface with windows, menus etc. or a system with specific requirements on reliability or response times for some or all of the components.

To give the possibility to express this type of specifications and also to allow other types of design or project documentation in an environment that is mainly SOMT and SDL oriented, the SOMT method gives a possibility to include textual documents in the system design documentation.


Consistency Checks

This section gives a number of examples of consistency checks that can be made on the models produced in the system design.

  • Check that there is a simple (preferably one-to-one) mapping between all the top-level subsystems in the architecture definition and some of the design modules as defined in the design module structure.
  • Check that the actual modules (SDL packages etc.) used in the design are consistent with the design module structure.
  • Check that the subsystems in the logical architecture in the analysis object model are mapped to the architecture definition in the design.
  • Check that all use cases from the requirements analysis and system analysis are refined to design use cases.
  • Check that the instances in the design use cases correspond to the blocks/processes in the architecture definition.
  • Check that all objects in the analysis object model either has been mapped to some interface definition or really are internal to their module.
  • Check that the different models conform to the rules for their respective notation (like SDL and MSC).


Summary

The system design is an activity in which the architecture of the system to be built is defined in SDL. Use cases from the analysis are refined to a granularity that will be sufficient for describing the behavior of the subsystems in the architecture. These use cases should be a source for module and system testing in later activities.


74 Object Design

This chapter gives you the rules for how to transform object models to SDL design models. Mappings for active and passive objects and associations are described and exemplified. How to define the behavior of an object is also discussed as well as a section on how to test the design.

The chapter requires that you are at least reasonably familiar with SDL.


Object Design Overview

The object design is the activity that completes the definition of the system. It carries on where the system design finished and fills in the details about object behavior and system structure. The object design is a creative activity that refines the object definitions and system structure taking at least three aspects into account:

  • The system structure: where in the system is an object localized
  • The reuse structure: is the object a subject for reuse internally within the system or externally
  • The precise definition of internal object structure, the behavior and data aspects

Figure 655 : Overview of the object design activity

There is a close relation between the system design and the object design, in the sense that both activities are dealing with the structure of the system. The difference between the activities is mainly a difference in the point of view. The system design takes a top-down look at the system to identify subsystems and overall structures. The object design on the other hand focuses on the objects and uses them as a starting point for the refinement and structuring.

In practice one of the major tasks of the object design is to define the behavior of the objects. Essentially the object design can be viewed as three sequential tasks that must be performed.

  1. Map all the classes in the relevant part of the analysis object model to suitable SDL concepts.
    • Active classes are mapped to processes or process types and passive classes are mapped to data types. This mapping is described in "Mapping Object Models to SDL Design Models" .
    • The localization of the process (type) or data type in terms of the SDL package/system structure should be done according to the design module structure and architecture definition from the system design.
  2. Choose a set of essential use cases and define the behavior of the SDL processes and data types that implements these use cases. Concentrate on the normal behaviors and leave the exceptions for a later step. The design of SDL processes is further discussed in "Describing Object Behavior" .
    • Note that this also includes a testing activity that verifies that the SDL design implements the requirements from the use cases. This is further described in "Design Testing" .
  3. Elaborate the design by introducing more use cases and refine the SDL design to handle also these cases. Take care of exceptional situations like error handling etc.
    • This elaboration is an iterative process where the design is incrementally developed until all requirements are implemented.
    • Each iteration also includes a testing step where both newly implemented and old functionality is checked.
    • The elaboration can include both refining existing processes/ data types and introducing new process/types.

In a project where the design is split on several development teams the iterations in the design will often have to be synchronized. This is further discussed in 76 SOMT Projects.


Mapping Object Models to SDL Design Models

In SOMT object design, an important step is the transformation of (parts of) the analysis object model to an SDL system. This section describes this transformation.

There are several aspects important in the transformation:

  • How to map objects to SDL, taking into consideration e.g. whether the object is active or passive
  • How to represent associations in SDL
  • How to preserve the inheritance/aggregation relations in SDL

The mapping to ASN.1 will also be discussed briefly.

Mapping an Active Object

Consider an object in the analysis model that has been found to be an active object. How should this be mapped into the design model? The default choice is to map this object as an SDL process type. The attributes of the object will then be mapped to variables and the operations will correspond either to remote procedures defined in the type or signals handled by the process type. As an example consider the DisplayInterface object in the Access control system. This object is responsible for interfacing a display that is capable of showing a line of text to a user. In the analysis object model this object may look like Figure 656. It has one attribute, Text, and one operation, Display.

Figure 656 : The DisplayInterface object

When mapped to an SDL diagram as a process type the result will be a process type reference, as shown in Figure 657.

Figure 657 : The DisplayInterface process type

Now consider the case where the Display operation was defined to be an asynchronous operation which is the default. If we now take a look at the DisplayInterface process type definition we can see that it has a variable called Text and a gate with the signal Display. This process type definition is shown in Figure 658.

Figure 658 : The DisplayInterface process type definition

If, on the other hand, the Display operation was defined to be synchronous (by giving the keyword sync after the operation name), then the definition of the DisplayInterface process type would now also be different. It would contain a definition of the Display remote procedure instead of a gate with a signal. See Figure 659.

Figure 659 : The DisplayInterface process type when mapped
to a process type with RPCs

When mapping an object like the DisplayInterface, the design issue of reuse shows up as a question of where to define the SDL object. If the DisplayInterface class is considered to be a general class that is to be reused in different projects or by different development teams, the most natural choice is to put the process type in a package that includes this type definition and other related types that are to be reused in different contexts. The design choice of what packages to use in a project was one of the issues of system design.

If the DisplayInterface only is intended to be used in this project but it is used in several of the blocks representing subsystems then there is also a possibility to put the process type on the system level. This would allow the type to be used in the entire system but it would not be convenient to use it in other projects.

If the DisplayInterface is only to be used within the local block it can be defined anywhere in the scope in question, even if it probably is a good idea to keep all process type references on one page in the block diagram.

Finally, if the DisplayInterface object is only to be used in one particular place in the system, it is possible to define it as a process directly where it will be used instead of as a process type. This would be done the same way that it was mapped to a process type except that a process would be generated instead of a process type. Sometimes this strategy is a good idea since it slightly reduces the complexity of the system, however it is only possible if the object is only used in one place in the system.

Mapping Active Objects with Inheritance

Inheritance among active objects is common in object models and is mapped directly to inheritance between the corresponding process types. For example, when mapping the EnglishDisplay object from Figure 660 to a process type, the result is as shown in Figure 661.

Figure 660 : Object model with inheritance

Figure 661 : Process type with inheritance

Mapping Aggregations of Active Objects

A fairly common structure is an aggregation with one assembly class that contains a number of other object classes, the part classes1. This is common for example when using container classes as abstract interfaces to a certain functionality. One example is given in a description of the software in one part of the access control system: the part that controls the access to one particular door in the building.

Figure 662 : An example of an aggregation of active objects

The most common mapping for this type of structure is to map the assembly class to a block or a block type, depending on the strategy for reuse that has been decided upon for the object.

One special, but fairly common, case is when the assembly object class contains attributes. In this case there are two possibilities: either the aggregation is considered as a "subsystem", in which case the attributes should be implemented by one of the parts classes, or the object should in addition to the mapping to a block (type) also be mapped to a process within the block that acts as a data server. This mapping follows the same principles as was discussed in section "Mapping an Active Object" .

Another possibility is that the assembly object class contains operations. This implies that these operations should be included in the interface of the block/block type. In the same way as when pasting as process types there is a design choice involved here. Are the operations intended to be synchronous remote procedures or are they asynchronous signals? In this case it is also important to define where the operations are to be implemented. Also in this case there are two choices: either the operations are implemented in one of the parts classes or a process is introduced in the block that handles the operations the same way a data server process handles the attributes.

As an example consider the analysis model in Figure 662. The block type DoorModule has both an attribute and an operation. A design counterpart for this is shown in Figure 663 and Figure 664. The process DoorModuleCtrl is the server process that handles the data and operations defined in the DoorModule analysis object.

The choice where to implement the operations and the attributes of the aggregate class is depending on the intended meaning with the aggregation. In SOMT the recommended practise is to use aggregation in object model that describes the architecture of a system as a "subsystem" or "parts vs. whole" relation, meaning the aggregate class is completely determined by its parts classes. In this case the operators and attributes of the aggregate class should be implemented by the parts classes.

Note that this is an example where the attributes and operations of the aggregate class DoorModule have been implemented by one of the part classes, the DoorModuleCtrl class.

Figure 663 : A block type reference for the DoorModule object

Figure 664 : A block type with a data/operations server process

If the object that is mapped to a block type is a subtype of another object in the object model, then the resulting block type will be defined as a subtype that inherits a block type that corresponds to the supertype in the object model.

Mapping State Charts to SDL Process Graphs

The principle of reusing as much information as possible of the information gained during the analysis activities when working in the design activities implies that an effort should be made to translate state chart descriptions into SDL process graphs. For a thorough description of the mapping rules please refer to: "Converting State Charts to SDL.

State charts may be converted into SDL. Converting state charts without any hierarchical states is very straight forward, but converting a state chart containing hierarchical states requires flattening since the concept of hierarchical states does not exist in SDL.

The state chart LocalStation Figure 665 contain a hierarchical state with sub states and need to be flattened when converted to SDL.

Figure 665 : The State Chart Local Station

The behavior of the SDL process LocalStation Figure 666 is the behavior defined in the state chart LocalStation. The process is flattened and gives a straight forward view of the behavior. To increase traceability between the state chart and the SDL process the converter functionality provides comments on states and transitions which are related to any hierarchical state.

Figure 666 : The SDL process LocalStation

Mapping a Passive Object

A passive object is an object that does not have any thread of control or spontaneous behavior of its own. A passive object is often used to encapsulate a certain amount of information that is needed in the system. In the context of distributed systems it is often useful to classify the passive data descriptions into two broad classes depending on the way the data is used: external data and internal data

  • The external data is focused on describing the data units that will be transported across the system when that application executes. In an application where the different components execute in different memory spaces, and maybe even on different hardware, there is a need to consider transportation format and maybe even coding/decoding of the data. Often the description of external data is focused on the information contents of the data units and not very much on the operations that can be performed on the data units. Typical example applications where external data is very common includes protocols in telecom applications. A common property of this kind of data is that they are usually structured in trees, in an object model often in aggregation hierarchies, and not in graph structures.
  • The internal data is characterized by the fact that it is used to describe information that the application needs to do its work. Typically the data is localized to one concurrent execution unit. The internal data units are thus used to store rather than to transport data. Some typical examples are data bases and complex data structures in conventional program units. A local data unit is typically not copied from one component to the other. Instead operators are used to access the data unit.

As will be seen in the next sections the mapping of passive objects to SDL data types is slightly biased towards the external data view of passive objects, the mapping to ASN.1 data types is very biased to external data view, and the mapping to C data types is slightly biased towards the internal data view of passive objects.

Mapping Objects to SDL Structs

In general, the SDL construct that can be used as the design representation for a class is an SDL STRUCT. This is exemplified in Figure 667 below.

Figure 667 : Mapping a passive object to a STRUCT type

In this mapping all attributes of the class are mapped to fields of the STRUCT.

Attribute Data Types

The attributes of a class may have data types associated with them. In general there are three ways to handle these data types:

  • Defining the data type in the analysis model.
  • Giving an abstract definition in the analysis model and making a final decision in the design model.
  • Consider it to be a design issue and give no definition of the data type in the analysis model.

As usual the choice is a matter of personal taste but should be directed by the general idea that the analysis model must be complete enough to be understandable by itself, but as small as possible to facilitate overview and ease of use.

The default mapping in SOMT is a simple literal mapping of whatever exists in the analysis model to the design model in SDL. See Figure 668.

Figure 668 : A data type mapping example

A special case which might be of interest in the analysis is when more complex data types like lists or sets are used. SOMT treats this type of data in the same way as elementary types are treated.

Mapping Operations

When a class is mapped to a data type in SDL there exists several ways to map the operations of the class. Operations could be mapped to:

  • Operators described by (textual) operator definitions
  • Operators described by operator diagrams
  • Operators described using C code
  • Procedures described in SDL
  • External procedures

The default mapping used by SOMT is to map operations to SDL operators with operator diagrams.

Operators Described by Operator Definitions

Operators described by operator definitions is the simplest choice. Consider the PersonInfo class as defined in Figure 669.

Figure 669 : A class with operations

This object has two operations: IncreaseAge and Retired which are intended to increase the age of the person with one, and to check if the person has reached the age where he/she has retired from his job.

Figure 670 shows how a mapping of operations to operator definitions can be done.

Figure 670 : Data type with operator diagrams implementing the class operations

Operators Described by Operator Diagrams

Operators described by operator diagrams is another alternative.

If a mapping to SDL is done using operators with operator diagrams, the SDL will look like in Figure 671.

Figure 671 : Data type with operator diagrams implementing the class operations

SDL Operators in General

Some things worth noting about SDL operators are:

  • An SDL operator can only be used within an expression, e.g. "var:= oper( 1 ) + 1".
  • All operators must return a result.
  • Operators can not have IN/OUT parameters. All parameters are IN parameters.

A consequence of this is that an operator cannot both modify an object and return a result. The operators can thus be divided into two classes:

  • Modifiers, that modify the object
  • Extractors, that extract information from the object but does not modify it

The modifiers are defined as:

ModOp: ObjType, P1type, P2type -> ObjType;

and used as

MyObj := ModOp( MyObj, p1, p2 )

An extractor would be defined as:

ExtrOp: ObjType, P1type, P2type -> ResultType;

and used as

Result := ExtrOp( MyObj, p1, p2 )

However, SOMT allows a way to overcome the third aspect above. If a C implementation is used as discussed below, the restriction that operators cannot modify the parameters is somewhat relaxed, since the data type itself can be defined using a pointer and then whatever is pointed at can of course be modified by the operator.

Operators Described Using C Code

The second mapping possibility for object model operations is to map them to SDL operators with C implementation. See Figure 672.

Figure 672 : Data type with C implemented operators

Procedures Described in SDL

The third way to implement operations of a class is to use SDL procedures. In this case the definition of the PersonInfo class would be like in Figure 673.

Figure 673 : Data type with procedure implementation of operations

Some differences when procedures are used compared to when operators are used:

  • Procedures can use both IN parameters, IN/OUT parameters and a return value.
  • There is no syntactic relationship between the procedure and the data type definition.
  • Procedures can be used in two different ways:
    • using special procedure call symbols (like in Figure 674).

Figure 674 : Procedure call symbol

    • in expressions with a syntax as the following example:
ret:= CALL retired(p1)

External Procedures

The fourth way is to implement the operations as normal C functions. These functions correspond in SDL to external procedures. For example, to implement the IncreaseAge operation, one could have the following C function (the PersonInfo data type would have to be specified as a C type):

void IncreaseAge (PersonInfo *p)
{
(p->age)++;
}

External procedures can be declared in text symbols, and they are called as if they were normal SDL procedures, as shown in Figure 675. "Mapping Passive Objects to C" gives more details about mapping operations to C.

Figure 675 : External procedures in SDL

Mapping Aggregations

A common situation is that the information used by a system has to be structured into some kind of tree structure. In the analysis this will appear as an aggregation hierarchy of passive objects. An example is shown in Figure 676.

Figure 676 : An aggregation of passive objects

If the PersonInfo object is mapped to a struct the aggregation would be visible in the design model as fields in the struct the same way attributes would be mapped. The mapping of the PersonInfo object from Figure 676 into an SDL diagram is shown in Figure 677.

Figure 677 : The SDL mapping of a passive object with aggregation

A common special case is when there is a multiplicity associated with the aggregation as in where one person can have more than one card.

Figure 678 : An aggregation with associated multiplicity

In general the multiplicity implies that there is a list or set of elements associated with the aggregation. There are several mappings to SDL possible, for example based on:

  • Standard SDL generators like:
    • Array
    • String
    • Other data types as described in 2 Data Types
  • A user-defined C implementation of lists

The default mapping in SOMT is a mapping to a type called "xxxList", where "xxx" is the name of the class. In Figure 679 the mapping of the PersonInfo type is illustrated.

Figure 679 : An SDL mapping an aggregation with multiplicity other than one

The "xxxList" type will then have to be designed separately. One simple way is to use an SDL string as in Figure 680 for the CardInfoList type.

Figure 680 : An SDL implementation of a list using the string generator

Another special case is given by recursive data structures that are used to describe tree structures. In Figure 681 a simple recursive tree is illustrated. In general this type of tree can of course also include a multiplicity other than one.

Figure 681 : A recursive object model

Due to the lack of pointers in SDL, this type of structure can normally not be defined in standard SDL-92. However, SDL tools may offer tool-specific pointer generators that can be used to represent the above tree. Figure 681 shows how the recursive data structure can be represented with help of the Ref pointer generator of the SDL suite.

Inheritance

Inheritance in an object model is used to model "is-a" relationships. In practise the inheritance shows how attributes, operations and associations are inherited from a superclass to the subclasses. An example is shown in Figure 682 which models the fact that both the users and operators are persons.

Figure 682 : Inheritance relations

When mapping classes that inherit other classes to SDL data types there are three mechanisms that can be used:

  • Flattening
  • Delegation
  • The SDL inheritance concept

Flattening means essentially that all operators, attributes and associations are copied from the superclass to the subclasses. In the example above this strategy would imply that the SDL representation of the User class might look like in Figure 683.

Figure 683 : Representing inheritance using flattening

Using delegation to represent inheritance is essentially to replace the inheritance hierarchy with aggregation hierarchies. When using this strategy the SDL representation of the classes in Figure 682 will be as illustrated in Figure 684.

Figure 684 : Using delegation to represent inheritance

When using the data types defined as in Figure 684, note that the syntax for accessing the attributes will of course show the delegation strategy used. For example, in order to access the name attribute of a User a construction like "uservar!person!name"" will have to be used.

SDL includes an inheritance concept for inheritance between data types. Unfortunately the inheritance between data types is an inheritance of operators only which limits the usefulness of the SDL inheritance. For more information about inheritance between SDL data types see "Inherits" .

Multiple inheritance implies that attributes, operations and association are inherited from more than one superclass as illustrated in Figure 685, that models the fact that a user is both a person and a card holder.

Figure 685 : Multiple inheritance example

When mapping classes with multiple inheritance to SDL both the flattening and delegation strategy works fine (except for name clashes when using the flattening strategy) but the SDL inheritance does not include multiple inheritance so it can not be used. In Figure 686 the delegation strategy is used to map the User class from the previous example to SDL.

Figure 686 : Mapping multiple inheritance using delegation

Delegation is the default mapping of inheritance used in SOMT.

Mapping Passive Objects to Signals

A special kind of passive objects in the analysis object model are the objects that are used only for communication, either between the system and its environment or between modules within the system. For example, when defining the use cases it is useful to show the relations among the events using an object model. It is especially useful if there are inheritance relations among the events as shown in Figure 687. The corresponding SDL signal definitions are shown in Figure 688.

Figure 687 : Object model describing communication events

There is often a choice of whether to map a passive object used for communication to a struct data type or to a signal. This is one of the design decisions that has to be taken during the object design.

Figure 688 : SDL signal definitions corresponding to the object model in Figure 687

Mapping Passive Objects to C

Passive objects can also be mapped to C data types and functions. In C, classes correspond to types, attributes of a class to fields in struct types, and operations to functions.

Figure 689 Mapping a passive object to C

Figure 689 shows a possible mapping of class PersonInfo to C. Note that in the mapping of the operations, a parameter is present to identify the PersonInfo object.

To represent aggregations in C, the same mechanisms as described in "Mapping Aggregations" can be used. When mapping inheritance to C, the flattening and delegation mechanisms described in "Inheritance" can be used.

When mapping associations to C, pointers are very powerful. Figure 690 shows an example of a one-to many association that is mapped to a linked list in C. Note how the role name has been used in the mapping.

Figure 690 Mapping an association to C

The SDL suite has facilities to instantiate classes that have been mapped to C, and access their attributes and operations from SDL. This is described more detailed in 2 Data Types.

Note:

Try to avoid pointers to data in other SDL processes! Data inconsistency will occur if the same data can be read/written by more than one SDL process at the same time. This can be achieved by avoiding pointers in parameters of signals and remote procedures.

Figure 691 shows an SDL fragment that uses the C types for PersonInfo of Figure 689. The CString2CStar operator converts an SDL Charstring to C's char *. Operations are called by means of SDL procedure calls. Note also the address operator `&' in the call to IncreaseAge.

Figure 691 Using C type PersonInfo in SDL

The choice between the SDL struct representation of classes and the C code representation is to some extent a matter of taste. There is a trade-off between simplicity and expressiveness. The SDL struct definition is very simple and all SDL based tools can completely analyze and manipulate this type of data. When using a C implementation, you take over some of the responsibilities from the tools. This means more work for you, but also a possibility to define in detail what you want.

Mapping Passive Objects to ASN.1 Data Types

An analysis object can also be mapped to an ASN.1 data type. The ASN.1 SEQUENCE construct corresponds best to a passive object with attributes. The most basic example is illustrated in Figure 692 below.

Figure 692 : Passive object mapped to ASN.1

The ASN.1 SEQUENCE can be compared with the SDL STRUCT, so most of chapter "Mapping a Passive Object" on mapping classes to STRUCTs is also valid for ASN.1. The few differences are treated here.

The largest difference is that ASN.1 has no possibility to specify operators. Therefore the operations of a passive object should be inserted in some dummy SDL type, while the attributes are mapped to a different ASN.1 type, as illustrated below.

Figure 693 : Passive object with operators mapped to ASN.1

The second difference is that ASN.1 has no concepts for inheritance. Therefore only flattening and delegation can be used to represent inheritance. ASN.1 has a special construct, COMPONENTS OF, that is useful to represent flattening. An example of this is given in Figure 694 below.

Figure 694 : The use of COMPONENTS OF to represent inheritance

The SDL suite only allows use of ASN.1 in separate ASN.1 modules, that have to be included into SDL with the IMPORTS construct.

Mapping Associations

Associations are in object models used to represent relationships between objects of different classes. The instances of associations are called links. An example is given in Figure 695. In this example the association is a relationship between Cards and Codes that describes that a card must have exactly one valid code. In the object model this is represented by an association called Valid between the classes Card and Code.

Figure 695 : An example of an object model with associations

In the mapping to SDL, the information about the association is kept in one or both of the involved classes, in the example in Card, in Code, or in both.

There are several aspects of associations that are important to consider when mapping an association to SDL:

  • Whether involved objects are active or passive
  • The structure of the associations: graph vs. tree
  • Intrusive vs. non-intrusive representation
  • The traversal direction, one-way vs. two-way
  • The multiplicity of the association
  • Role names vs. association names
  • Association attributes/association class

The rest of this section will discuss these issues and how they influence the mapping to SDL.

In general, associations form a graph structure among the objects where each object may have associations to a number of the other objects. Mapping associations to SDL implies in most cases that some kind of object references or pointers must be used.

In general, associations between active objects indicates that there is a possibility for the objects to communicate. In SDL this means that there must exist a communication path (signal routes and channels) between the corresponding SDL concepts (usually processes). In addition, an association between two active objects may also need to be represented by a PId variable in one (or both) of the processes.

There are however cases when PIds should not be used: as PId is a concept that only exists in the SDL world, associations with objects outside the SDL system cannot be represented with PIds. Instead, data types defined in protocols define how to refer to external objects. For example in the TCP/IP protocol, TCP services are addressed by a host address (for example 3.1.29.1) and a local port number. In an SDL implementation of a TCP service it would be impossible to refer to a service outside the SDL system by means of a PId; the host number and the port number must be used instead.

Since strict SDL does not include a pointer concept, associations with passive objects must be represented by other data types. Alternatively a C representation can be used when mapping the objects to SDL as discussed in "Mapping Objects to SDL Structs" .

There is one special case where there is no need for special data types. This is the case when the associations form a pure tree structure and furthermore all associations are one-way one-to-one associations with a traversal direction from the root to the leaves. In this case a strategy based on mapping classes to SDL structs can be used, i.e. a reference to an object is in SDL represented by the object itself.

Sometimes an association is implicitly represented in the class definitions themselves, which is called an intrusive representation. In this case the association does not have a representation of its own in the SDL model. For example, if the classes are represented by SDL structs then the association can be represented by a field in one (or both) of the structs. As an example the Valid association from Figure 695 is mapped in Figure 696 to a field in the struct that represents the Card.

Figure 696 : Mapping an association to a field in a struct

A non-intrusive representation of the association, on the other hand, does not rely on fields in structs that represent classes or any similar strategy. Instead the association is explicitly represented in SDL. A convenient way to accomplish this is to use the SDL array generator as exemplified in Figure 697.

Figure 697 : A non-intrusive mapping of an association using an SDL array

The design choice to make when choosing a mapping to SDL depends on the way it will be traversed in the application: is the traversal of the association always in one direction or is it traversed in both directions. This is usually not relevant in the analysis model but influences the SDL representation. For example if the Valid association in Figure 695 is a one-way association only traversed from the Card to the Code then the SDL representation in Figure 696 is all that is needed. If, on the other hand, the association is also traversed from the Code to the Card then the Code representation will also have to contain an element corresponding to the association (note that this requires a C implementation due to the lack of pointers in SDL) or alternatively a non-intrusive representation can be used.

The multiplicity of the association defines how many instances of one class can be associated with an instance of the other class. A one-to many association requires a list or set representation. This is essentially the same as an aggregation with a multiplicity greater than one, which is described in "Mapping Aggregations" .

Role names are an alternative that can be used instead of or in combination with association names. A role is one end of an association, and the role name uniquely identifies the object from the perspective of the object at the other end. An example is given in Figure 698 where the association is identified using role names instead of an association name.

Figure 698 : An association that uses role names instead of an association name

In many cases the role names are more convenient and less confusing than an association name. In a mapping to SDL it is preferred to use the role name as e.g. the name of a field in a struct rather than the association name. As an example consider Figure 699 where the Person object from Figure 698 is mapped to a struct in SDL and the role name is used as the field name.

Figure 699 : SDL mapping of a an association using the role
name instead of the association name

An association may have an associated class as illustrated in Figure 700.

Figure 700 : An example of an association class

The implication of this is that there are some attribute values and/or operations associated with each link of this association class that exists between the two objects. When mapping this construct to SDL there are two strategies: an intrusive representation and an explicit representation of the association class. If an intrusive strategy is used there is no explicit representation of the association so the attributes/operations must instead be associated to one of the objects involved in the relation. This strategy is possible only if at least one of the end points involved has the multiplicity "1". In the example in Figure 700 it would be possible to incorporate the association class into the Person object since there is only one company for each person in this model. A structured way to represent this in SDL is illustrated in Figure 701.

Figure 701 : The association class from Figure 700 mapped into
the Person object with an intrusive strategy

The second alternative is essentially to view the association class as a regular class and map it to SDL using any of the strategies that can be used to map regular classes to SDL. This is necessary for many-to-many associations.

The default mapping of associations between passive objects in SOMT is to use the intrusive strategy where classes are mapped to SDL structs and thus associations are mapped to fields in these structs. The name of the field in the struct is the corresponding role name if a role name exists, otherwise it is the association name. If there is no name specified for one of the roles and furthermore no name for the association, then no field is generated in the corresponding struct, and the association is considered to be a one-way association.

Summary of Mappings from Object Models to SDL

There are a number of possible SDL target concepts that an analysis object can be mapped to. The choice of target depends mainly on properties of the object:

  • Active objects are mapped to processes or process types
  • Aggregations of active objects are mapped to blocks or block types
  • Passive objects are mapped to struct data types (or to signals if they are used for communication only)
  • Associations between passive objects are mapped to fields in struct data types, or to new data types that explicitly represent the association
  • Associations between active objects are mapped to communication paths (and possibly to variables within processes)
1

Terminology (assembly and parts classes) after [20] the "Object Model Notation Basic Concepts"


Describing Object Behavior

Once the type of SDL target concept has been chosen, the behavior of the object can be defined. Processes and process types are defined by creating the process graphs and ADTs are preferably defined by giving operator diagrams for the operators.

In practise, the major task of the object design activity is the definition of the behavior of SDL processes since they are the SDL representation of active objects that tend to have a more complex behavior than the passive objects. SDL process graphs provide a graphical notation for extended finite state machines, i.e. finite state machines with variables. In Figure 702 an example of a small process graph that illustrates some of the constructs possible in an SDL process is shown. More details about SDL and SDL process graphs are provided in section "SDL" .

Figure 702 : An SDL process graph

The possible inputs to the process design task are illustrated in Figure 703. The possible inputs directly from the system analysis/design are:

  • MSC use cases from the design use case model or analysis use case model
  • Possibly a state machine, described by a state chart, giving an overview of the behavior if this was defined in the system analysis

The inputs resulting from the mapping of object models to SDL are:

  • The signal and/or remote procedure call interface of the process
  • Some process variables defined by the attributes of the object model class

Based on these inputs the goal of the process design is to create a process diagram that defines the behavior of the process.

Figure 703 : Inputs and output of the process design task

A useful way to structure the tasks that are needed to create a complete process are:

  1. Create a first version of the process that defines the control structure in terms of states and transitions. There are two subtasks that in practise are performed more or less in parallel:
    • Defining the control structure
    • Defining data aspects.
  2. Elaborate the process by e.g. considering secondary use cases and exceptional cases.

The First Version - Defining the Control Structure

The control structure of an SDL process is defined by the states and the transitions of the process. Ideally the states of a process represent what the environment might expect of the process. Different states represent different stable phases in the life-time of a process and depending on what state a process is in it will respond differently to requests and inputs from the environment.

One straight-forward way to find the states of a process is to analyze the use cases. Since the use cases show an external view of the processes they reflect the expectations the environment can have on the behavior of the process. Both directly in terms of sequences of inputs and outputs the process has to conform to but also indirectly in terms of states since each input of a process must be preceded by a state.

So, the task of designing the control structure of the process starts with selecting a set of typical and essential use cases. If the use cases are in MSC format and on an appropriate abstraction level that includes the process to be defined, the use cases can be analyzed directly. If not they should be rewritten to clearly show the responsibilities of the process in question.

Analyze each use case in terms of states and transitions for the process. Incrementally build up the process graph by adding states and transitions. Start in the beginning of the use case and figure out what state the process must be in. Manually walk through the use case, checking the process defined so far and incrementally adding states and transitions to the process graph. Check for each transition in the use case (i.e. input followed by one or more outputs by the process in question) that the transition exists in the process graph. If it does not exist, add it. Take a look in the use case to see if there is an external need for a state change in the process: has the expectations on the process changed after this transition in the use case? If no: go back to the same state again. If yes: is there an already defined state that may fit these expectations? If there is one, use it. If there is no such state, create a new one and give it a name that describes the expectations. Continue until all use cases has been analyzed.

When adding transitions do not forget to check with the mapping from the object model if it is a regular transition with input and outputs or a remote procedure that is to be added. Also check if state lists (and "*" states) can be used as the starting state of the transition.

During the design of the process also consider what part of the control to put in the process graph states and what to put in variable values. In general it is recommended to define the control flow using the process graph states, but there are cases when it is better to put parts of the control in data values instead of as explicit process states. One example is loop variables that count the number of occurrences of something and is used to exit the loop after a certain number.

One problem that might occur during the use case analysis is that two of the use cases seem to be very difficult to combine in the same process since they require different states of the process. This is an indication that some restructuring is needed and that maybe the process should be divided into different processes or into a set of services.

When finished with the analysis of the selected use cases the result should be a skeleton process graph that contains states and transitions with mainly inputs, outputs, remote procedures, timer actions and a few tasks and decisions that deal with control variables. Make sure that the state/transition structure makes sense. The states should represent external expectations on the behavior and their names should reflect it. This is an important issue, in particular for the possibilities to maintain the process.

The next step is now to consider the data aspects of the transitions.

The First Version - Data Aspects

Often there will be three kinds of variables in an SDL process: temporary variables used to handle the parameters of signals, control variables like loop counters as discussed above, and "real" variables that store information about some entity that will be accessed later during the execution. Most of the "real" variables should have been identified during the analysis are given by the mapping from the object model to SDL. The task now is to define how the "real" variables are affected by the transitions. Add temporary variables handling the parameters of the signals when needed and tasks with expressions that define the needed computations. If complex computations are needed it is good practise to hide them in procedures or operators. The transitions should preferably stay fairly simple.

The first version of the process is considered to be finished when it is possible to verify that the process fulfills the selected use cases, e.g. by running a simulator or verifying MSC use cases (compare with "Design Testing" ). Both the control and the data aspects should be dealt with.

Now it is time to start with the elaboration of the process.

Elaboration of the Process

The purpose of the first version of the process was to define the control structure of the process and make sure that this is able to cope with the requirements from the most typical and important use cases. The purpose of the elaboration is to complete and refine this structure to make the process definition reliable and facilitate the maintenance. There are several aspects to cover in this elaboration:

  • Secondary use case and exceptional cases in primary use cases
  • Simplification e.g. using state lists and procedures
  • Robustness and completeness of the process
  • Restructuring for inheritance and reuse

The major topic for the elaboration task is to consider the secondary use case that was not treated in the first version and also the exceptional cases of the already treated use cases. This is done essentially the same way as when creating the first version as described in "The First Version - Defining the Control Structure" . The use cases are walked through by hand and the process graph is checked and possibly extended to cope with the new cases.

To enable the understanding of the process and thus also to make it possible to maintain it, it is important that the definition is as simple as possible. This is a topic that is dealt with in the elaboration task. Procedures can be used to simplify process definitions considerably by defining a particular piece of code in one place and using it in several. Procedures can also be used on a higher level to indicate different phases in the lifetime of the process. Using state lists and "*" states it is also possible to simplify the definition of a process by defining transitions that are common to many states in one place.

The robustness and completeness of the process must also be handled in the elaboration. The strategy is essentially to make sure that the appropriate action is taken by the process, not only for the expected cases but also for unexpected cases. So, for each state in the process and each input signal/ remote procedure call possible; check that the action taken makes sense. Also check the treatment of unexpected parameter values.

Another topic to be treated in the elaboration is to consider how to facilitate reuse of the created process. Is it possible to create a more general process type by factoring out some parts of the definition and defining a more general process type that can be specialized in other situations?

The elaboration is in practise an iterative process where all the aspects above are treated more or less in parallel. When the elaboration is finished, the process definition is completed and is ready for integration test. The module test should preferably already have been done at this stage.

Operator Diagrams

When defining the behavior of passive data types defined in SDL the preferred way to define the operator is using operator diagrams. An operator diagram is essentially a flow graph with a start symbol, symbols defining the actions performed by the operation and one or more return symbols. The symbols may for example be tasks with assignments or decisions. An example is given in Figure 704 that shows the operator diagram for an operator BirthDay that increases the age of a person by 1.

Figure 704 : An operator diagram


Design Testing

One of the major benefits with a design notation like SDL that has a well-defined and complete semantics, is the possibility to test the application already in the design activity. This is feasible since the completeness of an SDL design makes it possible to simulate the design taking distribution and concurrence into account.

It is important to emphasis that the output of the object design activity is not only an SDL design but it is a tested SDL design that has been shown to fulfil its requirements. This implies that the design testing is an important task in the object design activity.

Testing Strategy

A traditional development/test strategy can be described by a "V" as in Figure 705. The design is performed top down, starting with a system design where the major components and their interfaces are defined, followed by a module design and an implementation phase where the application is implemented. The implementation of each module is then tested separately in a module test and finally the entire system is tested. The system test can also sometimes be divided into two parts, one focusing on the integration of the different modules and the other focusing on testing the functionality of the complete system.

Figure 705 : The "V" model of a traditional design/test strategy

This model works in practise fairly good but it has one problem: the complete functionality is not tested until the system tests are performed in the end of the development/testing process. To some extent this problem can be overcome by an iterative process that includes more than one "V" in a development project. Using techniques like SDL this can be even more improved by introducing one more line of testing in the model as in Figure 706.

Figure 706 : The improved "V" design/test strategy

The extra line of testing represents the design level testing that is the focus of this section. There are two practical aspects that differentiates the design testing from the traditional target testing:

  • It is performed using a simulation of the design instead of on the real application in its target environment:
  • It is performed as part of the design activity instead of as a separate testing activity performed after the implementation.

The second aspect is very important. Problems that otherwise would not show up until system test time is now found and solved during design at a much lower cost.

In the figure it may look like the testing effort has doubled in the improved "V" strategy since there are now two lines of testing instead of one. This is fortunately not the case. What has happened is that the effort of testing has switched from the target testing to the design testing, making the total amount of testing more or less the same. There are several reasons for this:

  • The cost of testing is smaller for design testing than for target testing: the design testing on SDL level is very easy to perform. Since a large portion of the testing is performed at the SDL level this reduces the total testing cost.
  • The target testing can focus on the integration and targeting aspects since the logic of the design has already been tested in the design tests. In practice the target module testing can even be skipped if automatic code generation is used when producing the implementation.

Test Case Sources

There are several sources from where the test cases may come:

  • From Design Use Cases
  • Internally developed during design
  • From external sources.

The most important input, both to module and system test, is the design use case model from the system design. This model should capture most of the requirements on the system and using the implinks it is also possible to trace the dependencies from the original requirements all the way to the design use cases. Furthermore, the design use case should be in a format that is possible to test more or less automatically against the SDL system, like MSC or TTCN.

However, during the object design there are usually more test cases developed that tests other aspects of the design, and these form also an important part of the module testing tests.

The third source of tests is external sources. For example, in the telecommunication area it is common to have standardized tests suited for certain types of applications or interfaces. In other cases the customer may have specified acceptance tests that the system must comply to before it is approved. These type of tests should of course also be part of the design tests, in particular for system testing the external sources are important.

It is convenient, but not necessary, if the same notation is used for the design use cases, the tests developed during object design and the external test suites.

Tools for Testing

To perform the testing there is a need for tools, and fortunately there are several tools available that make a number of testing strategies possible:

  • Manual or batch simulation of an SDL system using a standard SDL simulator
  • MSC verification and automatic testing using a state space exploration tool
  • Co-simulation of SDL and TTCN, using standard SDL and TTCN simulators

Using a standard SDL simulation tool it is of course possible to manually simulate the test cases and check that the system performs as expected, but it requires quite a lot of manual work. A better way is to produce test scripts that contain the simulator commands that are needed and then execute them automatically in a batch mode and log the results on a log file. To check the outcome of the test either the log files are manually inspected or checked by a post processing tool that e.g. compares the new log files with old, manually inspected log files.

Another approach to testing is to use a state space exploration tool that can automatically check if an MSC is consistent with the SDL system. The benefit with this method is that MSCs can be directly input to the tool and checked and furthermore there is no need for a manual inspection of the results: a verdict can be automatically generated by the tool. The drawback is that some features like the combination of user-written and automatically generated code can not always be handled by state space exploration tools.

A third approach that is useful if the tests are defined using TTCN is to use a co-simulation of an SDL system and a TTCN test suite as the means to perform design testing. Essentially this is similar to using an SDL simulator alone, but instead of specifying the input as simulator commands a TTCN simulator specifies the input to the SDL simulator and checks the outcome of the test.

Test Practices

A common situation in particular when performing module tests is that there is a need to test one part of an SDL system in isolation from the rest of the system. In an SDL system the part may be for example a block, a process or a data type definition. The simplest way to accomplish this in SDL is to use a package as a container of e.g. the block (which in this case will have be a block type) or data type and then use a special test system to specify the test environment.

As an example consider the DoorCtrl part of the access control system. Assume that this part is designed as a block type "DoorCtrlT" in a package DoorCtrlPack. To perform a module test on this block the simplest way is to create a special test system DoorCtrlTest that instantiates the DoorCtrlT and connects all its gates to the environment.


Consistency Checks

This sections describes some consistency checks that are useful to perform on the models produced in the object design.

  • Check that all objects from the analysis object model has been implemented in the design.
  • Check that the design model is complete according to the SDL rules, e.g. that all processes have a defined behavior.
  • Check that the design model correctly implements the requirements from the design use cases using design level testing.


Summary

The object design activity should produce a complete and tested design of the system. The precise system and internal object structure as well as the reuse structure are defined in this activity. Relevant parts of the object models are mapped to SDL concept and then completed in an SDL process design activity with design use cases as the main input. This is done iteratively by starting with a initial set of essential use cases, making that part of the design complete and then testing the design (verifying it against the use cases). The activity is finished when all use cases have been implemented and the final design has been tested against all the use cases.


75 SOMT Implementation

This chapter describes the different ways to implement an SDL design and the tasks that have to be done in connection with this. The focus is on automatic implementation relying on automatic code generation and using C as the target language.


Implementation

The implementation activity results in a tested and running application in the target environment.

Figure 707 : Overview of the implementation activity

The activities during implementation are highly dependent upon the application and target and there are several possible ways to implement an SDL design. It can be manually implemented in software or hardware or a more automatic implementation can be used relying on automatic code generation. The discussion in this section is mainly intended to give an overview of different aspects on the latter approach using C as the target language. There are several tasks to be done in the implementation activity:

  • Partitioning the SDL system into different software (and/or hardware) run-time modules.
  • Implementing the adaptation code that is needed for this specific SDL system to operate in its environment.
  • Selecting and implementing a general integration strategy for the target hardware and run-time environment.
  • The generation of C code and the customizing of it for different application areas.
  • Testing to ensure that the application works in the target environment.

Figure 708 : Example of activities during the implementation


Partitioning an SDL System

The purpose of the partitioning task is to partition the SDL system into separate parts that will form stand-alone executables by themselves, either to run as separate programs on one computer or distributed on several computers in a network.

There are two different possible strategies for how to do the partitioning in practise:

  • Use directives to the C code generator to define what parts of the system that will form separate run-time executables.
  • Create different SDL systems for the different partitions and generate code for them separately.


Adaptation

An application generated from an SDL description can be viewed as having three parts:

  • The SDL system
  • The physical environment of the system
  • The environment functions, where the SDL system is connected with the environment

When adapting the application, the environment functions may have to be specified depending on the integration mechanism used. The environment functions are the place where the two worlds, the SDL system and the physical environment, meet. Signals sent from the SDL system to the environment can be specified to perform any event in the physical environment, and events in the environment are specified to cause signals to be sent into the SDL system.

Figure 709 : The structure of an application

In a distributed system an application might consist of several communicating SDL systems. Each SDL system will become one executable program. The environment functions that has to be written for each SDL system are:

  • xInitEnv - handles the initialization of the environment and will be called during the start-up of the application (before the SDL system is initialized).
  • xCloseEnv - is called when the SDL system terminates.
  • xOutEnv - will be called each time a signal is sent out of the SDL system.
  • xInEnv - This function is repeatedly called during the execution of the system. During this call, the environment could be scanned for events which should result in a signal sending into the SDL system.
  • xGlobalNodeNumber - returns a number that is unique for each communicating SDL system that constitutes an application.


Integration

The purpose of the integration task is to select (and implement if no predefined integration exists) a generic integration mechanism that makes it possible to execute a generated application in a target hardware/software environment. There are three different strategies available for this integration:

  • Making an integration using the SDL run-time system, where the SDL application directly runs on a micro processor without any additional operating system support.
  • Making a light integration to an operating system, where an SDL system (together with a run-time system) is treated as one task in the operating system.
  • Making a tight integration to a real-time operating system, where each SDL process instance (or set of instances of a specific type) results in a task in the operating system.

Both the integration using the SDL run-time system and the light integration use a supplied run-time system to execute the SDL system that takes care of the SDL semantics including scheduling of processes etc.

A tight OS integration consists of a set of files that define how the SDL semantics is mapped to the operating system in question. The main categories are:

  • Macro definitions that define the macros in the generated code
  • Functions that handle constructs that cannot be used directly in the operating system (i.e. saving of signals)
  • Functions that are dependent on the specific operating system (i.e. allocate/free memory)
  • Definitions and handling of SDL predefined data types
  • Identifiers for signals, timers and remote procedure calls
  • Post processing utilities to enumerate signal and process types

An existing integration for an operating system is highly reusable and several predefined integrations are available.


C Code Generation

Although the C code generation is a highly automated activity, there are several ways of customizing the generated code. Some examples are:

  • Generating separate C files for different SDL structural entities
  • Assigning priorities to processes to enable scheduling (which is undefined in SDL)
  • Making a user-defined implementation for the handling of certain signals
  • Making a user-defined main-loop (run-time system) in the generated application

Separation of the C files is recommended for large systems, since a minor, local change in for example a block diagram only requires a regeneration and recompilation of the code for that unit. The object files (the compiled versions of the C files) for the other unchanged units can then be used in the link operation to form a new executable program. Thus, the turn-around time from a change in the design to an executable application is minimized.

When doing a customization of the code, it is important that this is done in a way that keeps maintenance of the design easy.


Testing

The purpose of the testing task in the implementation activity is to verify that the application works in its target environment. The input is the test cases specified in the system design and the output is a test report and a tested application. The details of the testing task is very much depending on the target environment and the possibilities to run tests against the application in this environment. Essentially the tasks involved in the testing are:

  • Creating a test environment that can communicate with the application and where the tests can be executed
  • Transforming the test cases to a format that can be used in the test environment
  • Run the tests
  • Analyze the results of the tests


Summary

The final SOMT activity, the implementation, completes the development activities by creating an application that runs on the target environment. From the SDL object design, C code is created, the code is adapted to handle the environment of the SDL system and then integrated to the hardware by means of generic interfaces to real-time operating systems. Finally, the application is tested in its target environment.


76 SOMT Projects

This chapter describes how to organize the activities and models of SOMT into a project. The description is intended to be suitable for a medium size project.


SOMT Projects

A development project that uses an object oriented approach like the SOMT method is not very different from any other development project. The project has a starting point, the project members work hard and finally the project is finished, hopefully successfully accomplishing the goals of the project in terms of quality, functionality and delivery time. The skill of planning, managing and executing a successful development effort has been studied and described in many books and it is outside of the scope of this document to give a complete treatment of this topic. A recent book that treats management and planning issues for object oriented projects is "Object Solutions" [32] which is recommended for further reading.

Nevertheless, this section is intended to give some indications on how to organize the activities and models of the SOMT method into a project. The description is intended to be suitable for a medium sized project where the effort is big enough to force the development to be divided into several development teams. A smaller project would most likely need less formalism in the development process and a bigger one more control.

Project Phases

From an external point of view (like a manager's point of view) it is useful to organize a project into a number of phases, where each phase represents work performed during a limited period of time resulting in a set of artifacts, deliverables that summarizes the state of the work after the phase is finished. There is a fundamental difference between the phases of a project and the activities as used in this document to describe the SOMT method:

  • The phases are used to organize the calendar time of a project.
  • The activities represent a categorization of different kinds of tasks by their nature, not by their relative time in a project.

Nevertheless there is a strong relation between the phases of a project and the activities that has to be performed. There is a dependency between the activities of the SOMT method that indicates an ordering in time between the activities. There is no reason to start the system/object design before a substantial amount of work has been done on the system analysis. Likewise there is no reason to start the system analysis before there is a common understanding of the requirements elaborated in the requirements analysis. On the other hand it would be a waste of time and even dangerous for the project to get bogged down with the details of the requirements for a substantial amount of time without considering their consequences in terms of architecture and design.

The dependency between the activities indicates that a fruitful way to organize a SOMT project is to consider it as a sequence of iterations of the activities. The phases are introduced as a means to get a visibility of important milestones and deliverables from the project. One way to define the phases of a SOMT project is as follows:

  • Prestudy/conceptualization phase
  • First iteration
    • Requirements analysis phase
    • System analysis phase
    • System design phase
    • Design/implementation phase
  • Elaboration phase
    • Planned consecutive iterations

Each of these phases has a section of its own in this chapter.

Multi-User Support

There is often a need to facilitate multi-user support when working with an SDL system managed by Telelogic Tau. That is, we want to have a development environment capable of handling parallel development. One way to get support for the development process is through using Configuration Management (CM). With CM is usually meant the check in and check out control of sources and binaries, and the ability to perform builds of these entities.

If CM is to be used within a project it has to be planned for. This planning is not something that is carried out in isolation. It is a part of the overall project planning process and is implemented throughout the life cycle of the project. The plan should cover activities to be performed, the schedule for the activities, the assigned responsibilities and the resources needed (including staff, tools and computer facilities). A key task is to decide exactly which items that are to be controlled and define the engineers responsible for these items. During the development process the code is usually stored in a database based on a revision control system. The developers checkout a copy of it to their own personal workspace. Changes are then made locally and checked in when completed and tested. The developer is responsible for making sure that the module works before he checks in the changed files.

When several users work on an SDL system, the management of the system file may be difficult to synchronize. This problem is solved if every user or group has control over their own part of the system file. The multi-user support in Telelogic Tau is based on letting the users split the system file into several files, called control unit files. Where to split the system is an active action taken by the user, but the idea is to partition the system according to work responsibilities and to assign a control unit to each partition. Apart from supporting parallel development, the control unit files also facilitate merging of the individual results to one common system file. An example is a large SDL system where there are several blocks on system level developed in parallel by different developers. Each block could then be associated with a control unit file. Now, the blocks can be updated independently and the changes are shaping the local control unit files. Also, there is no need to manually merge changes into the system file when the work has been done. This is because the management of control unit files, performed by the Organizer, includes the merge.

Another way to get support for parallel development is through using the object oriented concepts of SDL, i.e. types and packages. Instead of introducing a block reference symbol for every subsystem we introduce a block type. The block types are placed in packages together with the signal and data type definitions that are needed within that particular block. If two blocks need the same signals and data types then these definitions are placed in a package of their own. Other packages can then use this package. In the same way as we define block types we can also define process types instead of process reference symbols. The different packages containing the types can be analyzed independently. We can also create instances of the types to simulate, verify and validate the behavior of a particular part of the system. When all parts of the system have been designed and tested we put them together, i.e. we create instances of the types and test and verify the overall system behavior.


Prestudy/Conceptualization Phase

The prestudy/conceptualization is the initial activity needed to establish the core requirements that satisfy a well-defined user need and to identify the risks involved in the project by establishing a proof of concept for the project. It is not in the scope of the prestudy/conceptualization to completely analyze all aspects of the requirements, it should rather establish a vision of the underlying idea. It should also validate the assumptions on user needs and implementation technology. One way to do this can be to build an early prototype that illustrates the goals of the project. The prototype may also be an aid in the identification of risks, e.g. related to technical aspects or to the functionality of the system.

In many cases the prestudy/conceptualization can be viewed as a project by itself, following essentially the same steps and phases as any other project, with the exception that the time scale is shorter and that the result is not a finished system. The tangible results from the prestudy/conceptualization should be:

  • A clear vision of the requirements (possibly illustrated by an early prototype)
  • A risk assessment that identifies the major obstacles ahead


Requirements Analysis Phase

After the prestudy/conceptualization phase it is time for the first iteration through the activities in the SOMT method. This will go through the requirements analysis, system analysis and system/object design and sometimes also the implementation activity. This first iteration is in some sense the most important part of the project since it involves both an analysis of the requirements on the system and the development of an architecture that will meet these (and future) requirements. If this first iteration is successful the further elaboration and refinement of the system will work without any catastrophes. If the first iteration is not successful, e.g. an insufficient understanding of the requirements leading to an inappropriate system architecture, there are loads of problems ahead.

The requirements analysis phase starts the first iteration. The activities of this phase are of course centered around the analysis of the requirements as detailed in 70 Requirements Analysis. When this phase is finished the analysis team must have established a common vocabulary and a common understanding of the system's desired behavior. The deliverables are first versions of the models associated with the requirements analysis:

  • The textual requirements
  • The data dictionary
  • The requirements object model, including both information models of the problem and context diagrams
  • The use case model
  • The system operations model

The most important of these are the use case model, the requirements object model, including the context diagrams, and the data dictionary. Together these describe the major behavior of the system and define a vocabulary describing the application and its environment. The textual requirements are hopefully part of the input to the requirements phase and it is often useful to elaborate these further mainly in the case where the original requirements are too unstructured or incomplete. The system operations are useful if the level of abstraction in the use cases are not found to be detailed enough.

In practise most of the time during the requirements analysis is usually spent designing the use cases, using these as a means to investigate the intended behavior of the system. It is impossible to completely cover the entire set of behaviors in the requirements analysis. Finding the right trade-off between the completeness of the use cases and the time and effort spent in requirements analysis is an important aspect of this phase. A recommended practise from [32] is that the use cases should cover `approximately 80% of the primary scenarios along with a representative selection of the secondary ones'. The use case model (as well as the other models) will be further extended and refined during the elaboration phase so it is important to force the requirements analysis phase to a completion when a sufficient level of understanding has been reached.


System Analysis Phase

The system analysis phase takes over where the requirements analysis stopped. Where the requirements analysis focussed on external requirements the system analysis focuses on the internal architecture of the system. The analysis object model is the major medium used to describe the architecture. The architecture is defined in terms of the objects and object structures defined in this model. To establish the responsibilities of the different classes and verify that the proposed architecture is sufficient the use cases from the requirements analysis are in this phase refined in the analysis use case model.

It is not uncommon in practise that there is an overlap in time between the different phases and this is also true for the requirements analysis phase and the system analyses phase. It makes sense to start sketching the architecture of the system before the requirements analysis is brought to completion to capture ideas about the architecture whenever they emerge. It is however important to view this as a side activity and not forget to force the requirements analysis to a completion before digging into the details of the architecture.

The system analysis is finished when there is a consistent and well understood definition of the major objects needed in the system, including a clear definition of the responsibilities for the different objects, and the architecture is validated using the analysis use cases. It is beneficial if the system analysis can be performed by a small team consisting of the best people available including an experienced architect and some more developers.


System Design Phase

For many projects there is a need to divide the design work on more than one design team. In this situation the system design phase is a crucial phase since this is when the interfaces between the different parts of the system are defined. A good interface definition is essential to give the different development teams a possibility to progress with their work without confusion. In the system design the logical architecture from the system analysis is used to decompose the system into subsystems to be implemented by different teams and the interfaces between the subsystems are defined. The static interface is defined in terms of signals and/or remote procedure calls. The dynamic aspects of the interface are defined in the design use cases that should be precise enough to be used as test cases by the design teams.

For practical reasons it is best if the same team that performed the system analysis phase also is involved in the system design phase, but extended with more designers and test engineers from the teams that will continue the design work to ensure that an understanding of the architecture is spread also into the different design teams.

The system design also includes planning the design module structure to be used in the design of the system to facilitate a smooth integration between the different subsystems. The design module structure is in essence a definition of the structure of the work to be performed by the different teams and it must be designed in order to facilitate reuse of common components and existing frameworks.

A third aspect to be considered in the system design phase, which is more of a project management nature, is to plan the following design and elaboration phases. The planning should be based on the achieved knowledge of the architecture and behavioral requirements and is intended to define the order in which the different features of the application is designed. The major criteria for defining this order is to minimize the risks involved in the project by validating the assumptions about the architecture as soon as possible and by designing the difficult and uncertain parts as early as possible. This implies that the design phase following the system analysis should concentrate on designing a first version of the application that covers an `interesting' subset of the behavioral requirements (as defined in the use cases) and create a skeleton structure where all major components are in place but where their complete functionality is not yet realized.

When the system design is completed the tangible results are thus:

  • A detailed architecture described using SDL block structures, including:
    • Static interface definitions with signals, remote procedures and the necessary data definitions, possible described using ASN.1
    • Design use cases describing the dynamic aspects of the interfaces
  • A design module structure describing the structure that is to be used in the design phase
  • A plan for the design process, that identifies key concepts to be designed and key use cases to use as a focus of the design phase and the elaboration phase


Design/Implementation Phase

The design/implementation phase, which as discussed above in general, is performed in parallel by several different development teams is in an SDL based SOMT project aimed at producing an executable SDL model of the application. Executable may here mean that it is possible to verify the design use cases against the SDL-model by executing the SDL model in e.g. a simulator or state space exploration based tool, but it may also imply an implementation activity that creates a first version of the application running in the target environment.

The choice of when to start the implementation activity is mainly riskdriven. If performance or memory requirements are crucial and seen as a risk in the project, e.g. if the hardware architecture is new and untested, then at least parts of the system should be implemented on the target to minimize these risks. If this is not the case, the integration with the target hardware can be planned to be part of some of the iterations in the elaboration phase.

Depending on the circumstances for the specific project the target platform can of course be very different, from the simplest case being that the target platform is the same type of computer as the development platform to the more complex situation where an embedded system is to be built and the target platform is a small micro processor. In the latter case, the implementation activity for an SDL-based project does in general consist of using a code generator to generate the code from the SDL system, write adaptation code to interface to the target hardware and the run-time environment to be used on this platform, and to use a cross compiler to produce code that is executable on the target machine.

In any case the deliverable from the design/implementation phase is an executable system that implements some of the requirements posed on the application and that is internally released as the first version of the application. The system should also have been through a testing process that verifies that the selected design use cases that where implemented indeed works as they should. This testing will of course consist of both a module testing performed on the different parts by themselves as well as a system/integration test that verifies that the system as a whole works as it should.


The Elaboration Phase

The rest of the project, the elaboration phase, consists of a number of iterations through all the activities, from requirements analysis to implementation. Each iteration produces a new internal release of the application and refines and extends the architecture and system until it finally is finished. A typical iteration starts with a requirements analysis activity that includes a review and refinement of the use cases to be implemented in the current iteration. This is followed by system analysis and design activities that checks that the use cases are correctly distributed over the architecture and that the interface definitions are updated if needed. These activities should preferably be performed by an architecture group containing representatives both from the original architecture group who worked in the system analysis/design phase and from the different design teams.

The design and implementation activities that are part of an iteration are of course as before performed by the different design teams, each one refining and extending their part of the system to implement the use cases that are the goal of this particular iteration. The result of the design and implementation activity should be a new internal release of the application that has been through the appropriate module and system tests to verify its functionality.

In addition to extending the functionality of the system each iteration should also be focussed on minimizing the risks in the project. Crucial and difficult aspects should be tackled as early as possible in the elaboration phase to avoid unpleasant surprises at the end of the project.


Summary

A SOMT project can be described in terms of a number of phases, that describe the calendar time of the project. The phases are introduced as a means to get a visibility of important milestones and deliverables from the project. The various phases of a SOMT project are:

  • Prestudy/conceptualization phase
  • First iteration
    • Requirements analysis phase
    • System analysis phase
    • System design phase
    • Design/implementation phase
  • Elaboration phase
    • Planned consecutive iterations

A graphical view of a possible SOMT project is illustrated in Figure 710.

Figure 710 : The different phases in a SOMT project

In this figure the various activities (as show on the vertical axis) are divided into a number of phases (as shown in the horizontal axis). The dashed lines indicate the deadlines for the different phases. Note that the activities associated with a specific phase may often start before the deadline of the previous phase is reached. This is common and useful. The purpose of the organization of the activities into phases is not to control when an activity starts, but to be able to focus on when an activity should be finished. This is what indicates the progress of the project.


77 SOMT Tutorial

This tutorial is intended to present how to combine object-oriented analysis and SDL design in practise in a development process. This is a method developed by Telelogic, known as the SOMT method, SDL-oriented Object Modeling Technique.

We will demonstrate, using an Access Control system as example, the various activities and models in SOMT together with the provided tool support for SOMT in Telelogic Tau.

Through the tutorial you will practise on various exercises that will get you familiar with the SDL suite tools as well as the SOMT method.


Introduction

Purpose of This Tutorial

This tutorial presents how to use the SOMT method and Telelogic Tau in practise in a design process.

The working example is an Access Control system. The system shall control the entrances to an office. Each employee working in the office has a card and a personal code. To enter the office, the employee enters a card into a card reader and types a personal code on a keypad. To exit the office the employee presses an exit button.

You will perform the development process for the Access Control system applying the SOMT method. The tutorial will guide you through the development process step by step presenting a number of hands on exercises for you to perform. The tutorial is expected to be read sequentially.

After reading the tutorial, you should have gained knowledge about how to apply the SOMT method on a development process.

Note: Platform differences

This tutorial, and the others that are possible to run on both the UNIX and Windows platform, are described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc. When such platform indicators are found, please pay attention only to the instructions for the platform you are running on.
Normally, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see when running Telelogic Tau on your platform. Only if a screen shot differ in an important aspect between the platforms, two separate screen shots will be shown.

Required Skills

It is assumed that you have a basic knowledge about UML and SDL. We also recommend newcomers to acquaint themselves with the basic features of the SDL suite tools. You can do this by practising on the exercises in the tutorials provided for the different tools. Please see the previous chapters in this volume.

It is recommended that you have read the SOMT Methodology Guidelines in chapters 68-76 in the User's Manual.

Preparations

  1. Make a new empty directory of your own for the purpose of this tutorial, e.g. ~/somttutorial (on UNIX) or C:\Telelogic\SDL_TTCN_Suite4.4\work\somttutorial (in Windows).
  2. Copy the SOMT tutorial directory and its subdirectories in $telelogic/sdt/examples/somttutorial (on UNIX), or C:\Telelogic\SDL_TTCN_Suite4.4\sdt\examples\somttutorial (in Windows), into this new directory (contact if necessary your system manager).

Note: Installation directory

On UNIX, the Telelogic Tau installation directory is pointed out by the environment variable $telelogic. If this variable is not set in your UNIX environment, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for instructions on how to set this variable correctly.
In Windows, the Telelogic Tau installation directory is assumed to be C:\Telelogic\SDL_TTCN_Suite4.4 throughout this tutorial. If you cannot find this directory on your PC, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for the correct path to the installation directory.

  3. On UNIX, cd to your own subdirectory somttutorial
  4. Start Telelogic Tau.
  5. Specify the source directory for the system by double clicking on the Source directory symbol located second uppermost in the Organizer window. The source directory specifies where new documents that you have created are saved by default, and from where to read when opening and converting documents. Since there are multiple versions of the Access Control system, each version with diagrams stored on files with identical names (but in different directories), omitting to specify the source directory may cause the wrong version of a file to be opened.
  6. In the Set Directories dialog that is opened, select the third radio button associated with Source directory. In the text field, enter the complete path and name of your own somttutorial directory, if it is not there already. Press OK to close the dialog. (You do not have to change any of the other options in this dialog.)


Preparing the Documentation Structure

What You Will Learn

  • To prepare a SOMT project by making preparations in the Organizer

Introduction to the Exercise

Your task is to modify the basic view of the Organizer to get the desired document structure.

The result of the exercise will be an Organizer structure containing a number of chapters and modules, see Figure 713. The chapters will correspond to the different activities in SOMT and the modules will correspond to the models in each activity.

Deleting Unwanted Chapters

When you start a new project with Telelogic Tau you will get the default basic Organizer view, see Figure 711. (This view could be different if you do not have the default preferences set). The Organizer contains a few black lines with attached names, the chapters. The purpose of these chapters is to group together collections of documents.

Figure 711 : The basic Organizer view

We want each chapter in the Organizer view to represent an activity in SOMT. The current chapters in the Organizer will not fit into our future documentation structure so they should be removed.

Delete the unwanted chapters by following the steps below:

  1. Make sure you have the basic view in the Organizer.
  2. Select the chapter named Analysis Model.
  3. Select the Remove command in the Edit menu or press the <Delete> button. You also find the Remove command in the pop up menu. The Remove dialog is issued asking you to Remove or to Cancel the action.
  4. Press the Remove button. The dialog disappears and the chapter is deleted.
  5. Repeat the steps above and remove all of the remaining chapters.

Adding New Chapters

You should now organize the Organizer view into chapters corresponding to the different activities in the SOMT method, i.e. each chapter should contain documents and diagrams from one particular activity.

You will have to add four chapters and they will be named Requirements Documents, System Analysis Documents, System Design Documents and Object Design Documents, respectively.

First, add the Requirements Documents chapter:

  1. Select the Add New command in the Edit menu. The Add New dialog arises with the Organizer radio button set.
  2. Select the Chapter option in the option menu connected to the Organizer radio button.
  3. Change the document name Untitled to
    Requirements Documents.
  4. Press the OK button or <Return>. A chapter named Requirements Documents will appear as the uppermost chapter object.
  5. Now repeat the steps above and add the three remaining chapters and name them System Analysis Documents, System Design Documents and Object Design Documents, respectively.

If the chapters show up in another order than the one you want in the Organizer window, you may move a selected chapter by using the arrow quick buttons in the tool bar.

  6. If needed, move the chapters in the Organizer to get a structure corresponding to the one in Figure 712.

Figure 712 : The Chapter structure

Adding the Organizer Modules

The next step to take when preparing the document structure is to add the Organizer modules. A module in the Organizer forms a naming scope around the documents it contains. It may contain any kind of documents.

As each activity in SOMT consists of a number of models, it seems natural to let a model correspond to a module in the corresponding chapter. You should now add the modules to the chapters in the Organizer structure.

  1. Select the chapter named Requirements Documents.
  2. Select the Add New command in the Edit menu.
  3. In the Add New dialog, make sure that the Organizer radio button is set. Select the Module option in the Organizer option menu.
  4. Change the name Untitled to RequirementsUseCaseModel

Note:

You are not allowed to have any space characters in the name of a module.

  5. Press the OK button. A module named RequirementsUseCaseModel appears in the Requirements Documents chapter.
  6. Now add the other modules to their respective chapter in the Organizer view. Let each model in a SOMT activity have its own module. The document structure in the Organizer should look like Figure 713 when you are finished.

Figure 713 : The complete document structure

This structure will form the framework to organize the forthcoming documents around.

  7. Save the Organizer structure and name the file accesscontrol.sdt.

Now you have finished the preparations and you can start to develop the Access Control system using the SOMT method.


Identifying the Requirements

Figure 714 : Overview of the SOMT process

What You Will Learn

  • To bring in external (requirements) documents into the Organizer
  • To identify important concepts
  • To use a data dictionary
  • To identify actors and use cases and to compile the information gained into textual documents
  • To create a textual use case
  • To create an MSC use case out of a textual use case
  • To make a requirements object model
  • To connect important concepts in the different documents with implinks
  • To perform consistency checks

Introduction to the Exercise

In this exercise you will perform the tasks associated with the requirements analysis activity. The purpose of the requirements analysis is to:

  • Gain understanding of the problem domain - the Access Control system and the environment in which it is going to exist.
  • Find and understand all requirements imposed on the Access Control system.

Producing a complete requirements analysis would take too much time in this tutorial. Therefore, you will only perform parts of every required step of the process.

The result will not be a complete requirements structure, but you will have acquired knowledge of how to use the SOMT method in the process of identifying requirements.

Preparing the Exercise

You can use your own document structure from the previous exercise (just move your accesscontrol.sdt file to the ReqA directory), or use a provided solution.

  1. Open the system file somttutorial/ReqA/accesscontrol.sdt (on UNIX), or somttutorial\reqa\accesscontrol.sdt (in Windows).
  2. Check that the Source directory is set to somttutorial/ReqA/ (on UNIX), or somttutorial\reqa\ (in Windows), in the same way as you did in the preparation to this tutorial (see "Preparations" ).

Studying the Textual Requirements

Including External Textual Requirements

A textual document with requirements is the input to the Access Control system development project and it will form the base from which the Access Control system is developed. You will later on create implementation links (so called implinks) between the textual requirements document and other models. This is done to make it possible to follow a requirement through a number of models all the way down to code.

The textual requirements document of the Access Control system is contained in a text file. This file should now be included in the Organizer work area.

  1. Select the module named TextualRequirementsModel in the Requirements Documents chapter.
  2. Select the Add Existing command in the Edit menu.
  3. In the Add Existing dialog, change the filter to *.txt and press the Filter button. Select the file TextualRequirements.txt and press OK to add it.
  4. The TextualRequirements document is now added to the module TextualRequirementsModel in the Organizer and the Text Editor showing the document is opened. The document looks like Example 604.

Example 604 : The textual requirements

The task is to design the software to support a computerized Access Control system. The purpose of the system is to control the accesses to an office.

An entrance leading to an office can have four different security levels:

  1. Always unlocked
  2. Requires a card to unlock
  3. Requires a card as well as a code to unlock
  4. Always locked

The security levels of an office entrance can be altered during the day.

Each employee working in the office has a card with a personal code consisting of four digits. To open a door with security level three, the employee enters her card into a card reader and types her personal code on a keypad. The time between consecutive keystrokes when typing the code is not allowed to exceed three seconds. To enter through a door with security level two, the employee just enters her card into a card reader.

Each entrance leading into the office consists of a door with an electric lock as well as a card reader, a keypad and a display on the outside, and an exit button on the inside. The employee needs a card and a code to enter the office. To exit, the employee just presses the exit button and the door is unlocked for ten seconds.

All entrances communicate directly with a central controller which makes sure that a validation of the correctness of cards and codes is performed. The controller has access to a database consisting of all card numbers and their corresponding personal codes. If the card is valid and, in case of security level three, the corresponding code correct, the door is unlocked for ten seconds and the employee may enter. In case of an invalid or unregistered card, access to the office is not allowed. In case of an incorrect code, the employee is informed of this and must try again by entering the card into the card reader and retyping the personal code.

The Access Control system must read its data, consisting of card numbers with their corresponding personal code, from a database. The database is managed by using a separate management system that is not developed within the project. The system operator, who is running the management system, is authorized to register new employees, cards and codes, to change a code if the employee wishes so, to delete employees from the database and to change the security level of an entrance. The system operator is also responsible for initializing the Access Control system. All the actions mentioned above are done using the management system.

The system must be able to recover from computer and connection failures. If a connection between an entrance and the central controller is lost, the door is locked from the outside not permitting anyone to enter (i.e. security level four is set). It is, however, possible to open the door from the inside by means of the exit button.

The system must be extensible to include new functions and be easily maintained.

Creating Textual Endpoints

Now you should study the textual requirements document and mark all concepts (nouns) that you find essential for the problem domain as link endpoints. These marks will be very useful in later stages of the project. In this tutorial most of the endpoints in the textual requirements document have already been created. You task is to add the two missing ones:

  1. In the second sentence of the textual requirements document locate the word "office" and mark it with the mouse.
    When you mark an endpoint see to it that you only mark the word itself and not any additional characters, like a space or a dot after the word.
  2. In the Link submenu in the Tools menu, choose Create Endpoint.
  3. The text will be underlined indicating that the text fragment now is a link endpoint.
  4. Now, locate the word "entrance" in the third sentence and create an endpoint out of it by repeating the procedure above.
  5. If you go through the rest of the document you can see that the rest of the important concepts already have been marked as endpoints.
  6. Save the document.
  7. Open the Link Manager. This is done by choosing Link Manager in the Link submenu in the Tools menu. You can do this either in the Organizer window or in the Text Editor window; the result will be the same.
    The Link Manager window will pop up showing all the endpoints of the textual requirements document. The endpoint background color is used to show the endpoint status. As the endpoints are newly created, and the link file has not been saved yet, the background of the endpoints is painted gray.
  8. Save the link file from the File menu, giving it the name Links.sli.
  9. Close the Link Manager window.

Creating the Data Dictionary

A data dictionary is a textual document which should define all important concepts found during the whole development process. It forms a common vocabulary for the members of the project. It is a good idea to:

  • Provide each item included in the data dictionary with a name and a brief explanation.
  • Categorize the concepts in nouns, verb phrases and relation phrases.
  • Sort the concepts alphabetically.
  • Have a section in the data dictionary for each activity. This might be a good idea because a certain concept often has different meanings in different activities. For example, a concept can be described by a class in one activity and in the next activity it might be described by a block with a corresponding process.

All the important objects, relations and verbs that you find in the textual requirements should be included in the data dictionary. This has already been done in an existing DataDictionary file, so you do not have to do anything. Just add the existing file:

  1. Add the existing DataDictionary.txt file to the DataDictionaryModel module in the Organizer. The Text Editor will show the DataDictionary.
  2. Read through the document to get yourself acquainted with the problem domain vocabulary.

All nouns, relation phrases and verb phrases in the data dictionary are marked as link endpoints. This has been done to make it possible to do entity matches between any model and the data dictionary. An entity match checks that all entities in one model have matching entities in another model. That is, we can check that all entities in a model really are described in the data dictionary. This will be performed in "Entity Match" .

The example below shows a part of the requirements analysis data dictionary.

Example 605 : A data dictionary

Nouns/Objects

Access control system - A system to control the access rights to an office so that no unauthorized persons can enter without permission.

Card - Each employee working in the office gets a card and a corresponding personal code. By means of this card and code, the employee can get access to the office.

Cardnumber - The number that uniquely defines a card.

...

Relation Phrases

Card with code - Each employee in the office has a card with a personal code.

Connection between central controller and entrance - There is a connection between every entrance and the central controller.

...

Verb Phrases

Change code - An operation done by the system operator to change the code of a card.

Change Security Level - An operation done by the system operator to alter the security level of an entrance.

Connection is lost - The connection between an entrance and the central controller can sometimes fail. In case of broken connection nobody can enter the office. It is, however, possible to leave the office.

...

Creating the Use Case Model

The purpose of a use case model is to capture the requirements and present them from the users point of view, thus, making it easier for the intended users to validate the correctness of the requirements analysis.

The use case model consists of:

  • A list of actors
  • A list of use cases
  • A number of MSCs (message sequence charts) and/or textual use cases

The use case model is also a useful source of information when developing the requirements object model, see "Creating the Requirements Object Model" .

A use case is a sequence of actions showing a possible usage of a system. Use cases developed during the requirements analysis activity should mainly concern the interaction between the system and the users of the system. No message exchanges within the system should be shown.

Users of a system may be people, other systems or objects outside the system border which interact with the system.

An actor is a user taking part in a use case. An actor is not supposed to be an individual user, but rather represents one of the different roles a user can play when interacting with the system.

There are different ways to describe a use case:

  • A textual description of the use case
  • A description of the use case using an MSC
  • A combination of both a textual description and an MSC

Describing use cases using textual descriptions will make it easier to model exceptions and alternative paths of action sequences. Describing use cases using MSCs will make the use cases more formal and easier to verify. Also, as MSCs will be used in the coming activities, it might be a good idea to start using them already in the requirements analysis. The tutorial will use both textual descriptions and MSCs in the requirements analysis activity, and only MSCs in the later activities.

Creating a List of Actors

Now it is time to create a list of actors. The list of actors should list the actors by name, together with their respective responsibility.

  1. In the Organizer, select the RequirementsUseCaseModel module and choose Add New. In the Add New dialog, set the Text radio button and choose Plain in the corresponding option menu. Name the new document ActorsList and set the toggle button Show in Editor. This will give you a new text document in the Organizer window and an empty Text Editor window will pop up.
  2. Try to find the actors of the Access Control system by studying the textual requirements in Example 604. For information on how to find actors, see "Finding Actors" below.
  3. List the actors by name in the newly created textual document together with a brief description of the actor's role when interacting with the system.
  4. Mark the actors in the ActorsList as endpoints in the same way as you did in "Creating Textual Endpoints" .
  5. Save the document giving it the name ActorsList.txt.

Finding Actors

You will find actors by studying the textual requirements. Useful questions to ask are:

  • Which users will need services from the system to perform their tasks?
  • Which users are needed by the system to perform its tasks?
  • Are there any external systems that use or are being used by our system?

In practise, the activity of defining actors should be performed iteratively. Try to find as many of the actors as possible now. If you do not believe you found them all, start creating some MSC use cases (as having done some MSCs often makes it easier to determine the actors). Then go back and complete the list of actors.

In our case with the Access Control system we find that an employee, who daily interacts with the system, is an obvious candidate for the list of actors. Also, considering the third question above, it is obvious that the management system is being used by our system and therefore should be added to the list. The third actor, the door, may not be so easy to find at a first glance, but when you have created the MSCs it will become more evident that the door is an actor as well. The door's interaction with the system consists of notifying the system every time it is opened or closed.

The example below shows a part of the list of actors.

Example 606 : Part of a list of Actors

Employee - Someone who needs to enter and exit the office. To enter the office, an employee must have a registered card and (depending on the current security level) a corresponding personal code. To exit, the employee must press an exit button to unlock the door.

ManagementSystem - The management system starts and maintains the Access Control system. All changes to the database are handled by the management system. The management system is run by a system operator.

...

Creating a List of Use Cases

When you have defined the set of actors it is time to describe the way they interact with the system, which is done in use cases. The first step is to create a list of all use cases. The list of use cases should list the use cases by name together with a short description.

  1. Add a new plain text document in the RequirementsUseCaseModel module. Name it UseCaseList and set the toggle button Show in Editor. Press OK.
  2. Try to find the normal use cases and list them in the newly created textual document. For information on how to find use cases, see "Finding Use Cases" .
  3. To each use case, add a general one-sentence description of its functionality.
  4. For each normal use case, examine which exceptions that can occur and state these exceptions as well in the list.
  5. Mark the use case names in the UseCaseList as endpoints.
  6. Save the document giving it the name UseCaseList.txt.

Finding Use Cases

It is often quite easy to identify use cases by looking at the purpose of the system. To verify that you have identified most of the important use cases you should:

  • look at the list of actors, and, for each actor,
  • identify the tasks that the actor should be able to perform and the tasks which the system needs the actor to perform. Each such task is a candidate for a new use case. It is often very useful to check the textual requirements document for verb phrases (or you could look directly in the DataDictionary to see which verb phrases that have been stated as important); these are possible candidates for use cases.

Start with the employee actor and try to determine which actions he or she needs to perform. There are different ways to enter an office, either using a card or using both a card and a code. Both ways are obvious candidates for the use case list. Also, the employee must be able to exit the office, this will be yet another use case.

The Management system must inform the Access Control system when there has been a change in security level. This will be our fourth use case.

As for the door actor, the task of notifying the system when a door is opened and closed can be included in the enter/exit office use cases. You should always try to make the use cases as complete as possible, that is, make one complete use case instead of several minor ones.

When you have found the normal use cases, refine them by examining the exceptions that are possible for each use case. Look in the textual requirements document and try to find the exceptions that can occur.

In the case where an employee enters the office, the first thing that can go wrong is that there is a connection failure between the entrance and the central controller. Other possible things that can fail are that the card is invalid, the code is wrong, the time between consequent keystrokes when typing the code is too long, and, finally, the door is never opened even though it was unlocked. All these exceptional cases can be found by studying the textual requirements thoroughly.

The example below shows a part of the use case list.

Example 607 : Part of a Use Case List

Normal Cases:

Enter_Office_With_Card - Describes the interaction between an employee and the Access Control system when the employee wants to enter the office through a door with security level two.
Enter_Office_With_Card_And_Code - Describes the interaction between an employee and the Access Control system when the employee wants to enter the office through a door with security level three.
Exit_Office - Describes the interaction between an employee and the Access Control system when the employee wants to exit the office.
...

Exceptional Cases:

Exc_No_Connection
Exc_Invalid_Card
...

Creating a Textual Use Case

Now that we have a list of the actors to the system as well as a list of use cases, we can start to create a more detailed description of the use cases. A textual use case consists essentially of natural text structured into a number of text fields, see "Describing a Textual Use Case" . In this exercise we will only create one textual use case, as creating them all takes too much time. The use case we will focus on throughout the rest of the tutorial is the one where an employee enters an office with both a card and a code.

  1. Add a new textual document in the RequirementsUseCaseModel module and name it Enter_Office_With_Card_And_Code.
  2. Try to create the textual use case consisting of the fields described in "Describing a Textual Use Case" .
  3. Create endpoints of the textual use case name (for consistency use exactly the same name as you used in the list of use cases) and of the actors involved in the use case.
  4. Save the document giving it the name Enter_Office_With_Card_And_Code.txt.

Describing a Textual Use Case

A textual use case should consists of the following fields:

  • Name: The name of the use case.
  • Actors: A list of the actors involved in the use case.
  • Preconditions: A list of properties that must be true for this use case to take place.
  • Postconditions: A list of properties that are true when the use case is finished.
  • Description: A textual description of the normal sequence of events that describe the interaction between the actors and the system.
  • Exceptions: A list of exceptional interactions that complement the normal flow of events described in the Description field. If an exception leads to different postcondition properties compared to the normal sequence this should be noted.

The description field should thus describe what happens when everything is going as expected. No exceptions should be considered here. They are not described until the exceptions field.

The example below shows a textual description of the use case "Enter office with card and code."

Example 608 : A Textual Use Case

Use case name: Enter_Office_With_Card_And_Code

Actor: Employee, door

Preconditions: System is initialized, security level three is set, and the door is closed and locked. The display displays "Enter card".

Postconditions: The door is closed and locked again.

Description: An employee enters a card into the card reader. The display displays "Enter code". The employee enters a code consisting of four digits using the keypad. The door is unlocked and "Please enter" is displayed. The employee opens the door, enters the office and closes the door again. The door is locked and "Enter card" is displayed.

Exceptions:

- If the employee enters an invalid or unregistered card, "Invalid card" is displayed for three seconds and then "Enter card" is displayed.

- If the time between consequent keystrokes when typing the code exceeds three seconds, everything is interrupted and "Enter card" is displayed.

- If the employee types the wrong code, "Wrong code" is displayed for three seconds and then "Enter card" is displayed.

- If the employee does not open the door within ten seconds after it has been unlocked the door is locked again and "Enter card" is displayed.

- If there is no connection between the entrance and the central controller and a card is entered, then the text "Connection failure" is displayed for three seconds and then "Enter card" is displayed again.

Creating an MSC Use Case

The second notation for use cases used in SOMT is MSCs. Creating MSCs for all the use cases and their exceptions takes too much time in this tutorial. Therefore you will concentrate on the use case corresponding to the textual description you just created, Enter_Office_With_Card_And_Code, and one of its exceptions, when an employee enters an invalid card.

  1. Select the module RequirementsUseCaseModel and choose Add New. In the Add New dialog, set the MSC radio button. Name the document Enter_Office_With_Card_And_Code and set the Show in Editor toggle button.
  2. In the MSC Editor, try to create the MSC. Look at the textual description of the use case and describe it by means of the notations defined for MSCs. Also, make references to exceptions at the points where these can occur. Figure 715 shows an example of the complete MSC.
    • Each actor should be represented by a separate instance. The Access Control system itself should also be represented by a separate instance.
    • Actions, displayed messages, etc. should be drawn as MSC messages between the instances.
    • An exception is drawn by adding an MSC reference symbol, located last in the MSC Editor's symbol menu. An MSC reference symbol is a reference to another MSC, described in a separate MSC diagram. The symbol is added to one of the instance axes. By convention, MSC exceptions are named "exc" followed by the name of the exception. To connect the symbol to all three axes, select Connect from the Edit menu. Press the Global button to connect the reference symbol to all axes.
  3. Save the MSC diagram giving it the name Enter_Office_With_Card_And_Code.msc.

Figure 715 : An MSC example

  4. Create a new module in the Requirements Documents chapter in the Organizer. Name the module MSC_Exceptions_ReqA.
  5. Add a new MSC document to the newly created module in the Organizer and name the document Exc_Invalid_Card.
  6. In the MSC Editor, try to create the exception, i.e. describe what happens when an employee has entered an invalid card.
  7. Save the diagram giving it the name Exc_Invalid_Card.msc.

Figure 716 : An MSC exception example

  8. In the Organizer view, select the MSC Exc_Invalid_Card and then choose Associate in the Edit menu. The Associate dialog appears.
  9. Choose to associate the Exc_Invalid_Card MSC with the Enter_Office_With_Card_And_Code MSC as it is an exception to this use case.

The Requirements Documents chapter should now look like in Figure 717.

In reality you repeat the steps above for all the use cases found and associate each one of them with its exceptions. In this tutorial, however, we will not create the entire use case model as that would take too much time.

Figure 717 : The Requirements Documents chapter

Now, when we have our use cases and a data dictionary we will continue the activity with producing a requirements object model. In practise, you should work with all the models in parallel. The activities in SOMT are not supposed to be performed in a sequential order, rather, producing the models is a highly iterative process.

Creating the Requirements Object Model

The requirements object model is intended to capture the objects, the relations between these objects and other concepts of the real world that are of importance for the application we intend to build. There are different types of concepts that can be described in this model. The two major diagram types show the logical structure of the data and information and the context of the system.

Relations between objects in the model will be expressed through associations, aggregations and inheritance.

Creating a Requirements Object Model

Now you should create the requirements object model.

  1. In the Organizer, select the RequirementsObjectModel module and choose Add New. In the Add New dialog, set the UML radio button and make sure the Object Model option in the UML option menu is set. Name the new document LogicalStructure and set the toggle button Show in Editor. This will pop up an empty OM Editor window.
  2. Try to find the objects, see "Identifying the Objects" .
  3. Enter the classes found into the object model diagram in the OM Editor and give them a suitable name. As you can see, every class is automatically marked as an endpoint.
  4. Relate the classes by means of associations, aggregations and inheritance, see "Identifying the Relations" .
  5. Consider if multiplicity is needed on any of the associations and if so, add it. (Double-click a line to bring up the Line Details dialog.)
  6. To increase the readability of the model, name the associations or attach role names to the classes. The diagram should look something like in Figure 718 when you are finished.

Figure 718 : The logical structure

  7. Save the diagram giving it the name logicalstructure.som.
  8. Add yet another object model to the RequirementsObjectModel module in the Organizer. Name it ContextDiagram.
  9. In the diagram, show the system and the external actors interacting with it. Use collapsed class symbols (select Collapse from the Edit menu). The classes are automatically marked as endpoints.
  10. Clear the endpoint on the Access_Control_System class as we will not need this. (Select Clear Endpoint from the Link submenu in the Tools menu.)
  11. Save the diagram giving it the name contextdiagram.som.

Figure 719 : The Context diagram

Identifying the Objects

The main input sources to the requirements object model are the textual requirements, the use case model and the data dictionary. Other sources of information are domain experts, textbooks etc.

A classical way to find the objects is to study the textual requirements and note all nouns (or look directly in the nouns section in the data dictionary). If a particular noun appears in many places, the concept is probably important for the problem domain and should be modeled in the requirements object model.

The use cases are also helpful for finding the objects. They define the actors that interact with the system and these are obvious object candidates. Other likely object candidates are the entities that are transported in to or out of the system. The use cases are helpful in identifying these concepts as well.

The requirements object model should at least describe all concepts that are visible on the outside of the system. This includes all physical entities that a user can see as well as the knowledge a user must have to use the system. It is, however, not only concepts outside the system that should be modeled in the requirements object model. Concepts inside the system that are so obvious that we know of them already at this stage should be dealt with as well. In our Access Control system, for instance, it is quite easy to see that the system itself is built up of a central control and a number of entrances, each having its own local control. Therefore, in the requirements object model, we do not model the heart of the system as one class, but as two communicating classes.

Identifying the Relations

The information sources when identifying relations between objects are the same as when identifying the objects. Look for relation phrases in the textual requirements (or use the data dictionary as an information source). You may also take a look at each object and ask the questions:

  1. What services does the object provide?
  2. Does the object need services from other objects to complete its services?

If the object needs services from other objects, identify these objects and model the relations in the object model.

There are three different types of relations, described below.

The Association Relation

The association relation describes how different classes relate to each other by means of information exchange.

Figure 720 : An Association relation

The Aggregation Relation

The aggregation relation is a special case of the association relation and it describes a "consists of" relation. For example: a document consists of paragraphs.

Figure 721 : An Aggregation relation

The Inheritance Relation

The inheritance relation describes an "is a" relation. For example: a car is a vehicle.

Figure 722 : An Inheritance relation

Entity Match

Now it is time to do some consistency checks between the created models. When you do an entity match you check that all entities in one model have matching entities in another model.

  1. Open the Link Manager. The window popping up shows all endpoints from the models you have created during the requirements analysis activity.
  2. To be able to perform an entity match you must be in entity mode (i.e. not in endpoint mode). Press the Show endpoints or entities button in the Tool bar to change to entity mode. (The view in the Link Manager window will look just the same, since one entity corresponds to exactly one endpoint in all our models.)

The first thing we will check is that all important concepts in the textual requirements model are described in the data dictionary.

  3. Choose Consistency Check in the Tools menu. The Consistency Check dialog appears and you are asked to choose between a link check and an entity match. Set the entity match radio button and press Continue.
  4. A new dialog appears and you are asked to select the documents representing the from group. Select the TextualRequirementsModel module and press Continue. (As you can see, the text document in the module is also selected when you select the module.)
  5. Yet another dialog appears asking you to select the documents representing the to group. Select the DataDictionaryModel module and press Check.
  6. The Link Manager window will show the result of the entity match in a new consistency view. Entities from the from group are shown as normal endpoints and entities from the to group are shown as dashed endpoints. The links shown are temporary links created by the Link Manager to indicate matching entities, see Figure 723.

Figure 723 : Matching entities

  7. As you can see, if you scroll through the Link Manager window, all the concepts from the textual requirements have a matching entity in the data dictionary. (An endpoint from the to group without a matching link from it would have indicated that no corresponding entity could be found in the to group.)

There are a few more consistency checks which you can perform at this point:

  • Check that all entities in the requirements object model are described in the data dictionary.
    • Let the RequirementsObjectModel module form the from group and the DataDictionary module the to group.
    • As you can see from the result all concepts but the four different security levels have been described in the data dictionary.
  • Check that all important concepts in the textual use cases are described in the data dictionary and in the use case list. Important concepts in a textual use case are the actors and the use case name. The actors should be described in the data dictionary and in the actors list. The use case name should be described in the use case list.
    • In this case the from group will be the textual use case, Enter_Office_With_Card_And_Code, and the to group will be the DataDictionary, the ActorsList and the UseCaseList. (You can select any number of individual documents in the list, not only modules.)
    • The result shows that the use case name was found in the UseCaseList and that the actors were described both in the data dictionary and in the list of actors.
  • Check that all actors in the use cases are modeled in the context diagram and vice versa.
    • First, the Actorslist will form the from group and the Context Diagram will form the to group, then we will do another entity match with the groups vice versa.

Creating Implinks

Now that we know that all our models are consistent, it is time to add the implinks. Implinks are used to enable traceability between the models.

We will start with creating implinks from the concepts in the textual requirements to the requirements object model, in particular the logical structure diagram.

  1. Open the Link Manager by selecting it in the submenu Link in the Tools menu if it is not already open.
  2. Make sure the window shows endpoint view, not entity view or consistency view. If necessary, press the Show endpoint or entities quick button.
    In the Link Manager window you see all the endpoints from the different models in the requirements analysis activity. If you scroll to the very end of the window you can see how many endpoints and links you have in your system. There should be no links at this point.
  3. To check that all endpoints are present in the Link Manager window, choose Check Endpoints in the Tools menu.
  4. The Check Endpoints window will pop up showing if any previously unknown endpoints were found. If so, select these and press Add. Then press Continue.
  5. Another version of the Check Endpoints window pops up showing if any invalid endpoints were found. In such case you can choose to delete these by pressing Delete. Press OK when you are done and want to close the dialog.
  6. To be able to create the implinks between the textual requirements and the classes in the logical structure you only need to see the endpoints from these diagrams in the Link Manager window. You do not have to see all the other endpoints. Therefore, choose Filter in the View menu.
    The Filter dialog pops up and you can choose to set filter settings for links, endpoint or documents, by selecting from the option menus.
  7. Choose to set the filter for documents and select that the only documents to be shown should be the textual requirements and the logical structure documents.
  8. Press Apply and then Done.
  9. In the Link Manager window, highlight the endpoint Text Office by first selecting the endpoint and then clicking the Highlight quick button in the tool bar. The endpoint is highlighted with a frame around it.
  10. Create an implink to the Class Office by first selecting the class and then pressing the Create Link quick button in the tool bar. The Create Link dialog will open.
  11. Name the link Implementation Link and press the Create button. A link from the text "office" to the class Office is created.

The rest of the links between the textual requirements and the object model diagram are created in a similar way. You can do this if you want, or go to the next exercise, where this has been done, and check out the result.

Links from the UseCaseList to the different MSCs and their exceptions should also be created. You cannot do this here however, as you have not created all the use cases.

What we aim at here is to create links from the textual requirements, through the object models of the different activities, to the SDL design. Simultaneously we want to create links from the list of use cases, through the use case models in the different activities, to the SDL design. The result of this will be that we can trace a design decision backwards to requirements through either object models or use case models.

Summary

After having completed an entire requirements analysis, the Requirements Document chapter the Organizer view should look like in Figure 724.

Figure 724 : The entire requirements analysis document structure


Performing the System Analysis

Figure 725 : Overview of the SOMT process

What You Will Learn

  • To identify and present the logical architecture of a system which includes refining the object model from the previous phase
  • To refine use cases from the previous phase
  • To use the Paste As mechanism

Introduction to the Exercise

In this exercise you will perform the system analysis activity. The purpose of the exercise is to outline a logical model of the Access Control system. This model will fulfil the requirements that were identified in the requirements analysis. In other words, the purpose of this activity is to identify the objects that are needed in the Access Control system and the services these objects should provide.

Producing a complete system analysis structure takes too much time. Thus, you will only perform parts of every step necessary to produce the complete structure.

The input to the system analysis activity is a complete requirements structure with the two main models:

  • requirements object model
  • requirements use case model

The output from the system analysis activity are the two models:

  • analysis object model
  • analysis use case model

These two models should be created in parallel through a number of iterations.

Preparing the Exercise

  1. Open the system file somttutorial/SysA/accesscontrol.sdt (on UNIX), or somttutorial\sysa\accesscontrol.sdt (in Windows).
  2. Check that the Source directory is set to somttutorial/SysA/ (on UNIX), or somttutorial\sysa\ (in Windows).

What you see in the Organizer window is a complete requirements analysis structure with all implinks made.

Creating the Analysis Object Model

The analysis object model is a refinement of the requirements object model. However, when transferring from the requirements analysis to the system analysis you change the focus.

During the requirements analysis the focus is on understanding the problem and the problem domain. In the system analysis the focus is to model a solution and to understand the logical structure of the system that will be the solution to the stated problem. This change of focus should be reflected by the analysis object model.

Little emphasis should be put on implementation aspects during the system analysis activity. Questions regarding the implementation of the solution will very likely hide our actual problem.

A glance at the headlines may give you the impression that the activity of creating the analysis object model is a sequential activity, but it is not. You will probably not first add all the necessary classes, then the relations, and finally specify the attributes and operations. This is, however, the way the text is structured here to make it readable and to highlight the important tasks of the activity.

Creating a Logical Architecture

Now it is time to create the logical architecture diagram.

  1. Select the AnalysisObjectModel module in the System Analysis Documents chapter in the Organizer.
  2. Add a new object model diagram and name it LogicalArchitecture.
  3. Open the LogicalStructure diagram from the previous activity as well as the new LogicalArchitecture diagram in the OM Editor.

Adding Classes to the Logical Architecture

Now you should start adding classes to the logical architecture diagram. For information on how to find the classes, see "Finding Classes" .

Several of the classes in the requirements object model can be transferred as-is to the analysis object model. The provided Paste As mechanism lets you transfer objects from one model to another while automatically creating implinks between the objects in the two separate models. This mechanism should be used here, see below.

  4. Select the class CentralControl in the LogicalStructure diagram and choose Copy in the Edit menu.
  5. Go to the LogicalArchitecture diagram by selecting it in the Diagrams menu.
  6. Choose Paste As in the Edit menu. The Paste As dialog is opened.
  7. Set the option menu to Class and see to it that the Create link toggle button is set. Press the Paste As button.
  8. Select where in the LogicalArchitecture diagram you want to place the CentralControl object.

Now you have created a class named CentralControl in your LogicalArchitecture diagram. The class is connected with an implink to the CentralControl class in the LogicalStructure diagram. The link is indicated by the filled triangle on the class symbol.

  9. Repeat the procedure above with the class Entrance but name the new class EntranceUnit as this is a more descriptive name.
  10. The classes Cardreader, Keypad, Display and ExitButton are obvious interfaces to our system and, also, parts of an EntranceUnit. Repeat the procedure above with these classes. As it is often useful to name objects according to their function, give the new classes names of the form xxxInterface.

One class in the requirements object model may result in several classes in the analysis object model. One reason may be that the class provides so much functionality that splitting the class into several smaller may be convenient. Another reason may be that a class identified in the requirements object model needs services from other, not yet introduced classes. Consequently these classes should be introduced at this point of the development process.

In practice, the actions in the two cases above are the same. The newly introduced classes should be linked to the original class in the requirements object model. In our example this is the case with the class Door. In the requirements object model we have one single class representing the door. Further analysis, however, shows that the door object includes both a door lock as well as a door sensor. This aggregation structure should be shown in the analysis object model. See section "Finding Relations" .

  11. Copy the class Door in the LogicalStructure diagram.
  12. Paste it three times as a class in the LogicalArchitecture diagram and see to it that the implinks are created at the same time. Name the new classes DoorUnit, DoorLockInterface and DoorSensorInterface respectively.

Now look at the classes you have so far in the LogicalArchitecture diagram. Think about the tasks of the different objects. As you can see there is no class that can handle the logic, that is, an object that is responsible for what happens at an entrance. Therefore, you should add such an object and name it EntranceCtrl, see below. The EntranceCtrl will be a part of the EntranceUnit.

  13. Copy the class Entrance from the LogicalStructure diagram.
  14. Paste it as a class in the LogicalArchitecture and rename the class, giving it the name EntranceCtrl.
  15. Also, copy and paste the SecurityLevel class and its subclasses.

Classes in the requirements object model that only exist outside the system border or classes that do not provide any necessary services should not be transferred at all to the analysis object model.

Finding Classes

Useful sources where you can find objects that may be included in the analysis object model are:

  • the requirements object model
  • interfaces that the system will have to the environment
  • use cases

When you intend to transfer objects from the requirements object model to the analysis object model, consider the following to validate each requirements object:

  • Decide if the system needs information about the object to fulfill its task.
  • If the answer is "yes" then add the class to the analysis object model.

Another useful way to find the objects is to examine which interfaces the system needs. Often the application area itself makes it obvious what interfaces must exist. To find the interface objects, go through the list of actors and, for each actor, decide which interfaces that are needed to the system.

The use cases from the system analysis activity are also a useful source for finding the objects. The problem is that we have not created these use cases yet. As stated before, the work done in each activity is often done iteratively. This is a typical situation where an iteration is needed as some objects in the analysis object model may not be found until we have created and inspected the analysis use case model.

When you have created the MSCs you should examine them to check which interface objects that are involved and which internal objects that are modified. Also, check if there is a control object that might handle the logic of the use case or if there is a need to introduce such an object in the analysis object model.

Adding Relations to the Logical Architecture

When you have identified all classes it is time to add the relations. For information about how to add relations, see "Finding Relations" .

In our Access Control system example, most of the relations from the requirements object model can be preserved.

  1. Connect the CentralControl to the EntranceUnit with an association. Add multiplicity to the association. The CentralControl may be connected to several EntranceUnits but the Access Control system has only one CentralControl.
  2. Connect the EntranceUnit to the DoorUnit with an aggregation. One EntranceUnit consists of only one DoorUnit.
  3. The DoorUnit consists of a DoorLockInterface and a DoorSensorInterface. Add aggregations from the DoorUnit to the DoorLockInterface and to the DoorSensorInterface.
  4. Connect the rest of the classes you have added with necessary associations, aggregations and generalizations. Also consider if multiplicity is needed or not.

Finding Relations

Useful sources that may assist the process of finding relations are:

  • the requirements object model (preserving and modifying existing relations)
  • analysis use case model
  • textual requirements

The process of finding new relations and verifying old ones are closely related to the process of creating the analysis use case model. It is mainly a question about which other objects the object needs to know about to be able to provide its services. Also generalizations and aggregational dependencies have to be considered, see "Identifying the Relations" .

Adding Attributes to the Logical Architecture

Now we have come to the point where it is time to add the attributes. For information on how to find the attributes, see "Identifying Attributes" .

There are not many classes in our LogicalArchitecture diagram that need any attributes. In fact there is only one, the class Display. This class must be able to display different text messages depending on the situation at hand. Therefore:

  1. Define Text to be an attribute of the class DisplayInterface.

Identifying Attributes

Attributes can be found in:

  • the requirements model (keeping existing attributes)
  • the textual use cases
  • the textual requirements

Attributes describe a property of an object and often correspond to nouns. For example, possible attributes of an object "Person" may be eye color, weight, shoe size, and so on. Attributes that may describe a vehicle are owner, color, current speed, current gear, and direction.

Adding Operations to the Logical Architecture

The last thing to add to the logical structure object model are the operations. For information on how to find the operations, see "Identifying Operations" .

Add the operations Open, Close, Lock and Unlock to the assembly class DoorUnit. This implies that you also must add the operations Open and Close to the class DoorSensorInterface and Unlock and Lock to the class DoorLockInterface.

  1. Select the class DoorUnit.
  2. Click on the operations section in the class.
  3. Add the operations Open, Close, Lock and Unlock.
  4. Repeat the procedure for the classes DoorLockInterface and DoorSensorInterface adding their respective operations.
  5. Continue to add the missing operations of the other classes in the diagram. When you are finished, your diagram should look something like in Figure 726.
  6. Save the diagram.

Figure 726 : The logical architecture

Identifying Operations

Sources that may support the identification of operations are:

  • the requirements object model
  • the analysis use case model (the messages in the MSC diagrams)
  • the data dictionary (the description of the objects)

By studying the responsibilities of each object is it possible to identify a set of operations that will provide the services assigned to the object.

Let one operation perform only one task. However, the class should not contain too many public operations. A large public interface of a class may indicate that the object is assigned too many responsibilities. Instead the object should probably be split and the responsibilities of the object should be distributed between several objects.

The easiest way to find the operations is probably to look at the MSC messages in the system analysis use cases. The messages can often be considered as operations in the analysis object model. A message received by an instance in an MSC corresponds to an operation on the corresponding class. Note that the operations on the classes representing subsystems define the interface of this subsystem and should often also exist as operations on some of the objects within the subsystem.

Creating an Information Diagram

Now it is time to create an information diagram. This diagram describes the concepts outside the system that the system must know of to fulfill its task. In our Access Control system example, Card and Code are two such concepts.

  1. Add a new object model diagram to the Organizer in the module AnalysisObjectModel. Name the diagram InformationDiagram.
  2. Open the LogicalStructure diagram from the previous activity and the new InformationDiagram in the OM Editor.
  3. Select and copy the classes Card and Code in the LogicalStructure diagram and paste them as classes in the InformationDiagram, while automatically creating the implinks.
  4. Consider if any or both of the classes should have any attributes.
  5. Associate the classes with each other.
  6. Save the diagram.

Your diagram should look like in Figure 727 when you are finished.

Figure 727 : The Information diagram

Creating the Analysis Use Case Model

The design of the two models in the system analysis activity, the object model and the use case model, is usually going on in parallel. The models view the Access Control system from two different perspectives, a dynamic perspective and a static perspective.

The analysis use case model shows the dynamic aspects and consists of a set of MSC diagrams. These diagrams may be categorized into two types:

  • Refined requirements use cases
  • Behavior pattern use cases

Refined Requirements Use Case

A refined requirement use case is what it reads like. Each valid use case from the requirements use case model is transferred to the analysis use case model and redesigned and refined to the analysis object model.

The purpose of the refined use cases is to validate whether the analysis object model really implements the requirements. At the same time the analysis use case model is an important source of information for identifying operations on the classes in the object model.

In the analysis use case model, the use cases are documented preferably using MSCs. MSC diagrams are more formal and correspond better to the object model than textual use cases.

Each instance in the MSC diagram corresponds to an object or subsystem in the analysis object model. The level of abstraction you choose is a trade-off between detail and clarity.

An object which encapsulates interfaces and just transfers the calls to other objects without adding much functionality may be omitted, but objects providing crucial functionality should be part of the MSC.

Creating a Refined Requirements Use Case

Now you should create an analysis use case of the Enter_Office_With_Card_And_Code use case from the requirements analysis activity.

  1. Create a new MSC diagram in the AnalysisUseCaseModel module and name it Enter_Office_With_Card_And_Code_SysA.
  2. Open the requirements use case Enter_Office_With_Card_And_Code. The system analysis use case is based on the requirements use case and it is therefore useful to use the latter as a reference (using copy and paste).
  3. Create the MSC on subsystem level, that is, replace the original system instance with instances of EntranceUnit and CentralControl.
  4. Create endpoints of the three instances in the MSC diagram. (Select Create Endpoint from the Link submenu in the Tools menu.)
  5. For each message in the requirements use case decide which instances that exchange that particular message in the analysis use case. Also consider which additional messages you need to add. All message exchanges inside the system that we did not consider in the requirements use cases have to be added at this point. Also, make references to exceptions at the points where these can occur.
  6. Replace the four ReadDigit signals with an MSC reference symbol referring to the MSC ReadCode. ReadCode is a behavior pattern which you will create later, see "Behavior Pattern Use Cases" .
  7. Save the diagram.
  8. In the Organizer, create an endpoint out of the newly created MSC diagram. (This is done in the same way as in the editors.)
  9. Open the Link Manager and connect this endpoint to the Enter_Office_With_Card_And_Code MSC from the requirements use case model. Name the link Implementation Link.

The created MSC should look like in Figure 728.

Figure 728 : A system analysis MSC use case

The rest of the requirements use cases and their respective exceptions are refined in a similar way. This will not be done in this tutorial because that would take too much time.

Behavior Pattern Use Cases

A behavior pattern is a detailed use case that may be used to examine special communication patterns in detail. A behavior pattern is part of an ordinary use case and most often several use cases share a behavior pattern. A use case may include none or several behavior patterns.

Behavior patterns let refined requirements use cases be presented in a higher abstraction level, making these less complex and easier to understand. By focusing use cases on special parts of the system it is easier to understand and maintain the requirements on the involved objects.

Creating a Behavior Pattern

The refined use case that you just created was created on subsystem level. With the help of behavior patterns we can describe what really happens at a certain point in the use case, i.e. which objects that interact and the messages that they exchange. In our case, where we will create a behavior pattern for the task of reading a code, we have to replace the MSC instance EntranceUnit with the MSC instances KeypadInterface and EntranceCtrl.

  1. Create a new Organizer module in the System Analysis Documents chapter. Name it BehaviorPatterns.
  2. In the MSC Editor, create the behavior pattern ReadCode, see Figure 729.
  3. Save the diagram using the name Behavior_Pattern_ReadCode.
  4. In the Organizer, associate the behavior pattern MSC with the use case MSC which it really is a part of. That is, associate it with Enter_Office_With_Card_And_Code_SysA.

Figure 729 : A behavior pattern example

The System Analysis Documents chapter should now look like in Figure 730.

Figure 730 : The System Analysis Documents chapter

Requirements Traceability

One important aspect in this activity is the relation between the models created here and the models created in the requirements analysis activity. We want to be able to check:

  • That all requirements have been implemented
  • Which system analysis object that implements a certain requirement
  • Which requirement that is implemented by a certain object in the analysis object model

The means to check the issues above is through consistency checks. There are two types of consistency checks:

  • Entity matches
  • Link checks

We will start with a link check and then we will perform an entity match.

Link Check

The first thing to check is that all entities described in the logical structure in the requirements object model are either represented in the analysis object model or not really needed by the application.

  1. Open the Link Manager. A link check can be performed in both entity and endpoint view, so it does not matter which view you have in the window.
  2. Choose Consistency Check in the Tools menu to perform a link check.
  3. The Consistency Check dialog pops up asking you to select the documents representing the from group. Select the LogicalStructure object model and press Continue.
  4. Yet another Consistency Check dialog appears, now asking you to select the documents representing the to group. Select the AnalysisObjectModel module (this will also highlight the documents in the module) and press Check.
  5. The Link Manager will show the result of the link check. You can see that all entities from the requirements, except the system operator, employee, database, management system and office, are represented in the analysis object model. These are concepts on the outside of the system and, thus, not really needed by the application.

To follow links from one model to another we use the Traverse command. To see how this works follow the steps below:

  6. Go to the LogicalArchitecture diagram in the OM Editor and select the class CentralControl.
  7. In the Link submenu in the Tools menu, choose Traverse.
  8. The OM Editor will open the LogicalStructure diagram and the CentralControl class will be selected. Go yet another step backwards by choosing Traverse in this diagram.
  9. The Traverse Link dialog pops up asking you to select a link to traverse. The class is the one we just came from so you should choose the text fragment and press Traverse Link.
  10. The Text Editor opens and the endpoint centralcontrol is selected.

In the same way we traversed from system analysis to requirements here, you can also traverse from the requirements to system analysis. Try this!

Entity Match

Now it is time for another consistency check. This time you should check that the instances in the MSC diagram correspond to classes in the object model or to actors that interact with the system.

  1. See to it that you have entity view in the Link Manager window. If not, press the Show endpoint or entities button in the tool bar.
  2. Choose Consistency Check in the Tools menu. Set the entity match radio button in the Consistency Check dialog and press Continue.
  3. As a document representing the from group, select the MSC Enter_Office_With_Card_And_Code_SysA.
  4. As documents representing the to group, select the AnalysisObjectModel module and the ActorsList.
  5. The result shows that all MSC instances really are described in the analysis object model or in the list of actors.

Summary

After having completed an entire system analysis, the System Analysis Document chapter would look like in Figure 731.

Figure 731 : The entire system analysis document structure


Performing the System Design

Figure 732 : Overview of the SOMT process

What You Will Learn

  • To create a design module structure
  • To define the static interfaces in packages
  • To make an architecture definition of the system
  • To make formalized testable use cases
  • To use the Paste As mechanism when transferring from the system analysis activity to the system design activity

Introduction to the Exercise

This is an exercise on system design. In this activity we no longer make use of object models; from now on SDL will be used. You will learn how to map concepts from the analysis object model from the previous activity into an SDL model. Mapping object-oriented concepts to SDL concepts forces you to make several design decisions. Support for these design decisions is provided through the Paste As mechanism. This exercise will teach you to make use of this support.

Useful sources for information in the system design activity are the analysis object model and the analysis use case model. The first provides information about the static structure and is useful when structuring the system into units. The latter provides information about the dynamic structure and is useful for the definition of the interfaces between the units.

Major tasks to perform in the system design are:

  • Define the design module structure.
  • Define the static interfaces.
  • Create an SDL system structure as a starting point for the formalization of the architecture.
  • Define the dynamic aspects of the interfaces by a continued use of use cases.

Producing a complete system design structure in the tutorial takes too much time. Thus, you will only perform parts of every step necessary to produce a system design structure.

Preparing the Exercise

  1. Open the system file somttutorial/SysD/accesscontrol.sdt (on UNIX), or somttutorial\sysd\accesscontrol.sdt (in Windows).
  2. Check that the Source directory is set to somttutorial/SysD/ (on UNIX), or somttutorial\sysd\ (in Windows).

What you now see in the Organizer window is a complete requirements analysis and system analysis structure.

Design Module Structure

An important part of the system design is to divide the system into units considering division of work, distribution of functionality and physical distribution.

The purpose of the design module structure is to show the actual source code modules the application will be built from. The most important aspect of the module structure is that it forms the basis for dividing the work load on different development teams.

In our Access Control system example we have two different subsystems, EntranceUnit and CentralControl. It might be the case that these subsystems are implemented by two different teams. Therefore, it seems natural to introduce two different modules, each module being described by the concept of a package. The contents of the packages will not be defined until the architecture definition, the task here is only to identify the modules needed.

The notation that will be used in this tutorial to describe the design module structure is the object model instance diagram where the instances represent the different modules.

Creating a Design Module Structure

  1. Add a new object model diagram to the Organizer in the module DesignModuleStructure and name the document DesignModuleStructure.
  2. In the OM Editor, create a first object instance symbol representing the whole SDL system. Name it using the name SDL_System_Access_Control.
  3. Decide which modules, i.e. packages, the SDL system is to make use of. In this example it might be suitable to introduce two different modules, one for each subsystem. Therefore, create two more object instances and name them CentralControlPackage and EntranceUnitPackage respectively.
  4. Draw associations from the SDL system module to the two new modules. The associations describe that the SDL system uses these two packages.
  5. Create yet another module which will consist of all common types and signals. This package is used by the other two packages and thus also by the SDL system itself. Name the module UtilityTypesPackage and draw the associations. Your diagram should now look like in Figure 733.
  6. Create endpoints out of the three packages. (Endpoints are not created automatically for object instance symbols.)
  7. Save the diagram giving it the name designmodulestructure.som.

Figure 733 : The Design Module Structure

Creating the Architecture Definition

When using SDL to design a system, the architecture is defined by block diagrams which define how the system is decomposed into blocks. The block diagrams are more or less a formalization of the analysis object model.

The first thing we will do when defining the architecture is to define the contents of the packages introduced in the design module structure, see "Defining the Packages" . The UtilityTypesPackage will contain data type declarations that are common to the subsystems of the system. Signals/remote procedures that make up the interface between the subsystems will also be defined in the UtilityTypesPackage. The other two packages, CentralControlPackage and EntranceUnitPackage, will contain block types and the signals/remote procedures that make up the interface to the particular block. If you have many signals it is often useful to structure these into signal lists.

The basic mechanism used in SOMT when going from analysis to design is the Paste As mechanism. This is used here when defining the signal interfaces, the blocks and block types, and, to some extent, the data type declarations.

The second task to do when creating the architecture definition is to define the system by means of SDL block diagrams, see "Creating the SDL System Diagram" .

Defining the Packages

Mapping Object Models to SDL Block Types

You should now define the two block types, CentralControl and EntranceUnit in their respective package using the Paste As mechanism.

  1. Add three new SDL packages to the ArchitectureDefinition module in the Organizer and name them according to the modules in the design module structure.
  2. Open the LogicalArchitecture diagram in the AnalysisObjectModel module.
  3. Select the class CentralControl and copy it.
  4. Go to the SDL Editor and the CentralControlPackage diagram and choose Paste As. The Paste As dialog is opened.
  5. Paste the class CentralControl as a Block Type (use the option menu) and create an implementation link from the copied object to the pasted object at the same time. The link is automatically created by default.
  6. Copy and paste the class EntranceUnit as a block type in the EntranceUnitPackage in a similar way.

Mapping Object Models to SDL Interface Definitions

Now it is time to design the interfaces of the newly pasted blocks. Interface definitions in SDL are defined using signals and/or remote procedure calls. Consequently, this is what is produced when mapping a class to an SDL interface.

Note that the signals that constitute the interface between our subsystems should be described in the UtilityTypesPackage. The rest of the signals, i.e. signals that are not exchanged between the subsystems should be described now. Signals from the environment to the subsystem and signals inside the subsystem are such signals.

  1. Once again, go to the LogicalArchitecture diagram in the AnalysisObjectModel and copy the class EntranceUnit.
  2. Go to the SDL Editor and the EntranceUnitPackage diagram and paste the class as a Text symbol with SDL interface. See to it that an implementation link is created at the same time.
    If you look at the signal definition you see that the ChangeSecurityLevel signal is present. This is a signal exchanged between our two subsystems and, thus, should not be declared here.
  3. Delete the ChangeSecurityLevel signal.
  4. Add the signal parameters. The signals ReadCard and ReadDigit are the only ones that need parameters. See Figure 734.
  5. Save the diagram, giving it the name entranceunitpackage.sun.

Figure 734 : The EntranceUnitPackage

  6. Go back to the LogicalArchitecture diagram and copy the class CentralControl.
  7. Paste it as a text symbol with SDL interface in the CentralControlPackage.
  8. If you look at the signal definition you realize that the ValidateCard, ValidateCode and RegisterEntrance signals are signals exchanged between our subsystems and, thus, should not be defined here. Therefore, delete these signals from the signal definition.
  9. Add a signal parameter of the type integer to the ChangeSystemSecurity signal, see Figure 735.
  10. Save the diagram, giving it the name centralcontrolpackage.sun.

Figure 735 : The CentralControlPackage

It is now time to define the last package, the UtilityTypesPackage. It will define the common data types needed in the subsystems as well as the interface between the subsystems. To define the package you should use the same procedure as above.

  1. Copy the class CentralControl from the LogicalArchitecture diagram.
  2. Paste it as a text symbol with SDL interface in the UtilityTypesPackage diagram.
  3. Delete the signal ChangeSystemSecurity as this has already been defined in the CentralControlPackage (because it is a signal from the environment).
  4. Add signal parameters to the three remaining signals.
  5. Continue with copying the class EntranceUnit and paste it as a text symbol with SDL interface in the UtilityTypesPackage.
  6. Remove all signals that have already been defined, i.e., all but the ChangeSecurityLevel signal.

Note that the Validate commands (ValidateCard and ValidateCode) have to be implemented with signals and not remote procedure calls. This is due to the fact that we must be able to keep track of how long it takes before we get the answer of a validation (to find out if there is a connection failure or not). As a consequence of this, the reply signals to the Validate commands have to be defined here.

  7. Add the two signals ValidateCardReply and ValidateCodeReply to the latest pasted signal definition.
  8. Add signal parameters to the three signals in the definition.

Mapping Object Models to SDL NewTypes

Now it is time to declare the common data types. In our Access Control system example the concepts of card and code are data types common to all parts of the system.

The data type Card is best declared as a SYNTYPE. You will have to do this declaration manually as there is no support in the Paste As mechanism for pasting something as a SYNTYPE. In declaring the data type Code, however, the Paste As mechanism can be used.

  1. Declare the Card concept as a SYNTYPE in the UtilityTypespackage, see Figure 736.
  2. Open the InformationDiagram in the AnalysisObjectModel and copy the class Code.
  3. Go to the SDL Editor and the UtilityTypesPackage and choose Paste As. The Paste As dialog is opened.
  4. Paste the class Code as a NEWTYPE with graphical operator or as NEWTYPE with textual operator (it does not matter which one you choose as the class Code has no operator) and see to it that an implementation link is created at the same time. This will only give you the structure, you have to fill in all relevant information yourself.
  5. As it is a type we are declaring, change the name Code to CodeType. Define the CodeType concept to be an array consisting of four integers (you will have to delete the word STRUCT). The index type of the array should be integer and you will have to define this type too, see Figure 736.
  6. Declare a SYNONYM NbrOfEntrances that will be used to alter the number of entrances we are to control in our system. For now, you can set the value of the variable to 1, see Figure 736.

Before you save and close the diagram you should create an implementation link between the class Card from the InformationDiagram to the definition of Card in this diagram. You have earlier used the Link Manager to manually create links. We will now show how to use the entity dictionary for this.

The entity dictionary is available in all editors and lists all entities in the system, i.e. all modules, diagrams, and endpoints. The main usage of the entity dictionary is to reuse names of entities, but it can also be used to create links.

  1. In the UtilityTypesPackage diagram, select the text symbol containing the Card definition.
  2. From the Window menu, choose Entity Dictionary. The Entity Dictionary window is opened. You will recognize the structure and icons of chapters, modules and diagrams from the Organizer window. In addition, all endpoints are listed beneath the corresponding diagram.
  3. Scroll the Entity Dictionary window until you find the class Card in the InformationDiagram in the AnalysisObjectModel module. Select the icon representing the class Card. (Make sure not to double-click an icon, since that will copy the name of the icon into the current diagram!)
  4. In the Entity dictionary, press the Create Link quick button.
  5. The Create Link dialog pops up. (This is the same dialog as when you created links in the Link Manager.) Set the from radio button, name the link Implementation Link and press Create.
  6. Close the Entity dictionary by using the Close quick button.
  7. Save the diagram, giving it the name utilitytypespackage.sun.

Figure 736 : The UtilityTypespackage

  8. In the Organizer, create endpoints out of the three packages.

Creating the SDL System Diagram

Now you should define the system structure, something which is to be done by means of SDL blocks in a system diagram.

  1. Add an SDL system diagram to the ArchitectureDefinition module in the Organizer and name it AccessControl.
  2. Copy the class CentralControl in the LogicalArchitecture diagram and paste it as a Block in the system diagram. See to it that an implementation link is created at the same time.
  3. Also, copy and paste the class EntranceUnit as a block.
  4. Change the name of the block instances, from CentralControl to theCentralControl and from EntranceUnit to theEntranceUnit. Also, define which block type the blocks are an instance of, see Figure 737.
  5. There will often be more than one entrance in a building and therefore you should define the block theEntranceUnit as a block instance set. (Use the variable NbrOfEntrances defined in the UtilityTypesPackage.)
    The two blocks theCentralControl and theEntranceUnit must be able to communicate with each other as well as with the environment. The next step is to create all necessary channels in the system diagram.
  6. Draw the channels through which the blocks communicate and name them and the gates with suitable names. Also, draw the channels to/from the environment. State which signals that run on a certain channel. To identify the signals consult the AnalysisObjectModel made in the system analysis.
  7. At this point we see the need to introduce a new signal, the EnvDisplay signal which goes from the EntranceUnit to the environment (i.e, to the display hardware). This signal contains information that is to be read by persons in the system environment. The parameter of this signal is Charstring. Define it in the EntranceUnitPackage.
  8. Reference the packages the SDL system makes use of in a USE clause in the top of the diagram. Your system diagram should now look like in Figure 737.
  9. Save the diagram, giving it the name accesscontrol.ssy.

Figure 737 : The Access Control system diagram

Refining the EntranceUnit - Mapping Aggregations

Considering the aggregation structure in the LogicalArchitecture diagram, the block EntranceUnit may be divided into several sub-blocks.

When mapping an aggregation structure from the analysis object model to an SDL diagram, the most common choice is to map the assembly class to a block type. Classes which are part of the assembly class will be mapped to process types, or, if the part class itself is an assembly class, to block types.

The block type corresponding to an assembly class will thus contain processes or blocks.

Figure 738 : Mapping aggregation to a block type

The process types and block types should be placed in a suitable package to enable reuse. The instances of the types should then be placed in the appropriate system or block diagram to form the system.

Mapping Classes to Block Types and Signal Interfaces

  1. Select the class DoorUnit in the LogicalArchitecture diagram. Copy it and paste it as a block type in the EntranceUnitPackage.
  2. Call the Paste As command again. This time, choose to paste the class as a text symbol with SDL interface in the EntranceUnitPackage.
  3. The resulting signal definition contains two signals that already have been defined in the package, namely Open and Close. Therefore, delete these signals in the newly pasted signal definition.

Mapping Classes to Blocks

Now it is time to place a block instance of the DoorUnit block type in the EntranceUnit block type.

  1. Double-click on the EntranceUnit block type in the EntranceUnitPackage diagram. The Edit dialog pops up, press OK. The Add Page dialog pops up. Create a block interaction page.
  2. For the third time, choose Paste As and paste the class DoorUnit as a block in the EntranceUnit block diagram. The block will be named DoorUnit.
  3. Change the block name so it is marked as an instance of the block type according to the SDL syntax. Change the name to theDoorUnit:DoorUnit.

Introducing new Block Types

Since SDL does not allow processes and blocks at the same level you have to create two more block types to be placed in the EntranceUnitPackage. These block types will be used as containers to the remaining classes that will be mapped to processes and process types. Give the first block type the name EntranceInterface. We introduce this block as a generic term for all those classes that represent an interface to the system, i.e. the cardreader, the keypad, the display and the exitbutton. The second block type to be placed in the EntranceUnitPackage is EntranceCtrl.

  1. Copy the class DisplayInterface in the LogicalArchitecture diagram.
  2. Paste it as a block type and as a text symbol with SDL interface in the EntranceUnitPackage.
  3. Rename the block type and give it the name EntranceInterface.
  4. Add a signal parameter called MessageType to the Display signal definition. By using this type for messages the EntranceCtrl does not have to handle strings. This solution makes the system independent of the language used, see "Performing an Iteration" for an example on how this works.
  5. Define the NEWTYPE MessageType, see Figure 739.
  6. Also, paste the class DisplayInterface as a block in the EntranceUnit block diagram. Rename the block and give it the name theEntranceInterface:EntranceInterface.
  7. Using the Entity Dictionary, create implementation links between the CardReaderInterface, KeypadInterface and ExitButtonInterface classes in the LogicalArchitecture diagram and the EntranceInterface block type and block.
    Note that you do not have to paste these three classes as SDL interfaces as their operations have already been defined as signals in the EntranceUnitPackage.
  8. Now, copy and paste the class EntranceCtrl as a block type and as a text symbol with SDL interface in the EntranceUnitPackage.
  9. Delete the signal ChangeSecurityLevel as this already has been defined in the UtilityTypesPackage.
  10. Add signal parameters where they are needed i.e. to the signals ReceiveCard and ReceiveCode.
  11. Also, paste the class as a block in the block type EntranceUnit diagram. Give the block the name theEntranceCtrl:EntranceCtrl.

The EntranceUnitPackage will look like in Figure 739.

Figure 739 : The EntranceUnitPackage

The block type EntranceUnit diagram should now contain three blocks: theDoorUnit, theEntranceInterface and theEntranceCtrl.

Figure 740 : The block Type EntranceUnit

Defining the Communication Structure

Now you should define the communication structures within the block type EntranceUnit. Define the channels needed for the three blocks theEntranceCtrl, theEntranceInterface and theDoorUnit to communicate.

To define the channels in the block type EntranceUnit, follow the steps described below.

  1. Identify necessary channels.
  2. Identify the signals that should be carried by the channels. You get a lot of information from the AnalysisObjectModel here.
  3. Name the channels and the gates.
  4. The complete block diagram for EntranceUnit should look something like in Figure 741.

Figure 741 : The complete structure of the block Type EntranceUnit

When you have completed the architecture definition, the System Design Documents chapter should look like in Figure 742.

Figure 742 : The System Design Documents chapter

Creating the Design Use Case Model

In system design we continue with the use of use cases, this time to define the dynamic interfaces between the blocks in the system.

In our example, the block theEntranceUnit in the system diagram is split into the three blocks, theEntranceCtrl, theEntranceInterface and theDoorUnit. The use cases will consist of the block instances theCentralControl, theEntranceCtrl, theEntranceInterface and theDoorUnit as well as an instance representing the environment.

The use cases must be formalized to a sufficient degree of detail, a level that is consistent with the level of detail found in the static interface definition. Also, the level of detail must be precise enough to make the design use cases act as detailed test specifications.

Formalizing Use Cases

A number of things have to be done when formalizing and refining analysis use cases to design use cases.

  • Check that each MSC instance head has a corresponding block in the architecture definition. The use cases define the dynamic interface between the blocks in the system and thus all blocks have to be represented.
  • The MSC instances corresponding to actors in the system environment should have env_ stated in their instance head before the actual name, e.g. env_Employee.
  • The MSC instances must have names corresponding to block instances as it is the instances that communicate. That is, the name of those instances that have been defined as block types in the SDL package structure must be changed to the corresponding block instance name. E.g. the MSC instance CentralControl can no longer have this name; the name has to be changed to theCentralControl according to the architecture definition.
  • The messages often have to be replaced with a sequence of message exchanges.
  • The MSC messages have to be complemented with parameters according to the definition of signals and remote procedures in the architecture definition. It should not be the name of the parameter that should be added but a value that the parameter can take. Alternatively the parameters can be skipped entirely.

Creating a Formalized Use Case

Now you should begin to formalize and refine one of the use cases from the system analysis.

  1. Add a new MSC diagram to the DesignUseCaseModel module in the Organizer.
  2. In the Add New dialog, set the toggle button Copy existing file. As the file to be copied, select the MSC Enter_Office_With_Card_And_Code_SysA from the system analysis activity. This file can be found in the somttutorial/sysanalysis directory.
  3. In the MSC Editor, rename the instance head Employee to env_Employee and change/add the other instance head names. They should conform to the names used on the block instances in the SDL system diagram and the blocks in the EntranceUnit block diagram in the architecture definition.
  4. For each message, decide if it has to be exchanged with a sequence of messages. If so, add these new messages to the MSC.
  5. Add parameters to the messages. Look at the definition of the signals in the architecture definition and add parameters to those messages that are defined to have parameters. E.g. the message ReadCard should have a parameter consisting of the card. Note that it is not the parameter name Card that is to be used here but an example of a value that the parameter can take, e.g. 123.
  6. Rename the use case and save it under its new name, Enter_Office_With_Card_And_Code_SysD (use Save As).

The exceptions and behavior patterns to this use case must also be formalized.

The other design use cases are created in a similar way. All design use cases should also be connected with implementation links to the corresponding analysis use case and exception. This is done in order to make it possible to check that all use cases from the requirements analysis and system analysis have been refined to design use cases.

Consistency Checks

Now the time has come to performing consistency checks on the models created in system design.

Entity Match

The first thing to check is that the actual modules (SDL packages) used in the design are consistent with the design module structure.

  1. In the Link Manager, choose Consistency Check in the Tools menu and set the entity match radio button. Note that you have to be in entity mode to be able to perform an entity match.
  2. Let the packages in the ArchitectureDefinition form the from group and the DesignModuleStructure module the to group.

The result shows that all packages in the ArchitectureDefinition really are described in the DesignModuleStructure. The consistency view (i.e. the resulting Link Manager window) also shows the contents of the packages. As you can see there are no matching entities to the block references, block types, etc. in the DesignModuleStructure. There should not be any, so just ignore this.

Link Check

By doing a link check we will first check that all objects in the analysis object model are mapped to the architecture definition.

  1. Once more, choose Consistency Check in the Tools menu and perform a link check. It does not matter which view you have in the link Manager window, a link check can be performed in either view.
  2. Let the AnalysisObjectModel form the from group and the ArchitectureDefinition module form the to group.

The result shows that most of the objects from the analysis object model are described as block types and block references in the architecture definition. Many of the objects have also been mapped to an interface definition. The fact that some classes have no corresponding mapping indicates that these classes probably should reside as processes inside some of the mapped blocks. This holds e.g. for the DoorSensorInterface and the DoorLockInterface as well as for the SecurityLevel classes.

At this point you can also select any block or block type in the architecture definition and choose Traverse link. The corresponding class in the analysis object model will then be selected. By choosing Traverse link again you can follow a link all the way back to the textual requirements. It is also possible to follow a link in the other direction, i.e. from the textual requirements via the object models, to the design. Try this!

Summary

After having completed an entire system design the corresponding document structure in the Organizer would look like in Figure 743.

Figure 743 : The entire System Design Documents structure


Performing the Object Design

Figure 744 : Overview of the SOMT process

What You Will Learn

  • To transfer the analysis object model into a consistent object design model in SDL
  • To use the Paste As functionality to assist the task
  • To perform design level testing

Introduction to the Exercise

In this exercise you will perform the object design activity. This activity is, like the system design activity, focused on SDL. However, while the system design is focused on how to structure the architecture and how to decompose the system into blocks, the object design is focused on decomposing the blocks into processes and defining the behavior of the single processes.

The object design activity may be divided into three separate tasks:

  1. Map the classes and associations in the analysis object model to suitable SDL concepts.
  2. Choose a set of essential use cases and define the behavior of the SDL processes and data types that implement these use cases.
  3. Elaborate the design by introducing more use cases and refine the SDL design to handle also these use cases.

Preparing the Exercise

The input to this activity should be a complete requirements analysis, system analysis and system design structure.

  1. Open the system file somttutorial/ObjD/accesscontrol.sdt (on UNIX), or somttutorial\objd\accesscontrol.sdt (in Windows).
  2. Check that the Source directory is set to somttutorial/ObjD/ (on UNIX), or somttutorial\objd\ (in Windows).

Mapping Active Objects to SDL

An object with its own behavior is called active object. The opposite is an object which acts as an information container - a passive object. Active objects are, most often, mapped to SDL process types. Active objects may also sometimes, as was the case in the system design activity, be mapped to block types.

The default choice in the Paste As mechanism is to paste a class copied from an object model diagram as a process type in an SDL diagram.

The attributes of the copied object will be pasted as variables. The operations will be pasted either as signals or as remote procedures of the process type. This depends on whether the operations are synchronous or asynchronous.

Figure 745 : Mapping a class to a process type

Mapping to Process Types

Now it is time to map the classes in the analysis object model that should be mapped to SDL process types. In this example you should map the processes which will reside within the block type EntranceInterface.

The classes which should reside as processes in the block EntranceInterface are: the CardreaderInterface, the KeypadInterface, the DisplayInterface and the ExitButtonInterface.

  1. Copy and paste each class from the LogicalArchitecture diagram as a Process Type in the EntranceUnitPackage.
  2. Open the block type EntranceInterface diagram in the SDL Editor by double-clicking on the corresponding block type symbol in the EntranceUnitPackage. Press OK in the Edit dialog. In the Add Page dialog choose to create a process interaction page.
  3. Copy each class once again and paste it as a Process in the block type EntranceInterface diagram.

When pasting e.g. the class KeypadInterface as a process, the process will get the same name as the class. This name should be changed since the syntax for process instances requires both an instance name and the name of the corresponding process type. The number of statically and dynamically created instances must also be stated.

  4. Name the process theKeypadInterface. The process theKeyPadInterface should have one statically created instance and it should not be possible to create any instances dynamically. The following text should thus be written in the process name area: theKeyPadInterface(1,1):KeyPadInterface.
    (If the Remove Reference Symbol dialog appears, just click OK.)
  5. Change the other three process names too, according to the above.

Now the block type EntranceInterface should contain four processes named: theCardreaderInterface, theKeyPadInterface, theExitButtonInterface and theDisplayInterface.

Figure 746 : The block type EntranceInterface

Defining the Communication Structure

You have already specified the channels to and from the block theEntranceInterface (this was done in the block type EntranceUnit). Now you have to connect the processes within this block with the outside.

Creating a communication structure between processes and the border of the block is made in the same way as creating communication structures between blocks, with one difference. The terminology specifies signal routes instead of channels as the name for the communication structures at this level. However, there is no practical difference between signal routes and channels.

Now, edit the block type EntranceInterface diagram:

  1. Connect each process with the border of the block with a signal route in each direction.
  2. Give the gate of the input signal to each process the name Entry and the other gate the name Exit.
  3. Specify the signals that are transported on each signal route. Consult the system analysis object model and the specification of the block theEntranceUnit to find all signals you should specify.
  4. Connect the signal routes with the channels by specifying the appropriate gate for each signal route.

Figure 747 : The complete structure of the block type EntranceInterface

Defining the Object Behavior

The activity of describing object behavior is a pure SDL design activity. This section is intended to describe how to structure this activity. It will not focus on specific SDL details.

The most important source of information in this activity are the use cases which specify the signal calls and responses to and from the blocks and processes in the system.

The design of the processes is best made iteratively:

  • Select a subset of use cases which describe the most common interaction sequences. Create a basic version of the processes that correspond to these use cases.
  • Second, you should introduce a couple of more use cases. Edit the behavior of the processes making them correspond to the extended subset of use cases.
  • Continue with introducing more use cases. Edit the processes to cover these, until the behavior of the objects correspond to the complete set of use cases.

Using MSCs to describe the use cases makes it fairly simple to identify the states and transitions of the processes. A transition in a process graph is an input signal, often followed by one or more output signals from the actual process in a use case.

If the situation occurs that two use cases are difficult to combine, you should consider to split the process in question into two separate processes, one process for each use case.

An example is the block type EntranceInterface which have a quite complex structure of input and output signals. However, by dividing the block type into four separate processes, each one of these processes becomes fairly simple.

Defining the Basic Behavior of a Process

  1. Take a look at the process type KeypadInterface. You will see that the process has a signal set of only two signals: the input signal ReadDigit and the output signal ReceiveCode.
  2. If you study the MSC diagram Enter_Office_With_Card_And_Code_SysD and the behavior pattern ReadCode you see that four ReadDigit signals generate the output signal ReceiveCode.

Figure 748 : The signal sequence of the process theKeyPadInterface

Creating the behavior of the process out of this information is a quite easy task. Adding the timer, which provides the time-out functionality, will make the first version of the behavior specification of the process complete.
  3. In the EntranceUnitPackage, double-click on the KeypadInterface process type symbol.
  4. In the process type diagram, define the basic behavior of the process.

Figure 749 : Basic behavior of the KeypadInterface process type

Defining the Data of a Process

The processes will of course also need some data containers, entity variables and control variables. The control variables, such as loop counters and flags, are identified during the object design. Entity variables are most often identified during the system analysis and they may be mapped to the process diagrams from the analysis diagrams.

If we take a look at the process theKeyPadInterface again we will notice that we need to introduce a counter to control the number of times a digit will be read before the signal ReceiveCode will be sent. We will also need an index to place the read digit in the correct position of the Code array.

  1. Place a text symbol in the diagram and declare a CodeIndexType named i in the process.
  2. The parameter of the ReadDigit signal is of type integer. Declare a variable named Digit of type integer.
  3. The parameter of the ReceiveCode signal is of type CodeType. Therefore, declare a variable Code of this type.
  4. Change the name of the gate GKeypadInterface to Entry.
  5. Also, add an Exit gate and the signal ReceiveCode going out of the process type.
  6. Declare a timer KeyStrokeTimer with duration 3.
  7. Refine the behavior of the process.
  8. Save the diagram.

Figure 750 : The complete process type KeypadInterface

The rest of the processes in the system are created in a similar way. However, this will not be done in this tutorial.

Design Testing

SDL makes it possible to test the system already during the design. It is possible to simulate an SDL system taking both concurrency and distribution into account. It is also possible to verify requirements specified in MSCs using the Validator.

The MSC diagrams may, with no or little effort, be used directly as input to the Validator. This makes the requirements verification simple and efficient.

Preparing the Design Testing

To be able to test your design you must have a complete system.

  1. Open the system file somttutorial/objdesign/accesscontrol.sdt (on UNIX), or somttutorial\objdesign\accesscontrol.sdt (in Windows). What you see in the Organizer now is a complete system structure. All four documentation chapters representing activities from the SOMT method are complete.
  2. Check that the Source directory is set to somttutorial/objdesign/ (on UNIX), or somttutorial\objdesign\ (in Windows).

Simulating the System

Simulating the system gives information about how different parts respond to certain inputs and how different parts of the system interacts with other parts. Simulating is often done during the object design to test different parts of the system.

The complete system should also be tested using the simulator to verify that the whole system works as it is intended to.

Try to simulate the system AccessControl. Follow the steps below to make a simulator version of the system AccessControl.

  1. Select the system AccessControl in the Organizer.
  2. Choose the Make option in the Generate menu.
  3. In the Make dialog, choose the code generator to be Cbasic.
  4. Choose the standard kernel to be Simulation.
  5. Press Full Make. The system will be automatically analyzed. If there are any warnings you can ignore them. These warnings show up because we have not used all our declared signal lists. As they are just warnings, not errors, you can ignore them.
  6. When the make process is finished, start the Simulator by choosing Simulator UI in the SDL submenu in the Tools menu.
  7. In the SDL Simulator UI window, open the file accesscontrol1_smb.sct (on UNIX), or accesscontrol1_smb.exe (in Windows). Now you can simulate the system, as you have learned in previous tutorials.

Validating the System

When the design of the system is finished you want to verify that the system meets the requirements. This is quite easily done in the SDL suite by using the SDL Validator.

MSCs from the system design are used as input to the Validator.

The requirements use case model is the essential part of the requirements and is often the specification of the system which the customer and the contractor agree upon. Thus, by verifying the system with the MSCs from the system design you are verifying that the system meets the customers requirements.

By making it possible to verify the customers requirements already in the object design and not in a special system design test phase, as in an ordinary design process, you save a lot of effort and time.

Now you should validate some of the MSCs from the system design activity.

  1. Select the system AccessControl in the Organizer.
  2. Choose the Make option in the Generate menu.
  3. In the Make dialog, choose the code generator to be Cbasic.
  4. Choose the standard kernel to be Validation.
  5. When the Make process is finished, start the Validator UI and open the file accesscontrol1_vlb.val (on UNIX), or accesscontrol1_vlb.exe (in Windows). Now the system is ready to be validated.
  6. Press the Verify MSC button and choose the system design MSC diagram enter_office_with_card_sysd.msc which you can find in the directory somttutorial/sysdesign.
  7. If the verification succeeds, you will get the message "** MSC <Diagram name> verified **".

It is perhaps too much work to verify all the MSC diagrams of the system design activity during this tutorial and you may quit when you feel that you have understood the principle of how to verify an SDL system.

If all diagrams can be verified against the system, then it is verified that the system also meets the requirements specified in the beginning of this tutorial.

Consistency Checks

There are mainly two consistency checks that should be performed in the object design activity:

  • Check that all objects from the analysis object model have been implemented in the design.
  • Check that the design model correctly implements the requirements from the design use cases.

The second consistency check is done through design level testing, see "Design Testing" . The first one will be performed through a link check, see below.

Link Check

In our complete Access Control system there are implementation links from the system analysis models to both the system design models and the object design models. This implies that we must check our analysis object model against both these design models to see if all the classes have been implemented in the design.

  • Perform a link check. Let the analysis object model form the from group. The architecture definition and the SDL design model will form the to groups.

The result shows that all classes but the class SecurityLevel have corresponding processes, blocks, signal interfaces or procedures in the design. The SecurityLevel does not have any behavior of its own, it is implemented through its subclasses, and, therefore, the result is just as we want it.

We have now completed the design of the system. It is possible to pick an endpoint in the textual requirements and follow the implink from it, through the object models, to SDL. It is also possible to traverse links the other way, i.e. from design to requirements. Try this!

The use cases are also connected to each other, from requirements to design, as can be seen in the view of the link file in the Link Manager window.

Summary

After having completed an entire object design the corresponding document structure in the Organizer would look like in Figure 751.

Figure 751 : The entire Object Design Documents structure


Implementation

Figure 752 : Overview of the SOMT process

The implementation of the system lies outside the scope of this tutorial. For information about the implementation activity, see the SOMT Methodology Guidelines in chapters 68-76 in the User's Manual.


Performing an Iteration

What You Will Learn

  • To introduce changes to a system in a controlled way
  • To use the implementation links to assist you in the activity

Introduction to the Exercise

During the life time of a system new requirements and changes in existing requirements are almost always introduced. We have to be able to handle these requirement changes and adapt the system to the new situation in a controlled way. We call this process iteration. An iteration may also be planned in advance in, for example, incremental development.

This section will describe the scenario of an iteration caused by the introduction of an additional requirement.

Preparing the Exercise

As input to this exercise we will use the complete Access Control system.

  1. Open the system file somttutorial/Iter/accesscontrol.sdt (on UNIX), or somttutorial\iter\accesscontrol.sdt (in Windows).
  2. Check that the Source directory is set to somttutorial/Iter/ (on UNIX), or somttutorial\iter\ (in Windows).
  3. Create a new chapter and name it Iteration Documents.
  4. Add a new module called AdditionalTextualRequirements to the new chapter.
  5. Add the existing file AdditionalTextualRequirements.txt to the new module.

Studying the Additional Requirements

  • Open the additional textual requirements document if it is not already open. The example below shows the document.

Example 609 : Additional requirements

The system should be able handle the languages English, German and French. One version of the system should handle a specific language and the system should be easily configured to handle a new language.

As stated in the example above, the task is to redesign the system so it can handle different languages. The design should be made in a way that makes it easy to configure the system to new languages.

The words English, German and French are marked as endpoints in the document.

Examining the Consequences

Now it is time to validate what consequences the new requirement has on the system. The new requirement identify one object that may be affected, the Display object.

  1. Study the requirements regarding the Display in the original textual requirements document. You should find that the new requirement does not contradict with the original requirements.
  2. Traverse the implementation link from the text fragment Display in the original textual requirements. The logical structure diagram in the requirements object model will pop up with the class Display selected.
  3. With the class still selected, choose Traverse Link once more and follow the link to the logical architecture diagram in the analysis object model. The class DisplayInterface, with operation Display and attribute Text will be selected. The class is a part of the class EntranceUnit. It also has a connection to the class EntranceCtrl, see Figure 753.

Figure 753 : Part of the Logical Architecture diagram

  4. Continue to follow the link of the class DisplayInterface, from the logical architecture to the package EntranceUnitPackage. The class is connected with the block type EntranceInterface and the process type DisplayInterface as well as with the signal interface defining the signal Display.
  5. You can also follow the implementation links from the class DisplayInterface to the block theEntranceInterface (within the block type EntranceUnit) and to the process theDisplayInterface (within the block type EntranceInterface).
  6. Open the block type EntranceInterface in the Object Design Documents structure. Study the signal routes leading to and from the process theDisplayInterface. You will notice two signals: Display and EnvDisplay. Examining the two signals with help of the Signal Dictionary will give you information about the signals. EnvDisplay has the parameter Charstring and the signal Display has the parameter MessageType.
  7. Open the process type DisplayInterface. Study the behavior. You will notice that it is possible to change the content of the EnvDisplay signal without affecting the behavior of the process type. It also seems like the required changes to the system are limited to the process type DisplayInterface.

Introducing Changes in Documents

Now you should introduce the necessary changes to the system to get the desired behavior. Changes should be made in a controlled way. All documents affected of the changes should be edited, to keep the consistency.

Updating the Data Dictionary

  1. Open the data dictionary. Include information presented in the additional requirements to the data dictionary.
  2. Save the file as DataDictionary.txt in the current directory.

Updating the Requirements Object Model

As we saw earlier, the change we have to introduce to the system is focused on the process type DisplayInterface. The new requirement specify that one version of the system should handle a specific language and the only language dependent part of the system is the process type DisplayInterface.

It seems natural to introduce a class for each one of the languages English, German and French in the logical structure diagram. These classes should be subclasses to the class Display, i.e. an inheritance structure is needed.

  1. Add the three new classes to the logical structure diagram in the requirements object model. Name the classes FrenchDisplay, EnglishDisplay and GermanDisplay respectively.
  2. Link the classes with the corresponding text in the additional textual requirements document.
  3. Save the diagram as logicalstructure.som in the current directory.

Figure 754 : The class Display and its subclasses

  4. Make a link from the class Display to the class DisplayInterface in the logical architecture diagram in the analysis object model.

Updating the Analysis Object Model

In the logical architecture diagram we have to create an inheritance hierarchy corresponding to the inheritance hierarchy in the logical structure.

  1. Create the three subclasses to the class DisplayInterface. Name the classes EnglishDisplayInterface, GermanDisplayInterface and FrenchDisplayInterface.
  2. Create implementation links to the corresponding classes in the logical structure diagram. (An alternative here would have been to copy the classes from the logical structure diagram and paste them as classes in the logical architecture diagram. The implementation links would then have been created automatically.)
  3. Traverse the link from the class DisplayInterface to the process type DisplayInterface in the EntranceUnitPackage.

Updating the SDL Design

Now it is time to make some changes to the SDL design, making it correspond to the logical architecture. The inheritance hierarchy of the DisplayInterface classes should be mapped to an inheritance hierarchy of process types.

  1. Create two new process types in the EntranceUnitPackage. Name the process types GermanDisplayInterface and FrenchDisplayInterface. The already existing DisplayInterface process type will function as the EnglishDisplayInterface.
  2. Mark these process types as endpoints and create links between them and the corresponding classes in the logical architecture. (Alternatively, use the Copy-Paste As mechanism.)
    Now, edit the DisplayInterface process type to make it more general and suitable for reuse.
  3. Double-click on the DisplayInterface process type in the EntranceUnitPackage.
  4. Create a variable of type charstring for each possible message that can be sent to the environment. You will need eight such variables.
  5. Put the text Virtual in the start symbol.
  6. Insert a task symbol just after the start symbol.
  7. In the task symbol you should initialize the message variables to the corresponding message.
  8. Edit each output symbol making it use the corresponding message variable as a parameter instead of a text string. The process type DisplayInterface will use English language.

Figure 755 : The process type DisplayInterface

  9. Save the diagram in the current working directory.

After editing the DisplayInterface process type it is time to create the process types GermanDisplayInterface and the FrenchDisplayInterface. For each process follow the steps below:

  10. Open a graph page for each process type by double-clicking on the corresponding process type symbol in the EntranceUnitPackage. Press OK in the edit dialog.
  11. In the additional heading you should enter the text:
    INHERITS DisplayInterface ADDING;
  12. Place a start symbol in the diagram and enter the text REDEFINED in the symbol.
  13. Connect a task symbol to the start symbol. The task is to initialize the message variables to the appropriate messages. Do not use national characters.
  14. Connect a state symbol with the task symbol and name it Wait_for_signal.
  15. Save the diagrams.

Now the necessary behavior is described and it is time to show how to configure the system to make use of the new design.

Figure 756 : The process type GermanDisplayInterface

Configuring the System

The necessary design is done and we want to configure our system to make use of the new design. Following the steps below will configure the system to a German version.

  1. Open the block type EntranceInterface.
  2. Select the process theDisplayInterface and change the text theDisplayInterface(1,1):DisplayInterface to theDisplayInterface(1,1):GermanDisplayInterface
  3. Now you can analyze the system. Perhaps you want to simulate the new version of the system; if so, follow the steps described in "Simulating the System" .

Figure 757 : The block type EntranceInterface

Now you have completed the iteration exercise.


To Conclude ...

You have now learned the steps of the SOMT method, and we hope you have enjoyed the tour.

Once again we would like to point out that the activities are presented in a sequential order in this tutorial just to simplify the reading. In practise, the task of developing a system using SOMT is a highly iterative process. One activity may start before the preceding activity is completed and the models inside an activity are usually created in parallel.

The SOMT method is intended to support the development process, not to control it. In other words, it is a proposed way of working. For your own work, you should not feel that you are locked by SOMT, but pick the parts that suit you best.