PACiS Equipment Simulator
Technical Guide ES/EN T/B11
Technical Guide PACiS Equipment Simulator
ES/EN T/B11 Page 1/2
PACiS Equipment Simulator CONTENT Safety & Handling
ES/EN SA/B11
Technical Data
ES/EN TD/B11
Technical Guide
ES/EN TG/B11
Installation
ES/EN IN/B11
Human Machine Interface
ES/EN HI/B11
Settings
ES/EN ST/B11
Language Reference
ES/EN LR/B11
Application
ES/EN AP/B11
Maintenance
ES/EN MF/B11
ES/EN T/B11
Technical Guide
Page 2/2
PACiS Equipment Simulator
BLANK PAGE
Safety & Handling
ES/EN SA/B11
PACiS Equipment Simulator
SAFETY & HANDLING
Safety & Handling PACiS Equipment Simulator
ES/EN SA/B11 Page 1/8
CONTENT 1.
INTRODUCTION
3
2.
SAFETY
4
2.1
Health and Safety
4
2.2
Explanation of symbols and labels
4
2.3
Installing, Commissioning and Servicing
4
2.4
Decommissioning and Disposal
4
3.
GUARANTIES
5
4.
COPYRIGHTS & TRADEMARKS
6
4.1
Copyrights
6
4.2
Trademarks
6
5.
WARNINGS REGARDING USE OF T&D AIS PRODUCTS
7
ES/EN SA/B11
Safety & Handling
Page 2/8
PACiS Equipment Simulator
BLANK PAGE
Safety & Handling PACiS Equipment Simulator
1.
ES/EN SA/B11 Page 3/8
INTRODUCTION The present document is a PACiS ES chapter of the documentation binders. It describes the safety, handling, packing and unpacking procedures applicable to PACiS ES software tools.
ES/EN SA/B11 Page 4/8
2.
Safety & Handling PACiS Equipment Simulator
SAFETY WARNING: THIS SAFETY SECTION SHOULD BE READ BEFORE COMMENCING ANY WORK ON THE EQUIPMENT.
2.1
Health and Safety The information in the Safety Section of the product documentation is intended to ensure that products are properly installed and handled in order to maintain them in a safe condition. It is assumed that everyone who will be associated with the equipment will be familiar with the contents of the Safety Section and all Safety documents related to the PC and Communication networks.
2.2
Explanation of symbols and labels The meaning of symbols and labels may be used on the equipment or in the product documentation, is given below.
2.3
Installing, Commissioning and Servicing Equipment operating conditions The equipments (PC and communication network supporting PACiS SMT) should be operated within the specified electrical and environmental limits. Fibre optic communication Where fibre optic communication devices are fitted, these should not be viewed directly. Optical power meters should be used to determine the operation or signal level of the device.
2.4
Decommissioning and Disposal Disposal It is recommended to avoid incineration and disposal of the PACiS ES CD-ROM. The product should be disposed of in a safe manner.
Safety & Handling PACiS Equipment Simulator
3.
ES/EN SA/B11 Page 5/8
GUARANTIES The media on which you received T&D AIS software are guaranted not to fail executing programing instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. T&D AIS will, at its option, repair or replace software media that do net execute programming instructions if T&D AIS receive notice of such defects during the guaranty period. T&D AIS does not guaranty that the operation of the software shall be uninterrupted or error free. A Return Material Authorisation (RMA) number must be obtained from the factory and clearly marked on the package before any equipment acceptance for guaranty work. T&D AIS will pay the shipping costs of returning to the owner parts, which are covered by warranty. T&D AIS believe that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, T&D AIS reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult T&D AIS if errors are suspected. In no event shall T&D AIS be liable for any damages arising out of or related to this document or the information contained in it. Expect as specified herein, T&D AIS makes no guaranties, express or implied and specifically disclaims and guaranties of merchantability or fitness for a particular purpose. Customer's rights to recover damages caused by fault or negligence on the part T&D AIS shall be limited to the amount therefore paid by the customer. T&D AIS will not be liable for damages resulting from loss of data, profits, use of products or incidental or consequential damages even if advised of the possibility thereof. This limitation of the liability of T&D AIS will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against T&D AIS must be brought within one year after the cause of action accrues. T&D AIS shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein dues net cover damages, defects, malfunctions, or service failures caused by owner's failure to follow the T&D AIS installation, operation, or maintenance instructions; owner's modification of the product; owner's abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control.
ES/EN SA/B11 Page 6/8
4.
COPYRIGHTS & TRADEMARKS
4.1
Copyrights
Safety & Handling PACiS Equipment Simulator
Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of T&D AIS. 4.2
Trademarks PACiS, PACiS SCE, PACiS ES, PACiS SMT, PACiS PS, PACiS SCE, T&D AIS, pacis.biz and pacis.com- are trademarks of T&D AIS. Product and company names mentioned herein are trademarks or trade names of their respective companies.
Safety & Handling PACiS Equipment Simulator
5.
ES/EN SA/B11 Page 7/8
WARNINGS REGARDING USE OF T&D AIS PRODUCTS T&D AIS products are not designed with components and testing for a level of reliability suitable for use in or in connection with surgical implants or as critical components in any life support systems whose failure to perform can reasonably be expected to cause significant injuries to a human. In any application, including the above reliability of operation of the software products can be impaired by adverse factors, including -but not limited- to fluctuations in electrical power supply, computer hardware malfunctions, computer operating system, software fitness, fitness of compilers and development software used to develop an application, installation errors, software and hardware compatibility problems, malfunctions or failures of electronic monitoring or control devices, transient failures of electronic systems (hardware and/or software), unanticipated uses or misuses, or errors from the user or applications designer (adverse factors such as these are collectively termed "System failures"). Any application where a system failure would create a risk of harm to property or persons (including the risk of bodily injuries and death) should not be reliant solely upon one form of electronic system due to the risk of system failure to avoid damage, injury or death, the user or application designer must take reasonably steps to protect against system failure, including -but not limited- to back-up or shut-down mechanisms, not because end-user system is customised and differs from T&D AIS' testing platforms but also a user or application designer may use T&D AIS products in combination with other products. These actions cannot be evaluated or contemplated by T&D AIS; Thus, the user or application designer is ultimately responsible for verifying and validating the suitability of T&D AIS products whenever they are incorporated in a system or application, even without limitation of the appropriate design, process and safety levels of such system or application.
ES/EN SA/B11
Safety & Handling
Page 8/8
PACiS Equipment Simulator
BLANK PAGE
Technical Data
ES/EN TD/B11
PACiS Equipment Simulator
TECHNICAL DATA
Technical Data PACiS Equipment Simulator
ES/EN TD/B11 Page 1/4
CONTENT 1.
SCOPE OF THE DOCUMENT
3
2.
REQUIREMENTS
4
ES/EN TD/B11
Technical Data
Page 2/4
PACiS Equipment Simulator
BLANK PAGE
Technical Data PACiS Equipment Simulator
1.
ES/EN TD/B11 Page 3/4
SCOPE OF THE DOCUMENT This document is a chapter of the PACiS Equipment Simulator (ES) documentation binder. It describes the Technical Data (ES/EN TD) of this software application.
ES/EN TD/B11 Page 4/4
2.
Technical Data PACiS Equipment Simulator
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).
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
TECHNICAL GUIDE
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 1/114
CONTENT 1.
INTRODUCTION
5
1.1
Overview
5
1.2
Organization of this Manual
5
2.
INSTALLATION AND CONFIGURATION
7
2.1
Installation and Configuration – General
7
2.2
Installation
7
2.2.1
Requirements
7
2.2.2
Distribution
7
2.2.3
Proceeding to the installation
8
2.2.4
What is installed
11
2.3
Registration
12
2.4
Configuration
13
3.
THE EQUIPMENT SIMULATOR WINDOW
16
3.1
Equipment Simulator Window - General
16
3.2
Description of the Equipment Simulator Window
16
3.3
Menu and Toolbar
17
3.4
Device Tree Pane
18
3.5
Log Pane
19
3.6
Status Bar
19
3.7
Client Area
19
3.7.1
Data Windows
19
3.7.2
Scenario Windows
22
3.7.3
Arrange Data and Scenario Windows
22
4.
CONFIGURATION FILES AND WORKSPACES
23
4.1
Configuration Files and Workspaces – General
23
4.2
Configuration Files
23
4.2.1
Loading a standalone configuration file
23
4.2.2
Loading from an SCE zip file
24
4.3
Workspaces
24
5.
IF YOU DISABLE THE EMBED XML CONFIGURATION OPTION, THE EQUIPMENT SIMULATOR SEARCHES THE CONFIGURATION FILE IN THE DIRECTORY THE FILE WAS ORIGINALLY IMPORTED FROM.SCENARIOS 26
5.1
Scenarios – General
26
5.2
Organization of Scenarios
26
ES/EN TG/B11 Page 2/114
Technical Guide PACiS Equipment Simulator
5.3
The Scenario Window
27
5.3.1
The Control Center
28
5.3.2
The Code Section
28
5.3.3
The Log Section
29
5.4
Managing Scenarios
30
5.4.1
Scenario Files
30
5.4.2
Scenarios
31
5.5
Writing Scenarios
33
5.5.1
General Structure of Scenarios
33
5.5.2
Using Variables in Scenarios
34
5.5.3
Referencing UCA2 Data Leaves
35
5.5.4
Using Named Constants
37
5.5.5
Event Handler
38
5.5.6
Other Topics
42
5.6
Preparing a Simulation - General
42
5.7
Selecting Server and Clients
42
5.8
Attaching and Detaching Scenarios
44
5.8.1
Attaching Scenarios to Single Objects
46
5.8.2
Attaching Scenarios to Multiple Objects
46
5.8.3
Detaching Scenarios
48
5.9
Initializing Data Leaves
49
5.10
Preparing File Simulation
50
6.
STARTING AND STOPPING A SIMULATION
53
6.1
Starting and Stopping a Simulation – General
53
6.2
Starting a Simulation
53
6.3
Stopping a Simulation
53
6.4
Generation of Object Definition, Data Model and UCA2 Agency Configuration Files 54
6.4.1
LEAN.CFG
54
6.4.2
AGENCY.CFG
55
6.4.3
MMS_LOG.CFG
56
6.4.4
Generation of Data Model Files
56
7.
SIMULATION OF UCA2 OPERATIONS
58
7.1
Simulation of UCA2 Operations - General
58
7.2
Displaying Data Objects and Data Leaves
58
7.2.1
Reading mode
59
7.2.2
Illustration of modified Data Leaves
64
7.2.3
User Readable Names
66
7.3
Modifying Data Objects and Data Leaves
67
7.3.1
Complete Modification using Dialogs
67
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 3/114
7.4
Server Operations
70
7.4.1
Modifying Data Objects and Data Leaves
70
7.4.2
Reason For Inclusion
70
7.4.3
Control Termination
71
7.4.4
Disable associations
72
7.5
Client Operations
73
7.5.1
Reading Data Objects and Data Leaves
73
7.5.2
Modifying Data Objects and Data Leaves
73
7.5.3
Write Quality and Control Operations
74
7.5.4
Time Synchronization
76
8.
SIMULATION OF REDUNDANCY
77
8.1
Simulation of Redundancy - General
77
8.2
Modifying the Current Redundancy Status
77
9.
SIMULATION OF FILES
79
9.1
Simulation of Files - General
79
9.2
Server
79
9.3
Client
79
9.3.1
Put File to Server
80
9.3.2
Get File from Server
80
9.3.3
Delete File
80
10.
SIMULATION OF GOOSE
81
10.1
Simulation of goose - General
81
10.2
Starting a simulation with goose
81
10.3
Receiving goose
82
10.4
Sending goose
83
11.
USING SCENARIOS DURING SIMULATION
84
11.1
Using Scenarios during Simulation - General
84
11.2
The Scenario Runtime Engine
84
11.2.1
Status of Scenarios
84
11.2.2
Execution of Scenarios
85
11.2.3
Runtime Errors
85
11.2.4
Configuration
85
11.3
Scenario Status View
88
11.3.1
Execution History
89
11.4
Starting and Stopping Scenarios
90
11.4.1
Starting Scenarios
90
11.4.2
Stopping Scenarios
93
11.4.3
Removing Scenarios
94
ES/EN TG/B11 Page 4/114
Technical Guide PACiS Equipment Simulator
12.
APPENDIX A BITSTRINGS USE
95
12.1
Bitstrings Use - General
95
12.2
Bitstrings use in the graphical user interface
95
12.3
Bitstrings use in the scenarios
95
13.
APPENDIX B SCENARIO LANGUAGE REFERENCE
97
13.1
Scenario Language – General
97
13.2
UCA2 Data Leaves, Scenario Variables and Named Constants
97
13.3
Data Types
98
13.4
Literals
99
13.5
Event Handler
100
13.6
Expressions and Operators
101
13.7
Built-In Functions
102
13.7.1
Statements
102
13.7.2
Assignment
102
13.7.3
CONTROLTERMINATION
103
13.7.4
DIRECTCONTROL
103
13.7.5
DIRECTCONTROLDONE
104
13.7.6
EXIT
105
13.7.7
FILEGET
105
13.7.8
FILEPUT
106
13.7.9
FOR Loop
106
13.7.10 GETGOOSEBITPAIR
107
13.7.11 GOTO
107
13.7.12 IF Statement
108
13.7.13 SBOSELECT
108
13.7.14 SBOSELECTDONE
109
13.7.15 SBODESELECT
109
13.7.16 SLEEP
110
13.7.17 TRACE - NOTRACE
110
13.7.18 WHILE Loop
111
13.7.19 UCA2 Assignment
111
14.
APPENDIX C EQUIPMENT SIMULATOR LOGGING
14.1
Equipment Simulator Logging
15.
APPENDIX D ERROR AND BUG REPORTS
15.1
Error and Bug Reports
112 112
114 114
Technical Guide PACiS Equipment Simulator
1.
INTRODUCTION
1.1
Overview
ES/EN TG/B11 Page 5/114
This user manual describes how the Equipment Simulator is installed, configured and used, how simulations are prepared, started and stopped and how scenarios can be used to automate certain tasks. The Equipment Simulator is designed for the Windows NT and Windows 2000 operating system families. The Equipment Simulator is based on the UCA2 Agency for communication with other devices or between Equipment Simulators on different computers. This user manual is for people who want to use the Equipment Simulator to browse a UCA2 network, simulate certain devices, which are physically not available, or investigate and control a remote device. This user manual assumes a basic knowledge of UCA2 terminology and procedures. For programmers who want to use the scenario language some knowledge and experience in developing in a high level language such as Visual Basic or PASCAL or a scripting language is needed. 1.2
Organization of this Manual The Equipment Simulator user manual is organized as follows: •
The chapter "Installation and Configuration" lists the hardware and software requirements for the Equipment Simulator and explains how to install and configure the Equipment Simulator.
•
The chapter "The Equipment Simulator Window" provides basic information about the organization of the Equipment Simulator main window and about how to adjust the appearance to your needs.
•
The chapter "Configuration Files and Workspaces" describes how configuration files are imported and workspaces are used to store current simulation settings to files.
•
The chapter "Scenarios" gives a detailed explanation about how scenarios can be used to automate simulation tasks. Beside the language syntax, all the important concepts of the scenario language are shown.
•
The chapters "Preparing a Simulation" and "Starting and Stopping a Simulation" describe the steps necessary to prepare simulations and how to start and stop simulations.
•
The chapters "
•
Simulation of UCA2 Operations", "Simulation of Files", "Simulation of Redundancy" and "Simulation of goose" explain how common UCA2 operations and redundancy operations can be simulated using the Equipment Simulator.
•
"Using Scenarios during Simulation" gives you detailed information about how the Equipment Simulator executes scenarios and which functions you can use to investigate and control running scenarios.
•
appendix A Bitstrings Use" contains a detailed reference on how bitstring data are managed in Equipment Simulator.
•
"Appendix B Scenario Language Reference" contains a detailed reference of all scenario language elements and concepts.
•
"Appendix C Equipment Simulator Logging" and "Appendix D Error and Bug Reports" contain information about how logging can be used to investigate the Equipment Simulator behavior and which information error and bug reports should contain.Relationship to Other Documents
ES/EN TG/B11 Page 6/114
Technical Guide PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
2.
INSTALLATION AND CONFIGURATION
2.1
Installation and Configuration – General
Page 7/114
This chapter deals with the following main topics:
2.2
•
Installation,
•
Registration,
•
Configuration.
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:
2.2.2
•
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).
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.
ES/EN TG/B11
Technical Guide
Page 8/114 2.2.3
PACiS Equipment Simulator
Proceeding to the installation NOTE:
You need administrator privileges to install the Equipment Simulator. If you currently do not have enough privileges, log off and on again with administrator privileges before installing the Equipment Simulator.
To install the Equipment Simulator simply start “Equipment simulator install.exe”. The Equipment Simulator setup wizard will guide you through the setup process. Click Next> on the welcome dialog.
Then read the license agreement and accept it by clicking Yes.
Then, if you install on a computer on which the equipment simulator was already installed, the following question appears.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 9/114
Except if you are an expert, you need to answer Yes to the question. Then you will have to enter your registration key (see registration) and user information. Enter your name, company, serial key and then proceed by clicking Next>. If you do not have a registration key at this time, you can let "dummyKey" as your serial. If you have already registered a previous version of the simulator, current information is automatically filled into the dialog. Do not change them if OK.
When the following dialog is displayed, choose the directory, where the Equipment Simulator should be installed (or leave default option) and click Next >.
ES/EN TG/B11 Page 10/114
Technical Guide PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
2.2.4
Page 11/114
What is installed Files The following files are installed the folder chosen during the installation: Bastypes.cfg
: List of basic types and common classes
Cmax20.dll
: dll codemax
Equipsim.cnt
: link file for the online help.
EquipSim.exe
: Equipment simulator executable file
EquipSim.hlp
: Equipment simulator online help file
Sceintf.dtd
: DTD for the XML configuration file
Escren.dll resources
: English release of the Equipment simulator
EquipSimUserManual.doc
: this document
EQT_SIM_ReleaseNote_1.2.doc
: Release Note
Startup menu item A folder is added to the startup. This folder contains 2 menu items. One to start the equipment simulator, and the other to view the user manual. By default, folder name is “Areva/Pacis/Equipment simulator”
ES/EN TG/B11 Page 12/114 2.3
Technical Guide PACiS Equipment Simulator
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 email address. An activation key for your computer is sent back and must be entered into the Equipment Simulator. Without registration, simulations are possible for a period of 60 days. After 60 days you can still use the Equipment Simulator, load XML configuration files and workspaces and browse through the device structure but you cannot start simulation. During the evaluation period of 60 days you can use all features of the Equipment Simulator including simulations. When you start a simulation the Equipment Simulator checks if you have registered. If not, the following dialog is displayed which gives information about the remaining evaluation period.
If you select Register Later, the Equipment Simulator starts the simulation process. Select Register Now to register the Equipment Simulator. You can also choose Help - Register... from the main menu to register the Equipment Simulator at any time. The following dialog is used for registration.
The unique number calculated for your computer is displayed in the first text box. Send this number per e-mail to
[email protected]. An activation key will be calculated for your computer and sent back to you. Enter the returned number into the registration key text box and click register.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 13/114
If you do not register within 60 days after the first start of the Equipment Simulator, you cannot start further simulations. Until you register, the following dialog is displayed every time you start a simulation.
2.4
Configuration When you start the Equipment Simulator the first time, some basic configuration settings should be checked. If you have installed the Equipment Simulator after the installation of the UCA2 Agency and you have selected the appropriate option in the Setup Wizard, no modification of configuration settings should be necessary. But in this case you should carefully read this chapter too and check if all settings, which are done automatically, are correct. For most of the configuration settings, the Equipment Simulator uses default values which are built in. With the exception of some paths for the UCA2 Agency and its configuration files you normally have to check only if the default values match your requirements and modify only those which do not. NOTE:
Configuration settings are stored in the Windows registry. If you want to transfer configuration settings between computers or users, you can use the Microsoft Registry Editor (REGEDIT.EXE) to export registry settings on one computer and import it on another computer. Configuration settings are stored in the HKEY_LOCAL_MACHINE\SOFTWARE\AREVA\Equipment Simulator and HKEY_CURRENT_USER\SOFTWARE\AREVA\Equipment Simulator registry keys. If you transfer the HKEY_LOCAL_MACHINE part of the Equipment Simulator settings be sure that you do not include the registration key stored under HKEY_LOCAL_MACHINE\SOFTWARE\AREVA\Equipment Simulator\Registration because the registration key is not valid on other computers.
This chapter contains a description of how to change the settings which are absolutely necessary. Other settings are described in the chapters where they are used and affect the behavior of the Equipment Simulator. NOTE:
The Equipment Simulator stores most of its settings in the Windows registry. Some of the settings and options are stored on a per user basis, some are not. Settings which are not stored on a per user basis are located in the HKEY_LOCAL_MACHINE registry key. To change settings stored under this registry key appropriate privileges are necessary, which ordinary users normally do not have. You must be logged on with administrator privileges or the appropriate right assigned by your administrator if you are logged on as ordinary user. Settings which cannot be changed are grayed in the options dialog.
ES/EN TG/B11 Page 14/114
Technical Guide PACiS Equipment Simulator
To change configuration settings and Equipment Simulator options choose Tools Options... from the menu. The following dialog is displayed:
Equipment Simulator options are organized in categories with the categories displayed in a tree like hierarchy on the left side and the options of a selected category on the right side. To change the settings for a category simply select its name on the left side. Please check and if necessary adjust the following settings when you first start the Equipment Simulator: 1.
Select the Object Foundry Settings - General category.
2.
Enter the path where the object foundry executable can be found. The object foundry, ODFOUNDRY.EXE, can normally be found in the directory where the UCA2 Agency has been installed. You can use the Browse... button to choose the path.
3.
Enter the path and name of the basic type ids configuration file. This file is normally copied during Equipment Simulator setup and can be found in the Equipment Simulator installation directory. The name of the file is BASTYPES.CFG. You can use the Browse... button to locate the file.
4.
Enter the path where the Equipment Simulator should store temporary object definition and data model files. You can use the Browse... button to choose the path.
5.
Select the UCA2 Agency Settings- General category.
6.
Enter the path where the UCA2 Agency is installed. You can use the Browse... button to choose the path.
7.
Select the Simulation of Files category.
8.
Enter the root directory where the Equipment Simulator should store files for servers which are simulated. For every server simulated by the Equipment Simulator a virtual root directory under this directory is created, where the server specific files are stored. See "Simulation of Files" for more details on how to simulate files with the Equipment Simulator. You can use the Browse... button to choose the path.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator NOTE:
Page 15/114
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.
ES/EN TG/B11 Page 16/114
3.
THE EQUIPMENT SIMULATOR WINDOW
3.1
Equipment Simulator Window - General
Technical Guide PACiS Equipment Simulator
This chapter deals with the following main topics:
3.2
•
Description of the Equipment Simulator Window,
•
Menu and Toolbar,
•
Device Tree Pane,
•
Log Pane,
•
Status Bar,
•
Client Area.
Description of the Equipment Simulator Window The Equipment Simulator main window consists of several items which can be adjusted to your needs. The following screen shot shows an example for the contents of a typical Equipment Simulator window:
This example shows a main window with a data window and a scenario window opened in the client area.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 17/114
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:
3.3
•
Menu and Toolbar,
•
Device Tree Pane,
•
Log Pane,
•
Status Bar,
•
Client Area.
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.
ES/EN TG/B11 Page 18/114 3.4
Technical Guide PACiS Equipment Simulator
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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 19/114
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 +1 to hide it. To show a hidden device tree pane, choose View - Device Tree or press +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 +2. You can clear the contents of the log by selecting Edit - Clear Log Window or clicking the on the toolbar. symbol Log level can be configured for each equipment simulator component with the Tools – Options –Logs configuration dialog. 3.6
Status Bar The status bar is used to display a single line of help text when you scroll through the menu or move the mouse over the toolbar.
The status bar can be hidden and shown using View - Status Bar. 3.7
Client Area The client area is used to display any number of data windows and scenario windows.
3.7.1
Data Windows Data windows are used to browse through the device structure or display and modify data object and data leaf values. Furthermore they are used to attach scenarios to and detach scenarios from items in the device structure. During a simulation it can be useful to open and arrange more than one data window in the client area to inspect the behavior of multiple data objects at once. Data windows are also used during simulation to initiate control operations or display and simulate files. Data windows contain a tree like device structure on the left side and an area to display information to a selected item on the right side.
ES/EN TG/B11 Page 20/114
Technical Guide PACiS Equipment Simulator
To display information to an item in the device structure, for example a brick or a data object, simply select it in the tree view on the left side. On the right side you can choose to display the objects which are children of the selected item or the scenarios which are attached to the item. The title bar of a data window contains the name of the parent object of the item displayed at the top level. In the above example the station bus is the parent of HMI server (S2KHMI1A) which is displayed at the top level in the tree view. You can create any number of data windows starting at any level in the device structure. The only exception is that you cannot display a single data object or data leaf in a data window. To create a new data window simply right click the item, which should be the top level object, in an existing window and choose New Window.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 21/114
In the following example the GLOBE brick is displayed in its own data window.
ES/EN TG/B11 Page 22/114 3.7.2
Technical Guide PACiS Equipment Simulator
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 on the toolbar. new window, click the symbol See "Scenarios" for a more detailed description on how to create, modify and manage scenarios. 3.7.3
Arrange Data and Scenario Windows If you have many data and scenario windows opened the Equipment Simulator can auto arrange them for a more clear display. Choose Window - Cascade, Window - Tile Horizontally or Window - Tile Vertically to force the Equipment Simulator to auto-arrange data and scenario windows. You can also or from the toolbar. use the symbols ,
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
4.
CONFIGURATION FILES AND WORKSPACES
4.1
Configuration Files and Workspaces – General
Page 23/114
This chapter deals with the following main topics:
4.2
•
Configuration Files,
•
Workspaces.
Configuration Files The import of a configuration file is the starting point of every simulation. Configuration files are XML files, which describe the structure of devices managed by the Equipment Simulator. Because it is not possible to manually create devices and their structure in the Equipment Simulator, configuration files are the only way to set up a simulation environment in the Equipment Simulator. Configuration files are created by the System Configuration Editor (SCE) which produce a Zip file containing the XML configuration file for the equipment simulator. You can load the configuration directly from the Zip or extract it manually from the zip, eventually modify it, and then load it. You can also build you own configuration with a text editor or an XML editor. For a documentation of the format of these XML files see AREVA PACIS -Equipment Simulator – Product Interface Description Document, Identification Number: 94.030.074e. In addition to the XML file the DTD (Document Type Definition) file, which is referenced by the XML file, must be present to import a device configuration into the Equipment Simulator. NOTE:
4.2.1
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.
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.
ES/EN TG/B11 Page 24/114 4.2.2
Technical Guide PACiS Equipment Simulator
Loading from an SCE zip file To get the configuration directly from an SCE produced Zip file choose file – Import SCE configuration. In the following dialog choose the SCE file you want to import and click OPEN.
4.3
Workspaces Workspaces are used to store the actual work into a file. Workspaces contain information about opened data and scenario windows, devices which are simulated as servers or clients, scenarios which are attached to data objects, or data values entered for data leaves. Workspace files are stored with the extension .ESW (Equipment Simulator Workspace) by default. To open an existing workspace, choose File - Open Workspace... or press +O. You on the toolbar. In the following dialog choose the workspace file can also click the symbol you want to open. To save the current workspace, choose File - Save Workspace, press +S or click the symbol on the toolbar. To save the current workspace under a different name, choose File - 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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 25/114
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.
ES/EN TG/B11 Page 26/114
Technical Guide PACiS Equipment Simulator
5.
IF YOU DISABLE THE EMBED XML CONFIGURATION OPTION, THE EQUIPMENT SIMULATOR SEARCHES THE CONFIGURATION FILE IN THE DIRECTORY THE FILE WAS ORIGINALLY IMPORTED FROM.SCENARIOS
5.1
Scenarios – General This chapter deals with the following main topics:
5.2
•
Organization of Scenarios,
•
The Scenario Window,
•
Managing Scenarios,
•
Writing Scenarios.
Organization of Scenarios Scenarios are used to automate simulations in the Equipment Simulator. They are organized in scenario files with the extension .ESS (Equipment Simulator Scenarios). Scenario files are XML files which contain zero, one or more scenarios. Scenario files are stored in global and workspace specific directories. The Equipment Simulator automatically loads all scenario files in the global directory when it is started and the scenarios in the workspace specific directory when a workspace is loaded. After scenario files have been loaded, scenarios contained in the files are ready for use in the Equipment Simulator. To configure the global directory for scenarios, choose Tools - Options... and select the Scenarios - General category.
Enter the directory for global scenario files and click OK. If a workspace is in use, the workspace specific directory can be configured by choosing File - Workspace Properties....
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 27/114
By default the directory where the workspace file is stored is used. If you want to change the workspace specific scenario directory enter the desired path and click OK. Because scenarios are organized in stand alone files they can be easily exchanged between different users and computers. To exchange scenario files, simply copy the desired files from the global or workspace specific directory to the destination computer. In the Equipment Simulator on the destination computer choose Scenarios - Refresh All to reload the new scenario files if the Equipment Simulator is already started. 5.3
The Scenario Window The scenario window is used to create, display, modify and delete scenarios and scenario files.
For a description on how to display one or more scenario windows see "Scenario Windows". The scenario window contains a control center at the top, the code section in the middle and a log section at the bottom.
ES/EN TG/B11 Page 28/114 5.3.1
Technical Guide PACiS Equipment Simulator
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: [ - ] 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:
Technical Guide PACiS Equipment Simulator 5.3.3
ES/EN TG/B11 Page 29/114
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.
ES/EN TG/B11 Page 30/114 5.4
Technical Guide PACiS Equipment Simulator
Managing Scenarios This section describes the scenario and scenario file properties, and how you can create, modify and delete scenario files and scenarios. For the following topics it is assumed that you have a scenario window opened.
5.4.1
Scenario Files Scenario files are used to group scenarios which belong together. For example you could create a scenario file for every type of brick with scenarios useful for the appropriate brick. It is up to you how you organize your scenarios, the Equipment Simulator does not impose any restrictions on how you organize them in scenario files. Beside the name of the file, scenario files have additional properties which can be displayed by choosing Scenario File - Properties... from the scenario window control center. To display these properties you first have to select a scenario, which is stored in the desired file.
Below the folder, where the scenario file is stored, a note is displayed which gives you the information if it is a global or workspace specific scenario file. Beside a description for the file, a list of named constants is part of the properties of a scenario file. Named constants are simple name-value pairs used to associate a constant integer, floating point or string value with a more readable name which can be used in the scenario code. For more details on how you can use named constants to make scenario code more readable see "Using Named Constants". Using the Add..., Modify... and Remove buttons you can manage the list of named constants stored with the scenario file. To manage scenario files you can: •
Create new scenario files Choose Scenario Files - New..., enter the name of the new file and decide if you want to create a global or workspace specific scenario file.
•
Rename existing scenario files Choose Scenario Files - Rename..., select the scenario file you want to rename and enter the new scenario file name.
Technical Guide PACiS Equipment Simulator
5.4.2
ES/EN TG/B11 Page 31/114
•
Delete existing scenario files Choose Scenario Files - Delete... and select the scenario file you want to delete. If you delete a scenario file, all scenarios contained in the file are removed.
•
Change properties of scenario files Select a scenario which is stored in the scenario file you want to modify and choose Scenario Files - Properties.... Modify the description of the scenario file or change the list of named constants.
•
Save all scenario files Choose Scenario Files - Save All to save all modifications done to scenarios to disk.
•
Reload scenario files Choose Scenario Files - Refresh All to reload all scenario files from the global and workspace specific scenario directories. Reloading of scenario files is useful if you manually copy scenario files from other users or computers to the global or workspace specific scenario directory and want to use those files immediately in the Equipment Simulator.
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.
ES/EN TG/B11 Page 32/114
Technical Guide PACiS Equipment Simulator
Using the settings for periodic execution of scenarios you can configure to start a scenario at a specific time or periodically by specifying an interval between starts. Periodic settings stored with scenarios are default values for the scenario which can be overridden when the scenario is attached to or started for a specific device object. The following settings are used for periodic execution of scenarios: •
Start time relative to You can choose to either start the scenario at a specific time of day or relative to the start time of the simulation. For example if you choose to start the scenario at a specific time of day and enter 12:00:00 for the start time, the scenario is started at 12:00:00 midday no matter at which time the simulation has been started. If you choose to start the scenario relative to the simulation start and enter 01:00:00 for the start time, the scenario is started one hour after simulation start.
•
Start time The start time is either a specific time of day or the period between simulation start and start of the scenario. The start time specifies the time the scenario is started the first time if executed periodically.
•
Number of starts The number of starts are used for periodic execution and give the number of times the scenario will be executed. For a scenario which should be executed once at a specific time set the number of starts parameter to one.
•
Interval between starts If a scenario is executed periodically, this setting controls the duration between two consecutive starts of the scenario.
The data objects and data leaves the scenario is designed for are used to automatically attach the scenario to multiple device objects. In the above example, where the scenario is designed for $ODLock$b1 data leaves, the Attach Scenario to Multiple Objects... function can be used to search the device structure for all $ODLock$b1 data leaves and automatically attach the scenario to those leaves. For a more detailed description on how to attach scenarios to device objects see "Attaching and Detaching Scenarios". Use the Add... and Remove buttons in the above dialog to change the list of data objects and data leaves the scenario is designed for. To manage scenarios you can: •
Create new scenarios Choose Scenario - New... to create a new scenario. In the following dialog enter the name of the scenario, choose the scenario file, where the scenario should be stored, and enter the desired properties for the scenario.
•
Rename existing scenarios Choose Scenario - Rename..., select the scenario you want to rename and enter a new name for the scenario.
•
Delete existing scenarios Select the scenario in the control center of the scenario window and choose Scenario - Delete....
•
Print scenarios Select the scenario in the control center of the scenario window and choose Scenario - Print... or press +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....
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator 5.5
Page 33/114
Writing Scenarios This section is focused on how to write scenarios using the scenario language built into the Equipment Simulator. It describes in addition to other topics how scenarios are structured, how variables and UCA2 data leaves can be used, how event handler can be used to start scenarios event triggered and how to use named constants. A basic knowledge in a high level programming language such as Visual Basic, PASCAL or a scripting language is necessary to understand this chapter. This section treats only base topics needed to write scenarios which cannot be found in traditional programming languages. For a complete reference of the scenario language, including all statements and built in functions supported, see "Appendix B Scenario Language Reference". NOTE:
5.5.1
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.
General Structure of Scenarios A scenario is composed of the following sections: [Global Variables] [Local Variables] [Statements and Event Handler] The sections must be exactly in the above order. The global and local variables sections can be omitted if no variables are used. Example: LOCALS %ODLock : BSTR1; END_LOCALS; // forever ... WHILE 1 DO // get the current value of the device locked control %ODLock := $CO$ODLock$b1; // wait until the device locked control changes WHILE $CO$ODLock$b1 == %ODLock DO SLEEP( 100 ); END_WHILE; /* set the device locked status and time */ $ST$LockSt$b1 := $CO$ODLock$b1; $ST$LockSt$t := DATETIME; END_WHILE; This example contains a local variables section which defines one local variable and a statement section without a handler. If the scenario is started the statement section is simply executed.
ES/EN TG/B11 Page 34/114
Technical Guide PACiS Equipment Simulator
In contrast, the following example has an event handler: OnDirectControl // call direct control done DirectControlDone( #TRUE ); /* set device locked status to device locked control and update quality descriptor and time tagging */ BEGIN_UPDATE; $ST$LockSt$b1 := $ODLock$b1; $ST$LockSt$t := DATETIME; $ST$LockSt$q := 0; END_UPDATE; // control termination with OK ControlTermination( $AckCode, #CO_ACK_OK ); EXIT; If this scenario is started there are no statements executed at the first place. The scenario is attached to a data leaf or data object and "waits" for an event. If a direct control operation is done on the data object or data leaf the scenario is attached to, the Equipment Simulator activates the scenario and executes the OnDirectControl handler. As you can see from the above examples, the scenario language supports two types of comments. A single line comment which is simply prefixed with the characters // and multi line comment which starts with /* and ends with */. 5.5.2
Using Variables in Scenarios The Equipment Simulator supports both local and global variables. Values of global variables keep their value after a scenario is finished, local variables loose their values after a scenario is finished. Global variables are initialized when a simulation is started and loose their values when a simulation is terminated. Variables are declared at the beginning of a scenario using the following syntax: GLOBALS : ; : ; ... END_GLOBALS; LOCALS : ; : ; ... 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 (_).
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 35/114
Examples for variable names: %i %ODSwOld %RunningValue %Float_Value1 Valid data types are basically all types supported by the UCA2 Agency. Examples for data types supported in scenarios: BOOL ENUM16 FLT32 FLT64 VSTR32 For BSTRs types, please see "appendix A Bitstrings Use". For a list of all data types supported see "Data Types". Example for the declaration of a few local and global variables: GLOBALS %gi : INT32S; %gLastValue : FLT32; %gReturnValue : BOOL; END_GLOBALS; LOCALS %Command : BSTR2; %SavedValue : FLT64; %FileName : VSTR128; END_LOCALS; To use variables in your code simply use the variable name prefixed with the percent sign in expressions and statements. NOTE:
5.5.3
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.
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.
ES/EN TG/B11
Technical Guide
Page 36/114
PACiS Equipment Simulator
For example if a $CO$ODSw$OperDev data leaf is used in a scenario it can be assigned to the $CO$ODSw$OperDev data leaf, the $CO$ODSw data object, the $CO functional component and the brick the $CO functional component is in. But the scenario cannot be attached to a server or logical device because the Equipment Simulator does not know the brick the data leaf is in. If the above scenario is attached to the brick $Server1/LD1/XCBR, the data leaf will be resolved to $Server1/LD1/XCBR$CO$ODSw$OperDev. Using the technique of relative data leaf references it is possible to write generic scenarios which can be started for data objects, bricks, etc. on different servers or logical devices. The described resolution process can be used on any level in the UCA2 name hierarchy. For instance it is possible to use the $f reference in a scenario and start it for the $Server1/LD1/XCBR$MX$Pres data object. The Equipment Simulator uses the forward slash (/) to separate server name, logical device name and brick name and the dollar sign to separate brick name, functional component name, data object name and data leaf name. Data leaf names can be used in scenarios like variable names. The Scenario Runtime Engine reads or writes the respective value from or to the server if a client is simulated. If a server is simulated, the value is read from or written to the local device database and the UCA2 Agency. Examples on how to use data leaf names in scenarios: SBODESELECT ( $CF$ODSwSBO$SBOState, "OPERATOR", "ORIGIN", DATETIME ); IF $b2 == 0x80 THEN SLEEP( 1000 ); END_IF; $MX$Pres$f := $MX$Pres$f + 1.; NOTE:
The Equipment Simulator can only read and write data leaves. It is not possible to read or write data objects or other compound objects which have multiple data leaves.
You can use the Copy Name to Clipboard function to let the Equipment Simulator build UCA2 names to save time when entering fully qualified names and to reduce the likelihood of misspelled names. Simply right click the data object or data leaf, whose name you need in a data window, and select Copy Name to Clipboard from the context menu or press +C. Switch to the scenario edit window and insert the UCA2 name by pressing +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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 37/114
Examples: $*$*$*$f := 0.0; $*$*$*$q := 0x01; In the above examples the Equipment Simulator assigns the given values to all data objects on all functional components on all bricks. This technique is called bulk assignment and can be very useful to initialize all data leaves of a server, logical device or brick. 5.5.4
Using Named Constants Named constants can be used to make the scenario code more readable. Constants are defined either using the scenario file or via name-value pairs in XML configuration files. Examples for named constants are: Name
Value
CO_ACK_OK
0
CO_DEVICE_ALREADY_IN_POS
8
CO_DEVICE_LOCKED
5
FALSE
0
TRUE
1
DEFAULT_OPERATOR
"Pete"
To define named constants using scenario files, choose Scenario File - Properties... from the scenario window and modify the named constants in the bottom section of the dialog.
ES/EN TG/B11 Page 38/114
Technical Guide PACiS Equipment Simulator
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: Valid names for constants can only contain the following characters: A-Z, a-z, 0-9, _. All other characters are not allowed. This means that name-value pairs from XML files with names like "Jammed/Motion" or blanks in the name (e.g. "l Threshold Violation") are not allowed. Named constants can be used in scenarios by simply prefixing the name of the constant with the number sign (#). Examples: DirectControlDone( #TRUE ); ControlTermination( $AckCode, #CO_DEVICE_LOCKED ); %bValid := #FALSE; 5.5.5
Event Handler Scenarios can contain handlers which are automatically executed if the appropriate event is processed by the Equipment Simulator. An event can be an UCA2 event or an Equipment Simulator internal event. Event handlers in scenarios are organized as labels followed by the code which should be executed and the statement EXIT to leave the scenario at the end of the handler. Example of an OnDirectControl handler of a $ODLock$b1 data leaf: OnDirectControl: // call direct control done with success DirectControlDone( #TRUE ); // set device locked status to device locked // control and update quality descriptor and // time tagging BEGIN_UPDATE; $ST$LockSt$b1 := $ODLock$b1; $ST$LockSt$t := DATETIME; $ST$LockSt$q := 0; END_UPDATE; // control termination with OK ControlTermination( $AckCode, #CO_ACK_OK ); EXIT; If the scenario which contains this handler is attached to the $ODLock data object or the $ODLock$b1 data leaf, and a direct control operation is executed for the data object or data leaf, the Equipment Simulator starts the handler automatically.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 39/114
The Equipment Simulator supports the following handlers in scenarios: OnDirectControl This handler is executed if a direct control operation is done by a client. It can only be used for data objects and data leaves in a server session. OnSboSelect This handler is executed if a SBO select operation is done by a client. It can only be used for data objects and data leaves in a server session. OnSboDeselect This handler is executed if a SBO deselect operation is done by a client. It can only be used for data objects and data leaves in a server session. •
OnWrite This handler is executed if the data object or data leaf the scenario is attached to is written by a client. It can only be used for data objects and data leaves in a server session.
•
OnControlTermination This handler is executed if a direct control operation is terminated by a server. It can only be used for data objects and data leaves in a client session.
•
OnReportReceived This handler is executed if a report is received for the appropriate data object or data leaf. It can only be used for data objects and data leaves in a client session.
•
OnWriteQuality This handler is executed if a writequality is done by a client to the data object or data leaf the scenario is attached to. It can only be used for data objects and data leaves in a server session
•
OnGooseReceived This handler is executed if a Goose is received for the appropriate server or named bitpair. It can only be in a server session.
•
OnTime This handler is executed when a scenario should be executed at a specific time or periodically.
•
OnSimulationStart This handler is executed when the simulation is started. The handler is executed only once and only for scenarios which are attached to device objects at the time the simulation is started. If a scenario is started or attached during a simulation, the handler is not executed.
•
Default This handler is executed if no specific handler can be found for an event. It can be used to handle different events equally.
The Equipment Simulator uses the following procedure to find and execute a handler for an event: •
It is checked if a scenario is attached to the data leaf or data object for which the event has been detected.
•
If a scenario is found, it is checked if a handler for the appropriate event can be found. If a handler is found, it is executed.
•
If the handler is not found, it is checked if a Default handler exists. If a Default handler exists, it is executed.
The Equipment Simulator checks both the data leaf and the data object for handlers in attached scenarios. Therefore you can assign a scenario to both the $ODLock data object and the $ODLock$b1 data leaf for example. Both attachments have the same affect when a UCA2 operation is done for the $ODLock$b1 data leaf.
ES/EN TG/B11
Technical Guide
Page 40/114
PACiS Equipment Simulator NOTE:
Scenarios must be assigned to data objects or data leaves for UCA2 event handlers to get executed. If a scenario is assigned at a higher level of the device hierarchy (e.g. at functional component or brick level) handler are not executed because the scenario code cannot determine for which data object or data leaf the operation has been done.
If more than one scenario is assigned to a data leaf or data object, the Equipment Simulator checks all these scenarios for handler and executes them if found. In the OnDirectControl and OnSboSelect handler the scenario code must call DirectControlDone() respectively SboSelectDone(). The parameter to these statements is 1 if the result is success or 0 if the result is failure. Example: ObSboSelect: SboSelectDone( 1 ); EXIT; If the Equipment Simulator does not find a handler for a direct control or SBO select operation the DirectControlDone() and SbSelectDone() statements are automatically called. It can be configured, that the Equipment Simulator should call the ODSDirectControlDone() and ODSSboSelectDone() services automatically if not called by the scenario handler. Choose Tools -Options... and select the Scenarios - Server Sessions category:
If you want the Equipment Simulator to automatically call DirectControlDone() and ODSboSelectDone() enable the Call ODSDirectControlDone() and ODSSboSelectDone() automatically if not called by the scenario handler option. Similarly the scenario handler must call ControlTermination() with the acknowledgement data leaf and the result code if a direct control handler is executed.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 41/114
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;
ES/EN TG/B11 Page 42/114 5.5.6
Technical Guide PACiS Equipment Simulator
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" .Preparing a Simulation
5.6
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" for more details). This chapter deals with the following main topics:
5.7
•
Selecting Server and Clients,
•
Attaching and Detaching Scenarios,
•
Initializing Data Leaves,
•
Preparing File Simulation.
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 43/114
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.
ES/EN TG/B11 Page 44/114 5.8
Technical Guide PACiS Equipment Simulator
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" 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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 45/114
The scenarios which are attached to device objects are displayed in the right pane of the device window:
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 to if a scenario is attached to it or one of its leaves. objects changes from 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.
ES/EN TG/B11 Page 46/114 5.8.1
Technical Guide PACiS Equipment Simulator
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. 5.8.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:
Beside the scenario name, the Equipment Simulator needs two components to automatically attach a scenario to multiple device objects.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 47/114
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"). 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.
ES/EN TG/B11 Page 48/114 5.8.3
Technical Guide PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator 5.9
Page 49/114
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" (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. 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.
ES/EN TG/B11
Technical Guide
Page 50/114 5.10
PACiS Equipment Simulator
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. 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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 51/114
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 .
•
Rename file or directory Right click the file or directory you want to rename and choose Rename.
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.
ES/EN TG/B11 Page 52/114
Technical Guide PACiS Equipment Simulator
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 - ....
The Equipment Simulator starts the viewer to display the selected file.
Technical Guide PACiS Equipment Simulator
6.
STARTING AND STOPPING A SIMULATION
6.1
Starting and Stopping a Simulation – General
ES/EN TG/B11 Page 53/114
This chapter deals with the following main topics:
6.2
•
Starting a Simulation,
•
Stopping a Simulation,
•
Generation of Object Definition, Data Model and UCA2 Agency Configuration Files.
Starting a Simulation After you have finished the preparation steps, described under "Preparing a Simulation", you can start a simulation. Choose Simulation - Start, press F5 or click the symbol simulation.
on the toolbar to start a
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.
•
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", "Simulation of Files" and "Simulation of goose" for more details). 6.3
Stopping a Simulation When you have finished with your simulation simply choose Simulation - Stop, press on the toolbar. +F5 or click the symbol 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.
ES/EN TG/B11 Page 54/114 6.4
Technical Guide PACiS Equipment Simulator
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.
6.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.
Technical Guide PACiS Equipment Simulator 6.4.2
ES/EN TG/B11 Page 55/114
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.
ES/EN TG/B11 Page 56/114 6.4.3
Technical Guide PACiS Equipment Simulator
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. 6.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.
Technical Guide PACiS Equipment Simulator 6.4.4.1
ES/EN TG/B11 Page 57/114
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.
6.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.
ES/EN TG/B11 Page 58/114
7.
SIMULATION OF UCA2 OPERATIONS
7.1
Simulation of UCA2 Operations - General
Technical Guide PACiS Equipment Simulator
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:
7.2
•
Displaying Data Objects and Data Leaves,
•
Modifying Data Objects and Data Leaves,
•
Server Operations,
•
Client Operations.
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.
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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 59/114
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" for more details) and they are displayed in brown-yellow color.
7.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.
ES/EN TG/B11 Page 60/114 7.2.1.1
Technical Guide PACiS Equipment Simulator
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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 61/114
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. Example 3: /BrickName$ DL5Name In this third example, all the data leaves called DL5Name and directly under bricks called BrickName are marked as unreadable.
ES/EN TG/B11
Technical Guide
Page 62/114
PACiS Equipment Simulator
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. 7.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:
7.2.1.3
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.
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.
Technical Guide PACiS Equipment Simulator 7.2.1.4
ES/EN TG/B11 Page 63/114
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.
7.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). 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.
ES/EN TG/B11 Page 64/114
Technical Guide PACiS Equipment Simulator
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). 7.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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 65/114
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.
ES/EN TG/B11
Technical Guide
Page 66/114 7.2.3
PACiS Equipment Simulator
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" 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:
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.
Technical Guide PACiS Equipment Simulator 7.3
ES/EN TG/B11 Page 67/114
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.
7.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.
ES/EN TG/B11 Page 68/114
Technical Guide PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 69/114
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. NOTE:
Please refer to "appendix A Bitstrings Use" for more details on how Bitstrings data are managed in Equipment Simulator.
ES/EN TG/B11 Page 70/114 7.4
Technical Guide PACiS Equipment Simulator
Server Operations In server mode you can modify data objects and data leaves and terminate control operations.
7.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" (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.
7.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.
You can select multiple default value for Reason For Inclusion. If 0x00 (none) is selected, all the previous selected values are reset.
Technical Guide PACiS Equipment Simulator 7.4.3
ES/EN TG/B11 Page 71/114
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.
ES/EN TG/B11 Page 72/114 7.4.4
Technical Guide PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator 7.5
Page 73/114
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.
7.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.
7.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" (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).
ES/EN TG/B11 Page 74/114 7.5.3
Technical Guide PACiS Equipment Simulator
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.
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 75/114
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. 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.
ES/EN TG/B11 Page 76/114 7.5.4
Technical Guide PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
8.
SIMULATION OF REDUNDANCY
8.1
Simulation of Redundancy - General
Page 77/114
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. 8.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). sets the status of the server to “active”. This button is available only when the The button 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.
ES/EN TG/B11 Page 78/114
Technical Guide PACiS Equipment Simulator
Technical Guide PACiS Equipment Simulator
9.
SIMULATION OF FILES
9.1
Simulation of Files - General
ES/EN TG/B11 Page 79/114
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:
9.2
•
Server,
•
Client.
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" for a detailed description on how to set up and modify the directory structure of a simulated server.
9.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.
ES/EN TG/B11 Page 80/114 9.3.1
Technical Guide PACiS Equipment Simulator
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. 9.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. 9.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 . The Equipment Simulator removes the selected file on the server.
Technical Guide PACiS Equipment Simulator
10.
SIMULATION OF GOOSE
10.1
Simulation of goose - General
ES/EN TG/B11 Page 81/114
The equipment simulator is able both to send and receive goose. This chapter deals with the following main topics:
10.2
•
Starting a simulation with goose,
•
Receiving goose,
•
Sending goose.
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).
ES/EN TG/B11
Technical Guide
Page 82/114
PACiS Equipment Simulator
Server with active goose
S0385ENa
10.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" to know what can be done in the scenario with incoming goose).
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator 10.4
Page 83/114
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.
Data object with an attached outgoing goose
S0386ENa
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
ES/EN TG/B11 Page 84/114
11.
USING SCENARIOS DURING SIMULATION
11.1
Using Scenarios during Simulation - General
Technical Guide PACiS Equipment Simulator
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:
11.2
•
The Scenario Runtime Engine,
•
Scenario Status View,
•
Starting and Stopping Scenarios.
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.
11.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.
•
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").
Technical Guide PACiS Equipment Simulator 11.2.2
ES/EN TG/B11 Page 85/114
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"). 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.
11.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" ). 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.
11.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.
ES/EN TG/B11
Technical Guide
Page 86/114
PACiS Equipment Simulator
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.
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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 87/114
Select the Scenarios - Client Session category to modify settings used when the Equipment Simulator is acting in client mode and connects to a server.
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.
ES/EN TG/B11 Page 88/114 11.3
Technical Guide PACiS Equipment Simulator
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" for more details on scenario states.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 89/114
•
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:
11.3.1
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.
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....
ES/EN TG/B11
Technical Guide
Page 90/114
PACiS Equipment Simulator
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. 11.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-shotscenarios". 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".
11.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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 91/114
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.
ES/EN TG/B11 Page 92/114
Technical Guide PACiS Equipment Simulator
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") 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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 93/114
After the scenario has been started its execution can be observed using the scenario status view (see "Scenario Status View"). 11.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.
The Equipment Simulator stops the scenario but leaves it in the status view. The symbol on and the state of the scenario transitions the left side of the scenario name is changed to to Finished.
ES/EN TG/B11
Technical Guide
Page 94/114 11.4.3
PACiS Equipment Simulator
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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
12.
APPENDIX A BITSTRINGS USE
12.1
Bitstrings Use - General
Page 95/114
This section deals with the following main topics:
12.2
•
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. 12.3
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.
ES/EN TG/B11 Page 96/114
Technical Guide PACiS Equipment Simulator
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
Technical Guide PACiS Equipment Simulator
13.
APPENDIX B SCENARIO LANGUAGE REFERENCE
13.1
Scenario Language – General
ES/EN TG/B11 Page 97/114
This section deals with the following main topics:
13.2
•
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" 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. 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" 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" for a more detailed description of how to define and use named constants.
ES/EN TG/B11
Technical Guide
Page 98/114
PACiS Equipment Simulator
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; 13.3
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") and to type cast variables, UCA2 data leaves or constant values to other data types. Data type names are case insensitive. 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
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 99/114
Data Type Name
Description
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
Range of Values
For a detailed description of UCA2 Standard Data Types and UCA2 Common Classes see UCA2 GOMSFE, Version 0.9. NOTE: 13.4
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"
ES/EN TG/B11
Technical Guide
Page 100/114 13.5
PACiS Equipment Simulator
Event Handler The Equipment Simulator supports the following event handler in scenarios (for a detailed description of event handler see "Event Handler"). 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. 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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator 13.6
Page 101/114
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 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. 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.
ES/EN TG/B11
Technical Guide
Page 102/114 13.7
PACiS Equipment Simulator
Built-In Functions The Equipment Simulator has a few built-in functions which can be used in expressions: Function
Description
RAND( ) returns a random number between 0 and - 1
13.7.1
Examples %value := RAND( 1000 ); %value := RAND( %max );
DATETIME
returns the current date $t := DATETIME; and time 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;
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.
13.7.2
Assignment Syntax: := ; 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 []; 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. 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.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 103/114
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 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; 13.7.3
CONTROLTERMINATION Syntax: CONTROLTERMINATION ( , ); 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 );
13.7.4
DIRECTCONTROL Syntax: DIRECTCONTROL ( , , , , );
ES/EN TG/B11 Page 104/114
Technical Guide PACiS Equipment Simulator
Description: This statement performs a direct control operation by writing the data given by to the data leaf given by . and must evaluate to strings, 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. must be a valid UCA2 data leaf name, data object names are not allowed. , and can be omitted. In this case default values which can be configured in the Equipment Simulator are used. Examples: DIRECTCONTROL ( $CO$ODSw$OperDev, 0x40, "OPERATOR", "ORIGIN", DATETIME ); IF DIRECTCONTROL( $ODSw$OperDev, 0x40 ) == 1 THEN SLEEP( 1000 ); ELSE EXIT; END_IF; 13.7.5
DIRECTCONTROLDONE Syntax: DIRECTCONTROLDONE( ); 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. 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 );
Technical Guide PACiS Equipment Simulator 13.7.6
ES/EN TG/B11 Page 105/114
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;
13.7.7
FILEGET Syntax: FILEGET ( , , ); Description: This statement reads a file from the specified server and stores the file on the local file system. must be the name of a valid server, which is in a client session of the Equipment Simulator. and 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;
ES/EN TG/B11 Page 106/114 13.7.8
Technical Guide PACiS Equipment Simulator
FILEPUT Syntax: FILEPUT ( , , ); Description: This statement writes a file from the local file system to the specified server. must be the name of a valid server, which is in a client session of the Equipment Simulator. and 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. Examples: FILEPUT ( "REMOTESRV", "C:\TEMP\CFG.SET", "CFG.SET" ); IF FILEPUT( "SRV", %local, %remote ) 1 THEN EXIT; END_IF;
13.7.9
FOR Loop Syntax: FOR = TO [STEP BY ] DO ... END_FOR; Description: Repeats a group of statements a specified number of times. If the STEP BY clause is omitted, the 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;
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 107/114
13.7.10 GETGOOSEBITPAIR Syntax: GetGooseBitPair(); GetGooseBitPair() ; GetGooseBitPair(,) ; 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. Examples: LOCALS BSTR8 : % IcomGoose ; BSTR2 : %BitPair ; END_LOCALS; %IcomGoose :=GetGooseBitPair(«CALCUL1 », « LD1/BAY1$ST$SWDS ») ; IF %IcomGoose [7] then %BitPair := %IcomGoose ; END_IF; 13.7.11 GOTO Syntax: GOTO :; ... : ... 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:
ES/EN TG/B11 Page 108/114
Technical Guide PACiS Equipment Simulator
13.7.12 IF Statement Syntax: IF THEN ... [ ELSE ... ] END_IF; Description: Conditionally executes a group of statements, depending on the value of . If evaluates to true, the group of statements after the THEN clause is executed. If 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; 13.7.13 SBOSELECT Syntax: SBOSELECT ( , , , , ); Description: This statement performs a SBO select operation for the given . and must evaluate to strings, 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. must be a valid UCA2 data leaf name, data object names are not allowed. , and can be omitted. In this case default values, which can be configured in the Equipment Simulator, are used. 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.
Technical Guide PACiS Equipment Simulator
ES/EN TG/B11 Page 109/114
Examples: SBOSELECT ( $CO$ODSw$SBO, "OPERATOR", "ORIGIN", DATETIME, 0x40 ); IF SBOSELECT( $ODSw$SBO,,,,0x80 ) == 1 THEN SLEEP( 1000 ); ELSE EXIT; END_IF; 13.7.14 SBOSELECTDONE Syntax: SBOSELECTDONE( ); Description: SBOSELECTDONE is called from an OnSboSelect handler to return the result of the SBO select operation to the UCA2 Agency. 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. 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 ); 13.7.15 SBODESELECT Syntax: SBODESELECT ( , , , ); Description: This statement performs a SBO deselect operation for the given . and must evaluate to strings, 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.
ES/EN TG/B11 Page 110/114
Technical Guide PACiS Equipment Simulator
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. must be a valid UCA2 data leaf name, data object names are not allowed. , and 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; 13.7.16 SLEEP Syntax: SLEEP( ) Description: This statement suspends the execution of the scenario by the specified amount of time. must be given in milliseconds. Examples: SLEEP( 1000 ); SLEEP( %nDur * 1000 ); 13.7.17 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") and the TRACE function should be called.
Technical Guide
ES/EN TG/B11
PACiS Equipment Simulator
Page 111/114
13.7.18 WHILE Loop Syntax: WHILE DO END_WHILE;
...
Description: Executes a series of statements as long as the condition given by is true. Examples: %i := 0; WHILE %i < 10 DO $MX$Pres$f := %i * 100; %i := %i + 1; END_WHILE; 13.7.19 UCA2 Assignment Syntax: := on the welcome dialog.
FIGURE 1 : WELCOM WINDOW Then read the license agreement and accept it by clicking Yes.
FIGURE 2 : LICENSE AGREEMENT Then, if you install on a computer on which the equipment simulator was already installed, the following question appears.
Installation
ES/EN IN/B11
PACiS Equipment Simulator
Page 5/12
FIGURE 3 : ES ALREADY INSTALLED 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.
FIGURE 4 : USER INFORMATION When the following dialog is displayed, choose the directory, where the Equipment Simulator should be installed (or leave default option) and click Next >.
ES/EN IN/B11 Page 6/12
Installation PACiS Equipment Simulator
FIGURE 5 : CHOOSER DESTINATION LOCATION 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>.
FIGURE 6 : SELECT PROGRAM FOLDER 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.
Installation
ES/EN IN/B11
PACiS Equipment Simulator
Page 7/12
FIGURE 7 : SETUP COMPLETE 2.1
What is installed Files The following files are installed the folder chosen during the installation: Bastypes.cfg
: List of basic types and common classes
Cmax20.dll
: dll codemax
Equipsim.cnt
: link file for the online help.
EquipSim.exe
: Equipment simulator executable file
EquipSim.hlp
: Equipment simulator online help file
Sceintf.dtd
: DTD for the XML configuration file
Escren.dll resources
: English release of the Equipment simulator
EquipSimUserManual.doc
: this document
EQT_SIM_ReleaseNote_1.2.doc Startup menu item
: Release Note
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 “Areva/Pacis/Equipment simulator”
ES/EN IN/B11
Installation
Page 8/12
3.
PACiS Equipment Simulator
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 email address. An activation key for your computer is sent back and must be entered into the Equipment Simulator. Without registration, simulations are possible for a period of 60 days. After 60 days you can still use the Equipment Simulator, load XML configuration files and workspaces and browse through the device structure but you cannot start simulation. During the evaluation period of 60 days you can use all features of the Equipment Simulator including simulations. When you start a simulation the Equipment Simulator checks if you have registered. If not, the following dialog is displayed which gives information about the remaining evaluation period.
FIGURE 8 : ES EVALUATION 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.
FIGURE 9 : 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.
Installation
ES/EN IN/B11
PACiS Equipment Simulator
FIGURE 10 : EVALUATION PERIODE EXPIRED
Page 9/12
ES/EN IN/B11
Installation
Page 10/12
4.
PACiS Equipment Simulator
SETTINGS When you start the Equipment Simulator the first time, some basic configuration settings should be checked. If you have installed the Equipment Simulator after the installation of the UCA2 Agency and you have selected the appropriate option in the Setup Wizard, no modification of configuration settings should be necessary. But in this case you should carefully read this chapter too and check if all settings, which are done automatically, are correct. For most of the configuration settings, the Equipment Simulator uses default values which are built in. With the exception of some paths for the UCA2 Agency and its configuration files you normally have to check only if the default values match your requirements and modify only those which do not. NOTE:
Configuration settings are stored in the Windows registry. If you want to transfer configuration settings between computers or users, you can use the Microsoft Registry Editor (REGEDIT.EXE) to export registry settings on one computer and import it on another computer. Configuration settings are stored in the HKEY_LOCAL_MACHINE\SOFTWARE\AREVA\Equipment Simulator and HKEY_CURRENT_USER\SOFTWARE\AREVA\Equipment Simulator registry keys. If you transfer the HKEY_LOCAL_MACHINE part of the Equipment Simulator settings be sure that you do not include the registration key stored under HKEY_LOCAL_MACHINE\SOFTWARE\AREVA\Equipment Simulator\Registration because the registration key is not valid on other computers.
This chapter contains a description of how to change the settings which are absolutely necessary. Other settings are described in the chapters where they are used and affect the behavior of the Equipment Simulator. NOTE:
The Equipment Simulator stores most of its settings in the Windows registry. Some of the settings and options are stored on a per user basis, some are not. Settings which are not stored on a per user basis are located in the HKEY_LOCAL_MACHINE registry key. To change settings stored under this registry key appropriate privileges are necessary, which ordinary users normally do not have. You must be logged on with administrator privileges or the appropriate right assigned by your administrator if you are logged on as ordinary user. Settings which cannot be changed are grayed in the options dialog.
Installation
ES/EN IN/B11
PACiS Equipment Simulator
Page 11/12
To change configuration settings and Equipment Simulator options choose Tools Options... from the menu. The following dialog is displayed:
FIGURE 11 : OPTIONS Equipment Simulator options are organized in categories with the categories displayed in a tree like hierarchy on the left side and the options of a selected category on the right side. To change the settings for a category simply select its name on the left side. Please check and if necessary adjust the following settings when you first start the Equipment Simulator: 1.
Select the Object Foundry Settings - General category.
2.
Enter the path where the object foundry executable can be found. The object foundry, ODFOUNDRY.EXE, can normally be found in the directory where the UCA2 Agency has been installed. You can use the Browse... button to choose the path.
3.
Enter the path and name of the basic type ids configuration file. This file is normally copied during Equipment Simulator setup and can be found in the Equipment Simulator installation directory. The name of the file is BASTYPES.CFG. You can use the Browse... button to locate the file.
4.
Enter the path where the Equipment Simulator should store temporary object definition and data model files. You can use the Browse... button to choose the path.
5.
Select the UCA2 Agency Settings- General category.
6.
Enter the path where the UCA2 Agency is installed. You can use the Browse... button to choose the path.
7.
Select the Simulation of Files category.
8.
Enter the root directory where the Equipment Simulator should store files for servers which are simulated. For every server simulated by the Equipment Simulator a virtual root directory under this directory is created, where the server specific files are stored. See "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini. for more details on how to simulate files with the Equipment Simulator. You can use the Browse... button to choose the path.
ES/EN IN/B11
Installation
Page 12/12
PACiS Equipment Simulator 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.
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator
HUMAN INTERFACE
Human Interface PACiS Equipment Simulator
ES/EN HI/B11 Page 1/16
CONTENT 1.
SCOPE OF THE DOCUMENT
3
2.
EQUIPMENT SIMULATOR MAIN WINDOW
4
3.
MENU AND TOOLBAR
6
4.
DEVICE TREE PANE
7
5.
LOG PANE
9
6.
STATUS BAR
10
7.
CLIENT AREA
11
7.1
Data Windows
11
7.2
Scenario Windows
13
7.3
Arrange Data and Scenario Windows
13
8.
WORKSPACES
14
ES/EN HI/B11
Human Interface
Page 2/16
PACiS Equipment Simulator
BLANK PAGE
Human Interface PACiS Equipment Simulator
1.
ES/EN HI/B11 Page 3/16
SCOPE OF THE DOCUMENT This document is a chapter of the PACiS Equipment Simulator documentation binder. It describes the User Interface (ES/EN HI) of this product. 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.
ES/EN HI/B11
Human Interface
Page 4/16
2.
PACiS Equipment Simulator
EQUIPMENT SIMULATOR MAIN 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:
FIGURE 1 : MAIN WINDOW This example shows a main window with a data window and a scenario window opened in the client area.
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator
Page 5/16
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.
ES/EN HI/B11
Human Interface
Page 6/16
3.
PACiS Equipment Simulator
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.
FIGURE 2 : TOOLBAR The toolbar can be hidden and shown using View - Toolbar.
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator
4.
Page 7/16
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.
FIGURE 3 : CONTEXTUAL MENU
ES/EN HI/B11 Page 8/16
Human Interface PACiS Equipment Simulator
FIGURE 4: STATION BUS NEW WINDOW 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 +1 to hide it. To show a hidden device tree pane, choose View - Device Tree or press +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.
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator
5.
Page 9/16
LOG PANE The log pane is used to display information about ongoing simulations or other events.
FIGURE 5 : LOG PANE The log pane can be hidden and shown by choosing View - Log or by pressing +2. You can clear the contents of the log by selecting Edit - Clear Log Window or clicking the on the toolbar. symbol Log level can be configured for each equipment simulator component with the Tools – Options –Logs configuration dialog.
ES/EN HI/B11 Page 10/16
6.
Human Interface PACiS Equipment Simulator
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.
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator
7.
Page 11/16
CLIENT AREA The client area is used to display any number of data windows and scenario windows.
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.
FIGURE 6 : SELECTED ITEM To display information to an item in the device structure, for example a brick or a data object, simply select it in the tree view on the left side. On the right side you can choose to display the objects which are children of the selected item or the scenarios which are attached to the item. The title bar of a data window contains the name of the parent object of the item displayed at the top level. In the above example the station bus is the parent of HMI server (S2KHMI1A) which is displayed at the top level in the tree view. You can create any number of data windows starting at any level in the device structure. The only exception is that you cannot display a single data object or data leaf in a data window. To create a new data window simply right click the item, which should be the top level object, in an existing window and choose New Window. In the following example the GLOBE brick is displayed in its own data window.
ES/EN HI/B11
Human Interface
Page 12/16
PACiS Equipment Simulator
FIGURE 7 : GLOBE CONTEXTUAL MENU
FIGURE 8 : SCENARIOS VIEW
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator 7.2
Page 13/16
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.
FIGURE 9 : SCENARIOS 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 on the toolbar. new window, click the symbol 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.
ES/EN HI/B11 Page 14/16
8.
Human Interface PACiS Equipment Simulator
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 +O. You on the toolbar. In the following dialog choose the workspace file can also click the symbol you want to open. To save the current workspace, choose File - Save Workspace, press +S or click the symbol on the toolbar. To save the current workspace under a different name, choose File - 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.
FIGURE 10 : SAVE WORKSPACE You can also change this option without saving a workspace by choosing File - Workspace Properties.... In the following dialog enable the Embed XML configuration option and click OK.
Human Interface
ES/EN HI/B11
PACiS Equipment Simulator
Page 15/16
FIGURE 11 : WORKSPACE PROPERTIES 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.
ES/EN HI/B11
Human Interface
Page 16/16
PACiS Equipment Simulator
BLANK PAGE
Settings
ES/EN ST/B11
PACiS Equipment Simulator
SETTINGS
Settings PACiS Equipment Simulator
ES/EN ST/B11 Page 1/6
CONTENT 1.
SCOPE OF THE DOCUMENT
3
2.
CONFIGURATION FILES
4
2.1
Loading a standalone configuration file
4
2.2
Loading from an SCE zip file
5
ES/EN ST/B11
Settings
Page 2/6
PACiS Equipment Simulator
BLANK PAGE
Settings PACiS Equipment Simulator
1.
ES/EN ST/B11 Page 3/6
SCOPE OF THE DOCUMENT This document is a chapter of the PACiS Equipment Simulator documentation binder. It describes the Settings (ES/EN ST) of this software application.
ES/EN ST/B11
Settings
Page 4/6
2.
PACiS Equipment Simulator
CONFIGURATION FILES The import of a configuration file is the starting point of every simulation. Configuration files are XML files, which describe the structure of devices managed by the Equipment Simulator. Because it is not possible to manually create devices and their structure in the Equipment Simulator, configuration files are the only way to set up a simulation environment in the Equipment Simulator. Configuration files are created by the System Configuration Editor (SCE) which produce a Zip file containing the XML configuration file for the equipment simulator. You can load the configuration directly from the Zip or extract it manually from the zip, eventually modify it, and then load it. You can also build you own configuration with a text editor or an XML editor. For a documentation of the format of these XML files see AREVA PACiS -Equipment Simulator – Product Interface Description Document, Identification Number: 94.030.074e. In addition to the XML file the DTD (Document Type Definition) file, which is referenced by the XML file, must be present to import a device configuration into the Equipment Simulator. NOTE:
2.1
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.
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.
FIGURE 1 : IMPORT XML CONFIGURATION 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.
Settings
ES/EN ST/B11
PACiS Equipment Simulator 2.2
Page 5/6
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.
FIGURE 2 : IMPORT SCE CONFIGURATION
ES/EN ST/B11
Settings
Page 6/6
PACiS Equipment Simulator
BLANK PAGE
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator
LANGUAGE REFERENCE
Language Reference PACiS Equipment Simulator
ES/EN LR/B11 Page 1/18
CONTENT 1.
SCOPE OF THE DOCUMENT
3
1.1
Scenario Language – General
3
1.2
UCA2 Data Leaves, Scenario Variables and Named Constants
3
1.2.1
UCA2 Data Leaves
3
1.2.2
Scenario Variables
3
1.2.3
Named Constants
4
1.3
Data Types
4
1.4
Literals
5
1.5
Event Handler
6
1.6
Expressions and Operators
7
1.7
Built-In Functions
8
1.8
Statements
8
1.8.1
Assignment
8
1.8.2
BEGIN_UPDATE - END_UPDATE
8
1.8.3
CONTROLTERMINATION
9
1.8.4
DIRECTCONTROL
9
1.8.5
DIRECTCONTROLDONE
10
1.8.6
EXIT
11
1.8.7
FILEGET
11
1.8.8
FILEPUT
12
1.8.9
FOR Loop
12
1.8.10
GETGOOSEBITPAIR
13
1.8.11
GOTO
13
1.8.12
IF Statement
14
1.8.13
SBOSELECT
14
1.8.14
SBOSELECTDONE
15
1.8.15
SBODESELECT
15
1.8.16
SLEEP
16
1.8.17
TRACE - NOTRACE
16
1.8.18
WHILE Loop
17
1.8.19
UCA2 Assignment
17
ES/EN LR/B11
Language Reference
Page 2/18
PACiS Equipment Simulator
BLANK PAGE
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator
1.
Page 3/18
SCOPE OF THE DOCUMENT The present document is an Equipment Simulator chapter of the documentation binder. It describes Language Reference of this software application. This document is the Language Reference chapter (ES/EN LR).
1.1
Scenario Language – General This section deals with the following main topics:
1.2
•
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.
1.2.1
UCA2 Data Leaves Data leaves can be referenced in scenarios by using their UCA2 names. They must be prefixed with the dollar sign ($). See "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini. 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. Examples: $Server1/LD1/XCBR1$CO$ODSw$OperDev WHILE $Server2/LD1/CFAN$ST$DevST$b2 0x40 DO ... END_WHILE; $f $MX$Pres$q
1.2.2
Scenario Variables Variable names must start with a percent sign (%) followed by any number of letters, digits and underscores (_). See "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini. 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;
ES/EN LR/B11
Language Reference
Page 4/18 1.2.3
PACiS Equipment Simulator
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 "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini. 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;
1.3
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 "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini.) and to type cast variables, UCA2 data leaves or constant values to other data types. Data type names are case insensitive. 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
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator
Page 5/18
Data Type Name
Description
Range of Values
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
For a detailed description of UCA2 Standard Data Types and UCA2 Common Classes see UCA2 GOMSFE, Version 0.9. NOTE: 1.4
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"
ES/EN LR/B11
Language Reference
Page 6/18 1.5
PACiS Equipment Simulator
Event Handler The Equipment Simulator supports the following event handler in scenarios (for a detailed description of event handler see "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini.). 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. 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.
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator 1.6
Page 7/18
Expressions and Operators The Equipment Simulator supports the following operators: Operator
Description
Examples
()
parentheses to change the default operator precedence
32 / ( 4 + 4 )
NOT
logical NOT
IF NOT %bValid THEN ... END_IF;
~
bitwise NOT
$ODLock$b1 := ~$ODLock$b1
()
type cast
%int := (INT32S) "23";
( %gi + 32 ) / $f
%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. 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.
ES/EN LR/B11
Language Reference
Page 8/18 1.7
PACiS Equipment Simulator
Built-In Functions The Equipment Simulator has a few built-in functions which can be used in expressions: Function
Description
RAND( ) returns a random number between 0 and - 1 DATETIME
Examples %value := RAND( 1000 ); %value := RAND( %max );
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;
1.8
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.
1.8.1
Assignment Syntax: := ;
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
1.8.2
BEGIN_UPDATE - END_UPDATE Syntax: BEGIN_UPDATE; ... END_UPDATE [];
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. 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.
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator
Page 9/18
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 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;
1.8.3
CONTROLTERMINATION Syntax: CONTROLTERMINATION ( , );
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 );
1.8.4
DIRECTCONTROL Syntax: DIRECTCONTROL ( , , , , );
Description: This statement performs a direct control operation by writing the data given by to the data leaf given by . and must evaluate to strings, 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.
ES/EN LR/B11
Language Reference
Page 10/18
PACiS Equipment Simulator
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. must be a valid UCA2 data leaf name, data object names are not allowed. , and can be omitted. In this case default values which can be configured in the Equipment Simulator are used. Examples: DIRECTCONTROL ( $CO$ODSw$OperDev, 0x40, "OPERATOR", "ORIGIN", DATETIME ); IF DIRECTCONTROL( $ODSw$OperDev, 0x40 ) == 1 THEN SLEEP( 1000 ); ELSE EXIT; END_IF;
1.8.5
DIRECTCONTROLDONE Syntax: DIRECTCONTROLDONE( );
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. 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 );
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator 1.8.6
Page 11/18
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;
1.8.7
FILEGET Syntax: FILEGET ( , , );
Description: This statement reads a file from the specified server and stores the file on the local file system. must be the name of a valid server, which is in a client session of the Equipment Simulator. and 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;
ES/EN LR/B11
Language Reference
Page 12/18 1.8.8
PACiS Equipment Simulator
FILEPUT Syntax: FILEPUT ( , , );
Description: This statement writes a file from the local file system to the specified server. must be the name of a valid server, which is in a client session of the Equipment Simulator. and 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. Examples: FILEPUT ( "REMOTESRV", "C:\TEMP\CFG.SET", "CFG.SET" ); IF FILEPUT( "SRV", %local, %remote ) 1 THEN EXIT; END_IF;
1.8.9
FOR Loop Syntax: FOR := TO [STEP BY ] DO ... END_FOR;
Description: Repeats a group of statements a specified number of times. If the STEP BY clause is omitted, the 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;
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator 1.8.10
Page 13/18
GETGOOSEBITPAIR Syntax: GetGooseBitPair(); GetGooseBitPair() ; GetGooseBitPair(,) ;
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. Examples: LOCALS BSTR8 : % IcomGoose ; BSTR2 : %BitPair ; END_LOCALS; %IcomGoose :=GetGooseBitPair(«CALCUL1 », « LD1/BAY1$ST$SWDS ») ; IF %IcomGoose [7] then %BitPair := %IcomGoose ; END_IF;
1.8.11
GOTO Syntax: GOTO :; ... : ...
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:
ES/EN LR/B11
Language Reference
Page 14/18 1.8.12
PACiS Equipment Simulator
IF Statement Syntax: IF THEN ... [ ELSE ... ] END_IF;
Description: Conditionally executes a group of statements, depending on the value of . If evaluates to true, the group of statements after the THEN clause is executed. If 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;
1.8.13
SBOSELECT Syntax: SBOSELECT ( , , , , );
Description: This statement performs a SBO select operation for the given . and must evaluate to strings, 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. must be a valid UCA2 data leaf name, data object names are not allowed. , and can be omitted. In this case default values, which can be configured in the Equipment Simulator, are used. 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.
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator
Page 15/18
Examples: SBOSELECT ( $CO$ODSw$SBO, "OPERATOR", "ORIGIN", DATETIME, 0x40 ); IF SBOSELECT( $ODSw$SBO,,,,0x80 ) == 1 THEN SLEEP( 1000 ); ELSE EXIT; END_IF;
1.8.14
SBOSELECTDONE Syntax: SBOSELECTDONE( );
Description: SBOSELECTDONE is called from an OnSboSelect handler to return the result of the SBO select operation to the UCA2 Agency. 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. 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 );
1.8.15
SBODESELECT Syntax: SBODESELECT ( , , , );
Description: This statement performs a SBO deselect operation for the given . and must evaluate to strings, 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. must be a valid UCA2 data leaf name, data object names are not allowed. , and can be omitted. In this case default values which can be configured in the Equipment Simulator are used.
ES/EN LR/B11
Language Reference
Page 16/18
PACiS Equipment Simulator
Examples: SBODESELECT ( $CF$ODSwSBO$SBOState, "OPERATOR", "ORIGIN", DATETIME ); IF SBODESELECT( $ODSwSBO$SBOState ) == 1 THEN SLEEP( 1000 ); ELSE EXIT; END_IF;
1.8.16
SLEEP Syntax: SLEEP( );
Description: This statement suspends the execution of the scenario by the specified amount of time. must be given in milliseconds. Examples: SLEEP( 1000 ); SLEEP( %nDur * 1000 );
1.8.17
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 "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini.) and the TRACE function should be called.
Language Reference
ES/EN LR/B11
PACiS Equipment Simulator 1.8.18
Page 17/18
WHILE Loop Syntax: WHILE DO ... END_WHILE;
Description: Executes a series of statements as long as the condition given by is true. Exemples: %i := 0; WHILE %i < 10 DO $MX$Pres$f := %i * 100; %i := %i + 1; END_WHILE;
1.8.19
UCA2 Assignment Syntax: := ;
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. Exemples: $*$*$q := 0x0000; $Server/LD1/XCBR1$MX$Pres$f := 5000; $Server/LD1/XCBR1$MX$Pres$t := DATETIME; $CO$ODSw$Origin := "Origin"; $q := ( $q & 0xff ) | 0x01;
ES/EN LR/B11
Language Reference
Page 18/18
PACiS Equipment Simulator
BLANK PAGE
Application
ES/EN AP/B11
PACiS Equipment Simulator
APPLICATION
Application PACiS Equipment Simulator
ES/EN AP/B11 Page 1/20
CONTENT 1.
SCOPE OF THE DOCUMENT
3
2.
ORGANIZATION OF SCENARIOS
4
3.
THE SCENARIO WINDOW
6
3.1
The Control Center
6
3.2
The Code Section
7
3.3
The Log Section
7
4.
MANAGING SCENARIOS
8
4.1
Scenario Files
8
4.2
Scenarios
9
5.
WRITING SCENARIOS
12
5.1
General Structure of Scenarios
12
5.2
Using Variables in Scenarios
13
5.3
Referencing UCA2 Data Leaves
14
5.4
Using Named Constants
16
5.5
Event Handler
17
5.6
Other Topics
20
ES/EN AP/B11
Application
Page 2/20
PACiS Equipment Simulator
BLANK PAGE
Application
ES/EN AP/B11
PACiS Equipment Simulator
1.
Page 3/20
SCOPE OF THE DOCUMENT The present document is an Equipment Simulator chapter of the documentation binder. It describes the use cases of this software application. This document is the Application chapter (ES/EN AP). The aim of his document is to show you how to make scenarios. This chapter deals with the following main topics: •
Organization of Scenarios,
•
The Scenario Window,
•
Managing Scenarios,
•
Writing Scenarios.
ES/EN AP/B11
Application
Page 4/20
2.
PACiS Equipment Simulator
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.
FIGURE 1 : OPTIONS Enter the directory for global scenario files and click OK.
Application
ES/EN AP/B11
PACiS Equipment Simulator
Page 5/20
If a workspace is in use, the workspace specific directory can be configured by choosing File - Workspace Properties....
FIGURE 2 : 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.
ES/EN AP/B11
Application
Page 6/20
3.
PACiS Equipment Simulator
THE SCENARIO WINDOW The scenario window is used to create, display, modify and delete scenarios and scenario files.
FIGURE 3 : SCENARIOS WINDOW For a description on how to display one or more scenario windows see "Scenarios Window". The Scenario window contains a control center at the top, the code section in the middle and a log section at the bottom. 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: [ - ]
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.
Application
ES/EN AP/B11
PACiS Equipment Simulator 3.2
Page 7/20
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:
FIGURE 4 : LANGUAGE TAB 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.
FIGURE 5 : SCENARIOS COMPILATION
ES/EN AP/B11
Application
Page 8/20
4.
PACiS Equipment Simulator
MANAGING SCENARIOS This section describes the scenario and scenario files 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.
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.
FIGURE 6 : SCENARIOS FILE PROPERTIES 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. Using the Add..., Modify... and Remove buttons you can manage the list of named constants stored with the scenario file.
Application
ES/EN AP/B11
PACiS Equipment Simulator
Page 9/20
To manage scenario files you can:
4.2
•
Create new scenario files Choose Scenario Files - New..., enter the name of the new file and decide if you want to create a global or workspace specific scenario file.
•
Rename existing scenario files Choose Scenario Files - Rename..., select the scenario file you want to rename and enter the new scenario file name.
•
Delete existing scenario files Choose Scenario Files - Delete... and select the scenario file you want to delete. If you delete a scenario file, all scenarios contained in the file are removed.
•
Change properties of scenario files Select a scenario which is stored in the scenario file you want to modify and choose Scenario Files - Properties.... Modify the description of the scenario file or change the list of named constants.
•
Save all scenario files Choose Scenario Files - Save All to save all modifications done to scenarios to disk.
•
Reload scenario files Choose Scenario Files - Refresh All to reload all scenario files from the global and workspace specific scenario directories. Reloading of scenario files is useful if you manually copy scenario files from other users or computers to the global or workspace specific scenario directory and want to use those files immediately in the Equipment Simulator.
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.
ES/EN AP/B11
Application
Page 10/20
PACiS Equipment Simulator
Scenario properties are displayed in the following dialog:
FIGURE 7 : SCENARIOS PROPERTIES Scenario properties consist of the name of the scenario, the file where the scenario is stored, a short description of the scenario, settings for periodic execution of the scenario and a list of data objects and data leaves for which the scenario is designed. For the latter to be displayed you must select the Advanced >> button. Using the settings for periodic execution of scenarios you can configure to start a scenario at a specific time or periodically by specifying an interval between starts. Periodic settings stored with scenarios are default values for the scenario, which can be overridden when the scenario is attached to or started for a specific device object. The following settings are used for periodic execution of scenarios: •
Start time relative to You can choose to either start the scenario at a specific time of day or relative to the start time of the simulation. For example if you choose to start the scenario at a specific time of day and enter 12:00:00 for the start time, the scenario is started at 12:00:00 midday no matter at which time the simulation has been started. If you choose to start the scenario relative to the simulation start and enter 01:00:00 for the start time, the scenario is started one hour after simulation start.
•
Start time The start time is either a specific time of day or the period between simulation start and start of the scenario. The start time specifies the time the scenario is started the first time if executed periodically.
•
Number of starts The number of starts are used for periodic execution and give the number of times the scenario will be executed. For a scenario which should be executed once at a specific time set the number of starts parameter to one.
Application
ES/EN AP/B11
PACiS Equipment Simulator •
Page 11/20
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. Use the Add... and Remove buttons in the above dialog to change the list of data objects and data leaves the scenario is designed for. To manage scenarios you can: •
Create new scenarios Choose Scenario - New... to create a new scenario. In the following dialog enter the name of the scenario, choose the scenario file, where the scenario should be stored, and enter the desired properties for the scenario.
•
Rename existing scenarios Choose Scenario - Rename..., select the scenario you want to rename and enter a new name for the scenario.
•
Delete existing scenarios Select the scenario in the control center of the scenario window and choose Scenario - Delete....
•
Print scenarios Select the scenario in the control center of the scenario window and choose Scenario - Print... or press +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....
ES/EN AP/B11
Application
Page 12/20
5.
PACiS Equipment Simulator
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 ES/EN LR. NOTE:
5.1
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.
General Structure of Scenarios A scenario is composed of the following sections: [Global Variables] [Local Variables] [Statements and Event Handler]
The sections must be exactly in the above order. The global and local variables sections can be omitted if no variables are used. Example: LOCALS %ODLock : BSTR1; END_LOCALS; // forever ... WHILE 1 DO // get the current value of the device locked control %ODLock := $CO$ODLock$b1; // wait until the device locked control changes WHILE $CO$ODLock$b1 == %ODLock DO SLEEP( 100 ); END_WHILE; /* set the device locked status and time */ $ST$LockSt$b1 := $CO$ODLock$b1; $ST$LockSt$t := DATETIME; END_WHILE;
This example contains a local variables section which defines one local variable and a statement section without a handler. If the scenario is started the statement section is simply executed.
Application
ES/EN AP/B11
PACiS Equipment Simulator
Page 13/20
In contrast, the following example has an event handler: OnDirectControl: // call direct control done DirectControlDone( #TRUE ); /* set device locked status to device locked control and update quality descriptor and time tagging */ BEGIN_UPDATE; $ST$LockSt$b1 := $ODLock$b1; $ST$LockSt$t := DATETIME; $ST$LockSt$q := 0; END_UPDATE; // control termination with OK ControlTermination( $AckCode, #CO_ACK_OK ); EXIT;
If this scenario is started there are no statements executed at the first place. The scenario is attached to a data leaf or data object and "waits" for an event. If a direct control operation is done on the data object or data leaf the scenario is attached to, the Equipment Simulator activates the scenario and executes the OnDirectControl handler. As you can see from the above examples, the scenario language supports two types of comments. A single line comment which is simply prefixed with the characters // and multi line comment which starts with /* and ends with */. 5.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 : ; : ; ... END_GLOBALS; LOCALS : ; : ; ... 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.
ES/EN AP/B11
Application
Page 14/20
PACiS Equipment Simulator
Examples for data types supported in scenarios: BOOL ENUM16 FLT32 FLT64 VSTR32
Example for the declaration of a few local and global variables: GLOBALS %gi : INT32S; %gLastValue : FLT32; %gReturnValue : BOOL; END_GLOBALS; LOCALS %Command : BSTR2; %SavedValue : FLT64; %FileName : VSTR128; END_LOCALS;
To use variables in your code simply use the variable name prefixed with the percent sign in expressions and statements. NOTE:
5.3
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.
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.
Application
ES/EN AP/B11
PACiS Equipment Simulator
Page 15/20
The Equipment Simulator uses the forward slash (/) to separate server name, logical device name and brick name and the dollar sign to separate brick name, functional component name, data object name and data leaf name. Data leaf names can be used in scenarios like variable names. The Scenario Runtime Engine reads or writes the respective value from or to the server if a client is simulated. If a server is simulated, the value is read from or written to the local device database and the UCA2 Agency. Examples on how to use data leaf names in scenarios: SBODESELECT ( $CF$ODSwSBO$SBOState, "OPERATOR", "ORIGIN", DATETIME ); IF $b2 == 0x80 THEN SLEEP( 1000 ); END_IF; $MX$Pres$f := $MX$Pres$f + 1.;
NOTE:
The Equipment Simulator can only read and write data leaves. It is not possible to read or write data objects or other compound objects which have multiple data leaves.
You can use the Copy Name to Clipboard function to let the Equipment Simulator build UCA2 names to save time when entering fully qualified names and to reduce the likelihood of misspelled names. Simply right click the data object or data leaf, whose name you need in a data window, and select Copy Name to Clipboard from the context menu or press +C. Switch to the scenario edit window and insert the UCA2 name by pressing +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.
ES/EN AP/B11
Application
Page 16/20 5.4
PACiS Equipment Simulator
Using Named Constants Named constants can be used to make the scenario code more readable. Constants are defined either using the scenario file or via name-value pairs in XML configuration files. Examples for named constants are: Name
Value
CO_ACK_OK
0
CO_DEVICE_ALREADY_IN_POS
8
CO_DEVICE_LOCKED
5
FALSE
0
TRUE
1
DEFAULT_OPERATOR
"Pete"
To define named constants using scenario files, choose Scenario File - Properties... from the scenario window and modify the named constants in the bottom section of the dialog.
FIGURE 8 : PROPERTIES 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:
Application
ES/EN AP/B11
PACiS Equipment Simulator
Page 17/20
Valid names for constants can only contain the following characters: A-Z, a-z, 0-9, _. All other characters are not allowed. This means that name-value pairs from XML files with names like "Jammed/Motion" or blanks in the name (e.g. "l Threshold Violation") are not allowed. Named constants can be used in scenarios by simply prefixing the name of the constant with the number sign (#). Examples: DirectControlDone( #TRUE ); ControlTermination( $AckCode, #CO_DEVICE_LOCKED ); %bValid := #FALSE;
5.5
Event Handler Scenarios can contain handlers which are automatically executed if the appropriate event is processed by the Equipment Simulator. An event can be an UCA2 event or an Equipment Simulator internal event. Event handlers in scenarios are organized as labels followed by the code which should be executed and the statement EXIT to leave the scenario at the end of the handler. Example of an OnDirectControl handler of a $ODLock$b1 data leaf: OnDirectControl: // call direct control done with success DirectControlDone( #TRUE ); // set device locked status to device locked // control and update quality descriptor and // time tagging BEGIN_UPDATE; $ST$LockSt$b1 := $ODLock$b1; $ST$LockSt$t := DATETIME; $ST$LockSt$q := 0; END_UPDATE; // control termination with OK ControlTermination( $AckCode, #CO_ACK_OK ); EXIT;
If the scenario which contains this handler is attached to the $ODLock data object or the $ODLock$b1 data leaf, and a direct control operation is executed for the data object or data leaf, the Equipment Simulator starts the handler automatically. The Equipment Simulator supports the following handlers in scenarios: •
OnDirectControl This handler is executed if a direct control operation is done by a client. It can only be used for data objects and data leaves in a server session.
•
OnSboSelect This handler is executed if a SBO select operation is done by a client. It can only be used for data objects and data leaves in a server session.
•
OnSboDeselect This handler is executed if a SBO deselect operation is done by a client. It can only be used for data objects and data leaves in a server session.
•
OnWrite This handler is executed if the data object or data leaf the scenario is attached to is written by a client. It can only be used for data objects and data leaves in a server session.
ES/EN AP/B11
Application
Page 18/20
PACiS Equipment Simulator
•
OnControlTermination This handler is executed if a direct control operation is terminated by a server. It can only be used for data objects and data leaves in a client session.
•
OnReportReceived This handler is executed if a report is received for the appropriate data object or data leaf. It can only be used for data objects and data leaves in a client session.
•
OnWriteQuality This handler is executed if a writequality is done by a client to the data object or data leaf the scenario is attached to. It can only be used for data objects and data leaves in a server session
•
OnGooseReceived This handler is executed if a Goose is received for the appropriate server or named bitpair. It can only be in a server session.
•
OnTime This handler is executed when a scenario should be executed at a specific time or periodically.
•
OnSimulationStart This handler is executed when the simulation is started. The handler is executed only once and only for scenarios which are attached to device objects at the time the simulation is started. If a scenario is started or attached during a simulation, the handler is not executed.
•
Default This handler is executed if no specific handler can be found for an event. It can be used to handle different events equally.
The Equipment Simulator uses the following procedure to find and execute a handler for an event: •
It is checked if a scenario is attached to the data leaf or data object for which the event has been detected.
•
If a scenario is found, it is checked if a handler for the appropriate event can be found. If a handler is found, it is executed.
•
If the handler is not found, it is checked if a Default handler exists. If a Default handler exists, it is executed.
The Equipment Simulator checks both the data leaf and the data object for handlers in attached scenarios. Therefore you can assign a scenario to both the $ODLock data object and the $ODLock$b1 data leaf for example. Both attachments have the same affect when a UCA2 operation is done for the $ODLock$b1 data leaf. NOTE:
Scenarios must be assigned to data objects or data leaves for UCA2 event handlers to get executed. If a scenario is assigned at a higher level of the device hierarchy (e.g. at functional component or brick level) handler are not executed because the scenario code cannot determine for which data object or data leaf the operation has been done.
If more than one scenario is assigned to a data leaf or data object, the Equipment Simulator checks all these scenarios for handler and executes them if found. In the OnDirectControl and OnSboSelect handler the scenario code must call DirectControlDone() respectively SboSelectDone(). The parameter to these statements is 1 if the result is success or 0 if the result is failure.
Application
ES/EN AP/B11
PACiS Equipment Simulator
Page 19/20
Example: ObSboSelect: SboSelectDone( 1 ); EXIT;
If the Equipment Simulator does not find a handler for a direct control or SBO select operation the DirectControlDone() and SbSelectDone() statements are automatically called. It can be configured, that the Equipment Simulator should call the ODSDirectControlDone() and ODSSboSelectDone() services automatically if not called by the scenario handler. Choose Tools -Options... and select the Scenarios - Server Sessions category:
FIGURE 9 : OPTIONS If you want the Equipment Simulator to automatically call DirectControlDone() and ODSboSelectDone() enable the Call ODSDirectControlDone() and ODSSboSelectDone() automatically if not called by the scenario handler option. Similarly the scenario handler must call ControlTermination() with acknowledgement data leaf and the result code if a direct control handler is executed.
the
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.
ES/EN AP/B11
Application
Page 20/20
PACiS Equipment Simulator
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;
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 */.
Maintenance
ES/EN MF/B11
PACiS Equipment Simulator
MAINTENANCE
Maintenance PACiS Equipment Simulator
ES/EN MF/B11 Page 1/6
CONTENT 1.
SCOPE OF THE DOCUMENT
3
2.
ERROR AND BUG REPORTS
4
3.
EQUIPMENT SIMULATOR LOGGING
5
ES/EN MF/B11
Maintenance
Page 2/6
PACiS Equipment Simulator
BLANK PAGE
Maintenance PACiS Equipment Simulator
1.
ES/EN MF/B11 Page 3/6
SCOPE OF THE DOCUMENT This document is a chapter of the PACiS Equipment Simulator documentation binder, describing the Maintenance procedures (ES/EN MF) of this software product.
ES/EN MF/B11 Page 4/6
2.
Maintenance PACiS Equipment Simulator
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\AREVA\Equipment Simulator and HKEY_CURRENT_USER\Software\AREVA\Equipment Simulator subkeys into separate registry files).
Maintenance
ES/EN MF/B11
PACiS Equipment Simulator
3.
Page 5/6
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.
FIGURE 1 : LOGGING OPTIONS 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. 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 "Erreur ! Source du renvoi introuvable." on page Erreur ! Signet non défini.)
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
ES/EN MF/B11 Page 6/6
Maintenance PACiS Equipment Simulator
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.
Publication: ES/EN T/B11
