Equip Sim User Manual

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