Equip Sim User Manual

8/10/2019 Equip Sim User Manual

1/131

User Manual

Equipment Simulator

Issue C3


2/131

History

Version Date Author CommentsZ 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 clarificationand 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


3/131Equipment Simulator User Manual Table of Contents i

Table of Contents

1. Introduction 11.1. Overview...................................................................................................................11.2. Organization of this Manual......................................................................................11.3. Relationship to Other Documents .............................................................................2

2. Installation and Configuration 32.1. Installation and Configuration General ..................................................................32.2. Installation.................................................................................................................3

2.2.1 Requirements............................................................................................3

2.2.2 Distribution ..............................................................................................42.2.3 Proceeding to the installation ...................................................................42.2.4 What is installed .......................................................................................7

2.3. Registration ...............................................................................................................72.4. Configuration ............................................................................................................92.5. Multilingualism.......................................................................................................11

3. The Equipment Simulator Window 133.1. Equipment Simulator Window - General ................................................................133.2. Description of the Equipment Simulator Window..................................................133.3. Menu and Toolbar ...................................................................................................153.4. Device Tree Pane ....................................................................................................153.5. Log Pane .................................................................................................................163.6. Status Bar ................................................................................................................173.7. Client Area..............................................................................................................17

3.7.1 Data Windows........................................................................................173.7.2 Scenario Windows..................................................................................193.7.3 Arrange Data and Scenario Windows ....................................................19

4. Configuration Files and Workspaces 204.1. Configuration Files and Workspaces General......................................................204.2. Configuration Files..................................................................................................20

4.2.1 Loading a standalone configuration file.................................................214.2.2 Loading from an SCE zip file.................................................................21

4.3. Workspaces.............................................................................................................22

5. Scenarios 245.1. Scenarios General.................................................................................................245.2. Organization of Scenarios .......................................................................................245.3. The Scenario Window.............................................................................................26

5.3.1 The Control Center.................................................................................265.3.2 The Code Section ...................................................................................275.3.3 The Log Section .....................................................................................28

5.4. Managing Scenarios................................................................................................285.4.1 Scenario Files .........................................................................................285.4.2 Scenarios ................................................................................................30


4/131Equipment Simulator User Manual Table of Contents ii

5.5. Writing Scenarios....................................................................................................325.5.1 General Structure of Scenarios...............................................................325.5.2 Using Variables in Scenarios .................................................................345.5.3 Referencing UCA2 Data Leaves ............................................................365.5.4 Using Named Constants .........................................................................375.5.5 Event Handler.........................................................................................395.5.6 Other Topics...........................................................................................45

6. Preparing a Simulation 466.1. Preparing a Simulation - General ............................................................................466.2. Selecting Server and Clients ...................................................................................466.3. Attaching and Detaching Scenarios ........................................................................48

6.3.1 Attaching Scenarios to Single Objects ...................................................506.3.2 Attaching Scenarios to Multiple Objects................................................506.3.3 Detaching Scenarios...............................................................................52

6.4. Initializing Data Leaves ..........................................................................................536.5. Preparing File Simulation........................................................................................54

7. Starting and Stopping a Simulation 587.1. Starting and Stopping a Simulation General ........................................................587.2. Starting a Simulation...............................................................................................587.3. Stopping a Simulation.............................................................................................607.4. Generation of Object Definition, Data Model and UCA2 Agency Configuration

Files.........................................................................................................................607.4.1 LEAN.CFG ............................................................................................617.4.2 AGENCY.CFG ......................................................................................627.4.3 MMS_LOG.CFG....................................................................................637.4.4 Generation of Data Model Files .............................................................63

8. Simulation of UCA2 Operations 658.1. Simulation of UCA2 Operations - General .............................................................658.2. Displaying Data Objects and Data Leaves ..............................................................65

8.2.1 Reading mode.........................................................................................67

8.2.2 Illustration of modified Data Leaves......................................................738.2.3 User Readable Names ............................................................................74

8.3. Modifying Data Objects and Data Leaves...............................................................758.3.1 Complete Modification using Dialogs....................................................75

8.4. Server Operations....................................................................................................798.4.1 Modifying Data Objects and Data Leaves..............................................798.4.2 Reason For Inclusion..............................................................................798.4.3 Control Termination...............................................................................808.4.4 Disable associations ...............................................................................81

8.5. Client Operations ....................................................................................................828.5.1 Reading Data Objects and Data Leaves .................................................828.5.2 Modifying Data Objects and Data Leaves..............................................838.5.3 Write Quality and Control Operations ...................................................83

8.5.4 Time Synchronization ............................................................................86

9. Simulation of Redundancy 879.1. Simulation of Redundancy - General ......................................................................879.2. Modifying the Current Redundancy Status .............................................................87

10. Simulation of Files 8910.1. Simulation of Files - General ..................................................................................8910.2. Server ......................................................................................................................8910.3. Client.......................................................................................................................90

10.3.1 Put File to Server....................................................................................90


5/131Equipment Simulator User Manual Table of Contents iii

10.3.2 Get File from Server...............................................................................9110.3.3 Delete File..............................................................................................91

11. Simulation of goose 9211.1. Simulation of goose - General.................................................................................9211.2. Starting a simulation with goose .............................................................................9211.3. Receiving goose ......................................................................................................9311.4. Sending goose .........................................................................................................94

12. Using Scenarios during Simulation 9512.1. Using Scenarios during Simulation - General .........................................................9512.2. The Scenario Runtime Engine.................................................................................95

12.2.1 Status of Scenarios .................................................................................9512.2.2 Execution of Scenarios...........................................................................9712.2.3 Runtime Errors .......................................................................................9712.2.4 Configuration .........................................................................................98

12.3. Scenario Status View ............................................................................................10112.3.1 Execution History.................................................................................102

12.4. Starting and Stopping Scenarios............................................................................10312.4.1 Starting Scenarios.................................................................................10312.4.2 Stopping Scenarios...............................................................................10612.4.3 Removing Scenarios.............................................................................107

Appendix A Bitstrings Use 108Bitstrings Use - General...................................................................................................108Bitstrings use in the graphical user interface ........... .......... ........... .......... ........... ........... ...108Bitstrings use in the scenarios..........................................................................................109

Appendix B Scenario Language Reference 110Scenario Language General ......... ........... .......... ........... .......... ........... ........... .......... .......110UCA2 Data Leaves, Scenario Variables and Named Constants .......... ........... .......... .......110

UCA2 Data Leaves............................................................................................110

Scenario Variables.............................................................................................111Named Constants...............................................................................................111Data Types.......................................................................................................................111Literals.............................................................................................................................113Event Handler ..................................................................................................................113Expressions and Operators...............................................................................................116Built-In Functions............................................................................................................118Statements........................................................................................................................119

Assignment........................................................................................................119BEGIN_UPDATE - END_UPDATE................................................................119CONTROLTERMINATION.............................................................................121DIRECTCONTROL..........................................................................................121DIRECTCONTROLDONE...............................................................................123EXIT 123FILEGET...........................................................................................................124FILEPUT...........................................................................................................124FOR Loop..........................................................................................................126GETGOOSEBITPAIR ......................................................................................126GOTO 127IF Statement ......................................................................................................127SBOSELECT.....................................................................................................128SBOSELECTDONE..........................................................................................128SBODESELECT ...............................................................................................129SLEEP 130TRACE - NOTRACE........................................................................................130


6/131Equipment Simulator User Manual Table of Contents iv

WHILE Loop.....................................................................................................130UCA2 Assignment.............................................................................................131

Appendix C Equipment Simulator Logging 132Equipment Simulator Logging.........................................................................................132

Appendix D Error and Bug Reports 134

Error and Bug Reports .....................................................................................................134

Index 135


7/131Equipment Simulator User Manual Introduction 1

1. Introduction

1.1. OverviewThis user manual describes how the Equipment Simulator is installed, configuredand used, how simulations are prepared, started and stopped and how scenarioscan be used to automate certain tasks.

The Equipment Simulator is designed for the Windows NT and Windows 2000operating system families.

The Equipment Simulator is based on the UCA2 Agency for communicationwith other devices or between Equipment Simulators on different computers.

This user manual is for people who want to use the Equipment Simulator tobrowse a UCA2 network, simulate certain devices, which are physically notavailable, or investigate and control a remote device.

This user manual assumes a basic knowledge of UCA2 terminology andprocedures. For programmers who want to use the scenario language someknowledge and experience in developing in a high level language such as VisualBasic or PASCAL or a scripting language is needed.

1.2. Organization of this ManualThe 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 Simulatorand 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 EquipmentSimulator main window and about how to adjust the appearance toyour needs.

The chapter "Configuration Files and Workspaces" on page 20describes how configuration files are imported and workspaces areused 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 thescenario language are shown.

The chapters "Preparing a Simulation" on page 46 and "Starting

and Stopping a Simulation" on page 58 describe the steps necessaryto prepare simulations and how to start and stop simulations.


8/131Equipment Simulator User Manual Introduction 2

The chapters "Simulation of UCA2 Operations" on page 65,

"Simulation of Files" on page 89, "Simulation of Redundancy" onpage 87 and "Simulation of goose" on page 92 explain howcommon UCA2 operations and redundancy operations can besimulated using the Equipment Simulator.

"Using Scenarios during Simulation" on page 95 gives you detailed

information about how the Equipment Simulator executes scenariosand which functions you can use to investigate and control running

scenarios.

"Appendix A Bitstrings Use" on page 108 contains a detailedreference on how bitstring data are managed in EquipmentSimulator.

"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 containinformation about how logging can be used to investigate theEquipment Simulator behavior and which information error andbug reports should contain.

1.3. Relationship to Other DocumentsThis document references other documents. These other documents include thefollowing:

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.


9/131Equipment 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. InstallationThis section describes the requirements necessary to install and setup theEquipment Simulator, the files delivered with the Equipment Simulator and theinstallation process itself.

2.2.1 RequirementsThe following requirements are necessary to install and run the EquipmentSimulator:

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



2.2.2 DistributionWhatever the media support, the Equipment Simulator distribution consist inthree 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 inorder 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 withadministrator privileges before installing the Equipment Simulator.

It is not required to uninstall a previous version of Equipment Simulatorbefore installing the newest version of the software. Thus, your registration keyis not lost and you dont need to ask the Equipment Simulator team for a newkey 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 .



Then, if you install on a computer on which the equipment simulator was alreadyinstalled, 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 userinformation. 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, currentinformation is automatically filled into the dialog. Do not change them if OK.



When the following dialog is displayed, choose the directory, where theEquipment Simulator should be installed (or leave default option) and click Next > .

At last, choose (or leave the default one) the program folder where theequipment simulator shortcuts will be installed in the startup menu and click Next> .

The installation wizard now proceeds to the installation of the EquipmentSimulator. When it is finished, you get the following window. Click Finish toterminate the installation wizard.



2.2.4 What is installedFiles

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 startthe equipment simulator, and the other to view the user manual.

By default, folder name is Alstom/Pacis/Equipment simulator

2.3. RegistrationTo fully use the Equipment Simulator, registration is necessary. Registrationmust be done on every computer the Equipment Simulator is used on. Duringregistration the Equipment Simulator calculates a unique number for yourcomputer. This number must be sent to an e-mail address. An activation key foryour computer is sent back and must be entered into the Equipment Simulator.

Without registration, simulations are possible for a period of 60 days. After 60days you can still use the Equipment Simulator, load XML configuration filesand workspaces and browse through the device structure but you cannot startsimulation. During the evaluation period of 60 days you can use all features of the Equipment Simulator including simulations.



When you start a simulation the Equipment Simulator checks if you haveregistered. If not, the following dialog is displayed which gives informationabout the remaining evaluation period.

If you select Register Later , the Equipment Simulator starts the simulationprocess. Select Register Now to register the Equipment Simulator. You canalso choose Help - Register... from the main menu to register the EquipmentSimulator at any time.

The following dialog is used for registration.

The unique number calculated for your computer is displayed in the first textbox. Send this number per e-mail to [email protected] . Anactivation key will be calculated for your computer and sent back to you. Enterthe 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 EquipmentSimulator, you cannot start further simulations. Until you register, the followingdialog is displayed every time you start a simulation.



2.4. ConfigurationWhen you start the Equipment Simulator the first time, some basic configurationsettings should be checked. If you have installed the Equipment Simulator afterthe installation of the UCA2 Agency and you have selected the appropriateoption in the Setup Wizard, no modification of configuration settings should benecessary. 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 defaultvalues which are built in. With the exception of some paths for the UCA2Agency and its configuration files you normally have to check only if the defaultvalues match your requirements and modify only those which do not.

Note : Configuration settings are stored in the Windows registry. If you want totransfer configuration settings between computers or users, you can use theMicrosoft Registry Editor ( REGEDIT.EXE ) to export registry settings on onecomputer and import it on another computer. Configuration settings are stored inthe HKEY_LOCAL_MACHINE\SOFTWARE\ALSTOM\EquipmentSimulator 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 notinclude the registration key stored under HKEY_LOCAL_MACHINE\-SOFTWARE\ALSTOM\Equipment Simulator\Registration becausethe registration key is not valid on other computers.

This chapter contains a description of how to change the settings which areabsolutely necessary. Other settings are described in the chapters where they areused and affect the behavior of the Equipment Simulator.

Note : The Equipment Simulator stores most of its settings in the Windowsregistry. Some of the settings and options are stored on a per user basis, some arenot. Settings which are not stored on a per user basis are located in theHKEY_LOCAL_MACHINE registry key. To change settings stored under this

registry key appropriate privileges are necessary, which ordinary users normallydo not have. You must be logged on with administrator privileges or theappropriate right assigned by your administrator if you are logged on as ordinaryuser. Settings which cannot be changed are grayed in the options dialog.



To change configuration settings and Equipment Simulator options chooseTools - Options.. . from the menu. The following dialog is displayed:

Equipment Simulator options are organized in categories with the categoriesdisplayed in a tree like hierarchy on the left side and the options of a selectedcategory on the right side. To change the settings for a category simply select itsname on the left side.

Please check and if necessary adjust the following settings when you first startthe Equipment Simulator:

1. Select the Object Foundry Settings - General category.

2. Enter the path where the object foundry executable can befound. The object foundry, ODFOUNDRY.EXE , can normally befound 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 configurationfile . This file is normally copied during Equipment Simulator setupand can be found in the Equipment Simulator installation directory.The name of the file is BASTYPES.CFG . You can use theBrowse... button to locate the file.

4. Enter the path where the Equipment Simulator should storetemporary object definition and data model files . You canuse 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.



7. Select the Simulation of Files category.

8. Enter the root directory where the Equipment Simulator shouldstore files for servers which are simulated. For every serversimulated by the Equipment Simulator a virtual root directoryunder this directory is created, where the server specific files arestored. See "Simulation of Files" on page 89 for more details onhow to simulate files with the Equipment Simulator. You can usethe Browse... button to choose the path.

Note : The default AGENCY.CFG file, which is generated by the EquipmentSimulator before a simulation is started contains settings for a maximum of 3client and 3 server sessions. If you need to simulate more sessionssimultaneously you need to adjust the MaxClientSession andMaxServerSession settings appropriately under the UCA2 AgencySettings - Agency Configuration File category.

With these basic configuration settings done you should be able to dosimulations.

2.5. MultilingualismAccording to the provided resources DLLs (i.e. esrcen.dll, esrcfr.dll, and so on),Equipment Simulator offers multilingualism features, which can be set with thedialog of configuration available via the Tools Options menu in the Languagecategory.

After choosing the desired language, you have to quit and restart EquipmentSimulator in order to take the changes into account.



Note : At its first launch, Equipment Simulator starts with the language of theOperating System if a resource DLL for this language is available. Otherwise,the default language is English.


19/131Equipment Simulator User Manual The Equipment Simulator Window 13

3. The Equipment Simulator

Window

3.1. Equipment Simulator Window - General


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 WindowThe Equipment Simulator main window consists of several items which can beadjusted to your needs.

The following screen shot shows an example for the contents of a typicalEquipment Simulator window:



This example shows a main window with a data window and a scenario windowopened in the client area.

The Equipment Simulator main window consists of a user adjustable number andselection of the following items:

Item DescriptionMenu and toolbar Menu and toolbar are used to initiate actions in the Equipment

Simulator like creating new windows, opening workspacefiles or starting a simulation.

Device tree pane The device tree pane which is normally docked to the left sideof the Equipment Simulator main window is used to browsethrough 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 aboutongoing simulations or other potentially interestinginformation.

Status bar The status bar displays simple help texts if a menu item ortoolbar symbol is selected.

Client area The client area is used to display any number of data andscenario 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.


21/131



If you are opening new data windows from existing data windows and thereforedo not need the device tree pane choose View - Device Tree or press +1

to hide it. To show a hidden device tree pane, choose View - Device Tree orpress +1 again.

You can dock the device tree pane to any side on the Equipment Simulator mainwindow by clicking the border of the pane and dragging it to the desiredposition. If you do not want the device tree pane to be docked to the EquipmentSimulator main window, move the pane into the client area using the describedprocess. If the device tree pane is not docked you can move it around in theclient area like data and scenario windows.

3.5. Log PaneThe 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+2 .

You can clear the contents of the log by selecting Edit - Clear Log Windowor clicking the symbol on the toolbar.

Log level can be configured for each equipment simulator component with theTools Options Logs configuration dialog.



3.6. Status BarThe status bar is used to display a single line of help text when you scrollthrough the menu or move the mouse over the toolbar.

The status bar can be hidden and shown using View - Status Bar .

3.7. Client AreaThe client area is used to display any number of data windows and scenariowindows.

3.7.1 Data WindowsData windows are used to browse through the device structure or display andmodify data object and data leaf values. Furthermore they are used to attachscenarios to and detach scenarios from items in the device structure.

During a simulation it can be useful to open and arrange more than one datawindow 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 ordisplay and simulate files.

Data windows contain a tree like device structure on the left side and an area todisplay information to a selected item on the right side.

To display information to an item in the device structure, for example a brick ora 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 theselected item or the scenarios which are attached to the item.



The title bar of a data window contains the name of the parent object of the itemdisplayed 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 devicestructure. The only exception is that you cannot display a single data object ordata leaf in a data window.

To create a new data window simply right click the item, which should be thetop level object, in an existing window and choose New Window .

In the following example the GLOBE brick is displayed in its own data window.



3.7.2 Scenario WindowsScenario windows are used to manage scenarios and scenario files.

Scenario windows contain a control center at the top, the code section in themiddle and a log section at the bottom.

You can open any number of scenario windows to copy code between them orcompare scenarios. To open a new scenario window choose Window - NewScenario Window .

If you want to bring an existing scenario window into foreground, but do notwant 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 Simulatorcan 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 andscenario windows. You can also use the symbols , or from the toolbar.


26/131Equipment Simulator User Manual Configuration Files and Workspaces 20

4. Configuration Files and

Workspaces

4.1. Configuration Files and Workspaces General


Configuration Files,

Workspaces.

4.2. Configuration FilesThe import of a configuration file is the starting point of every simulation.Configuration files are XML files, which describe the structure of devicesmanaged by the Equipment Simulator.

Because it is not possible to manually create devices and their structure in theEquipment Simulator, configuration files are the only way to set up a simulationenvironment in the Equipment Simulator.Configuration files are created by the System Configuration Editor (SCE) whichproduce a Zip file containing the XML configuration file for the equipmentsimulator. You can load the configuration directly from the Zip or extract itmanually from the zip, eventually modify it, and then load it. You can also buildyou 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 isreferenced by the XML file, must be present to import a device configurationinto 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 theEquipment Simulator. All devices are configured using one single XML file.



4.2.1 Loading a standalone configuration fileTo import a device configuration choose File - Import XML ConfigurationFile... 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 automaticallycreated. See the following section for more information on workspaces.

4.2.2 Loading from an SCE zip fileTo get the configuration directly from an SCE produced Zip file choose file Import SCE configuration. In the following dialog choose the SCE file you wantto import and click OPEN .



4.3. WorkspacesWorkspaces are used to store the actual work into a file. Workspaces containinformation about opened data and scenario windows, devices which aresimulated as servers or clients, scenarios which are attached to data objects, ordata values entered for data leaves.

Workspace files are stored with the extension .ESW (Equipment S imulatorWorkspace) by default.

To open an existing workspace, choose File - Open Workspace... or press+O . You can also click the symbol on the toolbar. In the followingdialog choose the workspace file you want to open.

To save the current workspace, choose File - Save Workspace , press+S or click the symbol on the toolbar.

To save the current workspace under a different name, choose File - SaveWorkspace As... .

To close the current workspace, choose File - Close Workspace .

By default the Equipment Simulator stores a reference to the XML configurationfile or the SCE zip file in the workspace file. When you reopen the workspace, itis necessary that the file exists in the same directory and with the same name aswhen the workspace was saved.

To change this behavior you can embed the XML device configuration into theworkspace file. Using this technique you can store everything needed by theEquipment 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 - SaveWorkspace As... . In the following dialog, enable the Embed XMLconfiguration option and click Save .



You can also change this option without saving a workspace by choosing File -Workspace Properties... . In the following dialog enable the Embed XMLconfiguration option and click OK .

The XML configuration file is embedded into the workspace file the next timeyou save the workspace.

If you disable the Embed XML configuration option, the EquipmentSimulator searches the configuration file in the directory the file was originallyimported from.


30/131Equipment Simulator User Manual Scenarios 24

5. Scenarios

5.1. Scenarios GeneralThis chapter deals with the following main topics:

Organization of Scenarios,

The Scenario Window,

Managing Scenarios,

Writing Scenarios.

5.2. Organization of ScenariosScenarios are used to automate simulations in the Equipment Simulator. Theyare organized in scenario files with the extension .ESS (Equipment S imulatorS cenarios). Scenario files are XML files which contain zero, one or morescenarios.

Scenario files are stored in global and workspace specific directories. TheEquipment Simulator automatically loads all scenario files in the globaldirectory when it is started and the scenarios in the workspace specific directorywhen a workspace is loaded. After scenario files have been loaded, scenarioscontained in the files are ready for use in the Equipment Simulator.

To configure the global directory for scenarios, choose Tools - Options... andselect the Scenarios - General category.



Enter the directory for global scenario files and click OK .

If a workspace is in use, the workspace specific directory can be configured bychoosing File - Workspace Properties... .

By default the directory where the workspace file is stored is used. If you wantto change the workspace specific scenario directory enter the desired path andclick OK .

Because scenarios are organized in stand alone files they can be easilyexchanged between different users and computers. To exchange scenario files,simply copy the desired files from the global or workspace specific directory tothe destination computer. In the Equipment Simulator on the destinationcomputer choose Scenarios - Refresh All to reload the new scenario files if the Equipment Simulator is already started.



5.3. The Scenario WindowThe scenario window is used to create, display, modify and delete scenarios andscenario files.

For a description on how to display one or more scenario windows see "ScenarioWindows" on page 19.

The scenario window contains a control center at the top, the code section in themiddle and a log section at the bottom.

5.3.1 The Control CenterThe control center at the top of a scenario window is used to navigate throughexisting scenarios and manage scenarios and scenario files.

All scenarios currently loaded by the Equipment Simulator - global andworkspace specific - are displayed in the combo box at the left side of the control

center. They are displayed using the following format:

[ - ]



For example, if XCBR-ODSw [G - XCBRScoExamples.ess] is displayed inthe combo box, the code of the scenario XCBR-ODSw from the fileXCBRScoExamples.ess - which is a global scenario file - is displayed inthe 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 codesection of the scenario window.

The buttons Scenario and Scenario Files are used to manage scenarios andscenario files. See the following chapters for more details on these topics.

5.3.2 The Code SectionBelow the control center the code of the selected scenario is displayed.

The Equipment Simulator has a very comfortable code editor for modifyingscenarios built in. This code editor supports a lot of features like syntaxhighlighting or bookmarks which are known from other popular code editors ordeveloper studios.

You can adjust the code editor to your needs by choosing Tools - ScenarioEditor Options... . The following dialog is displayed:



5.3.3 The Log SectionThe log section is used to display errors during compilation of a scenario. Bydouble clicking an error in the log section the incorrect line is highlighted in thescenario code.

5.4. Managing ScenariosThis 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 FilesScenario files are used to group scenarios which belong together. For exampleyou could create a scenario file for every type of brick with scenarios useful forthe appropriate brick. It is up to you how you organize your scenarios, theEquipment Simulator does not impose any restrictions on how you organizethem in scenario files.

Beside the name of the file, scenario files have additional properties which canbe displayed by choosing Scenario File - Properties... from the scenario

window control center. To display these properties you first have to select ascenario, which is stored in the desired file.



Below the folder, where the scenario file is stored, a note is displayed whichgives 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 propertiesof a scenario file. Named constants are simple name-value pairs used to associatea constant integer, floating point or string value with a more readable namewhich can be used in the scenario code. For more details on how you can usenamed constants to make scenario code more readable see "Using NamedConstants" 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 fileand decide if you want to create a global or workspace specificscenario file.

Rename existing scenario files

Choose Scenario Files - Rename... , select the scenario file youwant to rename and enter the new scenario file name.

Delete existing scenario files

Choose Scenario Files - Delete... and select the scenario fileyou want to delete. If you delete a scenario file, all scenarioscontained in the file are removed.

Change properties of scenario files

Select a scenario which is stored in the scenario file you want tomodify and choose Scenario Files - Properties... . Modify thedescription of the scenario file or change the list of namedconstants.



Save all scenario files

Choose Scenario Files - Save All to save all modifications doneto scenarios to disk.

Reload scenario files

Choose Scenario Files - Refresh All to reload all scenario filesfrom the global and workspace specific scenario directories.Reloading of scenario files is useful if you manually copy scenariofiles from other users or computers to the global or workspace

specific scenario directory and want to use those files immediatelyin the Equipment Simulator.

5.4.2 ScenariosBeside the code a scenario consists of some additional properties can bemanaged for scenarios which are used during attachment of scenarios to thedevice 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 thescenario is stored, a short description of the scenario, settings for periodicexecution of the scenario and a list of data objects and data leaves for which thescenario is designed. For the latter to be displayed you must select theAdvanced >> button.



Using the settings for periodic execution of scenarios you can configure to start ascenario at a specific time or periodically by specifying an interval betweenstarts. Periodic settings stored with scenarios are default values for the scenariowhich can be overridden when the scenario is attached to or started for a specificdevice 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 dayor relative to the start time of the simulation. For example if youchoose to start the scenario at a specific time of day and enter12:00:00 for the start time, the scenario is started at 12:00:00midday no matter at which time the simulation has been started. If you choose to start the scenario relative to the simulation start andenter 01:00:00 for the start time, the scenario is started one hourafter simulation start.

Start time

The start time is either a specific time of day or the period betweensimulation start and start of the scenario. The start time specifiesthe time the scenario is started the first time if executedperiodically.

Number of starts

The number of starts are used for periodic execution and give thenumber of times the scenario will be executed. For a scenariowhich 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 theduration between two consecutive starts of the scenario.

The data objects and data leaves the scenario is designed for are used toautomatically attach the scenario to multiple device objects. In the aboveexample, where the scenario is designed for $ODLock$b1 data leaves, theAttach Scenario to Multiple Objects... function can be used to search the

device structure for all $ODLock$b1 data leaves and automatically attach thescenario to those leaves. For a more detailed description on how to attachscenarios 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 thefollowing dialog enter the name of the scenario, choose thescenario file, where the scenario should be stored, and enter thedesired properties for the scenario.

Rename existing scenariosChoose Scenario - Rename... , select the scenario you want torename and enter a new name for the scenario.

Delete existing scenarios

Select the scenario in the control center of the scenario window andchoose Scenario - Delete... .



Print scenarios

Select the scenario in the control center of the scenario window andchoose Scenario - Print... or press +P .

Check the syntax of scenarios

To check if the code of your scenario is syntactically correct, selectthe scenario in the control center and choose Scenario - CheckSyntax or press F7 . In the log section of the scenario windoweither syntax errors are displayed or a short message that no errors

were found is given.

Change properties of scenariosSelect a scenario in the control center and choose Scenario -Properties... .

5.5. Writing ScenariosThis section is focused on how to write scenarios using the scenario languagebuilt into the Equipment Simulator. It describes in addition to other topics howscenarios are structured, how variables and UCA2 data leaves can be used, howevent handler can be used to start scenarios event triggered and how to usenamed 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 befound in traditional programming languages. For a complete reference of thescenario 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 namedconstants can be written in lower case or upper case and mixed in anycombination.

5.5.1 General Structure of ScenariosA 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 variablessections can be omitted if no variables are used.



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 DOSLEEP( 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 variableand a statement section without a handler. If the scenario is started the statementsection 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. Thescenario is attached to a data leaf or data object and "waits" for an event. If adirect control operation is done on the data object or data leaf the scenario isattached to, the Equipment Simulator activates the scenario and executes theOnDirectControl handler.

As you can see from the above examples, the scenario language supports twotypes of comments. A single line comment which is simply prefixed with thecharacters // and multi line comment which starts with /* and ends with */ .


40/131


41/131



Examples on how to use data leaf names in scenarios:

SBODESELECT($CF$ODSwSBO$SBOState,"OPERATOR","ORIGIN",DATETIME);

IF $b2 == 0x80 THENSLEEP( 1000 );

END_IF;$MX$Pres$f := $MX$Pres$f + 1.;

Note : The Equipment Simulator can only read and write data leaves. It is notpossible to read or write data objects or other compound objects which havemultiple data leaves.

You can use the Copy Name to Clipboard function to let the EquipmentSimulator build UCA2 names to save time when entering fully qualified namesand to reduce the likelihood of misspelled names.

Simply right click the data object or data leaf, whose name you need in a datawindow, and select Copy Name to Clipboard from the context menu or press

+C . Switch to the scenario edit window and insert the UCA2 name bypressing +V .

Note : You need to prefix the UCA2 name with a dollar sign ( $ ) if you copy aname 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 thename with a $ when copying it from a data window.

An additional format for UCA2 data leaf names can be used in UCA2assignment statements. The assignment statement supports the asterisk wildcardcharacter ( * ) 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 awildcard character is used.

Examples:

$*$*$*$f := 0.0;$*$*$*$q := 0x01;

In the above examples the Equipment Simulator assigns the given values to alldata objects on all functional components on all bricks.

This technique is called bulk assignment and can be very useful to initializeall data leaves of a server, logical device or brick.

5.5.4 Using Named ConstantsNamed constants can be used to make the scenario code more readable.Constants are defined either using the scenario file or via name-value pairs inXML configuration files.



Examples for named constants are:

Name ValueCO_ACK_OK 0

CO_DEVICE_ALREADY_IN_POS 8

CO_DEVICE_LOCKED 5

FALSE 0

TRUE 1DEFAULT_OPERATOR "Pete"

To define named constants using scenario files, choose Scenario File -Properties... from the scenario window and modify the named constants in thebottom section of the dialog.

Named constants can be defined in the XML configuration file using theUserReadableValueNamesList element and its child elements. See thefollowing extract for the definition of the constants Between , Off , On andInvalid using an XML configuration file:

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 pairsfrom XML files with names like "Jammed/Motion" or blanks in the name (e.g."l Threshold Violation") are not allowed.



Named constants can be used in scenarios by simply prefixing the name of theconstant with the number sign ( # ).

Examples:

DirectControlDone( #TRUE );ControlTermination( $AckCode, #CO_DEVICE_LOCKED );%bValid := #FALSE;

5.5.5 Event HandlerScenarios can contain handlers which are automatically executed if theappropriate event is processed by the Equipment Simulator. An event can be anUCA2 event or an Equipment Simulator internal event.

Event handlers in scenarios are organized as labels followed by the code whichshould 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 dataobject or the $ODLock$b1 data leaf, and a direct control operation is executedfor the data object or data leaf, the Equipment Simulator starts the handlerautomatically.

The Equipment Simulator supports the following handlers in scenarios:

OnDirectControl

This handler is executed if a direct control operation is done by aclient. It can only be used for data objects and data leaves in aserver session.

OnSboSelect

This handler is executed if a SBO select operation is done by aclient. It can only be used for data objects and data leaves in aserver session.

OnSboDeselect

This handler is executed if a SBO deselect operation is done by aclient. It can only be used for data objects and data leaves in aserver session.



OnWrite

This handler is executed if the data object or data leaf the scenariois attached to is written by a client. It can only be used for dataobjects and data leaves in a server session.

OnControlTermination

This handler is executed if a direct control operation is terminatedby a server. It can only be used for data objects and data leaves in aclient session.

OnReportReceived

This handler is executed if a report is received for the appropriatedata object or data leaf. It can only be used for data objects anddata leaves in a client session.

OnWriteQuality

This handler is executed if a writequality is done by a client to thedata object or data leaf the scenario is attached to. It can only beused for data objects and data leaves in a server session

OnGooseReceived

This handler is executed if a Goose is received for the appropriateserver or named bitpair. It can only be in a server session.

OnTime

This handler is executed when a scenario should be executed at aspecific time or periodically.

OnSimulationStart

This handler is executed when the simulation is started. Thehandler is executed only once and only for scenarios which areattached to device objects at the time the simulation is started. If ascenario is started or attached during a simulation, the handler isnot executed.

Default

This handler is executed if no specific handler can be found for anevent. It can be used to handle different events equally.

The Equipment Simulator uses the following procedure to find and execute ahandler 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 appropriateevent 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 forhandlers in attached scenarios. Therefore you can assign a scenario to both the

$ODLock data object and the $ODLock$b1 data leaf for example. Bothattachments 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 eventhandlers to get executed. If a scenario is assigned at a higher level of the devicehierarchy (e.g. at functional component or brick level) handler are not executedbecause the scenario code cannot determine for which data object or data leaf theoperation has been done.



If more than one scenario is assigned to a data leaf or data object, the EquipmentSimulator checks all these scenarios for handler and executes them if found.

In the OnDirectControl and OnSboSelect handler the scenario codemust call DirectControlDone() respectively SboSelectDone() . Theparameter to these statements is 1 if the result is success or 0 if the result isfailure.

Example:

OnSboSelect:

SboSelectDone( 1 );EXIT;

If the Equipment Simulator does not find a handler for a direct control or SBOselect operation the DirectControlDone() and SboSelectDone()statements are automatically called.

It can be configured, that the Equipment Simulator should call theODSDirectControlDone() and ODSSboSelectDone() servicesautomatically if not called by the scenario handler.

Choose Tools -Options... and select the Scenarios - Server Sessionscategory:

If you want the Equipment Simulator to automatically callODSDirectControlDone() and ODS SboSelectDone() enable theCall ODSDirectControlDone() and ODSSboSelectDone()automatically if not called by the scenario handler option.

Similarly the scenario handler must call ControlTermination() with theacknowledgement data leaf and the result code if a direct control handler isexecuted.



Example:

OnDirectControl:

DirectControlDone( 1 );ControlTermination( $CO$ODSw$AckCode, 0 );EXIT;

If a scenario should be executed periodically, the Equipment Simulator executesthe OnTime handler of the scenario at the specified times. It is possible to mixOnTime and other handler in one scenario.If a scenario contains at least one handler, code which is located before the firsthandler is never executed by the Equipment Simulator. The EquipmentSimulator always starts execution at the appropriate handler. If you want toinitialize local variables or data leaves you need to place the appropriate codeinside 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 thescenario with an EXIT statement before the next handler is defined. Otherwise

the Equipment Simulator "falls through" and continues execution at thefollowing handler.

Example:

OnDirectControl:

DirectControlDone( 1 );ControlTermination( $CO$ODSw$AckCode, 0 );EXIT ;

OnSboSelect:

SboSelectDone( 1 );EXIT ;

OnTime:

...

EXIT ;



5.5.6 Other TopicsThis section lists other issues and hints which can be helpful when usingscenarios.

The Equipment Simulator scenario language is case insensitive. Keywords,variable names, UCA2 names, event handler names and named constants can bewritten in lower case or upper case and mixed in any combination.

The scenario language supports literals or constants like other traditionalprogramming languages. Decimal and hexadecimal integers, floating pointvalues, 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 singleline comment is simply prefixed with the characters // . A multi line commentstarts with /* and ends with */ .

For more information on literals, operators, expressions and built-in functionssee "Appendix B Scenario Language Reference" on page 110.


49/131Equipment Simulator User Manual Preparing a Simulation 43

6. Preparing a Simulation

6.1. Preparing a Simulation - GeneralBefore a simulation can be started a few preparation steps are necessary. Thischapter 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 andwork with data windows is required (see "The Equipment Simulator Window"on page 13 for more details).


Selecting Server and Clients,

Attaching and Detaching Scenarios,

Initializing Data Leaves,

Preparing File Simulation.

6.2. Selecting Server and ClientsFrom the list of available servers on the station bus you have to select whichones should be simulated by the Equipment Simulator and to which ones theEquipment 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 shouldconnect to the server right click the server in the tree view of a data window andselect 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 theEquipment Simulator connect to the server.



You can also select the server and choose Simulation - Simulate Device asServer , Simulation - Connect to Device or Simulation - DeactivateDevice from the menu or click one of the following symbols from the toolbar:

Symbol Simulation Mode

Act as a server

Act as a clientDo not simulate device

The same symbols are used in the tree view of the device structure to show if aserver is simulated, if the Equipment Simulator connects to the server or if thedevice is deactivated.

The selection of server and clients is stored in the workspace file. Therefore thispreparation step is only needed once for a workspace file.

Note : The Equipment Simulator creates one UCA2 Agency server session forevery server simulated and one single UCA2 Agency client session for allservers to which the Equipment Simulator should connect when the simulation isstarted.



6.3. Attaching and Detaching ScenariosBy attaching scenarios to device objects the connection between the object andthe scenario is permanently stored in the workspace. Attached scenarios areautomatically started by the Equipment Simulator when the simulation is startedand stopped when the simulation is stopped.

Scenarios are normally attached to device objects during preparation of asimulation. Because the attachment is stored in the workspace the simulation canbe started multiple times using the same scenarios without the need to start thescenarios manually every time.

Attaching a scenario to a device object permanently binds the scenario to theobject. In contrast starting a scenario during simulation is a one-shot event. Afterthe scenario is finished or the simulation is stopped the scenario is automaticallydetached from the device object.

Attaching a scenario to and detaching a scenario from device objects is onlypossible before a simulation is started. During a simulation it is only possible tostart scenarios which are automatically detached when the simulation is finished.

Scenarios can be attached on any level of the device structure. Scenarios can beattached to the station bus as a whole, to servers, logical devices, bricks,

functional components, data objects and data leaves. But it is necessary that theEquipment 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 beassigned 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 theEquipment Simulator does not know the brick the data leaf is in. See"Referencing UCA2 Data Leaves" on page 36 for a more detailed description onhow data leaves can be referenced in scenarios.

Attached scenarios can be scenarios which are executed periodically (e.g. tochange a measurement) or contain event handlers which are executed whenUCA2 Agency service requests are received.

The scenarios which are attached to device objects are displayed in the rightpane of the device window:



If you select a device object in the tree view, the Equipment Simulator displaysthe scenarios attached to the device object and its child objects in the scenariolist. The child objects of the next level of the device structure are displayed tosee for example the scenarios attached to a data object and its leaves at once. Butthis rule applies on any level of the device structure (e.g. if you select a brick, thescenarios attached to the brick and its functional components are displayed).

In the tree view, device objects which have scenarios attached to it change theiricon. A small sheet is displayed in the top right corner of the icon. For examplethe icon for data objects changes from to if a scenario is attached to it orone of its leaves.

Note : It is not possible to edit the scenario code from the data window. To editthe scenario code switch to a scenario window or right click the desired scenarioand 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 attachmentmethod to attach a scenario to multiple objects at a time.


53/131



Beside the scenario name, the Equipment Simulator needs two components toautomatically attach a scenario to multiple device objects.

The first part is the UCA2 device structure level from which the EquipmentSimulator should start the attachment process. This can be any name starting atstation bus level, this means you must include the server name in the UCA2name. 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 levelthe Equipment Simulator searches the whole device structure fordata objects and data leaves the scenario should be attached to. Thismeans 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 dataobjects and/or data leaves the scenario should be assigned to. The EquipmentSimulator suggests the data objects and data leaves the selected scenario isdesigned 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 orremove data objects and data leaves the scenario should be attached to.

By selecting Preview Data Objects... it is possible to check which deviceobjects are affected by the attachment process prior to attachment. TheEquipment Simulator searches the device structure with the given parametersand displays the found objects in the following dialog:

By clicking OK in the Attach Scenario to Multiple Objects dialog thescenarios are attached to the affected objects.



6.3.3 Detaching ScenariosTo detach a scenario from a device object simply right click the scenario in theright side of the data window and choose Detach Scenario .

If you want to detach multiple scenarios at once, right click the device object inthe device tree from which on you want to detach scenarios and choose DetachMultiple Scenarios... or choose Scenarios Detach MultipleScenarios.. . from the main menu. The following dialog is displayed:

Choose the scenario you want to detach or Detach all scenarios and selectthe device object from which you want to remove the scenario or select Detachscenarios from all device objects .

According to your settings the Equipment Simulator searches through the devicestructure and removes the scenarios which match your conditions.



6.4. Initializing Data LeavesIf you are simulating a server using the Equipment Simulator it could be usefulto initialize certain data leaves with predefined values before starting asimulation (e.g. the data objects of the Device Identity brick).

Note : Initialization of data leaves for servers to which the Equipment Simulatorconnects is not useful because the server stores the current values and the clientis notified about modified values by reports or actively reads the values from theserver.

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 inthe data view on the right side, data leaves can only be selected in the data viewon the right side.

Depending on the data object or data leaf selected a dialog similar to thefollowing one will be displayed:

The left side of this dialog displays the current values of the data leaves, on theright side you can modify the leaves as desired. See "Displaying Data Objectsand Data Leaves" on page 65 (server and client modes) for a more detaileddescription of how data objects and data leaves can be modified.

When a simulation is started, the Equipment Simulator initializes the data leaveswith the values last entered.



When a workspace is saved, the current values of all data leaves are storedwithin the workspace file.

Note : If you want to do simulations with different start values for a lot of dataleaves you can create a workspace for every set of data values and switchbetween the start values by loading the different workspaces.

6.5. Preparing File SimulationThe Equipment Simulator supports simulation of files both in server and clientmode.

In client mode the Equipment Simulator can be used to browse the directorystructure of the server, download and upload files and remove files on the server.For servers to which the Equipment Simulator connects during a simulation nopreparation is necessary because all file related services are requested from theserver during simulation.

In server mode the directory and file structure must be prepared on the local filesystem. The Equipment Simulator manages a "virtual" root directory for everyserver 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 directoriesshould be managed choose Tools - Options... and select the Simulation ofFiles category.

In the Virtual root directory for simulation of files enter the directorywhere the Equipment Simulator should store files for simulation.

Note : During installation a subdirectory called Server Files is createdunder the Equipment Simulator installation directory. By default, this directoryis used as virtual root directory for the simulation of files.

For every server simulated, the Equipment Simulator creates a subdirectory withthe name of the server. These directories act as root directories for the simulatedserver.



For example if files should be stored in C:\UCA2 Agency\Root and thename of the server is SRV1 , the "virtual" root directory of the server isC:\UCA2 Agency\Root\SRV1 . All file requests from clients to SRV1 aremapped to this root directory.

To populate the directory with files and subdirectories you can use theWindows Explorer or any other file manager. Simply copy the desired filesinto and create subdirectories in the "virtual" root directory of the server.

Additionally the Equipment Simulator has some support to set up a directorystructure built in. To display and modify the directory structure of a server selectthe 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 directoryis stored on the disk from the user.

Note : To display a directory structure, the affected server must be configured tobe simulated by the Equipment Simulator. If the server is deactivated or should

be simulated in client mode, no directory structure can be displayed. Toconfigure the server to be simulated right click the name of the server and chooseSimulate Device as Server from the context menu.

You can browse through the directory structure, as you know it from theWindows 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 sideof the data window, choose New - Directory and enter the nameof the new directory.

Create fileTo 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 newfile. The Equipment Simulator creates an empty file with thespecified name.

Delete file or directory

Right click the file or directory you want to delete and chooseDelete or press .

Rename file or directory

Right click the file or directory you want to rename and chooseRename .



If you modify the directory structure outside of the Equipment Simulator youcan choose Files - Refresh or press F9 to update the directory structure in theEquipment Simulator.

From the directory structure you can directly start an application to view ormodify a file. The Equipment Simulator manages a list of file viewers which youcan configure by choosing Tools - Options... and selecting the Simulationof Files category.

You can add your own viewers to this list by clicking Add and entering a namefor the viewer. For every viewer you add, you must enter the name of theexecutable to start (including the path) and the arguments which should bepassed to the application. The placeholder %s is used to insert the name of thefile 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 chooseView - ... .

The Equipment Simulator starts the viewer to display the selected file.


60/131Equipment Simulator User Manual Starting and Stopping a Simulation 54

7. Starting and Stopping a

Simulation

7.1. Starting and Stopping a Simulation General


Starting a Simulation,

Stopping a Simulation,

Generation of Object Definition, Data Model and UCA2 AgencyConfiguration Files.

7.2. Starting a SimulationAfter you have finished the preparation steps, described under "Preparing aSimulation" on page 46, you can start a simulation.

Choose Simulation - Start , press F5 or click the symbol on the toolbar tostart a simulation.

The Equipment Simulator starts a simulation by performing the following tasks:

For every server simulated and every server the EquipmentSimulator connects t