User Manual

Equipment Simulator
Issue C3
History
Version Date Author Comments
Z 12.11.2001 A. Mair First draft version
A 14.12.2001 A. Mair Minor modifications after comments; Chapter
"Installation and Configuration" revised
B 15.11.2002 M. Pargney Updated for the release 1.1: added Bitstring clarification
and global Active/Standby rollswitch command
C1 15.01.2003 JJ. Charon
O. Juyaux
M. Pargney
Updated for the release 1.2
C2 03.02.2003 O. Juyaux Added new scenario features description
C3 24.04.03 M. Pargney Added Multilingualism and new log features
Equipment Simulator User Manual Table of Contents i
Table of Contents
1. Introduction 1
1.1. Overview...................................................................................................................1
1.2. Organization of this Manual......................................................................................1
1.3. Relationship to Other Documents .............................................................................2
2. Installation and Configuration 3
2.1. Installation and Configuration General ..................................................................3
2.2. Installation.................................................................................................................3
2.2.1 Requirements............................................................................................3
2.2.2 Distribution ..............................................................................................4
2.2.3 Proceeding to the installation ...................................................................4
2.2.4 What is installed.......................................................................................7
2.3. Registration ...............................................................................................................7
2.4. Configuration ............................................................................................................9
2.5. Multilingualism.......................................................................................................11
3. The Equipment Simulator Window 13
3.1. Equipment Simulator Window - General ................................................................13
3.2. Description of the Equipment Simulator Window..................................................13
3.3. Menu and Toolbar ...................................................................................................15
3.4. Device Tree Pane ....................................................................................................15
3.5. Log Pane .................................................................................................................16
3.6. Status Bar ................................................................................................................17
3.7. Client Area ..............................................................................................................17
3.7.1 Data Windows........................................................................................17
3.7.2 Scenario Windows..................................................................................19
3.7.3 Arrange Data and Scenario Windows ....................................................19
4. Configuration Files and Workspaces 20
4.1. Configuration Files and Workspaces General ......................................................20
4.2. Configuration Files..................................................................................................20
4.2.1 Loading a standalone configuration file .................................................21
4.2.2 Loading from an SCE zip file.................................................................21
4.3. Workspaces .............................................................................................................22
5. Scenarios 24
5.1. Scenarios General.................................................................................................24
5.2. Organization of Scenarios .......................................................................................24
5.3. The Scenario Window.............................................................................................26
5.3.1 The Control Center.................................................................................26
5.3.2 The Code Section ...................................................................................27
5.3.3 The Log Section .....................................................................................28
5.4. Managing Scenarios ................................................................................................28
5.4.1 Scenario Files .........................................................................................28
5.4.2 Scenarios ................................................................................................30
Equipment Simulator User Manual Table of Contents ii
5.5. Writing Scenarios....................................................................................................32
5.5.1 General Structure of Scenarios...............................................................32
5.5.2 Using Variables in Scenarios .................................................................34
5.5.3 Referencing UCA2 Data Leaves ............................................................36
5.5.4 Using Named Constants .........................................................................37
5.5.5 Event Handler.........................................................................................39
5.5.6 Other Topics...........................................................................................45
6. Preparing a Simulation 46
6.1. Preparing a Simulation - General ............................................................................46
6.2. Selecting Server and Clients ...................................................................................46
6.3. Attaching and Detaching Scenarios ........................................................................48
6.3.1 Attaching Scenarios to Single Objects ...................................................50
6.3.2 Attaching Scenarios to Multiple Objects................................................50
6.3.3 Detaching Scenarios...............................................................................52
6.4. Initializing Data Leaves ..........................................................................................53
6.5. Preparing File Simulation........................................................................................54
7. Starting and Stopping a Simulation 58
7.1. Starting and Stopping a Simulation General ........................................................58
7.2. Starting a Simulation...............................................................................................58
7.3. Stopping a Simulation.............................................................................................60
7.4. Generation of Object Definition, Data Model and UCA2 Agency Configuration
Files.........................................................................................................................60
7.4.1 LEAN.CFG ............................................................................................61
7.4.2 AGENCY.CFG ......................................................................................62
7.4.3 MMS_LOG.CFG....................................................................................63
7.4.4 Generation of Data Model Files .............................................................63
8. Simulation of UCA2 Operations 65
8.1. Simulation of UCA2 Operations - General .............................................................65
8.2. Displaying Data Objects and Data Leaves ..............................................................65
8.2.1 Reading mode.........................................................................................67
8.2.2 Illustration of modified Data Leaves......................................................73
8.2.3 User Readable Names ............................................................................74
8.3. Modifying Data Objects and Data Leaves...............................................................75
8.3.1 Complete Modification using Dialogs....................................................75
8.4. Server Operations....................................................................................................79
8.4.1 Modifying Data Objects and Data Leaves..............................................79
8.4.2 Reason For Inclusion..............................................................................79
8.4.3 Control Termination...............................................................................80
8.4.4 Disable associations ...............................................................................81
8.5. Client Operations ....................................................................................................82
8.5.1 Reading Data Objects and Data Leaves .................................................82
8.5.2 Modifying Data Objects and Data Leaves..............................................83
8.5.3 Write Quality and Control Operations ...................................................83
8.5.4 Time Synchronization ............................................................................86
9. Simulation of Redundancy 87
9.1. Simulation of Redundancy - General ......................................................................87
9.2. Modifying the Current Redundancy Status .............................................................87
10. Simulation of Files 89
10.1. Simulation of Files - General ..................................................................................89
10.2. Server ......................................................................................................................89
10.3. Client .......................................................................................................................90
10.3.1 Put File to Server....................................................................................90
Equipment Simulator User Manual Table of Contents iii
10.3.2 Get File from Server...............................................................................91
10.3.3 Delete File ..............................................................................................91
11. Simulation of goose 92
11.1. Simulation of goose - General.................................................................................92
11.2. Starting a simulation with goose .............................................................................92
11.3. Receiving goose ......................................................................................................93
11.4. Sending goose .........................................................................................................94
12. Using Scenarios during Simulation 95
12.1. Using Scenarios during Simulation - General .........................................................95
12.2. The Scenario Runtime Engine.................................................................................95
12.2.1 Status of Scenarios .................................................................................95
12.2.2 Execution of Scenarios...........................................................................97
12.2.3 Runtime Errors .......................................................................................97
12.2.4 Configuration .........................................................................................98
12.3. Scenario Status View............................................................................................101
12.3.1 Execution History.................................................................................102
12.4. Starting and Stopping Scenarios............................................................................103
12.4.1 Starting Scenarios.................................................................................103
12.4.2 Stopping Scenarios...............................................................................106
12.4.3 Removing Scenarios.............................................................................107
Appendix A Bitstrings Use 108
Bitstrings Use - General...................................................................................................108
Bitstrings use in the graphical user interface ...................................................................108
Bitstrings use in the scenarios..........................................................................................109
Appendix B Scenario Language Reference 110
Scenario Language General ..........................................................................................110
UCA2 Data Leaves, Scenario Variables and Named Constants ......................................110
UCA2 Data Leaves............................................................................................110
Scenario Variables.............................................................................................111
Named Constants...............................................................................................111
Data Types.......................................................................................................................111
Literals .............................................................................................................................113
Event Handler ..................................................................................................................113
Expressions and Operators...............................................................................................116
Built-In Functions............................................................................................................118
Statements........................................................................................................................119
Assignment ........................................................................................................119
BEGIN_UPDATE - END_UPDATE................................................................119
CONTROLTERMINATION.............................................................................121
DIRECTCONTROL..........................................................................................121
DIRECTCONTROLDONE...............................................................................123
EXIT 123
FILEGET...........................................................................................................124
FILEPUT...........................................................................................................124
FOR Loop..........................................................................................................126
GETGOOSEBITPAIR ......................................................................................126
GOTO 127
IF Statement ......................................................................................................127
SBOSELECT.....................................................................................................128
SBOSELECTDONE..........................................................................................128
SBODESELECT ...............................................................................................129
SLEEP 130
TRACE - NOTRACE........................................................................................130
Equipment Simulator User Manual Table of Contents iv
WHILE Loop.....................................................................................................130
UCA2 Assignment.............................................................................................131
Appendix C Equipment Simulator Logging 132
Equipment Simulator Logging.........................................................................................132
Appendix D Error and Bug Reports 134
Error and Bug Reports .....................................................................................................134
Index 135
Equipment Simulator User Manual Introduction 1
1. Introduction
1.1. Overview
This user manual describes how the Equipment Simulator is installed, configured
and used, how simulations are prepared, started and stopped and how scenarios
can be used to automate certain tasks.
The Equipment Simulator is designed for the Windows NT and Windows 2000
operating system families.
The Equipment Simulator is based on the UCA2 Agency for communication
with other devices or between Equipment Simulators on different computers.
This user manual is for people who want to use the Equipment Simulator to
browse a UCA2 network, simulate certain devices, which are physically not
available, or investigate and control a remote device.
This user manual assumes a basic knowledge of UCA2 terminology and
procedures. For programmers who want to use the scenario language some
knowledge and experience in developing in a high level language such as Visual
Basic or PASCAL or a scripting language is needed.
1.2. Organization of this Manual
The Equipment Simulator user manual is organized as follows:
The chapter "Installation and Configuration" on page 3 lists the
hardware and software requirements for the Equipment Simulator
and explains how to install and configure the Equipment Simulator.
The chapter "The Equipment Simulator Window" on page 13
provides basic information about the organization of the Equipment
Simulator main window and about how to adjust the appearance to
your needs.
The chapter "Configuration Files and Workspaces" on page 20
describes how configuration files are imported and workspaces are
used to store current simulation settings to files.
The chapter "Scenarios" on page 24 gives a detailed explanation
about how scenarios can be used to automate simulation tasks.
Beside the language syntax, all the important concepts of the
scenario language are shown.
The chapters "Preparing a Simulation" on page 46 and "Starting
and Stopping a Simulation" on page 58 describe the steps necessary
to prepare simulations and how to start and stop simulations.
Equipment Simulator User Manual Introduction 2
The chapters "Simulation of UCA2 Operations" on page 65,
"Simulation of Files" on page 89, "Simulation of Redundancy" on
page 87 and "Simulation of goose" on page 92 explain how
common UCA2 operations and redundancy operations can be
simulated using the Equipment Simulator.
"Using Scenarios during Simulation" on page 95 gives you detailed
information about how the Equipment Simulator executes scenarios
and which functions you can use to investigate and control running
scenarios.
"Appendix A Bitstrings Use" on page 108 contains a detailed
reference on how bitstring data are managed in Equipment
Simulator.
"Appendix B Scenario Language Reference" on page 110 contains
a detailed reference of all scenario language elements and concepts.
"Appendix C Equipment Simulator Logging" on page 132 and
"Appendix D Error and Bug Reports" on page 134 contain
information about how logging can be used to investigate the
Equipment Simulator behavior and which information error and
bug reports should contain.
1.3. Relationship to Other Documents
This document references other documents. These other documents include the
following:
MiCOM SYSTEMS System Internal Interfaces (SII),
UCA2 Agency API Reference (APIxx.HTM),
Equipment Simulator Product Interface Description Document,
MiCOM SYSTEMS UCA2 Communications Agency - Installation
Guide,
UCA2 Generic Object Models for Substation & Feeder Equipment
(GOMSFE), Version 0.9.
Equipment Simulator User Manual Installation and Configuration 3
2. Installation and
Configuration
2.1. Installation and Configuration General
This chapter deals with the following main topics:
Installation,
Registration,
Configuration.
2.2. Installation
This section describes the requirements necessary to install and setup the
Equipment Simulator, the files delivered with the Equipment Simulator and the
installation process itself.
2.2.1 Requirements
The following requirements are necessary to install and run the Equipment
Simulator:
Personal Computer with a Pentium III-600 or faster processor,
256 MB of memory,
30 MB of free hard disk space,
Windows NT 4.0, Windows 2000,
Internet Explorer 5 or higher,
Microsoft word to view the manual,
UCA2 Agency v2.9 or higher (including the OdFoundry 1.10 or
higher).
Equipment Simulator User Manual Installation and Configuration 4
2.2.2 Distribution
Whatever the media support, the Equipment Simulator distribution consist in
three files:
EquipSimUserManual.doc: It corresponds to what you are reading
now.
EQT_SIM_Release_Note 1.2.doc: Release note.
Equipment simulator install.exe: The single executable to start in
order to install the product.
2.2.3 Proceeding to the installation
Note: You need administrator privileges to install the Equipment Simulator. If
you currently do not have enough privileges, log off and on again with
administrator privileges before installing the Equipment Simulator.
It is not required to uninstall a previous version of Equipment Simulator
before installing the newest version of the software. Thus, your registration key
is not lost and you dont need to ask the Equipment Simulator team for a new
key for the same PC.
To install the Equipment Simulator simply start Equipment simulator
install.exe.
The Equipment Simulator setup wizard will guide you through the setup process.
Click Next> on the welcome dialog.
Then read the license agreement and accept it by clicking Yes.
Equipment Simulator User Manual Installation and Configuration 5
Then, if you install on a computer on which the equipment simulator was already
installed, the following question appears.
Except if you are an expert, you need to answer Yes to the question.
Then you will have to enter your registration key (see registration) and user
information. Enter your name, company, serial key and then proceed by clicking
Next>. If you do not have a registration key at this time, you can let
"dummyKey" as your serial.
If you have already registered a previous version of the simulator, current
information is automatically filled into the dialog. Do not change them if OK.
Equipment Simulator User Manual Installation and Configuration 6
When the following dialog is displayed, choose the directory, where the
Equipment Simulator should be installed (or leave default option) and click
Next >.
At last, choose (or leave the default one) the program folder where the
equipment simulator shortcuts will be installed in the startup menu and click
Next>.
The installation wizard now proceeds to the installation of the Equipment
Simulator. When it is finished, you get the following window. Click Finish to
terminate the installation wizard.
Equipment Simulator User Manual Installation and Configuration 7
2.2.4 What is installed
Files
The following files are installed the folder chosen during the installation:
Bastypes.cfg : List of basic types and common classes
Cmax20.dll : dll codemax
Equipsim.cnt : link file for the online help.
EquipSim.exe : Equipment simulator executable file
EquipSim.hlp : Equipment simulator online help file
Sceintf.dtd : DTD for the XML configuration file
Esrcen.dll resources : English release of the Equipment simulator
EquipSimUserManual.doc : this document
EQT_SIM_ReleaseNote_1.2.doc : Release Note
Startup menu item
A folder is added to the startup. This folder contains 2 menu items. One to start
the equipment simulator, and the other to view the user manual.
By default, folder name is Alstom/Pacis/Equipment simulator
2.3. Registration
To fully use the Equipment Simulator, registration is necessary. Registration
must be done on every computer the Equipment Simulator is used on. During
registration the Equipment Simulator calculates a unique number for your
computer. This number must be sent to an e-mail address. An activation key for
your computer is sent back and must be entered into the Equipment Simulator.
Without registration, simulations are possible for a period of 60 days. After 60
days you can still use the Equipment Simulator, load XML configuration files
and workspaces and browse through the device structure but you cannot start
simulation. During the evaluation period of 60 days you can use all features of
the Equipment Simulator including simulations.
Equipment Simulator User Manual Installation and Configuration 8
When you start a simulation the Equipment Simulator checks if you have
registered. If not, the following dialog is displayed which gives information
about the remaining evaluation period.
If you select Register Later, the Equipment Simulator starts the simulation
process. Select Register Now to register the Equipment Simulator. You can
also choose Help - Register... from the main menu to register the Equipment
Simulator at any time.
The following dialog is used for registration.
The unique number calculated for your computer is displayed in the first text
box. Send this number per e-mail to Equip.Sim@tde.alstom.com. An
activation key will be calculated for your computer and sent back to you. Enter
the returned number into the registration key text box and click register.
If you do not register within 60 days after the first start of the Equipment
Simulator, you cannot start further simulations. Until you register, the following
dialog is displayed every time you start a simulation.
Equipment Simulator User Manual Installation and Configuration 9
2.4. Configuration
When you start the Equipment Simulator the first time, some basic configuration
settings should be checked. If you have installed the Equipment Simulator after
the installation of the UCA2 Agency and you have selected the appropriate
option in the Setup Wizard, no modification of configuration settings should be
necessary. But in this case you should carefully read this chapter too and check if
all settings, which are done automatically, are correct.
For most of the configuration settings, the Equipment Simulator uses default
values which are built in. With the exception of some paths for the UCA2
Agency and its configuration files you normally have to check only if the default
values match your requirements and modify only those which do not.
Note: Configuration settings are stored in the Windows registry. If you want to
transfer configuration settings between computers or users, you can use the
Microsoft Registry Editor (REGEDIT.EXE) to export registry settings on one
computer and import it on another computer. Configuration settings are stored in
the HKEY_LOCAL_MACHINE\SOFTWARE\ALSTOM\Equipment
Simulator and HKEY_CURRENT_USER\SOFTWARE\ALSTOM\-
Equipment Simulator registry keys. If you transfer the HKEY_LOCAL_-
MACHINE part of the Equipment Simulator settings be sure that you do not
include the registration key stored under HKEY_LOCAL_MACHINE\-
SOFTWARE\ALSTOM\Equipment Simulator\Registration because
the registration key is not valid on other computers.
This chapter contains a description of how to change the settings which are
absolutely necessary. Other settings are described in the chapters where they are
used and affect the behavior of the Equipment Simulator.
Note: The Equipment Simulator stores most of its settings in the Windows
registry. Some of the settings and options are stored on a per user basis, some are
not. Settings which are not stored on a per user basis are located in the
HKEY_LOCAL_MACHINE registry key. To change settings stored under this
registry key appropriate privileges are necessary, which ordinary users normally
do not have. You must be logged on with administrator privileges or the
appropriate right assigned by your administrator if you are logged on as ordinary
user. Settings which cannot be changed are grayed in the options dialog.
Equipment Simulator User Manual Installation and Configuration 10
To change configuration settings and Equipment Simulator options choose
Tools - Options... from the menu. The following dialog is displayed:
Equipment Simulator options are organized in categories with the categories
displayed in a tree like hierarchy on the left side and the options of a selected
category on the right side. To change the settings for a category simply select its
name on the left side.
Please check and if necessary adjust the following settings when you first start
the Equipment Simulator:
1. Select the Object Foundry Settings - General category.
2. Enter the path where the object foundry executable can be
found. The object foundry, ODFOUNDRY.EXE, can normally be
found in the directory where the UCA2 Agency has been installed.
You can use the Browse... button to choose the path.
3. Enter the path and name of the basic type ids configuration
file. This file is normally copied during Equipment Simulator setup
and can be found in the Equipment Simulator installation directory.
The name of the file is BASTYPES.CFG. You can use the
Browse... button to locate the file.
4. Enter the path where the Equipment Simulator should store
temporary object definition and data model files. You can
use the Browse... button to choose the path.
5. Select the UCA2 Agency Settings- General category.
6. Enter the path where the UCA2 Agency is installed. You can use
the Browse... button to choose the path.
Equipment Simulator User Manual Installation and Configuration 11
7. Select the Simulation of Files category.
8. Enter the root directory where the Equipment Simulator should
store files for servers which are simulated. For every server
simulated by the Equipment Simulator a virtual root directory
under this directory is created, where the server specific files are
stored. See "Simulation of Files" on page 89 for more details on
how to simulate files with the Equipment Simulator. You can use
the Browse... button to choose the path.
Note: The default AGENCY.CFG file, which is generated by the Equipment
Simulator before a simulation is started contains settings for a maximum of 3
client and 3 server sessions. If you need to simulate more sessions
simultaneously you need to adjust the MaxClientSession and
MaxServerSession settings appropriately under the UCA2 Agency
Settings - Agency Configuration File category.
With these basic configuration settings done you should be able to do
simulations.
2.5. Multilingualism
According to the provided resources DLLs (i.e. esrcen.dll, esrcfr.dll, and so on),
Equipment Simulator offers multilingualism features, which can be set with the
dialog of configuration available via the Tools Options menu in the Language
category.
After choosing the desired language, you have to quit and restart Equipment
Simulator in order to take the changes into account.
Equipment Simulator User Manual Installation and Configuration 12
Note : At its first launch, Equipment Simulator starts with the language of the
Operating System if a resource DLL for this language is available. Otherwise,
the default language is English.
Equipment Simulator User Manual The Equipment Simulator Window 13
3. The Equipment Simulator
Window
3.1. Equipment Simulator Window - General
This chapter deals with the following main topics:
Description of the Equipment Simulator Window,
Menu and Toolbar,
Device Tree Pane,
Log Pane,
Status Bar,
Client Area.
3.2. Description of the Equipment Simulator Window
The Equipment Simulator main window consists of several items which can be
adjusted to your needs.
The following screen shot shows an example for the contents of a typical
Equipment Simulator window:
Equipment Simulator User Manual The Equipment Simulator Window 14
This example shows a main window with a data window and a scenario window
opened in the client area.
The Equipment Simulator main window consists of a user adjustable number and
selection of the following items:
Item Description
Menu and toolbar Menu and toolbar are used to initiate actions in the Equipment
Simulator like creating new windows, opening workspace
files or starting a simulation.
Device tree pane The device tree pane which is normally docked to the left side
of the Equipment Simulator main window is used to browse
through the device structure and create new data windows.
Log pane The log pane which is normally docked to the bottom side of
the main window displays information or events about
ongoing simulations or other potentially interesting
information.
Status bar The status bar displays simple help texts if a menu item or
toolbar symbol is selected.
Client area The client area is used to display any number of data and
scenario windows.
The items listed above are described in more detail in the following topics:
Menu and Toolbar,
Device Tree Pane,
Log Pane,
Status Bar,
Client Area.
Equipment Simulator User Manual The Equipment Simulator Window 15
3.3. Menu and Toolbar
The menu and toolbar at the top of the Equipment Simulator main window are
used to initiate actions in the Equipment Simulator. By choosing a menu item or
clicking a toolbar symbol with the mouse you can open files, start and stop
simulations, simulate data read and writes and so on.
The toolbar can be hidden and shown using View - Toolbar.
3.4. Device Tree Pane
The device tree pane can be used to browse through the structure of the devices
on the station bus. The device tree pane is similar to the data windows displayed
in the client area with the difference that no data leaves and their values are
displayed.
The device tree pane is normally used as a starting point to open new data
windows. Simply right click an item in the device tree, like a server or a brick,
and choose New Window from the context menu. Using this method you can
open any number of data windows from any level in the device structure.
For example if you choose the server C264 Computer (C264_1N) in the
following example, the data window displayed below is created.
Equipment Simulator User Manual The Equipment Simulator Window 16
If you are opening new data windows from existing data windows and therefore
do not need the device tree pane choose View - Device Tree or press <Alt>+1
to hide it. To show a hidden device tree pane, choose View - Device Tree or
press <Alt>+1 again.
You can dock the device tree pane to any side on the Equipment Simulator main
window by clicking the border of the pane and dragging it to the desired
position. If you do not want the device tree pane to be docked to the Equipment
Simulator main window, move the pane into the client area using the described
process. If the device tree pane is not docked you can move it around in the
client area like data and scenario windows.
3.5. Log Pane
The log pane is used to display information about ongoing simulations or other
events.
The log pane can be hidden and shown by choosing View - Log or by pressing
<Alt>+2.
You can clear the contents of the log by selecting Edit - Clear Log Window
or clicking the symbol on the toolbar.
Log level can be configured for each equipment simulator component with the
Tools Options Logs configuration dialog.
Equipment Simulator User Manual The Equipment Simulator Window 17
3.6. Status Bar
The status bar is used to display a single line of help text when you scroll
through the menu or move the mouse over the toolbar.
The status bar can be hidden and shown using View - Status Bar.
3.7. Client Area
The client area is used to display any number of data windows and scenario
windows.
3.7.1 Data Windows
Data windows are used to browse through the device structure or display and
modify data object and data leaf values. Furthermore they are used to attach
scenarios to and detach scenarios from items in the device structure.
During a simulation it can be useful to open and arrange more than one data
window in the client area to inspect the behavior of multiple data objects at once.
Data windows are also used during simulation to initiate control operations or
display and simulate files.
Data windows contain a tree like device structure on the left side and an area to
display information to a selected item on the right side.
To display information to an item in the device structure, for example a brick or
a data object, simply select it in the tree view on the left side.
On the right side you can choose to display the objects which are children of the
selected item or the scenarios which are attached to the item.
Equipment Simulator User Manual The Equipment Simulator Window 18
The title bar of a data window contains the name of the parent object of the item
displayed at the top level. In the above example the station bus is the parent of
HMI server (S2KHMI1A) which is displayed at the top level in the tree view.
You can create any number of data windows starting at any level in the device
structure. The only exception is that you cannot display a single data object or
data leaf in a data window.
To create a new data window simply right click the item, which should be the
top level object, in an existing window and choose New Window.
In the following example the GLOBE brick is displayed in its own data window.
Equipment Simulator User Manual The Equipment Simulator Window 19
3.7.2 Scenario Windows
Scenario windows are used to manage scenarios and scenario files.
Scenario windows contain a control center at the top, the code section in the
middle and a log section at the bottom.
You can open any number of scenario windows to copy code between them or
compare scenarios. To open a new scenario window choose Window - New
Scenario Window.
If you want to bring an existing scenario window into foreground, but do not
want to create a new window, click the symbol on the toolbar.
See "Scenarios" on page 24 for a more detailed description on how to create,
modify and manage scenarios.
3.7.3 Arrange Data and Scenario Windows
If you have many data and scenario windows opened the Equipment Simulator
can auto arrange them for a more clear display.
Choose Window - Cascade, Window - Tile Horizontally or Window -
Tile Vertically to force the Equipment Simulator to auto-arrange data and
scenario windows. You can also use the symbols , or from the toolbar.
Equipment Simulator User Manual Configuration Files and Workspaces 20
4. Configuration Files and
Workspaces
4.1. Configuration Files and Workspaces General
This chapter deals with the following main topics:
Configuration Files,
Workspaces.
4.2. Configuration Files
The import of a configuration file is the starting point of every simulation.
Configuration files are XML files, which describe the structure of devices
managed by the Equipment Simulator.
Because it is not possible to manually create devices and their structure in the
Equipment Simulator, configuration files are the only way to set up a simulation
environment in the Equipment Simulator.
Configuration files are created by the System Configuration Editor (SCE) which
produce a Zip file containing the XML configuration file for the equipment
simulator. You can load the configuration directly from the Zip or extract it
manually from the zip, eventually modify it, and then load it. You can also build
you own configuration with a text editor or an XML editor.
For a documentation of the format of these XML files see ALSTOM PACIS -
Equipment Simulator Product Interface Description Document, Identification
Number: 94.030.074e.
In addition to the XML file the DTD (Document Type Definition) file, which is
referenced by the XML file, must be present to import a device configuration
into the Equipment Simulator.
Note: There is only one configuration file for all devices belonging to a system.
It is not possible to merge several files into one device configuration using the
Equipment Simulator. All devices are configured using one single XML file.
Equipment Simulator User Manual Configuration Files and Workspaces 21
4.2.1 Loading a standalone configuration file
To import a device configuration choose File - Import XML Configuration
File... or click on the toolbar.
In the following dialog choose the file you want to import and click OPEN.
The Equipment Simulator reads the file and displays the device structure.
When a new configuration file is imported a new workspace is automatically
created. See the following section for more information on workspaces.
4.2.2 Loading from an SCE zip file
To get the configuration directly from an SCE produced Zip file choose file
Import SCE configuration. In the following dialog choose the SCE file you want
to import and click OPEN.
Equipment Simulator User Manual Configuration Files and Workspaces 22
4.3. Workspaces
Workspaces are used to store the actual work into a file. Workspaces contain
information about opened data and scenario windows, devices which are
simulated as servers or clients, scenarios which are attached to data objects, or
data values entered for data leaves.
Workspace files are stored with the extension .ESW (Equipment Simulator
Workspace) by default.
To open an existing workspace, choose File - Open Workspace... or press
<Ctrl>+O. You can also click the symbol on the toolbar. In the following
dialog choose the workspace file you want to open.
To save the current workspace, choose File - Save Workspace, press
<Ctrl>+S or click the symbol on the toolbar.
To save the current workspace under a different name, choose File - Save
Workspace As....
To close the current workspace, choose File - Close Workspace.
By default the Equipment Simulator stores a reference to the XML configuration
file or the SCE zip file in the workspace file. When you reopen the workspace, it
is necessary that the file exists in the same directory and with the same name as
when the workspace was saved.
To change this behavior you can embed the XML device configuration into the
workspace file. Using this technique you can store everything needed by the
Equipment Simulator into one file, take this file and copy it to another computer.
This option is not available when working with an SCE zip file.
To embed the configuration file into the workspace file, choose File - Save
Workspace As.... In the following dialog, enable the Embed XML
configuration option and click Save.
Equipment Simulator User Manual Configuration Files and Workspaces 23
You can also change this option without saving a workspace by choosing File -
Workspace Properties.... In the following dialog enable the Embed XML
configuration option and click OK.
The XML configuration file is embedded into the workspace file the next time
you save the workspace.
If you disable the Embed XML configuration option, the Equipment
Simulator searches the configuration file in the directory the file was originally
imported from.
Equipment Simulator User Manual Scenarios 24
5. Scenarios
5.1. Scenarios General
This chapter deals with the following main topics:
Organization of Scenarios,
The Scenario Window,
Managing Scenarios,
Writing Scenarios.
5.2. Organization of Scenarios
Scenarios are used to automate simulations in the Equipment Simulator. They
are organized in scenario files with the extension .ESS (Equipment Simulator
Scenarios). Scenario files are XML files which contain zero, one or more
scenarios.
Scenario files are stored in global and workspace specific directories. The
Equipment Simulator automatically loads all scenario files in the global
directory when it is started and the scenarios in the workspace specific directory
when a workspace is loaded. After scenario files have been loaded, scenarios
contained in the files are ready for use in the Equipment Simulator.
To configure the global directory for scenarios, choose Tools - Options... and
select the Scenarios - General category.
Equipment Simulator User Manual Scenarios 25
Enter the directory for global scenario files and click OK.
If a workspace is in use, the workspace specific directory can be configured by
choosing File - Workspace Properties....
By default the directory where the workspace file is stored is used. If you want
to change the workspace specific scenario directory enter the desired path and
click OK.
Because scenarios are organized in stand alone files they can be easily
exchanged between different users and computers. To exchange scenario files,
simply copy the desired files from the global or workspace specific directory to
the destination computer. In the Equipment Simulator on the destination
computer choose Scenarios - Refresh All to reload the new scenario files if
the Equipment Simulator is already started.
Equipment Simulator User Manual Scenarios 26
5.3. The Scenario Window
The scenario window is used to create, display, modify and delete scenarios and
scenario files.
For a description on how to display one or more scenario windows see "Scenario
Windows" on page 19.
The scenario window contains a control center at the top, the code section in the
middle and a log section at the bottom.
5.3.1 The Control Center
The control center at the top of a scenario window is used to navigate through
existing scenarios and manage scenarios and scenario files.
All scenarios currently loaded by the Equipment Simulator - global and
workspace specific - are displayed in the combo box at the left side of the control
center. They are displayed using the following format:
<Scenario Name> [ <Global/Local> - <Scenario file> ]
Equipment Simulator User Manual Scenarios 27
For example, if XCBR-ODSw [G - XCBRScoExamples.ess] is displayed in
the combo box, the code of the scenario XCBR-ODSw from the file
XCBRScoExamples.ess - which is a global scenario file - is displayed in
the code section.
Use the combo box in the control center to select the scenario you want to work
with. The Equipment Simulator displays the code of the scenario in the code
section of the scenario window.
The buttons Scenario and Scenario Files are used to manage scenarios and
scenario files. See the following chapters for more details on these topics.
5.3.2 The Code Section
Below the control center the code of the selected scenario is displayed.
The Equipment Simulator has a very comfortable code editor for modifying
scenarios built in. This code editor supports a lot of features like syntax
highlighting or bookmarks which are known from other popular code editors or
developer studios.
You can adjust the code editor to your needs by choosing Tools - Scenario
Editor Options.... The following dialog is displayed:
Equipment Simulator User Manual Scenarios 28
5.3.3 The Log Section
The log section is used to display errors during compilation of a scenario. By
double clicking an error in the log section the incorrect line is highlighted in the
scenario code.
5.4. Managing Scenarios
This section describes the scenario and scenario file properties, and how you can
create, modify and delete scenario files and scenarios.
For the following topics it is assumed that you have a scenario window opened.
5.4.1 Scenario Files
Scenario files are used to group scenarios which belong together. For example
you could create a scenario file for every type of brick with scenarios useful for
the appropriate brick. It is up to you how you organize your scenarios, the
Equipment Simulator does not impose any restrictions on how you organize
them in scenario files.
Beside the name of the file, scenario files have additional properties which can
be displayed by choosing Scenario File - Properties... from the scenario
window control center. To display these properties you first have to select a
scenario, which is stored in the desired file.
Equipment Simulator User Manual Scenarios 29
Below the folder, where the scenario file is stored, a note is displayed which
gives you the information if it is a global or workspace specific scenario file.
Beside a description for the file, a list of named constants is part of the properties
of a scenario file. Named constants are simple name-value pairs used to associate
a constant integer, floating point or string value with a more readable name
which can be used in the scenario code. For more details on how you can use
named constants to make scenario code more readable see "Using Named
Constants" on page 37.
Using the Add..., Modify... and Remove buttons you can manage the list of
named constants stored with the scenario file.
To manage scenario files you can:
Create new scenario files
Choose Scenario Files - New..., enter the name of the new file
and decide if you want to create a global or workspace specific
scenario file.
Rename existing scenario files
Choose Scenario Files - Rename..., select the scenario file you
want to rename and enter the new scenario file name.
Delete existing scenario files
Choose Scenario Files - Delete... and select the scenario file
you want to delete. If you delete a scenario file, all scenarios
contained in the file are removed.
Change properties of scenario files
Select a scenario which is stored in the scenario file you want to
modify and choose Scenario Files - Properties.... Modify the
description of the scenario file or change the list of named
constants.
Equipment Simulator User Manual Scenarios 30
Save all scenario files
Choose Scenario Files - Save All to save all modifications done
to scenarios to disk.
Reload scenario files
Choose Scenario Files - Refresh All to reload all scenario files
from the global and workspace specific scenario directories.
Reloading of scenario files is useful if you manually copy scenario
files from other users or computers to the global or workspace
specific scenario directory and want to use those files immediately
in the Equipment Simulator.
5.4.2 Scenarios
Beside the code a scenario consists of some additional properties can be
managed for scenarios which are used during attachment of scenarios to the
device structure and execution of scenarios during a simulation.
Scenario properties are displayed in the following dialog:
Scenario properties consist of the name of the scenario, the file where the
scenario is stored, a short description of the scenario, settings for periodic
execution of the scenario and a list of data objects and data leaves for which the
scenario is designed. For the latter to be displayed you must select the
Advanced >> button.
Equipment Simulator User Manual Scenarios 31
Using the settings for periodic execution of scenarios you can configure to start a
scenario at a specific time or periodically by specifying an interval between
starts. Periodic settings stored with scenarios are default values for the scenario
which can be overridden when the scenario is attached to or started for a specific
device object.
The following settings are used for periodic execution of scenarios:
Start time relative to
You can choose to either start the scenario at a specific time of day
or relative to the start time of the simulation. For example if you
choose to start the scenario at a specific time of day and enter
12:00:00 for the start time, the scenario is started at 12:00:00
midday no matter at which time the simulation has been started. If
you choose to start the scenario relative to the simulation start and
enter 01:00:00 for the start time, the scenario is started one hour
after simulation start.
Start time
The start time is either a specific time of day or the period between
simulation start and start of the scenario. The start time specifies
the time the scenario is started the first time if executed
periodically.
Number of starts
The number of starts are used for periodic execution and give the
number of times the scenario will be executed. For a scenario
which should be executed once at a specific time set the number of
starts parameter to one.
Interval between starts
If a scenario is executed periodically, this setting controls the
duration between two consecutive starts of the scenario.
The data objects and data leaves the scenario is designed for are used to
automatically attach the scenario to multiple device objects. In the above
example, where the scenario is designed for $ODLock$b1 data leaves, the
Attach Scenario to Multiple Objects... function can be used to search the
device structure for all $ODLock$b1 data leaves and automatically attach the
scenario to those leaves. For a more detailed description on how to attach
scenarios to device objects see "Attaching and Detaching Scenarios" on page 48.
Use the Add... and Remove buttons in the above dialog to change the list of
data objects and data leaves the scenario is designed for.
To manage scenarios you can:
Create new scenarios
Choose Scenario - New... to create a new scenario. In the
following dialog enter the name of the scenario, choose the
scenario file, where the scenario should be stored, and enter the
desired properties for the scenario.
Rename existing scenarios
Choose Scenario - Rename..., select the scenario you want to
rename and enter a new name for the scenario.
Delete existing scenarios
Select the scenario in the control center of the scenario window and
choose Scenario - Delete....
Equipment Simulator User Manual Scenarios 32
Print scenarios
Select the scenario in the control center of the scenario window and
choose Scenario - Print... or press <Ctrl>+P.
Check the syntax of scenarios
To check if the code of your scenario is syntactically correct, select
the scenario in the control center and choose Scenario - Check
Syntax or press F7. In the log section of the scenario window
either syntax errors are displayed or a short message that no errors
were found is given.
Change properties of scenarios
Select a scenario in the control center and choose Scenario -
Properties....
5.5. Writing Scenarios
This section is focused on how to write scenarios using the scenario language
built into the Equipment Simulator. It describes in addition to other topics how
scenarios are structured, how variables and UCA2 data leaves can be used, how
event handler can be used to start scenarios event triggered and how to use
named constants.
A basic knowledge in a high level programming language such as Visual Basic,
PASCAL or a scripting language is necessary to understand this chapter.
This section treats only base topics needed to write scenarios which cannot be
found in traditional programming languages. For a complete reference of the
scenario language, including all statements and built in functions supported, see
"Appendix B Scenario Language Reference" on page 110.
Note: The Equipment Simulator scenario language is case insensitive.
Keywords, variable names, UCA2 names, event handler names and named
constants can be written in lower case or upper case and mixed in any
combination.
5.5.1 General Structure of Scenarios
A scenario is composed of the following sections:
[Global Variables]
[Local Variables]
[Statements and Event Handler]
The sections must be exactly in the above order. The global and local variables
sections can be omitted if no variables are used.
Equipment Simulator User Manual Scenarios 33
Example:
LOCALS
%ODLock : BSTR1;
END_LOCALS;
// forever ...
WHILE 1 DO
// get the current value of the device locked control
%ODLock := $CO$ODLock$b1;
// wait until the device locked control changes
WHILE $CO$ODLock$b1 == %ODLock DO
SLEEP( 100 );
END_WHILE;
/* set the device locked status and time */
$ST$LockSt$b1 := $CO$ODLock$b1;
$ST$LockSt$t := DATETIME;
END_WHILE;
This example contains a local variables section which defines one local variable
and a statement section without a handler. If the scenario is started the statement
section is simply executed.
In contrast, the following example has an event handler:
OnDirectControl:
// call direct control done
DirectControlDone( #TRUE );
/* set device locked status to device locked
control and update quality descriptor and
time tagging */
BEGIN_UPDATE;
$ST$LockSt$b1 := $ODLock$b1;
$ST$LockSt$t := DATETIME;
$ST$LockSt$q := 0;
END_UPDATE;
// control termination with OK
ControlTermination( $AckCode, #CO_ACK_OK );
EXIT;
If this scenario is started there are no statements executed at the first place. The
scenario is attached to a data leaf or data object and "waits" for an event. If a
direct control operation is done on the data object or data leaf the scenario is
attached to, the Equipment Simulator activates the scenario and executes the
OnDirectControl handler.
As you can see from the above examples, the scenario language supports two
types of comments. A single line comment which is simply prefixed with the
characters // and multi line comment which starts with /* and ends with */.
Equipment Simulator User Manual Scenarios 34
5.5.2 Using Variables in Scenarios
The Equipment Simulator supports both local and global variables. Values of
global variables keep their value after a scenario is finished, local variables loose
their values after a scenario is finished.
Global variables are initialized when a simulation is started and loose their
values when a simulation is terminated.
Variables are declared at the beginning of a scenario using the following syntax:
GLOBALS
<variable> : <type> ;
<variable> : <type> ;
...
END_GLOBALS;
LOCALS
<variable> : <type> ;
<variable> : <type> ;
...
END_LOCALS;
If no local or global variables are used, the appropriate sections can be omitted.
The global variables section must be before the local variables section.
Variable names must start with a percent sign (%) followed by any number of
letters, digits and underscores (_).
Examples for variable names:
%i
%ODSwOld
%RunningValue
%Float_Value1
Valid data types are basically all types supported by the UCA2 Agency.
Examples for data types supported in scenarios:
BOOL
ENUM16
FLT32
FLT64
VSTR32
For BSTRs types, please see "Appendix A Bitstrings Use" on page 108.
For a list of all data types supported see "Data Types" on page 111.
Example for the declaration of a few local and global variables:
GLOBALS
%gi : INT32S;
%gLastValue : FLT32;
%gReturnValue : BOOL;
END_GLOBALS;
LOCALS
%Command : BSTR2;
%SavedValue : FLT64;
%FileName : VSTR128;
END_LOCALS;
To use variables in your code simply use the variable name prefixed with the
percent sign in expressions and statements.
Equipment Simulator User Manual Scenarios 35
Note: After one periodic execution of a scenario or after the execution of an
event handler the scenario is classified as finished. This means that local
variables loose their values in these cases. Local variables are initialized every
time an instance of a scenario is started, which takes place if it is time for a
periodic execution or an event handler is executed. If you need to preserve
variable values between two invocations of a scenario you must use global
variables.
5.5.3 Referencing UCA2 Data Leaves
Data leaves can be referenced in scenarios by using their UCA2 names. UCA2
data leaf names must be prefixed with the dollar sign ($) followed by the name
of the leaf. Data leaf names can be fully qualified names with server name,
logical device name, brick name, functional component name, data object name
and data leaf name. Furthermore leaf names can be relative to any level in the
device structure.
Examples for UCA2 data leaf references:
$Server1/LD1/XCBR$CO$ODSw$OperDev
$Server2/LDX/CFAN$ST$DevST$b2
$f
$MX$Pres$q
If the UCA2 reference does not fully describe the data leaf (e.g. $MX$Pres$q)
the Equipment Simulator tries to resolve the name when the scenario is started.
At this time the scenario is attached to a specific device object in the device
structure. Based on this object the Equipment Simulator tries to build a fully
qualified UCA2 name.
For example if a $CO$ODSw$OperDev data leaf is used in a scenario it can be
assigned to the $CO$ODSw$OperDev data leaf, the $CO$ODSw data object,
the $CO functional component and the brick the $CO functional component is in.
But the scenario cannot be attached to a server or logical device because the
Equipment Simulator does not know the brick the data leaf is in.
If the above scenario is attached to the brick $Server1/LD1/XCBR, the data
leaf will be resolved to $Server1/LD1/XCBR$CO$ODSw$OperDev.
Using the technique of relative data leaf references it is possible to write generic
scenarios which can be started for data objects, bricks, etc. on different servers or
logical devices.
The described resolution process can be used on any level in the UCA2 name
hierarchy. For instance it is possible to use the $f reference in a scenario and
start it for the $Server1/LD1/XCBR$MX$Pres data object.
The Equipment Simulator uses the forward slash (/) to separate server name,
logical device name and brick name and the dollar sign to separate brick name,
functional component name, data object name and data leaf name.
Data leaf names can be used in scenarios like variable names. The Scenario
Runtime Engine reads or writes the respective value from or to the server if a
client is simulated. If a server is simulated, the value is read from or written to
the local device database and the UCA2 Agency.
Equipment Simulator User Manual Scenarios 36
Examples on how to use data leaf names in scenarios:
SBODESELECT
(
$CF$ODSwSBO$SBOState,
"OPERATOR",
"ORIGIN",
DATETIME
);
IF $b2 == 0x80 THEN
SLEEP( 1000 );
END_IF;
$MX$Pres$f := $MX$Pres$f + 1.;
Note: The Equipment Simulator can only read and write data leaves. It is not
possible to read or write data objects or other compound objects which have
multiple data leaves.
You can use the Copy Name to Clipboard function to let the Equipment
Simulator build UCA2 names to save time when entering fully qualified names
and to reduce the likelihood of misspelled names.
Simply right click the data object or data leaf, whose name you need in a data
window, and select Copy Name to Clipboard from the context menu or press
<Ctrl>+C. Switch to the scenario edit window and insert the UCA2 name by
pressing <Ctrl>+V.
Note: You need to prefix the UCA2 name with a dollar sign ($) if you copy a
name via clipboard. The reason is that the scenario syntax expects data leaf
names to start with a dollar sign and the Equipment Simulator does not prefix the
name with a $ when copying it from a data window.
An additional format for UCA2 data leaf names can be used in UCA2
assignment statements. The assignment statement supports the asterisk wildcard
character (*) to write the value of an expression to multiple data leaves.
Every part of a UCA2 name except the data leaf name itself can be replaced with
the wildcard character. The Equipment Simulator tries to substitute every part of
the UCA2 name with all possible names on the appropriate hierarchy level if a
wildcard character is used.
Examples:
$*$*$*$f := 0.0;
$*$*$*$q := 0x01;
In the above examples the Equipment Simulator assigns the given values to all
data objects on all functional components on all bricks.
This technique is called bulk assignment and can be very useful to initialize
all data leaves of a server, logical device or brick.
5.5.4 Using Named Constants
Named constants can be used to make the scenario code more readable.
Constants are defined either using the scenario file or via name-value pairs in
XML configuration files.
Equipment Simulator User Manual Scenarios 37
Examples for named constants are:
Name Value
CO_ACK_OK 0
CO_DEVICE_ALREADY_IN_POS 8
CO_DEVICE_LOCKED 5
FALSE 0
TRUE 1
DEFAULT_OPERATOR "Pete"
To define named constants using scenario files, choose Scenario File -
Properties... from the scenario window and modify the named constants in the
bottom section of the dialog.
Named constants can be defined in the XML configuration file using the
UserReadableValueNamesList element and its child elements. See the
following extract for the definition of the constants Between, Off, On and
Invalid using an XML configuration file:
<Enumeration Name="EnumDCOOnOff" Description="Switch Status">
<NameValuePair UserReadableName="Between" Value="0"/>
<NameValuePair UserReadableName="Off" Value="1"/>
<NameValuePair UserReadableName="On" Value="2"/>
<NameValuePair UserReadableName="Invalid" Value="3"/>
</Enumeration>
Valid names for constants can only contain the following characters: A-Z, a-z,
0-9, _. All other characters are not allowed. This means that name-value pairs
from XML files with names like "Jammed/Motion" or blanks in the name (e.g.
"l Threshold Violation") are not allowed.
Equipment Simulator User Manual Scenarios 38
Named constants can be used in scenarios by simply prefixing the name of the
constant with the number sign (#).
Examples:
DirectControlDone( #TRUE );
ControlTermination( $AckCode, #CO_DEVICE_LOCKED );
%bValid := #FALSE;
5.5.5 Event Handler
Scenarios can contain handlers which are automatically executed if the
appropriate event is processed by the Equipment Simulator. An event can be an
UCA2 event or an Equipment Simulator internal event.
Event handlers in scenarios are organized as labels followed by the code which
should be executed and the statement EXIT to leave the scenario at the end of
the handler.
Example of an OnDirectControl handler of a $ODLock$b1 data leaf:
OnDirectControl:
// call direct control done with success
DirectControlDone( #TRUE );
// set device locked status to device locked
// control and update quality descriptor and
// time tagging
BEGIN_UPDATE;
$ST$LockSt$b1 := $ODLock$b1;
$ST$LockSt$t := DATETIME;
$ST$LockSt$q := 0;
END_UPDATE;
// control termination with OK
ControlTermination( $AckCode, #CO_ACK_OK );
EXIT;
If the scenario which contains this handler is attached to the $ODLock data
object or the $ODLock$b1 data leaf, and a direct control operation is executed
for the data object or data leaf, the Equipment Simulator starts the handler
automatically.
The Equipment Simulator supports the following handlers in scenarios:
OnDirectControl
This handler is executed if a direct control operation is done by a
client. It can only be used for data objects and data leaves in a
server session.
OnSboSelect
This handler is executed if a SBO select operation is done by a
client. It can only be used for data objects and data leaves in a
server session.
OnSboDeselect
This handler is executed if a SBO deselect operation is done by a
client. It can only be used for data objects and data leaves in a
server session.
Equipment Simulator User Manual Scenarios 39
OnWrite
This handler is executed if the data object or data leaf the scenario
is attached to is written by a client. It can only be used for data
objects and data leaves in a server session.
OnControlTermination
This handler is executed if a direct control operation is terminated
by a server. It can only be used for data objects and data leaves in a
client session.
OnReportReceived
This handler is executed if a report is received for the appropriate
data object or data leaf. It can only be used for data objects and
data leaves in a client session.
OnWriteQuality
This handler is executed if a writequality is done by a client to the
data object or data leaf the scenario is attached to. It can only be
used for data objects and data leaves in a server session
OnGooseReceived
This handler is executed if a Goose is received for the appropriate
server or named bitpair. It can only be in a server session.
OnTime
This handler is executed when a scenario should be executed at a
specific time or periodically.
OnSimulationStart
This handler is executed when the simulation is started. The
handler is executed only once and only for scenarios which are
attached to device objects at the time the simulation is started. If a
scenario is started or attached during a simulation, the handler is
not executed.
Default
This handler is executed if no specific handler can be found for an
event. It can be used to handle different events equally.
The Equipment Simulator uses the following procedure to find and execute a
handler for an event:
It is checked if a scenario is attached to the data leaf or data object
for which the event has been detected.
If a scenario is found, it is checked if a handler for the appropriate
event can be found. If a handler is found, it is executed.
If the handler is not found, it is checked if a Default handler
exists. If a Default handler exists, it is executed.
The Equipment Simulator checks both the data leaf and the data object for
handlers in attached scenarios. Therefore you can assign a scenario to both the
$ODLock data object and the $ODLock$b1 data leaf for example. Both
attachments have the same affect when a UCA2 operation is done for the
$ODLock$b1 data leaf.
Note: Scenarios must be assigned to data objects or data leaves for UCA2 event
handlers to get executed. If a scenario is assigned at a higher level of the device
hierarchy (e.g. at functional component or brick level) handler are not executed
because the scenario code cannot determine for which data object or data leaf the
operation has been done.
Equipment Simulator User Manual Scenarios 40
If more than one scenario is assigned to a data leaf or data object, the Equipment
Simulator checks all these scenarios for handler and executes them if found.
In the OnDirectControl and OnSboSelect handler the scenario code
must call DirectControlDone() respectively SboSelectDone(). The
parameter to these statements is 1 if the result is success or 0 if the result is
failure.
Example:
OnSboSelect:
SboSelectDone( 1 );
EXIT;
If the Equipment Simulator does not find a handler for a direct control or SBO
select operation the DirectControlDone() and SboSelectDone()
statements are automatically called.
It can be configured, that the Equipment Simulator should call the
ODSDirectControlDone() and ODSSboSelectDone() services
automatically if not called by the scenario handler.
Choose Tools -Options... and select the Scenarios - Server Sessions
category:
If you want the Equipment Simulator to automatically call
ODSDirectControlDone() and ODSSboSelectDone() enable the
Call ODSDirectControlDone() and ODSSboSelectDone()
automatically if not called by the scenario handler option.
Similarly the scenario handler must call ControlTermination() with the
acknowledgement data leaf and the result code if a direct control handler is
executed.
Equipment Simulator User Manual Scenarios 41
Example:
OnDirectControl:
DirectControlDone( 1 );
ControlTermination( $CO$ODSw$AckCode, 0 );
EXIT;
If a scenario should be executed periodically, the Equipment Simulator executes
the OnTime handler of the scenario at the specified times. It is possible to mix
OnTime and other handler in one scenario.
If a scenario contains at least one handler, code which is located before the first
handler is never executed by the Equipment Simulator. The Equipment
Simulator always starts execution at the appropriate handler. If you want to
initialize local variables or data leaves you need to place the appropriate code
inside the corresponding handler. See the following code extract for an example:
/* This code is never executed */
%i := 1;
%k := 5;
%Oper = "Name";
/* The Equipment Simulator starts execution at the
appropriate handler */
OnDirectControl:
/* Initialization of local variables must be done
inside the handler */
%i := 1;
%k := 5;
%Oper = "Name";
DirectControlDone( 1 );
ControlTermination( $CO$ODSw$AckCode, 0 );
If more than one handler is present in a scenario, it is very important to leave the
scenario with an EXIT statement before the next handler is defined. Otherwise
the Equipment Simulator "falls through" and continues execution at the
following handler.
Example:
OnDirectControl:
DirectControlDone( 1 );
ControlTermination( $CO$ODSw$AckCode, 0 );
EXIT;
OnSboSelect:
SboSelectDone( 1 );
EXIT;
OnTime:
...
EXIT;
Equipment Simulator User Manual Scenarios 42
5.5.6 Other Topics
This section lists other issues and hints which can be helpful when using
scenarios.
The Equipment Simulator scenario language is case insensitive. Keywords,
variable names, UCA2 names, event handler names and named constants can be
written in lower case or upper case and mixed in any combination.
The scenario language supports literals or constants like other traditional
programming languages. Decimal and hexadecimal integers, floating point
values, strings, date and time constants are supported.
Examples:
3, 312, 0x1000, 4711.1147, "OPERATOR"
"01.01.2001 12:30:00"
The scenario language supports single line and multi line comments. A single
line comment is simply prefixed with the characters //. A multi line comment
starts with /* and ends with */.
For more information on literals, operators, expressions and built-in functions
see "Appendix B Scenario Language Reference" on page 110.
Equipment Simulator User Manual Preparing a Simulation 43
6. Preparing a Simulation
6.1. Preparing a Simulation - General
Before a simulation can be started a few preparation steps are necessary. This
chapter describes how these steps are performed.
The following sections assume that you have a configuration file opened.
Furthermore some basic knowledge on how to browse the device hierarchy and
work with data windows is required (see "The Equipment Simulator Window"
on page 13 for more details).
This chapter deals with the following main topics:
Selecting Server and Clients,
Attaching and Detaching Scenarios,
Initializing Data Leaves,
Preparing File Simulation.
6.2. Selecting Server and Clients
From the list of available servers on the station bus you have to select which
ones should be simulated by the Equipment Simulator and to which ones the
Equipment Simulator should connect in a client session.
If a server is simulated by the Equipment Simulator, this is called server mode, if
the Equipment Simulator connects to a server, this is called client mode.
To decide if a server should be simulated or if the Equipment Simulator should
connect to the server right click the server in the tree view of a data window and
select one of the following options:
Simulate Device as Server
Connect to Server
Deactivate Device
If you choose Deactivate Device the server is neither simulated nor does the
Equipment Simulator connect to the server.
Equipment Simulator User Manual Preparing a Simulation 44
You can also select the server and choose Simulation - Simulate Device as
Server, Simulation - Connect to Device or Simulation - Deactivate
Device from the menu or click one of the following symbols from the toolbar:
Symbol Simulation Mode
Act as a server
Act as a client
Do not simulate device
The same symbols are used in the tree view of the device structure to show if a
server is simulated, if the Equipment Simulator connects to the server or if the
device is deactivated.
The selection of server and clients is stored in the workspace file. Therefore this
preparation step is only needed once for a workspace file.
Note: The Equipment Simulator creates one UCA2 Agency server session for
every server simulated and one single UCA2 Agency client session for all
servers to which the Equipment Simulator should connect when the simulation is
started.
Equipment Simulator User Manual Preparing a Simulation 45
6.3. Attaching and Detaching Scenarios
By attaching scenarios to device objects the connection between the object and
the scenario is permanently stored in the workspace. Attached scenarios are
automatically started by the Equipment Simulator when the simulation is started
and stopped when the simulation is stopped.
Scenarios are normally attached to device objects during preparation of a
simulation. Because the attachment is stored in the workspace the simulation can
be started multiple times using the same scenarios without the need to start the
scenarios manually every time.
Attaching a scenario to a device object permanently binds the scenario to the
object. In contrast starting a scenario during simulation is a one-shot event. After
the scenario is finished or the simulation is stopped the scenario is automatically
detached from the device object.
Attaching a scenario to and detaching a scenario from device objects is only
possible before a simulation is started. During a simulation it is only possible to
start scenarios which are automatically detached when the simulation is finished.
Scenarios can be attached on any level of the device structure. Scenarios can be
attached to the station bus as a whole, to servers, logical devices, bricks,
functional components, data objects and data leaves. But it is necessary that the
Equipment Simulator can resolve all references to data leaves in the scenarios.
For example if a $CO$ODSw$OperDev data leaf is used in a scenario it can be
assigned to the $CO$ODSw$OperDev data leaf, the $CO$ODSw data object,
the $CO functional component and the brick the $CO functional component is in.
But the scenario cannot be attached to a server or logical device because the
Equipment Simulator does not know the brick the data leaf is in. See
"Referencing UCA2 Data Leaves" on page 36 for a more detailed description on
how data leaves can be referenced in scenarios.
Attached scenarios can be scenarios which are executed periodically (e.g. to
change a measurement) or contain event handlers which are executed when
UCA2 Agency service requests are received.
The scenarios which are attached to device objects are displayed in the right
pane of the device window:
Equipment Simulator User Manual Preparing a Simulation 46
If you select a device object in the tree view, the Equipment Simulator displays
the scenarios attached to the device object and its child objects in the scenario
list. The child objects of the next level of the device structure are displayed to
see for example the scenarios attached to a data object and its leaves at once. But
this rule applies on any level of the device structure (e.g. if you select a brick, the
scenarios attached to the brick and its functional components are displayed).
In the tree view, device objects which have scenarios attached to it change their
icon. A small sheet is displayed in the top right corner of the icon. For example
the icon for data objects changes from to if a scenario is attached to it or
one of its leaves.
Note: It is not possible to edit the scenario code from the data window. To edit
the scenario code switch to a scenario window or right click the desired scenario
and choose Edit Scenario. A scenario window is automatically opened and the
selected scenario displayed for modification.
The Equipment Simulator offers two ways to attach scenarios to device objects.
A simple method to assign a scenario to one single object and a bulk attachment
method to attach a scenario to multiple objects at a time.
Equipment Simulator User Manual Preparing a Simulation 47
6.3.1 Attaching Scenarios to Single Objects
To attach a scenario to a single device object, right click the desired device
object in the device tree view and choose Attach scenario.... The following
dialog is displayed:
From the combo box select the scenario you want to attach.
If you want the scenario to be executed periodically or at a specific time enter
the appropriate options in this dialog. By clicking OK, the scenario will be
attached to the device object.
6.3.2 Attaching Scenarios to Multiple Objects
To attach a scenario to multiple device objects, right click the device object from
which the automatic attachment should start (e.g. if you want to attach a scenario
to all $ODLock objects of a logical device, right click the logical device). From
the context menu choose Attach Scenario to Multiple Objects.... The
following dialog is displayed:
Equipment Simulator User Manual Preparing a Simulation 48
Beside the scenario name, the Equipment Simulator needs two components to
automatically attach a scenario to multiple device objects.
The first part is the UCA2 device structure level from which the Equipment
Simulator should start the attachment process. This can be any name starting at
station bus level, this means you must include the server name in the UCA2
name. This UCA2 name can contain the wildcard character * for every part of
the name.
Examples:
If you do not enter any name for the UCA2 device structure level
the Equipment Simulator searches the whole device structure for
data objects and data leaves the scenario should be attached to. This
means all servers are searched.
If you enter Srv1/LD1 all bricks on server Srv1, logical device
LD1 are searched.
If you enter Srv3/LD0/XCBR1$CO the Equipment Simulator
starts searching in the functional component CO of the brick
XCBR1 of the logical device LD0 of the server Srv3.
If you enter Srv1/*/XCBR the Equipment Simulator searches all
XCBR bricks on all logical devices of server Srv1.
The second part the Equipment Simulator needs for bulk attachment are the data
objects and/or data leaves the scenario should be assigned to. The Equipment
Simulator suggests the data objects and data leaves the selected scenario is
designed for (see "Scenarios" on page 24). In the above dialog example, the
$ODLock$b1 data leaf is suggested.
By clicking Add... and Remove in the above dialog it is possible to add or
remove data objects and data leaves the scenario should be attached to.
By selecting Preview Data Objects... it is possible to check which device
objects are affected by the attachment process prior to attachment. The
Equipment Simulator searches the device structure with the given parameters
and displays the found objects in the following dialog:
By clicking OK in the Attach Scenario to Multiple Objects dialog the
scenarios are attached to the affected objects.
Equipment Simulator User Manual Preparing a Simulation 49
6.3.3 Detaching Scenarios
To detach a scenario from a device object simply right click the scenario in the
right side of the data window and choose Detach Scenario.
If you want to detach multiple scenarios at once, right click the device object in
the device tree from which on you want to detach scenarios and choose Detach
Multiple Scenarios... or choose Scenarios Detach Multiple
Scenarios... from the main menu. The following dialog is displayed:
Choose the scenario you want to detach or Detach all scenarios and select
the device object from which you want to remove the scenario or select Detach
scenarios from all device objects.
According to your settings the Equipment Simulator searches through the device
structure and removes the scenarios which match your conditions.
Equipment Simulator User Manual Preparing a Simulation 50
6.4. Initializing Data Leaves
If you are simulating a server using the Equipment Simulator it could be useful
to initialize certain data leaves with predefined values before starting a
simulation (e.g. the data objects of the Device Identity brick).
Note: Initialization of data leaves for servers to which the Equipment Simulator
connects is not useful because the server stores the current values and the client
is notified about modified values by reports or actively reads the values from the
server.
To change data objects or data leaves simply right click the desired object or leaf
in the data window and choose Write Data Object... or Write Data Leaf....
You can select data objects both in the device tree view on the left side and in
the data view on the right side, data leaves can only be selected in the data view
on the right side.
Depending on the data object or data leaf selected a dialog similar to the
following one will be displayed:
The left side of this dialog displays the current values of the data leaves, on the
right side you can modify the leaves as desired. See "Displaying Data Objects
and Data Leaves" on page 65 (server and client modes) for a more detailed
description of how data objects and data leaves can be modified.
When a simulation is started, the Equipment Simulator initializes the data leaves
with the values last entered.
Equipment Simulator User Manual Preparing a Simulation 51
When a workspace is saved, the current values of all data leaves are stored
within the workspace file.
Note: If you want to do simulations with different start values for a lot of data
leaves you can create a workspace for every set of data values and switch
between the start values by loading the different workspaces.
6.5. Preparing File Simulation
The Equipment Simulator supports simulation of files both in server and client
mode.
In client mode the Equipment Simulator can be used to browse the directory
structure of the server, download and upload files and remove files on the server.
For servers to which the Equipment Simulator connects during a simulation no
preparation is necessary because all file related services are requested from the
server during simulation.
In server mode the directory and file structure must be prepared on the local file
system. The Equipment Simulator manages a "virtual" root directory for every
server simulated. Starting with this root directory a tree with subdirectories and
files can be set up which is accessible from clients on the network.
To configure the directory where the server specific virtual root directories
should be managed choose Tools - Options... and select the Simulation of
Files category.
In the Virtual root directory for simulation of files enter the directory
where the Equipment Simulator should store files for simulation.
Note: During installation a subdirectory called Server Files is created
under the Equipment Simulator installation directory. By default, this directory
is used as virtual root directory for the simulation of files.
For every server simulated, the Equipment Simulator creates a subdirectory with
the name of the server. These directories act as root directories for the simulated
server.
Equipment Simulator User Manual Preparing a Simulation 52
For example if files should be stored in C:\UCA2 Agency\Root and the
name of the server is SRV1, the "virtual" root directory of the server is
C:\UCA2 Agency\Root\SRV1. All file requests from clients to SRV1 are
mapped to this root directory.
To populate the directory with files and subdirectories you can use the
Windows Explorer or any other file manager. Simply copy the desired files
into and create subdirectories in the "virtual" root directory of the server.
Additionally the Equipment Simulator has some support to set up a directory
structure built in. To display and modify the directory structure of a server select
the Files object in the tree view of a data window.
The Files object in the tree view corresponds to the "virtual" root directory of
the server. The Equipment Simulator hides the details about where this directory
is stored on the disk from the user.
Note: To display a directory structure, the affected server must be configured to
be simulated by the Equipment Simulator. If the server is deactivated or should
be simulated in client mode, no directory structure can be displayed. To
configure the server to be simulated right click the name of the server and choose
Simulate Device as Server from the context menu.
You can browse through the directory structure, as you know it from the
Windows Explorer.
The Equipment Simulator offers the following file management functions:
Create directory
To create a new directory right click the file view on the right side
of the data window, choose New - Directory and enter the name
of the new directory.
Create file
To create a new file right click the file view on the right side of the
data window, choose New - File and enter the name of the new
file. The Equipment Simulator creates an empty file with the
specified name.
Delete file or directory
Right click the file or directory you want to delete and choose
Delete or press <Del>.
Rename file or directory
Right click the file or directory you want to rename and choose
Rename.
Equipment Simulator User Manual Preparing a Simulation 53
If you modify the directory structure outside of the Equipment Simulator you
can choose Files - Refresh or press F9 to update the directory structure in the
Equipment Simulator.
From the directory structure you can directly start an application to view or
modify a file. The Equipment Simulator manages a list of file viewers which you
can configure by choosing Tools - Options... and selecting the Simulation
of Files category.
You can add your own viewers to this list by clicking Add and entering a name
for the viewer. For every viewer you add, you must enter the name of the
executable to start (including the path) and the arguments which should be
passed to the application. The placeholder %s is used to insert the name of the
file which should be viewed into the parameter list passed to the application.
To view or modify a file, right click the file in the data window and choose
View - <Name of the Viewer>....
The Equipment Simulator starts the viewer to display the selected file.
Equipment Simulator User Manual Starting and Stopping a Simulation 54
7. Starting and Stopping a
Simulation
7.1. Starting and Stopping a Simulation General
This chapter deals with the following main topics:
Starting a Simulation,
Stopping a Simulation,
Generation of Object Definition, Data Model and UCA2 Agency
Configuration Files.
7.2. Starting a Simulation
After you have finished the preparation steps, described under "Preparing a
Simulation" on page 46, you can start a simulation.
Choose Simulation - Start, press F5 or click the symbol on the toolbar to
start a simulation.
The Equipment Simulator starts a simulation by performing the following tasks:
For every server simulated and every server the Equipment
Simulator connects to a object definition file is dynamically created
from the device structure.
For every object definition file the OdFoundry tool is called to
generate the data model files needed by the UCA2 Agency.
All scenarios which are attached to device objects and must be
started during simulation start are syntax checked.
The data leaf references of all scenarios attached to device objects
are resolved.
The UCA2 Agency is started and initialized.
For every server a UCA2 Agency server session is started and
initialized.
For all servers the Equipment Simulator should connect to a single
client session is started and initialized.
Equipment Simulator User Manual Starting and Stopping a Simulation 55
The Equipment Simulator automatically subscribes to all reports
offered by the server that the Equipment Simulator connects to, as
soon as the connection is active.
The OnSimulationStart handlers of all attached scenarios are
executed.
If an error occurs in one of these steps the simulation start is cancelled and the
error reason is displayed.
If a syntax error is detected in a scenario or data leaf references in a scenario
cannot be resolved, the Equipment Simulator automatically jumps to the faulty
scenario and displays the line where the error occurred.
After the simulation is started, you are able to simulate UCA2 operations (see
"Simulation of UCA2 Operations" on page 65, "Simulation of Files" on page 89
and "Simulation of goose" on page 92 for more details).
7.3. Stopping a Simulation
When you have finished with your simulation simply choose Simulation -
Stop, press <Ctrl>+F5 or click the symbol on the toolbar.
The Equipment Simulator stops all client and server sessions and terminates the
UCA2 Agency.
Scenarios which were started during the simulation are detached from their
device objects. Only Scenarios which were attached before a simulation remain
attached to their respective device objects.
7.4. Generation of Object Definition, Data Model and
UCA2 Agency Configuration Files
This section describes the internal procedures of how the Equipment Simulator
dynamically generates the environment for the UCA2 Agency. The section is
primarily not intended for the end user but it may be useful to understand what is
going on in the background if something goes wrong during the generation of
this environment.
The following sections describe the steps the Equipment Simulator performs to
configure the UCA2 Agency and generate the data model files needed.
Depending on the configuration settings Remove temporary UCA2 Agency
configuration files after simulation and Remove temporary Object
Foundry files after simulation the Equipment Simulator automatically
removes the dynamically generated configuration and data model files or not.
The options can be found in the UCA2 Agency Settings- General and
Object Foundry Settings - General categories in the configuration settings
under Tools - Options....
Not removing the files can be useful to investigate them when there is a problem
generating the data model files or starting the UCA2 Agency.
Equipment Simulator User Manual Starting and Stopping a Simulation 56
7.4.1 LEAN.CFG
The network configuration file is dynamically generated from the settings
defined in the Equipment Simulator and the devices which should be simulated.
The configuration settings can be displayed and modified using Tools -
Options....
Under the category UCA2 Agency Settings - Network Configuration File
the SISCO Stack Parameters, the Local Server Parameters and the
Remote Server Parameters can be configured.
The SISCO Stack Parameters and the Local Server Parameters are taken over
unchanged to the network configuration file. The Remote Server Parameters
must contain placeholders for the server name, AE qualifier and IP address. This
parameters are automatically replaced with the appropriate settings from the
XML configuration file when the Equipment Simulator generates the network
configuration file. The Equipment Simulator creates a remote server entry in the
network configuration file for every client or server simulated.
Normally you need not change any of the above settings. The Equipment
Simulator has default settings built in, which should be suitable in most cases.
The network configuration file is always named LEAN.CFG and is created in the
UCA2 Agency directory configured under Tools - Options... in the UCA2
Agency Settings - General category.
Equipment Simulator User Manual Starting and Stopping a Simulation 57
7.4.2 AGENCY.CFG
The agency configuration file does not contain any dynamic components. The
file is created without any modification from the settings in the UCA2 Agency
Settings - Agency Configuration File category under Tools - Options....
The Equipment Simulator has default settings for the agency configuration file
built in. If these settings do not suit your needs you can modify them as needed.
For example if you are simulating a large number of servers you may need to
increase the MaxServerSession parameter which is 3 by default. See the
MiCOM SYSTEMS UCA2 Communications Agency - Installation Guide for a
detailed description of all UCA2 Agency parameters which can be influenced
using the agency configuration file.
The agency configuration file is always named AGENCY.CFG and is created in
the UCA2 Agency directory configured under Tools - Options... in the UCA2
Agency Settings - General category.
Equipment Simulator User Manual Starting and Stopping a Simulation 58
7.4.3 MMS_LOG.CFG
The MMS log configuration file does not contain any dynamic components. The
file is created without any modification from the settings in the UCA2 Agency
Settings - MMS Log Configuration File category under Tools -
Options....
The Equipment Simulator has default settings for the configuration file built in.
If these settings do not suit your needs you can modify them as needed. See the
MiCOM SYSTEMS UCA2 Communications Agency - Installation Guide for more
details on the MMS log configuration file.
The MMS log configuration file is always named MMS_LOG.CFG and is created
in the UCA2 Agency directory configured under Tools - Options... in the
UCA2 Agency Settings - General category.
7.4.4 Generation of Data Model Files
When using a stand-alone XML configuration file, the Equipment Simulator
creates data model files device which should be simulated at the start of the
simulation. This generation is done in two steps:
1. Generation of the object foundry files.
2. Generation of the data model files.
When stopping the simulation/restarting it with the same devices to simulate,
Data Model files are not rebuilt.
When using a configuration from an SCE zip file, the equipment simulator uses
directly the Data Model files included in the zip file.
Equipment Simulator User Manual Starting and Stopping a Simulation 59
7.4.4.1 Object Foundry Files
When using a stand-alone XML configuration file, the Equipment Simulator
creates an object foundry file for every device which should be simulated.
At the beginning of every object foundry file the Equipment Simulator places the
execution control settings configured in the Object Foundry Settings -
Execution Control category under Tools - Options.... The default execution
control settings delivered with the Equipment Simulator should be suitable in
most cases and need no modification.
Then all basic types, common classes, bricks, etc., a device consists of, are
dynamically generated and appended to the object foundry file.
Because the type ids of basic types, common classes and some bricks generated
by the object foundry tool must exactly match the ids used by the UCA2 Agency
a predefined order of types must be retained by the Equipment Simulator when
generating the object foundry files.
A configuration file is used for this purpose. This configuration file, which is
normally named BASTYPES.CFG, lists all types together with their predefined
id,. When generating the object foundry file for a specific device, the Equipment
Simulator ensures that the object foundry will generate the ids listed in the file
by generating the types in the needed order.
The configuration file used can be configured in the Object Foundry
Settings - General category under Tools - Options....
If the predefined type ids are modified in the UCA2 Agency a new
BASTYPES.CFG file must be generated and used with the Equipment
Simulator.
7.4.4.2 Data Model Files
For every object foundry file generated, the Equipment Simulator executes the
object foundry tool to create the associated data model files.
An alignment control file is generated for this purpose which consists of the
contents configured in the Object Foundry Settings - Alignment Control
category under Tools - Options.... As for most other settings the built in
default alignment control should be suitable in most cases.
After the object foundry tool is finished, the Equipment Simulator scans the
generated data model files to extract the data ids needed for the communication
with the UCA2 Agency.
Equipment Simulator User Manual Simulation of UCA2 Operations 60
8. Simulation of UCA2
Operations
8.1. Simulation of UCA2 Operations - General
This chapter describes how to investigate and modify data objects and data
leaves and how to perform operations available through the UCA2 Agency.
The first two sections show how data object and data leaf values are displayed in
data windows and how they can be modified. Both sections are useful in both
server and client mode.
The following main topics describe UCA2 operations, organized by server and
client mode:
Displaying Data Objects and Data Leaves,
Modifying Data Objects and Data Leaves,
Server Operations,
Client Operations.
8.2. Displaying Data Objects and Data Leaves
Data windows can be used to browse through the device structure in both server
and client mode. If a functional component or data object is selected, the data
leaves belonging to the data objects of the functional component or the selected
data object are displayed in the data window.
In the following example all data objects and data leaves of the functional
component ST of the GLOBE brick are displayed.
Equipment Simulator User Manual Simulation of UCA2 Operations 61
If the Equipment Simulator is acting in client mode and the connection to the
server is active all data objects and data leaves are displayed in black color like
in the above example.
If the connection is inactive, all data objects and data leaves are displayed in
gray color. Using different colors for active and inactive connections makes it
easy to identify broken connections.
See the following example for a client which has no connection to the server.
If the Equipment Simulator is simulating a server, the data leaf values are
fetched from the local device database, if acting in client mode, the data leaf
values are read from the server.
On the client side, if the displayed data leaves have not been read at least once
on the server during the simulation, their values can be masked (please refer to
"Reading mode" on page 67 for more details) and they are displayed in brown-
yellow color.
Equipment Simulator User Manual Simulation of UCA2 Operations 62
8.2.1 Reading mode
A reading mode is the policy the Equipment Simulator uses when it is simulating
a client to read the data objects and data leaves on the server.
There are 3 different reading modes:
The values of the data leaves are read as soon as the data leaves are
displayed in the right panel. This mode is called "automatic
reading".
The values of the data leaves are read on request. The user triggers
a reading request when he wants. Even data leaves (or any objects
from a device being simulated as client), which are not displayed,
can be read on a reading request.
The values of the displayed data leaves are periodically read
(period polling is configurable). Timer starts counting when the
data leaves are displayed.
Reading mode must be defined for every simulated client and each client has its
own reading mode. For instance, 2 components from a same device cannot have
2 different reading modes at the same time.
Besides, one client device displayed in 2 different views of the Equipment
Simulator is bound to have the same reading mode in the 2 views.
Equipment Simulator User Manual Simulation of UCA2 Operations 63
8.2.1.1 Configuration
The configuration of the reading mode is possible when the device is not marked
to be simulated as server (see following screen shot).
Only one mode can be simultaneously selected. The current mode is the checked
one.
When the Periodic Polling mode is being checked, a popup window appears to
specify the period of the polling.
If you want to enable Periodic Polling, mind checking the Active Periodic
Polling checkbox. If you uncheck this checkbox and click OK, the current
reading mode becomes On Request Reading.
There is a default mode configurable in the tools options panel. The default
mode applies to all the devices simulated as client.
Equipment Simulator User Manual Simulation of UCA2 Operations 64
A mask can be defined and activate to hide values which have not been read on
the server side. In the following screen shot, values, which have not been read,
are masked.
It is possible, in the reading configuration panel, to define a range of UCA2
components for which automatic reading and periodic polling are disabled.
These data are marked as they cannot be read (they are called unreadable). For
instance, it is possible to disable reading for CO and SP functional components
and for some or all of their components (data objects and data leaves).
Here after there are some samples to explain how to disable reading for some
components.
Exemple 1: $DLName
The reference is always the UCA2 data leaf name. So, in this example, all the
data leaves called DLName will be marked as unreadable.
Example 2: $FCName$DO3Name$DL2Name
In this sample, all the data leaves called DL2Name in the data objects called
DO3Name, which are in functional components called FCName must be marked
as unreadable.
Equipment Simulator User Manual Simulation of UCA2 Operations 65
Example 3: /BrickName$ DL5Name
In this third example, all the data leaves called DL5Name and directly under
bricks called BrickName are marked as unreadable.
Example 4: $Name4$*
* is a wildcard. For instance, in the current sample, all the data leaves under an
UCA2 component called Name4 (which can be either a data object or a
functional component) are marked as unreadable.
Example 5: $FCName$*$*
In this example, all the data leaves of all the data objects of the functional
components called FCName are marked as unreadable.
8.2.1.2 Start-up
At the start-up of the simulation:
The components, which must not be read (the list is fetched from
the array of unreadable data leaves of the reading configuration
panel), are marked.
Reports are activated and data leaves involved in report operations
are marked as read is matching report is received.
There are some data leaves which are marked as unreadable and then, reports are
activated and received. For instance, in this screen shot, the functional
component ST has received report and this is why the values are displayed in
black color.
Note: All data leaves involved in a report are read. The fact to mark a data leaf
as "unreadable" whereas it is involved in a report is allowed but will not be taken
into account at simulation runtime.
Equipment Simulator User Manual Simulation of UCA2 Operations 66
8.2.1.3 Automatic Reading
When enabled, automatic reading is triggered once when data leaves are being
displayed in the right panel. Every time the display in the right panel is refreshed
to show data leaves, automatic reading is done.
In this mode, reading is done when:
Data are not marked as unreadable. If a functional component is
marked as it cannot be read, all its sub-devices are not read. If a
particular sub-device of a component is marked as unreadable, all
the other sub-devices of the component are read but not the one
marked as unreadable.
Data must be displayed in the right panel.
8.2.1.4 Periodic Polling
Polling reading starts when new data are displayed in the right panel in periodic
polling mode. The Periodic Polling menu item must be checked.
Polling reading, once it has been triggered, lasts until the user changes the
objects displayed in the right panel. Then, if there are no more displayed objects
involved in Periodic Polling left, polling reading is stopped and waits for a next
trigger.
Like automatic reading, periodic polling does not read objects marked as
unreadable.
8.2.1.5 On Request Reading
In this mode, reading is done when user chooses to do a reading. This command
is available via the Operations menu and pop-up menus (right click) on the
tree view.
When On Request Reading is the selected reading mode, any kinds of
components can be read except server components (for instance, HMI server
cannot be read). So it is possible to read data, which are not displayed in the
right panel (sending a read request from a logical device for instance).
Equipment Simulator User Manual Simulation of UCA2 Operations 67
The On Request Reading is the only way to read values from objects marked as
unreadable. In this case, the request must be sent from the object himself and the
command is titled FORCE Reading Values instead of Read Values.
Thus, sending a request from a component will not read its sub-components
marked as unreadable but will read all the others sub-components not marked as
unreadable. In such cases, UCA2 operation will be a sequence of read data leaf
operations.
In the previous screen shot, it is possible to read the data object ODMode. This
data object has a SBO data leaf marked as unreadable. So sending a request
order from this data object will read all its data leaves except SBO data leaf. The
UCA2 operation is not anymore a Read data object operation but a sequence
of read data leaf operations.
On the SBO data leaf, the command is titled FORCE Read values and using
this command will read the SBO data leaf (whereas it is marked as unreadable).
Equipment Simulator User Manual Simulation of UCA2 Operations 68
8.2.2 Illustration of modified Data Leaves
If data leaves are modified by remote devices, the appropriate leaf values are
displayed in a different color for a few seconds. Using this method it is easy to
see updates from remote devices without investigating the log.
The highlighting technique is used both in server and client mode. In server
mode if a client is modifying a data leaf, which can be the result of a simple
write operation or a control operation like direct control, the leaf is displayed in a
different color. In client mode if a data leaf is modified on the server and a report
is issued to the client, the modified leaves are also highlighted. Because the
Equipment Simulator automatically activates all reports a server offers in client
mode, the client is notified about all modifications.
Two different colors are used to illustrate modified data leaves.
If the Equipment Simulator receives a notification about a modified data leaf and
the value is different from the previous value, the appropriate lines in the data
window are displayed in red.
If the Equipment Simulator receives a notification about a modified data leaf but
the value is equal to the previous value, the Equipment Simulator illustrates the
data leaves in blue.
Equipment Simulator User Manual Simulation of UCA2 Operations 69
8.2.3 User Readable Names
To make data leaf values more readable, the Equipment Simulator supports a
technique called user readable names.
Using this method, values of data leaves can be displayed in text form instead of
in simple decimal or hexadecimal form. For example a quality data leaf which
has the value 0x000a can be displayed in the more descriptive form 0x000a -
Invalid, Forced.
In the following example user readable names are used for the q and tq data
leaves.
User readable names are supported for the following UCA2 primitive data types:
BOOL, BSTRx, VBSTRx, ENUM8 and ENUM16.
The Equipment Simulator distinguishes between enumerations and bit strings
when using user readable names. Enumerations are used to give a certain value
of a data leaf a name (e.g. On for 0x40 in a b2 data leaf). Bit strings are used to
give a name to every bit in a bit array (e.g. Forced and Invalid for a quality
descriptor).
Note: The Equipment Simulator does not have any built in associations of data
leaf values to user readable names. User readable names must be configured in
the UserReadableValueNamesList section of the XML configuration file
(see "Configuration Files" on page 20 for more information about device
configuration files). Without appropriate entries in the configuration file, user
readable names cannot be used.
The usage of user readable names can be configured. Choose Tools -
Options... and select the General category to change the configuration for user
readable names:
Equipment Simulator User Manual Simulation of UCA2 Operations 70
By enabling or disabling the Display user readable names for bit strings
and enumerations you can enable or disable user readable names. If disabled,
data leaf values are displayed in decimal or hexadecimal form only.
If the option is active, you can enable the Display numeric value beside
user readable name to show both numeric value and user readable name. If
disabled only the user readable name is displayed in data windows.
8.3. Modifying Data Objects and Data Leaves
Data objects and data leaves can be modified in both server and client mode. The
Equipment Simulator supports different techniques and input methods for the
varying UCA2 data types which are described in this section.
Basically the Equipment Simulator supports two methods to modify data objects
and data leaves: Quick modification using context menus and complete
modification using dialogs.
8.3.1 Complete Modification using Dialogs
Using dialogs for modification you can modify all types of data leaves (quick
modification is only supported for bit strings and enumerations). Furthermore all
data leaves of a data object can be modified at once.
To modify a data leaf right click the leaf in the data window and choose Write
Data Leaf... from the context menu.
To modify a data object right click the object in the data window and choose
Write Data Object.... You can select the data object in both the device tree
view on the left side and the data view on the right side of a data window.
Equipment Simulator User Manual Simulation of UCA2 Operations 71
Depending on the selected data object or data leaf, different dialogs are
displayed for modification. In the following example a data object of class SIT
is modified:
On the left side of modification dialogs the current values of all data leaves are
displayed. On the right side you can modify the data leaves as you desire.
Depending on the data type of the leaves different methods are used to display
and modify values.
For data leaves of type integer, floating point, string or bit string and
enumeration without user readable names, simple text boxes are used to display
and modify their values.
For bit strings with user readable names, the names are used to display and
modify data leaves.
Equipment Simulator User Manual Simulation of UCA2 Operations 72
For bit string data leaves both the hexadecimal value and its user readable
representation are used.
If more than one bit is set in the current value, the combo box with the user
readable names contains three dots (...). If you click the arrow at the right of the
value, all bits which are set are displayed.
In the new value section you can either enter the numeric value or choose from
the user readable names in the combo box. If you enable the Multiple
Selection option, you can add or remove bits from the value by opening the
combo box and selecting the desired value. If the Multiple Selection option is
disabled, only the selected bit is set, all other bits are set to zero.
For enumerations with user readable names, the display and input method
corresponds to the one used for bit strings with the exception that only one value
is displayed and can be selected whereas in bit strings more than one bit can be
chosen.
For data leaves of type date and time, the date, time and milliseconds portions
are modified individually.
If you enable the Use current time option, the data leaf is set to the current
local time. The controls to input the date and time value are disabled in this case.
IMPORTANT NOTE:
Please refer to "Appendix A Bitstrings Use" on page 108 for more details on
how Bitstrings data are managed in Equipment Simulator.
Equipment Simulator User Manual Simulation of UCA2 Operations 73
8.4. Server Operations
In server mode you can modify data objects and data leaves and terminate
control operations.
8.4.1 Modifying Data Objects and Data Leaves
To modify data objects and data leaves the functions described in "Modifying
Data Objects and Data Leaves" on page 75 (server and client modes) can be
used.
If data objects or data leaves are modified, the Equipment Simulator forwards
the changes automatically to the UCA2 Agency. If the modified data object or
data leaf is part of a report, the overall data object modified is sent to active
clients by the UCA2 Agency (if the clients have activated the appropriate
reports). If the data objects or data leaves are not part of a report, the clients are
not notified about the modifications.
8.4.2 Reason For Inclusion
A Reason For Inclusion is always added when a data object or a data leaf is
modified via the graphical user interface.
The default value of Reason For Inclusion can be modified with Tools
Options and Reason For Inclusion.
Equipment Simulator User Manual Simulation of UCA2 Operations 74
You can select multiple default value for Reason For Inclusion. If 0x00 (none) is
selected, all the previous selected values are reset.
8.4.3 Control Termination
To simulate a control termination operation, simply right click the AckCode
data leaf of the data object the operation should be applied to, select the Control
Termination submenu and choose the desired result code.
If more than one client is connected to the server you also have to select the
client to which the control termination should be sent.
If no client is connected to the server, control termination is not possible.
Equipment Simulator User Manual Simulation of UCA2 Operations 75
8.4.4 Disable associations
In order to simulate the absence of a server, you can disable any client
association to it.
For this, right click on a server in the device tree to get the server contextual
menu and choose Disable associations. This is a toggle menu item, so you
re-enable the associations with the same operation.
Equipment Simulator User Manual Simulation of UCA2 Operations 76
8.5. Client Operations
If the Equipment Simulator is connected to a remote server (client mode) you
can read and write data objects and data leaves, and perform write quality and
control operations.
8.5.1 Reading Data Objects and Data Leaves
The Equipment Simulator reads data objects and data leaves as you browse
through the device structure of a server. For example if you select a data object
in the device tree view the data leaves are automatically read from the server and
displayed in the data window.
Additionally if you want to refresh an already displayed data object or data leaf
you can manually initiate a read operation. Right click the desired data object or
data leaf and choose Read Data Object... or Read Data Leaf... from the
context menu.
8.5.2 Modifying Data Objects and Data Leaves
To modify data objects and data leaves the functions described in "Modifying
Data Objects and Data Leaves" on page 75 (server and client modes) can be
used.
The Equipment Simulator automatically writes the modified data objects or data
leaves to the appropriate server.
Note: The client data objects and data leaves are not updated whereas the server
data objects and data leaves are updated. To update the values on the client side,
a read operation must be processed or the server must send reports (to be done in
scenarios).
Equipment Simulator User Manual Simulation of UCA2 Operations 77
8.5.3 Write Quality and Control Operations
The Equipment Simulator can perform write quality and control operations for
certain data objects and data leaves.
The data objects and data leaves for which those operations are offered and some
general settings for UCA2 client operations can be configured in the Equipment
Simulator. To examine and if necessary change the settings choose Tools -
Options....
Select the Simulation of Control Operations - General category.
Every control operation is provided with an user name and origin. Using the
above settings you can ask the Equipment Simulator to suggest the name of the
currently logged on user for the operator name and the computer name for the
origin.
Select the Simulation of Control Operations - Write Quality category.
Equipment Simulator User Manual Simulation of UCA2 Operations 78
Using this category you can define for which data objects and data leaves the
write quality operation should be offered. By adding an entry with the names of
the value data leaf and a quality descriptor data leaf you can make the write
quality operation available for the data object.
Use the Add..., Modify... and Remove buttons to adjust the list to your needs.
If you choose the Default Settings button, the Equipment Simulator sets the
list to a built-in default.
Similar settings like the ones for write quality are necessary for direct control,
SBO select and SBO deselect operations. You can configure the appropriate data
objects and data leaves using the Simulation of Control Operations -
Direct Control and Simulation of Control Operations - Select Before
Operate categories. For SBO control operations, the last column in the list view
is an optional column.
In the previous picture, the Control Type Data Leaf is an optional entry. It
can be empty. In this case, it is impossible to enter a value when sending an SBO
operation.
To perform a control operation, right click the desired data object or data leaf
and choose Write Quality..., SBO Select..., SBO Deselect... or Direct
Control... from the context menu.
Depending on the operation you have chosen you have to enter a value or a
quality and the operator name, origin and timestamp values.
Equipment Simulator User Manual Simulation of UCA2 Operations 79
See the following example for an SBO operation.
Note: For SBO operations, depending on your configuration, it is possible to
enter a Value as control type parameter. When the Value entry is available, you
can type or not a value. Entering a value is not mandatory. The value displayed
by default is the value of the Control Type Data Leaf. If you do not want to
write the control type anyway, clear this field.
8.5.4 Time Synchronization
You can activate or deactivate time synchronization by selecting a device which
is simulated as client and choose Time Synchronization - Activate or Time
Synchronization - Deactivate from the context menu.
Equipment Simulator User Manual Simulation of Redundancy 80
9. Simulation of Redundancy
9.1. Simulation of Redundancy - General
The Equipment Simulator can help to the simulation of redundancy (server side)
by switching a server from active mode to standby mode and vice-versa.
9.2. Modifying the Current Redundancy Status
Only current redundancy status of Redundant servers can be modified. The
status can be changed from standby to active and vice-versa. Mark a server as
active is equivalent to put the value of the $ST$RedSt$b1 dataleaf of the Diag
brick in the LD0 logical device to 0x80. Mark a server as standby is the same as
put this value to 0x00. There are 3 ways to do it:
Directly change the value of the redundancy status dataleaf.
Use the toolbar buttons to switch from standby to active and
reverse.
The button sets the status of the server to standby. This button is available
only when the current status of the server is active. Applying this button is
equivalent to change the value of the data leaf LD0/xDiag$ST$RedSt$b1 to 1
(0x80).
The button sets the status of the server to active. This button is available
only when the current status of the server is standby. Applying this button is
equivalent to change the value of the redundancy status dataleaf to 0 (0x00).
These 2 buttons are active only one at the same time and only when a server is
selected.
Use the pop-up menu of the server (which appears on right click on the server
item in the tree view). There are the two same buttons as ones in the toolbar.
Equipment Simulator User Manual Simulation of Redundancy 81
Equipment Simulator User Manual Simulation of Files 82
10. Simulation of Files
10.1. Simulation of Files - General
The Equipment Simulator can simulate UCA2 file management services in both
server and client mode. In server mode all file requests from clients are directed
to a "virtual" root directory, in client mode you can browse through the directory
structure on the server, upload and download files and remove files from the
server.
This chapter deals with the following main topics:
Server,
Client.
10.2. Server
If a server is simulated by the Equipment Simulator all file requests from clients
are automatically redirected to a "virtual" root directory on the local disk.
If the directory structure has been fully set up during preparation of a simulation
no further actions are necessary during the simulation itself. The file requests are
redirected by the Equipment Simulator without user intervention.
During a simulation you can modify the directory structure (e.g. add, change or
remove files and directories) in the same way you do it during preparation of a
simulation.
See "Preparing File Simulation" on page 54 for a detailed description on how to
set up and modify the directory structure of a simulated server.
Equipment Simulator User Manual Simulation of Files 83
10.3. Client
If you are connected to a server you can browse the directory structure of the
server by simply selecting the Files object or a subfolder in the data window
tree view.
You can browse through the directory structure, as you know it from the
Windows Explorer or other file managers.
If you want to refresh the currently displayed directory to include possible
changes on the server, right click the file view on the right side and choose
Refresh or press F9.
Using the Equipment Simulator you can put a file to a server, get a file from a
server or delete a file on a server.
10.3.1 Put File to Server
To copy a local file to a remote server, right click the file view and choose Put
File to Server....
On the left side of this dialog you can select the Destination directory and the
Destination file name on the server. If you want the file to have the same
name it has on the local file system, enable Use same file name.
On the right side of this dialog choose the local file you want to transfer to the
server.
Choose Put File to copy the selected file to the server.
Equipment Simulator User Manual Simulation of Files 84
10.3.2 Get File from Server
To copy a file from a server to the local file system, right click the desired file in
the file view and choose Get File from Server....
Choose the directory and file name on the local file system and select Save to
get the file from the server.
10.3.3 Delete File
To delete a file on a remote server, right click the desired file in the file view and
choose Delete or press <Del>. The Equipment Simulator removes the selected
file on the server.
Equipment Simulator User Manual Simulation of goose 85
11. Simulation of goose
11.1. Simulation of goose - General
The equipment simulator is able both to send and receive goose.
This chapter deals with the following main topics:
Starting a simulation with goose,
Receiving goose,
Sending goose.
11.2. Starting a simulation with goose
Due to limitations on the goose protocol and on the UCA2 agency, only one
server is able to use goose on one computer (either receiving or sending).
So, when starting a simulation with more than one server configured with goose,
you must choose the server that will have the goose active. The following
window is an example of the window you get.
Select one server and click OK to start the simulation.
When the simulation is running and a server is using goose, this server gets a
special icon in the device tree (this is a flying goose).
Equipment Simulator User Manual Simulation of goose 86
11.3. Receiving goose
Data in "Incoming goose" for one server are displayed by selecting the item
incoming goose in the device tree for this server.
The data view displays the list of incoming goose items with all the needed
information.
It is also possible to view only incoming coming from one particular server by
selecting this server item located under the incoming goose in the device tree.
Scenarios can be attached to a server item or to an incoming item displayed in
the data window. (See "Scenarios" on page 24 to know what can be done in the
scenario with incoming goose).
Equipment Simulator User Manual Simulation of goose 87
11.4. Sending goose
Outgoing goose can be attached to data objects of class SI or SIT.
When a data object has an outgoing goose attached to it, a G is added to its icon
in the device tree.
An outgoing is sent in the two following cases:
When you modify the data object with an outgoing goose using the
HMI. (Either write data object or write data leaf on any leaf of
the object).
When a scenario has modified a data leaf of a data object with an
outgoing goose and calls the END_UPDATE instruction
Equipment Simulator User Manual Using Scenarios during Simulation 88
12. Using Scenarios during
Simulation
12.1. Using Scenarios during Simulation - General
This chapter describes how scenarios are used during a running simulation.
Scenarios which are attached to device objects can be observed using the
scenario status view. Furthermore scenarios which were not attached to device
objects at the start of a simulation can be started, and running or attached
scenarios can be stopped.
This chapter deals with the following main topics:
The Scenario Runtime Engine,
Scenario Status View,
Starting and Stopping Scenarios.
12.2. The Scenario Runtime Engine
The scenario runtime engine is the component of the Equipment Simulator
which is responsible for the execution of scenarios.
Scenarios which are attached to device objects or are currently running are
managed by the runtime engine.
12.2.1 Status of Scenarios
The scenario runtime engine manages a state for every scenario. This state
controls how a scenario is handled by the runtime engine.
Every scenario is in one of the following states:
Waiting
The scenario is currently not running but is waiting for execution.
This state is used for scenarios which contain event handlers. This
scenario is started if an event for which the scenario has a handler
defined is processed.
Ready
The scenario is currently not running but is already scheduled for
the next start. This state is only applicable for scenarios which are
executed periodically. After the runtime engine has determined the
next start time from the periodic execution settings, the scenario is
moved into the ready state waiting for the start time to be reached.
Equipment Simulator User Manual Using Scenarios during Simulation 89
Ready + Waiting
The ready and waiting states can be combined if the scenario is
both waiting for events and should be executed periodically.
Running
The scenario runtime engine is currently executing the scenario.
This is normally the result of a periodic start or the start of an event
handler.
Running + Waiting
An instance of the scenario is currently running but the scenario is
still ready for further starts. This state combination is used for
scenarios which contain event handler where one event handler is
currently executing and the scenario is ready for further events.
Finished
The scenario has been terminated. This can be the result of
manually stopping the scenario, a runtime error or the termination
of periodic execution.
The status of a scenario is displayed in the scenario status view (see "Scenario
Status View" on page 101).
12.2.2 Execution of Scenarios
An execution interval is used to run scenarios. This interval is given in
milliseconds and controls the time the Equipment Simulator waits between the
execution of two consecutive statements in the scenario code.
For example if the execution interval is 20 milliseconds, the runtime engine
executes statement by statement with a break of 20 milliseconds between the
statements. The interval controls only the break after a statement is finished until
the next statement is started. The duration needed to execute a statement must be
added to calculate the total time needed by a statement. This time may vary
depending on the type of statement executed. For example a UCA2 operation
like a direct control operation takes longer than a simple assignment because
network communication is necessary.
The real execution interval may also vary with the current workload which for
example depends on other applications running on the system or the number of
scenarios started. The execution interval can be seen as a minimum break
between two consecutive statements in a scenario.
The execution interval can be configured (see "Configuration" on page 98).
Larger execution intervals execute scenarios slower, smaller execution intervals
execute scenarios faster.
If the runtime engine is executing multiple scenarios at the same time all
scenarios are handled with the same priority.
12.2.3 Runtime Errors
If the runtime engine discovers a runtime error during the execution of a
scenario, the scenario is terminated.
Runtime errors can occur if the scenario code is incorrect, a UCA2 server is not
answering or the UCA2 Agency returns an error.
Examples for runtime errors are: Division by zero, data type mismatch in an
expression or assignment, timeout in an UCA2 operations, etc.
If a scenario is terminated the reason is displayed in the scenario status window
and in the execution history of the scenario (see "Scenario Status View" on page
101).
Equipment Simulator User Manual Using Scenarios during Simulation 90
If a scenario is executed periodically or contains event handler, only the affected
instance of the scenario is terminated. The scenario remains ready for further
periodic executions if necessary or waits for UCA2 events to be handled.
Because the reason for the runtime error may be temporary (e.g. a server is not
responding) it does not make sense to fully terminate the scenario.
12.2.4 Configuration
Some details of the behavior of the scenario runtime engine can be configured by
choosing Tools - Options....
The Equipment Simulator offers some general and some client and server
session specific configuration settings.
Select the Scenarios - General category to modify the execution interval used
to run scenarios.
Using this interval you can influence the speed scenarios are executed with. A
smaller value means higher speed, a higher value means slower speed. The
execution interval is the time the Equipment Simulator waits between the
execution of two consecutive statements in a scenario. If you set this value to 0,
scenarios are executed at maximum speed.
Select the Scenarios - Server Session category to modify settings used if
the Equipment Simulator is simulating a server.
Equipment Simulator User Manual Using Scenarios during Simulation 91
The only setting in this category is if the Equipment Simulator should
automatically call ODSDirectControlDone() and
ODSSboSelectDone() if the appropriate handler has not called
DirectControlDone() or SboSelectDone(). When a scenario finishes
its event handler the Equipment Simulator checks if DirectControlDone()
or SboSelectDone() has been called. If not and this option is enabled,
ODSDirectControlDone() or ODSSboSelectDone() is called
automatically.
Note: This setting is used for all simulated servers. It is not possible to configure
the automatic call of ODSDirectControlDone() and
ODSSboSelectDone() differently for each server.
Select the Scenarios - Client Session category to modify settings used when
the Equipment Simulator is acting in client mode and connects to a server.
Equipment Simulator User Manual Using Scenarios during Simulation 92
For client sessions you can define under which circumstances the Equipment
Simulator reads data leaf values from servers if referenced in scenarios. If you
enable Always read data leaf values from server if simulating a client,
data leaves are always read. If you do not enable this option, data leaf values are
read only once from the server, stored in the local device database and fetched
from this database when the leaf is next accessed. If you enable this option you
can reduce the network communication between client and server if the data leaf
value does not change on the server or is always reported by the server when
modified.
If you disable this option and enable Do not read data leaf values from
server if they are part of a report, the Equipment Simulator checks if the
data leaf is part of a report and does not read the leaf in this case. The Equipment
Simulator assumes that the local device database is always up to date because all
changes on the server are reported to the client.
By configuring the timeouts on this configuration page you can define how long
the Equipment Simulator waits for a response from the server before an
operation is classified as faulty. If the server does not respond within the
specified time the scenario which issued the statement is terminated by the
runtime engine.
Furthermore you can configure the default origin and operator name used when
direct control, SBO select or SBO deselect operations are done from the client. If
the appropriate statements are issued without operator or origin in a scenario the
default values configured here are used.
If you enable Use currently logged on user as default operator name
in control operations, the runtime engine determines the name of the
currently logged on user and uses this name for the operator name. If you disable
the option you can provide any name by entering a value in the Default
operator name edit box.
If you enable Use computer name as default origin in control
operations, the runtime engine determines the name of the computer and uses
this name as origin. If you disable the option you can provide any name by
entering a value in the Default origin edit box.
Equipment Simulator User Manual Using Scenarios during Simulation 93
12.3. Scenario Status View
When the scenario page on the right side of a data window is selected, scenarios
attached to the currently selected device object and their status are displayed.
Using the scenario status view you can observe, which scenarios are running,
which scenarios are finished, which scenarios are waiting for events and so on.
The Equipment Simulator displays all scenarios attached or running for the
device object selected in the left tree view or one hierarchy level below the
selected item. In the above example the $CO functional component is selected.
In this case all scenarios which are attached to this functional component and all
its child data objects are displayed in the scenario status view.
The following information is displayed for every scenario:
Scenario Name
The name of the scenario together with the information if it is a
local or global scenario file and the name of the scenario file.
Object Name
The name of the device object to which the scenario is attached.
State
The state of the scenario. See "Status of Scenarios" on page 95 for
more details on scenario states.
Equipment Simulator User Manual Using Scenarios during Simulation 94
Number of Starts
This column displays information about how often the scenario has
been started so far. The format of this column is xx (S: yy,
T: zz) where xx is the total number of starts of the scenario so
far (not the number of starts as declared in the scenario properties),
yy is the number of scheduled or periodic starts and zz is the
number of events handled which is increment every time a handler
in the scenario is called (for example if an OnDirectControl
handler in reaction to a direct control operation is started, yy is
incremented - xx is also incremented in this case because it shows
the total number of starts).
Date and Time of Next Start
If the scenario is a periodic scenario this column contains the date
and time of the next scheduled start of the scenario if the scenario
is currently not running.
Comment
The comment column is used to display state specific additional
information like the start time of the scenario if it is currently
running or the reason why a scenario has been stopped.
If you select a scenario in the status view the scenario code is displayed in the
window below the scenario status list.
Note: The code of scenarios which are attached to device objects or are running
cannot be modified. You must stop the scenario or the simulation to edit its code.
12.3.1 Execution History
The scenario status window shows only the current state of scenarios. To get
information about past executions of a scenario the execution history can be
used.
To display the execution history of a scenario, right click the desired scenario in
the status view and select Show Execution History....
Equipment Simulator User Manual Using Scenarios during Simulation 95
The following dialog is displayed:
Using the execution history you can display a detailed list about when the
scenario has been executed and if the scenario terminated successfully. You can
also investigate problems if a scenario is not executing correctly. For example if
a runtime error occurs, it is logged in this history. Runtime errors can be for
example a division by zero or a data type mismatch.
12.4. Starting and Stopping Scenarios
During a simulation scenarios can be started and stopped.
Starting scenarios during simulation is different from attaching scenarios to
device objects prior to simulation. Scenarios which are attached to device objects
are remembered by the Equipment Simulator after the simulation is stopped.
Attached scenarios are stored in the workspace file. Scenarios which are started
during a simulation can be seen as "one-shot-scenarios". They are automatically
detached from the device objects when they are finished or when the simulation
is stopped.
Scenarios which are started during simulation are handled equally to scenarios
which are attached to device objects and started automatically when the
simulation is started. This means that scenarios which are started during a
simulation can be executed periodically and contain event handler for all events
defined by the scenario language.
For a detailed description on how to attach scenarios to and detach scenarios
from device objects see "Attaching Scenarios to Single Objects" on page 50.
12.4.1 Starting Scenarios
Scenarios can either be started directly from the scenario window or by selecting
a device object (e.g. a server or data object) in the UCA2 device tree.
Note: A simulation must be running to start a scenario. Prior to simulation
scenarios are attached to device objects and automatically started at simulation
start.
To start a scenario right click the scenario code in the scenario window or right
click a device object in the device tree view and choose Start Scenario... or
press F4.
Equipment Simulator User Manual Using Scenarios during Simulation 96
Equipment Simulator User Manual Using Scenarios during Simulation 97
The following dialog is displayed:
Choose the scenario you want to start and configure periodic execution settings
if you want to run the scenario periodically or at a specific time. The settings are
taken over from the scenario properties (see "Scenarios" on page 24) but can be
modified here for specific instances of running scenarios.
When you click OK, the Equipment Simulator checks if the scenario is
syntactically correct and resolves data leaf names used in the scenario. This is an
important step when the UCA2 names in scenarios are relative to a data object,
brick, server, etc. In this case the Equipment Simulator builds the full names of
the data leaves by attaching the relative names used in the scenario to the name
of the device object for which the scenario should be started.
For example if the scenario uses the data leaves $CO$ODSw$OperDev and
$ST$ODSwSt$b2 and the scenario is started for the $Server1/LD1/XCBR1
brick, the data leaves are resolved to $Server1/LD1/XCBR1$CO$ODSw$-
OperDev and $Server1/LD1/XCBR1$ST$ODSwSt$b2.
Using this resolution method it is possible to start one scenario for many
different servers, logical devices, bricks, etc. For instance you can write a
scenario for the $f, $q and $t leaves of an AI (Analogue Input) data object and
start it for the $MX$Pres, $MX$Lev, $MX$Den and $MX$T data objects of a
XCBR brick without modifying of the scenario.
When a scenario is started from the scenario window or by right clicking the
station bus in the device tree view, the scenario must reference data leaves by
specifying their full names (including server name, logical device name, etc.),
because the Equipment Simulator does not know for which device object the
scenario should be started.
If the Equipment Simulator cannot resolve all data leaves, the scenario cannot be
started. This can occur if the data leaves referenced in the scenario are
misspelled or the scenario has been started for a device object for which the
scenario is not designed. In this case the scenario is displayed in the scenario
window and the incorrect data leaves are displayed in the log section.
Equipment Simulator User Manual Using Scenarios during Simulation 98
After the scenario has been started its execution can be observed using the
scenario status view (see "Scenario Status View" on page 101).
12.4.2 Stopping Scenarios
Running or attached Scenarios can be stopped during a simulation.
Right click the scenario in the scenario status view and choose Stop Scenario.
Equipment Simulator User Manual Using Scenarios during Simulation 99
The Equipment Simulator stops the scenario but leaves it in the status view. The
symbol on the left side of the scenario name is changed to and the state of the
scenario transitions to Finished.
12.4.3 Removing Scenarios
If you do not want a finished scenario to be displayed in the scenario status view
you can remove it.
Note: You cannot remove a running scenario. If you want to remove a running
scenario, you must stop it first.
Right click the scenario in the scenario status view and choose Remove
Scenario.
The Equipment Simulator removes the selected scenario from the scenario status
view.
Equipment Simulator User Manual Appendix A Bitstrings Use 100
Appendix A Bitstrings Use
Bitstrings Use - General
This section deals with the following main topics:
Bitstrings use in the graphical user interface,
Bitstrings use in the scenarios.
Bitstrings use in the graphical user interface
Bitstrings are displayed in hexadecimal representation matching their actual
network value.
BSTR1, BSTR2, BSTR4 and BSTR8 take up 1 byte: bit 0 is the most important
bit.
BSTR16 take up a 2-byte array: bit 0 is the more important bit of the first byte.
BSTR32 take up a 4-byte array: bit 0 is the more important bit of the first byte.
BSTR64 take up an 8-byte array: bit 0 is the more important bit of the first byte.
BSTR128 take up a 16-byte array: bit 0 is the more important bit of the first
byte.
Decimal or hexadecimal inputs are allowed. Data input is cast according to the
BigEndian convention.
For instance for a BSTR16:
Input Actual network
value
0x8000 0x8000
0x80 0x0080
128 0x0080
512 0x0200
Selection by bit is still allowed when the bits label is available.
Concerning BSTR1, 2 and 4, unused bits are forced to 0 whatever the input data
is.
Equipment Simulator User Manual Appendix A Bitstrings Use 101
Bitstrings use in the scenarios
Bitstrings are field bits. Available operations for field bits are limited. Available
operations on the field bits are:
Explicit cast: BSTRn converted to BSTRm. If n < m, the 0 to (n-1)
bits are copied from BSTRn to BSTRm and the n to (m-1) bits are
set to 0. Else the 0 to (m-1) bits are copied from BSTRn to
BSTRm.
Implicit cast. When 2 or more different type BSTRs are involved in
a expression, the different BSTRs are cast in a BSTR of the
higher type of the expression.
NOT: logical NOT.
~: bitwise NOT.wise
AND, OR: logical AND, OR.
&, | : bitwise AND, OR.
==, <> : equality and difference.
[ ] access to a specific bit into a BSTRn
The +,-,/,* operations should not be used in spite of the compiler supports them.
However, *2 and /2 operations could be used to enable bits offset operations. *2
operation is an offset to the left and /2 operation is an offset to the right. For
example:
$q := 0x4000 * 2; // $q is now equals to 0x8000
$q := $q / 2; // $q is now equals to 0x4000
Hexadecimal or decimal data are processed the same way as data inputs via HMI
are:
$b2 := 0x80; // $b2 is now equals to 0x80
$q := 0x80; //$q is now equals to 0x0080
Equipment Simulator User Manual Appendix B Scenario Language Reference 102
Appendix B Scenario Language
Reference
Scenario Language General
This section deals with the following main topics:
UCA2 Data Leaves, Scenario Variables and Named Constants,
Data Types,
Literals,
Event Handler,
Expressions and Operators,
Built-In Functions,
Statements.
UCA2 Data Leaves, Scenario Variables and Named
Constants
This section describes the syntax used to reference UCA2 data leaves, variables
and named constants in scenarios.
UCA2 data leaf names, variable names and named constants are case insensitive.
UCA2 Data Leaves
Data leaves can be referenced in scenarios by using their UCA2 names. They
must be prefixed with the dollar sign ($). See "Referencing UCA2 Data Leaves"
on page 36 for a more detailed description of how to reference UCA2 data leaves
from a scenario.
The forward slash (/) is used to separate server name, logical device name and
brick name and the dollar sign ($) is used to separate brick name, functional
component name, data object name and data leaf name.
Equipment Simulator User Manual Appendix B Scenario Language Reference 103
Examples:
$Server1/LD1/XCBR1$CO$ODSw$OperDev
WHILE $Server2/LD1/CFAN$ST$DevST$b2 <> 0x40 DO
...
END_WHILE;
$f
$MX$Pres$q
Scenario Variables
Variable names must start with a percent sign (%) followed by any number of
letters, digits and underscores (_). See "Using Variables in Scenarios" on page
34 for a more detailed description on how variables are declared and used.
Examples:
%gLastValue
%sOperator
FOR %i := 1 TO 30 DO
%gValue := 100.3 * %i;
END_FOR;
Named Constants
Named constants are used to make the scenario code more readable. Named
constants are either defined using the scenario file properties or via name-value
pairs in XML configuration files. See "Using Named Constants" on page 37 for a
more detailed description of how to define and use named constants.
Valid names for constants start with the number sign (#) followed by any
number of letters, digits and underscores (_).
Examples:
DirectControlDone( #TRUE );
ControlTermination( $AckCode, #CO_DEVICE_LOCKED );
%bValid := #FALSE;
Data Types
The data types supported by the Equipment Simulator are based on the data
types supported by the OdFoundry tool and the UCA2 Agency. Some additional
data types which were not supported by the OdFoundry tool and the UCA2
Agency at the time when this documentation has been created can be used within
scenarios (e.g. BDATE).
Data types are used to declare variables in the local and global variable
declaration sections of scenarios (see "Using Variables in Scenarios" on page 34)
and to type cast variables, UCA2 data leaves or constant values to other data
types.
Data type names are case insensitive.
Equipment Simulator User Manual Appendix B Scenario Language Reference 104
The following data types are supported:
Data Type
Name
Description Range of Values
BOOL Boolean - 1 Bit
BSTR1 Bitstring 1 Bit
BSTR2 Bitstring - 2 Bits
BSTR4 Bitstring - 4 Bits
BSTR8 Bitstring - 8 Bits
BSTR16 Bitstring - 16 Bits
BSTR32 Bitstring - 32Bits
BSTR64 Bitstring - 64 Bits
BSTR128 Bitstring - 128 Bits
VBSTR1 Visible Bitstring - 1 Bit
VBSTR2 Visible Bitstring - 2 Bits
VBSTR4 Visible Bitstring - 4 Bits
VBSTR8 Visible Bitstring - 8 Bits
VBSTR16 Visible Bitstring - 16 Bits
VBSTR32 Visible Bitstring - 32 Bits
VBSTR64 Visible Bitstring - 64 Bits
VBSTR128 Visible Bitstring - 128 Bits
INT8U Unsigned Integer - 8 Bits 0 to 255
INT16U Unsigned Integer - 16 Bits 0 to 65,535
INT32U Unsigned Integer - 32 Bits 0 to 2,147,483,647
INT8S Signed Integer - 8 Bits -128 to +127
INT16S Signed Integer - 16 Bits -32,768 to 32,767
INT32S Signed Integer - 16 Bits -2,147,483,648 to
2,147,483,647
FLT32 Floating Point, IEEE Format,
Single Precision
FLT64 Floating Point, IEEE Format,
Double Precision
ENUM8 Enumerated Value, 8 Bits, Signed
ENUM16 Enumerated Value, 16 Bits, Signed
IDENT VSTR65
VSTR8 Printable ASCII Text String - 0 to 8
characters
VSTR16 Printable ASCII Text String - 0 to 16
characters
VSTR32 Printable ASCII Text String - 0 to 32
characters
VSTR64 Printable ASCII Text String - 0 to 64
characters
VSTR128 Printable ASCII Text String - 0 to 128
characters
BTIME4 Number of ms since Midnight - 4 Bytes
BTIME6 Number of milliseconds since Midnight
and Days since 1 January 1984 - 8 Bytes
BTIME10 Number of nanoseconds since Midnight
and Days since 1 January 1984 - 10 Bytes
BDATE Number of Days since 1 January 1984
Equipment Simulator User Manual Appendix B Scenario Language Reference 105
For a detailed description of UCA2 Standard Data Types and UCA2 Common
Classes see UCA2 GOMSFE, Version 0.9.
Note: BOOL and BSTR1 are different: do not cast directly a BOOL type
variable into a BSTR1 type variable.
Literals
The following types of literals or constants are supported by the Equipment
Simulator:
Literal Type Examples
Decimal Integers 3, 312, 4711
Hexadecimal Integers 0x9a, 0x1000, 0xffffffff
Floating Point Values 0.3, 4711.1147, 3.1e10
Strings "ORIGIN", 'MyName', 'Operator'
Date and Time
Constants
"01.01.2001 12:30:00", "16.10.2001
00:00:00", "12:30:00"
Event Handler
The Equipment Simulator supports the following event handler in scenarios (for
a detailed description of event handler see "Event Handler" on page 39).
Handler Description
OnDirectControl is executed if a direct control operation is done
by a client to a server session
OnSboSelect is executed if a SBO select operation is done by
a client to a server session
OnSboDeselect is executed if a SBO deselect operation is done
by a client to a server session
OnWrite is executed if a data leaf is written by a client to
a server session
OnControlTermination is executed if a control termination service is
received in a client session
OnReportReceived is executed if a report is received in a client
session
OnWriteQuality is executed if a write quality request is received
OnGooseReceived is executed if a Goose is received
OnTime is executed if a scenario should be executed at a
specific time or periodically
OnSimulationStart is executed once during the start of a simulation
Default is executed if no event specific handler can be
found
OnDirectControl, OnSboSelect, OnSboDeselect, OnWrite,
OnWriteQuality and OnGooseReceived handlers are only useful in
server sessions, OnControlTermination and OnReportReceived
handlers are used in client sessions. OnTime, OnSimulationStart and
Default handler can be used in both client and server sessions.
Equipment Simulator User Manual Appendix B Scenario Language Reference 106
Scenarios must be assigned to data objects or data leaves for UCA2 event
handlers to get executed. If a scenario is assigned at a higher level of the device
hierarchy (e.g. at functional component or brick level), handler are not executed
because the scenario code cannot determine for which data object or data leaf the
operation has been done. This rule applies to the OnDirectControl,
OnSboSelect, OnSboDeselect, OnWrite, OnWriteQuality
,OnControlTermination and OnReportReceived handler.
The OnGooseReceived handler must be assigned to a incoming goose server or a
named Bitpair under it.
The OnSimulationStart and OnTime handler are executed on any device
structure level.
Note: If a scenario contains at least one handler, code which is located before
the first handler is never executed by the Equipment Simulator. The Equipment
Simulator always starts execution at the appropriate handler. If you want to
initialize local variables or data leaves you need to place the appropriate code
inside the corresponding handler.
Note: The last statement in a scenario handler should always be the EXIT
statement. If a handler is not terminated with EXIT and the scenario contains
more than one handler the code in the following handler is executed until an
EXIT statement or the end of the scenario is reached.
Equipment Simulator User Manual Appendix B Scenario Language Reference 107
Expressions and Operators
The Equipment Simulator supports the following operators:
Operator Description Examples
( ) parentheses to change
the default operator
precedence
32 / ( 4 + 4 )
( %gi + 32 ) / $f
NOT logical NOT IF NOT %bValid THEN
...
END_IF;
~ bitwise NOT $ODLock$b1 := ~$ODLock$b1
(<type>) type cast %int := (INT32S) "23";
%float := (FLT32) %string;
*, / multiplication, division $f := %value / 3e10 * %div
+, - addition, subtraction %sum := %v1 + %v2 + %v3
<, <=,
==, <>,
>= >
relational and equality
operators
WHILE $OperDev <> 2 DO
...
END_WHILE;
IF DATETIME >= "01.01.2001
10:00:00" THEN
...
END_IF;
&, | bitwise AND, bitwise
OR
$q := ( $q & 0xff ) | 0x2000;
AND, OR logical AND, logical OR IF %a == 1 AND %b <> 0 THEN
...
END_IF;
[] Bit access in a BSTRn $q[13]:=1 ;
$ST$*$b1[0]:=0;
%bsrt16_foo[%int8s_foo * 2] :=
$b1[0];
IF %bstr32_foo[25]
THEN SLEEP(1000);
END_IF;
Operator precedence is in the order the operators are listed in the above table
(e.g. multiplication has higher precedence than subtraction, addition has higher
precedence than logical operators, ...).
Most of the operators can be used for many of the available data types. The
Equipment Simulator tries to convert implicitly between different data types if
possible (e.g. if a INT8S is added to an INT32S, the INT8S value is implicitly
converted to an INT32S).
If an operator is not available for a data type, an exception is raised and the
instance of the scenario terminated.
The [] operator can be used only on a BSTRn variable or dataleaf. After its
evaluation, index expression represents the bit number to access (from left to
write starting at #0). When a bit of a BSTR is accessed, the other bits of the
BSTR are not modified.
Equipment Simulator User Manual Appendix B Scenario Language Reference 108
Index expression should be included in the [0,n-1] interval. If not, a run-time
error occurs. If a scenario is executed periodically or contains event handler,
only the affected instance of the scenario is terminated. The scenario remains
ready for further periodic executions if necessary or waits for UCA2 events to be
handled. Because the reason for the runtime error may be temporary (e.g. a
server is not responding) it does not make sense to fully terminate the scenario.
Built-In Functions
The Equipment Simulator has a few built-in functions which can be used in
expressions:
Function Description Examples
RAND( <max> ) returns a random number
between 0 and <max> -
1
%value := RAND( 1000 );
%value := RAND( %max );
DATETIME returns the current date
and time
$t := DATETIME;
IF DATETIME ==
"01.01.2001 10:00:00"
THEN
...
END_IF;
DATE returns the current date $t := DATE;
IF DATE == "01.01.2001"
THEN
...
END_IF;
TIME returns the current time $t := TIME;
IF TIME == '10:00:00'
THEN
...
END_IF;
Equipment Simulator User Manual Appendix B Scenario Language Reference 109
Statements
This section lists all statements supported by the Equipment Simulator scenario
language together with statement specific hints and examples. The statements are
listed alphabetically.
Assignment
Syntax:
<variable> := <expression>;
Description:
Assigns the value of an expression to a local or global scenario variable.
Examples:
$gi := 1;
$Operator := "TickTrick&Track";
$RandValue := RAND( 10 ) * 2 / 3;
$Uca2Value := $Server/LD/XCBR1$MX$Pres$f
BEGIN_UPDATE - END_UPDATE
Syntax:
BEGIN_UPDATE;
...
END_UPDATE [<reason_for_inclusion_expression>];
Description:
These two statements group a series of data leaf updates and delay the sending of
reports to clients by the UCA2 Agency until END_UPDATE is called. The
Equipment Simulator caches the data leaf updates between BEGIN_UPDATE
and END_UPDATE and sends all modifications to the UCA2 Agency at once
when the END_UPDATE statement is reached. <reason_for_inclusion
expression> is evaluated then cast in a byte and used as a the value of the
reason_for_inclusion parameter . Constant can be used as well (please refer to
"Using Named Constants" on page 37 to correctly use constants).
Valid values for reason_for_inclusion are:
#ODD_DATA_CHANGE = 0x40
#ODD_QUALITY_CHANGE = 0x20
#ODD_FOLLOWING_CONTROL = 0x8
#ODD_CYCLIC = 0x2
The validity of the reason_for_inclusions value is not checked. If <expression>
is omitted, ODD_DATA_CHANGE is used as reason_for_inclusion.
Example:
BEGIN_UPDATE;
$f := %NewValue;
$q := 0;
$t := DATETIME;
END_UPDATE #ODD_QUALITY_CHANGE;
Equipment Simulator User Manual Appendix B Scenario Language Reference 110
CONTROLTERMINATION
Syntax:
CONTROLTERMINATION
(
<acknowledgement leaf>,
<result expression>
);
Description:
This statement indicates that a previous control operation is terminated. The
acknowledgement leaf must be a $AckCode data leaf and is updated with the
result expression, which must evaluate to an integer value and corresponds to the
result of a direct control operation.
CONTROLTERMINATION must be called from an OnDirectControl
handler. If the statement is used outside of an OnDirectControl handler an
exception is thrown and the scenario is terminated.
CONTROLTERMINATION is only valid in server sessions.
Examples:
CONTROLTERMINATION( $CO$ODSw$AckCode, 0 );
CONTROLTERMINATION( $ODSw$AckCode, #CO_DEVICE_LOCKED );
DIRECTCONTROL
Syntax:
DIRECTCONTROL
(
<control leaf>,
<expression>,
<operator expression>,
<origin expression>,
<date/time expression>
);
Description:
This statement performs a direct control operation by writing the data given by
<expression> to the data leaf given by <control leaf>. <operator
expression> and <origin expression> must evaluate to strings,
<date/time expression> must be a valid date/time. All three parameters
are sent to the server and are written to the respective data leaves by the server.
DIRECTCONTROL is only allowed from a client session. If called for a data leaf
in a server session an exception is raised and the scenario is terminated.
DIRECTCONTROL returns 1 if the operation succeeded or 0 if the operation
failed. The return value can be checked in an IF statement for example.
<control leaf> must be a valid UCA2 data leaf name, data object names
are not allowed.
<operator expression>, <origin expression> and <date/time
expression> can be omitted. In this case default values which can be
configured in the Equipment Simulator are used.
Equipment Simulator User Manual Appendix B Scenario Language Reference 111
Examples:
DIRECTCONTROL
(
$CO$ODSw$OperDev,
0x40,
"OPERATOR",
"ORIGIN",
DATETIME
);
IF DIRECTCONTROL( $ODSw$OperDev, 0x40 ) == 1 THEN
SLEEP( 1000 );
ELSE
EXIT;
END_IF;
DIRECTCONTROLDONE
Syntax:
DIRECTCONTROLDONE( <result expression> );
Description:
DIRECTCONTROLDONE is called from an OnDirectControl handler to
return the result of the direct control operation to the UCA2 Agency.
If the statement is used outside of an OnDirectControl handler an exception
is thrown and the scenario is terminated.
DIRECTCONTROLDONE is only valid in server sessions.
<result expression> controls the result of the direct control operation. If
the expression evaluates to zero, an error is returned to the UCA2 Agency, if the
expression evaluates to a value unequal to zero, the operation is finished with
success.
Examples:
DIRECTCONTROLDONE( 1 );
DIRECTCONTROLDONE( 0 );
DIRECTCONTROLDONE( %nSuccess );
EXIT
Syntax:
EXIT;
Description:
The EXIT statement either leaves the innermost FOR or WHILE loop or the
scenario if used outside of a loop.
Examples:
WHILE %i < 10 DO
...
IF %bFound THEN
EXIT;
END_IF;
...
END_WHILE;
Equipment Simulator User Manual Appendix B Scenario Language Reference 112
FILEGET
Syntax:
FILEGET
(
<server expression>,
<local file expression>,
<remote file expression>
);
Description:
This statement reads a file from the specified server and stores the file on the
local file system.
<server expression> must be the name of a valid server, which is in a
client session of the Equipment Simulator.
<local file expression> and <remote file expression> are
strings which contain valid path and file names on the local and remote file
systems.
FILEGET is only allowed from a client session. If called from a server session
an exception is raised and the scenario is terminated.
FILEGET returns 1 if the operation was successful or 0 if the operation failed.
The return value can be checked in an IF statement for example.
Examples:
FILEGET
(
"SRV1",
"C:\TEMP\CONFIG.SET",
"CONFIG.SET"
);
IF FILEGET( "SRV", %local, %remote ) <> 1 THEN
EXIT;
END_IF;
FILEPUT
Syntax:
FILEPUT
(
<server expression>,
<local file expression>,
<remote file expression>
);
Description:
This statement writes a file from the local file system to the specified server.
<server expression> must be the name of a valid server, which is in a
client session of the Equipment Simulator.
<local file expression> and <remote file expression> are
strings which contain valid path and file names on the local and remote file
systems.
FILEPUT is only allowed from a client session. If called from a server session
an exception is raised and the scenario is terminated.
FILEPUT returns 1 if the operation was successful or 0 if the operation failed.
The return value can be checked in an IF statement for example.
Equipment Simulator User Manual Appendix B Scenario Language Reference 113
Examples:
FILEPUT
(
"REMOTESRV",
"C:\TEMP\CFG.SET",
"CFG.SET"
);
IF FILEPUT( "SRV", %local, %remote ) <> 1 THEN
EXIT;
END_IF;
FOR Loop
Syntax:
FOR <variable> := <expr1> TO <expr2> [STEP BY <expr3>] DO
...
END_FOR;
Description:
Repeats a group of statements a specified number of times. If the STEP BY
clause is omitted, the <variable> is increased by 1 by default.
Examples:
FOR %i := 1 TO 30 DO
$MX$Pres$f := %i * 100;
END_FOR;
FOR %i := %Start * 2 TO %End * 2 STEP BY 2 DO
...
END_FOR;
GETGOOSEBITPAIR
Syntax:
GetGooseBitPair();
GetGooseBitPair(<NamedBitPair Expression >) ;
GetGooseBitPair(<SendingServer Expression>,<NamedBitPair
Expression>) ;
Description:
The GetGooseBitPair built-in function allows the scenario to get a specific
bit pair from an incoming Goose
The GetGooseBitPair built-in function returns a BSTR8. The bit 7 of the
BSTR8 is cleared if the specified incoming Goose has been received once at
least. It the bit 7 of the BSTR8 is cleared, the bits 0 and 1 of the BSTR8 are set
to the last value of the specified bitpair received.
SendingServer expression is should a string. It is the name of the server that
sends the incoming Goose. It can be omitted if the running scenario is attached
to one of the server listed in the IncomingGoose Node or to a Named BitPair
under it.
NamedBitPair expression is should a string. It is the name of the bitpair that is
going to be read. It can be omitted along with the sending server name if the
running scenario is attached to a Named BitPair.
Equipment Simulator User Manual Appendix B Scenario Language Reference 114
Examples:
LOCALS
BSTR8 : % IcomGoose ;
BSTR2 : %BitPair ;
END_LOCALS;
%IcomGoose :=GetGooseBitPair(CALCUL1 , LD1/BAY1$ST$SWDS ) ;
IF %IcomGoose [7] then
%BitPair := %IcomGoose ;
END_IF;
GOTO
Syntax:
GOTO <label>:;
...
<label>:
...
Description:
Leaves the normal path of execution and jumps to the specified label.
Examples:
IF %bValid THEN
GOTO Valid:
END_IF;
...
GOTO Finish:
Valid:
...
Finish:
IF Statement
Syntax:
IF <expression> THEN
...
[ ELSE
... ]
END_IF;
Description:
Conditionally executes a group of statements, depending on the value of
<expression>. If <expression> evaluates to true, the group of statements
after the THEN clause is executed. If <expression> evaluates to false, the
group of statements following the ELSE clause is executed. If the ELSE clause
is not given, no statements are executed in this case.
Examples:
IF %b1 == 0x80 THEN
SLEEP( 1000 );
ELSE
SLEEP( 2000 );
END_IF;
IF %b2 == 0x40 THEN
SLEEP( %Timeout );
END_IF;
Equipment Simulator User Manual Appendix B Scenario Language Reference 115
SBOSELECT
Syntax:
SBOSELECT
(
<select leaf>,
<operator expression>,
<origin expression>,
<date/time expression>,
<controlType expression>
);
Description:
This statement performs a SBO select operation for the given <select
leaf>.
<operator expression> and <origin expression> must evaluate
to strings, <date/time expression> must be a valid date/time. All four
parameters are sent to the server and are written to the respective data leaves by
the server.
SBOSELECT is only allowed from a client session. If called for a data leaf in a
server session an exception is raised and the scenario is terminated.
SBOSELECT returns 1 if the operation was successful or 0 if the operation
failed. The return value can be checked in an IF statement for example.
<select leaf> must be a valid UCA2 data leaf name, data object names are
not allowed.
<operator expression>, <origin expression> and <date/time
expression> can be omitted. In this case default values, which can be
configured in the Equipment Simulator, are used.
<controlType expression> can be omitted too. In this case, no control
type is written on the server. If one or more of the three first parameters are
omitted but the Control Type, commas should be used in the parameters list.
Examples:
SBOSELECT
(
$CO$ODSw$SBO,
"OPERATOR",
"ORIGIN",
DATETIME,
0x40
);
IF SBOSELECT( $ODSw$SBO,,,,0x80 ) == 1 THEN
SLEEP( 1000 );
ELSE
EXIT;
END_IF;
SBOSELECTDONE
Syntax:
SBOSELECTDONE( <result expression> );
Description:
SBOSELECTDONE is called from an OnSboSelect handler to return the result
of the SBO select operation to the UCA2 Agency.
Equipment Simulator User Manual Appendix B Scenario Language Reference 116
If the statement is used outside of an OnSboSelect handler an exception is
thrown and the scenario is terminated.
SBOSELECTDONE is only valid in server sessions.
<result expression> controls the result of the SBO select operation. If
the expression evaluates to zero, an error is returned to the UCA2 Agency, if the
expression evaluates to a value unequal to zero, the operation is finished with
success.
Examples:
SBOSELECTDONE( 1 );
SBOSELECTDONE( 0 );
SBOSELECTDONE( %nSuccess );
SBODESELECT
Syntax:
SBODESELECT
(
<select leaf>,
<operator expression>,
<origin expression>,
<date/time expression>
);
Description:
This statement performs a SBO deselect operation for the given <select
leaf>. <operator expression> and <origin expression> must
evaluate to strings, <date/time expression> must be a valid date/time.
All three parameters are sent to the server and are written to the respective data
leaves by the server.
SBODESELECT is only allowed from a client session. If called for a data leaf in
a server session an exception is raised and the scenario is terminated.
SBODESELECT returns 1 if the operation was successful or 0 if the operation
failed. The return value can be checked in an IF statement for example.
<select leaf> must be a valid UCA2 data leaf name, data object names are
not allowed.
<operator expression>, <origin expression> and <date/time
expression> can be omitted. In this case default values which can be
configured in the Equipment Simulator are used.
Examples:
SBODESELECT
(
$CF$ODSwSBO$SBOState,
"OPERATOR",
"ORIGIN",
DATETIME
);
IF SBODESELECT( $ODSwSBO$SBOState ) == 1 THEN
SLEEP( 1000 );
ELSE
EXIT;
END_IF;
Equipment Simulator User Manual Appendix B Scenario Language Reference 117
SLEEP
Syntax:
SLEEP( <expression> );
Description:
This statement suspends the execution of the scenario by the specified amount of
time. <expression> must be given in milliseconds.
Examples:
SLEEP( 1000 );
SLEEP( %nDur * 1000 );
TRACE - NOTRACE
Syntax:
TRACE;

NOTRACE ;
Description:
This function call turns on the run-time scenario log for the calling scenario,
starting at the calling site until the end of the instance of the scenario or until the
scenario reaches the calling site of a NOTRACE function call.
The NOTRACE function call can be omitted: the NOTRACE function is called
automatically at the end of each periodic or event call of the scenario.
To be active, the run-time Scenario Logs boxes should be checked (see
"Appendix C Equipment Simulator Logging" on page 132) and the TRACE
function should be called.
WHILE Loop
Syntax:
WHILE <expression> DO
...
END_WHILE;
Description:
Executes a series of statements as long as the condition given by
<expression> is true.
Examples:
%i := 0;
WHILE %i < 10 DO
$MX$Pres$f := %i * 100;
%i := %i + 1;
END_WHILE;
Equipment Simulator User Manual Appendix B Scenario Language Reference 118
UCA2 Assignment
Syntax:
<UCA2 data leaf> := <expression>;
Description:
Assigns the value of an expression to one or more UCA2 data leaves.
If the assignment take place outside a BEGIN_UPDATE END_UPDATE
section on a simulated server, the overall parent data object is sent to the client.
The Equipment Simulator can assign the result of the expression to a specific
data leaf by its name or to multiple data leaves by using the asterisk (*) as a
wildcard character in the data leaf name. For example if the expression is
assigned to the UCA2 data leaf $*$*$q and the scenario which contains this
statement is assigned to a brick, the result value is assigned to the q data leaves
of all data objects of all functional components of the concerned brick.
Examples:
$*$*$q := 0x0000;
$Server/LD1/XCBR1$MX$Pres$f := 5000;
$Server/LD1/XCBR1$MX$Pres$t := DATETIME;
$CO$ODSw$Origin := "Origin";
$q := ( $q & 0xff ) | 0x01;
Equipment Simulator User Manual Appendix C Equipment Simulator Logging 119
Appendix C Equipment
Simulator Logging
Equipment Simulator Logging
The Equipment Simulator can log different areas of its processing to log files
(especially the interface to the UCA2 Agency or the log output of the scenario
runtime engine can be interesting to investigate problems).
Logging can be configured via the tools options panel.
You can select the category of log messages you are interested in, the destination
of these messages (files or log panel of the Equipment Simulator).
The names of the created log files are ESLOGxxx.LOG where xxx is a
consecutive number. When the specified maximum size is reached, a new file
with a new consecutive number is created.
The number of created files will never exceed the specified number of max files.
Equipment Simulator User Manual Appendix C Equipment Simulator Logging 120
Field Description
DEVICES logs internal processing of the device structure
OTHER logs messages not part of other components
SCENARIO logs general scenario related events
SCO_IL logs compilation and syntax checks of scenarios
SCO_RT logs execution of scenarios (in conjunction with the TRACE
NOTRACE function call: see "TRACE - NOTRACE" on
page 130)
SIMULAT logs events directly related to a simulation (e.g. a report
which has been activated or a data leaf which has been
written on the server)
UCA2 logs general UCA2 Agency related events
UCA2_DLL logs calls to the UCA2 Agency and callbacks from the
UCA2 Agency
UCA2_FIL dumps file contents in UCA2 Agency file management calls
and callbacks
XML logs XML import related events
Note: Logging can slow down the Equipment Simulator considerably when
many components are logged at the same time. Therefore turn on logging only
for those components you are interested in and turn off logging for all other
components.
Equipment Simulator User Manual Appendix D Error and Bug Reports 121
Appendix D Error and Bug
Reports
Error and Bug Reports
When you detect abnormal behavior of the Equipment Simulator please enclose
the following information and items to the error description:
The operating system version and service pack installed.
Equipment Simulator version number and EQUIPSIM.EXE
executable timestamp.
UCA2 Agency version number and timestamps of ODRPC.DLL,
Win32Agency.EXE and OdFoundry.EXE.
The workspace and XML configuration files used.
The scenario files used.
The BASTYPES.CFG file used.
The current settings from the registry (use REGEDIT.EXE and
export the HKEY_LOCAL_MACHINE\Software\ALSTOM\-
Equipment Simulator and HKEY_CURRENT_USER\-
Software\ALSTOM\Equipment Simulator subkeys into
separate registry files).
Equipment Simulator User Manual Index 122
Index
- 106
&
& 106
*
* 106
/
/ 106
:
:= 108
|
| 106
~
~ 106
+
+ 106
<
< 106
<= 106
<> 106
=
== 106
>
> 106
>= 106
A
AGENCY.CFG 11, 56
AND 106
Arrange data and scenario windows 18
Assignment statement 108
Attach scenario 44
B
BEGIN_UPDATE statement 32, 37, 108, 116
Built-in functions 107
DATE 107
DATETIME 107
RAND 107
TIME 107
Bulk assignment 35
C
Cascade 18
Check scenario syntax 31
Client area
Data windows 16
Complete modification 69
Configuration 3
Configuration file 19
Constants 102, 104
Control center 25
Control termination 73
CONTROLTERMINATION statement 109
Create directory 51
Create file 51
Create scenario 30
Create scenario file 28
D
Data types 102
Data windows 16
DATE built-in function 107
DATETIME built-in function 107
Default 38, 104
Default operator name 91
Default origin 91
Delete directory 51
Delete file 51, 83
Delete scenario 30
Delete scenario file 28
Detach scenario 44
Device configuration file 19
Device tree pane 13
Direct control operation 75
DIRECTCONTROL statement 109
DIRECTCONTROLDONE statement 110
Directory
Delete 51
Rename 51
Display data leaf 59
Display data object 59
Distribution list 7
Equipment Simulator User Manual Index 123
E
Embed XML configuration 21
END_UPDATE statement 32, 37, 108, 116
Event handler 104
Default 38, 104
OnControlTermination 38, 104
OnDirectControl 32, 37, 93, 104, 109
OnGooseReceived 104
OnReportReceived 38, 104
OnSboDeselect 37, 104
OnSboSelect 37, 40, 104, 114
OnSimulationStart 38, 54, 104
OnTime 38, 104
OnWrite 38, 104
OnWriteQuality 104
Execution history 88, 93
EXIT statement 110
Expressions 106
F
FILEGET statement 111
FILEPUT statement 111
Files 11, 50, 52, 81
Create 51
Create directory 51
Delete 51, 83
Delete directory 51
Get from server 83
Put to server 82
Rename 51
Rename directory 51
FOR statement 112
G
Get file from server 83
Global scenario directory 23
Global variables 33
Data types 102
GOTO statement 113
I
IF statement 113
Illustration of modified data leaves 67
Installation 3
L
Literals 104
Local variables 33
Data types 102
Log pane 13, 15
M
MaxClientSession 11
MaxServerSession 11, 56
Modify data leaf 69, 72, 75
Modify data object 69, 72, 75
N
Named constants 102
NOT 106
O
Object foundry settings 10, 54, 58
OnControlTermination 38, 104
OnDirectControl 32, 37, 93, 104, 109
OnGooseReceived 104
OnReportReceived 38, 104
OnSboDeselect 37, 104
OnSboSelect 37, 40, 104, 114
OnSimulationStart 38, 54, 104
OnTime 38, 104
OnWrite 38, 104
OnWriteQuality 104
Operator 91
& 106
* 106
/ 106
| 106
~ 106
+ 106
< 106
<= 106
<> 106
== 106
> 106
>= 106
AND 106
NOT 106
OR 106
Type cast 102, 106
Operator precedence 106
Operators 106
OR 106
Organization of scenarios 23
Origin 91
P
Print scenario 31
Put file to server 82
Q
Quick modification 69
R
RAND built-in function 107
Read data leaf 75
Read data object 75
Remove scenario 98
Rename directory 51
Rename file 51
Rename scenario 30
Equipment Simulator User Manual Index 124
Rename scenario file 28
Requirements 1, 3, 9
Runtime engine 34, 87
S
SBO deselect operation 75
SBO select operation 75
SBODESELECT statement 115
SBOSELECT statement 114
SBOSELECTDONE statement 114
SCE 19
Scenario control center 25
Scenario file properties 28
Scenario Files
Create 28
Properties 28
Rename 28
Scenario runtime engine 34, 87
Scenario window
Code section 25
Control center 25
Log section 25
Scenarios
Attach 44
Built-in functions 107
Check syntax 31
Constants 102, 104
Create 30
Data types 102
Default 38, 104
Delete 30
Detach 44
Event handler 104
Expressions 106
Global 23
Global variables 33
Literals 104
Local variables 33
Named constants 102
OnControlTermination 38, 104
OnDirectControl 32, 37, 93, 104, 109
OnGooseReceived 104
OnReportReceived 38, 104
OnSboDeselect 37, 104
OnSboSelect 37, 40, 104, 114
OnSimulationStart 38, 54, 104
OnTime 38, 104
OnWrite 38, 104
OnWriteQuality 104
Operators 106
Print 31
Properties 31
Remove 98
Rename 30
Start 94
Statements 108
Status view 87, 92, 97
Stop 94
UCA2 data leaves 34, 44, 101
Variables 33, 102
Workspace specific 23
Simulation
Start 1, 53
Stop 1, 53
Simulation of files 11, 50, 52, 81
SLEEP statement 116
Start scenario 94
Start simulation 1, 53
Statements 108
Assignment 108
BEGIN_UPDATE 32, 37, 108, 116
CONTROLTERMINATION 109
DIRECTCONTROL 109
DIRECTCONTROLDONE 110
END_UPDATE 32, 37, 108, 116
EXIT 110
FILEGET 111
FILEPUT 111
FOR 112
GOTO 113
IF 113
SBODESELECT 115
SBOSELECT 114
SBOSELECTDONE 114
SLEEP 116
UCA2 assignment 117
WHILE 116
Status view 87, 92, 97
Stop scenario 94
Stop simulation 1, 53
System Configuration Editor 19
T
Tile horizontally 18
Tile vertically 18
TIME built-in function 107
Time synchronization 78
Type cast 102, 106
U
UCA2 Agency settings 10, 54
UCA2 assignment 117
UCA2 data leaves 34, 44, 101
UCA2 data types 102
UCA2 operation
Control termination 73
Direct control 75
Display data leaf 59
Display data object 59
Modify data object 69, 72, 75
Read data leaf 75
Read data object 75
SBO deselect 75
SBO select 75
Time synchronization 78
User readable names 68
Write Quality 75
Equipment Simulator User Manual Index 125
User readable names 68
V
Variables 33, 102
Data types 102
W
WHILE statement 116
Windows Explorer 51, 82
Workspace 21
Embed XML configuration 21
Workspace specific scenario directory 23
Write quality operation 75
X
XML 19