PACiS
Equipment Simulator
Technical Guide
PACiS Equipment Simulator
CONTENT
Safety & Handling ES/EN SA/B11
Technical Data ES/EN TD/B11
Technical Guide ES/EN TG/B11
Installation ES/EN IN/B11
Human Machine Interface ES/EN HI/B11
Settings ES/EN ST/B11
Language Reference ES/EN LR/B11
Application ES/EN AP/B11
CONTENT
1.
INTRODUCTION 3
2.
SAFETY 4
2.1 Health and Safety 4 2.2 Explanation of symbols and labels 4 2.3 Installing, Commissioning and Servicing 4 2.4 Decommissioning and Disposal 4
3.
GUARANTIES 5
4.
COPYRIGHTS & TRADEMARKS
6
4.1 Copyrights 6 4.2 Trademarks 6
1. INTRODUCTION
The present document is a PACiS ES chapter of the documentation binders. It describes the safety, handling, packing and unpacking procedures applicable to PACiS ES software tools.
2. SAFETY
WARNING: THIS SAFETY SECTION SHOULD BE READ BEFORE COMMENCING ANY WORK ON THE EQUIPMENT.
2.1 Health and Safety
The information in the Safety Section of the product documentation is intended to ensure that products are properly installed and handled in order to maintain them in a safe condition. It is assumed that everyone who will be associated with the equipment will be familiar with the contents of the Safety Section and all Safety documents related to the PC and Communication networks.
2.2 Explanation of symbols and labels
The meaning of symbols and labels may be used on the equipment or in the product documentation, is given below.
2.3 Installing, Commissioning and Servicing Equipment operating conditions
The equipments (PC and communication network supporting PACiS SMT) should be operated within the specified electrical and environmental limits.
Fibre optic communication
Where fibre optic communication devices are fitted, these should not be viewed directly. Optical power meters should be used to determine the operation or signal level of the device.
2.4 Decommissioning and Disposal Disposal
It is recommended to avoid incineration and disposal of the PACiS ES CD-ROM. The product should be disposed of in a safe manner.
3. GUARANTIES
The media on which you received T&D AIS software are guaranted not to fail executing programing instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. T&D AIS will, at its option, repair or replace software media that do net execute programming instructions if T&D AIS receive notice of such defects during the guaranty period. T&D AIS does not guaranty that the operation of the software shall be uninterrupted or error free.
A Return Material Authorisation (RMA) number must be obtained from the factory and clearly marked on the package before any equipment acceptance for guaranty work. T&D AIS will pay the shipping costs of returning to the owner parts, which are covered by warranty. T&D AIS believe that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, T&D AIS reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult T&D AIS if errors are suspected. In no event shall T&D AIS be liable for any damages arising out of or related to this document or the information contained in it.
Expect as specified herein, T&D AIS makes no guaranties, express or implied and specifically disclaims and guaranties of merchantability or fitness for a particular purpose. Customer's rights to recover damages caused by fault or negligence on the part T&D AIS shall be limited to the amount therefore paid by the customer. T&D AIS will not be liable for damages resulting from loss of data, profits, use of products or incidental or consequential damages even if advised of the possibility thereof.
This limitation of the liability of T&D AIS will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against T&D AIS must be brought within one year after the cause of action accrues. T&D AIS shall not be liable for any delay in performance due to causes beyond its reasonable control.
The warranty provided herein dues net cover damages, defects, malfunctions, or service failures caused by owner's failure to follow the T&D AIS installation, operation, or maintenance instructions; owner's modification of the product; owner's abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control.
4.
COPYRIGHTS & TRADEMARKS
4.1 Copyrights
Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of T&D AIS.
4.2 Trademarks
PACiS, PACiS SCE, PACiS ES, PACiS SMT, PACiS PS, PACiS SCE, T&D AIS, pacis.biz and pacis.com- are trademarks of T&D AIS. Product and company names mentioned herein are trademarks or trade names of their respective companies.
5. WARNINGS
REGARDING
USE OF T&D AIS PRODUCTS
T&D AIS products are not designed with components and testing for a level of reliability suitable for use in or in connection with surgical implants or as critical components in any life support systems whose failure to perform can reasonably be expected to cause significant injuries to a human.
In any application, including the above reliability of operation of the software products can be impaired by adverse factors, including -but not limited- to fluctuations in electrical power supply, computer hardware malfunctions, computer operating system, software fitness, fitness of compilers and development software used to develop an application, installation errors, software and hardware compatibility problems, malfunctions or failures of electronic monitoring or control devices, transient failures of electronic systems (hardware and/or software), unanticipated uses or misuses, or errors from the user or applications designer (adverse factors such as these are collectively termed "System failures").
Any application where a system failure would create a risk of harm to property or persons (including the risk of bodily injuries and death) should not be reliant solely upon one form of electronic system due to the risk of system failure to avoid damage, injury or death, the user or application designer must take reasonably steps to protect against system failure, including -but not limited- to back-up or shut-down mechanisms, not because end-user system is customised and differs from T&D AIS' testing platforms but also a user or application designer may use T&D AIS products in combination with other products.
These actions cannot be evaluated or contemplated by T&D AIS; Thus, the user or application designer is ultimately responsible for verifying and validating the suitability of T&D AIS products whenever they are incorporated in a system or application, even without limitation of the appropriate design, process and safety levels of such system or application.
CONTENT
1.
SCOPE OF THE DOCUMENT
3
1.
SCOPE OF THE DOCUMENT
This document is a chapter of the PACiS Equipment Simulator (ES) documentation binder. It describes the Technical Data (ES/EN TD) of this software application.
2. 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,
CONTENT
1.
INTRODUCTION 5
1.1 Overview 5 1.2 Organization of this Manual 5
2.
INSTALLATION AND CONFIGURATION
7
2.1 Installation and Configuration – General 7 2.2 Installation 7
2.2.1 Requirements 7
2.2.2 Distribution 7
2.2.3 Proceeding to the installation 8
2.2.4 What is installed 11
2.3 Registration 12 2.4 Configuration 13
3.
THE EQUIPMENT SIMULATOR WINDOW
16
3.1 Equipment Simulator Window - General 16 3.2 Description of the Equipment Simulator Window 16 3.3 Menu and Toolbar 17 3.4 Device Tree Pane 18 3.5 Log Pane 19 3.6 Status Bar 19 3.7 Client Area 19
3.7.1 Data Windows 19
3.7.2 Scenario Windows 22
3.7.3 Arrange Data and Scenario Windows 22
4.
CONFIGURATION FILES AND WORKSPACES
23
4.1 Configuration Files and Workspaces – General 23 4.2 Configuration Files 23
4.2.1 Loading a standalone configuration file 23
4.2.2 Loading from an SCE zip file 24
4.3 Workspaces 24
5.
IF YOU DISABLE THE EMBED XML CONFIGURATION OPTION, THE
EQUIPMENT SIMULATOR SEARCHES THE CONFIGURATION FILE IN
THE DIRECTORY THE FILE WAS ORIGINALLY IMPORTED
FROM.SCENARIOS 26
5.1 Scenarios – General 26 5.2 Organization of Scenarios 26
5.3 The Scenario Window 27
5.3.1 The Control Center 28
5.3.2 The Code Section 28
5.3.3 The Log Section 29
5.4 Managing Scenarios 30
5.4.1 Scenario Files 30
5.4.2 Scenarios 31
5.5 Writing Scenarios 33
5.5.1 General Structure of Scenarios 33
5.5.2 Using Variables in Scenarios 34
5.5.3 Referencing UCA2 Data Leaves 35
5.5.4 Using Named Constants 37
5.5.5 Event Handler 38
5.5.6 Other Topics 42
5.6 Preparing a Simulation - General 42 5.7 Selecting Server and Clients 42 5.8 Attaching and Detaching Scenarios 44
5.8.1 Attaching Scenarios to Single Objects 46
5.8.2 Attaching Scenarios to Multiple Objects 46
5.8.3 Detaching Scenarios 48
5.9 Initializing Data Leaves 49 5.10 Preparing File Simulation 50
6.
STARTING AND STOPPING A SIMULATION
53
6.1 Starting and Stopping a Simulation – General 53 6.2 Starting a Simulation 53 6.3 Stopping a Simulation 53 6.4 Generation of Object Definition, Data Model and UCA2 Agency Configuration Files 54
6.4.1 LEAN.CFG 54
6.4.2 AGENCY.CFG 55
6.4.3 MMS_LOG.CFG 56
6.4.4 Generation of Data Model Files 56
7.
SIMULATION OF UCA2 OPERATIONS
58
7.1 Simulation of UCA2 Operations - General 58 7.2 Displaying Data Objects and Data Leaves 58
7.2.1 Reading mode 59
7.2.2 Illustration of modified Data Leaves 64
7.2.3 User Readable Names 66
7.3 Modifying Data Objects and Data Leaves 67
7.4 Server Operations 70
7.4.1 Modifying Data Objects and Data Leaves 70
7.4.2 Reason For Inclusion 70
7.4.3 Control Termination 71
7.4.4 Disable associations 72
7.5 Client Operations 73
7.5.1 Reading Data Objects and Data Leaves 73
7.5.2 Modifying Data Objects and Data Leaves 73
7.5.3 Write Quality and Control Operations 74
7.5.4 Time Synchronization 76
8.
SIMULATION OF REDUNDANCY
77
8.1 Simulation of Redundancy - General 77 8.2 Modifying the Current Redundancy Status 77
9.
SIMULATION OF FILES
79
9.1 Simulation of Files - General 79
9.2 Server 79
9.3 Client 79
9.3.1 Put File to Server 80
9.3.2 Get File from Server 80
9.3.3 Delete File 80
10.
SIMULATION OF GOOSE
81
10.1 Simulation of goose - General 81 10.2 Starting a simulation with goose 81 10.3 Receiving goose 82 10.4 Sending goose 83
11.
USING SCENARIOS DURING SIMULATION
84
11.1 Using Scenarios during Simulation - General 84 11.2 The Scenario Runtime Engine 84
11.2.1 Status of Scenarios 84
11.2.2 Execution of Scenarios 85
11.2.3 Runtime Errors 85
11.2.4 Configuration 85
11.3 Scenario Status View 88
11.3.1 Execution History 89
11.4 Starting and Stopping Scenarios 90
11.4.1 Starting Scenarios 90
11.4.2 Stopping Scenarios 93
12.
APPENDIX A BITSTRINGS USE
95
12.1 Bitstrings Use - General 95 12.2 Bitstrings use in the graphical user interface 95 12.3 Bitstrings use in the scenarios 95
13.
APPENDIX B SCENARIO LANGUAGE REFERENCE
97
13.1 Scenario Language – General 97 13.2 UCA2 Data Leaves, Scenario Variables and Named Constants 97 13.3 Data Types 98 13.4 Literals 99 13.5 Event Handler 100 13.6 Expressions and Operators 101 13.7 Built-In Functions 102 13.7.1 Statements 102 13.7.2 Assignment 102 13.7.3 CONTROLTERMINATION 103 13.7.4 DIRECTCONTROL 103 13.7.5 DIRECTCONTROLDONE 104 13.7.6 EXIT 105 13.7.7 FILEGET 105 13.7.8 FILEPUT 106 13.7.9 FOR Loop 106 13.7.10 GETGOOSEBITPAIR 107 13.7.11 GOTO 107 13.7.12 IF Statement 108 13.7.13 SBOSELECT 108 13.7.14 SBOSELECTDONE 109 13.7.15 SBODESELECT 109 13.7.16 SLEEP 110 13.7.17 TRACE - NOTRACE 110 13.7.18 WHILE Loop 111 13.7.19 UCA2 Assignment 111
14.
APPENDIX C EQUIPMENT SIMULATOR LOGGING
112
14.1 Equipment Simulator Logging 112
15.
APPENDIX D ERROR AND BUG REPORTS
114
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" 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" 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" describes how configuration files are imported and workspaces are used to store current simulation settings to files.
• The chapter "Scenarios" 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" and "Starting and Stopping a Simulation" describe the steps necessary to prepare simulations and how to start and stop simulations.
• The chapters "
• Simulation of UCA2 Operations", "Simulation of Files", "Simulation of Redundancy" and "Simulation of goose" explain how common UCA2 operations and redundancy operations can be simulated using the Equipment Simulator.
• "Using Scenarios during Simulation" 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" contains a detailed reference on how bitstring data are managed in Equipment Simulator.
• "Appendix B Scenario Language Reference" contains a detailed reference of all scenario language elements and concepts.
• "Appendix C Equipment Simulator Logging" and "Appendix D Error and Bug Reports" contain information about how logging can be used to investigate the Equipment Simulator behavior and which information error and bug reports should contain.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.
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). 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
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. 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 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.
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.
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
Escren.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.
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.
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 [email protected]. 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.
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\AREVA\Equipment
Simulator and
HKEY_CURRENT_USER\SOFTWARE\AREVA\-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\AREVA\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.
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.
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" 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.
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:
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.
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.
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.
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.
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.
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.
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" 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.
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 AREVA 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.
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.
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
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.
5.
IF YOU DISABLE THE EMBED XML CONFIGURATION OPTION, THE
EQUIPMENT SIMULATOR SEARCHES THE CONFIGURATION FILE IN
THE DIRECTORY THE FILE WAS ORIGINALLY IMPORTED
FROM.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.
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.
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". 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> ]
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
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.
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".
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.
• 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.
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".
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....
• 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
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".
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.
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 */.
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". For a list of all data types supported see "Data Types".
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.
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.
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. 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.
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.
• 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.
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:
ObSboSelect:
SboSelectDone( 1 ); EXIT;
If the Equipment Simulator does not find a handler for a direct control or SBO select operation the DirectControlDone() and SbSelectDone() 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 DirectControlDone() and
ODSboSelectDone() enable the Call ODSDirectControlDone() and
ODSSboSelectDone() automatically if not called by the scenario handler option. Similarly the scenario handler must call ControlTermination() with the
