2.9 What is a Custom Algorithm Block? 37. 2.9.1 CAB creation. 37. 2.9.2 CAB functionality. 37. 2.10 What is a Custom Data Block? 38. 2.10.1 Creating a CDB.
EXPERION PKS
RELEASE 516
Custom Algorithm and Data Blocks User's Guide
EPDOC-XX26-en-516A August 2020
Disclaimer
This document contains Honeywell proprietary information. Information contained herein is to be used solely for the purpose submitted, and no part of this document or its contents shall be reproduced, published, or disclosed to a third party without the express permission of Honeywell International Sàrl. While this information is presented in good faith and believed to be accurate, Honeywell disclaims the implied warranties of merchantability and fitness for a purpose and makes no express warranties except as may be stated in its written agreement with and for its customer. In no event is Honeywell liable to anyone for any direct, special, or consequential damages. The information and specifications in this document are subject to change without notice. Copyright 2019 - Honeywell International Sàrl
2
Contents Chapter 1 - About This Document
1.1 Revision History 1.2 References
Chapter 2 - Introduction
2.1 Overview 2.2 Who should use this guide 2.3 Terms and acronyms 2.4 Prerequisite knowledge 2.5 What's new in R516 2.6 What's new in R511 2.7 What's new in R430 2.8 What's new in R410 2.9 What is a Custom Algorithm Block?
2.9.1 CAB creation 2.9.2 CAB functionality
2.10 What is a Custom Data Block?
2.10.1 Creating a CDB
2.11 Getting started tutorial
2.11.1 System requirements 2.11.2 Description of the tutorial examples 2.11.3 Creating a CAB type 2.11.4 Instantiating the CAB type in a control strategy 2.11.5 Creating a CDB type 2.11.6 Instantiating the CDB type 2.11.7 Additional examples
Chapter 3 - CAB and CDB purpose
3.1 Purpose, use, and value of the system
3 35
35 35
36
36 36 36 36 36 37 37 37 37
37 37
38
38
38
38 39 39 41 42 43 45
46
46
3
3.1.1 Why use CAB?
46
3.1.2 CDB overview
46
3.1.3 Why use CDB?
47
3.1.4 System functions that support CAB and CDB
47
3.1.5 Relationships of subsystems
47
3.2 CAB in system context
48
3.2.1 Description of subsystems
49
3.2.2 Platform hosting of block type categories
50
3.2.3 Role of block types, instances, and templates
50
3.3 CAB functional overview
52
3.3.1 How a CAB works
52
3.3.2 CAB data characteristics
57
3.3.3 CAB algorithm characteristics
57
3.3.4 CAB execution mode characteristics
58
3.4 CDB functional overview
58
3.4.1 How a CDB works
58
3.4.2 CDB data definition characteristics
60
Chapter 4 - CAB and CDB system planning and design
61
4.1 System architecture
61
4.1.1 Role of CAB and CDB in system architecture
61
4.1.2 System requirements
61
4.1.3 CDB Requirements
62
4.2 CAB and CDB hardware and software requirements
63
4.2.1 Hardware requirements for CAB and CDB
63
4.2.2 Software environment requirements for CAB and CDB
63
4.3 Security policy
65
4.3.1 User access
65
4.3.2 CDP Access Lock attribute
65
4.3.3 SIM-ACE and the Microsoft Visual Studio debugger
65
4.3.4 Configuring for OPC history data access
66
4.4 Input data validation
66
4
Chapter 5 - CAB memory and processing load considerations
67
5.1 CAB on ACE
67
5.1.1 Determine ACE CAB processing capacity
67
5.1.2 Determine ACE configuration limits for CAB/ACE types and instances
67
5.1.3 Determine ACE memory utilization
68
5.1.4 Determine ACE shutdown horizon
69
5.2 CAB on C300
69
5.2.1 Determine C300 CAB processing capacity
70
5.2.2 Determine C300 configuration limits for CAB types and instances
70
5.2.3 Determine C300 memory utilization
70
5.2.4 Determine Size limits on CAB/C300 block types and instances
71
5.3 Configuration limits
71
5.3.1 Determine CAB configuration limits
71
5.3.2 Determine CDB configuration limits
72
5.4 Determine CDB memory utilization
73
5.5 C200, C200E, and C300 memory availability
73
5.6 Exceptional CABs
73
Chapter 6 - CAB and CDB type planning and design
74
6.1 Control strategy
74
6.1.1 Determine that CAB and CDB are needed
74
6.1.2 Develop strategies
74
6.2 Configuration planning
74
6.2.1 Configuration planning steps
74
6.2.2 CAB execution platform considerations
75
6.2.3 Software development considerations
75
6.2.4 Requirements external to system
75
6.3 CAB configuration choices
76
6.3.1 Define the CAB naming strategy
76
6.3.2 Make CAB user interface decisions
76
6.3.3 Determine the CAB algorithm and parameters
77
5
6.3.4 Define execution mode
77
6.3.5 Support for evaluating parameter re-referencing on ACE
78
6.3.6 Determine Continuous Control access
78
6.3.7 Data and algorithm characteristics of CAB
78
6.3.8 CAB fixed definition parameters
79
6.3.9 CAB states
79
6.3.10 CAB notifications
80
6.3.11 CAB constraints
80
6.3.12 CAB API
81
6.4 Design the CAB
81
6.4.1 Design the usage of the CAB
81
6.4.2 Determine when to use CAB
82
6.4.3 Develop a conceptual design
82
6.4.4 Organizing CAB programs for best performance
82
6.4.5 Determine CAB/ACE memory usage
84
6.4.6 Determine CAB/C300 memory usage
84
6.4.7 Determine shutdown horizon for ACE
84
6.4.8 Determine the CAB distribution policy
84
6.5 CDB configuration choices
85
6.5.1 Define the CDB naming strategy
85
6.5.2 Determine where the CDB will execute
85
6.5.3 Make CDB user interface decisions
85
6.5.4 Data characteristics of CDB
86
6.5.5 CDB fixed definition parameters
86
6.5.6 CDB constraints
86
6.6 Design the CDB
86
6.6.1 Design the usage of the CDB
86
6.6.2 Determine when to use CDB
87
6.6.3 Define the CDB distribution policy
87
Chapter 7 - CAB and CDB installation and upgrade
88
7.1 Hardware installation and upgrade
88
7.2 Software installation and upgrade
88
6
7.2.1 Licensing considerations
88
7.2.2 CAB Developer license
88
7.2.3 ACE Base license
88
7.2.4 Possible licensing scenarios
89
7.2.5 Interoperability between R410 and R400, R3xx systems
89
7.2.6 Interoperability of ACE controllers with CAB types running on different
.NET versions
89
Chapter 8 - CAB configuration
92
8.1 Create a new CAB type
92
8.1.1 CAB development environment overview
92
8.1.2 Layout of the development environment
92
8.1.3 Opening the CAB Source Code window
93
8.1.4 Opening the Parameter Definition Editor window
93
8.1.5 Honeywell additions to Microsoft Visual Studio
93
8.1.6 Honeywell files
93
8.1.7 Microsoft Visual Studio resources
94
8.1.8 Microsoft Visual Studio Offline Help
94
8.1.9 Microsoft Visual Studio build directories
94
8.1.10 CAB configuration procedures
94
8.1.11 Open a new CAB type for edit
95
8.1.12 Define data and algorithm
96
8.1.13 Build the solution
96
8.1.14 Save the solution
96
8.1.15 Save-Renew command
97
8.1.16 Block type locking flags
98
8.1.17 Interactions with the ERDB database lock feature
98
8.1.18 Close the development environment
99
8.2 Define CAB type parameters
99
8.2.1 Custom Data Parameter purpose
99
8.2.2 CDP characteristics
99
8.2.3 Define custom data parameters
100
8.2.4 Validity checks based on CDP attributes
100
7
8.2.5 Access Lock attribute for CDPs 8.2.6 Fixed definition parameter purpose 8.2.7 Define values for fixed definition parameters 8.2.8 Define CAB execution time limit 8.2.9 Define re-reference mode 8.2.10 Define parameter references 8.2.11 Assign parameter references 8.2.12 Specify symbol attributes 8.2.13 Specify form layout 8.2.14 Form entry steps 8.2.15 Fixed definition parameters 8.2.16 FDPs common with native blocks 8.2.17 FDPs specific to CAB 8.2.18 Detailed description of CAB specific FDPs 8.2.19 Save parameter definitions 8.2.20 Limitations on number of CAB parameters 8.2.21 CABs with large numbers of parameters
8.3 Code CAB algorithm
8.3.1 Overview 8.3.2 Define block scope variables 8.3.3 Define local variables 8.3.4 Algorithm definition - Execute() 8.3.5 Avoid the use of recursion 8.3.6 Execution mode of CAB programs 8.3.7 Characteristics of distributed mode execution 8.3.8 CAB programs in sequence control applications 8.3.9 PRef as data alias within CAB program 8.3.10 Configuring parameter addresses on CAB instances 8.3.11 Access level used In PRef writes 8.3.12 Data types for CDPs and parameter references
8.4 CAB algorithm data definition
8.4.1 Data initializations under Execute() 8.4.2 Using the Restart property
101 102 103 103 103 104 104 104 105 105 105 106 106 110 111 111 111
112
112 113 113 113 114 114 116 117 118 118 119 119
123
123 123
8
8.4.3 Restart() behavior after checkpoint and restore
124
8.4.4 CDP initializations associated with block load
124
8.4.5 Data access integrity
125
8.4.6 Local parameter access
125
8.4.7 Remote communication with no group integrity requirements
126
8.4.8 Remote communication with group integrity requirements
127
8.4.9 Read versus write
128
8.4.10 Structure and class usage within CAB
129
8.4.11 Array usage within CAB
129
8.4.12 Floating point usage within CAB
130
8.4.13 Using IsNaN(), IsInfinity(), IsNegativeInfinity(), and IsPositiveInfinity() 131
8.4.14 TIME and TIMEOFDAY usage in CAB
131
8.5 CAB algorithm parameter references
131
8.5.1 Implicit type conversion with CAB parameter references
131
8.5.2 Parameter references used for read
132
8.5.3 Parameter references used for write
134
8.5.4 Parameter reference fail-safe values
135
8.5.5 Limitations on PRef writes to C200, C200E, or C300
135
8.5.6 CAB writes with Continuous Control access level
136
8.6 Dynamic re-referencing of parameter references
137
8.6.1 What is dynamic re-referencing?
137
8.6.2 Configuration summary
137
8.6.3 Enabling dynamic re-referencing
137
8.6.4 How re-referencing works
138
8.6.5 The translate and commit functions
138
8.6.6 Performance considerations
138
8.6.7 Data integrity considerations
139
8.6.8 Re-referencing through OPC Gateway
139
8.6.9 Parameters used for re-referencing
139
8.6.10 Configuring the X_REFMODE parameter
140
8.6.11 Using the X_REFCOMMIT parameter
140
8.6.12 Using the X_REFSTATE parameter
141
9
8.6.13 Viewing re-referencing in Control Builder 8.6.14 Renaming a configured reference
8.7 Re-referencing from the CAB algorithm using the TextRef property
8.7.1 Reading the reference name 8.7.2 Changing the reference name 8.7.3 Checking for re-reference errors 8.7.4 Checking for re-references in process
8.8 Re-referencing from an external agent using the TEXTREF parameter
8.8.1 Entering a new reference manually 8.8.2 Entering a new reference programmatically
8.9 Checkpoint save, restore, and upload
8.9.1 Checkpointing and restoring re-referenced parameters 8.9.2 Uploading re-referenced parameters
8.10 Create a CAB instance
8.10.1 Configure the Value CDPs tab 8.10.2 Configure the Parameter References tab 8.10.3 Parameter Reference tab Monitor view 8.10.4 Source tab 8.10.5 Alarms tab 8.10.6 Save the configuration
8.11 Access files using CAB
8.11.1 Programming CAB to access file data 8.11.2 Coding for file access 8.11.3 Recommended directory for local CAB files 8.11.4 Accessing files on remote systems 8.11.5 Timestamps with Move and Copy commands
8.12 Configure insertion points
8.12.1 Overview 8.12.2 RegCtl insertion points 8.12.3 DataAcq insertion points
141 141
142
142 142 143 143
144
144 145
145
145 146
146
146 147 148 149 149 149
149
150 150 150 150 152
152
152 153 153
10
8.12.4 Configuring an insertion point
153
8.12.5 Do not use graphical connections
154
8.13 Test and debug the CAB
154
8.13.1 Developmental debugging
154
8.13.2 Off-process debugging
155
8.13.3 On-process debugging
155
8.13.4 Troubleshooting information
155
8.14 Modify a CAB
156
8.14.1 Modify/Edit CAB type with Microsoft Visual Studio
156
8.14.2 Converting CAB types created from previous releases of Visual Studio to
Visual Studio 2012 format Converting CAB types created from previous
releases of Visual Studio to Visual Studio 2017 format
156
8.14.3 Converting CAB types using Microsoft Visual Studio 2012 for ACEs still
running Microsoft .Net 2.0 Converting CAB types using Microsoft Visual Studio
2017 for ACEs still running Microsoft .Net 2.0
157
8.14.4 Manage instances after modification of CAB type
158
8.14.5 User actions when saving modified CAB type
159
8.14.6 Situations that require a Save As operation for a modified CAB
160
8.14.7 Behaviors when saving modified CAB types to ERDB
160
8.14.8 Convert instances to modified CAB type
160
8.14.9 Additional notes about the convert function
161
8.15 Manage CABs
161
8.15.1 Verify match of CAB program in ERDB
161
8.15.2 View a CAB type as read only
163
8.15.3 Delete a CAB type from ERDB
163
8.15.4 Rename a CAB
163
8.15.5 Recover a CAB with checkpoint restore
163
8.15.6 Recover CAB source code
164
8.15.7 Export CAB
164
8.15.8 Protecting CAB source
164
8.15.9 Procedure to export CAB without the source
165
8.15.10 Import CAB
166
8.15.11 Discover CAB dependency relationships
167
11
8.15.12 QVCS support for Custom Algorithm Block
8.16 Attaching to the Remote Debugger
Chapter 9 - CAB/C300 special considerations
9.1 Comparison of CAB/ACE and CAB/C300 9.2 Purpose of this section 9.3 Summary of supported functionality
9.3.1 Data and algorithm 9.3.2 ECMA .NET value types 9.3.3 ECMA .NET core classes 9.3.4 Execution 9.3.5 Types and Instances 9.3.6 Custom Data Parameters (CDPs) 9.3.7 Parameter References (PRefs) 9.3.8 Fixed Definition Parameters (FDPs) 9.3.9 CEE APIs 9.3.10 Events 9.3.11 Fault protection 9.3.12 Detection of subset violation 9.3.13 Integration with Control Builder 9.3.14 Simulation 9.3.15 Debugging 9.3.16 Determinism 9.3.17 Program unload 9.3.18 Checkpoint 9.3.19 RAM Retention Restart 9.3.20 Redundancy 9.3.21 On-process migration 9.3.22 List of loaded CAB types 9.3.23 Export and Import
9.4 Summary of excluded functionality
9.4.1 Dynamic re-referencing 9.4.2 Distributed execution
12
167
167
169
169 169 169
170 170 170 171 171 171 171 171 172 172 172 172 172 173 173 174 174 174 174 174 174 175 175
175
175 175
9.4.3 History access 9.4.4 File access 9.4.5 Relational database access 9.4.6 Try-Catch 9.4.7 Process Special CM 9.4.8 Aggregate data members of class CABlock 9.4.9 Structure variables 9.4.10 Shared variables 9.4.11 Static Variables 9.4.12 ECMA .NET types 9.4.13 VB-only syntax
9.5 CAB/C300 system considerations
9.5.1 Planning and design 9.5.2 CAB/C300 Licensing 9.5.3 Installation 9.5.4 Configuration and setup
9.6 CAB/C300 loading considerations
9.6.1 Approaches to determine CAB/C300 loads 9.6.2 Effects of loading large CAB instances 9.6.3 Memory fragmentation in CAB/C300 9.6.4 Example of a CAB load failure due to memory fragmentation 9.6.5 Guidelines to troubleshoot CAB load failures due to memory fragmentation 9.6.6 Freeze-And-Switchover
9.7 CAB execution platform specification and change
9.7.1 Platforms supported by a CAB type 9.7.2 Changing the platform option 9.7.3 Platform option change with forced name change 9.7.4 Platform Specific Functionalities
9.8 VB-only constructs
9.8.1 Example: CStr( ) 9.8.2 Example: New String( )
175 176 176 176 176 176 177 177 177 177 177
178
178 178 178 179
179
179 179 180 180
181 181
182
182 182 182 183
183
183 184
13
9.8.3 VB-only constructs usage guidelines
9.9 Aggregates and the semantics of 'New'
9.9.1 Example: String variable as data member of CABlock 9.9.2 Example: String variable as Local 9.9.3 Example: String Variable As CDP 9.9.4 Guidelines for using aggregate data types within CAB/C300
9.10 Extreme configuration
9.10.1 Size of Stack 9.10.2 Size of Short Term Heap 9.10.3 Size of Looping 9.10.4 Redundancy Traffic 9.10.5 Redundancy Traffic Instrumentation 9.10.6 Redundancy count exceeded alarm
9.11 Controller Restarts
9.11.1 CAB/C300 data across restarts 9.11.2 APIs for restart handling
9.12 On-process migration
9.12.1 Migration constraints 9.12.2 OPM guidelines
9.13 PRef string size
9.13.1 Configuring the Size attribute
9.14 Parameters of time data type
9.14.1 Establishing time zone and daylight saving time 9.14.2 Precision of conversion
9.15 Debugging CAB/C300
9.15.1 Black box debugging on C300 9.15.2 SIM-C300 debugging 9.15.3 SIM-ACE debugging
9.16 Versioning of CAB/C300 enablers
9.16.1 Comparing CAB/ACE versioning with CAB/C300 versioning
9.17 CM Process Special
184
185
185 186 187 187
188
188 190 190 191 192 193
194
195 196
196
196 196
197
197
198
198 199
199
199 200 200
200
200
201
14
9.17.1 Overview 9.17.2 CAB/C300 behavior
9.18 Metadata 9.19 Error Examples when writing CAB/C300 programs
9.19.1 PDE Errors And Build Errors 9.19.2 Dynamic PRef 9.19.3 Distributed Execution 9.19.4 File access 9.19.5 History access 9.19.6 Unsupported value types 9.19.7 Unsupported core class 9.19.8 Try-Catch clause 9.19.9 Keyword 'Structure' 9.19.10 Keyword 'Shared' 9.19.11 Keyword 'Static' 9.19.12 Option Strict 9.19.13 Late Stage Build Processing 9.19.14 CAB security considerations
9.20 Functional differences supplement
9.20.1 Build stages 9.20.2 Character count of CAB type name
9.21 Exceptions And Errors
9.21.1 Run-time Exceptions 9.21.2 Resolution Of Programming Errors 9.21.3 Execution timing 9.21.4 Mathematical Functions 9.21.5 Array dimensions 9.21.6 Parameter differences
9.22 CAB/C300 performance and capacity 9.23 CAB/C300 migration and interoperability
9.23.1 Characteristics of CAB/C300 OPM support
201 202
202 203
203 203 203 204 204 205 206 206 206 207 207 208 208 209
209
209 210
210
210 211 211 212 213 213
213 214
214
15
9.23.2 Characteristics of CAB/C300 interoperability support
9.24 CAB Types Info Form 9.25 Frequently Asked Questions on CAB/C300
Chapter 10 - CDB configuration
10.1 Create a new CDB type
10.1.1 CDB development environment 10.1.2 Summary of configuration steps 10.1.3 Open a new CDB type for edit 10.1.4 Types of saves for CDB 10.1.5 Save As Renew command 10.1.6 Save CDB to ERDB
10.2 Define CDB type parameters
10.2.1 Custom Data Parameter purpose 10.2.2 CDP characteristics 10.2.3 Define CDB custom data parameters 10.2.4 Validity checks based on CDP attributes 10.2.5 Access lock attribute for CDPs 10.2.6 Fixed definition parameter purpose 10.2.7 Fixed definition parameters in CDBs 10.2.8 Detailed description of CDB FDPs 10.2.9 Specify symbol attributes 10.2.10 Specify form layout 10.2.11 Form entry steps 10.2.12 Save parameter definitions 10.2.13 Limitations on number of CDB parameters
10.3 Create a CDB instance
10.3.1 Configure Value CDPs tab
10.4 Test the CDB 10.5 Modify a CDB
10.5.1 Manage instances after modification of CDB type 10.5.2 User actions when saving modified CDB type
16
214
215 216
219
219
219 219 219 220 221 221
221
221 222 222 223 223 225 225 225 225 226 226 227 227
227
228
229 229
229 230
10.5.3 Situations that require a Save As operation for a modified CDB 10.5.4 Behaviors when saving modified CDB types to ERDB 10.5.5 Convert instances to modified CDB type 10.5.6 Additional notes about the convert function 10.5.7 Verify match of CDB version in ERDB 10.5.8 View a CDB type as read only 10.5.9 Delete a CDB type from ERDB 10.5.10 Rename a CDB 10.5.11 Recover a CDB with checkpoint restore 10.5.12 Export CDB 10.5.13 Import CDB 10.5.14 Discover CDB dependency relationships 10.5.15 QVCS support for Custom Data Block
Chapter 11 - CAB and CDB Example Scenarios
11.1 Summary of example scenarios
11.1.2 Example scenarios included
11.2 CAB insertion algorithm
11.2.1 Vapor-to-liquid ratio control 11.2.2 Creating empty block type VLR_CALC 11.2.3 Setting the access level for VLR_CALC 11.2.4 Defining value CDPs for VLR_CALC 11.2.5 Define parameter references for VLR_CALC 11.2.6 Define the algorithm for VLR_CALC 11.2.7 Save VLR_CALC to ERDB 11.2.8 Block instances in the VLR_CALC application 11.2.9 Configure VLR_CALC1 11.2.10 Configure VLR_CTL1 11.2.11 Control module chart for VLRATIO
11.3 Formulation of VLR_CALC without insertion point
11.3.1 CDP definitions for alternate formulation of VLR_CALC 11.3.2 Control module chart for alternate formulation of VLRATIO
231 231 231 232 232 233 234 234 234 234 235 235 236
237
237
237
238
238 239 239 239 240 240 242 242 243 245 245
245
246 246
17
11.4 CDPs as Engineering Unit labels
11.4.1 Example
11.5 A CDB to hold sensor data
11.5.1 Temperature at position within PFR 11.5.2 Creating block type POSTEMPCDB 11.5.3 Block instances in temperature at position application 11.5.4 Configure the CM POSTEMP1 11.5.5 Configure POSTEMP1.DATA1
11.6 A CDB to consolidate array data
11.6.1 Block type ZONETEMPCDB
11.7 A CAB to calculate statistics over arrays
11.7.1 Block type ZONESTATSCAB 11.7.2 Value CDPs for ZONESTATSCAB 11.7.3 Algorithm for ZONESTATSCAB 11.7.4 Bulk array connection on ZONESTATSCAB instance
11.8 A CAB to calculate statistics over a set of PRefs
11.8.1 Block type ZONESTATSCABP 11.8.2 Value CDPs for ZONESTATSCABP 11.8.3 Algorithm for ZONESTATSCABP 11.8.4 Configuring the parameter references on the ZONESTATSCABP instance
11.9 Using dynamic re-referencing to move among zones online
11.9.1 Value CDPs for ZONESTATSCABR 11.9.2 Parameter Reference definitions for ZONESTATSCABR 11.9.3 Dynamic re-referencing settings for ZONESTATSCABR 11.9.4 Algorithm for ZONESTATSCABR 11.9.5 Configuring an instance of ZONESTATSCABR 11.9.6 ZONESTATSCABR in operation, controlled by an operator
11.10 Array and scalar variables in CAB
11.10.1 Example variables 11.10.2 PDE definitions
246
247
247
247 248 249 249 250
251
251
252
252 252 253 255
255
256 256 257
259
259
259 259 260 260 262 263
264
264 265
18
11.10.3 Minimum and maximum values 11.10.4 Instance configuration 11.10.5 Program 11.10.6 Two-dimensional array example
11.11 Initializing in response to system events
11.11.1 Fast history block 11.11.2 PDE definitions 11.11.3 Program
11.12 Example using data type TIME
11.12.1 Shift calculations 11.12.2 Value CDP definition for SHIFTCALC 11.12.3 Algorithm for SHIFTCALC
11.13 Example using data type TIMEOFDAY
11.13.1 Slow monitoring calculations 11.13.2 Value CDP definitions for MONCALC 11.13.3 Algorithm for MONCALC
11.14 Example using data type DELTATIME
11.14.1 Time-out monitor 11.14.2 Value CDP definitions for TIMEOUTMON 11.14.3 Algorithm for TIMEOUTMON
11.15 Use of data access status in CAB
11.15.1 Device monitor with Stop/Run command 11.15.2 Value CDP for DEVMON 11.15.3 Parameter references for DEVMON 11.15.4 Algorithm for DEVMON
11.16 Use of parameter reference variables in CAB
11.16.1 Setting control state for a group of CMs 11.16.2 Value CDPs for SETMODE 11.16.3 Parameter references for SETMODE 11.16.4 Algorithm for SETMODE
11.17 History time examples
265 266 266 267
268
268 268 268
269
269 270 270
271
271 271 272
272
272 273 273
274
274 275 275 275
277
277 277 278 279
283
19
11.17.1 What is UTC time? 11.17.2 Data types that store time 11.17.3 Some CAB rules related to time 11.17.4 Time usage examples
11.18 Reading history values using wrapped methods
11.18.1 Value CDPs for READHIST 11.18.2 Algorithm for READHIST
11.19 Reading history values using only the OPC .Net API
11.19.1 Algorithm for READHIST2
11.20 Reading average history values using wrapped methods
11.20.1 Value CDPs for READAVGHIST 11.20.2 Algorithm for READAVGHIST
11.21 Reading average history values using the OPC .Net API
11.21.1 Algorithm for READAVGHIST2
11.22 Reading history values from redundant servers
11.22.1 Preparation 11.22.2 Code changes
11.23 Reading history for an extended period
11.23.1 Algorithm for READ_1DAY
11.24 Use of file IO in CAB
11.24.1 Description of CAB Type FILEIO 11.24.2 Value CDPs for FILEIO 11.24.3 Symbol Attributes for FILEIO 11.24.4 Algorithm for FILEIO
11.25 Using a CAB to change the MODE of a TPN point 11.26 Method 1: Using an integer to change a MODE
11.26.1 Integer method (INTMODE) PDE definitions 11.26.2 Value CDP definitions for INTMODE 11.26.3 Parameter reference definition for INTMODE 11.26.4 Algorithm for INTMODE
283 283 284 284
285
286 286
288
288
290
290 291
293
293
295
295 296
296
297
299
299 299 300 301
303 304
304 304 304 304
20
11.27 Method 2: Using a string to change a MODE
11.27.1 String method (STRMODE) PDE definitions 11.27.2 Value CDP definitions for STRMODE 11.27.3 Parameter reference definition for STRMODE 11.27.4 Algorithm for STRMODE
Chapter 12 - CAB and CDB operations
12.1 Startup and shutdown
12.1.1 Custom Algorithm Blocks 12.1.2 Custom Data Blocks
12.2 Process operations
12.2.1 Monitor CAB and CDB 12.2.2 View CAB alarms
12.3 View CAB and CDB from Station 12.4 Properties forms specific to CAB and CDB
12.4.1 Where to find information 12.4.2 Main tab of a CAB property form 12.4.3 Main tab of a CDB property form 12.4.4 Value CDPs tab for CAB and CDB 12.4.5 Parameter References tab 12.4.6 Source tab 12.4.7 Alarms tab
Chapter 13 - CAB and CDB system administration
13.1 CAB development environment administration
13.1.1 Recovering from a Control Builder crash
13.2 User management
13.2.1 User management functions 13.2.2 Setting user permissions 13.2.3 Establishing a User account for SIM-ACE
13.3 Remote debugging using Visual Studio 13.4 Administrator Setup on the SIM-ACE
305
305 305 305 306
307
307
307 307
307
307 308
308 308
308 309 309 309 309 309 309
311
311
311
311
311 311 311
312 312
21
13.4.1 Setting up the Firewall and Remote Debugging Monitor
312
13.4.2 Configuring the CAB Remote Debug Service
313
13.4.3 Configuring the Local Security Policy
313
13.5 Administrator Setup on the Client (Station, Flex, and so
on)
314
13.6 Resource management
314
13.6.1 Use performance monitoring FDPs 13.6.2 Use Task Manager 13.6.3 Use Performance Monitor
13.7 Custom Install Paths
315 315 316
321
13.8 Backup and restore
321
13.8.1 ACE shutdown procedure for reclaiming CAB memory
321
Chapter 14 - CAB and CDB troubleshooting and maintenance
322
14.1 CAB troubleshooting approach
322
14.1.1 Troubleshooting approaches and tools
322
14.2 CAB instance states
322
14.2.1 State diagram 14.2.2 State descriptions 14.2.3 Status of I/O performed by a block that terminates 14.2.4 Transition descriptions
14.3 CAB alarms
322 323 324 324
325
14.3.1 CAB state Terminated 14.3.2 CAB state Exception 14.3.3 Read error 14.3.4 Write error 14.3.5 FDPs that capture exception information
14.4 Debug with SIM-ACE
325 326 326 326 326
327
14.4.1 The Microsoft Visual Studio debugger
327
14.4.2 Scope
327
14.4.3 Basic characteristics of SIM-ACE
328
14.4.4 Attaching to the Remote Debugger
329
22
14.4.5 Tips for using Microsoft Visual Studio with SIM-ACE
14.5 CAB fault handling
14.5.1 Function limiter and supported namespaces 14.5.2 Supported namespaces and classes 14.5.3 Summary of fault handling 14.5.4 Parameter access faults 14.5.5 Divide-by-zero handling 14.5.6 Unbounded recursion 14.5.7 Exception handling 14.5.8 Overlong execution 14.5.9 Loops In 'Catch' Or 'Finally' clauses 14.5.10 Site responsibilities in CAB fault handling 14.5.11 CAB error reporting 14.5.12 CAB error messages and codes 14.5.13 Error Messages associated with CAB/C300
14.6 CDB troubleshooting approach
14.6.1 CDB exceeds maximum checkpoint size 14.6.2 Array parameter exceeds maximum size 14.6.3 Storage requirements for data types 14.6.4 Unloaded state is an error
14.7 Contacting TAC
14.7.1 Information required for build-time problems 14.7.2 Information required for CAB/ACE run-time problems 14.7.3 Information required for CAB/C300 run-time problems
Chapter 15 - CAB API reference
15.1 The overall CAB map
15.1.1 Object Browser
15.2 API quick reference
15.2.1 Summary of APIs
15.3 Class CAB
15.3.1 Subroutine Execute() of class CAB
330
330
331 331 335 337 338 338 338 338 339 339 339 345 353
356
356 356 356 357
357
357 357 358
359
359
359
359
359
360
361
23
15.4 Enumerations
15.4.1 Enumeration RestartEnum 15.4.2 Enumeration CABAccStatusEnum 15.4.3 Enumeration CABCommandEnum 15.4.4 Enumeration CABStateEnum 15.4.5 Enumeration CABReRefCommitEnum 15.4.6 Enumeration CABReRefStateEnum
15.5 CDP classes
15.5.1 Summary of CDP classes 15.5.2 CDP class usage
15.6 Parameter reference classes
15.6.1 Summary of parameter reference classes 15.6.2 Parameter reference class usage 15.6.3 Read(), ReadStatus, and Value 15.6.4 Write() 15.6.5 WriteStatus 15.6.6 Parameter reference list class 15.6.7 PRef writes to C200, C200E or C300
15.7 CABMath class
15.7.1 Methods in the CABMath class 15.7.2 Min Methods 15.7.3 Max Methods 15.7.4 Sum Methods 15.7.5 Avg Methods 15.7.6 Examples of CABMath functions usage
15.8 BlockBase
15.8.1 FDP classes 15.8.2 Base class 15.8.3 PROGSTSDESC 15.8.4 CABCOMMAND 15.8.5 CABSTATE 15.8.6 X_REFCOMMIT
24
361
361 362 363 363 364 364
364
364 365
366
367 367 368 369 370 371 371
373
373 373 374 374 375 375
376
376 376 377 378 378 379
15.8.7 X_REFSTATE 15.8.8 PERIOD 15.8.9 PROCSPECEXEC 15.8.10 Subroutine Send() 15.8.11 Subroutine Abort() 15.8.12 Subroutine Wait() 15.8.13 Property Restart() 15.8.14 Property RRRestart
15.9 History APIs
15.9.1 Programming CAB to access history data 15.9.2 Summary of wrapped functionality properties and methods 15.9.3 ExperionHistoryServerName property 15.9.4 PHDHistoryServerName property 15.9.5 ConnectToHDAServer method 15.9.6 GetHistory method 15.9.7 GetAvgHistory method 15.9.8 OPC functionality 15.9.9 Example scenarios for reading history
15.10 VB.NET APIs
15.10.1 Private and public access types In CAB programs
Chapter 16 - Glossary of terms and acronyms
16.1 Special terms and acronyms
16.1.1 .NET 16.1.2 .NET CLR 16.1.3 ACE 16.1.4 Aggregate types 16.1.5 AICHANNEL 16.1.6 AND 16.1.7 API 16.1.8 Basic block 16.1.9 Black box debugging 16.1.10 Block instance
379 379 380 380 381 381 382 382
383
384 384 385 386 386 387 389 392 392
392
393
394
394
394 394 394 394 394 394 395 395 395 395
25
16.1.11 Block template
395
16.1.12 Block type
395
16.1.13 Build a program
396
16.1.14 C200, C200E, C300
396
16.1.15 CAB
396
16.1.16 CAB algorithm
396
16.1.17 CAB/ACE
396
16.1.18 CAB/C300
396
16.1.19 CAB program
396
16.1.20 CB
397
16.1.21 CDB
397
16.1.22 CDP
397
16.1.23 CDS
397
16.1.24 CE
397
16.1.25 CEE
397
16.1.26 Change Parent
397
16.1.27 CM
397
16.1.28 Configuration of block instances
397
16.1.29 Component block
398
16.1.30 Connections
398
16.1.31 Container Block
398
16.1.32 Control Builder
398
16.1.33 Control Module
398
16.1.34 Convert
398
16.1.35 Custom Data Block
398
16.1.36 Custom Definition Parameter
398
16.1.37 Custom Data Segment
399
16.1.38 DATAACQ
399
16.1.39 Data owner principle
399
16.1.40 DLL
399
16.1.41 ECMA
399
16.1.42 Edit Lock
399
16.1.43 EE
399
26
16.1.44 ERDB 16.1.45 EU 16.1.46 EULA 16.1.47 European Computer Manufacturer's Association 16.1.48 Exception handler 16.1.49 FDP 16.1.50 Fixed Definition Parameter 16.1.51 GPL 16.1.52 Graphical connections 16.1.53 GUID 16.1.54 HON 16.1.55 ICG 16.1.56 IDE 16.1.57 IEEE 754 16.1.58 Incomplete Lock 16.1.59 INF 16.1.60 I/O 16.1.61 Long Term Heap 16.1.62 LTH 16.1.63 Monitor Side Instance 16.1.64 MSVS 16.1.65 NaN 16.1.66 Native blocks 16.1.67 OLE 16.1.68 OPC 16.1.69 OPC Gateway 16.1.70 Operator Training Simulation 16.1.71 OPM 16.1.72 OS 16.1.73 OTS 16.1.74 Parameter Definition Editor 16.1.75 Parameter reference 16.1.76 PDE
399 400 400 400 400 400 400 400 400 401 401 401 401 401 401 401 401 401 402 402 402 402 402 402 402 402 403 403 403 403 403 403 403
27
16.1.77 PKS 16.1.78 PRef 16.1.79 Project side instance 16.1.80 Redundancy Transfer Count 16.1.81 RTC 16.1.82 SCM 16.1.83 SCO 16.1.84 Sequence Control Module 16.1.85 Short Term Heap 16.1.86 SIM-ACE 16.1.87 SIM-C200E 16.1.88 SIM-C300 16.1.89 Source Level Debug 16.1.90 SR 16.1.91 STH 16.1.92 Strategy Check Out 16.1.93 System Repository 16.1.94 System template 16.1.95 Template 16.1.96 UI 16.1.97 User template 16.1.98 VB-Only
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.1 ABS 17.2 ALLOW_BAD 17.3 ATAN 17.4 AVG 17.5 BACKGRND 17.6 BADVAL 17.7 BKG_CHANGE_PRIORITY 17.8 BKG_DELAY
403 403 404 404 404 404 404 404 404 404 405 405 405 405 405 405 405 405 405 406 406 406
407
407 407 408 408 408 409 409 410
28
17.9 BKG_SWITCHOVER_RESTART 17.10 CDS_READ 17.11 COMM_ERROR 17.12 COS 17.13 CTL_ALG
17.13.1 Insertion point configuration
17.14 DATE_TIME 17.15 DAY_TIME 17.16 DELETE_FILE 17.17 ENGINEER 17.18 ENTITY_BLDR 17.19 ENUM_VALUE_STORE 17.20 EQUAL_NULL_POINT_ID 17.21 EQUAL_POINT_ID 17.22 EXISTS 17.23 EXP 17.24 FINITE 17.25 GENERAL 17.26 GET_CL_SLOT 17.27 INT 17.28 LEN 17.29 LN 17.30 LOG10 17.31 LOGICAL 17.32 MAX 17.33 MC 17.34 MIN
410 411 411 411 412
413
413 414 414 414 415 415 416 417 417 418 418 419 419 420 420 421 421 421 422 422 422
29
17.35 MODIFY_STRING
423
17.36 MOVE_PARAMETER
424
17.37 NOW
424
17.38 NUMBER
425
17.39 NUMBER_TO_STRING
425
17.40 OFF
426
17.41 ON
426
17.42 OPERATOR
426
17.43 ORD
427
17.44 PM
427
17.45 PRE_CTAG
427
17.46 PRE_CTPR
428
17.47 PRE_GI
428
17.48 PRE_PVA
428
17.49 PRE_PVAG
429
17.50 PRE_PVPR
429
17.51 PRE_SP
429
17.52 PROGRAM
429
17.53 PST_CTAG
430
17.54 PST_CTPR
430
17.55 PST_GO
430
17.56 PST_PVAG
431
17.57 PST_PVFL
431
17.58 PST_PVPR
431
17.59 PV_ALG
432
17.60 ROUND
432
17.61 SET_BAD
432
30
17.62 SET_NULL_POINT_ID
433
17.63 SIN
433
17.64 SQRT
433
17.65 STRING
434
17.66 SUM
434
17.67 SUPERVISOR
434
17.68 TAN
435
17.69 TIME
435
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved
words
436
18.1 ABORT
436
18.2 ACCESS
436
18.3 ALARM
437
18.4 AND
437
18.5 ANY_ENUMERATION
437
18.6 ARRAY
438
18.7 AT
438
18.8 BLD_VISIBLE
439
18.9 BLOCK
439
18.10 CALL
440
18.11 CLASS
440
18.12 CUSTOM
440
18.13 DATA_POINT_ID
441
18.14 DAYS
441
18.15 DEFINE
442
18.16 ELSE
442
18.17 EMERGENCY
442
31
18.18 END
442
18.19 ENUMERATION
443
18.20 ERROR
444
18.21 EU
444
18.22 EXIT
444
18.23 EXTERNAL
445
18.24 FAIL
446
18.25 FOR
447
18.26 FROM
447
18.27 FUNCTION
447
18.28 GENERIC
448
18.29 GOTO
448
18.30 HANDLER
449
18.31 HELP
449
18.32 HOLD
449
18.33 HOURS
450
18.34 IF
450
18.35 IN
450
18.36 INITIATE
451
18.37 LOCAL
451
18.38 LOOP
452
18.39 MINS
453
18.40 MOD
453
18.41 NAME
454
18.42 NOT
454
18.43 OR
454
18.44 OTHERS
455
32
18.45 OUT 18.46 PACKAGE 18.47 PARALLEL 18.48 PARAM_LIST 18.49 PAUSE 18.50 PHASE 18.51 POINT 18.52 RANGE 18.53 READ 18.54 REFERENCE 18.55 REFERENCE_N 18.56 RELAX 18.57 REPEAT 18.58 RESTART 18.59 RESUME 18.60 SECS 18.61 SEND 18.62 SEQUENCE 18.63 SET 18.64 SHUTDOWN 18.65 STEP 18.66 SUBROUTINE 18.67 THEN 18.68 UNIT 18.69 VALUE 18.70 WAIT 18.71 WHEN
455 455 456 456 457 457 457 458 458 459 459 459 460 460 460 461 461 462 462 463 463 463 464 464 465 465 465
33
18.72 WRITE
466
18.73 XOR
466
18.74 Background execution and distributed processing 466
Chapter 19 - Appendix C: Configuring CAB to support accessing files on
remote systems
467
19.1 Configuring the ACE process to execute under the
'mngr' account
467
19.2 Sharing a folder that you want to access files remotely
from CAB
467
Chapter 20 - Appendix D:ECMA .NET Data Types
469
20.1 Classes
469
20.2 Methods
470
Chapter 21 - Notices
481
34
CHAPTER
1
ABOUT THIS DOCUMENT
1.1 1.2
This document describes how to plan, develop, debug, deploy, and troubleshoot Custom Algorithm Blocks (CABs) and Custom Data Blocks (CDBs).
Revision History
Revision A
Date August 2020
Description Initial release of the document
References
The following list identifies all documents that may be sources of reference for material discussed in this publication.
Document Title Parameter Definition Editor Reference Application Control Environment User Guide Simulation ACE User Guide Control Building Guide Control Builder Components Reference Control Builder Components Theory Control Builder Parameter Reference
- 35 -
CHAPTER
2
INTRODUCTION
2.1 2.2
2.3 2.4 2.5
Overview
This document provides information on how you define, configure, deploy, and troubleshoot Custom Algorithm Block (CAB) and Custom Data Block (CDB) control blocks.
Who should use this guide
If your need is simply to familiarize yourself with the capabilities of CAB and CDB, this guide contains introductory and tutorial information that will be helpful. The introductory material is included in the section that you are reading. If you are an engineer developing control strategies that use, or might use, CAB and/or CDB, this guide also contains detailed reference material that you will require. Similarly, if your activities include deploying and monitoring CABs and CDBs, this guide contains detailed information about their behavior in the run-time environment.
Terms and acronyms
Special terms and acronyms contains special terms and acronyms that are commonly used in this guide. This list is an excellent introduction to the concepts and "language" of CAB and CDB. If you are new to CAB and CDB, we recommend that you read through this list prior to delving into the details of CAB and CDB.
Prerequisite knowledge
l You should be familiar with the basic principles of control systems. l You should have a good working knowledge of Experion PKSControl Builder. l If you will be developing control algorithms for Custom Algorithm Blocks, you will need to be
adept at using the Microsoft Visual Basic .NET programming language
What's new in R516
A new variant of C300 controller hardware is introduced in R516, called the C300v5. CAB types and instances deployed to run on a C300v5 behave the same as they do on prior variants of the C300 platform. Small differences, such as CPU consumption of a CAB typical, are documented.
- 36 -
2.6 2.7 2.8
2.9
2.9.1 2.9.2
Chapter 2 - Introduction
What's new in R511
l CAB is modified to integrate with Microsoft Visual Studio 2017 and thus move to the next version of the Microsoft .NET Framework. You can now build CABs based on Microsoft .NET Framework 4.6.2.
l Changes to the remote debug scenarios. See Remote debugging using Visual Studio l Backward compatibility of CAB/ACE types is supported. See Interoperability of ACE controllers
with CAB types running on different .NET versions
What's new in R430
CAB is modified to integrate with Microsoft Visual Studio 2012.
NOTE There are no major change done in R431 ,R500, R501 and R510.
What's new in R410
l CAB is modified to integrate with Microsoft Visual Studio 2010 and thus move to the next version of the Microsoft .NET Framework. You can now build CABs based on Microsoft .NET Framework 4.0.
l Support for Custom Install Paths - CAB software installation supports the ability to install the software in a different location than the default C:\Program Files (x86). See Custom Install Paths
l Changes to the remote debug scenarios. See Remote debugging using Visual Studio l Backward compatibility of CAB/ACE types is supported. See Interoperability of ACE controllers
with CAB types running on different .NET versions
What is a Custom Algorithm Block?
A CAB is similar in purpose and structure to the "native" function blocks that are distributed with Experion PKSControl Builder (CB). Examples of native blocks are REGCTL blocks such as PID and RAMPSOAK. These blocks have a predefined algorithm and a predefined data structure. By contrast, Custom Algorithm Blocks have user-defined algorithms and data structures.
CAB creation
CABs are created within CB. You must purchase a CAB Developer license from Honeywell in order to activate the CAB development features. These features include Microsoft Visual Studio 2017 which is combined with the Parameter Definition Editor (PDE) to provide the project development environment that is used to develop CAB types and that allows implementation of custom parameters and algorithms. Creating a CAB type requires fluency with the VB.NET programming language.
CAB functionality
With CAB Developer, you can define the block type itself, including the custom data parameters,
- 37 -
Chapter 2 - Introduction
parameter references, and the control algorithm. With ACE R210 and later, and with C300 R400 and later, you can create instances of your custom block types. You can also create block templates, which are an optional intermediate construct in between the type and the instance. Templates might be useful to you in certain situations. Templates are covered in Role of block types, instances, and templates. For more information on CAB functionality, see CAB functional overview. A control strategy can include combinations of native blocks and custom blocks.
2.10
What is a Custom Data Block?
CDB types are similar to CAB types in that they allow the creation of a custom type that can be instantiated multiple times. They differ in that they support the definition of custom data parameters, but they do not support parameter references or a control algorithm.
2.10.1
Creating a CDB
CDBs are created in CB. You do not need a license--CDB is a standard feature. You do not require skills with VB.NET, as CDB does not support an algorithm. For more information on CDB functionality, see CDB functional overview.
2.11
Getting started tutorial
Familiarity with Control Builder is assumed. The tutorial illustrates the following steps: l Creation of a CAB type, including a simple algorithm and a custom data parameter. l Instantiation of the CAB type in a Control Module (CM). l Assign, load, and activate the CM in the Control Execution Environment (CEE). l Monitor the operation of the CAB instance. l Creation of a CDB type including custom data parameters. l Instantiation of the CDB type in a CM. l Assign, load, and activate the CM in the CEE.
Related topics:
2.11.1
System requirements
Depending on your familiarity with the subject and your needs, you can skip the tutorial, read it, or follow the steps and build the examples on your system. If you choose to build the example, you should have an Experion system that includes a Server, a Station with Control Builder (with CAB Developer support), and an Application Control Environment (ACE) node. The ACE node must have a CEE configured. I/O is not required, as the examples do not perform I/O. The tutorial assumes that ACE/CEE has already been activated. Although ACE is specified in the tutorial, the . The CAB instance from this example can also be loaded and executed on a SIM-C300 or a C300 process controller. However, this is possible only if X_PLATOPT is set to "ACEANDC300" on the Fixed tab of the Parameter Definition Editor.
- 38 -
Chapter 2 - Introduction
2.11.2
Description of the tutorial examples
The tutorial consists of a CAB example and a CDB example. l In the CAB example, you will perform the following tasks:
o Create a custom library called CABLIB and create a CAB type called CABDEMO in the library.
o Configure a custom parameter called FLOW and write a simple, one-line VB.NET program that adds a constant to the value of FLOW.
o Build and save the project. o Create a new Control Module (CM) and create instances of your CAB and a NUMERIC
function block in the CM. o Wire the output of the CAB to the input of the NUMERIC function block, and wire the
output of the NUMERIC to the input of the CAB, forming a simple loop. o Load the CM to the CEE and activate it. o Monitor execution of the strategy and observe the value of FLOW increasing.
l In the CDB example, you will perform the following tasks: o Create a custom library called CDBLIB and create a CDB type called CDBDEMO in the library. o Configure Custom Data Parameters of various types. o Save the type to the Engineering Repository Database (ERDB). o Create a new CM and create an instance of your CDB in the CM. o Load the CM to the CEE and activate it.
The tutorial is separated into four parts: l Creating a CAB type l Instantiating the CAB type in a control strategy l Creating a CDB type l Instantiating the CDB type
2.11.3
Creating a CAB type
In this section of the CAB tutorial, you will create a custom library, and within the library you will create a custom CAB type, including:
l A custom data parameter--custom data parameters are called value CDPs within the CB development environment because the value of the parameter is stored within the block as opposed to being a reference to a variable located outside the block.
l A custom algorithm--a very simple one in this case, for demonstration only.
The tutorial example does not include the configuration of parameter references, although this functionality is available in CAB.
- 39 -
Chapter 2 - Introduction
To create a CAB type
1. Open Control Builder with the two tree views open--the upper pane displaying the Project view and the lower pane displaying the Library view.
2. To create a new CAB type, click File > New > Type > Custom Algorithm Block.
3. When the BlockType dialog appears, do the following steps: l Type CABLIB as the new Custom Library Name. l Type CABDEMO as the new CAB Block Type Name. l Click OK.
4. The CAB Development Environment opens. The Custom Algorithm Block (CAB) splash screen appears briefly.
style="width:400px;height:260px;"/> 5. The Custom Library and CAB appear in the CB Library window.
style="width:400px;height:260px;"/> 6. The Parameter Definition Editor (PDE) opens with the Value CDPs tab open as shown in the
following figure. This is where custom data parameters (value CDPs) are defined. Type the following data as follows: Parameter name: FLOW Parameter description: Demo custom parameter Data type: FLOAT64 Access lock: OPERATOR Configuration load: LOAD Default value: 2.2
7. Save the PDE data by clicking the indicated button.
8. Click the CABlock.vb* tab to expose the VB source code window. Note that several lines of code already exist. Add your line of code after the comment line that begins "TODO:..." as shown. Note that Microsoft IntelliSense provides dropdown lists to assist you as you code. Your line of code is: Me.FLOW.Value += 3.1
9. Click the Build Solution button to compile and link your code.
- 40 -
Chapter 2 - Introduction 10. Verify that there were no errors. 11. Click the indicated button to save the CAB type to the ERDB. 12. Click the X in the upper right corner to close the Microsoft Development Environment window.
A confirmation message appears briefly.
2.11.4
Instantiating the CAB type in a control strategy
In this section of the CAB tutorial, you will create a new Control Module. You will drag-and-drop your CAB type and a NUMERIC function block into the Control Module chart creating instances of the CAB and NUMERIC types. You will wire the CAB and NUMERIC forming a control strategy. You will load and activate the CM and observe the results.
To instantiate the CAB type
1. In CB, select the Project view and create a new Control Module by clicking File > New > Control Module.
Note: The system will automatically name your Control Module. In this example, the name is CM_35, but will probably be different in your system. You can rename the module by rightclicking on it in the Project tree. 2. From the Library tree view, drag and drop your CAB type (CABDEMO) and a NUMERIC (under UTILITY) function block into the Project chart. This process creates an instance of your CAB type and an instance of the NUMERIC type. 3. Double-click your CAB instance to display its properties form. Then, click the Value CDPs tab to display your custom parameter. If you had other custom parameters, they would be displayed in a list. 4. Select the Block Pins tab. Then, in the Parameters list, select FLOW(your custom parameter). 5. Using the CB pin addition functionality as shown below, add an input pin on the left side of the CAB and an output pin on the bottom of the CAB.
- 41 -
Chapter 2 - Introduction
6. The completed block is shown below. Click OK to save the configuration and close the properties form.
7. Double-click the NUMERIC block to display its properties form. Then, change the Actual Value from NaN to 2.2. Click OK.
8. Click the Block Pins tab. In the same manner as in steps 4-6 above, select the PV parameter and add an input pin to the left side of the block. When you have finished and closed the NUMERIC property form, the CM Project chart appears as shown below.
9. Click the Wire tool button. 10. Click once on the NUMERIC PV input pin and then click again on the CAB FLOW output pin,
wiring them together as shown below. 11. In the same manner, wire the PV output pin of the NUMERIC to the FLOW input pin of the
CAB. The result appears as shown below. 12. Click the X in the upper right corner of the Project chart to close the window. Then, click Yes
when prompted to save changes to the Project. 13. Assign the Control Module to the CEE. Then, select your Control Module from under the
Unassigned node in the Project tree view.
14. Click the Assign button on the CB toolbar.
15. When the Assignment screen appears, be sure that your new CM is selected in the Available Modules list and that the ACE CEE that you want to load it to is selected in the Assign To list, and then click Assign.
16. Click Close. Your CM now appears under the CEE node in the Project tree. 17. Click the Load button to load the CM. 18. When the Load dialog appears, click OK. 19. Click the Monitoring tab. 20. Double-click the CM to open the chart window.
2.11.5
21. Click Controller > Activate > Selected Item(s). Alternatively, right-click the CM and then click Activate > Selected Item(s).
22. Click Yes to confirm. Note that the value of your FLOW parameter is increasing.
Creating a CDB type
In this section of the CDB tutorial, you will create a custom library, and within the library you will create a custom CDB type, including five custom data parameters. This CDB is used in the A CDB to hold sensor data example later in this document.
- 42 -
Chapter 2 - Introduction
To create a CDB type
1. Open Control Builder with the two tree views open\the upper pane displaying the Project view and the lower pane displaying the Library view.
2. Create a new CDB type by clicking File > New > Type > Custom Data Block. 3. Type CDBLIB as the new Custom Library Name and type CDBDEMO as the new CDB Block
Type name. Then, click OK. 4. The Custom Library and CDB type appear in the CB Library window. 5. Type the values as shown below. (These values are also listed in Creating block type
POSTEMPCDB, which may be easier to read.)
2.11.6
6. Click the X in the right upper corner to close the PDE. 7. Click Yes when prompted to save data.
Instantiating the CDB type
In this section of the CDB tutorial, you will create a new Control Module and will drag and drop your CDB type from the Library tree window into the Control Module chart. You will load and activate the Control Module. Note that this is an incomplete example. It is intended only to illustrate the instantiation of a CDB, which is the same as for a CAB or native block. The CDB will not serve a useful purpose until it is incorporated into a strategy with other blocks. To see how this CDB might be used in a control application, see the A CDB to hold sensor data example later in this document.
To instantiate the CDB type
1. In Control Builder, select the project view and create a new Control Module by clicking File > New > Control Module. Note: The system will automatically name your Control Module. In this example, the name is CM_146, but will probably be different in your system. You can rename the module by rightclicking on it in the Project tree.
- 43 -
Chapter 2 - Introduction
2. From the Library tree view, drag and drop your CDB type (CDBDEMO) into the Project chart.
3. Double-click the CDB instance to open its properties form. Click the Value CDPs tab. Your custom data parameters will be displayed in a list.
4. Click OK to close the form. 5. Click the X in the upper right corner of the Project chart to close the window. Click Yes when
prompted to save data. 6. Assign the Control Module to the CEE.
Select the Control Module under the Unassigned node in the Project tree. 7. Click the Assign button on the Control Builder toolbar. 8. When the Assignment screen appears, be sure that your new CM is selected in the Available
Modules list and the CEE that you want to assign it to is selected in the Assign To list, and then click Assign. 9. Click Close. Your CM now appears under the CEE node in the Project tree.
l To load the CM, click the Load button. style="width:400px;height:319px;"/>
l Click OK to close the Load dialog that appears. 10. Click the Monitoring tab and then select the CDB in the tree view. 11. Click Controller > Activate > Selected Item(s).
- 44 -
Chapter 2 - Introduction
2.11.7
12. Click Yes to confirm. The CDB values are now available for other blocks and can be viewed.
Additional examples
More advanced examples of CAB and CDB usage are in the CAB and CDB Example Scenarios section later in this guide.
- 45 -
CHAPTER
3
CAB AND CDB PURPOSE
3.1
3.1.1 3.1.2
Purpose, use, and value of the system
One of your options for implementing a control strategy is to use instances of "native" blocks. These are block types that are built in, or predefined, in Experion PKSControl Builder (CB). You can "customize"these native blocks by values you assign to certain configuration parameters, but you cannot alter the basic structure of the block-the data elements and the control algorithm.
Creating control strategies this way is efficient, as it requires only the work of creating instances, configuring parameter values, binding the instances to other blocks, to an execution environment, and to I/O. Many control strategies can be implemented very efficiently with these native blocks. In some cases, however, you might find that you cannot easily solve a control problem using native block types. When these cases arise, you can use CAB functionality to create a new custom block type with a custom algorithm, custom data parameters, and parameter references.
The process of creating a CAB type requires an understanding of system capabilities and tools beyond those used for block instance creation and editing. Not least of these is the understanding of a programming language.
After a CAB type has been created and saved within the Experion PKSERDB, it has a look and feel equivalent to that of a native block type. It shows up within the library view of CB under the name of a user assigned library. It can be instantiated on the project side of CB by dragging from the library view to a control module chart. Once instantiated, the instances can be configured through a parameter driven properties form. They can be assigned and loaded as components of their parent control module. They can be monitored from the monitor side of CB.
The fully qualified name for a CAB type consists of the concatenation of the library name with the block type name. This means that different CAB types can be given the same name within different libraries.
User interaction to create CAB templates is analogous to that of native block types. Thus, an engineer can start with a CAB type and make a template directly from it. CAB parameters can be declared "template-defining" in the same manner as native block parameters.
Why use CAB?
An important reason to use CAB is to solve new control strategies that can be implemented most effectively by using custom algorithms and custom data parameters. Another reason for considering CAB is when you have an investment in custom control programs on another platform and want to migrate to Experion. CAB provides the support for custom algorithms and custom data. Existing programs can be recorded in VB.NET, which is a powerful, yet user-friendly programming language.
CDB overview
A CDB is a control block that stores data whose type and structure are defined by the user. CDB
- 46 -
3.1.3
Chapter 3 - CAB and CDB purpose
types are similar to CAB types in that they allow the creation of a custom type that can be instantiated multiple times. They differ in that while they support the definition of custom data parameters, they do not support the definition of parameter references and they do not support the definition of an algorithm.
CDB types are simpler to create than CAB types, as they are created in the PDE and do not require programming tools or the use of Microsoft Visual Studio. They appear within the CB in a library view and are dragged into control modules to create instances.
In all other respects, CDBs are analogous to CABs. They support associated properties forms and can be designed to support loadable configuration parameters. They can be used to create templates. Once instantiated, CDBs are configured, assigned, loaded, and monitored in a manner completely analogous to that of CABs and native blocks.
As with CAB types, the fully qualified name for a CDB type consists of the concatenation of the library name with the block type name. This means that different CDB types can be given the same name within different libraries.
Why use CDB?
CDBs are somewhat analogous to Custom Data Segments (CDS) in the TPS world. A typical use would be to pass data from one application (strategy) to another. For more information, see Custom Data Parameter purpose.
Anything that you can do with a CDB, you can also do with a CAB. Why would you choose to use a CDB rather than a CAB? Some examples are:
l You have not purchased a CAB developer license. CDB is a standard feature of CB and is therefore available to you without a CAB license.
l You have a situation where CDB is supported on a given platform and CAB is not. l CAB has a certain amount of .NET overhead because of its capability to support an algorithm,
and you do not need the algorithm feature.
3.1.4 3.1.5
System functions that support CAB and CDB
As with native blocks, the user view of CABs and CDBs is composed of elements provided by different subsystems, as summarized in the following table.
Relationships of subsystems
The following table illustrates the relationships of the major subsystems that support CAB and CDB. In this table, read a row from left to right. For example, "Microsoft Visual Studio .NET presents data content of ERDB" and "Engineering Repository Database hosts Block Type, Block Template, and Block Instance."
Table 3.1 Relationship of Subsystems that Support CAB and CDB
Subsystem
Relationship
Subsystem
Engineering Repository Database (ERDB)
Hosts
Block Type, Block Template, and Block Instance
Control Builder (CB) Edits
Block Type, Block Template, and Block Instance
- 47 -
3.2
Chapter 3 - CAB and CDB purpose
Subsystem
Relationship Presents data content of
Subsystem ERDB and CEE
Provides definition to
Experion server
Control Execution Environment (CEE)
Hosts Uses
Block Type and Block Instance Microsoft .NET Run-Time Enablers
Microsoft Visual Studio Edits
.NET (CAB only)
Uses
CAB Block Type
Microsoft .NET Compile-Time Enablers and/or Honeywell proprietary enablers.
Presents data content
ERDB
(including source code) of
Experion server
Transports data content to CEE
Experion PKSStation Presents data content of CEE and Experion server
CAB in system context
The following diagram displays how major subsystems connected with CAB/ACE and CAB/C300 fit into Experion. Note that there is a single build time for CAB, shown as "CAB Build-Time," within the diagram. This subsystem knows the differences between CAB/ACE and CAB/C300 but presents a unified authoring environment to the end user.
Figure 3.1 CAB in system context
- 48 -
3.2.1
Chapter 3 - CAB and CDB purpose
Description of subsystems
The relevance of each subsystem is as follows.
l Engineering Repository Database--ERDB forms the persistent storage for all non-run-time information related to blocks.
l Block Type--Native block types are formed from parameter definitions and associated information. This is true for CAB and CDB types as well but the definitions can be created and edited. The information that comprises the full definition of a block type is somewhat distributed, with parts residing in both the build-time and run-time environments. Within the user view, an abstraction is presented that makes block types appear as a unified entity.
l Block Instance--Block instances are data sets. In the build environment (held by ERDB), instances consist largely of configuration data. In the run-time environment (held by CEE), they consist of both configuration and run-time data. Block instances always rely on an associated block type. Block instances, like block types, are presented to users as an abstraction that unifies the distributed parts that make up the complete entity.
l Block Template--Block templates are data sets holding configuration data. They are used to reduce engineering effort in the maintenance of block instances and have similarities to both block types and block instances. Block templates exist only in the build-time environment. Like block instances, block templates always rely on an associated block type. Templates are supported for CAB and CDB types as well as standard block types.
l CEE--CEE is the repository for most information of the run-time environment. This includes both instance information and type information. For native blocks, CEE holds the type information in an unchangeable form. For CDBs and CABs, both instance and type information are loadable. For CABs, the type information includes both parameter definitions and algorithm (program) definition. Block templates play no role within CEE.
l Control Builder--Control Builder presents block instance data that is resident in both ERDB (the "project side" of CB) and CEE (the "monitor side" of CB). CB supports the visual editing of both block instances and block templates. CB also supports the editing of CDB types.
l Microsoft Visual Studio 2012--CAB types are edited with Microsoft Visual Studio 2012. This applies to both the parameter definitions of the block and the algorithm. Microsoft Visual Studio 2017--CAB types are edited with Microsoft Visual Studio 2017. This applies to both the parameter definitions of the block and the algorithm.
l Experion server--The Experion server plays a vital role in presenting blocks within the operational view. It holds large portions of run-time data including alarm and history databases. It also uses system communication services to transport run-time data from CEE block instances to operator displays. CB provides block definition information to Experion server to enable display of operational information.
l Experion PKSStation--The Experion PKSStation presents the final operator view of run-time data. This includes alarm summary display, event journal display, detailed displays, group display, and graphical displays. Experion PKSStation relies on communication with Experion server, and, in some cases, with CEE to access run-time data. Within Experion PKSStation and Experion server, blocks are treated equivalently, regardless of whether they are native blocks, CABs, or CDBs. This guide does not give particular attention to CABs and CDBs within Station and Server, as their behavior is equivalent to that of native blocks.
l Microsoft .NET Compile-Time Enablers--CAB types are highly dependent on Microsoft .NET software technology. One dependency is on the .NET compile-time tools incorporated within Microsoft Visual Studio 2012. These tools are used to build source code into modules that can be loaded to the run-time environment. CDB types do not depend on .NET compile-time enablers. Microsoft .NET Compile-Time Enablers--CAB types are highly dependent on Microsoft .NET software technology. One dependency is on the .NET compile-time tools incorporated within Microsoft Visual Studio 2017. These tools are used to build source code into modules that can be loaded to the run-time environment. CDB types do not depend on .NET compiletime enablers.
- 49 -
Chapter 3 - CAB and CDB purpose
l Run-Time Enablers--Executing CAB types within a controller requires special capabilities in the controller's execution environment. These are known as "run-time enablers." o For CAB/ACE, the CEE depends on Microsoft .NET software technology to load and execute CAB types. The .NET run-time enablers include the .NET Common Language Run-time and class namespaces. CDB types do not depend on the .NET run-time enablers. o For CAB/C300, the CEE uses only Honeywell proprietary enablers to load and execute CAB types. All run-time enablers are native to the C300.
3.2.2 3.2.3
Platform hosting of block type categories
CEE can execute on multiple platforms. However, not all categories of block types are supported on each platform. The following table shows the categories of block types that are supported on each platform at the time of this release.
Platform
Table 3.2 Platform Support for Block Types Block type category
Native
CAB
CDB
C200
Yes
No
Yes
C200E
Yes
No
Yes
C300
Yes
Yes
Yes
SIM-C200E
Yes
SIM-C300
Yes
No
Yes
Yes1
Yes
1. SIM-C300 does not support source-level debugging of CAB types.
2. The present release of CAB supports most of the SIM-ACE functionality. However, this excludes bulk data access for dynamic simulation data. Dynamic simulation data is used for freeze, backup, and replay in dynamic simulation applications.
Role of block types, instances, and templates
Within the Experion PKSsystem, control algorithms are housed in blocks. These include both "block types" and "block instances."
l A block type is a general-purpose algorithm together with a set of data definitions. Block types are not bound to particular execution environments, particular equipment sets or particular data values. Examples of "native" Experion PKSblock types are: CM, SCM, PID, DataAcq, AND, and AICHANNEL.
l A block instance is a rendering of a block type in application-specific form. A given block instance is always associated with a particular block type. For any given block type, there can be a single block instance or there can be multiple block instances. Each instance has specific values for each datum defined for its type.
The Experion PKSsystem also supports templates. Templates are distinct from types and instances yet bear some resemblance to each. The differences between types, templates and instances can sometimes be a point of confusion for Experion PKSusers.
For brevity, the term "type" is used to mean "block type" in the remainder of this section. Similarly, "instance" refers to "block instance" and "template" refers to "block template."
- 50 -
Chapter 3 - CAB and CDB purpose
When an instance is to be loaded and used, it must be associated with a particular execution environment. Instances can have references to particular blocks, particular I/O, and particular equipment sets. Instances always have names that distinguish them from their associated types. For example, an instance of a CM might be called FC101, while an instance of PID might be called FC101.PID1.
Like types, templates can have multiple corresponding instances. Each instance (or "child") that descends from a template carries some of the characteristics exemplified by its parent. Yet, unlike types, templates do not define the data or algorithm they represent. Instead, they refer back to a type that maintains all data and algorithm definitions.
Like instances, templates can establish particular values for their parameters. They can establish particular address values for data references. Yet, unlike instances, templates cannot be loaded to execution environments. They never maintain a correspondence with specific field equipment.
Within Experion, it is entirely possible for engineers to build and maintain control strategies without the use of templates\types and instances are all that are required. Templates add capabilities for maintaining and modifying control configurations with reduced engineering effort. By creating a template as a modification layer between a type and one or more instances, engineers can declare particular data values and data references to be the same across all those instances. If common data values or references must change, the change can be introduced at the parent template and automatically propagated to the off-process child instances within the project side of the ERDB.
Following diagram illustrates the difference between block types, block instances, and block templates.
In the above diagram, a single type is shown called "Type." Type has instances and templates that descend from it. The direct descendants are Instance \1 and Template \1. Instance \2 and Instance \3 are indirect descendants of Type through Template \1. In general, it is possible to have no templates between an instance and its type or to have multiple templates between an instance and its type. To further illustrate, consider the following examples.
l Instance Creation From Type--An engineer decides to create a CM instance for purpose of flow control. The engineer calls it "FC101." Within FC101, the engineer creates a PID and calls it "PID1." Its fully qualified name is "FC101.PID1." In this example, FC101.PID1 is analogous to Instance \1 with PID in the role of Type.
l Template Creation From Type--Later, the engineer decides that something similar to FC101 would serve as a good starting point for other flow controllers. The engineer creates a template CM and gives it the name "FC." The engineer inserts a PID into FC and calls it "PID1." The engineer assigns some of the parameters of FC.PID1 to be "template defining." In this example, FC is analogous to Template1 with CM in the role of Type. Similarly, FC.PID1 is analogous to Template1 with PID in the role of Type.
l Instance Creation From Template--Later still, the engineer decides to create some new flow controller instances. To save work, the engineer doesn't start from the types, CM and PID. Instead, the engineer starts from the template, FC. The engineer creates an instance of FC called FC102. By so doing, the engineer implicitly creates the instance FC102.PID1. The engineer also creates an instance of FC called FC103. By so doing, the engineer implicitly creates the block instance FC103.PID1. FC102 and FC103 acquire their structure from the parent template FC. FC102.PID1 and FC103.PID1 acquire template-defining data from the parent template from FC.PID1. In this example, FC102.PID1 is analogous to Instance \2 while FC103.PID1 is analogous to Instance \3.
Types, instances, and templates are each distinct. But templates are closer to being instances than they are to being types. Instances and templates each depend on an association with a known type to have their identity fully defined. The main difference between an instance and a template is that the template has particular parameters, or particular structural characteristics, fixed over the category of instances that they govern.
It is important to understand that while templates can be created from types, and instance can be created from either types or templates, types must be created through a completely independent mechanism as described in Create a new CAB type.
- 51 -
3.3
3.3.1
Chapter 3 - CAB and CDB purpose
When you define a template in CB, you are able to specify that certain parameters are Template Defining. This is accomplished on the Template Defining tab of the properties form of the template type. In typical usage, parameters that are defined as Template Defining can only be changed in the parent template and cannot be changed in the instances of the template. In most cases, CB enforces this restriction; however, it cannot enforce it in the case of CAB parameter references. Therefore, you should avoid writing to these Template Defining parameters with CAB parameter references if you want to maintain the discipline that Template Defining parameters remain strictly under control of the parent template.
CAB functional overview
A CAB type represents the same concept as a "class" in modern object-oriented software terminology. Instances made from CAB types can be thought of as "objects." A class can be thought of as a library model or template, a "master" from which specific usable instances can be created and deployed. Within the concepts of Experion PKSand CEE, the user-visible entities tend to be called "block types" and "block instances" rather than "classes" and "objects."
As with any class, a CAB type is fundamentally characterized by the following two parts:
l A set of data definitions l An algorithm definition
Also, as with any class, a CAB type is defined by a program. However, due to its integration with Experion, the program of a CAB type does not express the complete definition. In particular, you must define much of the data of a CAB outside the source code you write for the program.
How a CAB works
The user's experience of CABs is generated through a combination of various services and subsystems. Each subsystem can be thought of as an "agent" that adds capabilities to the overall function set. The following three tables summarize the complete set of agents.
The following table emphasizes agents that play a vital role in the creation and editing of block types and block instances. This includes the ERDB as the central off-process database. It includes various displays, as well as subsystems that are not directly visible within the user view. The diagram also shows some agents that play a role in both build-time and run-time operations.
Agent Control Builder (CB)
Table 3.3 CABs in Build-Time Environment
Function
Agent
Presents data ERDB content of
Opens
Microsoft Visual Studio
Hosts
Library Tree, Project Tree, Monitor Tree, CM Project Chart, CM Monitor Chart, and CAB Properties Form
Microsoft Visual Studio .NET
Hosts
Presents data contents of
PDE Window and Source Code Window ERDB
Parameter Definition Edits Editor (PDE) Window
Parameter Definitions
Source Code window Edits
Algorithm Definition
Library Tree
Shows symbol Custom Library
- 52 -
Chapter 3 - CAB and CDB purpose
Agent
Function of
Agent
Project Tree
Shows symbol CAB Instance - Project of
Monitor Tree
Shows symbol CAB Instance - Monitor of
CM Chart - Project
Shows symbol CAB Instance - Project and data of
CM Chart - Monitor
Shows symbol CAB Instance - Monitor and data of
Custom Library
Groups
CAB Types
CAB Type
Consists of Parameter Definitions and Algorithm Definition
Defines
CAB Properties Form
CAB Instance - Project Is one of
CAB Type
CAB Instance - Monitor Is one of
CAB Type
CAB Properties Form Development Folder
Edits data of CAB Instance - Project and CAB Instance - Monitor
Views data of CAB Type - Library
Caches
Parameter definitions and Algorithm definitions
The following table shows subsystems that play a vital role in the run-time operations of CABs. For context, it also shows some agents whose purpose primarily serves the build-time environment.
Agent
Table 3.4 CABs in Run-Time Environment
Function
Agent
Control Builder (CB) Presents data content of
ERDB
Hosts
Control Module Chart - Monitor, CAB Properties Form, and CEE Block Properties Form
Control Module Chart - Monitor
Shows symbol and data of
CAB Instance - Monitor
Shows
Control Module - EE
CAB Properties Form Edits data of
CAB Instance - Monitor
CEE Block Properties Form
CAB Library Directory Form ACE Platform C300 Platform
Shows system data of
Has tab
Shows
CEE
CAB Library Directory Form Custom Library
Hosts Hosts
CEE CEE
- 53 -
Chapter 3 - CAB and CDB purpose
Agent CEE
Function Hosts
Custom Library
Hosts
CAB Instance Monitor
Is one of Shows
CAB Instance - EE Is one of
Control Module - EE Hosts
CAB Type
Defines
Agent Custom Library and Control Module - EE CAB Type CAB Type CAB Instance - EE CAB Type CAB Instance - EE CAB Properties Form
Note: In the previous tables, read rows from left to right to determine the relationships. For example, "Control Builder (CB) presents data content of ERDB." The following table describes each agent in detail.
Table 3.5 Agents Supporting CABs in Build-Time and Run-Time Environments
Agent
Operating environment
Description
Engineering Build-time Repository DB
Control Builder
Build-time and runtime
Microsoft
Build-time
Visual Studio
2017
Parameter Definition Editor Window
Parameter definitions
Build-time Build-time
Algorithm definition
Build-time
Source code Build-time window
Provides persistent storage for all block types and block instances. This applies to native blocks, CABs, and CDBs. Holds CAB programs across edit sessions. Holds CAB programs after they are complete and ready for load to an EE.
Central agent that manages view and edit of block instances. This applies to native blocks, CABs, and CDBs. CB and its underlying services present data content of the ERDB. CB hosts various different views and displays. These include the Library Tree, the Project Tree, the project side CM chart, the Monitor Tree, the monitor side CM chart, and the CAB Properties Form. CB supports the opening of MS Visual Studio 2017 for purposes of CAB type editing.
Integrated Development Environment that plays central role in the viewing and editing of CAB types. Microsoft Visual Studio and associated CAB services present data content of the ERDB. To support block type editing, Microsoft Visual Studio hosts two main types of windows: the Parameter Definition Editor Window and the Source Code Window.
Window through which user defines and edits parameter definitions of a block type. Also edits parameter references. Also allows specification of attributes of block properties form and block faceplate symbol.
Descriptions of public and custom data of the block. Parameter definitions associated with CAB types are different from those of native block types in that they are under the control of the user. They are called custom data parameters (CDPs, or value CDPs). Parameter definitions establish the name, data type and other attributes of parameters.
The CAB program.
Edit window through which Control Engineer (CE) creates and
- 54 -
Chapter 3 - CAB and CDB purpose
Agent
Operating environment
Description
Development Build-time folder
CAB Type
Build-time and runtime
Library Tree Build-time
Custom Library
Build-time and runtime
Project Tree Build-time
CM Chart Project
Build-time
CAB Instance Build-time - Project
edits the source code program that is the CAB algorithm. CEs can use one or several source code windows to create and maintain CAB source code.
Cache area used to hold block type definitions during edit sessions. The Development folder is located on the PC where CB and Microsoft Visual Studio run. Ordinary "Save" operations commanded at Microsoft Visual Studio write the algorithm and parameter definitions to this location. Ordinary Save must be distinguished from "Save To ERDB," which transfers the block type definition from the Development Folder to ERDB. The Development folder holds block types while Microsoft Visual Studio is open. Block types must be transferred to ERDB before Microsoft Visual Studio is closed (Microsoft Visual Studio prompts for Save To ERDB before closing). CAB services do not preserve the contents of the Development folder across Microsoft Visual Studio shutdown or across PC shutdown and startup.
Logical union of the parameters and algorithm that define the CAB. Also defines the CAB Properties Form. The user view of the CAB Type comes from a combination of system enablers, some in the build-time and some in the run-time. The complete type definition is comprised of data and program stored within ERDB and (after load of at least one instance) the EE.
View hosted by CB that shows libraries and the block type they hold. Native block types are held in system libraries while CAB and CDB types are held in custom libraries.
A logical grouping of user-created block types. Whereas native block types are held within system libraries, CAB and CDB types are held within custom libraries. Custom libraries provide an additional layer of naming for block types that can help with resolution of name collisions that might occur during import to a new ERDB. Within the Library Tree, custom and system libraries are distinguished by different icons. Within a custom library, CAB and CDB types are distinguished by different icons.
View hosted by CB that shows block instances held on the project side of ERDB. The project tree is a hierarchical view that shows SCMs, CMs and the function blocks they contain. This includes native block instances, CAB instances, and CDB instances. CB and ERDB maintain a distinction between "project side" data and "monitor side" data. Project side data correspond to instances that are under edit and have not been deployed within the run-time system. Monitor side instances map directly to run-time instances within EEs.
A graphical display showing the internal representation of a project-side CM. It shows symbols and data of the blocks as stored in ERDB as well as graphical connections. CM chart - Project shows both native and CAB instances.
Instance of a CAB held in ERDB for configuration activities. This is to be distinguished from the monitor-side instance. When shown within a CM chart, the ERDB data is presented rather than the runtime data.
- 55 -
Chapter 3 - CAB and CDB purpose
Agent
Operating environment
Description
Monitor Tree Build-time and runtime
CM Chart Monitor
Build-time and run time
CAB instance Build-time
- Monitor
and run-
time
CAB Properties Form
Build-time and runtime
CEE Block Properties Form
Run-time
CAB Library Directory Form
Run-time
ACE platform Run-time
View hosted by CB that shows block instances held on the monitor side of ERDB. State data and other data shown within the monitor tree correspond to the loaded run-time instances of the blocks depicted.
A graphical display showing the internal representation of a monitor-side CM. Shows symbols and data of the EE resident blocks as well as graphical connections. CM chart - Monitor shows both native and CAB instances.
Monitor-side instantiation of a CAB type. Is created from the project-side instance at the time of parent CM load. It is viewed from within the parent CM's chart using CB or using chart visualization in Station. Data read or written from CAB Instance Monitor corresponds to run-time data within the EE.
One of the chief displays used to view and manipulates CAB data. There is a different form for each block type. The form can be used to edit and view both project-side and monitor-side data, and view CAB type data in the Library. When viewed from the project side, writes go to the ERDB. When viewed from the monitor side, writes go to the EE block instance. The form is frequently used for assigning configuration data before load. It can be used exclusively for monitoring if the block has no loadable parameters. The form can be viewed from within Control Builder. It can also be viewed from Station displays via chart visualization.
Form showing data associated with the CEE as a whole. This form is logically associated with the CEE function block which hosts CEEwide parameters. CEE Block Properties Form plays a role in the configuration of the CEE. For CAB however, it is only used in connection with the run-time environment.
CAB Types Info tab on CEE Block Properties Form that shows CAB instances loaded to a CEE. The form displays:
l the software version numbers for .NET and CAB software.
l the label "Instantiated CAB Types" followed by the number of CAB types that have at least one instantiation.
l the label "Max Instantiated CAB Types" followed by the maximum number of CAB types that can be instantiated at any one time.
l a grid box showing the friendly name of each instantiated CAB type and the number of instances of each instantiated type.
Platform that hosts CEEs capable of supporting CABs.
C300 platform
CEE
Run-time Run-time
Control
Run-time
Module - EE
Platform that hosts CEEs capable of supporting CABs.
A logical operating environment providing execution services to both native blocks, CABs, and CDBs.
Run-time resident module block hosting continuous type function blocks. EE-resident control modules (called "Control Module - EE" in the table) host CAB instances, CDB instances, and all native block instances except those of the SCM library. CABs run within
- 56 -
3.3.2
Chapter 3 - CAB and CDB purpose
Agent
Operating environment
Description
CAB Instance Run-time - EE
Control Modules but not within Sequence Control Modules.
Run-time instantiation of the CAB type. EE-resident CAB instances (called "CAB Instance - EE" within the table") actually hold the runtime data and do the run-time execution of CABs. CAB instances are always associated with generic programs. All references that bind the block to specific equipment and specific external function blocks are contained within the instances.
CAB data characteristics
There are different categories of data that can be used within a CAB. They differ according to persistence, visibility, and where they are stored.
l Fixed Definition Parameters (FDPs)--Parameters that are defined by the system. Some FDPs are for internal use only and are of no concern to users. Others are known to users and are used either at the time of block type creation, block instantiation or both. Certain of these parameters (for example, the COMMIT parameter) are also used at run time. Some of these parameters appear on the fixed tabof the Parameter Definition Editor in the Microsoft Visual Studio Development Environment within Control Builder, where you are able to specify a default value. Specific FDPs supported by CAB types are described in Fixed definition parameters.
l Parameter References (PRefs)--These are traditional process control data elements that exist external to the CAB but whose values can be used within the CAB. Parameter references are configured on the Parameter References tab of the Parameter Definition Editor in the Microsoft Visual Studio Development Environment within Control Builder.
l Custom Data Parameters (CDPs)--These parameters are also known as value CDPs, and are configured by the user on the Value CDPs tab of the Parameter Definition Editor in the Microsoft Visual Studio Development Environment within Control Builder. CDPs are variables visible within the program and within the Experion PKSas a whole. They are "public" in that any agent that has access to the PKS name space can read them. Similarly, CDPs can be written by any PKS agent subject to store access checks specified by the block designer. For more information, see Define CAB type parameters.
l Block scope variables--Block scope variables are like CDPs in that they are persistent and are retained across block executions. They differ in that they are not visible within the namespace of the PKS. Thus, they never "appear" on the "surface" of the block. Since block scope variables are visible only within the CAB program, their use is a matter private to the CE who creates the CAB type. For more information, see Define block scope variables.
l Local variables--These variables are declared within the Execute() subroutine that is included in the skeleton code framework supplied by Honeywell, or in user-created subroutines and functions. The Execute() subroutine is where you insert your custom algorithm code. Values of local variables are not persistent from one block execution to the next. For more information, see Define local variables.
3.3.3
CAB algorithm characteristics
Algorithms are defined in the CABlock.vb tab of the Microsoft Visual Studio Development Environment within Control Builder. On this page, Honeywell provides a skeleton application that includes an Execute() subroutine. You insert your application code under this subroutine. The Execute() subroutine can be configured to execute under control of the host CM, or it can be used as an insertion point algorithm for another component block such as a PID. For more information
- 57 -
3.3.4
3.4
3.4.1
Chapter 3 - CAB and CDB purpose
about CAB algorithm definition, see Algorithm definition - Execute(). For more information about using a CAB as an insertion point algorithm, see Configure insertion points.
CAB execution mode characteristics
CABs that run on C300 can only execute in the atomic execution mode. Distributed execution is not supported in C300. Since history and file access functions require distributed execution, these functions are also not supported on C300. CAB/C300 has an execution time limit that is different from that of CAB/ACE. For more information, refer to the section CAB/C300 execution time limit.
CDB functional overview
A CDB is basically a CAB without an algorithm and without parameter references. CDB types are useful in a wide variety of applications. They can be used to hold data that is shared by multiple block instances within a CM or across multiple CMs. They can be used in conjunction with both native blocks and CABs. They can be used as a more self-documenting alternative to flags, flag arrays, numerics and numeric arrays.
How a CDB works
As with CABs, the Control Engineer (CE) interacts with various agents when creating and using CDBs. Build-time and run-time agents important to CDBs are shown in the following table. In this table, read a row from left to right. For example, "Control Builder (CB) Presents data content of ERDB."
Agent
Control Builder (CB)
Table 3.6 CDBs in Build-Time and Run-Time Environments
Function
Agent
Presents data content of
ERDB
Hosts
Library Tree, Project Tree, Monitor Tree, CM Project Chart, CM Monitor Chart, CDB Properties Form, and the Parameter Definition Editor Window
Parameter Definition Editor (PDE) Window
Edits
Parameter Definitions
Library Tree
Shows
Custom Library
symbol of
Project Tree
Shows
CDB Instance - Project
symbol of
Monitor Tree
Shows
CDB Instance - Monitor
symbol of
CM Chart - Project Shows
CDB Instance - Project
symbol and
data of
CM Chart Monitor
Shows
CDB Instance - Monitor
symbol and
- 58 -
Chapter 3 - CAB and CDB purpose
Agent
Cxxx and ACE Platforms CEE Custom Library CDB Type
CDB Instance Project CDB Instance Monitor CDB Properties Form
Control Module EE
Function data of Shows Host
Control Module - EE CEE
Agent
Hosts
Control Module - EE
Groups
CDB Types
Consists of Parameter Definitions
Defines
CDB Properties Form
Is one of CDB Type
Is one of CDB Type
Represents CDB Instance - EE
Edits data CDB Instance - Project and CDB Instance - Monitor of
Views data CDB Type - Library of
Hosts
CDB Instance - EE
System agents relevant to CDBs are generally a subset of those relevant to CABs. Agents common to the two categories generally have the same meaning and usage in each case. However, there are some differences that are highlighted in the following table.
Table 3.7 Agents Supporting CDBs in Build-Time and Run-Time Environments
Agent
Description
Control Builder
CB hosts all services for creation and edit of CDB types. Control Builder plays largely the same role for CDBs that it does for CABs. One difference is that Microsoft Visual Studio plays no role in the creation and edit of CDB types. Thus, Control Builder does not open Microsoft Visual Studio in order to start edit sessions for CDB types.
Parameter For CDB types, the Parameter Definition Editor window is hosted directly within Control
Definition Builder. For CAB types there is an advantage to hosting the Parameter Definition
Editor
Editor window within Microsoft Visual Studio. This allows an integrated application to
Window be the seat of both the data complement and algorithm complement that make up a
CAB type. Since there is no algorithm in CDB types, it is most natural for the CE to
edit the type in the same application where the CE edits the instance.
CDB Type CDB types consist of parameter definitions with no algorithm definition.
Custom Library
CDB Types are grouped by custom libraries in the same manner as CAB types. Custom libraries are useful in that they provide an additional layer of naming that can help when resolving name collisions upon import to a new ERDB. One way in which CDBs and CABs differ is that for CDBs, custom libraries have no role to play in the runtime environment. The type definition of CDBs is held within each instance in the run-time environment. Thus, there is no dependence on a library for hosting of CDB types or unloading of CDB types.
CDB
As with CABs, CDB instances are held on the project side of the ERDB when they are
Instance - being created or edited.
- 59 -
3.4.2
Chapter 3 - CAB and CDB purpose
Agent
Description
Project
CDB
CDB Instances are held on the monitor side of the ERDB after they have been loaded
Instance - and reside in an EE.
Monitor
CDB Properties Form
As with CABs, the CDB properties form is defined by the CDB type. This form can be used to edit the project side instance or the monitor side instance. It can be used to view CDB type data in the Library. It can be used to display view-only parameters as well as configuration parameters. It can be viewed from within CB or from within Station displays via Experion PKSchart visualization.
CDB Instance EE
CDB instances within an EE form the repositories for actual run-time data. Note that CDB Instance - Monitor, though it is logically considered part of the run-time environment, is not used in any manner by control algorithms at run-time. It holds ERDB data that must be preserved to represent CDB Instance - EE. The instances can be used by control algorithms of CABs through connections or parameter references. They can also be part of control strategies with other native blocks involving connections.
CDB Library Directory Form
Block Types Info tab on CEE block properties form that displays the information about the functional blocks loaded to a CEE. The form displays (1) the label "Number of Block Types Defined" followed by the number of block types defined in the CEE, (2) the label "Maximum Number of Block Types" followed by the maximum number of block types that can be supported in the CEE, and (3) a grid box displaying the block type name which gives the description string used for the block type name, CCL library displaying the name of the CCL containing the block type, block size in bytes displaying the size of the block type footprint, and the instance count displaying the number of instances currently loaded to the controller. Custom Types Info tab on CEE block properties form that displays custom type information about the custom data blocks loaded to a CEE. The form displays (1) the label "Custom Types Represented" followed by the label "Custom Data Blocks(CDBs) and Phase Blocks", (2) the label "Instantiated Block Types" followed by the number of custom data definition manager types, (3) the label "Max Instantiated Block Types" followed by the maximum number of instantiated block types, and (4) a grid box displaying the block type name type and the number of each block type instance count.
CDB data definition characteristics
l Fixed definition parameters--Parameters that are defined by the system. Unlike CABs, CDBs do not have FDPs for which the user can define default values when the CDB type is defined in CB. Therefore when the PDE is open for CDB definition, it does not have the Fixed tab that is present for CAB definition.
l Custom data parameters--These parameters are also known as Value CDPs, and are configured by the user on the Value CDPs tab of the Parameter Definition Editor within Control Builder. CDPs are variables visible within the PKS as a whole. They are "public" in that they can be read by any agent that has access to the PKS name space. Similarly, CDPs can be written by any PKS agent subject to store access checks specified by the block designer. For more information on CDPs, see Define CDB custom data parameters.
- 60 -
CHAPTER
4
CAB AND CDB SYSTEM PLANNING AND DESIGN
4.1
System architecture
4.1.1 4.1.2
Role of CAB and CDB in system architecture
CAB and CDB are elements of the Experion PKSsystem. They adhere to the architecture of the Experion PKSsystem, which involves:
l Building control strategies within Control Modules, using the Control Builder development tool.
l Executing the strategies in a Control Execution Environment.
CAB and CDB provide the ability to build custom applications that are tightly integrated with the Experion PKSsystem.
CAB and CDB have similarities to components of the TPS system as shown in the following table.
Table 4.1 Comparisons of Experion PKSand TPS Architectures
Experion PKScomponent
TPS component
Function
Control Builder (CB)
DEB or TPS Builder
Tools for building control strategies.
Custom Algorithm Block (CAB) Control Language (CL/AM)
Allows development of custom control algorithms.
Custom Data Block (CDB)
Custom Data Segments Provides custom data storage. (CDS)
Application Control Environment (ACE)
Application Module (AM)
Hosts execution of CABs and CDBs.
C200 Controller
Process Manager (PM) Hosts execution of CDBs.
C200E Controller
Process Manager (PM) Hosts execution of CDBs.
C300 Controller
Process Manager (PM) Hosts execution of CABs and CDBs.
Note: C300 supports VB programming in CAB blocks for continuous algorithms only.
System requirements
l Minimum CAB Developer Requirements--The CAB product requires the following to allow users to develop CABs:
- 61 -
Chapter 4 - CAB and CDB system planning and design
o Control Builder on Experion PKSStation o Experion server o CAB Developer license and components o Microsoft Visual Studio 2012 (included with the CAB-Developer package) o Microsoft Visual Studio 2017 (included with the CAB-Developer package)
l Highly Recommended--SIM-ACE node for off-process CAB debug in conjunction with Microsoft Visual Studio debugger (see Off-process debugging). SIM-C300 can also be used for simulating CAB execution on C300. However, source-level debugging is not supported.
l Minimum CAB User Requirements--The CAB product requires the following to allow a CAB to be loaded to an ACE or C300 CEE and executed within an ACE or C300 CEE: o Control Builder on Experion PKSStation o ACE or C300 (hardware and software with latest ACE or C300 CEE version that supports the CAB function) o Experion server o CAB run-time components (included with the ACE and C300 base licensing)
l Minimum TPS Interoperability Requirements for CAB o TPN Release 64x or later o Control Builder on Experion PKSStation o ACE (with latest ACE CEE version that supports the CAB and CDB function) o Experion server o CAB run-time components (included with the ACE base licensing) o OPC Gateway interfacing to TPN Server
l Minimum CDB Developer Requirements--The CDB product requires the following to allow users to develop CDBs: o Control Builder on Experion PKSStation o Experion server
4.1.3
CDB Requirements
l Minimum CDB User Requirements--The CDB product requires the following to allow a CDB to be loaded to an ACE,C200, C200E, or C300 CEE and executed within an ACE, C200, C200E, or a C300 CEE: o Control Builder on Experion PKSStation o ACE, C200, C200E, or C300 (hardware and software with latest ACE, C200, C200E, or C300 CEE version that supports the CDB function) o Experion server
l Minimum TPS Interoperability Requirements for CDB o TPN Release 64x or later o Control Builder on Experion PKSStation o ACE (with latest ACE CEE version that supports the CDB function) o Experion server o OPC Gateway interfacing to TPN Server
- 62 -
Chapter 4 - CAB and CDB system planning and design
4.2
CAB and CDB hardware and software requirements
4.2.1 4.2.2
Hardware requirements for CAB and CDB
For hardware information, see the SCN and/or Spec and Tech applicable to the release.
ACE hardware must have at least 2 GB of memory.
An important part of your hardware planning is to determine:
l The number of ACE nodes and C300 controllers that you require for CAB and CDB. l The number of C200 or C200E controllers that you require for CDB. l The number of CB clients that you require for CAB and other strategy development. l The number of CAB Developer licenses that you require.
Clearly, these choices will depend on the level of your CAB, CDB, and native block development and use. If you subcontract your CAB development, or are at a location where you import your CAB instances, you only need to be concerned with ACE and/or C300 issues.
Honeywell recommends SIM-ACE node(s) for off-process CAB debug. SIM-ACE is ACE in the simulation mode. SIM-ACE can have the Microsoft Visual Studio debugger attached for source code debug, whereas ACE and SIM-C300 cannot. A separate SIM-ACE node allows you to develop and debug CAB programs independent of your on-process operations. Refer to Debug with SIMACE for SIM-ACE information. For your planning purposes, note that a dual-processor node will support up to four SIM-ACEs, while a single-processor node will support Determine ACE shutdown horizon up to two SIM-ACEs.
To determine your ACE and/or C300 node requirements, try to estimate your anticipated CAB usage. For guidance on ACE loading considerations, see Determine ACE CAB processing capacity, Determine ACE configuration limits for CAB/ACE types and instances, and Determine ACE shutdown horizon. For information about C300 performance and capacity, refer to the following sections: Determine C300 CAB processing capacity, and Determine C300 configuration limits for CAB types and instances.
To determine the number of Station nodes with CB that you will require, try to estimate your anticipated CB development activity, especially the total number of developers who will be doing concurrent development work. At this time, a server will support a maximum of eight concurrent CB connections. In addition, you must have enough CAB Developer licenses to support the maximum number of developers who will be doing concurrent CAB development activity on some or all of these CBs. These licenses are "floating" in the sense that they are not associated with a particular CB node, but the total number of CBs that have the integrated Microsoft Visual Studio application open for CAB development cannot exceed the number of licenses.
Software environment requirements for CAB and CDB
l CAB Build Time--For the build-time environment, CABs require the R400 versions of the following: o Experion server--Hosts the ERDB where CAB type definitions are stored. o Experion Control Builder on a Station node--Experion PKSCB incorporates a wide array of build-time services. These include enablers for compile and build of CAB types and instances, for parameter definition editing and others. CAB build-time enablers are independently licensable but are installed as part of CB.
- 63 -
Chapter 4 - CAB and CDB system planning and design
o Microsoft Visual Studio 2012--Microsoft Visual Studio is distributed by Honeywell to its customers as part of the overall CAB build-time solution.
o Microsoft Visual Studio 2017--Microsoft Visual Studio is distributed by Honeywell to its customers as part of the overall CAB build-time solution.
o Microsoft Windows OS--For specific OS requirements, refer to the SCN and/or Spec and Tech that is applicable to the release.
l CAB Run Time (ACE)--For the run-time environment, CAB/ACE requires the R400 versions of the following: o Experion ACE--Experion PKSACE provides a wide array of run-time services. This includes enablers for the load and execution of CAB types and instances. CAB runtime enablers are included with the ACE base license and are installed as part of ACE. o Microsoft Windows OS: For specific OS requirements, refer to the SCN and/or Spec and Tech that is applicable to the release. Legacy releases of CAB run on the Microsoft .NET Framework 2.0, 3.0, and 3.5 which includes .NET CLR as one of the required enablers for CAB run-time services. From the R311.2 release onwards, CAB run-time services run on Microsoft .NET Framework 2.0 and higher. o Highly Recommended--SIM-ACE node for off-process CAB debug in conjunction with Microsoft Visual Studio debugger (see Off-process debugging). SIM-C300 can also be used for simulating CAB execution on C300. However, source-level debugging is not supported.
l CAB Run Time (C300)--For the run-time environment, CAB/C300 requires the R400 versions of the following: o C300--C300 provides a wide array of run-time services. This includes enablers for the load and execution of CAB types and instances. CAB run-time enablers are included with the C300 base license and are bundled with the C300 firmware. o Highly Recommended--SIM-ACE node for off-process CAB debug in conjunction with Microsoft Visual Studio debugger (see Off-process debugging). SIM-C300 can also be used for simulating CAB execution on C300. However, source-level debugging is not supported.
l CDB Build Time--For the build-time environment, CDBs require the following software, at the current release (R400). o Experion server--Hosts the ERDB where CDB type definitions are stored. o Experion Control Builder on a Station node--CB includes enablers for the definition and build of CDB types and block instances. CDBs are not a separately licensable option, and therefore build-time enablers are included with every CB. o Microsoft Windows OS--For specific OS requirements, refer to the SCN and/or Spec and Tech that is applicable to the release.
l CDB Run Time (ACE)--If you are using CDBs on ACE, CDBs require the following software or firmware for the run-time environment: o Experion ACE--ACE includes enablers for the load and execution of CDB types and CDB instances. CDBs are not a separately licensable option, and therefore run-time enablers are included with every ACE. o Microsoft Windows OS (ACE node)--For specific OS requirements, refer to the SCN and/or Spec and Tech that is applicable to the release.
l CDB Run Time (C200, C200E, or C300)--If you are using CDBs on C200, C200E, or C300, Experion PKSCEE firmware at the current release (R300) that supports the load and execution of CDBs is required. CDBs are not a separately licensable option, and therefore run-time enablers are included with the C200, C200E, or C300.
Note: Size of the ERDB is not a concern for CAB.
- 64 -
4.3
Security policy
Chapter 4 - CAB and CDB system planning and design
4.3.1
4.3.2 4.3.3
User access
User access to build tools for creating CAB and CDB types is controlled by the same security policies that govern access to CB. Basic access to CB is controlled by logon password. A developer license is required to access CAB development tools within CB. CAB Developer optional licensed software can only be installed on Experion PKSStation nodes with Control Builder and cannot be installed on Experion server nodes. See CAB Developer license for additional information.
User access to CAB instances and CDB instances is controlled by the same security policies that govern access to native blocks.
To create or edit CAB/types, you need to be a member of the "Local Engineers" group.
For more information on security policies, refer to the Network and Security Planning guide.
CDP Access Lock attribute
Like native block parameters, custom data parameters have an additional level of access control, the Access Lock attribute. This attribute is configured when the CAB or CDB is created and cannot be changed thereafter except by editing the block type and reloading instances. See Access Lock attribute for CDPs for details.
SIM-ACE and the Microsoft Visual Studio debugger
The Microsoft Visual Studio source level debugger should never be attached to an on-process ACE because of the possibility of debugger activity freezing control processing. The best way to prevent this possibility occurs at ACE installation time. You will be given a choice of whether or not to install the remote debugger. You can choose to install this option only on nodes that will be running SIMACE but not ACE. If the debugger is installed on a node that is configured as ACE and the Remote Debug Monitor service runs, activation of the ACE CEE is prevented in CB.
With Visual Studio 2017, an administrator must enable remote debugging of CAB types by setting up an ACE to allow a remote debugger to attach to it. Once this is done, a user with the necessary permissions can attach to the Remote Debugger from the client. See Remote debugging using Visual Studio.
When using the Microsoft Visual Studio debugger, you create a debug version of the CAB program by building to the "debug target" in Microsoft Visual Studio. You debug the CAB program in the SIM-ACE environment, which is an off-process environment, and therefore isolates the debug activity and safeguards against disruption of on-process functions. When debug is complete, you create a release version of the CAB program by building to the "release target" in Microsoft Visual Studio. You should do a final test on SIM-ACE using the release version to ensure that the program still works as intended. Then, you deploy the release version to the on-process environment. For more information, see Off-process debugging.
Some CAB programs can be debugged without using the Microsoft Visual Studio debugger. But in other cases the debugger will be a useful tool for CAB development. In order to use the debugger, CAB programs must be loaded to an ACE that is configured to be in the simulation mode, called SIM-ACE. SIM-ACE is never used for on-process control. For more information about SIM-ACE, see Debug with SIM-ACE.
- 65 -
4.3.4
4.4
4.4.1
Chapter 4 - CAB and CDB system planning and design
Configuring for OPC history data access
History access, which requires distributed execution, is applicable only to CABs executing on ACE. History access is not supported on C300 because it does not support distributed execution. For a distributed CAB to access history data through OPC, the CDA-sp process must be configured the same way that you would configure to access data through the OPC Gateway. See "Configuring ACE to Communicate with OPC Servers" in the OPC Gateway for ACE Interface Reference manual and do the procedure, "Configuring CDA-sp for OPC.
Input data validation
You must ensure to validate all input data before using it in CAB blocks.
Loss of view or control resulting from improper configuration
Note that improper configuration of a CAB block can consume the controllers' CPU or other resources resulting in a loss of view or control. Therefore, prior to configuring a CAB block, refer to the Extreme configuration section of this document to be aware of the configuration details.
- 66 -
CHAPTER
5
CAB MEMORY AND PROCESSING LOAD
CONSIDERATIONS
5.1
CAB on ACE
5.1.1
Determine ACE CAB processing capacity
An ACE can run approximately 300 medium-sized CAB instances (see Determine ACE memory utilization) with a 0.5-second execution interval at a 60% load.
TIP Refer to Configuring the Local Security Policy in this guide for methods of monitoring CPU utilization.
5.1.2
Determine ACE configuration limits for CAB/ACE types and instances
The following table provides information on the limits on the number of types and instances that can be configured on an ACE with 2 GB of memory.
Item
Table 5.1 Configuration limits for CAB/ACE types and instances
Typical Maximum count count
Comment
Loaded
200
instantiated
CAB types
400 per ACE
This limit is enforced. CAB infrastructure (ACE loader) prevents the number of instantiated1 block types from growing beyond 400 per ACE2. The maximum count of
instantiated CAB types is enforced because it corresponds to
the count of programs actually in use. Each must be
physically resident within PC memory.
CAB
-
instances
per type
No
CAB does not have an enforced instance limit. The CAB
enforced instance limit is determined by the controller user memory
limit
pool.
Total CAB instances across all
1000
2000 per ACE
This limit is enforced. CAB infrastructure (ACE loader) prevents the total number of CAB instances from exceeding 2000 per ACE.
- 67 -
5.1.3
Chapter 5 - CAB memory and processing load considerations
Item
Typical Maximum count count
Comment
types
1. An instantiated CAB type is one that has one or more instances defined against it within the CEE.
2. You can have 400 CAB instantiated types and 400 CDB instantiated types per ACE. These limits are independent of each other and these limits are both enforced.
Determine ACE memory utilization
Memory utilization for CAB and CDB is a more complex topic than it is for native blocks. For this discussion we need some simple definitions. These definitions are not precise .NET definitions, but are suitable for this discussion and for planning purposes.
l OS Memory--This memory is a part of the memory managed by the Operating System. A typical size for this memory for an ACE is 2 GB.
l CEE Memory Pool--This memory is a part of the CEE executable, and is managed by the CEE. The size of this memory in current CEEs is 32 MB.
l Recoverable--Memory labeled as recoverable can be returned for later use, when it is no longer needed for type or instance storage.
l Unrecoverable--The opposite of recoverable. Memory labeled as unrecoverable cannot be returned for later use. An ACE node restart is required to "recover" unrecoverable memory.
CAB/ACE applications use these types of memory: l Unrecoverable OS Memory l Recoverable OS Memory l Recoverable CEE Memory Pool
The following table compares typical memory usage for some arbitrary typical CAB application size categories.
Table 5.2 Memory Requirements for Small, Medium, and Large ACE CABs
CAB size category
Lines of code
Number of CDPs
Number of PRefs
CAB type size CAB instance size
(KB)
(KB)
Small
20
1
10
73
31
Medium
100
15
50
74
61
Large
200
30
100
84
103
The previous table displays how CAB type memory size does not vary dramatically between small and large CAB types. Much of the size of a CAB type is taken up by the built-in CAB functionality, rather than the user-developed code or parameter definitions. CAB type memory comes from unrecoverable OS memory, as described in Determine ACE shutdown horizon.
CAB instance memory comes from recoverable OS memory. From the table, we can see that the CAB instance memory size is tied to both the number of lines of code, and the number of parameters.
- 68 -
5.1.4
5.2
Chapter 5 - CAB memory and processing load considerations
In addition to the OS memory, each CAB instance also consumes about 3 KB of recoverable CEE memory pool memory. The exact size of this consumed memory is variable, but is usually close enough to 3 KB that 3 KB is a good rule of thumb for planning purposes. With 32 MB of CEE memory pool memory available for CAB and native block instance memory, this is rarely the driver for planning decisions.
Determine ACE shutdown horizon
The shutdown horizon is applicable only to CAB/ACE.
CAB instance memory is reclaimed when the instance is deleted, for both the recoverable OS memory and the CEE memory pool memory associated with the instance. See ACE shutdown procedure for reclaiming CAB memory for the procedure to reclaim memory. See Configuring the Local Security Policy for methods of monitoring memory utilization.
Each time a CAB type is modified and the instance is loaded into the CEE, unrecoverable OS memory is used. The unrecoverable OS memory used for the old CAB type cannot be reclaimed until the ACE node is shutdown and restarted. Thus, unrecoverable OS memory gets used up as new CAB types are added and loaded, and when existing types are modified and reloaded. Eventually, the ACE needs to be shutdown and restarted to reclaim the memory used by obsolete CAB types. The system is designed such that under normal to heavy CAB engineering activities, shutdown and restart will not be required for at least two years.
The following table displays a calculation of estimated memory usage at the end of two years for medium sized blocks.
Table 5.3 ACE Memory Usage after Two Years for Medium-Sized CABs
Item
Maximum count
Maximum memory required (KB)
Total instantiated CAB Types reloaded in ACE during debug sessions.
400 types x 30 reloads = 12000
12000 x 74 = 888,0001
Total instantiated CAB Types reloaded in ACE during maintenance cycle.
400 types x 3 reloads x 2 years = 2400
2400 x 74 = 177,600
Total CAB instances allowed to be 2000 loaded at one time
2000 x 61 = 122,000
ACE + .Net Run-time + CAB runtime
Total memory
Loaded once
12,000 1,187,600 (1.13 GB)1
1. If you are using SIM-ACE for debug, the memory consumed during reloads of types is reclaimed when you shut down the SIM-ACE and therefore should not be included in the total memory figure.
Honeywell strongly advocates the use of SIM-ACE for debug because of the security advantage and the ability to use the Microsoft Visual Studio debugger. However, if you do choose to debug on ACE and then use the same ACE for production, you should do a shutdown before going on line, thereby reclaiming memory.
CAB on C300
- 69 -
5.2.1 5.2.2 5.2.3
Chapter 5 - CAB memory and processing load considerations
Determine C300 CAB processing capacity
The amount of CPU consumed by the execution of a CAB/C300 block instance can vary depending on the lines of code, the amount of looping, and the program's general complexity. For example, the following table gives an indication of the CPU consumption for one instance of the "Medium" CAB type.
CAB size category
Lines of code
Table 5.4 CPU Utilization of medium sample type
Number Number C300v3 CPU consumption C300v5 CPU consumption
of CDPs of PRefs (PU / block instance)
(PU / block instance)
Medium 100 15
50
6.27
2.52
Note 1:
In CEE, one Processing Unit (PU) is equal to 1\4 of the total amount of time required to process a typical DevCtl CM and a typical RegCtl CM.
For information about CAB/C300 memory usage and related topics, refer to Determine C300 memory utilization.
Determine C300 configuration limits for CAB types and instances
The following table provides information on the limits for the number of CAB types and instances that can be stored within an individual CEE-C300. There is no limit on the number of CAB/C300 types or instances that can be stored within the ERDB.
Item
Table 5.5 Configuration limits for CAB/C300 types and instances
Typical Maximum
count
count
Comment
Loaded instantiated CAB Types
30 to 70
C300 v3 - 100 This limit is enforced and adds to the constraint of C300 v5 - 200 memory utilization within the CEE user memory
pool.
CAB Instances Per 1 to 10 No enforced The only limit on instances per type is memory
Type
limit.
utilization within the CEE user memory pool.
Total CAB Instances Across All Types
50 to 500
No enforced limit.
The only limit on total instance count is memory utilization within the CEE user memory pool.
Maximum count for C300v5 in CAB types is set to display 201. However, it is restricted to load upto 200 CAB type. Any attempt to load more than that would result in an error.
Determine C300 memory utilization
CAB/C300 types and instances are allocated in the CEE user memory pool. The first time an instance of a CAB/C300 type is loaded to the CEE, the block type is loaded with it. The first instance thus requires a total amount of memory equal to that used by the type and the instance together. When the subsequent instances of a type are loaded, the only additional memory required is that used by the instance.
The following table indicates the type and instance memory used by three kinds of block type, roughly characterized as "Small", "Medium" and "Large". Types and instances substantially larger than what is called "Large" in the following table can be loaded to a C300.
- 70 -
Chapter 5 - CAB memory and processing load considerations
No Strategy Empty CM
Table 5.6 C300 memory use of sample types and instances
56632 56992
(bytes) (bytes)
CAB type used SMALL BNC
CM+CAB Loaded (bytes)
77080
CM delete (bytes) 75204
TYP TYP INS INS (bytes) (KB) (bytes) (KB)
18527 18.14 1516 1.48
MEDIUM CSUB 92180
87032
30400 29.69 4788 4.68
LARBNC
112324
103120
46488 45.4 8844 8.64
5.2.4
5.3
CAB/C300 differs from CAB/ACE in that the memory used by both block type and block instance comes exclusively from the CEE's user memory pool. There is no additional memory drawn from a separate pool managed by the C300 OS.
Total memory consumed by CAB/C300 types and instances can be monitored, together with the consumption of all the CEE native block instances, by viewing the following parameters.
l TOTALMEM l USEDMEM l FREEMEM l MAXFREEBLKSZ
These parameters are displayed in the Memory Tab of the CEE-C300 block form in CB.
When a CAB/C300 instance is deleted from the CEE, all of its memory is freed and made available within the user memory pool. When the last instance of a CAB/C300 block type is deleted, the type itself is deleted and all of its memory is made available within the user memory pool. CAB/C300 does not have any "shutdown horizon" which must be tracked by the user.
Determine Size limits on CAB/C300 block types and instances
Resource constraints in the C300 controller require that maximum limits be imposed on the size of CAB/C300 types and instances. These limits are listed in the following table.
Item
CAB/C300 Type CAB/C300 Instance
Typical Maximum
Size
Size
Comment
20 to 700 KB 200 KB
This limit is enforced and adds to the constraint of memory utilization within the CEE user memory pool.
2 to 20 160 KB KB
This limit is enforced and adds to the constraint of memory utilization within the CEE user memory pool.
Configuration limits
5.3.1
Determine CAB configuration limits
l There are no enforced limits on the number of CAB types can be stored in the ERDB.
- 71 -
5.3.2
Chapter 5 - CAB memory and processing load considerations
l There is an enforced limit of 400 CAB types loaded to any single ACE CEE and an enforced limit of 100 CAB types loaded to any single C300 v2/v3 CEE.
l There is an enforced limit of 2000 CAB types loaded to any single C300 v5 CEE. There is no enforced limit on the number of instances that can be loaded to a C300 CEE. For C300, instance count is limited by available memory.
Although these numeric limitations are important, they are usually overshadowed by subsequent memory capacity, execution performance, or shutdown horizon considerations.
Determine CDB configuration limits
The following table provides information on the limits for the number of CDB types and instances that can be configured in C200, C200E, C300, and ACE with a 2 GB of memory.
Item
Table 5.7 Configuration Limits for CDB Types and Instances
Typical Maximum
count
count
Comment
Loaded
200
instantiated
CDB types
for ACE.
600 per ACE
This limit is enforced. CDB infrastructure (ACE loader) prevents the number of instantiated1 block types from growing beyond 600 2.
Loaded
50
instantiated
CDB types
for C200.
100 per C200
This limit is enforced.
Loaded
50
instantiated
CDB types
for C200E.
100 per C200
This limit is enforced.
Loaded
100
instantiated
CDB types
for C300.
400 per C300
This limit is enforced.
Loaded
100
instantiated
CDB types
for UOC.
1000 per This limit is enforced. UOC
Loaded
100
instantiated
CDB types
for vUOC.
1000 per This limit is enforced. vUOC
CDB
-
-
CDB does not have an enforced instance limit. The CDB
instances
instance limit is determined by the controller user
per type
memory pool. For more information, refer to the section
C200, C200E, and C300 memory availability.
1. An instantiated CDB type has one or more instances defined against it within the CEE.
2. You can have 600 CAB instantiated types and 600 CDB instantiated types per ACE. These limits are independent of each other and these limits are both enforced.
- 72 -
5.4
5.5 5.6
Chapter 5 - CAB memory and processing load considerations
Determine CDB memory utilization
CDBs use recoverable CEE memory pool memory. A medium size CDB consumes approximately 1.5 KB of this memory. A medium size CDB is defined as containing 15 CDPs, of which two are arrays, as follows: l Five 32 character STRING l Four scalar FLOAT64 l Four scalar BOOLEAN l One 20-element FLOAT64 array l One 20-element BOOLEAN array
C200, C200E, and C300 memory availability
For C200 the CEE memory pool size is 4.2 MB. See Determine CDB configuration limits for configuration limits. For C200E and C300, the CEE memory pool size is 16 MB. See Determine CDB configuration limits for configuration limits.
Exceptional CABs
Most CABs will probably fall into the categories of small, medium, or large as described in Determine ACE memory utilization. However, CAB can support types that are much larger.
The following table displays two CABs that were created by Honeywell projects to run a pulp and paper batch digester mill on an R210 ACE. The first CAB is characterized by a large number of lines of code, and the second is characterized by a large number and size of arrays.
Lines of
code
Table 5.8 Memory Requirements for Two Exceptional CABs
Number Number of CDPs of
PRefs
CAB type size (KB)
CAB instance size (KB)
Comment
3070 116
73
440
92
Large number of code lines
489 38
28
409
412
CDPs include four, 10,000-element arrays of Float64 and twenty-one, 101-element arrays of Float64.
- 73 -
CHAPTER
6
CAB AND CDB TYPE PLANNING AND DESIGN
6.1
Control strategy
6.1.1 6.1.2
6.2
Determine that CAB and CDB are needed
You must determine if CAB and/or CDB are appropriate for your control requirements. See Purpose, use, and value of the system for help in making these decisions.
Develop strategies
Assuming you determine that CAB and/or CDB represent the most effective architecture to solve some of your control requirements, you must develop, at least at a conceptual level, the strategies that you will use to implement the solutions. We suggest that you review the example scenarios section of this guide. The example scenarios section presents a number of examples of the application of CAB and CDB to typical control scenarios. At an early stage, you will begin to formulate your strategies, including the CMs, CABs, CDBs, CDPs, PRefs, and native blocks that you will be using in each strategy. Consider organizing your CDPs and PRefs in Excel spreadsheets using the same format as the PDE forms. Then you can cut and paste your parameters from the spreadsheets directly into the PDE when you are ready to create your CABs or CDBs. The material in this type planning and design section should be viewed as an outline, or checklist, of the planning steps and design decisions that you should make prior to actual implementation of strategies involving CAB and CDB. You undoubtedly have site practices in place that address many of these items; however, CAB, CDB, and CDPs present some new features that require special consideration.
Configuration planning
6.2.1
Configuration planning steps
The following are some configuration planning considerations:
- 74 -
Chapter 6 - CAB and CDB type planning and design
l Configuration planning for CAB and CDB is similar to planning for native blocks. Because of the added functionality, however, CAB and CDB have some special planning needs.
l Plan the roles and responsibilities of users. This should address the issue of multiple developers working on the same or multiple parts of a CAB application. It should also address the responsibilities of individuals involved in deployment and monitoring of strategies that involve CABs.
l You should review your security practices with CAB in mind. See Security policy for information on security issues.
l Determine if templates can be used to reduce development effort, especially if you have multiple equipments that are similar. See Role of block types, instances, and templates for information about templates.
l With CAB, custom data and algorithm are user-defined. This increases the likelihood of "tweaking" to improve performance or reliability, or to add features. The problem of revision control of instances is therefore magnified. You will need to develop and adopt an appropriate strategy for managing types and instances.
l Your strategy for managing types and instances can take advantage of the Search tool (formerly known as the Relationship Browser) that is included in Experion. The tool is accessed from Configuration Studio. For more information, see Discover CAB dependency relationships.
6.2.2 6.2.3
6.2.4
CAB execution platform considerations
With R400, the ACE and the C300 platforms support CAB execution. The Control Builder development environment can be used to create CABs which run on ACE only, or which run on ACE and C300. However, C300 does not support all the CAB functionalities that are supported in ACE. Therefore, one of your early CAB planning steps must be to determine on which platform(s) you want to execute CAB. Refer to the section CAB/C300 special considerations to determine your execution platform.
Software development considerations
If you anticipate extensive software development for CAB algorithms, you may want to consider some of the following standards and procedures: l Software functional specifications l Standards for program internal documentation (comments) l Code peer review process l Software revision tracking using library/block names for version control l Standards and procedures for test
You will need enough detailed documentation so that the CAB can be maintained and perhaps modified or enhanced throughout its deployment life, even if there are personnel changes.
Requirements external to system
There are no special third-party software requirements. All necessary software is provided as part of Honeywell install packages. There are no physical switch settings required. You will require a license to develop CABs, and an ACE or a C300 to run CABs and CDBs. You may optionally use a C200 or a C200E controller to run CDBs. You will also require that the appropriate software development expertise is available to the project.
- 75 -
6.3
Chapter 6 - CAB and CDB type planning and design
CAB configuration choices
6.3.1 6.3.2
Define the CAB naming strategy
Determine a naming strategy that includes: l Library names l Type names l CDP names l Parameter reference alias names (the names defined in the type definitions) l Parameter reference values (the block.param assigned to alias names in instances) l Instance names l CM names
Consider using separate libraries for test types and deployed types, and include "test" as part of the test library names so as to avoid inadvertently instantiating a type that is still under test. Choose type names that include serialization or other means of supporting your versioning strategy. Use meaningful names that reflect the purpose. Use meaningful descriptions in the parameter definition "Description" fields. See the example scenarios in this guide for examples of naming.
Make CAB user interface decisions
Your CAB application planning and design should include the definition of the techniques that you will use to enable developers and operators to control and monitor the application. To the extent that it is feasible, it is appropriate to make as many of these decisions as possible early in the design so as to avoid extra edits and instance updates later in the project. Some items to consider are: l Determine the parameters that will be exposed on the faceplate. Configuring parameters on
the faceplate is easy to do in the PDE when the type is initially defined, but is more complex to do after instances have been created. See Specify symbol attributes for more information.
TIP To display parameter reference values, you must assign them to a CDP value that can be displayed on the faceplate or as a pin.
l Make decisions about when to use custom data parameters and when to use parameter references. Parameter references are recommended if the CAB is to be used as an insertion point algorithm (see Do not use graphical connections). Parameter references do not support whole array access whereas CDPs do. When using parameter references, user code should check status after the read or write operation. Parameter reference functionality supports PRef lists. This is a programmer convenience, and its use does not affect performance. Parameter references are defined as aliases in the type definition, and actual reference target names are assigned in the project side property forms of the instances. Parameter references can be enabled for dynamic re-referencing (not supported on C300), in which case you can change
- 76 -
Chapter 6 - CAB and CDB type planning and design
the target in the run-time environment, either manually or programmatically (see Support for evaluating parameter re-referencing on ACE). CDPs are connected by graphical connections (wires and parameter connectors). You can define the pins that are exposed on the block symbols when you define the type in the PDE. (There is one caveat, however-if you later edit a CAB type and change symbol attributes, these changes will not automatically propagate to instances.) You can also define these exposed pins for each instance in the block properties form.
l Consider how you will make configuration changes in the run-time environment. This is done through the block properties forms. See Properties forms specific to CAB and CDB for information on the relevant forms. Be aware that you can customize these forms in the PDE when you define the block type. You can rename tabs, define custom tabs, and organize how information is displayed on the tabs. For example, you could set up separate tabs for references to parameters in different controllers, or you could separate reads and writes on different tabs. See Specify form layout for information including a link to detailed information in the Parameter Definition Editor Reference.
l Consider how you will monitor the operation of your CAB by itself and in the overall control strategy. This could involve exposing certain critical parameters on the faceplate. It could involve displaying certain parameters on a custom schematic. In the latter case, your planning would include the resources and schedule impact of creating the schematic.
6.3.3 6.3.4
Determine the CAB algorithm and parameters
This step encompasses defining the calculations and control functions that will be implemented in the CAB program. This should include a definition of the PRef reads and writes that will be required, the CDPs that will be used by the CAB program, and the graphical connections that will be used to interface parameters on other blocks. This analysis could result in a specification for coding the CAB. This specification could, in turn, be part of an overall specification for the strategy of which the CAB is a part.
As part of the planning of the CAB program, consider any special provisions that will help during the debug process. For example, you could use local variables that capture interim calculations or status values or other internal data so that they can be easily viewed in the debugger. Similarly, you can define CDPs that could be used to display internal data on the faceplate or in the debugger. Also consider using the Send() subroutine to forward information to the message display of Experion PKSStation (see On-process debugging). Consider using SIM-ACE for debugging to take advantage of the powerful Microsoft Visual Studio debugging functionality. For more information on using SIM-ACE, see Debug with SIM-ACE.
Define execution mode
CAB execution mode can be configured as either "atomic" or "distributed"in the PDE when the CAB is defined. Distributed execution mode CABs can only execute in ACE..
CAB/ACE execution time limit
In the atomic execution mode, CAB execution time is limited to 250 milliseconds for CAB/ACE.
In the distributed execution mode, CAB execution time is not limited. Distributed execution mode is required for file I/O and history access functions. For more information, see Execution mode of CAB programs.
- 77 -
6.3.5 6.3.6 6.3.7
Chapter 6 - CAB and CDB type planning and design
CAB/C300 execution time limit
In CAB/C300, the execution time limit constraint is not based on time but on an internally maintained count of backward branches and subroutine calls. This is in contrast to CAB/ACE, where the execution time is limited to 250 milliseconds (in the atomic execution mode). For more information on CAB/C300 execution time limit, refer to Size of Looping.
Support for evaluating parameter re-referencing on ACE
Dynamic re-referencing is an option that you can configure for a parameter reference when you define the parameter reference in the PDE. Dynamic re-referencing is only supported on ACE. This option, if configured, enables the capability to change the parameter reference target in the runtime environment, either manually or programmatically. For more information on dynamic rereferencing, see Dynamic re-referencing of parameter references.
Determine Continuous Control access
You must determine whether to use Program or Continuous Control access level for each CAB. If a CAB is to be used as an insertion point algorithm, it must be configured for Continuous Control. Continuous Control is also used with legacy Honeywell control systems. For more information, see Access Lock attribute for CDPs, Access level used In PRef writes, and CAB writes with Continuous Control access level.
Data and algorithm characteristics of CAB
A CAB type represents the same concept as a "class" in modern object-oriented software terminology. Instances made from CAB types can be thought of as "objects." Within the context of Experion PKSand CEE, the user-visible entities tend to be called "block types" and"block instances" rather than "classes" and "objects." Like any class, the following two parts fundamentally characterize a CAB type: l A set of data definitions l An algorithm definition
Also, like any class, a program defines a CAB type. However, due to its integration with Experion, the program of a CAB type does not express the complete definition. In particular, you must define much of the data of a CAB type outside the source code you write for the program. There are different categories of data used within CAB types. They vary according to persistence and visibility. l Fixed definition parameters (FDPs) l Custom data parameters (CDPs) l Block scope variables l Local variables
For more detailed information on FDPs and CDPs, see Define CAB type parameters For more information on block scope variables and local variables, see Define block scope variables and Define local variables.
- 78 -
6.3.8
Chapter 6 - CAB and CDB type planning and design
Parameter references are a special case. They differ from the types listed above in that their values are not stored within the CAB. The CAB stores pointers to the actual data, which exists external to the CAB. For information on parameter references, see Define parameter references and Assign parameter references.
CAB fixed definition parameters
As with native blocks, CAB includes several predefined parameters. These FDPs are part of the CAB infrastructure. In some cases, you can supply default values when creating the type (for example, ACCESSLEVEL). In other cases, you can enter values at run time (for example, CABCOMMAND). One parameter, X_REFSTATE , is read-only. At this time, the planning phase, see Fixed definition parameters and familiarize yourself with these parameters. If possible, try to determine the default values that you will assign to: l ACCESSLEVEL--plays a part in the security of writes to parameter references l READEROPT--lets you configure event reporting on parameter read errors l WRITEERROPT--lets you configure event reporting on parameter write errors l X_EXECMODE--determines whether the CAB will execute in the atomic or distributed mode l X_PLATOPT--determines whether the CAB can run on ACE only, or on either ACE or C300 l X_REFMODE--determines the re-reference mode for PRefs that have been configured for
dynamic re-referencing l X_REFSTATE--a read-only parameter that lets you determine the state of the re-reference
function
The following FDPs can have values assigned at run time under certain conditions. If possible, plan how you will use these parameters. l CABCOMMMAND--lets you enter commands to alter the CAB state l EXCPTALM.PR--sets alarm notification priority for a CAB exception l EXCPTALM.SV--sets alarm notification severity for a CAB exception l RDERRALM.PR--sets alarm notification priority for a read error l RDERRALM.SV--sets alarm notification severity for a read error l TRMNTALM.PR--sets alarm notification priority for a CAB terminated alarm l TRMNTALM.SV--set alarms notification severity for a CAB terminated alarm l WRTERRALM.PR--sets alarm notification priority for a write error l WRTERRALM.SV--sets alarm notification severity for a write error l X_REFCOMMIT--allows you to indicate that you have completed entering new PRef targets and
that the re-reference function should begin
6.3.9
CAB states
A CAB instance can be in one of five states at any given time (see CAB instance states. The CAB transitions from one state to another in response to system events, program actions, or manual commands. The state is reflected in the CABSTATE parameter. See CABSTATE for an example of how to use the CABSTATE FDP in your program. See CABCOMMAND for an example of how you can use the CABCOMMAND FDP to alter the CAB state. For more information, see Startup and shutdown and Enumeration RestartEnum.
- 79 -
Chapter 6 - CAB and CDB type planning and design
6.3.10
CAB notifications
There are four CAB-specific notifications--all are alarms. A brief summary follows. For more detailed information, see CAB alarms.
l CAB State Terminated--Indicates that CAB execution was terminated. This alarm can have its priority and severity configured independently for each instance. You could determine these options in advance as part of your planning activity. Conditions that can cause a CAB to terminate are: o CAB execution exceeded the time allowed.
o An Out of Memory exception was detected
o A Stack Overflow exception was detected.
o ACE lost communication with the CAB client process.
o A distributed CAB instance was executing when the CEE transitioned to IDLE or the CM transitioned to InActive.
o While CABSTATE is Normal, Operator set CABCOMMAND to Quit (Distributed CAB only).
l CAB State Exception--This alarm can have its priority and severity configured independently for each instance. You could determine these options in advance as part of your planning activity.
l Read Error--This alarm is associated with parameter reference reads. This alarm can have its priority and severity configured independently for each instance. In addition, you must enable this alarm in the PDE when you define the type. It cannot be enabled in the instance. Your advanced planning should consider these options.
l Write Error--This alarm is associated with parameter reference writes. This alarm can have its priority and severity configured independently for each instance. In addition, you must enable this alarm in the PDE when you define the type. It cannot be enabled in the instance. Your advanced planning should consider these options.
6.3.11
CAB constraints
The following are constraints that you must be aware of when planning and designing your CABs:
CAB/C300 has constraints in addition to those of CAB/ACE. See section CAB/C300 special considerations for more information.
l CAB/ACE execution is constrained to 250 milliseconds in the atomic execution mode. CAB/C300 has a different execution time limit. See "CAB/C300 execution time limit." Distributed (background) execution is available (on ACE, but not on C300) and is not limited in execution time. For more information about atomic and distributed execution, see Execution mode of CAB programs. CAB/ACE infrastructure provides an FDP (CABEXECTIMER) that can be used to determine CAB/ACE execution time. CAB/ACE also provides two FDPs (CABPRFRDTIM and CABPRFWRTIM) that can be used to monitor the time outside of CAB user code consumed by processing PRef reads and writes. For further information on these CAB/ACE parameters see Use performance monitoring FDPs.
Note: CAB/C300 does not support these parameters. However, note that the EXECTIMER block can be used instead of parameter CABEXECTIMER to measure the execution time of CABs and CMs in C300, ACE and C200E.
- 80 -
Chapter 6 - CAB and CDB type planning and design
l CABs cannot use the file access features of Visual Basic in the atomic execution mode, but can use certain VB file access features in distributed execution mode (not supported on C300). For more information about file access, see Access files using CAB.
l There are certain VB functions that are not allowed. The function limiter in CAB will catch code that is not allowed and display an error message. See Supported namespaces and classes and Summary of fault handling.
l Parameter references do not support whole array access.
l Other CABs cannot share subroutines and functions without copying and pasting into each program.
l CAB does not have a data type for enumerations. You have two choices with respect to enumerations: o You can use the TYPECONVERT function block to convert parameters of type enumeration to parameters of type integer and work with the ordinal values within the CAB program. For information about the TYPECONVERT function block, see "TYPECONVERT Block" in the Control Builder Components Theory.
o You can use parameter references, which will do an implicit type conversion. See Implicit type conversion with CAB parameter references.
6.3.12
CAB API
The CAB Application Programming Interface (API) is a collection of interface elements provided by Honeywell that allows the CAB developer to access and use the functions and features of the CAB infrastructure. This interface includes classes, class members, data types, enumerations, subroutines, properties, and functions in support of FDPs, CDPs, PRefs, and custom math features. It also includes features in support of controlling and monitoring CAB initialization and execution.
Your application programmers need to become familiar with this functionality prior to beginning implementation of CABs. The CAB API is covered in the section CAB API reference of this guide, which includes examples of usage. Other examples are found throughout this guide, including the section that contains example scenarios.
6.4
Design the CAB
6.4.1
Design the usage of the CAB
CAB usage is the same as native block usage. CABs are contained in CMs and execute in a CEE in an ACE node or in a C300 controller. See "CAB overview" for more information.
Determine how your CAB will be deployed. Will it be instantiated multiple times? At the same site or different sites? Will the usage be identical in each case? Will it be similar but not identical? These criteria could influence the CAB design in terms of generality. Will you design it for one specific application, or will you design it such that it can be adapted (configured) to different equipment or process variations? Will it run as an insertion algorithm in a DataAcq or RegCtrl block (see Configure insertion points), a standalone CAB, or a process special ? (Process special is not supported in C300. For more information, refer to CM Process Special). Will the CAB execute in the atomic mode or distributed mode (required for history or file access) (see Execution mode of CAB programs)? Will the CAB use dynamic re-referencing for any parameter references? (see Dynamic re-referencing of parameter references)
Note: Distributed execution and dynamic re-referencing are not supported on C300.
- 81 -
6.4.2 6.4.3
Chapter 6 - CAB and CDB type planning and design
Determine when to use CAB
CABs are intended for situations where native function blocks do not satisfy your control requirements. This could include scenarios for developing new applications, functional enhancements to existing applications, or migration of legacy applications to Experion.
Develop a conceptual design
Your site practices will determine your methodology for this step. The following are suggestions. Develop a solid design concept, including the data content, algorithm, processing flow, and interaction with other blocks. Document the concept in sufficient detail that it can be reviewed by team members and used as a design specification. Include items such as: l Identify data that needs to be persistent and data that can be temporary (see CDP
characteristics, Define block scope variables, and Define local variables). l Determine when to use CDPs and when to use PRefs (see Make CAB user interface decisions). l List CDPs. l List PRefs and identify those that will need to have dynamic re-referencing enabled. l Define default values for FDPs where applicable. l Define values for symbol attributes (see Specify symbol attributes). l Define form layout (see Specify form layout). l Define the control algorithm(s) and outline the code that will be used for implementation.
Consider using pseudo code and/or prototyping selected routines in order to verify design concept (see Code CAB algorithm). l Develop a debug strategy (see Test and debug the CAB) and test specifications. l Develop a security policy (see Security policy) using the following suggestions:
o Identify the individuals who will have access to the CAB development tools (administrators and developers) and assign appropriate passwords.
o Identify the individuals who will have run-time access at the Engineer, Supervisor, and Operator access levels, and assign appropriate passwords.
o Plan ahead of time the access lock and access level attribute values that you will assign to individual CDPs as your CAB types are defined.
o Develop a policy regarding debug activity, especially on-process debugging. o Develop a policy for managing types and instances including requirements for testing
and distributing new or modified block types and instances.
6.4.4
Organizing CAB programs for best performance
Distributed (as opposed to atomic) execution mode (not supported in C300) is required for history and file access functions. However, any block can be configured to execute in distributed mode. Distributed execution may result in slower execution compared to the same block executing in the atomic execution mode. The degree of slowdown is dependent on the CPU loading of the ACE node. There is also a built-in delay when a distributed execution mode block requests a read or write of a parameter reference. This additional delay will not be less than one second (two base execution cycles of the ACE).
- 82 -
Chapter 6 - CAB and CDB type planning and design
A parameter reference dynamic re-reference operation (not supported in C300) requires two or more ACE base execution cycles to perform the re-reference operation for an atomic execution CAB. Four or more cycles are required for a distributed execution CAB. However, after the rereference is completed, subsequent references to the new target will be performed in the same time as for a standard reference (no added delay for atomic execution CABs, or within two cycles for distributed execution CABs.).
There are no other specific performance optimization guidelines other than the following:
l There is a performance issue to consider when deciding whether to use CDPs or PRefs. PRefs always have some performance cost, and it is even more significant if the CAB is executing in the distributed mode. Distributed CABs should use PREFLIST.READ() and PREFLIST.WRITE() if there is more than one PRef to read or write. Each read or write incurs the minimum two base cycle delay.
l Another performance issue to consider is when pushing data to a CAB using Value Custom Data Parameters of String or Time Data Types. In some cases, this can cause an increase in memory usage on the ACE which may result in an overrun when the system tries to reclaim this memory. This issue has been identified where the CAB is placed in a DORMANT state, when it no longer processes data being pushed to it. If such memory increases related to running CABs occur, you can limit this usage by using Parameter References instead of Value Custom Data Parameters. Using Parameter References allow you to control when data is being fetched and prevents the increase in memory in those conditions where the block is DORMANT.
l The number of PRef writes that a C200, C200E, or C300 controller can accept is limited to by its Push / Store Request Capacity. For example, if CAB PRef writes are directed to a traditional C300, the performance is limited to 50 parameters per sec. Please see specifications corresponding to the specific type of target controller.
l When using atomic execution mode CABs, avoid loops that can cause CAB execution to time out (see Execution mode of CAB programs).
l When using distributed execution mode CABs (supported only on ACE), avoid coding loops that do not include a means of preemption (relinquishment of the processor), such as I/O calls. Such loops can monopolize the processor and cause system degradation (see Execution mode of CAB programs).
l Use on-node references in preference to off-node references wherever possible. l Use whole array access instead of individual element access (CDPs only) unless you only need
a small number of elements. l For memory-intensive or processor-intensive routines executed in CAB/ACE, you can use
distributed execution mode to allow CAB execution to exceed 250 milliseconds. Distributed execution mode CABs can run only on ACE. l Assign the order of execution of CMs, and blocks within CMs, keeping in mind the logical flow of data within your control application. l You can use standard Windows performance monitoring tools to monitor performance and memory utilization (see " Configuring the Local Security Policy").
TIP
When using Distributed CAB, ensure that you have programmatically released all system resources, such as with a "try....finally" syntax, before exiting the block. Failure to release system resources could render the system resource inaccessible by other CABs.
For example, if one CAB opens a file and leaves that file in an open state, then other CABs will not be able to access that file. In this scenario, you would use the "try...finally" syntax. In the "finally" clause, any file opened should be closed. The "finally" clause is guaranteed to execute when the "try" clause exits. See Use of file IO in CAB for a code example.
- 83 -
6.4.5 6.4.6 6.4.7 6.4.8
Chapter 6 - CAB and CDB type planning and design
Differences between CAB/ACE and CAB/C300 performance
Application engineers must consider the following facts when measuring the performance of CAB algorithms.
l Dissimilarity of CAB/C300 and CAB/ACE performance. CAB/ACE and CAB/C300 use different run-time implementations and run on different CPUs. Although the two variants can be used for implementing the same algorithms, performance characteristics of those algorithms on their respective platforms are completely different.
l Dissimilarity of C300 and SIM-C300 performance. CAB running on C300v2/v3, C300 v5 and on SIM-C300 use different CPUs. Although the same algorithm can be executed on both platforms using the same run-time implementation, the performance characteristics of the algorithms on the two platforms are different.
Determine CAB/ACE memory usage
CAB instances require memory from the block of memory reserved within ACE for instances. In addition, unlike native blocks, they also require memory that is taken from the general .NET memory pool. If you anticipate significant CAB and native block utilization, you should do an ACE memory analysis. See Determine ACE memory utilization" for details about how to perform this analysis.
Determine CAB/C300 memory usage
For information about CAB/C300 memory usage and related topics, refer to Determine C300 memory utilization and Memory fragmentation in CAB/C300"
Determine shutdown horizon for ACE
As CAB types and instances are created, modified, and deleted, ACE memory that is required for type definition storage grows. This memory is not reclaimed even when all instances of a type are deleted. Eventually, it may be necessary do an ACE shutdown and restart in order to claim this unused memory. See Determine ACE shutdown horizon"for information about this potential requirement.
Determine the CAB distribution policy
This policy will depend on the characteristics of your plant or company, including such items as the number of sites and their geographical distribution, and your in-house Microsoft Visual Studio development expertise. You can choose to have your CAB applications developed by Honeywell or a third party, and use the import and export features for distribution of instances. In this case, you would not require a developer license unless you wanted the ability to make modifications to the programs. If you have in-house development capability, you can develop your CAB applications at a central location and use the import and export features for distribution. Your distribution policy should include a strategy for managing versions of types and instances. Take advantage of the ability to name libraries, types, and instances. Consider using serialization as part of names.
- 84 -
Chapter 6 - CAB and CDB type planning and design
6.5
CDB configuration choices
6.5.1
6.5.2 6.5.3
Define the CDB naming strategy
Determine a naming strategy that includes: l Library names l Type names l CDP names l Instance names l CM names
Consider using separate libraries for test types and deployed types, and include "test" as part of the test library names so as to avoid inadvertently instantiating a type that is still under test. Choose type names that include serialization or other means of supporting your versioning strategy. Use meaningful names that reflect the purpose. Use meaningful descriptions in the parameter definition "Description" fields. See the example scenarios in this guide for examples of naming.
Determine where the CDB will execute
You can choose to have your CDB run on an ACE node, or on a C200, C200E, or C300 controller. If you want your CDB data to be close to the blocks that are reading and writing the data, and those blocks run on a controller, you may want to consider running the CDB in a controller. Be aware, however, that the instance limits are smaller in the controllers. Refer to Determine CDB configuration limits to determine these limits.
Make CDB user interface decisions
Your CDB application planning and design should include the definition of the techniques that you will use to enable developers and operators to control and monitor the application. To the extent that it is feasible, it is appropriate to make as many of these decisions as possible early in the design so as to avoid extra edits and instance updates later in the project. Some items to consider are: l Define the CDPs that will be configured in your CDB before you begin definition of the type. l Determine the parameters that will be exposed on the faceplate. Configuring parameters on
the faceplate is easy in the PDE when the type is initially defined, but more complex after instances have been created (see Specify symbol attributes). l CDPs are connected by graphical connections (wires and parameter connectors). It is convenient to define the pins that are exposed on the block symbols when the type is created in the PDE. Otherwise, you will need to do this in the property form for each instance. (There is one caveat, however. If you later edit a CDB type and change symbol attributes, these changes will not automatically propagate to instances.)
- 85 -
Chapter 6 - CAB and CDB type planning and design
l Consider how you will make configuration changes in the run-time environment. This is done through the block properties forms (see Properties forms specific to CAB and CDB). Be aware that you can customize these forms in the PDE when you define the block type. You can rename tabs, define custom tabs, and organize how information is displayed on the tabs. See Specify form layout for information including a link to information in the Parameter Definition Editor Reference.
6.5.4 6.5.5 6.5.6
Data characteristics of CDB
There are two categories of data used within CDB types: l Fixed definition parameters (FDPs) l Custom data parameters (CDPs)
For more information on FDPs and CDPs, see Define CDB type parameters.
CDB fixed definition parameters
As with native blocks and CABs, CDB includes a number of predefined parameters. These FDPs are part of the infrastructure of the CDB. None of these CDB FDPs can be configured with default values. Therefore, there is no Fixed tab in the PDE (where default values are normally configured), and therefore a preliminary planning step is not needed to determine default values. For information on these FDPs, see Fixed definition parameters in CDBs.
CDB constraints
CDBs have the following constraints: l CDBs do not support parameter references. l CDBs do not support a control algorithm. l CDB does not have a data type for enumerations. You can use the TYPECONVERT function
block to convert parameters of type enumeration to parameters of type integer and work with the ordinal values.
6.6
Design the CDB
6.6.1
Design the usage of the CDB
CDB usage is the same as native block usage. CDBs are contained in CMs and execute in a CEE in an ACE node or in a C200, C200E, or C300 controller. See CDB overview for more information.
Determine how your CDB will be deployed. Will it be instantiated multiple times? At the same site or different sites? Will the usage be identical in each case? Will it be similar but not identical? These criteria could influence the CDB design in terms of generality. Will you design it for one specific application, or will you design it such that it can be adapted (configured) to different equipment or process variations?
- 86 -
6.6.2 6.6.3
Chapter 6 - CAB and CDB type planning and design
Determine when to use CDB
CDBs are intended for use in situations where native function blocks do not satisfy your control requirements. This could include scenarios for developing new applications, functional enhancements to existing applications, or migration of legacy applications to Experion. You do not require the CAB development license for CDB development. While CDBs will often be used in conjunction with CABs, this is not a requirement. CDBs can be used for generic data storage in applications that do not involve CABs. See the example A CDB to hold sensor data. See Why use CDB? for more information about CDB usage.
Define the CDB distribution policy
This policy will depend on the characteristics of your plant or company, including such items as the number of sites and their geographical distribution. Your distribution policy should include a strategy for managing versions of types and instances. Take advantage of the ability to name libraries, types, and instances. Consider using serialization as part of names.
- 87 -
CHAPTER
7
CAB AND CDB INSTALLATION AND UPGRADE
7.1 7.2
7.2.1
7.2.2 7.2.3
Hardware installation and upgrade
For hardware requirements, refer to the Software Change Notice (SCN) and/or the Specifications and Technical Data (Spec and Tech) that is applicable to the release.
Software installation and upgrade
For detailed information about installation and upgrade, refer to the System Installation and Upgrade Guide (SIUG) and the Software Change Notice (SCN). CAB/C300 licensing is similar to CAB/ACE licensing. Refer to CAB/C300 Licensing for more information.
Licensing considerations
CAB has a two-tiered licensing scheme that is based on the Client/Developer style of licensing. The two licenses that make up CAB licensing are CAB Developer and ACE Base. The CAB Developer license allows users to build programs using Microsoft Visual Studio 2017 and Control Builder integrated with CAB tools. The users will create custom programs using Microsoft Visual Basic .Net. The developed CAB types can be run on ACE CEEs throughout a site and even in other plants without the necessity of purchasing a special license.
CAB Developer license
The CAB Developer license allows users to develop and compile Visual Basic programs for use with the ACE CEE via CAB tools, Control Builder, and Visual Studio 2017. The user can add CAB function blocks to projects and attach programs to them. The CAB Developer license does not allow users to load CAB function blocks to the CEE Monitor environment. ACE Base and Control Builder allow users to add CAB function blocks to the CEE Monitor environment. CAB Developer is only allowed to be installed on Experion PKSStations. It is not allowed on Experion server nodes.
ACE Base license
The ACE Base license and package, which is included with ACE, allows users to load CAB instances to ACE environments, but they cannot edit CAB types or create new CAB types without a CAB Developer license. The ACE Base allows a user to import CAB types/libraries and CMs containing CAB function blocks.
- 88 -
7.2.4
Chapter 7 - CAB and CDB installation and upgrade
Possible licensing scenarios
l Purchase at least one CAB Developer license per major unit of a plant along with as many ACE nodes that are required for systems to run programs.
l Purchase one CAB Developer license per site with as many ACE nodes required to run the CAB programs.
l Purchase only ACE nodes and subcontract CAB development work to Honeywell or third parties.
7.2.5
Interoperability between R410 and R400, R3xx systems
There are specific rules for migrating strategies from R3xx and R400 to R410 and using strategies built in in ACE R3xx and R400 controllers. In general, strategies that contain CAB and CDB that have been migrated to the current release of Experion PKScan be loaded to the ACE of a previous release.
The following rules should be considered when migrating to, or developing in R410.
l If you migrate a strategy that includes CAB/CDB from an R3xx and R400 system to R410 and you do not edit the CAB, that strategy will still load and operate on R3xx and R400 ACE controllers.
l Once you edit and then compile an R3xx and R400 CAB type using the R410 CAB Developer and do a SAVE over existing instances, that CAB instantiated type is now only loadable and operable on an R410 ACE controller. You will receive an error when attempting to load an R410 CAB into an R3xx or R400 ACE. If you want to load the R3xx and R400 CAB into an R3xx and R400 ACE respectively, you will need to re-import the strategy and CAB type from your R3xx and R400 exports. If someone wants to run a CAB on R3xx, R400, and R410, they will need to edit and do a SAVEAS as a different CAB type on the R410 system to load to an R410 ACE while keeping the R3xx and R400 CAB type to run on an R3xx and R400 ACE.
l Once you edit a CDB on an R410 Control Builder, you can still load to an R3xx or R400 ACE.
l New CAB types created using the R410 CAB Developer are only loadable and operable on an R410 ACE controller. You will receive an error when attempting to load an R410 CAB into an R3xx or R400 ACE.
l New CDB types created with R410 Control Builder can still be loaded to R3xx or R400 ACE.
7.2.6
Interoperability of ACE controllers with CAB types running on different .NET versions
With R410 and R430, backward compatibility is supported. You can create and build CAB types to run on R400 if the Build Legacy Version of CAB is selected on the Build menu. In this case, the CAB type is built with both .Net 4.0 and .Net 2.0. The .Net 2.0 version loads to the previous R400 release.
R310 CAB types running on R311/R400/R410 ACE controller
Microsoft .Net provides backward compatibility by enabling previous versions of programs to run in new versions of the .Net Framework, if features of the previous versions are still supported. As a result of the changes in the Framework, the following may not work properly:
l CAB blocks that use XML Schemas.
- 89 -
Chapter 7 - CAB and CDB installation and upgrade
To ensure that the above works properly, you must execute an instance of the CAB type on an R311/R400/R410 SIM-ACE or rebuild the CAB types on an R311/R400/R410 Experion PKSclient to verify that all features are still supported.
Supported CAB Types and ACE platform scenarios
In R410, R430 and R511, there is a possibility of having different versions of .Net running on ACE controllers. Further, you can have CAB types that are built with different versions of .Net framework. Whether these CAB types load to the ACE depends on the .Net combination. The different variables are:
l R310 ACE controllers running on .Net 1.1 framework l R311 ACE controllers running on .Net 2.0, 3.0, and 3.5 framework l R400 ACE controllers running on .Net 2.0, 3.0, and 3.5 framework l R430,R431,R500,R501 and R510 ACE controllers running on .Net 2.0,3.0,3.5 and 4.0(R310) l CAB type last saved with Visual Studio .Net 2003 (.Net 1.1 framework) (R310) l CAB type last saved with Visual Studio 2008 (.Net 2.0 framework) (R311.2 and R400) l CAB type last saved with Visual Studio 2008 including legacy compile (.Net 1.1 and 2.0
framework) (R311.2 only) l CAB type last saved with Visual Studio 2010 (.Net 4.0 framework) (R410) l CAB type last saved with Visual Studio 2010 including legacy compile (.Net 4.0 and 2.0
framework) (R410 only) l CAB type last saved with Visual Studio 2012(.Net 4.0 framework) (R430) l CAB type last saved with Visual Studio 2012 including legacy compile (.Net 4.0 and 2.0
framework) (R430 only) l CAB type last saved with Visual Studio 2012(.Net 4.0 framework) (R430, R431, R500, R501,
R510) l CAB types last saved with Visual Studio 2017 (.Net 4.6.2 framework) (R511 onwards)
CAB Types built with .Net 2.0 run on ACE controllers running either .Net 2.0 or .Net 4.0 framework, except in cases where CAB blocks use XML schemas. See R310 types running on R311 ACE controller. However, CAB types built with .Net 4.0 will run only on ACE controllers running at least .Net 4.0 framework but not on an ACE running .Net 2.0. By default, CAB Types built with Visual Studio .Net 2008 are built with .Net 2.0 framework and CAB Types built with Visual Studio 2010 are built with .Net 4.0 framework. A key feature supported in R311 is the provision of a post build step in Visual Studio 2008 that will also build the CAB type with the .Net 1.1 framework to provide support for ACE controllers that are still on a R310 release. This post build step is not supported in R410 because .Net 1.1 is not installed on the R410 systems. However in R410 R430 ,R431, R500, R501 R510, a post build step in Visual Studio 2010/Visual Studio 2012 respectively is supported that will build the CAB type with the .Net 2.0 framework to provide support for ACE controllers that are still on R400. At load time, the version of the software running in the controller is determined and the CAB type that matches that version will be loaded. If a version compatible with the software running on the controller does not exist, an error message is displayed and the load will not be completed normally.
- 90 -
Chapter 7 - CAB and CDB installation and upgrade TIP For example, if you are trying to load a CAB type to an ACE, which is running a different version of the .Net Framework, the following error will be displayed on loading: The CAB block <Name of CAB block> is not compatible with the supported .Net version of ACE.
The following table displays the different combinations of .Net framework versions and whether they are supported on the different ACE platforms. To edit an existing CAB type built with Visual Studio .Net 2008, Visual Studio .Net 2003 and Visual studio 2010, you must use the migration wizard to convert the CAB type to the Visual Studio 2017 format. For more details, see Converting CAB types created from previous releases of Visual Studio to Visual Studio 2017 format.
- 91 -
CHAPTER
8
CAB CONFIGURATION
8.1
Create a new CAB type
8.1.1
CAB development environment overview
The CAB development environment is launched from the Control Builder application running on an Experion Station. The development environment provided by Honeywell for CAB creation is called the Integrated Development Environment (IDE). This environment integrates the following features into CB:
l Support for creation of new types for CABs, and for adding these new types to the CB library. l Support for instantiating the new types into CMs, and for loading them into the CEE. l A customized version of Microsoft Visual Studio 2012 for creating CAB algorithms. l A customized version of Microsoft Visual Studio 2017 for creating CAB algorithms. l The Honeywell PDE for configuring custom data parameters for CABs and CDBs and
parameter references for CABs. For CABs, this application opens within Microsoft Visual Studio as a tab-selectable option.
8.1.2
Layout of the development environment
When you open the IDE from Control Builder to create a new CAB type, you specify the library and block names. Then, the Microsoft Development Environment launches with the Honeywell Parameter Definition Editor tab selected, as shown in the following figure.
Note that in the IDE there are two tab-selected options available:
l Parameter Definition Editor--Where the parameters for your CAB are configured. This window is selected in the figure above. When you open the IDE for creation of a new CAB type, the PDE tab is active by default.
l CABlock.vb--Where the algorithm for your CAB is configured. When you open the IDE for edit of an existing CAB type, the CABlock.vb tab is active by default.
When you select the CABlock.vb tab, or if you are opening an existing CAB type for edit, the Source Code window appears as shown in the following figure.
If you are creating a new CAB, the source code window contains a framework of Honeywellsupplied code with no executable statements . It is in this framework that you will insert the code for your algorithm. Above figure shows how the source code window appears when you open it for creation of a new CAB type. If you were editing an existing CAB type, the window would contain your previously entered code.
- 92 -
8.1.3
8.1.4 8.1.5
Chapter 8 - CAB configuration
The CABlock.vb tab is shown in above figure as it appears when opening the window for creation of a new CAB. After the each build, a Globally Unique Identifier (GUID) is appended to the label as shown in the following figure. The GUID is used to ensure that each CAB type is globally unique across the system, independent of the library and type name. The GUID from the type is propagated to each instance and therefore ensures that an instance can be matched to its type, even if it is exported to another system where another CAB exists with the same library/type name but different algorithm.
Opening the CAB Source Code window
Microsoft Visual Studio 2017 has a Close box on the tab instead of the window. This might result in the users accidentally closing the CABlock.vb Source Code window. In such a scenario, perform the following steps to re-open the CABlock.vb Source Code window. 1. If CAB View is selected, choose View- > CAB View to uncheck it. 2. If the Solution Explorer window is not open, choose View- > Solution Explorer to open it. 3. In the Solution Explorer window, expand CABlockproject if it is not expanded. 4. Double-click the CABlock.vb in the tree.
Note: The CABlock.vb can be of a format CABlock-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.vb where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is a unique GUID. 5. After the CAB Source Code window has re-opened, choose View- > CAB Viewto revert to CAB View. Ensure that the CAB View is selected.
Opening the Parameter Definition Editor window
Microsoft Visual Studio 2017 has a Close box on the tab instead of the window. This might result in the users accidentally closing the Parameter Definition Editor window. In such a scenario, perform the following step to re-open the Parameter Definition Editor window.
l Choose File- > Open- > Parameter Definition Editor.
Honeywell additions to Microsoft Visual Studio
In order to support CAB development, Honeywell has provided customized features within Microsoft Visual Studio. Some of these are: l The PDE is integrated into Microsoft Visual Studio. l Microsoft Visual Studio starts in a mode in which certain advanced features are not displayed.
These are features that are not required for CAB development. This makes the environment friendlier for developers who are not power users of Microsoft Visual Studio. l Special classes were added to support CDPs and parameter references. The use of Microsoft IntelliSense will aid in typing CDP and PRef names and supporting properties. l Reliability features were added such as code validation checks. l Code was added to support saving data to the ERDB.
8.1.6
Honeywell files
CAB infrastructure includes many critical files provided by Honeywell. Do not modify or delete any
- 93 -
Chapter 8 - CAB configuration
files under either of the following locations: C:\Program Files (x86)\Honeywell\Experion PKS\Engineering Tools\CAB\ C:\Program Files (x86)\Honeywell\Experion PKS\Engineering Tools\CAB\Include
8.1.7
Microsoft Visual Studio resources
Many of the standard features of Microsoft Visual Studio 2017 and VB.NET are available to you in the Development Environment. These include certain libraries, objects, properties, methods, debugging tools, and the IntelliSense coding aid. Honeywell includes the features that are appropriate for the creation and editing of CABs that will run in the current ACE run-time environment. Features that are not required are not included.
8.1.8 8.1.9
Microsoft Visual Studio Offline Help
By default Visual studio launches help in web browser. To enable offline help in visual studio below settings needs to be done.
1. Open Help Menu. 2. Select "Set Help Preferences" and then Select "Launch in Help Viewer". 3. This sets the help preferences to launch offline help.
Then Open the help using "Help -> View Help" option , this launches Visual studio Help in Help Viewer.
Microsoft Visual Studio build directories
When you are creating or editing a CAB type, Microsoft Visual Studio keeps your project files in a build directory. When you save the type to ERDB and exit Microsoft Visual Studio, the project files are automatically deleted. This is the normal scenario. However, in unusual cases such as an unexpected error from the CAB build time, the project files may not be deleted. If this occurs, CAB infrastructure moves the files to a backup directory and notifies the user of the path to the new location so that the project can be re-created if desired. If for some reason an error occurs while the files are being moved, an error message notifies the user of the failure and the location of the files.
The path to the build directory is:
C:\Users\<userid>\AppData\Roaming\Honeywell\Experion PKS\Engineering Tools\cab\build\<GUID>
The path to the backup directory is:
C:\Users\<userid>\AppData\Roaming\Honeywell\Experion PKS\Engineering Tools\cab\build\/Saved/<GUID>
8.1.10
CAB configuration procedures
The following topics cover the steps involved in configuring a CAB type.
- 94 -
Chapter 8 - CAB configuration
l Open a new CAB type for edit l Define data and algorithm l Build the solution l Save the solution l Save-Renew command l Block type locking flags l Interactions with the ERDB database lock feature l Close the development environment
8.1.11
Open a new CAB type for edit
To create a new CAB type, click File > New > Type > Custom Algorithm Block in the Control Builder application to open the Integrated Development Environment. In the dialog box that appears as shown in the following figure, you specify the Custom Library Name (either by typing the new name or selecting an existing name from a drop-down list) and the name of the new block (CAB) type.
Figure 8.1 Specify Library and CAB Names
Rules for library and block type names are as follows: l Maximum character count for library and block type name is 40 each. l Name must include at least one underscore or alpha character. l All alpha characters, all numeric characters, and the underscore character are legal-all other
characters are illegal.
TIP If you plan to include the block name as part of the instance name(s), be aware that instance name requirements are the same as library and block name requirements as indicated above, except that instance names are limited to 15 characters. Default instance names are assigned as follows (for a block type name "xxx."):
l First instance = "xxxA" l Second instance = "xxxA_1" l Third instance = "xxxA_2"
- 95 -
Chapter 8 - CAB configuration
8.1.12
After specifying the Custom Library Name and the Block Type Name, click OK. The data entered is checked to ensure that only valid characters were entered and that the maximum character count was not exceeded. If the data is valid, the IDE opens with the Parameter Definition Editor window selected as previously shown in the above figure.
Define data and algorithm
You enter your custom data parameters and parameter references in the PDE window (see Define CAB type parameters).
You type your code for your control algorithm in the Source Code window, previously shown in Figure 2 (see Code CAB algorithm).
8.1.13
Build the solution
After data and code have been entered, you build the block type. You may need to invoke build multiple times until all build errors have been eliminated. After all build errors have been eliminated, you save the block type to the ERDB. You do this by invoking the "Save To ERDB" command that is made available within Microsoft Visual Studio. Save operations are covered in Save the solution.
You are not required to eliminate all build errors before saving to ERDB. ERDB serves as the permanent storage for all CAB types, whether they are complete and ready for use or whether they are under a prolonged period of edit. If a block type is saved to ERDB before it has been successfully built, it can still be used to make instances. However, before a CAB type is successfully built, its Incomplete Lock parameter is set. Instances of such a type cannot be loaded to a CEE. CB will report an error on any attempt to do so. For more information on the Incomplete Lock parameter, see Block type locking flags.
The following table shows the build command menu and toolbar button options, and the toolbar button that can be used to cancel a build in process.
File menu Toolbar
option
button
Table 8.1 Build Commands Action
Build Solution
Saves all project files to local storage, and then builds (compiles) the project.
N/A
Cancels a build option that is in progress. The button is inactive
(Grayed) when a build is not in progress.
8.1.14
Save the solution
With regard to storage of project files, developing a CAB in Microsoft Visual Studio under CB is different than you are probably used to if you have developed other projects under Microsoft Visual Studio in the past. With CAB, project files are kept in the ERDB, which is advantageous for several reasons. ERDB storage takes advantage of redundancy (if present), and the SQL Server backup and restores operations in effect for ERDB. It also avoids any confusion that might occur if multiple copies of a project exist. Local storage is used during a CAB edit session, but when the session is complete and you close Microsoft Visual Studio without saving to the ERDB, you will be prompted to save changes (if you have made any). This save operation is to the ERDB. If you decline, all changes made will be lost, because all local project files are deleted when Microsoft Visual Studio closes.
- 96 -
Chapter 8 - CAB configuration
Note that the fully qualified name for a CAB type consists of the concatenation of the library name and the block type name. This means that different types that are assigned different library names can use the same block type name. For example, suppose a CAB type called "VLR_CALC" is assigned to a library called "USER_UTILS." There is nothing to prevent a new block type called "VLR_CALC" from being assigned to a library called "USER_ALGOS."
The following table lists the types of saves that are available.
File menu Toolbar option button
Table 8.2 Types of Saves for CAB Action
Save PDE Data
Save-
N/A
Renew
PDE Data
Save
N/A
CABlock.vb
Save
N/A
CABlock.vb
As
Save All N/A
Save to ERDB
Save to N/A ERDB As
Saves the PDE data to local storage. This option is only available if you have made changes to PDE data. Note: You must save any PDE changes prior to developing code in order to have the changes recognized in IntelliSense.
Do not use this command unless prompted to do so (see Save-Renew command)
Saves program files to local storage. NOTE: This function saves data to a temporary development location for troubleshooting/diagnostic purposes. Use Save to ERDB or Save to ERDB As for normal development work.
Saves program files to local storage. Allows you to save another copy of the current program files under a different name. NOTE: This function saves data to a temporary development location for troubleshooting/diagnostic purposes. Use Save to ERDB or Save to ERDB As for normal development work.
Saves all project files to local storage. NOTE: This function saves project file data to a temporary development location for troubleshooting/diagnostic purposes. Use Save to ERDB or Save to ERDB As for normal development work. Save All does save the PDE data.
Saves all project files to the ERDB. IMPORTANT: If you are using the QVCS versioning system, refer to the topic QVCS support for Custom Algorithm Block for important information. There are certain situations where a Save operation is not allowed and a Save As operation is required (see Situations that require a Save As operation for a modified CAB)
Allows you to save another copy of the current block. You will be prompted for the desired Library and Block names. If you keep the same Library name, you must enter a different Block name. If you choose a new Library name, the Block name can be the same as, or different from, the name of the original block. After the save operation, the block under edit in Microsoft Visual Studio will be the new version.
8.1.15
Save-Renew command
Both CDPs and the PRefs parameters are identified within the system by the parameter identification numbers that are invisible to users. Under certain unusual conditions, it may become necessary for the system to regenerate these identification numbers in order to continue with the current operation. If this occurs, you will be notified by an error message that indicates that you need to execute the Save-Renew command. This command requires that you select a new name for the block that you are saving. If you execute the Save-Renew command, the parameter identification numbers within the system are regenerated.
- 97 -
Chapter 8 - CAB configuration
A consequence of the Save-Renew command is that you must reload all instances of the block. Alternatively, you can cancel the operation that you were doing when the error message indicating the need for Save-Renew was shown.
8.1.16
Block type locking flags
CAB types include two FDPs-EDITLOCK and INCOMPLETE. They are used internally to prevent certain potential errors from occurring during the CAB development process (edit phase). These parameters are shown as Edit Lock and Incomplete Flag on the Main tab of the block properties form. The following figure shows a partial view of the properties form where those flags appear.
Figure 8.2 CAB Type Locking Flags
8.1.17
EDITLOCK--The Edit Lock flag is supported by all CAB types. When blank, it indicates that the type is available for edit. When not blank, it contains the machine name and user name of the person who is editing the type. Edit Lock prevents a type from becoming corrupted by simultaneous edits. It is automatically set when the type is opened for edit, and is automatically cleared when the edit session ends.
When Edit Lock is set, the type can still be opened view-only by using the "View" command. Attempts to save to the ERDB will not work when the type has been opened view-only. Block instances can be created or loaded regardless of the state of Edit Lock.
Edit Lock gives no indication of the edit state between edit sessions. In order to prevent others from modifying your type when it is not open for edit, there must be a site practice for honoring reservations. To handle coordination of CAB types under development, a recommended procedure is to include a term such as "development" or "test" as a part of the name of a Custom Library to differentiate it from deployed libraries.
In the unlikely event that a PC crashes during an edit session, Edit Lock will be set. If this happens, the ERDB administration tool, DBAdmin, must be used to clear Edit Lock. For information, see "Using DBADMIN" in the Control Hardware Troubleshooting and Maintenance Guide.
INCOMPLETE--The Incomplete Lock flag is supported by all CAB types. When True (selected), it indicates an inconsistency between the parameter definitions established within PDE and the algorithm definition established within VB.NET source files. Parameter definitions have been added or changed since the last successful build. To clear the lock, you must successfully rebuild.
CAB types can be instantiated when Incomplete Lock is set (although there is no reason to do so), but they cannot be loaded.
You can view the value of Incomplete Lock, as previously shown in the above figure, by opening the block properties form and selecting the Main tab.
Interactions with the ERDB database lock feature
Database locks are a standard feature in most databases and used in the ERDB. Their purpose is to lock a database item when it is opened so that another user cannot attempt to edit the same item. Any attempt to modify a database item when it is locked will generate an error. There is a potential for this to occur any time you open a CAB or CDB type for creation or editing, or save a CAB or CDB to ERDB. These operations cause a change in the value of the Edit Lock flag, a database resident parameter.
- 98 -
Chapter 8 - CAB configuration
8.1.18
8.2
The system performs a check prior to setting or resetting the Edit Lock flag to ensure that the database is not locked. For example, assume that you have a project chart open containing an instance of a CAB type. A database lock is set for that CAB type (and for every other block type instantiated in the chart). If you attempt to open the CAB type for edit, or save it if it is already open, a warning will appear stating that the chart must be closed before the CAB or CDB can be opened or saved, because the open or save operation attempts to change the Edit Lock flag.
Another potential conflict is the case where you are editing a CAB or CDB type, and someone else opens a chart that contains an instance of that CAB or CDB type. If you try to save the CAB or CDB type, you will get an error because the database record for that CAB or CDB type is locked. The error message will indicate who has it locked and will give you the option to cancel, or to continue the operation, which will leave the Edit Lock set.
Close the development environment
After the block type has been saved to ERDB, you can close Microsoft Visual Studio if you believe that block type editing is complete. Alternatively, you can leave Microsoft Visual Studio open for debugging. In most cases, you will probably leave Microsoft Visual Studio open after first creating a new block type to support a cycle of instantiation, test and modification. Remember to save the PDE any time that you change its data so that IntelliSense will recognize the changes.
If you attempt to close Microsoft Visual Studio and you have a CAB type open for edit, you will get the dialog shown in the following figure.
If you select Discard, your changes will be lost. It is important to emphasize that source files saved within the development folder (local storage) are used as a temporary cache in support of edit and build sessions. They are not maintained after an edit session has ended. When an edit session is complete and Microsoft Visual Studio is closed, ERDB is the only storage resource for all data related to block types. "Save To ERDB" can be done at any time during the Microsoft Visual Studio edit session to preserve work done so far.
If you attempt to close Control Builder when you have a CAB type open for edit, you will get the error message shown in the following figure.
Define CAB type parameters
8.2.1
Custom Data Parameter purpose
As the name implies, CDB types support custom data parameters. CDPs as supported within CDB types are equivalent to the CDPs supported on CAB types.
Custom data parameters (CDPs) are parameters (variables) that you define. They are part of the overall definition, or configuration, of your CDB. CDPs are visible within the PKS as a whole. They are "public" in that any agent that has access to the PKS name space can read them. Similarly, CDPs can be written by any PKS agent subject to store access checks specified by you when you design the block. Thus, they represent an effective vehicle for exchanging custom data throughout the PKS.
CDB types are useful in a wide variety of applications. They can be used to hold data that is shared by multiple block instances within a CM or across multiple CMs. They can be used in conjunction with both native blocks and CABs. They can be used as a more self-documenting alternative to flags, flag arrays, numerics, and numeric arrays.
8.2.2
CDP characteristics
Some characteristics of CDPs are:
- 99 -
8.2.3 8.2.4
Chapter 8 - CAB configuration
l CDPs are directly analogous to the parameters of native CEE block types. However, the name, data type, access lock, and other properties, are not predefined. You specify them during the process of defining the block type. Attributes that can be specified for CDPs are described in "Reviewing custom parameters tab (Value CDPs)" in the Parameter Definition Editor Reference. Data types are described in Data types for CDPs and parameter references.
l CDP values are persistent in the sense that they are maintained from creation until deletion of the block instance. Their values are retained from one execution of the block to the next.
l The data types available for the CAB CDPs are the same as those available for CDB CDPs.
l CDP values can be changed by writes from within the block or from external blocks or other agents within the Experion.
l CDPs can be viewed from several different displays within the PKS. CDP values can be configured in the CAB properties form using the CB project side instance if their Configuration load attributes were configured as LOAD in the PDE. CDP values can be read and written on process from the CAB properties form using the CB monitor side instance. Values can be read and written using chart visualization from the Experion PKSStation. They can also be read and written from custom displays.
l CDPs can be defined as array parameters. The maximum number of elements that can be supported by a CDP array is 10,000 elements. This limit is enforced by PDE.
One difference between native block parameters and CDPs is that the native block parameters are only visible from outside of the block while the CDPs are visible from both inside of and outside of the block. To illustrate this, suppose that you decide to create a CDP called "FLOW" on a block type called "CONTROLLER." Then you make an instance of CONTROLLER called "CONTROLLER1" within a CM instance called "CM1." Then, the CDP called "FLOW" can be accessed externally under the name "CM1.CONTROLLER1.FLOW." In addition, it can be accessed internally by the CAB program under the name "FLOW.Value."
Define custom data parameters
CDP definitions are entered in the Value CDPs tab of the PDE. This form is selected by clicking the Value CDPstab of the PDE as shown in the following figure.
A portion of he Value CDPs configuration form (tab) is shown in the following figure.
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference.The following link leads to information about Value CDP information.
For information about...
Customizing the Value CDPs view (set of attributes that are displayed)
In the PDE Reference, see... Reviewing PDE views for CAB and CDB
Specifying CDP attributes
Reviewing custom parameters tab (Value CDPs)
It is strongly recommended that you avoid using VB reserved names in parameter definitions. You can search VB on-line help for "Visual Basic keywords."
Validity checks based on CDP attributes
Some of the CDP attributes that you configure are used to condition whether or not the CDB instance will accept writes from external agents. This is true for these attributes:
- 100 -
8.2.5
Chapter 8 - CAB configuration
l Access Lock l Minimum Value l Maximum Value l Dimension 1 Array Element Count l Dimension 1 Array Lower Bound l Dimension 2 Array Element Count l Dimension 2 Array Lower Bound
It is important to understand that these validity checks are done in accordance with the Data Owner Principle. Thus, the CDB instance is considered the owner of all its CDP data. Writes to its CDPs from external agents (such as blocks and displays) are accepted only if they do not violate the validity checks.
For validity checks of Maximum Value and Minimum Value, the special behaviors that follow are supported for CDPs of floating point type.
l Writes of NaN are always accepted. l Writes of non-NaN values are compared to the limits. For programmatic writes, out-of-range
values are never rejected but are clamped instead. For human-initiated writes, out-of-range writes are rejected and an error message is issued indicating that a limit or range was exceeded. l A write of +INF or -INF will be accepted unless a finite limit is set, in which case the value that is stored is clamped at the limit. For human-initiated writes, out-of-range writes are rejected and an error message is issued indicating that a limit or range was exceeded.
There are no validity checks of Maximum Value and Minimum Value for whole-array writes to a CDP of any type. For a write to a single element of an array, the same Maximum Value and Minimum Value validity checks are made as for a write to a scalar CDP of the same type.
A store to any parameter type other than floating point will be rejected if the value is outside the Maximum Value and Minimum Value limits. A store to a parameter of type floating point will clamp the value at the upper/lower limit and allow the store.
Access Lock attribute for CDPs
Attributes that can be specified as part of a CDP definition are described in the previous topic. One of these is Access Lock. The access lock of a CDP determines which external agents can initiate stores to the parameter. External agents are identified by an Access Level identifier that is sent with every write request.
The following table lists external agents that can attempt stores to CDPs and the access level that identifies them. An "X" in a cell indicates that the operation is allowed. Note that for some external agents, the access level can be one of several values, depending on circumstances. In the case of CAB instances, the access level will be either Program or Continuous Control depending on the value of fixed definition parameter ACCESSLEVEL which is configured on the Fixed tab in PDE. In the case of human initiated stores from CB monitoring displays or Station displays, the access level will be Engineer, Supervisor or Operator depending on privileges associated with the user ID.
Access Locks are configured for each CDP on the Value CDPs tab in the PDE when the block is created.
- 101 -
8.2.6
Chapter 8 - CAB configuration
Table 8.3 Access levels in Experion
External agent attempting Access level
store
Application
developer
Program Continuous Engineer Supervisor Operator control
Control Builder during X load of CM or SCM
Supervisory batch
X
application
SCM
X
CAB instance
X
X
Supervisory control
X
application
Algorithm function block
X
Human being storing from CB monitoring display
X
X
X
Human being storing from Station display
X
X
X
The following table lists possible values for CDP Access Lock and their meanings. Each cell indicates whether stores with the indicated Access Level will be accepted by a CDP that has been assigned the indicated Access Lock.
Access lock Access Level
Table 8.4 Access locks for CDPs
Application developer
Program Continuous control
Engineer Supervisor Operator
View Only No
No
No
No
No
No
AppDevOnly Yes
No
No
No
No
No
Program
Yes
Yes
Yes
No
No
No
Engineer Yes
Yes
Yes
Yes
No
No
Supervisor Yes
Yes
Yes
Yes
Yes
No
Operator Yes
Yes
Yes
Yes
Yes
Yes
As an example of how to interpret the above tables, consider a CDP defined with Access Lock = Engineer. Suppose a human being with engineering privileges is logged on and using a Station display. This user can store to the CDP. Users logged with only Supervisor or Operator privileges and using the same display cannot store to the CDP. Supervisory Batch or Continuous Control applications can store to the CDP, as can any CEE function blocks that have the capability to initiate stores.
Fixed definition parameter purpose
CDB types support fixed definition parameters (FDPs). These are parameters that are defined by the system in order to provide services essential to every CDB. Some FDPs are for internal use only and are of no concern to users. Others are known to users and are used either at the time of block type creation, block instantiation or both.
- 102 -
8.2.7 8.2.8 8.2.9
Chapter 8 - CAB configuration
Define values for fixed definition parameters
FDP configuration values (default values only) are entered in the Fixed configuration form of the PDE. This form is selected by clicking the Fixed tab of the PDE as shown in the following figure.
Figure 8.3 Fixed (FDP) Tab style="width:400px;height:31px;"/> A portion of the FDP configuration form is shown in the following figure.
Figure 8.4 FDP Configuration Form style="width:400px;height:110px;"/>
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about FDPs.
For information about... Configuring the default values for FDPs
In the PDE Reference, see... Reviewing Fixed Parameters tab
If you are configuring a CAB that will be used as an insertion point algorithm, you must configure the ACCESSLEVEL parameter as Continuous Control.
Define CAB execution time limit
CABs that execute on ACE can execute in either the atomic mode or the distributed mode. CABs that execute on C300 can execute only in the atomic mode.In atomic mode, CAB execution on ACE is constrained to one ACE base execution cycle (250 milliseconds).
In distributed mode (ACE only), CAB execution is permitted to exceed the 250-millisecond ACE base execution cycle. Distributed execution is required by the file access and history access functions, but CAB designers can use this functionality for other applications where extended execution time is required. The CAB API includes the Wait() subroutine, which can be used in CABs configured for distributed execution to insert a specified time delay in the CAB algorithm execution (see Subroutine Wait()).
In CAB/C300, the execution time limit constraint is not based on time but on an internally maintained count of backward branches and subroutine calls. This is in contrast to CAB/ACE, where the execution time is limited to 250 milliseconds (in the atomic execution mode).For more information on CAB/C300 execution time limit, refer to Size of Looping.
Execution mode is determined by the X_EXECMODE FDP and is configured in the PDE on the Fixed tab as shown in the following figure. You cannot change this parameter value in a CAB instance (see Execution mode of CAB programs).
Define re-reference mode
With dynamic re-referencing of parameter references, you must configure the value for the X_ REFMODE parameter, which determines the execution mode that CAB will use for all parameter re-references. The available values, AUTO or MANUAL, are configured in the PDE on the Fixed tab as shown in the following figure. You cannot change this parameter value in a CAB instance.
For more information about dynamic re-referencing, see Dynamic re-referencing of parameter references. For more information about the X_REFMODE parameter and the associated functionality, see Configuring the X_REFMODE parameter.
- 103 -
Chapter 8 - CAB configuration
8.2.10
8.2.11 8.2.12
Define parameter references
Parameters that reside in the System Repository (SR) cannot be accessed from CAB programs. CB will allow a parameter reference to refer to an SR-resident parameter, but the run-time will not allow access to the parameter. If in doubt about a given parameter, you can check its residency as follows:
Parameter references are configured on the Parameter References configuration form of the PDE, which is selected by clicking the Parameter References tab as shown in the following figure.
The following figure shows a part of the Parameter References configuration form. To configure individual parameter references for dynamic re-referencing, select the Dynamic Reference checkbox. See Dynamic re-referencing of parameter references for more information.
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about parameter references.
For information about... Configuring parameter references
In the PDE Reference, see... Reviewing Parameter References tab
The attributes specified for parameter references at type creation time guide built-in behavior of the type at instance configuration time and at run time. They are not available to user-written code. Attributes available to user code include "<PRef-name>.Value," "<PRef-name>.ReadStatus," "<PRef-name>.WriteStatus," and others (see Parameter reference classes).
Assign parameter references
Specific external references are assigned to the block instance on the block properties form with the Parameter Reference tab selected as shown in the following figure. You can access this form in the project or monitor tree view by double-clicking on the function block. You can assign values on the project side but you must do a load to reflect them on the monitor side. You can view parameter reference assigned values on the monitor side, but you cannot change them unless they are configured for dynamic re-referencing (see Dynamic re-referencing of parameter references).
Specify symbol attributes
As part of the CAB type definition, the Symbol Attributes tab on the PDE allows you to define attributes for the block symbol that appears within project and monitor control charts. By default, the symbol exposes CABSTATE and CABCOMMAND, which, if left as the default, would display on the monitor faceplate along with the block instance name and the block template or type name.
As part of the type definition, you can elect do the following:
l Expose any CDP as a connectable pin. l Expose any CDP value on the face of the symbol.
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about symbol attributes.
For information about... Configuring symbol attributes
In the PDE Reference, see... Reviewing Symbol Attributes tab
- 104 -
Chapter 8 - CAB configuration
8.2.13 8.2.14
Any changes you later make to symbol attributes will not propagate to existing CAB instances if you choose a Save and answer Yes when prompted to update instances. There are two ways to change Symbol Attributes in existing instances. Symbol Attribute changes must be done for each instance by deleting and re-adding the block to the CM, or making the change in the block properties form on the project side and then loading to update the monitor side.
Specify form layout
As part of the CAB type definition, the Form Layout tab of the PDE allows you to specify aspects of the layout of the block properties form. In most cases this is unnecessary as the default form layout will be adequate. In some cases, you might want to change the way the form appears during instance building or during chart visualization in on-process displays. Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about form layout.
For information about... Defining the layout of the properties form
In the PDE Reference see... Reviewing Form Layout tab
Form entry steps
CDB parameters and attributes are configured in the PDE forms. Descriptions and references for these parameters and attributes are covered in this guide. Information about using the PDE is covered in the Parameter Definition Editor Reference.
One PDE feature that can be especially useful is the ability to cut, copy, and paste parameters. If your block contains multiple parameters that are similar, you can copy a parameter and paste it into multiple lines. In this case, the PDE renames each parameter, so you may want to change the names to suit your preference. You can also copy parameters and paste them into a separate block that is open for edit. In this case, the PDE will not change the names. To use this PDE feature, right-click a line in the PDE as shown in the following figure.
Figure 8.5 Access Cut, Copy, and Paste Options
8.2.15
Fixed definition parameters
Each CAB type supports an identical set of FDPs. FDPs of interest to the end user are described in this section. FDPs that are only relevant for internal system implementation are not covered. The FDPs that are covered here are grouped into two categories:
- 105 -
Chapter 8 - CAB configuration
8.2.16 8.2.17
l FDPs that are common with native blocks l FDPs that are specific to CAB (and in some cases, CDB)
FDPs common with native blocks
The following table summarizes CAB and CDB FDPs that are common with native block types. The definitions of these parameters cannot be modified as part of CAB or CDB type definition.
Table 8.5 Summary of FDPs Common with Native Blocks
Parameter name
Description
BLCKCOMMENT1 Holds descriptive information that can be entered by the user.
BLCKCOMMENT2 Holds descriptive information that can be entered by the user.
BLCKCOMMENT3 Holds descriptive information that can be entered by the user.
BLCKCOMMENT4 Holds descriptive information that can be entered by the user.
CREATEDBY
Identifies the user who did the first save of the instance or template.
DATECREATED Gives the date of the first save of the instance or template.
DESC
Descriptive text appearing within configuration form and on alarm summary display.
EUDESC
Descriptive text typically used to describe engineering units of the block.
MODIFIEDBY
Identifies the user who did the most recent save of the instance or template.
ORDERINCM
Integer value that determines execution order of CAB instance within parent CM.
FDPs specific to CAB
The following table summarizes CAB FDPs that are not common with native blocks. Note that for most of these parameters, the definitions are fixed. There are some for which the instance default can be changed at type creation time.
The parameters with an asterisk have special methods that allow them to be accessed within the same CAB (see Base class). The parameter names are links to the parameter definitions in the Control Builder Parameter Reference.
Table 8.6 Summary of CAB FDPs Not Common with Native Blocks
Parameter name
Summary description
Modification of
definition
User Write access for instance
ACCESSLEVEL
Specifies access level with which CAB programs store to parameter references.
CE can assign instance default at type creation time.
View only.
BLOCKTYPEID CABCOMMAND1
Holds an identifier unique to each CAB or CDB Definition
type.
fixed.
Command parameter for CABSTATE.
Definition
View only. Operator can
- 106 -
Chapter 8 - CAB configuration
Parameter name
Summary description
Modification of
definition
User Write access for instance
fixed.
assign certain values under certain circumstances.
CABEXECTIMER
Contains the time in microseconds required during the last execute cycle to run the user's CAB code. For distributed CABs it will show the amount of time the distributed CAB has been running in negative seconds until it is complete then it shows total run-time in microseconds. This parameter is not supported in CAB/C300. If you attempt to use it, a NaN value is returned by the C300.
Definition fixed.
CABPREFRDTIM
Contains the total time in microseconds spent Definition outside of CAB user code processing PRef read fixed. requests during the current execute cycle. This parameter is not supported in CAB/C300. If you attempt to use it, a NaN value is returned by the C300.
CABPREFWRTIM
Contains the total time in microseconds spent Definition
outside of CAB user code processing PRef
fixed.
write requests during the current execute
cycle. This parameter is not supported in
CAB/C300. If you attempt to use it, a NaN value
is returned by the C300.
CABSOFTVER CABSTATE1
Contains the version of the CAB software that Definition was used to build the user's CAB program. This fixed. parameter is not supported in CAB/C300. If you attempt to use it, a null value is returned by the C300.
Operating state of CAB instance.
Definition fixed.
DOTNETVER[ ]
A one or two element array that contains the Definition version of .NET framework that was used to fixed. build the user's CAB program. This parameter is not supported in CAB/C300. If you attempt to use it, a null value is returned by the C300.
EDITLOCK
Prevents simultaneous type edits by holding identifier of CE and machine doing current edit. EDITLOCK also pertains to CDB.
Definition fixed.
EXCPTALM.PR
Sets the alarm notification priority for a CAB exception.
Definition fixed
EXCPTALM.SV
Sets the alarm notification severity for a CAB Definition
exception.
fixed
EXCPTNLINENM
Publishes the source file name and source
Definition
line number of the function executing on the fixed.
last exception incurred by CAB program. NOTE:
The source file and line number are only
View Only.
View Only.
View Only.
View only.
View only. View only.
View only. Engineer can assign values. Engineer can assign values. View only.
- 107 -
Chapter 8 - CAB configuration
Parameter name
Summary description
Modification of
definition
available when the CAB is built using the Debug Configuration of Visual Studio. If the Release Configuration is used, only the function name is shown. This parameter is not supported in CAB/C300. If you attempt to use it, a blank value is returned by the C300.
User Write access for instance
EXCPTNMODULE Publishes the name of the function executing on the last exception incurred by CAB program. This parameter is not supported in CAB/C300. If you attempt to use it, a blank value is returned by the C300.
Definition fixed.
View Only.
EXCPTNMSG
Publishes descriptive information on the last Definition View only.
exception incurred by CAB program.
fixed.
EXCPTNTYPE
Publishes type of last exception incurred by CAB program.
Definition View only. fixed.
INCOMPLETE
Indicates whether type is in consistent build state.
Definition View only. fixed.
INSMASTER
Indicates whether or not this block is being used for insertion point processing.
Definition fixed.
View only. The value is set to the name of the master block when the block is configured for insertion point processing.
OSVER PERIOD1
Contains the version of the operating system that was executing when the user's CAB program was created.
Definition fixed.
Provides the value of the PERIOD parameter of the parent CM of the CAB instance. Units are in seconds. NOTE - PERIOD appears in a CAB program like an FDP even though it is not a fixed definition parameter in the truest sense of an FDP definition. It is only available to the user code.
Definition fixed.
View only. View only.
PROCSPECEXEC
1
Provides the current value of the BPS parameter of the CAB instance's parent CM. It is intended only to provide information to the block about how it was started. NOTE PROCSPECEXEC appears in a CAB program like an FDP even though it is not a fixed definition parameter in the truest sense of an FDP definition. It is only available to the user code. This parameter is not supported in CAB/C300. If you attempt to use it, a false value is returned by the C300.
Definition fixed.
PROGSTSDESC1 Optionally publishes last error identified by CAB program.
Definition fixed.
Engineers can read/write from a CAB program even though writing this parameter has no effect on the block execution.
Engineers can read/write from a CAB
- 108 -
Chapter 8 - CAB configuration
Parameter name
Summary description
Modification of
definition
User Write access for instance
program.
RDERRALM.PR
Sets the alarm notification priority for a read Definition Engineer can
error.
fixed.
assign values.
RDERRALM.SV
Sets the alarm notification severity for a read Definition Engineer can
error.
fixed.
assign values.
READERROPT
Allows for design of CAB types that report an event in response to read errors.
CE can assign instance default at type creation time.
View only.
READSTATUS
Shows whether error occurred during read of Definition View only.
inputs on last execution cycle.
fixed.
SRCDATA[0]
Parameter that holds a copy of the CAB source Definition View only.
code.
fixed.
TRMNTALM.PR
Sets the alarm notification priority for a CAB terminated alarm.
Definition Engineer can
fixed.
assign values.
TRMNTALM.SV
Sets the alarm notification severity for a CAB Definition Engineer can
terminated alarm.
fixed.
assign values.
WRITEERROPT
Allows for design of CAB types that report an event in response to write errors.
CE can assign instance default at type creation time.
View only.
WRITESTATUS
Shows whether error occurred during write of Definition View only.
outputs on previous execution cycle.
fixed.
WRTERRALM.PR Sets the alarm notification priority for a write Definition Engineer can
error.
fixed.
assign values.
WRTERRALM.SV Sets the alarm notification severity for a write Definition Engineer can
error.
fixed.
assign values.
X_CC3MINREQV
Provides the minimum version of CAB/C300 run-time that can host the CAB type. This parameter is not supported in CAB/ACE. If you attempt to use it, zero is returned by the ACE.
Definition fixed
View only
X_EXECMODE
Determines whether the CAB executes in atomic mode or distributed mode. Distributed mode is not supported in CAB/C300. This parameter returns ATOMIC in C300.
CE can assign instance default at type creation time.
View only.
X_PLATOPT
Configuration option that allows the CAB type CE can designer to specify a CAB type that supports assign
View only
- 109 -
Chapter 8 - CAB configuration
8.2.18
Parameter name
Summary description
Modification of
definition
execution on either ACE only or ACE and C300. instance default at type creation time.
User Write access for instance
X_REFCOMMIT
Operator writes"COMMIT" to X_REFCOMMIT to Definition signal completion of entering new references fixed. for PRefs if the X_REFMODE is"MANUAL," initiating the change of the PRef references to new targets. Since CAB/C300 does not support dynamic re-referencing, this parameter has no meaning for CAB/C300. If read from C300, returns zero.
Engineer can assign values.
X_REFMODE
Determines if the re-reference mode is "MANUAL" or "AUTO." Since CAB/C300 does not support dynamic re-referencing, this parameter has no meaning for CAB/C300. If read from C300, returns zero.
CE can assign instance default at type creation time.
View only.
BLOCKTYPNAME Specifies the user-defined text name for the CAB type. This includes both the library name and the block type name itself.
Definition Fixed
View Only
X_BRANCHLIM
Controls branching and subroutine calling within a CAB/C300 type to prevent uncontrolled looping or uncontrolled recursion from damaging operation of the host C300 controller. This does not apply to CAB/ACE. Always returns zero from ACE.
CE can assign instance default at type creation time.
View Only
X_REFSTATE
Gives an indication of whether or not any dynamic re-referencing operations are currently being performed. Since CAB/C300 does not support dynamic re-referencing, this parameter has no meaning for CAB/C300. If read from C300, returns zero..
Definition fixed.
View only.
1. This parameter can be accessed by a CAB program.
Detailed description of CAB specific FDPs
Detailed descriptions are found in the Control Builder Parameter Reference. You can access them by clicking on the parameter name in FDPs specific to CAB. The following comments apply to the descriptions in the Control Builder Parameter Reference.
l Default is the default value assigned to the instance when it is first configured in a CM. l When an FDP has Access Lock "ViewOnly" it means that the parameter value cannot be written
at type creation time, at instance configuration time, or at any other occasion when working with an instance.
- 110 -
Chapter 8 - CAB configuration
8.2.19 8.2.20
8.2.21
l When an FDP has Access Lock "Type Definition Only" it means that PDE can be used to modify the instance default of the parameter at the time the type is created. The parameter value cannot be written at instance configuration time or at any other occasion when working with an instance.
Save parameter definitions
After completing configuration steps in the PDE, you must save the parameter definitions with the Save command. The PDE will remain open after the Save operation. You must close the PDE to end the edit session. For more information see Types of saves for CDB.
Limitations on number of CAB parameters
There is a limit to how many parameters a CAB can have. CDPs, FDPs, and parameter references all contribute to a total that is constrained as displayed in the following table. Note that the limits on user-defined parameters are somewhat different for CAB/ACE and CAB/C300.
Table 8.7 Configuration Limits for CAB Types and Instances
Parameter type
Max limit
Comment
FDPs
200
User-defined
28001
parameters, CAB/ACE
FDPs are defined by Honeywell and are not available for definition by users, although users can read them and write to some of them. Approximately 50 are currently used and 150 more are reserved for future use.
l CDPs count as one user-defined parameter.
l PRefs count as two user-defined parameters.
User-defined
15001,2
parameters, CAB/C300
l CDPs count as one user-defined parameter.
l PRefs count as two user-defined parameters.
1. Array parameters count as one parameter no matter how many elements they have. Also, see the topic CABs with large numbers of parameters.
1. While the overall CAB limit of 2800 user-defined parameters is enforced by Control Builder, the CAB/C300 limit of 1500 is not directly enforced. This limit occurs as a result of the memory required for the CAB program within the runtime environment. A larger number may be achievable depending upon the size of the CAB algorithm.
CABs with large numbers of parameters
Atomic execution mode CABs with large numbers of parameters may time out and terminate on first execution when executing on ACE (does not apply to CABs executing on C300).
There is a potential for atomic execution CABs with large numbers of parameters to terminate due to timeout when first executed on the ACE platform. This is because of the JIT (Just In Time) compilation functionality of .NET. When a CAB is first executed, there is a compilation overhead that is not present on subsequent executions. This can be handled in many ways:
- 111 -
Chapter 8 - CAB configuration
8.3
l If acceptable in your situation, restart the CAB. Subsequent executions should not time out. l Consider distributed mode execution. l Structure your atomic program such that parameter access is distributed over two or more
executions, with no more than 1500 parameters accessed in any execution. This could be done by grouping parameter accesses in separate subroutines that are executed in different cycles. l Limit the number of parameters. Honeywell tests have shown that Parameter References count as 2 parameters, or 750 PRefs and 1500 CDPs are a safe number for the current platform and release.
Code CAB algorithm
8.3.1
Overview
When the source code window opens, it contains a code frame with no executable statements as follows:
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() 'TODO: User should insert their Execute code here End Sub End Class
You can enter the following kinds of statements in the code frame: · Declarations of block scope variables are entered below declaration of class CAB and above the line "Public Overrides Sub Execute()." · Declarations of local variables are entered within subroutine Execute(). · Executable statements are entered within subroutine Execute() where the "TODO" comment is. · Private subroutines and functions are entered within the CAB class declaration, above or below the declaration of Execute(). Subroutines can be added outside the class definition, but if you do, you will not have access to all of the data that is inherited from the original class. Depending on the subroutine, this might not be a problem. Although parameter definitions and executable code are entered into different windows, there is interplay between the two. The PDE definitions ultimately yield support code that allows parameters to be used as variables within the Execute() subroutine. You do not need to provide definitions other than those entered within PDE. However, you must save parameter definitions before parameter names will be recognized within executable code. Entering a complete type definition is typically an iterative process in which you shift back and forth between PDE and the algorithm source window.
In your code, you must remember to add .Value to a CDP or parameter reference when accessing its value--for example, accessing Me.FLOW.Value. If you forget the .Value, you will get a build error similar to the following (this example is for a CDP that is Float64). .Value: Value of type `Double' cannot be converted to .Value: Value of type `Double' cannot be converted to Honeywell.CAB.BlockMap.Float64CDP For a parameter reference, the error message would be similar to the following (this example is for a PRef that is Float64). Honeywell.CAB.BlockMap.Float64PRef'
- 112 -
8.3.2 8.3.3 8.3.4
Chapter 8 - CAB configuration
Define block scope variables
Block scope variables are like CDPs in that they are persistent and retained across block executions. They differ in that they are not visible within the namespace of the Experion PKSand not checkpointed. Thus, they never "appear" on the "surface" of the block.
Since block scope variables are visible only within the CAB program, you determine their use when you create the CAB type. You might decide never to use block scope variables. Or, you might use them for holding internal state, for doing pre-computations that render several CDP values into a single value, or for other reasons.
Microsoft VB.NET establishes the rules for definition and manipulation of block scope variables. Generally, these variables are defined within the CAB program at the scope of the VB.NET class that defines the block type.
Block scope variables can be declared as either private or public. Either way, they cannot be accessed through the standard data access methods of the PKS.
In the terminology of VB.NET, block scope variables are "instance variables" of the class that defines the block. For an example of block scope variables, see Define the algorithm for VLR_CALC.
Define local variables
Local variables are similar to block scope variables in that they are visible only within the context of the CAB program. They differ in that their values are not retained from one block execution to the next. Their values are retained only during of execution of the subroutine or function where they are declared.
Local variables are declared within Execute(), which is described in the next topic. They can also be declared within custom subroutines and functions created by the CE. Microsoft VB.NET establishes the rules for definition and manipulation of local variables. For examples of local variables, see Define the algorithm for VLR_CALC.
Algorithm definition - Execute()
The single subroutine, Execute(), is known to the wider CEE environment. It forms the usersupplied interface for all CABs and is called whenever the containing CEE is in Run and the parent CM is Active.
All algorithmic content of the block consists of VB.NET statements that are either explicitly contained within Execute() or that are contained within custom subprograms called by Execute(). Execute() handles code that is intended to run continuously as well as initialization code that is intended to run only under special conditions.
Execute() can read and write CDPs, block scope variables, and local variables as needed. It can make reference to parameters owned by other block instances through the use of CAB parameter references. It can send messages and make use of other CEE-specific APIs. It can make use of a wide variety of built-in functions supported by VB.NET.
Execute() can call programmer-defined functions and subroutines as appropriate. However, functions and subroutines are always local to the CAB type. CAB does not support functions and subroutines that are shared across CAB types.
Execute() can have its execution triggered by the parent CM in the same manner as any other component block within the CM. In this scenario, the CAB's order of execution with respect to other component blocks is determined by its ORDERINCM parameter.
- 113 -
8.3.5 8.3.6
Chapter 8 - CAB configuration
Alternatively, CABs can have their execution controlled by one of the other component blocks within the parent CM. This would be the treatment used when a CAB is to serve as an insertion point algorithm. In this case, the partner component block, a PID for instance, would be configured to call the CAB at an appropriate point in its execution, while the CAB's parent CM would be configured to not call the CAB at all. Execute() runs when the CAB is instantiated within a CM, and the CM is scheduled to execute, or the CM is executed by a Block Process Special (BPS) command issued to the CM. CM process special is a configuration option that allows a trigger parameter to be set at run-time on the CM, causing any pre-fetch requests to be issued and the subsequent execution to be scheduled.
Avoid the use of recursion
Do not attempt recursive programming for your process control applications. Recursion is an advanced programming technique in which a code routine calls itself. It is not an appropriate technique for CAB programs because it can cause malfunctions if used improperly. In CAB/C300, recursion errors can lead to termination of the CAB instance(without impact to the C300 as a whole). In CAB/ACE, recursion errors can cause failure of the entire ACE or SIM-ACE because of a stack overflow condition. Three examples of recursion are: l Calling the Execute() subroutine from anywhere in the CAB code. l Calling subroutine MySub() from within subroutine MySub(). l Calling subroutine Sub1() which calls subroutine Sub2() which calls subroutine Sub1(). This is
sometimes called "mutual recursion."
The CAB build-time software has checks to prevent cases 1 and 2 above, but not case 3. Use SIM-ACE with Visual Studio to do extensive branch coverage debug tests to find recursion before on-process deployment.
Execution mode of CAB programs
TIP Distributed execution is not supported for CABs that have X_PLATOPT set to ACEANDC300.
CABs can be configured to execute in either the atomic execution mode or the distributed execution mode. The execution of a CAB is initiated by the CEE based on the execution period that is configured for CAB's CM container module (the period is the amount of time between two consecutive executions of the module). When the Execute() function of a CAB program starts, it runs to completion. This is true whether the CAB is configured for atomic or for distributed execution. In the atomic execution mode, CAB/ACE execution is constrained to 250 milliseconds (one-half of the ACE base execution cycle). However, CAB/C300 execution is constrained to using a different mechanism, not based on time. Instead, it is based on an internally maintained count of backward branches and subroutine calls. For more information, refer to Size of Looping. In the distributed execution mode (CAB.ACE only), the CAB executes in a process that is different from the ACE base execution process, and its execution time is not limited. Distributed mode execution is required for CABs that perform file I/O or Experion PKShistory access, but can be configured for any CAB when extended execution is required. CAB programs that are to be used as insertion point algorithms cannot execute in the distributed mode. These CABs must be configured for atomic execution (see Characteristics of distributed mode execution).
- 114 -
Chapter 8 - CAB configuration
During execution, a CAB is never interrupted by data access requests from outside the block. This is true in either atomic or distributed execution mode. This feature means that programmers who write CAB programs can do so without concern that the CAB's own data (CDPs) might be read or written by an external agent while their values are under computation and not ready for use.
In either atomic or distributed execution, values that are changed during execution are not updated for access by external agents until the block execution completes. For an atomic execution CAB, values that are manually or programmatically changed by external agents storing to the block while the block is executing are used by the block at its next execution. For a distributed execution CAB, values that are manually or programmatically changed by external agents storing to the block while the block is executing are cached for the next execution cycle. However, these cached values will be overwritten by any changes to the same parameters made as a result of block execution. Changes made to block parameters when the distributed block is not executing will be used by the block at its next execution.
The Wait() subroutine can be used in distributed mode CAB algorithms. This subroutine allows you to introduce a specified time delay in the execution of the CAB algorithm. See Subroutine Wait() for more information.
Long-running iterative calculations can, in principle, be supported within an atomic execution paradigm. This could be done by carefully tracking state data and by using counters or explicit state variables to direct looping activity. State variables could be used to determine when loops must be exited to avoid overruns, and how to reenter loops once the computation resumed. But this sort of approach is cumbersome. Distributed execution is probably a better choice as special programming is not required, other than preserving data integrity as described in the previous paragraph.
The following table summarizes the characteristics of atomic and distributed execution modes.
Table 8.8 Atomic and Distributed Execution Mode Comparison
Function
Atomic Distributed
Algorithm execution
Algorithm execution (Execute() subroutine) must complete within 250 ms of X an ACE base execution cycle).
Algorithm execution is allowed to span multiple ACE base execution cycles--
X
there is no execution time limit.
Algorithm execution is never interrupted by data access requests from outside the block.
X
X
Algorithm executes in the ace.exe process.
X
Algorithm executes in the cabclient.exe process.
X
A CAB with a large number of parameters may time out and terminate on X first execution.
Functionality
Can use Experion PKSHistory functions.
X
Can use certain VB file access features.
X
Can use the Wait() subroutine provided by the CAB API.
X
Can be used as a native block's insertion point algorithm.
X
CDP values
CDP values that are changed during execution are not updated for access X
X
by external agents until the block execution completes.
- 115 -
8.3.7
Chapter 8 - CAB configuration
Function
Atomic Distributed
CDP values that are changed by external agents storing to the block while X the block is executing will be used by the block at its next execution.
CDP values that are changed by external agents storing to the block while
X
the block is executing are cached for the next execution cycle. However,
these cached values will be overwritten by any changes to the same
parameters made as a result of block execution.
Parameter references
Algorithm execution stops and waits for the ACE to process parameter
X
reference reads and writes.
Two or more ACE base execution cycles are required to perform a parameter X reference dynamic re-reference operation.
Four or more ACE base execution cycles are required to perform a
X
parameter reference dynamic re-reference operation.
CABSTATE
CEE transition to IDLE causes CABSTATE to transition to TERMINATED.
X
CM transition to INACTIVE causes CABSTATE to transition to TERMINATED.
X
CABSTATE can be set to QUIT by an Operator, causing CABSTATE to
X
transition to TERMINATED.
CABSTATE can be set to QUIT programmatically or by the CAB run-time,
X
X
causing CABSTATE to transition to TERMINATED.
Characteristics of distributed mode execution
CABs created for distributed execution are essentially the same as CABs created for atomic execution, but are not restricted to the 250 ms time limit for the execute method. CAB distributed execution does not require any special coding by the CAB user.
Any CAB type created for atomic execution can also be made to execute in distributed mode by rebuilding the type and selecting distributed mode execution. However, there are additional features allowed in distributed execution that do require specific coding to select them, such as file I/O and history data access.
There are also some CAB features that will be slowed when executing distributed, such as parameter reference reads of on-node parameters. This slowdown should not be an issue because the block can execute as long as required without being stopped by the system.
There are no guarantees that a distributed CAB will run every cycle that the CM is scheduled. There are inherent delays due to the distributed CAB running in a lower priority process.
Creating and configuring instances of distributed mode CAB types in CMs does not require any special actions. The CAB types are dropped into the CM just as atomic mode blocks are. However, distributed CAB types cannot be configured as insertion point algorithms. When a CAB type built for distributed execution is instantiated in a CM, it will execute in the distributed process (cabclient.exe) as opposed to the ACE base process (ace.exe) when loaded to the ACE.
The general characteristics of CABs executing in the distributed mode are:
- 116 -
8.3.8
Chapter 8 - CAB configuration
l If the distributed block is not currently executing, the CEE initiates execution of the block based on the frequency configured for the container CM. If the block is executing at the next scheduled CM execution, the CEE will not take any action with respect to the executing distributed block.
l The current CDP values at the start of the block execution (the call to the Execute method) are copied to the distributed process so that the block has up-to-date values (a synchronization action). Only values modified since the last execute are sent to the block.
l The block does not see changes to CDP values from external sources while it executes. If an operator stores a new value to a CDP, the value is held in the ACE process and not propagated to the distributed process until the next Execute request sent to the block. Refer to the previous topic, Execution mode of CAB programs, for information about the behavior when the block's algorithm and an external agent attempt to change the same CDP.
l Stores to CDPs on the block by the block's algorithm code do not get propagated to the ACE process until the current Execute method exits. The operator (or another block) will not see the intermediate CDP values during execution. Only the final value stored by the code prior to exiting the Execute method are visible.
l Parameter Reference ("PRef") reads from off-node sources are made available by the CEE using either subscription or pre-fetching, as is done for atomic CABs.
l PRef writes to off-node are post-stored by the CEE at the end of the current execution cycle.
l PRef read/write requests to on-node parameters are performed when requested.
l If a block that is executing in the distributed execution process encounters a need for an ACE service, such as a PRef read or write, the block stops execution and waits for ACE to process the request. The processing of these requests is done at the end of the ACE base execution cycle (500 milliseconds) as long as there is sufficient time left in the current cycle. If the time remaining is insufficient, processing is deferred until the next cycle that has sufficient time. After ACE has processed the request, the data and/or status is returned to the distributed execution process and execution of the block resumes. Since this process introduces delays for each request, you can improve performance by including multiple PRefs in a single request (PRefList).
l The block can perform re-referencing of PRefs. Any delays imposed by re-referencing for atomic blocks will also apply to distributed blocks.
l A currently executing distributed execution mode CAB will be terminated if the parent CM is inactivated while the CAB is executing or if the CEE is set to IDLE.
CAB programs in sequence control applications
CAB programs are not used as sequence programs in the sense of SCMs or in the sense of prior Honeywell offerings such as SOPL/MFC, CL/MFC or CL/PM. Sequence block types or sequence programs are designed with built-in preemption mechanisms that accommodate the wait operations prevalent in sequence control. CAB programs offer no such inherent support.
In principle, a CAB program could be used to affect some level of sequence control. This could be done by explicitly managing state within the program design so that "steps" could be exited and reentered with each call to Execute(). In general though, this would be a time consuming design so CAB would not generally be used to drive sequence control within CEE. SCMs would be used instead.
However, SCMs can work with CAB instances to augment their own function. There several different ways that this can be accomplished:
l A CM containing a CAB can be triggered to do a process special execution by an SCM.
l A CAB can be written to alter its execution pattern in response to one or more values of its own CDPs. A partner SCM can be implemented to write the CAB CDPs to trigger different kinds of processing.
- 117 -
Chapter 8 - CAB configuration
l A CAB program can be written to alter its execution pattern in response to one or more PRef values read from a partner SCM.
l A CAB instance can be configured to operate as an insertion program triggered by a native block (the call master). Any changes of state an SCM might apply to the call master would likely impact execution of the CAB program. For example, if the call master is a PID, SCM writes to MODE would stop or start execution of the insertion program.
It is also true that CAB instances can initiate communications that impact execution of other CAB instances or SCMs.
l In general, any affect that an SCM can have on a CAB instance can also be triggered by a different CAB instance. Thus, a CAB could trigger the process special function for a CAB contained in a different CM, it could use CDPs and PRefs to affect the execution pattern of another CAB, or it could write to parameters like MODE that would impact the execution of a CAB insertion program.
l CAB instances can impact the execution of SCMs in the same way that SCMs impact the execution of other SCMs through writes to the SCM COMMAND parameter.
l A CAB can control the execution of another CAB in a different CM. A CAB can use a Boolean parameter called Block Process Special (BPS) on a CM to cause the CM to run once as a process special. Refer to CB documentation for more information.
l Another technique whereby a CAB can control the execution of another CAB is by activating and inactivating the host CM of the CAB to be controlled. This can be done by writing a zero (inactivate) or one (activate) to the CM's EXECSTATE parameter. As an example, a CAB (CAB1) can monitor an event and activate the CM in which another CAB (CAB2) resides. CAB2 can do the processing for the event, and can then inactivate its own CM at the end of the special processing.
8.3.9
PRef as data alias within CAB program
CAB programs read and write data on other blocks through parameter references (PRefs). Each PRef addresses exactly one scalar parameter or one element of an indexed parameter. Referenced parameters can be on blocks within the same or different CEE, or on a remote OPC server referenced through an OPC Server FB. For information on configuration and use of OPC Server FBs, see the Application Control Environment User Guide.
You specify the number and kinds of references used by a given program at the time you design the block type. Limits on reference count come from the ERDB parameter count limit per block type. See Limitations on number of CAB parameters for comments on ERDB limits that affect both CDPs and PRefs.
When creating PRefs, CAB programmers can assign the attributes of name, data type, description, and data flow direction. Data types supported for PRefs are described in Data types for CDPs and parameter references.
The name of a PRef is used within the CAB program to refer to the external parameter. This name can be thought of as an alias for the external data. It can be the same or different from the name of the parameter to be referenced. Often, PRef names are chosen so that they reflect what the data means within the program. For example, suppose a CE is designing a block type that receives a temperature input from a boiler. It would be natural to call the reference to this parameter BOILERTEMP.
8.3.10
Configuring parameter addresses on CAB instances
CAB PRefs are generic in that the block parameters they refer to are not bound at the time the block type is defined. The binding for static and dynamic references occurs later, at the time the
- 118 -
Chapter 8 - CAB configuration
block instance is configured, and at the time of the re-reference action for dynamically rereferenced parameters. Each instance can use its references uniquely, pointing to different blocks and parameters. Only one copy of the CAB program (type definition) is needed within the execution environment no matter how many instances are created.
The binding of CAB static reference PRefs is not so late that it can be considered "dynamic." Binding occurs before block load at the time of block instance configuration. After the block has been loaded, reference binding cannot be changed without reload unless the parameter is configured to enable dynamic re-referencing (see Dynamic re-referencing of parameter references).
Within CAB programs, PRefs are typically used as constant-valued pointers. But it is also possible to define PRef variables internal to the program. This would be done to allow the use of more flexible programming constructs such as looping over an array of references or passing references to a subroutine. For an example of the use of PRef variables, see Use of parameter reference variables in CAB.
When addresses are assigned to PRefs at configuration time, it is not required that an entry be supplied for every reference defined by the block. Undefined or null valued PRefs are accepted without error at time of load. However, if READERROPT and WRITEERROPT are specified as Event (see FDPs specific to CAB for a description of READERROPT and WRITEERROPT), an event is reported if a null reference is used at run time. Allowing null PRefs enables greater flexibility in the creation of generic block types.
PRefs allow CAB programs to read and write external data but do not allow that external data to be displayed as though it were a parameter on the block. When debugging, you must view external data on the externally referenced block or you must create value CDPs within the CAB and set their values to the parameter reference values to show the data locally.
8.3.11
Access level used In PRef writes
When PRefs are used for writes, CAB sends an identifier along with the data to indicate the type of agent originating the write. This identifier, called the Access Level, can have two possible valuesProgram or Continuous Control.
When a CAB type is designed, you choose one of these values by specifying the instance default for FDP ACCESSLEVEL (described in FDPs specific to CAB). After the CAB type is operational, it uses one or the other access level value exclusively.
When a CAB program interacts with CEE native blocks, writes are treated equivalently regardless of whether the access level is Program or Continuous Control. Typically, parameters like the SP of regulatory control blocks are not written from CAB. Instead, if a CAB is to serve as supervisory controller in a regulatory cascade, the downstream block pulls the SP from a CAB CDP.
If you explicitly want a CAB type to write to SP, then MODE at the target regulatory block must be Auto. This is equivalent to the MODE protocol that applies to sequences. In addition, MODEATTR must be set to Program at the target in order for writes to any of the parameters SP, MODE, OP, RATIO, or BIAS to be accepted.
In most cases, there is no reason for a CAB design to use Continuous Control instead of Program access level. Thus, when a CAB type is first created, the instance default for FDP ACCESSLEVEL is automatically set to Program by PDE and left unchanged by you. You would change ACCESSLEVEL to Continuous Control if the CAB type were designed for use with legacy Honeywell control systems. You must also change ACCESSLEVEL to Continuous Control if the CAB were to be used as an insertion point algorithm. For comments on interfacing to legacy systems, see Determine Continuous Control access.
8.3.12
Data types for CDPs and parameter references
The following table shows the data types supported for CDPs within CABs and CDBs, and for
- 119 -
Chapter 8 - CAB configuration
parameter references within CABs. Note that the set of types supported for data that exists within the PKS name space is more restricted than the set supported within the confines of a CAB program. Within a CAB program, the only limitations are with VB.NET.
Data type1
Table 8.9 Data Types for CDPs and Parameter References
Supported Supported
for CDPs
for
parameter
Comment
references
BOOLEAN
Yes
Yes
BOOLEAN CDPs as used within CABs and CDBs have a
representation equivalent to that of CEE parameters of
flag type. False (Off) has value 0 while True (On) has
value 1. The same is true for BOOLEAN parameter
references in CABs. Note that for consistency with past
characteristics of MS VB 6.0, VB.NET represents True as
-1 when converted to integer. Despite this, all BOOLEAN
type parameters in Experion, including those of CABs,
represent True as 1.
INT162
No
No
16-bit integers can be used within VB.NET. But for
parameters and parameter references visible within the
PKS name space, CABs and CDBs support INT32 as the
general-purpose integer.
INT32
Yes
Yes
There is a single integer type supported for CDPs and
parameter references within both CABs and CDBs. For
CAB parameter references, implicit conversion
operations are supported between INT32 and most
other scalar types (see Implicit type conversion with CAB
parameter references)
<Standard
No
No
Defining value CDPs or parameter references to be one
System
of the standard system enumeration types (for example,
Enumeration>
MODE enumeration or MODEATTR enumeration) is not
supported. Within CAB programs, you can use the
equivalent numerical values when dealing with system
enumerations. You can also define program-local
enumerations that match the system enumerations.
When storing to external parameters, CAB parameter
references support implicit conversion so that the store
will be accepted by the destination parameter (see
Implicit type conversion with CAB parameter
references).
<Self-Defining No
No
Defining value CDPs PREFs to be of type self-defining
Enumeration>
enumeration (such as PV state of Device Control, OP
state of Device Control, or PV state of Digital Input) is not
supported. Within CAB programs, you can use
equivalent numerical values when dealing with system
enumerations. They can also define program local
enumerations that match the self-defining
enumerations. When storing to external parameters,
CAB parameter references support implicit conversion
so that the store will be accepted by the destination
parameter (see Implicit type conversion with CAB
parameter references).
FLOAT32
No
No
32-bit floating-point numbers can be used within
- 120 -
Chapter 8 - CAB configuration
Data type1
Supported Supported
for CDPs
for
parameter
references
Comment
VB.NET if desired. But for parameters and parameter references visible within the PKS name space; CABs and CDBs support FLOAT64 as the general purpose floating point type.
FLOAT64
Yes
Yes
There is a single floating-point type supported for CDPs and PREFs. For CAB parameter references, implicit conversion operations are supported between FLOAT64 and most other scalar types (see Implicit type conversion with CAB parameter references). Within CAB programs, FLOAT64 CDPs and PRefs are of the VB.NET data type Double.
TIME
Yes
Yes
Parameters of type TIME indicate a point in time. Within CAB programs, TIME is represented by the .NET structure DateTime. Conversion between TIME and the internal representation of DateTime is always done implicitly for CABs. This applies to both PREFs and CDPs (see TIME and TIMEOFDAY usage in CAB).
DELTATIME Yes
Yes
Parameters of type DELTATIME indicate a time span (time duration). Internal to CAB programs, DELTATIME is represented by the VB.NET structure called TimeSpan. Conversion between DELTATIME and the internal representation of TimeSpan is always done implicitly for CABs. This applies to both PRefs and CDPs.
TIMEOFDAY Yes
Yes
Parameters of type TIMEOFDAY (Time Of Day) indicate the time elapsed since midnight. CDPs of type TIMEOFDAY are supported by both CABs and CDBs. Parameter references of type TIMEOFDAY are supported by CABs. Within CAB programs, TIMEOFDAY is represented as the VB.NET type TimeSpan. It is thus internally equivalent to DELTATIME and will, in many cases, provide no added value over that data type. In some cases, however, it may be convenient for the design of custom displays to define CDPs of time TIMEOFDAY (see TIME and TIMEOFDAY usage in CAB).
STRING3
Yes
Yes
String type CDPs are supported for both CDBs and
CABs. String type parameter references are supported
for CABs. String types can be up to 255 characters for
on-node references and up to 127 characters for off-
node references.
Structure
No
No
Structure types can be used internal to CAB programs, but CDPs and PRefs cannot have structure type.
Class
No
No
Class types can be used internal to CAB programs but CDPs and PRefs cannot have class type.
1. Each data type has a default size of 8 characters.
2. There are other integer data types beyond INT16 and INT32 supported within the PKS that are not explicitly listed here. INT32 is unique in being the only integer data type supported for CDPs and PRefs.
- 121 -
Chapter 8 - CAB configuration
Data type1
Supported Supported
for CDPs
for
parameter
references
Comment
3. CAB parameter references of type string have varied string size limits for Peer to Peer connections depending on the connection type. The following table these different string size limits.
The following table lists the different string size limits.
Peer-toPeer
Connection Type
Table 8.10 String Limit Based on Connection Type
Description
String Limit
CAB on ACE to ACE
A CAB on ACE_1 contains a string parameter reference that points to a string parameter (CDB parameter, CAB parameter, TextArray block) on ACE_2.
PRef Read: 1-128 characters. Bad status if string length > 128. Note: The peer string definition can be >128, but a string with length>128 cannot be read. PRef Write: 1-255 characters or max defined size for target. Concatenates > max defined size.
CAB on ACE to string parameter via OPC
A CAB on ACE_1 contains a string parameter reference that points to a string parameter (CDB parameter, CAB parameter, TextArray block) via an OPC gateway.
PRef Read: 1-127 characters. Bad status if string length > 127. Note: The peer string definition can be >127, but a string with length>127 cannot be read. PRef Write: 1-255 characters or max defined size for target. Concatenates > max defined size.
CAB on ACE to C200, C200E, or C300
A CAB on an ACE or C300 contains a string parameter reference that points to a string parameter (CAB parameter, CDB parameter, TextArray block) on a C200, C200E, or C300).
PRef Read: 1-64 characters. PRef Write: 1-64 characters or max defined size for target. Concatenates > max defined size.
CDPs can be indexed parameters (logical arrays) of dimension up to 2. When configuring array parameter definitions within the PDE window, the data type is selected from one of the scalar types listed above. That a CDP is indexed is specified by parameter attributes distinct from the data type.
Parameter references cannot be indexed (logical arrays of references are not supported). However, they can be used to refer to scalar elements of array parameters at fixed index.
In the previous table, it is important to understand that typing of CAB CDPs and CAB parameter references is described in terms of the Experion PKStype names. It is necessary to do so as CDPs are part of the PKS namespace and parameter references point to parameters that are part of that namespace. However, there is a one-to-one mapping between each of the supported data types listed above and the VB.NET data type used within a program, as shown in the following table.
Table 8.11 Data Type Names in Experion PKSand VB.NET
Data type of parameter as viewed externally in PKS namespace
Data type of alias as viewed internally within VB.NET program
BOOLEAN
Boolean
INT32
Int32
- 122 -
8.4
Chapter 8 - CAB configuration
Data type of parameter as viewed externally in PKS namespace
Data type of alias as viewed internally within VB.NET program
FLOAT64
Double
TIME
DateTime
DELTATIME
TimeSpan
TIMEOFDAY
TimeSpan
STRING
String
CAB algorithm data definition
8.4.1 8.4.2
Data initializations under Execute()
CAB instances can own data that is persistent but that is not computed every execution cycle. This data might be internal constants derived from externally stored configuration parameters. It might be status values that are typically constant but that can change in response to process or system failures. There are many other possibilities. All such data is initialized under the calling tree of subroutine Execute().
When the condition that triggers initialization derives from a process or communication occurrence, the initialization code is typically integrated directly into the periodic control algorithm. An example would be initialization of a PV in response to an I/O error status.
For CAB/C300 the kind of internal data that can be persistent from cycle to cycle is more limited than for CAB/ACE. For further information, refer to the section Aggregates and the semantics of 'New'.
Using the Restart property
Another kind of initialization is one that must be done in response to changes in the operating environment that hosts the CAB. To enable this, CAB supports an API called Restart, which is a VB property that can be accessed within Execute() to identify when special initializations are needed. The use of Restart is optional and unnecessary in many algorithms. Restart returns values of type RestartEnum. Possible values are:
l None--No system event has occurred since the last execution of the CAB instance. There has not been a system event since the last execution of the CAB instance.
l BlockLoad--The block is about to execute for the first time since creation within the EE, or for the first time since reload.
l BlockActivate--The block had been inactive but is now about to execute for the first time since going active. No load occurred while the block was inactive but the user may have changed configuration data within the block through on-process displays.
l BlockInActivate--The block is now inactive. Note that the CAB user code will never see this state because the code is not running.
l CABToNormal--The block has returned to Normal state from Dormant or Terminated state.
l CEEColdStart--The CEE as a whole is about to restart execution from a data state left after a previous execution. The time elapsed since last execution was judged by the operator to be long.
- 123 -
8.4.3
Chapter 8 - CAB configuration
l CEEWarmStart--The CEE as a whole is about to restart execution from a data state left after a previous execution. The time elapsed since last execution was judged by the operator to be moderately short.
l CEESwitchStart--This value is returned for the first cycle of execution following either a normal redundancy switchover of a C300 or an OPM switchover of a C300.
If more than a single system event occurs while a CAB is not running, CAB infrastructure uses a priority scheme to decide which value to return when Restart is accessed. This scheme insures that the CAB is informed of the most severe initialization condition. The priority is as follows.
BlockLoad > BlockActivate > CEEColdStart >CEEWarmStart > CEESwitchStart > CABToNormal > None
For an example of using Restart to select different initializations, see Initializing in response to system events.
It is important to understand that initializations that are conditioned by Restart only occur in response to events that impact execution of the instance. If instance execution is not impacted, then the value returned by Restart remains at None. As an example, consider conditions that cause a PV input to become unavailable or bad. This might be caused by communication failure, node failure or some kind of process condition. A condition such as this would never cause Restart to deviate from None. Instead, the CAB algorithm must detect this condition explicitly and respond as appropriate.
Restart() behavior after checkpoint and restore
A checkpoint operation saves the following state variables:
l Execute State--Active or InActive. l Initialization State--BlockLoad, BlockActivate, CEEColdStart, CEEWarmStart, CABToNormal, or
None.
A checkpoint restore operation restores these saved states to the values they were at the time of the checkpoint. When the block first executes after a restore, these saved states determine the value that Restart() returns. Here are some examples:
l Restart() will return BlockLoad if this is the first execution of the block following its load. Restart () always returns BlockLoad on first execution, even if multiple checkpoint save/restore sequences occurred prior to the first execution.
l If the block Execute State was Active and the block had executed at least one time prior to the checkpoint save/restore sequence, the restore operation will return the block to the Active state. In the first execution after the restore operation, Restart() will return the initialization that occurred after the restore, which will be CEEColdStart or CEEWarmStart.
l If the block Execute State was InActive and the block had executed at least one time prior to the checkpoint save/restore sequence and subsequently inactivated, the restore operation will return the block to the InActive state. After the block is activated, Restart() will return BlockActivate in the first execution after it is activated.
8.4.4
CDP initializations associated with block load
For CDPs, CAB infrastructure can support data initialization as part of block instance load. When this is done, there are actually three stages of CDP initialization of which the processing done within Execute() is the last, as shown in the following table.
- 124 -
Chapter 8 - CAB configuration
8.4.5
Type of CDP initialization
Table 8.12 Custom Data Parameter Initialization in CABs
Order Value returned by Restart
Comment
Default
1
Not
When you design a block type, you can define the instance
Applicable default for the CDP. You can also declare the CDP to be
loadable. When an instance is created within CB, the CDP will
be initialized with the default value.
Configuration 2
Not Applicable
After an instance is created within CB, the default of all loadable CDPs can be left unchanged or they can be modified. After loadable CDPs are configured, the instance is loaded to CEE. This causes all loadable CDPs to be initialized to the configured value within CEE. If a CDP is defined to be non-loadable, then it is initialized to the fail-safe value that goes with its data type. Fail-safe values are in Parameter reference fail-safe values.
Execute()
3
processing
BlockLoad When the CM parent of a CAB is activated for the first time following load, access to Restart within Execute() will result in return of the value BlockLoad. In response to this, code within Execute() can choose to leave the loaded values of CDPs unchanged or it can modify them.
Data access integrity
The Execution mode of CAB programs topic discussed how CAB instances execute atomically. This form of execution generally insures that data integrity is preserved. However, integrity issues can still occasionally arise. This discussion provides further information on integrity of parameter access.
Characteristics of parameter transfer vary depending on the nature of the application being developed. Three major variants are:
l Local Parameter Access--CAB type is intended to communicate only with local blocks. l Remote Communication With No Group Integrity Requirements--CAB type must communicate
with remote blocks but data transfer involves only scalar parameters or whole array parameters which pose no issues of consistency or timing across groups of different parameters. l Remote Communication With Group Integrity Requirements--CAB type must communicate with remote blocks and the application design imposes consistency or timing requirements across a group of two or more parameters.
Each of the variants is discussed in the following topics.
8.4.6
Local parameter access
In applications where a block reads parameters only from other blocks within the same CEE, no data integrity issues arise. The same is true for cases where a block writes only to blocks within the same CEE. In these cases, the property of atomic execution is sufficient to insure data integrity. To see this, consider the following code segment:
OUTPUT.Value = 0.0 For I = 0 To 9 OUTPUT.Value = OUTPUT.Value + SCALE.Value * INPUT(I).Value Next I
- 125 -
Chapter 8 - CAB configuration
Here, it is assumed that a program must generate a sum over a scaled input parameter that is indexed. Also assume the following:
l The input array, INPUT, is a custom parameter that can be written by other blocks. l The scale factor, SCALE, is a CDP that can be written by other blocks or displays. l The sum parameter, OUTPUT, is an output CDP which can be read by other blocks or displays.
While the syntax of CDP usage may appear unfamiliar at first (see CDP classes), it should be clear what the previous code segment is doing. In the context of data access, the following questions might arise.
l Suppose that another local block, CAB or native, tries to read parameter OUTPUT. Could it get a value taken from the middle of the loop computation? No. If a request to read OUTPUT arrives while the above code is executing, access to the parameter is locked until the code finishes executing.
l Suppose another local block writes to each of the elements of INPUT. Could it happen that the sum would get computed using values from two different execution cycles of the block that writes to INPUT? No. The loop above can never execute at the same time as another local block that stores to the INPUT array. As long as the writing block writes all elements of INPUT within one execution, the values are received as a consistent set.
l Suppose SCALE is written by another block. Could a new value of SCALE start to be used in the middle of the loop? No. If a write to SCALE occurs while the above code is executing, it does not take effect until the code finishes executing the current cycle.
8.4.7
Remote communication with no group integrity requirements
In some applications, it may be essential to access remote data, either for some or all instances of the CAB type. Ensuring that data obtained remotely is consistent and useable requires deliberate consideration of the CAB program designer. But in many cases, special measures need not be taken because of the nature of the data. To see this, consider the following line of code (assume a PRefList.Read was done before this code is executed):
PV.Value = Compute(MEASIN1.Value, MEASIN2.Value, MEASIN3.Value)
Here, it is assumed that a program must produce a PV that cannot be directly measured. Instead, the PV must be mathematically inferred from three other process measurements. To start, assume the following:
l Three measured inputs, MEASIN1, MEASIN2, MEASIN3, must be obtained from one or more remote CEEs.
l A single output, PV, must be computed from the three inputs by a proprietary algorithm.
l Each of the three inputs is accessed via a parameter reference.
While the syntax of PRef usage may appear unfamiliar at first (see Parameter reference classes) it should be clear what the previous line of code is doing.
In this example, data integrity issues can be reduced to considerations of whether each input value is good and useable. There are multiple techniques for identifying the usability of remote input data as discussed in Parameter reference classes.
The important point is that this example presents no issues of consistency across the group of inputs. MEASIN1 through MEASIN3 are continuous process readings. So, while you, the CAB type designer, must consider the general timing properties of the remote data access in this example, you need not be concerned about the order of data retrieval, nor about whether input values came from the same execution of a remote block. With continuous process values, there is no inherent ordering and, depending on the application, a fairly broad time interval can be considered close enough to simultaneous.
- 126 -
Chapter 8 - CAB configuration
Now, if the example is changed slightly to imagine that MEASIN1 through MEASIN3 were CDPs being pushed from one or more remote CEEs, then the same reasoning applies. No consistency requirements apply to the set of inputs, so the only integrity consideration is whether each value is good or bad.
8.4.8
Remote communication with group integrity requirements
The majority of CAB applications will fall into one of the two cases just discussed. However, it might occasionally arise that a CAB program must involve itself with remote parameter access in which two or more parameters in a group have consistency requirements. The means for addressing this will depend strongly on the particular application. Some examples are discussed below to give a feel for the issues.
First, reconsider the example in Local parameter access, changing the assumptions such that the input array, INPUT, is coming from a single remote block, not a local block. The example is reproduced here, with the new assumption: It is assumed that a program must generate a sum over a scaled input parameter that is indexed. Also assume the following.
l The input array, INPUT, is a custom parameter that is written by a single remote block.
l The scale factor, SCALE, is a CDP that can be written by other blocks or displays.
l The sum parameter, OUTPUT, is an output CDP that can be read by other blocks or displays.
OUTPUT.Value = 0.0 For I = 0 To 9 OUTPUT.Value = OUTPUT.Value + SCALE.Value * INPUT(I).Value Next I
In this case, consistency issues might arise. It is possible that the array data would need to be sampled from a single execution of the originating block. But, if each array element were pushed individually, transport services could not be guaranteed to preserve order or even to insure that the entire set of elements were received as a set between executions of the consuming CAB instance. The array might be received in parts across multiple executions of the consuming block.
A way to resolve this problem would be to implement the CM containing the receiving CAB instance so that it receives the array INPUT through bulk array transport. Bulk array transport is guaranteed to read the entire set of elements and to write them with no intervening block executions. Also, since the array is transported as a unit, no issues arise with respect to order.
This principle can be used fairly flexibly. For example, suppose that in the above example, the INPUT array together with the scale factor, SCALE, had consistency requirements. Then SCALE could be transported with the INPUT array by creating an array of 11 elements at the originating end and transporting that in bulk.
Bulk array transport could also be used to transport process value along with a quality indicator. Generally, the data status or quality needs to come from the same execution of the source block as the data value. If not, the quality indicator could say the data was good when it was bad or vice versa. While quality indicators would generally be thought of as being integer valued, there is nothing to prevent a floating-point number from being used to represent quality. Thus, quality and value could be placed into a single array at the originating end and transported as a unit.
Now consider a different example. Parameters MODE and SP of the PID block are related and can be considered to have a consistency requirement. In general, MODE must have a particular value in order for store of SP to be accepted by the target block.
When CAB writes MODE and SP to a local block, no particular design issues arise. As long as MODE is written with the appropriate value first, SP will be accepted. However, if the target block is remote, the write sequence will usually work but not guaranteed to always work. Peer-to-peer communication services are not guaranteed to maintain order of delivery. Also, depending on the remote device which hosts the block, it may be necessary for the receipt of MODE and the receipt of SP to be separated by an execution cycle at the target.
- 127 -
Chapter 8 - CAB configuration
A standard technique for addressing this problem is to write MODE and read it back before writing SP. Once MODE goes to the target value, the SP write may proceed. This is shown in the following code example where WriteSP is assumed to be a local Boolean state variable and SPTargetValue is the desired value for SP. Both MODE and SP are assumed to be PRefs.
If WriteSP Then If MODE.Value <> 1 Then
MODE.Value = 1 Else
SP.Value = SPTargetValue WriteSP = False End If
End If
8.4.9
Read versus write
Another consideration when designing applications that use CAB is whether a particular data transfer should be done with Read or Write--CAB supports both. Target blocks or devices may require one or the other. In some applications, you might have the option to choose whether a CAB design uses Read or Write. There is no rule as to which to use if the choice is available, but here are some general considerations:
l If CAB is to receive data and the chosen design has an external block push to the CDP of a CAB instance, then it is not possible for CAB to check status information on the data transfer. The last value pushed will always hold if the transfer operation fails, regardless of whether the transfer operation is peer-to-peer or confined to a single CEE.
l If CAB is to receive data and the chosen design has CAB pull from an external block via a PRef, then the CAB instance can always check status to see whether the data transfer was successful. This is true regardless of whether the transfer operation is peer-to-peer or is confined to a single CEE.
l If CAB is to send data and the chosen design has an external block pull from the CDP of a CAB instance, then depending on its design, the external block might be able to check status information on the data transfer. This is true regardless of whether the transfer operation is peer-to-peer or is confined to a single CEE.
l If CAB is to send data and the chosen design has CAB push to an external block via a PRef, then the CAB program can be implemented to check the status of the write operation. However, the program implementation depends on whether the destination block is always in the same CEE as the CAB instance, or whether there will be at least one case when the two will be in different CEEs. Response of the external block to transfer failure depends on its design. In most cases it would hold last value.
l If CAB pushes to a local block, status is always available in the same execution cycle where the push was performed. The program design to use the status is quite simple.
l If CAB pushes to a remote block, status is not available until an execution cycle subsequent to the cycle where the push was performed. The program design to use the status is more involved and requires the use of one or more state variables.
These observations are summarized in the following table.
Data flow direction
Table 8.13 Integrity Considerations for Read Versus Write Data flow initiator
External block
Cab instance
External block to CAB instance
l External block pushes to CAB CDP.
l CAB pulls through PRef. l CAB can see transfer status.
- 128 -
Chapter 8 - CAB configuration
8.4.10
Data flow direction External block
CAB instance to external block
Data flow initiator
Cab instance
l CDP holds on transfer failure.
l CAB cannot see transfer status.
l External block pulls.
l Depending on design, pulling block may check transfer status.
l CAB pushes through PRef.
l If target is local, CAB can see transfer status on same execution.
l If target is remote, CAB can see transfer status on subsequent execution.
l Depending on design, target generally holds in response to transfer failure.
Structure and class usage within CAB
Variables of structure type and variables of class type can be used within CAB/ACE programs as consistent with the syntax and semantics of the underlying .NET language. Structures are not supported in CAB/C300. CDPs that are visible to the PKS outside the CAB program cannot be defined to have structure or class type. Parameter references that access data on function blocks outside of the CAB program cannot be defined to reference parameters of structure or class type.
8.4.11 Array usage within CAB
TIP
If you are designing CABs that can execute on C300, there are some special considerations regarding array usage.Refer to Aggregates and the semantics of 'New' for more information.
Arrays can be used within CAB programs as consistent with the syntax and semantics of the underlying .NET language. For arrays that are only used internally to CAB programs (block scope variables or local variables), the full indexing capabilities of the VB.NET language are supported.
CAB CDPs can be defined to be of one- or two-dimensional array type. The element type of CDP arrays is always a simple type and is restricted to the set supported by scalar CDPs. The CAB that owns the array CDP can do index computations at run time in order to access elements of the array. All CDPs support properties Dim1, Dim2, LowBound1, and LowBound2, which can be used to determine the dimension sizes and lower bounds of arrays. See Parameter reference class usage for information about Dim1 and Dim2 properties.
CAB parameter references are always scalar. Thus, the block designer cannot create an array of parameter references. Scalar parameter references can point to scalar parameters or to individual elements of array parameters. References to external parameter arrays always use fixed indices and are thus equivalent to ordinary scalar references.
Several options are available for the space-efficient display of array-valued CDPs within operating displays:
- 129 -
Chapter 8 - CAB configuration
l Custom displays can be designed to show selected elements of arrays. l Chart visualization can be used to show CAB forms within the operational view.
Under chart visualization and monitoring, array CDPs can be displayed as follows: l Individual array elements can be displayed as parameter values on the CAB faceplate symbol. l Individual array elements can be displayed as pins on the CAB faceplate symbol. l The CAB form can be opened to view a scrollable form for the entire array.
For an illustration of the differences between internal array variables, CDP arrays, and scalar parameter references to array elements, see Array and scalar variables in CAB.
8.4.12
Floating point usage within CAB
Floating-point data within CAB programs are represented according to the IEEE 754 floating-point standard. The following functions are provided.
l Floating-point divide of a finite value by zero produces +INF or -INF with no exception being thrown.
l Assigning an INF value from one floating-point variable does not cause an exception.
l INF values are ordinal. Use of INF in any floating-point comparison produces results consistent with comparison of finite values.
l INF values propagate through subsequent calculations. Thus, a finite value divided by +INF or INF will yield zero. A positive finite value multiplied by -INF will yield -INF. +INF subtracted from any finite number will yield -INF.
l INF values can be identified through the IsInfinity() method and related methods (see Using IsNaN(), IsInfinity(), IsNegativeInfinity(), and IsPositiveInfinity()).
l Floating-point divide of zero by zero produces NaN with no exception being thrown.
l Assigning a NaN value from one floating-point variable to another does not cause an exception.
l NaN values are non-ordinal. Use of NaN in any floating-point comparison produces the value False. For example, the following comparisons will all return False: (1.0 = NaN); (1.0 <> NaN); (1.0 > NaN); (1.0 <NaN); (NaN = NaN).
l NaN values propagate through subsequent calculations. Any calculation done with one or more NaN values as input yields NaN as output.
l NaN values can be identified through the IsNaN() method (see Using IsNaN(), IsInfinity(), IsNegativeInfinity(), and IsPositiveInfinity()).
A NaN constant is available within the language implementation to allow variables to be initialized to NaN.
When INF or NaN values are stored to external block parameters through parameter references, the resulting behavior is determined by the design of the receiving block. Some blocks might be designed to allow write of these values to specific parameters. Others might be designed to reject such writes. If a CAB program attempts to write a NaN or INF and the write is rejected, the program can learn of this from the returned data access status.
CAB infrastructure never throws exceptions when programs attempt to write floating-point values to internal or external variables. If you want to prevent NaN or INF values from going out, you must write the program to test before storing.
- 130 -
Chapter 8 - CAB configuration
8.4.13
Using IsNaN(), IsInfinity(), IsNegativeInfinity(), and IsPositiveInfinity()
If you define a CDP or PRef in CAB as data type Float64 and enter code that includes <param name>.Value, and then put a period after Value, the IntelliSense drop-down list includes IsNaN, IsInfinity, IsNegativeInfinity, and IsPositiveInfinity as shown in the following figure.
Figure 8.6 IntelliSense List for Float64
This would seem to indicate that they are properties that you can select and use. However, they cannot be used in this manner. They are methods of the structure Double. You must pass the value to be tested as an argument, as shown in the following example:
If Double.IsNaN(<param name>.Value) Then
This expression will return True if <param name>.Value is NaN, or False if it is not.
8.4.14
TIME and TIMEOFDAY usage in CAB
The following rules summarize how to use data types TIME and TIMEOFDAY in CAB:
l All parameters of type TIME and TIMEOFDAY are stored internally (in ERDB) in UTC time format.
l If you enter a TIME or TIMEOFDAY CDP default value in PDE, it should be entered in regional (local) time. The value will be converted automatically to UTC time when stored in the ERDB.
l CB will display TIME and TIMEOFDAY parameters in PC regional time. l Displays will display TIME and TIMEOFDAY parameters in regional time. l CAB programs that convert TIME and TIMEOFDAY parameters to a string format are
responsible for converting TIME and TIMEOFDAY to regional time using the VB.NET conversions that are available.
See Example using data type TIME, Example using data type TIMEOFDAY, and Example using data type DELTATIME. Also, see History time examples for information on the use of time variables when accessing history.
8.5
CAB algorithm parameter references
8.5.1
Implicit type conversion with CAB parameter references
Although CAB parameter references can only be defined with one of the types listed in Data types for CDPs and parameter references, a particular parameter reference can actually address a wider set of parameter types. For example, a FLOAT64 reference can be configured to address parameters of type INT16, INT32, FLOAT32, one of the standard system enumerations, and others.
- 131 -
8.5.2
Chapter 8 - CAB configuration
To support this functionality, implicit data type conversions are performed for read and write operations associated with parameter references. Implicit conversions are supported for CAB parameter references but not for stores to value CDPs. Stores to value CDPs from native blocks or from displays must always come with matching data type.
Depending on the nature of the source data type, the nature of the destination data type, and the nature of the value to be converted, direct conversion may not always be possible. The following tables show how CAB handles conversions involving non-commensurate data. Symbols used within the table are explained by the following legend.
Legend
l "" indicates "transferred to" or "converted to."
l The term "commensurate" indicates a data transfer in which range, precision and data semantics are preserved.
l Terms "ordinal 0 or "ordinal 1" indicate the numeric value of an enumeration as distinct from the name value of an enumeration.
l MINI32 = -2147483648. This is the minimum value that can be represented by an INT32.
l MAXI32 = 2147483647. This is the maximum value that can be represented by an INT32.
l MINI16 = -32768. This is the minimum value that can be represented by an INT16.
l MAXI16 = 32767. This is the maximum value that can be represented by an INT16.
l MINF32 = -2.86E38. This is roughly the minimum value that can be represented by a FLOAT32.
l MAXF32 = 2.86E38. This is roughly the maximum value that can be represented by a FLOAT32.
l MAXP32 = 16777215. This is the maximum integer value that can be represented with full precision by a FLOAT32.
l "~x" indicates that the pre-existing value of x is preserved with some loss in precision. In cases of floating point to integer conversion the fractional part is always handled by rounding.
l .NETTO = .NET Time Origin. This is a 0 within the 64-bit .NET representation of time. It corresponds to January 1, 0001, 12:00 AM.
l ExpTO = Experion PKSTime Origin. This is 0 within the 64 bit Experion PKSrepresentation of time. It corresponds to January 1, 1972, 12:00 AM.
In cases where the data read results in real or potential loss of precision, there is no indication by the status property. In cases where the data flow is outgoing (write via CAB parameter reference) and data must be clamped, there is no indication by the status property.
Parameter references used for read
A CAB will now throw an exception if the user attempts to set a read-only parameter reference value.
Error type VS CAB run-time configuration mismatch.
Error message
Attempted assignment to a Read Only parameter.
Description Tried to Write a value to an INPUT parameter .
Cause
CAB programming is assigning a value to a INPUT only Parameter Reference
Workaround Remove the code that assigns the value to the INPUT only PRef or change the PRef to be IN/OUT or OUTPUT. If a local value needs to be stored in the CAB program, define a local variable to hold the value within the CAB subroutine. If the value needs to be used globally in the program, a variable can be defined in the
- 132 -
Chapter 8 - CAB configuration
CAB program within the CABLock class right above the Execute() subroutine. This allows the variable data to be accessed in any subroutine in the CAB program.
The following tables show how CAB handles implicit type conversions for reads through parameter references. In these tables, rows correspond to source while columns correspond to destination. "Source Data Type"is the data type of the external parameter being read. "Destination Data Type"is the data type of the CAB parameter reference. The destination data type maps directly to a VB.NET type as described in Data types for CDPs and parameter references.
Table 8.14 Implicit Data Type Conversion for PRef Reads (part 1)
Source data type
Destination data type
BOOLEAN
INT32
FLOAT64
BOOLEAN INT161 INT321
commensurate FALSE 0 TRUE 1
x == 0 FALSE x != 0 TRUE
x == 0 FALSE x != 0 TRUE
commensurate commensurate
FALSE 0.0 TRUE 1.0 commensurate
commensurate
<Standard System x == ordinal 0 ordinal 0 0 ordinal 1 1 etc. Enumeration> FALSE x != ordinal
0 TRUE
ordinal 0 0.0 ordinal 1 1.0 etc.
<Self Defining Enumeration>
x == ordinal 0 ordinal 0 0 ordinal 1 1 etc. FALSE x != ordinal 0 TRUE
ordinal 0 0.0 ordinal 1 1.0 etc.
FLOAT32
x is NaN FALSE x is NaN 0 x < MINI32 MINI32 commensurate
x == 0.0 FALSE x MAXI32 < x MAXI32 other x x
!= 0.0 TRUE
NOTE: When reading source type of
FLOAT32, the decimal value is
truncated.
FLOAT64
x is NaN FALSE x is NaN 0 x < MINI32 MINI32 commensurate
x == 0.0 FALSE x MAXI32 < x MAXI32 other x ~x
!= 0.0 TRUE
NOTE: When reading source type of
FLOAT64, the decimal value is
truncated.
TIME
FALSE
0
NaN
DELTATIME
FALSE
0
NaN
TIMEOFDAY
FALSE
0
NaN
STRING
FALSE
0
NaN
1. Although there are several other integer data types beyond INT16 and INT32 supported within the PKS, they are not listed here. INT32 is unique in being the only integer data type supported for CDPs and PRefs. However, like INT16, implicit conversion to and from INT32 is supported for other integer types.
Note: See the previous Implicit type conversion with CAB parameter references topic for information about interpreting this table.
- 133 -
8.5.3
Chapter 8 - CAB configuration
Table 8.15 Implicit Data Type Conversion for PRef Reads (part 2) Source data type Destination data type
TIME
DELTATIME
TIMEOFDAY
STRING
BOOLEAN
.EXPTO
0
INT161
.EXPTO
0
INT321
.EXPTO
0
12:00 AM
""
12:00 AM
""
12:00 AM
""
<Standard
.EXPTO
0
System
Enumeration>
12:00 AM
""
<Self Defining .EXPTO
0
Enumeration>
12:00 AM
""
FLOAT32
.EXPTO
0
12:00 AM
""
FLOAT64
.EXPTO
Converts to seconds
Converts to
""
seconds modulus
the number of
seconds in a day
TIME
commensurate 0
12:00 AM
""
DELTATIME
.EXPTO
commensurate 12:00 AM
""
TIMEOFDAY
.EXPTO
0
Commensurate ""
STRING
.EXPTO
0
12:00 AM
commensurate
1. Although there are several other integer data types beyond INT16 and INT32 supported within the PKS, they are not listed here. INT32 is unique in being the only integer data type supported for CDPs and PRefs. However, like INT16, implicit conversion to and from INT32 is supported for other integer types.
Note: See the previous Implicit type conversion with CAB parameter references topic for information about interpreting this table.
Parameter references used for write
The following tables show how CAB handles implicit type conversions for writes through parameter references. "Destination Data Type" is the data type of the external parameter being written. "Source Data Type" is the data type of the CAB parameter reference itself. The source data type maps directly to a VB.NET type as described in Data types for CDPs and parameter references. In these tables, columns correspond to source while rows correspond to destination. The table is divided into two parts for readability.
Source data type
Table 8.16 Implicit Data Type Conversion for PRef Writes (part 1) Destination data type
BOOLEAN
INT32
FLOAT64
BOOLEAN
commensurate Same as read
same as read
INT32
same as read commensurate
same as read
FLOAT64
same as read
Commensurate NOTE: When writing source commensurate type of INT32, the decimal value is truncated.
- 134 -
8.5.4 8.5.5
Chapter 8 - CAB configuration
Source data type
BOOLEAN
Destination data type INT32
FLOAT64
TIME
ExpTO
ExpTO
ExpTO
DELTATIME same as read Same as read
same as read
TIMEOFDAY same as read Same as read
same as read
STRING
same as read Same as read
same as read
Note: See the previous Implicit type conversion with CAB parameter references topic for information about interpreting this table.
Table 8.17 Implicit Data Type Conversion for PRef Writes (part 2)
Source data type
Destination data type
TIME
DELTATIME
TIMEOFDAY
STRING
BOOLEAN
same as read
same as read
same as read
same as read
INT32
same as read
same as read
same as read
same as read
FLOAT64
same as read
same as read
same as read
same as read
TIME
commensurate ExpTO
ExpTO
ExpTO
DELTATIME
same as read
commensurate same as read
same as read
TIMEOFDAY
same as read
same as read
commensurate same as read
STRING
same as read
same as read
same as read
Commensurate
Note: See the previous Implicit type conversion with CAB parameter references topic for information about interpreting this table.
Parameter reference fail-safe values
CAB infrastructure returns a fail-safe value for any parameter reference that incurs a read error. The value returned depends on the data type as shown in the following table.
Data type
Table 8.18 Fail-Safe Values Fail-safe value
BOOLEAN
False
INT32
0
FLOAT64
Nan
TIME
EXPTO - 1/1/1972 12:00 AM
DELTATIME
0
TIMEOFDAY
12:00 AM
STRING
""
Limitations on PRef writes to C200, C200E, or C300
PRef writes to a C200, C200E. or C300 controller are limited to the maximum Push / Store Request Capacity of the target controller. For example, if the target is a traditional C300, the limit is 50
- 135 -
8.5.6
Chapter 8 - CAB configuration
Parameters Per Second (PPS). Please consult specifications corresponding to the type of target controller in use. This maximum rate applies to the total of all sources writing to the controller. Be aware of this limit when writing CAB code that uses PRef writes, especially PRefList writes, to a C200, C200E, or C300. To determine if a given C200, C200E, or C300 controller is approaching this limit, view the Peer Communications tab on the properties page of the controller's CEE as shown in the following figure.
Figure 8.7 Peer Communication Tab
style="width:400px;height:71px;"/>
In this example, controller C300_17 is writing at a maximum of 20 pps to this controller, controller C200_15 is writing at 10 pps, and C200_03 is writing at 20 pps. Therefore, this controller is at the limit of 50 pps if the maximum rates occur simultaneously.
While this example shows writes from C200 and C300 controllers, it would also show writes from ACE if they existed. To avoid this problem, use pin connections on the parameters in the C200, C200E, or C300 controller to pull the information, or in the case of CAB, redesign the CAB program so as to limit the rate of writes.
CAB writes with Continuous Control access level
Assume that a CAB type was designed to support supervisory control to a UCN resident PM, APM or HPM controller. Several different ACE configurations could be used as described in the following three cases.
l Case 1: CAB instance serves as insertion algorithm for Regulatory Control FB in ACE. UCNOUT FB pulls from regulatory FB. UCNOUT FB pushes to Regulatory Control point or to AO point in PM through an OPC Server FB. In this case, the CAB instance directs PRef writes to an ACE regulatory FB. In this case, the CAB must be configured with an access level of Continuous Control.
l Case 2: CAB instance executes stand-alone in ACE. CAB instance computes SP or OP command as CDP value. UCNOUT FB pulls from CAB instance. UCNOUT FB pushes to Regulatory Control point or AO point in PM through an OPC Server FB. In this case, the CAB instance does not issue PRef writes. Therefore, access level is irrelevant.
l Case 3: CAB instance executes stand-alone. CAB instance uses PRefs to write parameters of PM points through an OPC Server FB, independent of any regulatory or UCNOUT FBs in ACE. In this case, use of Program or Continuous Control access level in the CAB design will have different effects, as described below. When Program is used, PM points receiving the write react as though the CAB program is part of a sequence. The following applies: o Regulatory points must have MODE = Auto for SP writes to be accepted.
o Regulatory points must have MODE = Man for OP writes to be accepted.
o AO points must have MODE = Man for OP writes to be accepted.
o Parameter MODEATTR at the target point must be Program in order for writes to parameters SP, OP, MODE, RATIO or BIAS to be accepted.
When Continuous Control access level is used, PM points receiving the write react as though the CAB program is supervisory continuous controller. The following applies:
o Regulatory points must have RCASOPT set to SPC or RSP and MODE set to Cas in order for SP writes to be accepted.
o Regulatory points must have RCASOPT set to DDC or DDC RSP and MODE set to Cas in order for OP writes to be accepted.
o AO points must have RCASOPT set to DDC and MODE set to Cas for OP writes to be accepted.
o MODEATTR does not condition acceptance of writes to parameters SP, OP or MODE.
- 136 -
8.6
Chapter 8 - CAB configuration
Dynamic re-referencing of parameter references
TIP Dynamic re-referencing is not supported in CAB/C300.
8.6.1 8.6.2 8.6.3
What is dynamic re-referencing?
In CAB release 210, all parameter references were static. You assigned an alias name for each reference when defining the CAB in the PDE (for example, RFXFLOW, for the reflux flow rate as shown in CAB insertion algorithm). When creating a block instance in the Control Builder project view, you assigned a specific target value to the reference (FI202.AI1.PV in the example). After loading the instance to ACE for execution, the target value of the reference was fixed or static, and could not be changed without reloading the instance.
Beginning with CAB release 300, dynamic re-referencing functionality is available. With this functionality, individual parameters can be configured for either static referencing capability (the same as release 210 functionality), or for dynamic re-referencing capability. When a parameter is configured for dynamic re-referencing capability, the target for the reference can be changed "on the fly," even though the instance is loaded and executing in ACE. This change can be done manually or programmatically. For example, a program or operator could change FI202.AI1.PV to FI302.AI1.PV in the CAB insertion algorithm example mentioned above, thereby directing the reference to a different target. Similarly, a program or operator could change all of the references (assuming that they are all enabled for dynamic re-referencing) to redirect the program to use a totally different equipment set.
Configuration summary
The following general steps are used to configure for dynamic re-referencing:
1. Individually enable dynamic re-referencing for each parameter reference that you want to have this capability. This is done during CAB creation.
2. Configure how the CAB will handle all of its dynamic re-references. This can be automatic, in which case each reference begins using its new target as soon as it is ready to be used, or it can be manual, in which case new re-reference targets are saved as they are entered and then all references switch at the same time in response to a manual action.
If any of your re-reference targets require access through OPC Gateway, a special configuration step is necessary. See Re-referencing through OPC Gateway.
These steps and the re-reference tools to accomplish them are described in the following topics.
Enabling dynamic re-referencing
A parameter reference is configured to enable dynamic re-reference capability by selecting the Dynamic Reference checkbox when defining the parameter in the PDE as shown in the following figure.
Figure 8.8 Enabling Parameters for Dynamic Re-referencing
style="width:400px;height:35px;"/>
- 137 -
8.6.4 8.6.5 8.6.6
Chapter 8 - CAB configuration
If this checkbox is left unchecked, the parameter reference will be a static reference. If the box is selected, the parameter will have dynamic re-reference capability enabled.
If you edit a CAB that has instances, and you uncheck a Dynamic Reference box, you will have to do a Save As operation. The reason for this is that when you enable a parameter reference for rereferencing, the CAB build environment creates a new parameter (see Re-referencing from an external agent using the TEXTREF parameter). If you later edit the CAB and uncheck the Dynamic Reference option, this parameter will be deleted, an operation that requires a Save As.
How re-referencing works
If a parameter is configured to enable dynamic re-referencing, it can be re-referenced in one of two ways:
l The CAB algorithm can store a text string (the new target parameter) to a property on the parameter reference (see Re-referencing from the CAB algorithm using the TextRef property).
l An external agent, human or another block, can store a text string (the new target parameter) to a new parameter associated with the parameter reference (see Re-referencing from an external agent using the TEXTREF parameter). This new parameter is created by the CAB build time environment when the reference is enabled for dynamic re-referencing.
The re-reference function can also be used to "disable" a PRef. If a blank string is stored instead of a new target parameter, the PRef will be set to a null reference and cannot be used for further reading or writing. This is the same behavior as is seen by the algorithm if a parameter reference is not configured. Setting the reference to a null reference is not considered an error--it simply means that the parameter reference cannot be used. A dynamic parameter reference can be null at load time and configured at a later time. A parameter reference that has been set to null can be made useable again by storing a valid text string.
The translate and commit functions
The translate and commit functions are underlying functions that do most of the "dirty work" in the dynamic re-reference process. It is important to have a general understanding of these functions to effectively use the tools that are available for dynamic re-referencing.
The translate process refers to the process of converting the text string name of the parameter reference to an internal handle used by the infrastructure to access the parameter. Translation occurs in Control Builder when you use the point picker to assign a target to a parameter reference on the project side. Later, if a new target name is entered for re-referencing, another translation step must take place to determine the handle of the new target before the new reference is useable. For an atomic execution block, this translation is initiated at the end of the CAB execution cycle in which the new target string is stored. It takes place during the time that the CAB is not executing. For a distributed execution block, the translate operation is performed when the block exits the Execute method. The commit operation will be done on the next end-of-cycle after names have been translated and the COMMIT is set, either implied automatically or set manually.
The commit function is the process (call) by which the CEE connects to the physical reference. References are committed when the CAB is loaded to ACE. When a parameter is re-referenced during execution, the new target is committed after it has been translated. The commit action can be initiated manually or automatically, as will be discussed. Like translation, this process takes place while the CAB is not executing.
Performance considerations
If a parameter has dynamic re-reference capability enabled, you can still use the parameter as a
- 138 -
8.6.7 8.6.8 8.6.9
Chapter 8 - CAB configuration
static reference by simply not changing the reference target. There is no performance penalty, and there is only a minor memory use penalty because the CAB development environment infrastructure creates an additional parameter for a parameter that can be re-referenced (see Rereferencing from an external agent using the TEXTREF parameter). The process of re-referencing a parameter reference introduces delays because the translate/commit activity is performed when the CAB is not executing, and therefore cannot be completed in one ACE execution cycle. However, after the translate/commit to a new target is completed, subsequent parameter references to the new target will be at the same speed as static parameter references. The action of re-referencing does not change the user view of parameter references except that a new status parameter is available that shows when one or more re-referencing operations are in process, indicating that the references may be temporarily unusable. The PRef parameter will temporarily change to "err 2953" while it is busy translating (as seen by an operator). There is also a temporary change to the text name entered in the TEXTREF parameter while the name is being translated. It changes to "<BUSY>name" during translation and then reverts to the user-entered name when translation is completed.
Data integrity considerations
Parameter references become unusable at the point when a new target string is stored. They remain unusable until the translate/commit process is complete. This will be one or more execution cycles later. Attempts to read or write a parameter that is unusable due to translate/commit activity will return errors. CAB re-reference capability includes a tool (the X_ REFSTATE parameter) that allows you to determine when all re-referenced parameters are usable. In addition, your application may require that you maintain the integrity of a set of references. For example, you can perform multiple re-references (manually or programmatically) and then you require that all of them simultaneously switch to new targets before any of them are used. The CAB re-reference tools provide functionality (the X_REFMODE and X_REFCOMMIT parameters) to accomplish the synchronization of multiple parameter re-references.
Re-referencing through OPC Gateway
For dynamic re-referencing of a point.param that goes through OPC Gateway, a static parameter reference pointing to the potential dynamic OPC reference must be configured on the Parameter Reference configuration form of a CAB. This can be any CAB, including the CAB whose algorithm is using or performing the re-referencing, or a "dummy"CAB that is used only for the configuration of these OPC re-reference targets. If this is not done, the system will not be able to determine the handle for the OPC references and the dynamic re-referencing to the OPC references will not work.
Parameters used for re-referencing
There are three FDPs associated with dynamic re-referencing capability: l X_REFMODE--Used to specify whether re-references are committed manually or automatically.
l X_REFCOMMIT--Used to manually commit re-references when the X_REFMODE is set to Manual-commit.
l X_REFSTATE--Used to monitor whether any parameters are in the process of being rereferenced.
These parameters are described in the following three topics.
- 139 -
Chapter 8 - CAB configuration
8.6.10
Configuring the X_REFMODE parameter
The X_REFMODE parameter sets the execution mode that the CAB will use for all parameter rereferences. The execution mode determines when parameter references become usable after they have been re-referenced.
The values for the X_REFMODE parameter are:
l AUTO--In this mode, each individual parameter reference will begin to use its new target as soon as the translate/commit functions complete. This will occur asynchronously as individual re-references complete and occurs automatically without external action. This mode would typically be used for: o A single parameter re-reference.
o Multiple parameter re-references when it is not necessary to simultaneously switch all parameters to new references.
o A CAB that is only executed by a Process Special request. All of the re-referencing can be done while the block is not executing. When all of the new references have been entered, the operator can do a Process Special for the CM to execute the block.
l MANUAL--In this mode, re-referenced parameters are not used until another parameter (X_ REFCOMMIT) is set to COMMIT. As individual parameters have new target strings stored to them, they become unusable and attempts to read or write them result in errors. When the entry of new target reference strings is complete, the operator initiates the commit action, which will simultaneously switch all re-referenced parameters to their new targets.
The default value of this parameter is AUTO. You can change this value to MANUAL in the PDE, but you cannot change the value on CAB instances.
8.6.11
Using the X_REFCOMMIT parameter
The X_REFCOMMIT is used only when the re-reference mode parameter X_REFMODE is set to MANUAL. The X_REFCOMMIT parameter can be used to cause a set of references (one or more) to simultaneously commit to new references under human control. The commit is performed when the block is not running (between executions). The block will use the new references on the next execution that occurs after the commit is completed.
The X_REFCOMMIT parameter has the following states:
l IDLE
l COMMIT
l CANCEL
The operator writes COMMIT to this parameter to initiate the commit function for all references that have had new target values stored to them. If the operator writes CANCEL to this parameter, all parameters that have new target names stored to them will be set to NULL and the TEXTREF parameter (see Re-referencing from an external agent using the TEXTREF parameter) will be set to blank .
While the new references are being added, and before the COMMIT is stored, any attempt to reference a parameter that has a new reference target stored will return an error. User code must be written to accommodate this condition. One possibility is to have the code monitor the X_ REFSTATE parameter.
A typical scenario might be that an operator stores new target names to one or more re-reference enabled parameters from a faceplate or custom schematic display. When the operator has finished entering new targets, he or she sets the X_REFCOMMIT parameter to COMMIT from the faceplate or schematic display.
- 140 -
Chapter 8 - CAB configuration
The COMMIT can also be written programmatically. If the X_REFMODE is MANUAL and new targets are stored programmatically, the same program could store the COMMIT at the conclusion of writing new target strings.
TIP If an operator stores the new target names, the operator should perform the COMMIT or CANCEL operation. If the algorithm stores the new target names, the algorithm should perform the COMMIT or CANCEL operation.
After the commit function completes, the system sets the value of X_REFCOMMIT to IDLE.
8.6.12
Using the X_REFSTATE parameter
The X_REFSTATE parameter can be used to monitor the state or re-referencing activity for a CAB. It can be monitored on a faceplate or schematic display, and can be referenced by the CAB algorithm.
The X_REFSTATE parameter has the following states:
l IDLE--indicates that there is no re-reference activity in process.
l TRANSLATING--indicates that one or more re-reference text names have been entered, are being or have been translated, but have not been committed.
l COMMITTING--indicates that the re-reference COMMIT has been set and the parameter references are being redirected to the new targets.
If the re-reference mode is set to AUTO, depending on the load on the ACE node and on the number of parameters being re-referenced, the observed value of this parameter may appear to be continuously IDLE. If it is not predominately IDLE in the AUTO mode, this would indicate a problem with the re-reference function.
If the re-reference mode is set to MANUAL, this parameter, if displayed, would indicate when the operator has entered one or more re-references, but has not committed them yet. In the MANUAL mode, the algorithm could monitor this parameter to determine when new targets are being entered so that parameter reference reads and writes can be suspended to avoid receiving errors.
Note that storing a blank string to a PRef will not cause X_REFSTATE to change from IDLE to TRANSLATING, though it will cause that particular PRef to become unstable.
8.6.13
Viewing re-referencing in Control Builder
While a re-reference action is in process, a parameter reference viewed on the Parameter Reference tab of the CB monitor view will show as Error 2953 (kVAStsPreviousCommandPending). If a re-reference action fails, a parameter reference viewed on the Parameter Reference tab of the CB monitor view will show as Error 2957 (kVAStsInvalidNoConnectionToOwner).
8.6.14
Renaming a configured reference
If you rename a block that is referenced, the connection to that block is set so that it will continue to be referenced despite its name change. However, the TEXTREF parameter for the dynamic reference is not changed. So, if you were to look at it, it would still show the previous name, and not the name of the referenced block after you renamed.
- 141 -
Chapter 8 - CAB configuration
8.7
Re-referencing from the CAB algorithm using the TextRef property
A CAB can re-reference its own parameter references by using the TextRef property that exists on each parameter reference type. This property can be read to determine what the current reference is, and can be written to modify the reference. The TextRef property is a string data type.
The CAB run-time checks to see if the new name entered is different than the current name. If the names are identical, no re-reference action will take place and the existing connection will remain active.
If the re-reference mode, X_REFMODE, is set to MANUAL, the CAB algorithm must also set the commit command by storing COMMIT to the re-reference commit parameter X_REFCOMMIT.
If a re-reference action fails for a parameter reference (for example, if the text name entered does not exist), that parameter reference will be left in a failed state and cannot be used for any read or write. The TextRef property and the TEXTREF parameter for the failed re-reference action will be set to "<err xxxx>name"where name is the text string that was stored and xxxx is the specific error code from the name translation operation. If the CAB algorithm attempts to read or write using a parameter reference that has failed the re-reference, the appropriate ReadStatus or WriteStatus property will be set to CABAccStatusEnum.ReRefFail.
The following are some examples of syntax that can be used by the CAB algorithm:
8.7.1
Reading the reference name
A CAB can use the following syntax to read the current parameter reference name:
CurrentRef = <parameter_reference_name>.TextRef Reading the re-reference string has no effect on the reference being used. It is a means of fetching the current reference target name.
8.7.2
Changing the reference name
A CAB can use the following syntax to write a new parameter reference name:
<parameter_reference_name>.TextRef = newRef
Writing the re-reference string causes the CAB infrastructure to initiate the re-reference process for the parameter reference. The re-reference behavior depends on the setting of the rereference mode parameter X_REFMODE.
If the re-reference mode parameter is set to AUTO:
l The parameter reference will become unusable when the new string is stored. l A request is queued to translate the string text name to a handle. All reference names entered
during one execute cycle are queued to be translated at the end of the current ACE cycle. This has the effect of sending all re-reference names in a single request to be translated. A CAB executing in the distributed mode must exit the Execute() method for the new names to begin translation.
If the re-reference mode parameter is set to MANUAL:
- 142 -
Chapter 8 - CAB configuration
l The parameter reference will become unusable when the new string is stored. l A request is queued to translate the string text name to a handle. All reference names entered
during one execute cycle are queued to be translated at the end of the current ACE cycle. l New references are translated but are not used until the COMMIT is set. l Setting the COMMIT flag
A CAB can use the following syntax to set the COMMIT flag to apply the re-reference changes when the re-reference mode parameter, X_REFMODE, is MANUAL:
X_REFCOMMIT.Value = CABReRefCommitEnum.Commit The CAB may also cancel the re-reference operation by setting the COMMIT flag to CANCEL:
X_REFCOMMIT.Value = CABReRefCommitEnum.Cancel
8.7.3
Checking for re-reference errors
If a re-reference action fails for a parameter reference (example, the text name entered does not exist), the CAB algorithm can use the parameter reference IsValid property to detect the error.
If <parameter_reference_name>.IsValid then ' do process for the Re-Reference success <parameter_reference_name>.Read() ' else process the error
The CAB algorithm can also use the parameter reference read or write to detect the error.
<parameter_reference_name>.Read() If <parameter_reference_name>.ReadStatus = CABAccStatusEnum.ReRefFail then ' do error process for the Re-Reference failure
The CAB algorithm can also examine the parameter reference TextRef property to see if it has been set to the error string to detect an error in the rebinding. The TextRef property will be set to a string that starts with "<err."
8.7.4
Checking for re-references in process
The CAB algorithm can detect if any re-reference action is currently underway by checking the rereference state parameter X_REFSTATE:
If ( NOT X_REFSTATE = CABReRefState.IDLE ) then ' some re-reference is being done, maybe skip this execution cycle
This might be useful to detect when the algorithm should skip the execution cycle because some of the parameter references are being modified.
This check might be necessary because the parameter references become unusable as soon as the re-reference names are stored. In this case, some of the parameter references will work properly and some will return errors.
For parameter references that are in the process of translating a new name, if the algorithm attempts to read or write through the parameter reference, an error status of ReRefBusy is returned. This can also be used to detect a re-reference in progress.
- 143 -
8.8
Chapter 8 - CAB configuration
Re-referencing from an external agent using the TEXTREF parameter
When you enable a parameter reference for dynamic re-referencing in the PDE, the CAB buildtime infrastructure creates a new string parameter. The parameter holds the reference target name in the form, <parameter_reference_name>.TEXTREF. Note that this parameter includes a period, which is unusual, and which, in fact, is a form users are not allowed to create. This parameter is not to be confused with the TextRef property, which is present on all parameter reference types and which can only be used by the CAB algorithm.
The TEXTREF parameter is valid only when dynamic re-referencing is enabled for a parameter reference. When it is not enabled for a parameter reference and the user attempts to use it, a NullReferenceException will be thrown.
The following figure shows parameters REFIN and REFOUT, which are enabled for dynamic rereferencing. When the CAB is built, the new special parameters REFIN.TEXTREF and REFOUT.TEXTREF are created. These parameters can be exposed on a schematic or on the faceplate as shown in the figure. Note that the currently assigned reference values are displayed next to the parameters.
Figure 8.9 TEXTREF Parameters Displayed on the CAB Faceplate
8.8.1
On the project side, you cannot change the target of a re-referenceable parameter reference by assigning a value to the TEXTREF parameter. You can only do this on the monitor side. Therefore, Honeywell recommends that you do not add TEXTREF as a configuration parameter on the project side (do not expose it on the faceplate).
Entering a new reference manually
The term "manually" as used here refers to the situation where a new reference is entered by an operator, instead of by a program. It is not to be confused with the re-reference mode, which can be either MANUAL or AUTO when a human enters reference names.
An operator can enter a new parameter reference target name on the Parameter References tab of the CAB properties form in the Control Builder monitor view. This action can also be performed from a faceplate display or schematic if the TEXTREF parameter is displayed. The operator can enter the name directly or use the point picker. A check is made to see if the new name entered is different than the current name. If the names are identical, no re-reference action will take place and the existing connection will remain active. If the names are not identical, the new name will be accepted and the translation to a handle will begin. The re-reference state parameter X_REFSTATE will change from IDLE to TRANSLATING. While translating, TEXTREF will contain the string "<BUSY>name" or "<PENDING>name"where "name" is the new target name that was stored. If the
- 144 -
Chapter 8 - CAB configuration
translation fails, the parameter reference name displayed will change to "Err 2957" and the TEXTREF parameter will be set to a string of the form "<err xxxx>name" where "xxxx" is the specific error code from the translation and "name" is the new target name that was stored. A failed status will be returned if the user attempts to use a parameter reference that has failed re-reference.
When appearing in a TEXTREF, <PENDING> indicates that a new name has been recognized but, the translation process has not yet begun. The <PENDING> will change to <BUSY> when the translation process begins.
If the re-reference mode parameter X_REFMODE is set to MANUAL, the operator must also set the commit command by storing COMMIT to the re-reference commit parameter X_REFCOMMIT after all new references have been stored. Alternatively, the operator can cancel the re-reference operation by storing CANCEL to X_REFCOMMIT.
When the re-reference is complete, the X_REFSTATE parameter will change to IDLE.
8.8.2
Entering a new reference programmatically
Other blocks can also initiate the re-referencing of a parameter reference. Another block will store a new text reference to the <parameter_reference_name>.TEXTREF parameter on the CAB instance. A check is made to see if the new name entered is different than the current name. If the names are identical, no re-reference action will take place and the existing connection will remain active. If the names are not identical, the new text name will be accepted and the translation to a handle will begin. The re-reference state parameter X_REFSTATE will change from IDLE to TRANSLATING.
If the translation fails, the parameter reference name displayed will change to "Err 2957" and the TEXTREF parameter will be set to a string of the form "<err xxxx>name" where "xxxx" is the specific error code from the translation and "name" is the new target name that was stored. The parameter reference will be left in a failed state and will be unusable. A failed status will be returned if the user attempts to use a parameter reference that has failed re-reference.
If a re-reference action fails for a parameter, a parameter reference property is accessible to the algorithm to make it simple to detect the error. The code can use the following to determine if a parameter re-reference name failed translation:
<parameter_reference_name>.IsValid
The code will return FALSE if the translation failed.
If the re-reference mode parameter X_REFMODE is set to MANUAL, the other block must also set the commit command by storing the COMMIT enumeration value to the re-reference commit parameter X_REFCOMMIT on the CAB instance.
When the re-reference action is complete, the X_REFSTATE will change to IDLE.
8.9
Checkpoint save, restore, and upload
8.9.1
Checkpointing and restoring re-referenced parameters
When parameter references are identified as re-reference enabled, they are added to the list of parameters that are captured in the checkpoint data. This will enable the restored CAB instance to reconnect to the references that were saved.
If a re-reference was in progress at the time the Checkpoint Save was performed, the CAB infrastructure will set the parameter references to NULL on LOAD. The TEXTREF parameter will be set to "<LOAD FAILED>name."
- 145 -
8.9.2
8.10
Chapter 8 - CAB configuration
Uploading re-referenced parameters
When parameter references are identified as re-reference enabled, the associated TEXTREF parameter that is created is "Uploadable."This allows the re-reference name to be saved into the monitor side of the ERDB. This value can then be "Updated to Project" to copy it to the project side of the ERDB. If a re-reference was in progress at the time the Upload was performed, the CAB infrastructure will set the parameter references to NULL on LOAD. The TEXTREF parameter will be set to "<LOAD FAILED>name."
Create a CAB instance
The process of configuring CAB instances is the same as for native block instances, and only the differences are covered here. For more information on creating instances, refer to the Control Building Guide. You can also review the Getting started tutorial in this document, which demonstrates many of the basic Control Builder steps that are used in creating a CAB type and creating a CAB instance. Double-clicking on the block symbol within the project or monitor control chart accesses the block's properties form, which has several tabs. (There are other ways to open the form, which are standard CB functionality.) The form can be used to specify and load configuration parameters, and can also be used to display view only parameters when monitoring. When the block is a CAB, the properties form has three additional tabs that are not present on the forms for native blocks. They are: l Value CDPs tab l Parameter References tab l Source tab
These are the default tabs. Other custom tabs can be configured in the PDE using the form layout feature.
TIP l The Value CDPs tab is present only if you configured value CDPs when you defined the type. Similarly, the Parameter References tab is present only if you configured parameter references when you defined the type. l You can create custom tabs and do other special properties form editing tasks in the PDE. For more information, see "Reviewing general block type functions" in the Parameter Definition Editor Reference.
8.10.1
Configure the Value CDPs tab
The following figure shows the Value CDPs tab on the properties form. It has two viewing options, depending on whether the Show Parameter Names option at the bottom of the form is checked or unchecked.
- 146 -
Chapter 8 - CAB configuration Figure 8.10 Show Parameter Names Check Box
8.10.2
The following figure shows the Value CDPs tab as it appears when the Show Parameter Names option is unchecked. In this view, the Parameter description that you entered when you created the type is listed for each CDP, along with its default value.
Figure 8.11 Value CDPs Tab with Descriptions Shown
style="width:400px;height:127px;"/>
The following figure shows the Value CDPs tab when the Show Parameter Names tab is checked. In this case, the parameter name is listed rather than the parameter description.
Figure 8.12 Value CDPs Tab with Parameters Shown
style="width:400px;height:123px;"/>
The parameters that are listed on the form are the parameters that you configured when you defined the CAB type in the IDE. The corresponding values shown for each parameter are the default values that you assigned at that time (unless you subsequently changed the default value for the instance, as described in the next paragraph).
If you were in the Project tree view when you opened the properties form, you can change a default value on the form and new value will be saved to the ERDB when the form is saved. It will then be saved to the CEE when the block is loaded, provided that the parameter's Configuration load attribute was set to LOAD when you created the type. This change of a default value will apply only to the specific block instance, and will not be reflected in other instances of the type, nor will it change the value in the type definition.
If you opened the properties form from the Monitoring view, you can change a parameter value, and when you click OK on the form, you will be prompted as to whether or not you want to save the online value:
style="width:400px;height:123px;"/>
If you click Yes, the new value will be loaded to the CEE immediately. The change will not be reflected in the ERDB, and the next time the block is loaded, the default value stored in the ERDB will be loaded. See also Value CDPs tab for CAB and CDB.
Configure the Parameter References tab
To configure static parameter references, you must open the properties form when you are in the Project view. You cannot configure or modify static parameter references in the Monitoring view. You can, however, change a parameter reference target on the Monitoring view if the parameter is enabled for dynamic re-referencing. See Entering a new reference manually.
When you select the Parameter References tab on the block properties form for the first time, the list of parameters is displayed, but the values are empty, as shown in the following figure.
- 147 -
Chapter 8 - CAB configuration Figure 8.13 Parameter References Tab
As in the case of the Value CDPs tab, you have the option of viewing the parameter names, or descriptions, depending on whether the Show Parameter Names option at the bottom of the form is checked or unchecked (see Configure Value CDPs tab). In Figure 3 and Parameter Reference tab, the parameter names are displayed. These parameter names are the alias names that you entered when you defined the block type in the IDE. On this form, you configure the parameter references that will be used for this instance of the CAB. Use the browse button at the right of each entry box to select the reference. You can also enter the parameter reference directly, but it must be valid reference that is configured on the system and saved in the database. The following figure shows a Parameter References tab that is configured with parameter references (see Parameter References tab).
Figure 8.14 Parameter Reference Tab Configured
8.10.3
Parameter Reference tab Monitor view
The following figure shows the Monitor-side view of a CAB that has one static parameter reference and one dynamically re-referenceable parameter reference configured. In this figure, note that
- 148 -
Chapter 8 - CAB configuration
the static reference is grayed out, indicating that it cannot be modified on the Monitor side. However, the dynamically re-referenceable parameter is not grayed out, indicating that a new reference target can be added or changed.
Figure 8.15 Parameter Reference Tab Viewed on the Monitor Side
8.10.4
8.10.5 8.10.6
8.11
Source tab
In the following figure, this tab is present for CAB instances. It displays the CAB algorithm. On the project side, it displays the most recent code saved to ERDB from Microsoft Visual Studio. On the monitor side, it shows the last-loaded version of code (the code that the instance is using). If you modify and save code, you must do a load to transfer the new code to the monitor side instance. The Source tab has some important uses. It can be used to compare the code that is running in the CEE (monitor side) with the code stored in the ERDB (project side). It can also be used to recover code that has been saved over. See ` Recover CAB source code.' There are situations where the CAB may not include the source code that was used to generate its algorithm. This could occur in the case where Honeywell or a third-party developer created a CAB type and considered the code to be proprietary. In these cases, the Source tab will appear as shown in the following figure.
Alarms tab
In Figure, this tab is present on CAB Properties forms. For information on the parameters that are displayed on this tab, see CAB alarms. You can change configuration values on the project side, but you must do a load to reflect them on the monitor side. You cannot change values on the monitor side.
Save the configuration
When you have completed the configuration of value CDPs, parameter references, and the other standard configuration items, click OK to close the form. The configuration information will be saved to the ERDB when you save the project chart using one of the standard CB methods.
Access files using CAB
TIP
File access is not available in CAB/C300. Attempts to use file access within a CAB/C300 program are flagged with an error indicating that such access is only allowed under distributed execution.
- 149 -
Chapter 8 - CAB configuration
The CAB file access functionality allows you to write custom blocks that do file I/O. These blocks must be configured to operate in the distributed execution mode (see Execution mode of CAB programs). You are able to create and access binary, text, and xml files using this functionality. Only local file access (files on the same ACE) is supported.
8.11.1
Programming CAB to access file data
You must use the methods that are defined for the System.IO or System.XML Namespaces of .NET. As a Visual Basic user, you may be more familiar with the methods of the FileSystem class in the Microsoft.VisualBasic Namespace, but this functionality is not supported for CAB. The CAB Function Limiter will abort the build of a CAB program if unsupported classes and/or methods are used. For more information, see Function limiter and supported namespaces.
8.11.2 8.11.3
Coding for file access
You can determine the supported methods and view coding examples in the Microsoft Visual Studio .NET help. For example, Table 40 shows how to access coding examples for text file I/O functions.
1. With the CAB development environment open, click Help > Search.
2. In the Filtered by: box, select Visual Basic.
3. In the Look for: box, type "System.IO" and then click Search.
4. In the search results, double click System.IO Namespace.
5. Click on a specific class. For example, click File.
6. Scroll down to the To do this ... table to see links to examples of various text file I/O tasks such as create, write to, read from, append to, and many others.
Recommended directory for local CAB files
When doing CAB file IO, the files are normally created on the ACE server node where the CAB is running (to access files on another system, see the following topic, Accessing files on remote systems). The CAB runs with the same security permissions as Experion PKSCDA-SP service. If CDA is configured to run as MNGR for OPC access, it will not have administrator privileges. This affects where you can create files on ACE from within CAB. The recommended directory structure for creating CAB files is under C:\ProgramData\Honeywell\Experion PKS\FileIO\<Ace server name>. This is the default path for files created by using relative paths in a Distributed CAB. If you prefer to use an absolute path to create a file in a different directory, you must have permissions to do so. Otherwise, you will get a CAB UnauthorizedAccessException.
Note: If the CAB software was installed using Custom Install Path, then ProgramData will be replaced with the value that was specified in the Experion PKS Runtime Data field in the Installation Path(s) Selection dialog box during Experion PKSinstallation. You must consult your administrator to find out what was specified for this value.
8.11.4
Accessing files on remote systems
Some special configuration steps are necessary to develop and execute a CAB type that can create, delete, read, and/or write files that are on nodes other than the ACE where the CAB is executing. These configuration steps can be divided into two categories:
- 150 -
Chapter 8 - CAB configuration
l Administrator procedure--configuring the CDA-SP service on the host ACE l User procedure--sharing the appropriate drive or folder on the remote system
The administrative procedure involves configuring the ACE process account. The ACE (and cabclient.exe process) must execute under a userid that has network credentials. By default, the ACE process will execute under the "Local System" account, which does not have network credentials. Your Administrator will have to configure the ACE process to execute under the "mngr" account. The following procedure will accomplish this. 1. Click Start > Control Panel > Administrative Tools > Services to open Services. 2. Locate the Experion PKS CDS-SP service in the Services window (right window pane). 3. Right-click and click the Properties menu item. 4. Click the Logon tab on the Properties dialog. 5. Select the This account option button under the Log on as section. 6. Click Browse and browse to the mngr account. 7. Type the mngr password in the Password and the Confirm Password text boxes. 8. Click Apply to commit the changes. 9. Click the General tab. 10. Click Stop to stop the service. 11. Click Start to start the service under the newly configured account. 12. Click OK to close the dialog.
The user procedure involves configuring the target drive or folder on the remote system. You must set up this drive or folder to be shared to allow access by your CAB program. You must also configure the shared drive or folder with the correct permissions to limit access to it. You should configure the shared drive or folder such that only the configured group can access it to read/write files. You should deny the ability for anyone to execute files from this directory. This will help to prevent users from doing tasks that you would not be doing with your CAB. The following procedure will set up a folder in which you can access files from a remote CAB. 1. If the folder does not already exist, create it. 2. Right-click the folder and click the Sharing and Security menu item. 3. Click the Sharing tab if not already selected. 4. Select the Share this folder option button. 5. Type a share name if you do not like the default. 6. Click Permissions. 7. By default, "Everyone" is given Read permission to the share. Remove this by selecting
Everyone and then clicking Remove. 8. Click Add. 9. Click Advanced. 10. Click Find Now. 11. Click Local Engineers in the list and then click OK. 12. Click OK to close the Select Users and Groups dialog. 13. With Local Engineers selected, select the Change and Read check boxes, leaving the Full
Control check box cleared. 14. Click OK to close the dialog. 15. Click the Security tab on the Properties dialog. 16. Click Add.
- 151 -
Chapter 8 - CAB configuration
17. Click Advanced. 18. Click Find Now. 19. Click Local Engineers from the list and then click OK. 20. Click OK to close the Select Users and Groups dialog. 21. With Local Engineers selected in the Group or User names window, make the appropriate
selections in the Permissions for Local Engineers such that only the Read and Write check boxes are selected for Allow. 22. Click Advanced. 23. Click Local Engineers from the Permission Entries pane. 24. Click Edit. 25. Add the Delete subfolders and files and Delete to the list that was already selected. 26. Click OK to close the dialog. 27. Clear the Allow inheritable permissions from the parent check box. 28. Click OK to close the Advanced Security settings dialog. The Special Permissions check box should now be selected, along with the Read and Write check boxes. 29. Click OK to close the properties dialog of the share.
You can now write a CAB program to access the shared folder. To access the shared folder in your CAB program, you must use the UNC name format (for example, \\server\shared folder\filename) for the filename. You cannot use the traditional local drive (such as, w:\) format. This is because the shared folder is not mapped to the ACE for you to be able to access it in this manner.
8.11.5
Timestamps with Move and Copy commands
When you copy or move files with a CAB program using the methods defined for the System.IO or System.XML Namespaces, the timestamp conventions are the same as for other Microsoft Move and Copy operations. Specifically, they will be as follows:
l For a Copy, the Date Created and Date Last Accessed timestamps on the new copy reflect the date and time of the copy operation. The Date Last Modified reflects the time that the original file was last modified.
l For a Move, the Date Created timestamp remains the date and time when the file was originally created. The Date Last Accessed timestamp shows the date and time that the file was moved. The Date Last Modified shows the time that the file was last modified.
8.12
8.12.1
Configure insertion points
Overview
In this discussion, "insertion point" refers to a place in the normal processing sequence of a block where a CAB algorithm can be inserted, and is not to be confused with the usage of "point" as tagged entity. CAB instances can be configured to execute in the "normal" way that blocks are processed in a CM. Alternatively, a CAB instance can be configured to execute at an insertion point in the processing sequence of certain other block types. In this case, the CAB instance will not execute independently.
- 152 -
Chapter 8 - CAB configuration
When inserted into a native block instance, the CAB will execute whenever the host native block is scheduled to run, and will execute when the appropriate point in the processing of the native block is reached (the configured insertion point). The host native block instance and the CAB instance being inserted must be in the same CM. The CAB must have its ACCESSLEVEL parameter set to Continuous Control (CONTCONTROL).
When used as an insertion point algorithm, a CAB can replace the standard algorithm, or it can be used to enhance other aspects of the native block's function--depending on where it is inserted.
The ACE Data Acquisition block type and many of the Regulatory Control block types can be configured to accept a CAB instance as an insertion point algorithm. Refer to Control Builder documentation for specific information about using these various insertion points.
CABs configured for distributed execution cannot be used as insertion point algorithms. Only CABs configured for atomic execution can be used.
8.12.2 8.12.3 8.12.4
RegCtl insertion points
The following table shows the available insertion points for regulatory control type block instances:
Insertion Post-Input
Table 8.19 Insertion Points for RegCtl Points Description
CAB instance inserted after input processing
Pre-Alg
CAB instance inserted prior to algorithm processing
Ctl-Alg
CAB instance inserted in place of the built in algorithm
Post-Alg
CAB instance inserted after algorithm processing
Post-CtlOut
CAB instance inserted after control output processing
DataAcq insertion points
The following table shows the available insertion points for the data acquisition point.
Insertion PV-Alg
Table 8.20 Insertion Points for Data ACQ Point Description
Custom PV algorithm
Post-PVchar
CAB instance inserted after PV characterization
Post-Clampfilt
CAB instance inserted after PV filtering and clamping
Post-PVsrc
CAB instance inserted after PV source selection
Post-Alarmproc
CAB instance inserted after alarm processing
Configuring an insertion point
Refer to the Control Builder documentation for additional information.
- 153 -
Chapter 8 - CAB configuration
8.12.5
To configure an insertion point
1. When defining the CAB type in the development environment, be sure to configure the Access Level as Continuous Control--this is important.
2. Configure the RegCtl or DataAck instance and the insertion CAB instance in the same CM and do a Save.
3. Open the properties form for the RegCtl or DataAck instance and then click the Insertion tab. 4. Configure the number of insertions (NUMINSERT), Insert Type, and CAB name (you can use
the browser button to pick the name, but do not pick a parameter even though they are listed). The result will be similar to the figure below:
style="width:400px;height:136px;"/>
5. Open the CAB properties form and configure values for any parameter references that you have defined.
6. Use either of these methods to verify that the insertion is configured correctly: l With the CAB properties form open, click either the Configuration Parameters or the Monitoring Parameters tab, select INSMASTER, and then click Add. l With the RegCtl or DataAck properties form open, click the Configuration Parameters tab, select INSBLOCK, and then click Add.
7. Save, load, and activate the CM.
Do not use graphical connections
When using a CAB as an insertion algorithm, do not use graphical connections (wire or parameter connections). CAB insertion programs usually share data only with their insertion master (the block that is using the CAB as an insertion program). When this is the case, PRefs must be used to accomplish data flow into or out of the CAB instance. This is because PRefs are the only data flow mechanism that will insure that data flow occurs in the proper sequence with respect to execution of the insertion master and the CAB program.
8.13 Test and debug the CAB
TIP
If you are developing CABs that run on C300, there are some special considerations. Refer to Debugging CAB/C300"and Exceptions And Errors.
8.13.1
Developmental debugging
There are several steps that you can take before you incorporate your CAB into a strategy that is ready for debugging in a CEE. With Control Builder, you can l Create libraries and define CAB and CDB types. l Define CDPs for your CAB and CDB types, Develop control algorithms for your CAB types, and
ensure that the code compiles without errors. l Save your types to the ERDB.
- 154 -
Chapter 8 - CAB configuration
However, in order to test your types as part of a strategy, you will need to configure them in CMs and load them into a CEE. You will undoubtedly want to debug your CAB in the context of the overall strategy, but in an off-process environment.
8.13.2
Off-process debugging
You can debug CAB programs in an off-process mode. By doing so, you can utilize the source level debug capabilities of the Microsoft Visual Studio IDE. These capabilities include single step execution, break points that can be set and viewed directly within the source code, and the ability to examine internal variables during break.
To do source level debugging, start by creating a debug build of the CAB program. To do this, build to the "debug target" within Microsoft Visual Studio. This produces a build of the program that is different from the normal "release target build in that it contains additional information to be used by the source level debugger.
The CAB infrastructure supports four parameters (EXCPTNLINENM, EXCPTNMODULE, EXCPTNMSG, and EXCPTNTYPE) that can assist in debugging code that is causing an exception (see FDPs that capture exception information).
After building, save the debug build to ERDB and load an instance of the block to a SIM-ACE. With the block instance loaded, attach the Microsoft Visual Studio debugger to the SIM-ACE OS process that is running the block instance. With the debugger attached, you can then set break points and use other Microsoft Visual Studio debugger capabilities. The Microsoft Visual Studio online documentation set includes information on the use of the Microsoft Visual Studio debugger.
You can iterate through as many variations of the block type as needed to eliminate defects, using the source level debugger to identify defects at each stage. When all defects have been removed and off-process debug is considered complete, you should do a final test of your CAB with a build to the "release target" and do a test run of the "release" built CAB. Then save this final build to the ERDB.
To insure safety, source level debugging must only be used with an off-process SIM-ACE. An alarm is generated if the remote debug monitor service is running on an ACE node. This is the service that allows breakpoints to be set, so it should be disabled on on-process ACE nodes. For more information, see Security policy.
For further information on the use of SIM-ACE, see Debug with SIM-ACE.
8.13.3
On-process debugging
You can choose to use on-process debugging in addition to or instead of off-process debugging. In some cases this may be convenient because it avoids the need to create simulation strategies to support off-process debug.
The facilities available for on-process debugging are equivalent to the facilities available for debugging instances of native block types like SCM, AUXCALC and REGCALC. You use the monitoring capabilities of CB to view run-time values of CAB parameters and draw conclusions about the correctness of the underlying code.
With CAB types, the definition of visible parameters is under your control. This means that you can define parameters to make internal data visible, either permanently to form characteristic attributes of the block, or temporarily to support debug. You can also use the Send() subroutine to forward information to the message display of Experion PKSStation. This technique can be used to construct a trace of specific block data across successive executions (see Subroutine Send()).
8.13.4
Troubleshooting information
The section on CAB and CDB troubleshooting and maintenance has information that will help you
- 155 -
troubleshoot CAB problems. Refer to the following topics: l CAB troubleshooting approach l CAB instance states l CAB alarms l Debug with SIM-ACE l CAB fault handling
8.14 Modify a CAB
Chapter 8 - CAB configuration
8.14.1
Modify/Edit CAB type with Microsoft Visual Studio
You will frequently need to modify CAB types to include algorithm defect fixes, algorithm functional enhancement, addition of CDPs, modification to attributes of existing CDPs, or deletion of CDPs. Whatever the reason, changes will happen most often while the type is in development. Less frequently they will also happen after a type has been deployed.
If you have already started an edit session and Microsoft Visual Studio is open, you can immediately make modifications. If you want to open an existing type for edit, you must consider the lock status as described in Block type locking flags. If Edit Lock is set (that is, the type is currently under edit by another engineer), you will see a message indicating that the block cannot be edited.
To open the type, right-click on the block symbol within the library tree and choose Edit Type. Alternatively, double-click on the CAB type, or choose the CAB type in the library, then go to the Edit menu, and choose Type. When Microsoft Visual Studio opens, the algorithm code window will show the executable code for this type. To see the parameter definitions for the type, open the Parameter Definition Editor.
With Microsoft Visual Studio open, edit the type as required and change or add parameter definitions and executable statements as needed. When the editing session is complete, save PDE changes and build. Repeat edit, save, and build operations until all build errors are eliminated.
After you have a clean build, you are ready to save to ERDB. When modifying a type, the procedure of saving to ERDB can be different than it is when saving a newly created type. This depends on whether instances already exist for the block type and what kinds of changes have been made to the type. These issues are discussed in Manage instances after modification of CAB type.
8.14.2
Converting CAB types created from previous releases of Visual Studio to Visual Studio 2012 format Converting CAB types created from previous releases of Visual Studio to Visual Studio 2017 format
Use the migration wizard that converts a project created from a previous version of the compiler to the Visual Studio 2017 format.
DO NOT convert CAB types that were built using Visual Studio .Net 2003/.Net 2008/.Net 2010 to Visual Studio 2012 if they will be opened with CAB software running with an older version of Visual Studio.
DO NOT convert CAB types that were built using Visual Studio .Net 2003/.Net 2008/.Net 2010 and Visual Studio 2012 to Visual studio 2017, if they will be opened with CAB software running with an older version of Visual Studio.
- 156 -
Chapter 8 - CAB configuration
8.14.3
To migrate a CAB type built using Microsoft Visual Studio .Net 2003/Visual Studio.Net 2008/Visual Studio .Net 2010 to Visual Studio 2017,:
1. To open the type, right-click the block symbol within the library tree and choose View Type or Edit Type. Alternatively, double-click the CAB type, or choose the CAB type in the library, then from the Edit menu choose Type. The following message appears.
style="width:400px;height:127px;"/>
When you open CAB types built using Visual Studio 2010, the system does not ask for conversion. After the CAB type is built and saved to the engineering repository database, it will be converted to visual studio 2012. When you open CAB types built using Visual Studio 2012, the system does not ask for conversion. After the CAB type is built and saved to the engineering repository database, it will be converted to visual studio 2017. 2. Click OK to launch the conversion wizard. The following screen appears.
style="width:400px;height:310px;"/>
3. Click OK to perform conversion and open Visual studio 2017 style="width:400px;height:200px;"/>
Converting CAB types using Microsoft Visual Studio 2012 for ACEs still running Microsoft .Net 2.0 Converting CAB types using Microsoft Visual Studio 2017 for ACEs still running Microsoft .Net 2.0
By default, CAB types edited/created by Visual Studio 2017 will work only on .NET 4.6.2 or later versions. For backward compatibility, that is, to load CAB types edited using Visual Studio 2017 to an ACE controller that is still running .NET 2.0, you need to perform a post build step to create a version of the CAB type that will run on the .NET 2.0 Framework.
The configuration of the post build step to generate .NET 2.0 dlls is done through a menu item. It is user configurable, that is, it will be set for the users that it was configured for and will not affect other users.
To build a version of the CAB type that will run on .NET 2.0
1. On the Control Builder menu, choose File > New Type > Custom Algorithm Block. 2. Type a Block Type Name. 3. Click OK.
The CAB MSVS window appears. 4. Choose File > Build > Build .Net 2.0 CABlocks.
This will set Microsoft Visual Studio to build the .NET 2.0 version of the CAB type when you perform the next step. 5. Click Build > Build Solution to execute the post build step. The resulting output window displays the status of the post build step.
- 157 -
Chapter 8 - CAB configuration
The occurrence of any error during the post build step aborts the build of both versions (.NET 2.0 and .NET 4.0) of the user program. The CAB type will be marked as INCOMPLETE. You must correct the problem or cancel the post build step if you want to build and load the CAB type.
TIP
You will not be able to navigate to the error by double clicking the errors that occur during the post build step. This is because the post build step is a separate process and is not directly integrated with the Visual Studio IDE. However, the error message descriptions are clear enough to help you identify and resolve the error.
8.14.4
Manage instances after modification of CAB type
When saving a modified block type to ERDB, you must make decisions about how to handle any preexisting instances. There are two options. Which one you use depends on whether you are in the process of debugging the block type or whether you are maintaining a block type that is already being used on process. The two options are:
l Save the modified block type under the preexisting name. This will immediately convert the project side instance. The actual operation of the block, if active, is not affected, because it will continue to use the old block until a load operation updates it with the new instance. If you have made changes such as new pins or parameters that are configured to show on the faceplate, there are special considerations. If you made these changes in the Symbol Attributes tab in the PDE, you need to delete and re-add the instance on the project side and then load to update the monitor side. If you made these changes from the project side properties form, the changes will not appear on the monitor side until you load.
l Save the modified block type under a new name, and convert the project and monitor side instances later.
The first option is used in debug scenarios. During debug, you typically go through multiple cycles of changing code and testing instances. It would be very inconvenient to manually reassign type names at every pass through the cycle. To avoid this, CB and CAB infrastructure allow modified types to be saved without name changes. Existing instances are converted automatically on the project side, subject to constraints on the nature of changes that can be made.
In the first option, a save overwrites the source code in ERDB. If you choose to update instances, the original code is eliminated from the project side. But, if you have not loaded the new code to the monitor side instances, the old code still exists there. If you want to recover the old code, you can open the source code tab on the monitor side property form, copy the old source code that is displayed there, and paste it back into Microsoft Visual Studio.
When on-process CABs must be modified, the second option is recommended. In this case, you save the modified CAB type under a new name so that none of the on-process blocks need be disturbed. Then you can inactivate the running blocks one at time, convert them to the new type, and reload them. The process of converting blocks can be carried on over an extended period of time without risk.
When you use the second option, the CAB type (program) used by the CEE instances is not overwritten within ERDB. Both the old and new types remain until you have converted all instances. After there are no remaining instances of the old type, you can delete it if desired. You cannot delete it while there are remaining instances. As long as there is an instance of the old CAB type within CEE or within ERDB, the old CAB type cannot be deleted from ERDB.
Note that a procedure exists whereby you can verify that the version of a CAB program running in CEE is the same as the version stored in ERDB. This is described in Verify match of CAB program in ERDB.
- 158 -
Chapter 8 - CAB configuration
8.14.5
User actions when saving modified CAB type
There are several conditions that can affect the save operation. To make this clear, consider the following scenario.
1. You create a block type called CONTROLLER.
2. You instantiate CONTROLLER under the name CONTROLLER1 within control module CM1.
3. You assign and load CM1.CONTROLLER1 to a CEE so that both project and monitor copies exist.
4. You now open type CONTROLLER once again and make changes.
5. You successfully build type CONTROLLER.
6. Now you attempt to save block type CONTROLLER to ERDB
The first relevant condition to affect the save operation is whether instances of the type exist within ERDB. In this case, there is an instance so you will get this warning message:
"Overwrite type and convert all ERDB instances?"
If saving a modified CAB type that was already on process, you would normally click Cancel (the default) because you would not want to overwrite an on-process CAB with one that is untested. Similarly, if debugging a new type but wanted to leave the old version in ERDB for a while longer, you would click Cancel. But, suppose that you are debugging and decide not to keep the old version of the type--you would then click OK.
At this time, another condition comes into play. This condition is the nature of the changes that have been made to the block type. For most changes, CB automatically converts all existing instances to match the new block type. This is what would happen, for example, if CDPs had been added to the type, parameter references had been added, or if any algorithm changes had been made. However, under a specific set of conditions such as deletion of a preexisting CDP or PRef, or changing the data type of a CDP or PRef, CB does not support automatic conversion.
Suppose that you had modified CONTROLLER in such a way that a CDP was deleted. CB would then respond to the save command as follows:
A "Save-As" dialog appears that gives the option of changing the name of the block type or of canceling the save operation.
Faced with this dialog, you must now save the CONTROLLER to ERDB under a new library or block name.
The fully qualified name for a CAB type consists of the library name concatenated with the block type name. Thus, at this stage in the scenario, it is sufficient to change one or the other. If the library name is left unchanged then the modified type goes into the preexisting library under a new block type name. If the block type name is left unchanged then the new block type goes into a different library under the old block type name.
To complete the scenario, suppose that you choose to leave the library name unchanged and change the block type name to "CONTROLLERB."You have now succeeded in saving the modified version of "CONTROLLER"to the original library in ERDB, under the new name "CONTROLLERB."What remains is to convert the preexisting instance, CONTROLLER1, from an instance of CONTROLLER to an instance of CONTROLLERB. The section Convert instances to modified CAB type describes how to use the CB "Convert"command.
Note that when save under a new name is done, the edit lock on the old type is automatically cleared and a new lock is opened for the newly named type. The lock remains active until you close Microsoft Visual Studio for the new block type.
If you are using the QVCS versioning system, refer to the topic QVCS support for Custom Algorithm Block"; for more information.
See Figure 1 to see a flow diagram that shows how various conditions affect the save operation. This diagram covers the most usual scenarios but does not necessarily cover every special case that might arise.
- 159 -
Chapter 8 - CAB configuration
8.14.6
Situations that require a Save As operation for a modified CAB
When you modify a CAB that has instances, there are certain situations under which you will be required to do a Save As operation. These situations are:
l You deleted a CDP or Pref.
l You changed the name of a CDP or Pref.
l You changed the data type of a CDP or Pref.
l You changed from a scalar to an array or from an array to a scalar.
l You changed the dimension of an array. For example, you changed from a one-dimensional array to a two-dimensional array.
l You changed the definition of a parameter reference by clearing the Dynamic Reference option. The reason for this is that when you configure a PRef for dynamic re-referencing, the CAB infrastructure automatically creates a new parameter. If you subsequently remove the dynamic re-reference configuration, the system automatically deletes this parameter. Deleting a parameter requires a Save As operation.
l You changed the data type of a CDP or PRef, saved the PDE data, and then changed the data type back to its original value. This will require a Save As operation when you save to ERDB.
l There are instances of this CAB type that are being used as insertion point algorithms, and you are attempting to change execution mode from atomic to distributed. Distributed execution mode is not allowed for CABs that are used as insertion point algorithms. You will be asked if you want to save the type under a different name.
l You create a CAB type and define one or more PRefs as dynamic references and then save it to ERDB. If you then change one or more of the dynamic references back to a static PRef, you must execute a Save As.
8.14.7 8.14.8
Behaviors when saving modified CAB types to ERDB
Although there is only one condition that impacts Convert of block instances from one type to another, there are several conditions that impact the save operation as illustrated in Figure 30.
Figure 8.16 Saving Modified CAB Types
style="width:400px;height:527px;"/>
Convert instances to modified CAB type
CB allows you to change a block instance from one type to another, known as "converting a block instance." A typical use of this feature is to modify an existing type, save it as a new type, and then update the existing instances of the old type. This technique avoids the need for you to delete the old instances and create new instances of the new type. Other scenarios are possible. When conversion is done, the ERDB type definition data is updated in both the project side and monitor side instances. Instances must be converted one at a time, and a subsequent load operation is required to update the CEE. Changes that you can make to the type that are allowed by the conversion function are:
l Add CDPs or change their data types. l Delete CDPs unless they have connections to other blocks. If a parameter with an external
connection needs to be deleted, the connection must be removed first. l Delete PRefs.
- 160 -
Chapter 8 - CAB configuration
l Add PRefs or change data types, but you will have run-time errors until you configure the references in the instances.
l Change the control algorithm.
To convert instances to modified CAB types
1. Identify an in-service CAB instance that needs to be converted. 2. Select the block instance to be converted in the project side chart view. 3. Right-click the instance and click Change Parent. 4. From the list that appears, select the new block type that should be assigned to the instance. 5. Click Convert. 6. After the existing instance has been converted, you can inactivate, load and reactivate the CM
that contains the CAB instance.
8.14.9
Additional notes about the convert function
Note that the convert function has fewer constraints than the Save to ERDB operation. For example, you cannot Save to ERDB a block that has parameter deletions or data type changes if there are existing instances of the block. These operations are permitted in the convert operation.
When a block instance is converted, the new type might have fewer parameters than the old type, have more parameters than the original type, or have parameters with the same name but different data type. These situations are handled as follows:
l Parameters that have the same name and data type receive the value from the original instance.
l Parameters that have the same name but different data type are initialized to their default values.
l Parameters present on the new block type but absent from the old are initialized to their default values.
l Parameters absent from the new block type but present on the old are eliminated from the new instance.
When converting instances, you might need to identify all instances of a block type. See Discover CDB dependency relationships for comments on locating instances of a type using the Search tool in Configuration Studio.
8.15 Manage CABs
8.15.1
Verify match of CAB program in ERDB
You can compare the values of parameter BLOCKTYPEID to verify that the version of a CAB program running in a CEE is the same as the version stored within ERDB. The easiest method is to use the Compare Parameters function. Right-click the CM in either the project or monitor views, and click Compare Parameters as shown in the following figure.
- 161 -
Chapter 8 - CAB configuration
TIP The CM chart window must be closed for the Compare Parameters function to work properly.
Figure 8.17 Selecting the Compare Parameters Function
The following figure shows the Compare Parameters window. Figure 8.18 Compare Parameters Window
style="width:400px;height:121px;"/> Note that the BLOCKTYPEID in the controller is different than the BLOCKTYPEID in the ERDB. This indicates that the type was modified and not loaded to the instance. Note also that the PROGNAME (0) parameter is also different. This parameter is a Globally Unique Identifier (GUID) associated with the CAB dll, and the mismatch is a further indication that the type and instance versions do not correspond. The Compare Parameters function offers another benefit. If the CM contains more than one custom block, the parameter differences will be listed for all of these blocks.
To verify the match of CAB program in ERDB
1. Open the properties form for the CAB type defined within ERDB. This can be done in one of two ways. Either open the form directly from the library tree, or open the form for an instance of the CAB type within the project tree.
2. Read the value of BLOCKTYPEID from the form. This is a 36-character alphanumeric value. 3. Open the properties form for an instance of the CAB type within the monitoring tree. 4. Read the value of BLOCKTYPEID from the form.
- 162 -
Chapter 8 - CAB configuration
5. Compare the two values.
TIP If you are interested in determining whether or not a specific code change is loaded into a monitor side instance, you can compare the code displayed on the Source tab of the monitor and project property forms.
8.15.2
View a CAB type as read only
You can use the View > Type menu option when the Library tree has focus to open, as read only, a CAB type that is under edit by another engineer. You can also use this command to open the type without setting the Edit Lock flag.
If a type is under edit and you try to open it without using the View Type command, you will be prompted to open as read only or to cancel.
8.15.3
Delete a CAB type from ERDB
You can delete CAB types from the ERDB if they are no longer needed or if they have been superseded by later versions. CB will not allow you to delete block types if there are corresponding instances on the project side or monitor side of ERDB. Similarly, CB will not allow you to delete block types if there are templates on the project side that depend on the type you are attempting to delete. If such instances or templates exist, CB will return an error message on the delete attempt.
Deletion of a CAB type is not allowed when it is open for edit.
Custom libraries that contain custom block types or user templates can also be deleted.
System security policies allow anyone with engineering access to delete CAB types.
8.15.4
Rename a CAB
You can rename a CAB type except under the following conditions: l You cannot rename a CAB type that is open for edit. l You cannot rename a CAB type, or change the library name, if the type has an instance loaded
to the monitor side.
There are no restrictions on renaming CAB instances.
8.15.5
Recover a CAB with checkpoint restore
The system is designed to insure that all data and program associated with a CAB are recovered by using the checkpoint restore command. Using a checkpoint containing CABs is no different than using a checkpoint that contains only native blocks. You select the ACE of interest and command a restore or save.
If the checkpoint restore is commanded to an ACE with a preexisting database, the existing CAB programs will be deleted and only those CAB programs that were loaded to the ACE when the checkpoint save operation was executed are reloaded.
- 163 -
Chapter 8 - CAB configuration
Also, CAB infrastructure ensures that the data restored with checkpoint restore is a unified set. If it matters to the application, CAB programmers can rely on the fact that the restored data was captured at one instant in time between block executions. Locally defined variable values are not checkpointed and therefore are not restored. CDP values are checkpointed and restored. PRef values are not saved. PRef connections are saved IF the PRef is dynamic re-reference enabled. For more information about checkpoint and restore, see the section titled "Using Checkpoint to Save and Restore Data" in the Control Building Guide.
8.15.6
Recover CAB source code
If you have a CAB loaded and running in the CEE, but have overwritten (saved over) the source code in the ERDB, there is a way to recover the source. The Source tab on the CAB properties form on the monitor side reflects the source for the code that is actually running in the CEE. You can copy the source code from this form, paste it into Microsoft Visual Studio, rebuild, and do a Save As. Then you can convert existing instances or create new instances as needed.
8.15.7
Export CAB
CABs can be exported from ERDB into a specified directory in the same manner that native blocks are exported through the File > Export menu option. The procedures and the user interface for doing so are covered in the Control Building Guide and are not duplicated here. However, some important differences are highlighted here.
When you export native blocks, it is only the instance data that is extracted from ERDB. In general, there is no need to extract native block types because they will already be defined within the ERDB that is to receive the instances upon import. CAB types, however, are different. In all likelihood, the receiving ERDB will not already have a definition of the CAB type. Therefore, in R300, functionality is provided so that when you export a CM that contains one or more CAB instances, the custom types will be selected automatically along with the CM.
System services for export and import provide special handling for name collisions in CAB types. A type name collision would occur if two engineers working with different ERDBs had coincidentally chosen the same block name and the same library name for the type they had created. Such a collision would not matter and would never be discovered unless one engineer tried to import the block type into the ERDB used by the other. But if this did happen, services associated with import would resolve the conflict by renaming the library.
To insure name collisions can be properly handled, export processing anticipates the possibility of name change by supplying an internal identifier for associated types and instances. This internal identifier is always unique and never changes. On import the identifier can be used to properly match associated types and instances even when a type name must change.
When CAB types are exported, they always bring their library name with them. You may choose whether to export the entire type content of the library or only a subset of the types. Only those block types that have been explicitly selected are exported. To export an entire library, you select all types contained within.
When a CAB type is exported, a directory structure is created. This directory structure is used when importing (see the next topic, Import CAB).
8.15.8
Protecting CAB source
CAB types can be exported without the source. When these CAB types are installed on systems, other users cannot edit or view the CAB type source code.
- 164 -
Chapter 8 - CAB configuration
Exporting CAB types without source is accomplished through a new menu item of Visual Studio 2017, that is, File > Export without Source.
8.15.9
Procedure to export CAB without the source
The following procedure illustrates how to export a CAB type without the source code.
Prerequisites
l CAB type must be in a completed state. l CAB type must be built with a clean compile and the configuration must be in "Release" mode.
The "Export without Source" menu option is enabled only when you change the configuration to "Release" and build it. However, if you modify the code and do not build it, an error is displayed stating that you cannot export unless the CAB type is in a complete state. The following figure displays a sample CAB type with the "Release" configuration.
style="width:400px;height:276px;"/>
- 165 -
Chapter 8 - CAB configuration
To export a CAB without the source
1. From the MicroSoft Visual Studio 2017, click File - > Export without Source.
The Select Directory dialog box appears.
2. Select the directory in which you want to save the opened CAB type file set and click Export. The resulting imported file set does not contain the associated source code file.
8.15.10
Import CAB
CABs can be imported from ERDB through the File > Import menu option. Block types are imported first. The system checks to see if a duplicate exists. A duplicate exists if the library/block name and the internal identifier (BLOCKTYPEID) all match. If the block is a duplicate, the import is bypassed.
- 166 -
Chapter 8 - CAB configuration
If the library/block name is different, but the BLOCKTYPEID is the same, this indicates that the library/type has gone through a name change. In this case, the instance's library/type name is changed to match that of the type being imported, and a status message is reported in file IXP_ log.txt.
If the library and block names are the same but the BLOCKTYPEID is different, the system renames the library by appending an underscore and serialization number. For example, CABLIB would be renamed the first time as CABLIB_1.
Import messages are recorded in a log file called "IXP_log.txt"within this directory:
C:\ProgramData\Honeywell\Experion PKS
Following import, you have the opportunity to change the automatically generated names.
When a custom block type (CAB or CDB) is exported from one ERDB and imported to another, the system that the type is imported to must be at an Experion release level that is the same as or later than the release level of the system that is being exported from.
8.15.11
Discover CAB dependency relationships
Experion PKSsupports services for tracing relationships between CABs and other named entities within the PKS. These services are part of the Search functionality of Configuration Studio.
All forms of dependency identification supported for native block instances and templates are also supported for CAB instances and templates. Also, the Search tool supports identification of certain dependencies that are unique to custom block types, such as:
l CAB instances that derive from a given CAB type. l CAB type from which a given CAB instance is derived. l CAB templates that derive from a given CAB type. l CAB type from which a given CAB template is derived.
8.15.12
QVCS support for Custom Algorithm Block
Prior to R400, the Qualification and Version Control System (QVCS) did not support versioning of CAB types or instances. Thus there was no direct way of tracking changes to a type that is instantiated in a control strategy, or to restore an earlier version of the custom type. QVCS, did, however, support versioning of CMs that contained CAB instances.
In R400, QVCS supports versioning of CBT types and instances. Unlike the standard system types (such as CM, SCM, RCM, I/O, and so on), all Custom Block Types (CBTs) are user-defined. Once a CBT is defined, it exists in a Custom Block Library, and is available to be used like any other block type in the system for creating instances in container objects (CM, SCM, and RCM) or for creating User Defined Templates (UDTs). CBT objects in the Library tree can be versioned like any other objects in the Project/Library tree. Also, changes to the CBT objects can be tracked in the QVCS database.
Refer to the Qualification and Version Control System document for more information about QVCS support for CBT.
8.16
Attaching to the Remote Debugger
After the administrator has configured the ACE to allow the Remote Debugging Monitor to execute and you have the required permissions, you can now attach to the Remote Debugger from your client.
- 167 -
Chapter 8 - CAB configuration
TIP
Note that the procedure to attach the remote system to the debugger is different from the one performed from Visual Studio 2003.
8.16.1
To attach to the remote debugger:
1. On the client, open the CAB type that you want to debug and that has been loaded to the ACE for edit or view only.
2. Click Debug > Attach to Process.... 3. If the program that you want to debug is running on another computer, in the Qualifier list,
select or specify the remote computer. For more information, refer to the Visual Studio Remote Debugging Setup documentation. 4. If the process is running under a different user account, select the Show processes from all users check box.
5. If the Attach to field is not set to Managed code, click Select... 6. Select Debug these code types and then choose the Managed code option leaving all the
others unchecked and click OK. 7. From the list of Available Processes, select the appropriate process: ace.exe for an atomic
execution CAB, or cabclient.exe for a distributed execution CAB. 8. Click Attach.
- 168 -
CHAPTER
9
CAB/C300 SPECIAL CONSIDERATIONS
9.1 9.2 9.3
When CAB was first introduced in Experion, it was designed to work with a single run-time platform, the ACE platform. CAB has now been enhanced to support execution of CAB types on the C300 Process Controller also. The implementation of C300 support for CAB preserves the functionality and the look and feel of the CAB/ACE product to the greatest extent possible.
Comparison of CAB/ACE and CAB/C300
The C300 controller has tighter resource constraints than ACE, which runs on a powerful, servergrade PC. As a result, CAB/C300 supports a subset of the functionality that is available in CAB/ACE. Although the run-time platforms are significantly different, CAB/ACE and CAB/C300 share a common development environment. The semantic and syntactic characteristics are virtually identical for the two CAB variations, supporting the design goal to keep CAB/C300 as a true and accurate subset of CAB/ACE functionality. The development environment, although common, is aware of the target execution platform for CAB types under development. Extensive checks are made to ensure that a CAB intended for execution on C300 does not include functionality that is only available on ACE. A new FDP, X_ PLATOPT (Platform Option), defines the intended platform, and has either the value ACEONLY (default) or ACEANDC300. Any CAB defined for C300 execution can also execute on ACE..
Purpose of this section
This user's guide contains warnings throughout whenever functionality under discussion is not available in C300. The purpose of this section is to summarize the characteristics of CAB/C300 with special emphasis on details of functionality that are different from CAB/ACE or that are excluded from the CAB/C300 subset. In most cases, developers should be able to use this section without having to review the overall guide in order to be aware of CAB/C300 development requirements. A developer can proceed knowing that the build environment rejects any attempt to incorporate functionality that is not available for a CAB destined for C300 execution. However, advance familiarity with the material in this section will prevent some development false starts.
Summary of supported functionality
This is a high-level summary of CAB/C300 functional capabilities. For CAB/ACE functions included in the CAB/C300 subset, behavior is identical except for isolated cases where differences are necessitated by the target platform. These differences are discussed in subsequent sections.
- 169 -
9.3.1
Chapter 9 - CAB/C300 special considerations
Data and algorithm
CAB/C300 supports the following commonly used fundamental data types: l Double-precision floating point l Integer l String l Boolean l Absolute time l Relative time
You can create persistent arrays of each of these types, but only as CDPs, not as private internal data. The algorithm is programmed using the VB.NET programming language. The types of programming statements supported include the following: l Arithmetic expressions l Logical expressions l If-then-else l Looping l Subroutine calls l Subroutine definitions
9.3.2 9.3.3
ECMA .NET value types
CAB/C300 supports a run-time emulation of key ECMA .NET value types. Value type support includes classes for the following: l Double precision floating point l Integer l String l Boolean l Absolute time l Relative time.
Methods of these classes form part of a fundamental toolkit for writing algorithms. For example, the Double class supports methods IsNaN() and IsInfinity(). Refer to Appendix D:ECMA .NET Data Types for a list of ECMA .NET classes and methods supported by CAB/C300.
ECMA .NET core classes
CAB/C300 supports a run-time emulation of key ECMA .NET core classes. Methods of these core classes provide additional elements of the CAB/C300's algorithmic toolkit. For example, the Math class emulation provides trigonometric, logarithmic, and other common mathematical functions. Refer to Appendix D:ECMA .NET Data Types for a list of ECMA .NET classes and methods supported by CAB/C300.
- 170 -
9.3.4 9.3.5 9.3.6 9.3.7
9.3.8
Chapter 9 - CAB/C300 special considerations
Execution
CAB/C300 blocks execute periodically as atomic units in a fashion identical to native blocks. They execute as basic blocks within a parent CM. CAB/C300 blocks can be ordered to execute between other blocks within the parent CM. They can also be used to implement insertion programs for Regulatory Control and Data Acquisition blocks in the same manner as CAB/ACE. CAB/C300 does not support distributed (background) execution.
Types and Instances
CAB/C300 follows the same pattern as CAB/ACE in that the program and its definition constitute a type from which one or more instances can be created. The creation of a CAB instance must always be preceded by CAB type creation. CAB types are inherently generic in that any configuration data or configuration reference information needed for the instance to operate is supplied during a configuration stage separate from type creation.
Custom Data Parameters (CDPs)
CAB/C300 supports CDPs (also called "Custom Parameters"). CDPs allow the CAB designer to define data owned by the block so that it is visible to other blocks within CEE and visible to the wider DCS.
Parameter References (PRefs)
CAB/C300 supports fixed PRefs. PRefs provide one of the mechanisms through which CAB instances can read (pull) or write (push) data to other blocks. Both local access and remote access are supported to the same degree as native blocks. In addition to PRefs, data connectivity between CAB instances and other blocks can also be accomplished through CM connections to CDPs. Unlike ACE, the C300 does not support data access to OPC servers through the OPC Gateway for any of its blocks. As a result, CAB/C300 instances cannot access OPC server data or ICG data. Also, CAB/C300 does not support dynamic PRefs.
Fixed Definition Parameters (FDPs)
CAB/C300 supports FDPs. Most FDPs are not visible to end users but support elements of subsystem infrastructure. Others are visible to end users and allow for the control of specific attributes of the block type. One example of a user-visible FDP is ACCESSLEVEL. Similar to CAB/ACE, CAB/C300 supports the configuration of the access level with which PRef stores are issued by the block. Choices are PROGRAM and CONTCONTROL. Two other examples are CABSTATE and CABCOMMAND. CABSTATE publishes the current CAB operating state, while CABCOMMAND allows the operating state to be changed under a restricted set of circumstances. Both FDPs are supported by CAB/C300 and behave consistently with CAB/ACE. CAB/C300 differs from CAB/ACE in that some FDPs, for example those related to dynamic rereferencing and distributed execution, are not supported. However, FDPs that are supported in CAB/C300 behave equivalently.
- 171 -
9.3.9
Chapter 9 - CAB/C300 special considerations
CEE APIs
CAB/C300 supports a set of APIs, which allow for the exchange of information relevant to the CEE operating context. This includes a property to identify the configured PERIOD of the parent CM, functions to detect start-up type, a function to send messages, a function to abort the current cycle of execution, and others.
9.3.10
Events
CAB/C300 can issue message events through the use of the Send() API. Similar to CAB/ACE, CAB/C300 can issue a fixed set of error condition alarms corresponding to data access errors or exceptions in the CAB operating state.
Also, like CAB/ACE, CAB/C300 does not directly support the creation of custom events as part of the CAB type definition. Instead, it relies on the services of native alarm blocks, such as FLAG, which can be built up as an auxiliary configuration item to support a CAB instance. FLAG blocks or other native alarm blocks like Data Acquisition can be stimulated by CAB instances through the use of PRefs, or CDPs with CM connections.
9.3.11
Fault protection
Like CAB/ACE, CAB/C300 supports a full set of fault protection capabilities which prevent end users from crashing an entire controller with a programming error. Fault protection includes detecting null reference usage, array index checking, stack checking, data validity checking on receipt of CDP stores, and long loop detection. Fault protection also includes build-time support to prevent the use of VB.NET language features that are inappropriate to the mission of process control.
Long loop detection works differently in CAB/C300 from the way it works in CAB/ACE. In CAB/ACE, the looping limit is based on a timeout condition. In CAB/C300, it is based on a branch and call counting. While a loop is executing, CAB/C300 services count the total number of backward branches and subroutine calls that are made. If the count reaches a limit that was established when the type was created, execution terminates with a loop timeout exception.
9.3.12
Detection of subset violation
From the time of its first release for CAB/ACE, the CAB build-time has employed a check to detect if a programmer has attempted to use VB.NET programming constructs that are inconsistent with the mission of process control. With the release of CAB/C300, the CAB build-time has been enhanced to support additional checks.
When CAB types that are specified to run on ACE ,C300v2 / v3 and C300v5 are built, a check is performed to see if the programmer has attempted to use programming constructs not supported within the CAB/C300 subset. If such a programming construct is found, the build fails.
While all violations of the CAB/C300 subset are detected at build-time, some may be detected differently from others. For a majority of violations, detection involves identifying the offending line of source code in the error message. For a minority of other violations, where it is not possible to identify the offending line of source code, the programmer must locate where the error occurred by deducing the nature of the error message.
9.3.13
Integration with Control Builder
CAB/C300 integrates with Experion PKSControl Builder similar to CAB/ACE. This means that the
- 172 -
Chapter 9 - CAB/C300 special considerations
user experience in creation and modification of CAB types for CAB/C300 is the same as that for CAB/ACE. Operations such as opening the CAB editing environment (MS VS.NET) from CB, saving CAB types to CB, instantiating CAB types, loading CAB types and instances to the CEE, and so on, on CAB/C300 are like what they are with CAB/ACE.
This principle of equivalence in CAB edit operations applies everywhere in Control Builder, including important instance operations such as Copy and Change Parent. When a CAB instance is copied, a new instance is created under a different name within the same or different CM. This operation is equivalent regardless of whether the CAB is to run on ACE, C300, or both. Similarly, when a CAB instance undergoes a Change Parent operation, the pre-existing instance is converted from one CAB type into another CAB type. This operation behaves equivalently regardless of whether it is an ACE or a C300 CAB type.
There are some differences between CAB/ACE and CAB/C300 with regards to build errors. The CAB/C300 subset is enforced in the build time and can give rise to errors which do not occur while building a CAB type restricted to ACE operations.
9.3.14
Simulation
CAB/C300 supports execution on the SIM-C300 simulation environment for two distinct purposes.
l Strategy Check Out (SCO)
l Operating Training Simulation (OTS), in conjunction with a high-fidelity simulator such as UniSim.
When operating in the context of a larger OTS system, CAB/C300 instances provide dynamic state data to enable features such as backup and replay.
Execution of CAB/C300 types and instances is also supported on the SIM-ACE simulation environment. .Source level debugging can be used when CAB/C300 programs run on SIM-ACE but not when they run on SIM-C300. To debug CAB/C300 programs using either SIM-C300 or the C300 itself, "black box debugging" with CB monitoring must be used.
An important goal of SIM-C300 design is to allow an entire controller configuration to be transferred either from SIM-C300 to C300 or from C300 to SIM-C300 with minimal effort. CAB/C300 supports this by building each C300-enabled CAB type so that it supports both the C300 and the SIM-C300 targets.
However, application engineers must be aware that while SIM-C300 provides functional emulation of C300 capabilities, it does not provide performance and capacity emulation of C300 capabilities. The same statement applies to CEE as a whole, not just CAB. This means that the SIM-C300 cannot be used to gauge whether a CEE configuration can be successfully hosted on a C300. As a final stage of testing, the configuration must be loaded and run on a C300.
9.3.15
Debugging
CAB/C300 types support simple program debugging either on a commissioned controller (C300) or on a simulated controller (SIM-C300) through the services of CB monitoring and through the use of the Send() function. Using these platforms, debugging is "black box" in nature, with visibility only to state data published through CDPs or through message send. If a bug is not understood, insight into the flow of program execution must be obtained by adding CDPs or message send commands which tell what the program is doing.
Like CAB/ACE types, CAB/C300 types also support source-level debugging. Source debug allows break points to be set within the VB.NET code so that data can be read directly from the halted program. However, source-level debugging is supported only when the CAB type runs on the SIMACE simulation environment.
- 173 -
Chapter 9 - CAB/C300 special considerations
Source debugging for CAB/C300 is different from CAB/ACE in one important aspect. With CAB/ACE, the language run-time used for source debugging and for control are the same. With CAB/C300, the run-time used for source debugging is different from the one that runs when CAB/C300 is used for process-connected control. However, CAB/C300 is designed so that programs debugged under CAB/ACE simulation will execute equivalently on the C300 itself. For more information, refer to the section, Debugging CAB/C300.
9.3.16
Determinism
CAB/C300 supports a level of deterministic execution on the C300 platform which is consistent with that delivered by any other CEE block. There is no code compilation that takes place on the target platform. There are no memory operations which can suspend execution long enough for control to be interrupted.
9.3.17
Program unload
CAB/C300 block types can be unloaded from the C300 as desired. Unload occurs when the last instance of the type is deleted. When CAB/C300 types are unloaded, all associated memory is freed. This means that there is no need to manage an impending "shutdown horizon"when working with CAB block types on the C300.
9.3.18
Checkpoint
CAB/C300 is fully supported within the C300 checkpoint. This means that the program is restored with the checkpoint along with the instance data. As with CAB/ACE, the data which is restored with the checkpoint consists of all write-able CDPs. Upon first execution following a checkpoint restore, the CAB algorithm gets a chance to initialize its data depending upon whether a cold or warm restart was commanded.
9.3.19
RAM Retention Restart
CAB/C300 supports restart from power down using battery-preserved memory to the same extent as CEE native blocks executing on the C300. After a re-power in which RAM has been preserved, the CAB algorithm gets a chance to initialize its data. APIs allow the program to detect whether a RAM retention restart occurred and whether CEE subsequently did a cold or warm restart.
9.3.20
Redundancy
CAB/C300 operates within the environment of a redundant C300 controller pair in a manner which is consistent with CEE native blocks. Persistent CAB data is synchronized between primary and secondary and is available on the new primary / old secondary after switchover. This includes CDPs, last fetched PRef values, and scalar data members of the CAB class.
9.3.21
On-process migration
Redundant C300 controllers can be migrated from an older to a newer version of firmware without loss of control. This is called On-Process Migration (OPM). The fundamental mechanism is based on a modified form of switchover which allows the primary and secondary to be on different
- 174 -
Chapter 9 - CAB/C300 special considerations
firmware versions. OPM necessitates the transfer of fresh data from the primary controller to the secondary controller just before switchover occurs. The transfer is done by a mechanism that is different from normal switchover so as to allow for the firmware mismatch. The data transfer must be managed in such a way that data generated by the old firmware version is correctly recognized and deployed by the new firmware version.
9.3.22
List of loaded CAB types
Like CAB/ACE, CAB/C300 supports the display of a list of loaded CAB types under the CEE block properties form. All CAB types loaded to the CEE-C300 are listed as well as a count of the instances of each type.
9.3.23
Export and Import
CAB/C300 types and instances can be exported from one Experion PKSERDB and imported to another in a manner equivalent to CAB/ACE. This allows CAB types to be distributed after development for use at other sites within an organization.
9.4
Summary of excluded functionality
This section lists elements of CAB/ACE functionality which are not supported by CAB/C300. Many of these topics are discussed at greater length later in this section on CAB/C300 special considerations.
9.4.1
Dynamic re-referencing
Dynamic re-referencing is the ability to specify a PRef address at run time as a string. CAB/ACE infrastructure works with remote name resolution services of the Experion PKSarchitecture to bind the string address to an internal binary address. CAB/ACE can then read or write the referenced parameter using the dynamically bound address.
Dynamic re-referencing is not supported by CAB/C300.
9.4.2
Distributed execution
Distributed execution is the ability to define a CAB type whose execution can be extended in time for seconds, 10s of seconds, minutes, or even longer. Such programs are useful for complex iterative calculations, for file access, and for communication operations in which the response is not guaranteed to return within the limited time span of a block execution.
CAB/ACE supports distributed execution but CAB/C300 does not. CAB/C300 supports only periodic, atomic execution in which the algorithm runs from start to finish during a short interval of time that recurs during every CM period.
9.4.3
History access
History access typically involves transfer of large quantities of data and can only be done from
- 175 -
9.4.4 9.4.5 9.4.6
9.4.7 9.4.8
Chapter 9 - CAB/C300 special considerations
within a thread of distributed execution. Because CAB/C300 does not support distributed execution, it does not support history access.
File access
C300 does not have a local disk. A similar challenge, which arises for remote access to disk and for History Access, is the need to transfer large quantities of data within a thread of distributed execution. CAB/C300 does not support File Access.
Relational database access
Relational database access, like file access, is disk-based and requires distributed execution. It is not supported by CAB/C300.
Try-Catch
Modern languages such as VB.NET support the feature of user-written exception handling based on the syntax of "Try-Catch." In the context of complex programs, this feature can be useful for clean error handling. This is particularly true in cases where reserved resources other than memory, such as an open file, would need to be released when an error occurs. Because CAB/C300 programs have no disposable resource other than memory, Try-Catch clauses are not necessary. CAB/ACE supports user-written Try-Catch, but the CAB/C300 run-time does not.
Process Special CM
Process special CM is the ability to request special execution of a Control Module by store to one of its parameters. Strictly speaking, this is not CAB functionality but is typically used in conjunction with CAB. Process special CM is supported in CEE-ACE but not in CEE-C300.
Aggregate data members of class CABlock
When a CAB type is created, there are two ways of defining persistent data. l As CDPs. l As variables (also called "data members") of the CABlock class. In this case, CAB/ACE allows a
full range of ECMA .NET data types to be used including strings, arrays, structs, and classes.
With CAB/C300, the use of data members of the CABlock class is more restricted. Only scalar data types can be used. More specifically, the following conditions apply: l Variables of simple type (floating point, integer, Boolean, absolute time, and relative time) may
be allocated as data members of the CAB class CABlock. l Variables of non-simple or aggregate type (strings, arrays, structs, and classes) may not be
allocated as data members of the CAB class CABlock.
- 176 -
Chapter 9 - CAB/C300 special considerations
One consequence of this restriction is that the VB.NET operator used to instantiate aggregate types (the "New" operator) has different semantics in CAB/C300 from those of CAB/ACE. In CAB/C300, "New" may be used to instantiate short life-span aggregates that last as long as the current execution. However, it may not be used to instantiate persistent aggregates. For more information, refer to the section Aggregates and the semantics of 'New'".
9.4.9
Structure variables
Variables of type "Structure" are aggregates. CAB/C300 does not allow aggregates to be declared as data members of the CAB class. However, the restrictions on Structure in particular go beyond this. Structure variables may not be used anywhere within a CAB/C300 program.
9.4.10
Shared variables
VB.NET allows programmers to declare class data members as Shared. This has the effect of causing each instance of the class to use the same storage for that variable. Shared Variables are different from Instance Variables, which have unique storage for each instance of the class. CAB/C300 supports instance variables only. Shared Variables are supported by CAB/ACE but not by CAB/C300.
9.4.11
Static Variables
VB.NET allows programmers to declare procedure scope variables as Statics. This has the effect of causing the variable to retain its value after the procedure exits. Static variables are different from ordinary local variables, which have procedure scope. Ordinary local variables lose their value when the procedure exits. CAB/C300 supports ordinary local variables only. Static variables are supported by CAB/ACE but not by CAB/C300.
9.4.12
ECMA .NET types
ECMA .NET supports a large set of classes and value types when hosted on a fully conformant platform. CAB/C300 emulates only a subset of these types. This subset is sufficient to meet the needs of programming within the control mission. A few examples of excluded ECMA .NET types are listed below. l Decimal l Short l Single
9.4.13
VB-only syntax
MS .NET has been implemented to support a special set of enablers for particular functions and syntax within the VB.NET programming language. This VB-only syntax is supported by CAB/ACE but is not supported by CAB/C300.
The lack of support for VB-only syntax does not handicap CAB/C300 in any way. In every case where VB-only syntax cannot be used, there is a generic ECMA .NET syntax which can be used to accomplish the same task and can be programmed within VB.NET.
- 177 -
9.5
Chapter 9 - CAB/C300 special considerations
In general, any programming construct which causes the VB.NET compiler to generate output dependent upon the namespace "Microsoft.VisualBasic,"or on any sub-namespace of that namespace, is not supported by CAB/C300. CAB programmers do not need to know all the functions defined within that namespace in order to use CAB/C300. The recommended approach is to simply use the syntax that one feels appropriate and depend on the CAB build-time to inform when a VB-only construct is used. For more information, refer to the section VB-only constructs.
CAB/C300 system considerations
9.5.1 9.5.2
Planning and design
The main planning tasks are the analysis and decision steps required to determine whether or not the CAB/C300 functionality subset is an appropriate choice for implementing your control strategy. This section talks about CAB/C300 special considerations that help you make that decision by identifying differences and exclusions in C300.
There are no other specific site, system, or hardware planning tasks different from CAB/ACE required to deploy CAB/C300 other than what is required for the C300 controllers themselves.
CAB/C300 Licensing
Licensing for CAB/C300 is similar to that of CAB/ACE. It is handled separately for the capabilities of creating or modifying CAB types, creating or modifying CAB instances, and running CAB types and instances on a controller.
l License for the capability to create and modify CAB Types Licensing of CAB types edit capability is covered by the CAB Developer License. This is a single license that covers both CAB/ACE and CAB/C300. Purchasing the license enables you to create types that run on both the ACE and C300 controllers. You cannot purchase separate licenses for CAB/ACE and CAB/C300.
l License for the capability to create and modify CAB instances The capability to edit CAB instances, for both the ACE and C300 targets, is inherent in Experion PKSCB. A CB license enables you to create CAB instances for either platform.
l License for the capability to run CAB Types in the C300 controller The CAB/C300 run-time is analogous to the CAB/ACE run-time in that it is bundled into the controller personality. Every C300 license includes the capability to run CAB types and instances. The ability to run CAB types and instances is not dependent on the CAB Developer License in any way.
9.5.3
Installation
Installation of the software to enable CAB/C300 functionality is accomplished by three different components of the overall Experion PKSinstallation.
l Installation of CAB build-time CAB build-time software makes it possible to create and edit CAB types. It is installed, subject to purchase of the CAB Developer License, along with other Experion PKSbuild-time components.
l Installation of Control Builder CB includes, as built-in functionality, the ability to build instances of CAB types that exist in the ERDB. This is a default capability included as a part of Experion PKSinstallation.
- 178 -
Chapter 9 - CAB/C300 special considerations
l Installation of CAB/C300 run-time The CAB/C300 run-time is built into the C300 firmware image. Each C300 controller is delivered with preloaded firmware appropriate to the purchased Experion PKSrelease. As part of Experion PKSinstallation, C300 firmware is saved on the hard drive of the CB server node. It can be reloaded to C300 controllers from there.
9.5.4
9.6
Configuration and setup
System enablers for CAB/C300 do not require configuration or setup activities which are different from those required to set up the CB and C300 controllers.
CAB/C300 loading considerations
9.6.1
Approaches to determine CAB/C300 loads
In general, application engineers need to take an experimental approach to determine how CAB instances fit into the CPU load of a C300. Two likely approaches are as described here.
l Build C300 configuration and monitor CPU load parameters. When CAB/C300 types are used, they are created and instantiated in CMs. The CMs are then loaded to C300s. To assess the CPU impact, application engineers may monitor instrumentation parameters as the CMs are loaded. Performance parameters available on the CEE block form may be used to observe CPU load. CPUFREEAVG gives the time average of the free CPU available in the entire C300. CPUCYCLEAVG[I] gives the time average of the CPU used in the processing of CEE cycle I. CPUCYCLEAVG[40] gives the average over all cycles of the time average of CPU use in each cycle. Many CAB/C300 programs consume a level of CPU not much greater than that of the CEE PID block. For such CAB types, using the simple approach of monitoring CPU consumption while building up a C300 configuration works just as well as it does for native blocks.
l Characterize a CM as part of algorithm design. Engineers may choose to characterize CPU consumption of a CAB type and its associated CM before deploying the algorithm widely in a C300. This approach may be warranted if the CAB program is expected to use more CPU than most native blocks. The recommended technique for doing this is to use the EXECTIMER block to measure block execution time as described in section Execution timing. EXECTIMER can measure either an individual CAB instance within a CM, or an entire CM containing one or more CAB instances. The latter approach is generally preferred, given that a reusable algorithm is usually deployed as a CM containing one or more CAB instances together with a collection of instances of native blocks. If a CM with CAB has its CPU consumption characterized at the time the CAB algorithm is implemented, projections can be made as to how much CPU load is consumed by a group of CMs of that type, running at a selected period. Note that the percentage impact of a CM with known execution time on a CEE execution cycle is easily computed as follows.% CPU used by CM in a CEE cycle = 100 X CM execution time (microseconds) / 50,000
9.6.2
Effects of loading large CAB instances
Though instances as large as 160 KB can be deployed, application engineers must exercise caution when loading multiple, large-sized CAB instances to a C300. The CAB/C300 run-time protects the controller from the worst consequences of extreme configurations. However, engineers must be aware that excessive CAB configuration can put a C300 into overload. For more information on extreme configuration, refer to the section Size of Stack".
- 179 -
9.6.3 9.6.4
Chapter 9 - CAB/C300 special considerations
As a reminder to engineers, the CAB/C300 run-time issues a warning whenever a CAB instance whose size exceeds 20 KB is loaded. The message is sent in response to load of the parameter BLOCKTYPEID and appears as follows.
style="width:400px;height:181px;"/>
Application engineers should consider the total controller load they are imposing whenever they see this warning. This is true at the time of designing a CAB type. But it is even more true when configuring the C300 as a whole. Single instances of large CAB types will rarely cause overload. It is when multiple instances are used that a C300 is most likely to become overloaded. When you receive this warning, check the memory usage. Based on your judgement, you may then choose to continue loading CAB types.
Memory fragmentation in CAB/C300
CEE's user memory pool is designed so that most memory allocations are "compactable."This means that the allocations can be rearranged so that all used memory is adjacent and all free memory is coalesced into a single, large-sized allocation. Compressing memory in this manner has the advantage that the next requested allocation, no matter how large, can be satisfied as long as the total amount of free memory is sufficiently large. The memory allocated for CAB/C300 programs is different in that it is not compactable. After it has been allocated, it remains in the same location until the program is deleted. The presence of noncompactable allocations prevents all free memory from being grouped into a single allocation. It may be possible for much of the free memory to be grouped into a single, large-sized allocation but some of it will remain dispersed in smaller chunks. Free memory is in this state is called "fragmented." Generally, the presence of fragmented memory does not affect C300 operation. For example, it does not change the performance of memory access operations at all. However, in extreme cases, it can prevent the successful load of large CAB programs. If a user wants to load a program, but CEE does not have a block of free memory large enough to accommodate the program, then the load will fail.
Example of a CAB load failure due to memory fragmentation
Chances of a failed program load are greatest if the type to be loaded is large and there is little free memory in the CEE user memory pool. Users are encouraged to keep a significant amount of free CEE memory to reduce the likelihood of this occurrence. Consider the following example as an illustration of a case where a CAB load can fail due to fragmentation. l An application engineer has configured a C300 with a very heavy memory load. Of the 16,000
KB of memory available in the CEE-C300 user memory pool, 15,000 KB has been used. 1,000 KB remains. l The 1,000 KB of memory that remains is fragmented. While total free memory is equal to 1,000 KB, as determined by reading parameter FREEMEM from the Memory tab of the CEE-C300 form, the largest free block size is only 250 KB, as determined by reading parameter MAXFREEBLKSZ. l The user would now like to load an instance of a CAB type who size is 400 KB. When the load is attempted, the following message appears.
style="width:400px;height:180px;"/>
- 180 -
9.6.5
Chapter 9 - CAB/C300 special considerations
Guidelines to troubleshoot CAB load failures due to memory fragmentation
When the above error message is received, there is no impact to ongoing control operations within the C300 but, there may be no practical way for the user to load the CAB type. Options available will be as follows: l Shut down the controller and reload the entire configuration. l Shut down the controller and restore from checkpoint. l Remove the configuration that is already loaded, especially CMs with CAB instances.
In some cases, there is another alternative available: Freeze-And-Switchover. For more information, refer to the section Freeze-And-Switchover. In general, the following guidelines should be adhered to. l Application engineers who plan heavy use of CAB/C300, use of large CAB types, or both, should
avoid C300 configuration that cannot provide a large amount of usable memory. l When monitoring the spare memory that exists in a C300, application engineers must be aware
of both FREEMEM and MAXFREEBLKSZ. MAXFREEBLKSZ is the critical parameter with respect to the size of CAB types. This value forms the upper limit on the size of the next CAB type that can be loaded.
9.6.6
Freeze-And-Switchover
If you find that you cannot load a CAB type because MAXFREEBLKSZ is too small, and if your C300 is redundant, then consider doing a Freeze-And-Switchover. Freeze-And-Switchover is a menu option available from the monitoring tree view of the C300 platform block. The operation has the following characteristics.
l OPM with no firmware change. Performs a set of actions which are equivalent to On-Process Migration of the C300 except that no download of new firmware to either of the redundant partners takes place. The firmware present in both halves of the redundant pair remains unchanged across the operation of Freeze-And-Switchover.
l Control freezes for up to 10 seconds. As with a full OPM, the old secondary / new primary receives a database through a combination of two transfers. The first is restore of a rebuilt checkpoint to the secondary. The second is transfer of dynamic data from the primary to the secondary. While dynamic data is being transferred, control must be held in a frozen state. This can take as long as 10 seconds but is typically less than 10 seconds.
l Old secondary becomes new primary. Once the data transfer is complete, the former secondary becomes the new primary.
l Elimination of memory fragmentation. Creation of the database in the old secondary / new primary eliminates most or all fragmentation. After the Freeze-And-Switchover, it may be possible to load the large CAB type that had previously failed to load. Note, however, that memory defragmentation is different from the disk defragmentation that many are aware of from experience with computers. Memory defragmentation provides no performance benefits.
In many cases, users may judge that they cannot tolerate a 10 second interruption to control. In other cases, users will find the interruption tolerable and can command a Freeze-And-Switchover in order to eliminate fragmentation. In general, there is no reason to command a Freeze-AndSwitchover unless the CEE's user memory pool has reached a state where FREEMEM is large enough to support the load of a CAB type but MAXFREEBLKSZ is too small.
- 181 -
Chapter 9 - CAB/C300 special considerations
9.7
CAB execution platform specification and change
9.7.1 9.7.2 9.7.3
Platforms supported by a CAB type
When a CAB type is created, special enablers are built into it which determine the platform or platforms to which it can be loaded. An application engineer must deliberately decide whether the type is to be able to run on the ACE platform only or on both the ACE and C300 platforms. Selection of target platform(s) is accomplished through configuration of the platform option parameter, X_PLATOPT: an FDP whose value is fixed in the CAB type definition. Possible values for X_PLATOPT are as follows. l ACEONLY - Indicating that the CAB type can only run on the ACE. This is the default value. l ACEANDC300 - Indicating that the CAB type can run on both the ACE and C300.
X_PLATOPT is configured within the "Fixed" tab of the PDE along with other FDPs such as ACCESSLEVEL.
Changing the platform option
X_PLATOPT may be changed from the default value of ACEONLY as soon as a CAB type is first created. It may also be changed later: after a CAB type has already been created and used. The process of changing X_PLATOPT from ACEANDC300 to ACEONLY is never problematic. Any ACEANDC300 CAB type that builds successfully has been written to conform to the CAB/C300 subset. Since CAB/ACE supports all CAB/C300 functionality, changing X_PLATOPT to ACEONLY always works. The process of changing X_PLATOPT from ACEONLY to ACEANDC300 may require changes to the VB.NET program or to options selected within PDE. As an application engineer, you can generally change X_PLATOPT to ACEANDC300 without error. But you may get errors the next time you attempt to build the type if it had used functionality outside the CAB/C300 subset. For examples of the kinds of build errors that can occur, see the section, Overview. In general, to successfully change X_PLATOPT to ACEANDC300, you must make sure that the type definition conforms to the CAB/C300 subset.
Platform option change with forced name change
There is one scenario in which an application engineer will not be able to change X_PLATOPT from ACEONLY to ACEANDC300 without changing the name of the type. The scenario is as follows. l An ACEONLY CAB type is created with one or more PRefs configured as Dynamic References. l The CAB type is saved to the ERDB
o Dynamic Parameter References are changed to static Parameter References. o EXECMODE is changed from DISTRIBUTED to ATOMIC.
l The CAB type is opened and X_PLATOPT is changed to ACEANDC300.
- 182 -
Chapter 9 - CAB/C300 special considerations
The application engineer will now be unable to save the CAB type to the ERDB without renaming it. The reason for this is that the use of Dynamic References causes an additional parameter to be defined for each PRef. The additional parameter is deleted when the type is changed from ACEONLY to ACEANDC300. CAB types cannot be saved under the same name after a parameter has been deleted.
9.7.4
9.8
Platform Specific Functionalities
With ACE, C300, and the corresponding simulation platforms as variations, there are several different types of platforms on which CAB can run. Application engineers should understand that the characteristics and capabilities of a CAB type are different based on the hosting platform. This is summarized in the following figure.
Figure 9.1 CAB Functionalities Across Platforms
style="width:400px;height:280px;"/>
It is important for application engineers to understand that while the SIM-C300 emulates functional characteristics, it does not emulate the performance and capacity characteristics of the C300 embedded controller. This observation applies to CEE configurations as a whole, not just CAB. In order to judge whether a C300 has sufficient capacity to host a particular CEE configuration, application engineers must test the configuration on a C300. SIM-C300 is only run on a SCE platform. This is different from a SIM-ACE in that the SIM-ACE is loaded on an ACE platform. Both platforms are PC based.
VB-only constructs
CAB/C300 supports programming constructs according to the mainstream capabilities of ECMA .NET. There are language functionalities unique to VB.NET that are outside mainstream .NET capabilities. These functionalities are supported by CAB/ACE but not by CAB/C300.
9.8.1
Example: CStr( )
An example of a VB-only construct not supported by CAB/C300 is shown below.
1: alue of a CDP to the operator message display. 3 ' The following works for CAB/ACE only. 4 Send("The value of CDP X is " + CStr(X.Value)) 5 ' The following works for both CAB/ACE and CAB/C300. 6 Send("The value of CDP X is " + X.Value.ToString) 7:
The fourth line above is a problem because CStr() is supported by VB.NET but is not part of ECMA .NET functionality. It depends on the namespace Microsoft.VisualBasic.CompilerServices. No methods or classes defined within the namespace Microsoft.VisualBasic or its sub-namespaces are supported by CAB/C300.
If a CAB programmer tried to compile the above source code with X_PLATOPT = ACEONLY, the CAB programmer would get no errors. If the CAB programmer tried to compile it with X_PLATOPT = ACEANDC300, the CAB programmer would see the following error in the build output window for line 4 above:
CAB Error: Not allowed to use Microsoft.VisualBasic.CompilerServices.StringType::FromDouble
- 183 -
Chapter 9 - CAB/C300 special considerations
It is easy to correct this problem by using the syntax shown in the 6th line above. The Value property of CDP X is of type Double. The Double class supports method ToString(). ToString() can be called to convert from a floating point value to a string value. Double and Double.ToString( ) are part of ECMA.NET functionality and are supported by CAB/C300.
9.8.2
Example: New String( )
A second example of a VB-Only construct is shown below. This is a modification of the example shown above.
1: 2 Dim PartOfMessage As String 3 Dim CompleteMessage As String 4 ' Send a string message to operator message display. 5 ' The following works for CAB/ACE only. 6 PartOfMessage = "The value of CDP X is " 7 CompleteMessage = New String(PartOfMessage + X.Value.ToString) 8 Send(CompleteMessage) 9 ' The following works for both CAB/ACE and CAB/C300. 10 PartOfMessage = "The value of CDP X is " 11 CompleteMessage = _ 12 (New StringBuilder(PartOfMessage + _ 13 X.Value.ToString)).ToString 14 Send(CompleteMessage)
In the second example, the programmer has used ToString() instead of CStr() so that poses no problem. However, in the 7th line, the programmer tries to instantiate the String class using the New operator. Instantiating a string this way also requires the use of a function from namespace Microsoft.VisualBasic.CompilerServices and is thus not supported by CAB/C300. If the programmer tried to compile with X_PLATOPT = ACEANDC300, the programmer would see the following error in the build output window for
line 7 above:
CAB Error: Not allowed to use Microsoft.VisualBasic.CompilerServices.CharArrayType::FromString
One way to correct this problem is shown in lines 11 and 12 of the above example. Instead of using the New operator to instantiate a String, the programmer could use the New operator to instantiate the StringBuilder class. Having instantiated a StringBuilder instance, the programmer could then convert it to a String by calling the method ToString(). The instantiation of the class StringBuilder is done using general capabilities of ECMA .NET and thus is supported by CAB/C300.
There exist ways to correct the problem that are syntactically simpler because they avoid explicit use of the New operator and the StringBuilder class. One way is to use the "+" operation to concatenate the two strings as shown in the following lines.
10: 11 CompleteMessage = _ 12 PartOfMessage + X.Value.ToString 13:
Another method is to use the Concat() function after initializing the target string within one of the two values.
10: 11 CompleteMessage = PartOfMessage 12 CompleteMessage.Concat(X.Value.ToString) 13:
9.8.3
VB-only constructs usage guidelines
In general, CAB/C300 programmers can handle VB-only subset violations as follows:
- 184 -
Chapter 9 - CAB/C300 special considerations
1. Build the CAB type using X_PLATOPT = ACEANDC300 rather than X_PLATOPT = ACEONLY. 2. Be alert for build errors that indicate a programming construct requires support from the
name space Microsoft.VisualBasic or one of its sub-namespaces. 3. Replace the VB-only programming construct with a generic .NET programming construct that
accomplishes the same purpose.
9.9
Aggregates and the semantics of 'New'
There is an important difference between CAB/C300 and CAB/ACE with respect to the semantics of the "New" operator.
"New" can be used to instantiate non-scalar objects (also called aggregate types) such as a string, array, or class. In CAB/ACE, New causes objects to be instantiated on the persistent heap, referred here as Long Term Heap (LTH). When an object is instantiated on LTH in one execution of a CAB block, it still appears on the next and subsequent executions. An object on LTH disappears only when the reference to it disappears.
CAB/C300 is different in that it does not support instantiation on Long Term Heap. Instead, it supports instantiation on a non-persistent heap, here called Short Term Heap (STH). STH can hold objects from the time they are instantiated until the end of the execution in which they were instantiated. They disappear at completion of the Execute() call in which they were instantiated. By using STH and not LTH, CAB/C300 is able to avoid implementation characteristics that could affect the deterministic execution of the C300 controller.
Refer to the following examples to understand this.
9.9.1
Example: String variable as data member of CABlock
Consider a case in which a persistent string called LastMessage is created as a data member of class CABlock. LastMessage is intended to hold, for an indefinitely long period of time, the last message sent to the operator display.
1 Public Class CABlock 2 Inherits BlockBase 3 Private LastMessage As String 4 Public Overrides Sub Execute( ) 5 Dim PartOfMessage As String 6 Dim CompleteMessage As String 7 Dim Selection As Integer 8: 9Selection = 1 10 : 11 Select Case Selection 12 Case 1 13 ' Send a string message to message display. 14 PartOfMessage = "The value of CDP X is " 15 CompleteMessage = _ 16 (New StringBuilder(PartOfMessage + _ 17 X.Value.ToString)).ToString 18Send(CompleteMessage) 19' Save the message sent in a persistent data member. 20 LastMessage = CompleteMessage 21 Case 2 22 : 23 ' Save a different message. 24 LastMessage = CompleteMessage 25 :
- 185 -
Chapter 9 - CAB/C300 special considerations
26 End Select 27 : 28 End Sub 29 End Class
Line 3, declares a reference to string LastMessage. Lines 15, 16, and 17 instantiate the string CompleteMessage on heap. Line 20 copies the string reference from CompleteMessage to LastMessage. The net result in CAB/ACE is that the string created by line 15 is persisted on LTH as LastMessage and remains on LTH indefinitely.
If the above program were built with X_PLATOPT = ACEANDC300, it would fail due to an error at line 3. The following message would appear in the build output window.
"Data Type (System.String) is not legal to use in persistent memory such as statics or CAB user block data members."
It is possible to use the New operator with CAB/C300 but not if the variable that holds the reference to the aggregate type is a persistent data member of class CABlock.
Use of the New operator with a non-persistent variable is shown in the following example.
9.9.2
Example: String variable as Local
Consider a case in which a string variable called LastMessage is created but it is a local variable instead of a data member of CABlock.
1 Public Class CABlock 2 Inherits BlockBase 3 Public Overrides Sub Execute() 4 Dim PartOfMessage As String 5 Dim CompleteMessage As String 6 Dim Selection As Integer 7 Dim LastMessage As String 8: 9 Selection = 1 10 : 11 Select Case Selection 12 Case 1 13 ' Send a string message to message display. 14 PartOfMessage = "The value of CDP X is"" 15 CompleteMessage = _ 16 (New StringBuilder(PartOfMessage + _ 17 X.Value.ToString)).ToString 18 Send(CompleteMessage) 19 ' Save the sent message in a persistent data member. 20 LastMessage = CompleteMessage 21 Case 2 22 : 23 ' Save a different message. 24 LastMessage = CompleteMessage 25 : 26 End Select 27 : 28 End Sub 29 End Class
In this example, LastMessage is a local variable within function Execute(), declared at line 7. The assignment to variable CompleteMessage at lines 15, 16, and 17 is unchanged from the previous example. Line 20 still copies the string reference from CompleteMessage to Last Message.
- 186 -
Chapter 9 - CAB/C300 special considerations
The above code meets CAB/C300 subset requirements and would build correctly with X_PLATOPT = ACEANDC300. However, it does not accomplish the intended purpose. LastMessage does not persistently hold the last message sent to the operator display. Instead, the value of LastMessage disappears at the end of every Execute() call. To get around this problem in CAB/C300, LastMessage must be implemented as a CDP rather than a variable internal to the VB program. This is shown in the following example.
9.9.3
Example: String Variable As CDP
With CAB/C300, the only way to persist an aggregate type such as String from one execution to the next is through the use of CDPs. This is shown in the following example. Here it is assumed that LASTMESSAGE is a CDP.
1 Public Class CABlock 2 Inherits BlockBase 3 Public Overrides Sub Execute() 4 Dim PartOfMessage As String 5 Dim CompleteMessage As String 6 Dim Selection As Integer 7: 8 Selection = 1 9: 10 Select Case Selection 11 Case 1 12 ' Send a string message to message display. 13 PartOfMessage = "The value of CDP X is " 14 CompleteMessage = _ 15 (New StringBuilder(PartOfMessage + _ 16 X.Value.ToString)).ToString 17 Send(CompleteMessage) 18 ' Save the sent message in a persistent data CDP. 19 LASTMESSAGE.Value = CompleteMessage 20 Case 2 21 : 22 ' Save a different message. 23 LASTMESSAGE.Value = CompleteMessage 24 : 25 End Select 26 : 27 End Sub 28 End Class
This example illustrates how CDPs can be used to persist strings even if local variables are used to algorithmically arrive at their values. Lines 14, 15, and 16 compute a string value which is resident on heap only while the Execute() method is running. Line 19 transfers the string to a CDP where its value is retained until the CDP is changed.
Intermediate steps of computation can often require the use of the New operator together with a form of heap. CAB/C300 accommodates this by providing Short Term Heap. However, if it is necessary to save the computed string value over multiple executions, it must be copied to a CDP.
9.9.4
Guidelines for using aggregate data types within CAB/C300
In general, the following guidelines must be observed when using aggregate data types within CAB/C300.
- 187 -
Chapter 9 - CAB/C300 special considerations
l CAB/C300 cannot persist any data except that which is represented as a CDP or as data members of class CABlock.
l CDPs can be of type double float, integer, time, or delta time. CDPs can be arrays of these scalar types. CDPs can be strings and arrays of strings. CDPs cannot be of any aggregate type that is not an array of scalar types: a string, or an array of strings.
l CAB/C300 can persist scalar data types as data members of CABlock. It cannot have any aggregate types as data members of CABlock.
l If a CAB type is defined such that CABlock has an aggregate data member, then a build of that type will fail when X_PLATOPT = ACEANDC300.
l CAB/C300 supports the declaration of aggregate types as local variables within subroutine Execute( ).
l CAB/C300 programmers can declare local variables of type string or string array and then persist them by copying to CDPs. Programmers can also declare local variables of type class or array of class. But they are not likely to find these declarations very useful as they cannot be copied as a whole into CDPs.
9.10 Extreme configuration
9.10.1
Size of Stack
VB.NET programs use stack whenever there is a subroutine call. CAB/C300 supports a sizeable stack allocation. However, like any finite resource, the stack allocation can be exhausted. This could happen as a result of programming error, or from a failure to adhere to good programming practices. If it does happen, the C300 as a whole does not fail. Instead, the single CAB instance incurring the fault fails. Failure is marked by a transition of CABSTATE to Terminated and report of an alarm. While in the Terminated state, the CAB instance does not execute.
There are two kinds of programming practices which could lead to exhaustion of CAB/C300 stack.
l Excessive depth of nested subroutine calls. l Excessive count of subroutines calls from a single calling routine.
Excessive Call Nesting
CAB/C300 allows a depth of nested subroutine calls which is generally sufficient to cover the needs of any realistic program written to be consistent with the mission of level one process control.
The quantity of stack used by any particular subroutine depends on how it is written. Characteristics of a subroutine that cause stack usage to vary consist of the following.
l Arguments and return value - Stack is allocated to hold arguments passed into the subroutine and to hold a return value if the subroutine is a function. The data type of the return argument and the data type and count of arguments affect the stack usage.
l Local variables - Stack is allocated to hold local variables used within the context of the subroutine. Data type and count of local variables affects the stack usage.
It is not necessary for CAB programmers to keep track of stack usage while they are programming. However, it can be helpful to have a rough idea of what depth of nested calls can be supported by CAB/C300. To get an idea of this, consider the following subroutines.
- 188 -
Chapter 9 - CAB/C300 special considerations
Sub SubDepth1(ByVal ArgFloat1 As Double, ByVal ArgFloat2 As Double) Dim Float1, Float2, Float3, Float4 As Double : SubDepth2(ArgFloat1, ArgFloat2) : End Sub Sub SubDepth2(ByVal ArgFloat1 As Double, ByVal ArgFloat2 As Double) Dim Float1, Float2, Float3, Float4 As Double : SubDepth3(ArgFloat1, ArgFloat2) : End Sub
SubDepth1() has 2 floating point arguments and 4 floating point local variables. SubDepth2() has exactly parallel structure. Imagine that there is an endless set of these routines with exactly the same characteristics, where SubDepth1() calls SubDepth2(), SubDepth2() calls SubDepth3() and so on. We can ask how long this nesting of calls could continue before the available stack was exhausted. The answer is that greater than 50 nested calls can be made without failure.
In practice, the nesting limit is unlikely to be reached unless some form of recursion is used. If this does happen, the program will need to be modified.
Application engineers do not need to be aware of call depth while writing CAB programs. Stack overflow is not dangerous. If it does occur, the program under test must simply be modified.
Excessive Call Count
CAB/C300 allows a large number of subroutine calls to be made from within any single routine. However, if too many calls are made, it can lead to stack exhaustion. To make this more specific, suppose a particular CAB type has a subroutine called SubUtility() with 4 arguments.
Sub SubUtility (ByVal ArgFloat1 As Double, ByVal ArgFloat2 As Double) Dim Float1, Float2, Float3, Float4 As Double : End Sub
Suppose SubUtility() is called by the Execute() routine many times as shown below.
Sub Execute() : ' First call SubUtility(Arg1,Arg2,Arg3,Arg4) : ' Second call SubUtility(Arg1,Arg2,Arg3,Arg4) : ' Nth call SubUtility(Arg1,Arg2,Arg3,Arg4) : End Sub
If the total number of subroutine calls made from a single routine, N, is very large, then the stack usage becomes very large as well. In general, N here corresponds to the total number of calls to all routines, not just a single routine as shown in the example above.
The specific number of calls that would lead to stack overflow is difficult to predict as it depends on the following:
l The specific calls being made. l The amount of stack used for local variables within the calling routine. l The number of nested calls that have been made before the calling routine starts to execute.
In general, it should be possible to make 50 or more calls from within any single subroutine.
- 189 -
Chapter 9 - CAB/C300 special considerations
In practice, it could occur that a routine makes so many calls as to cause stack overflow. If this does happen, the program will need to be modified by breaking up large routines.
Application engineers do not need to be aware of call count while writing CAB programs. Stack overflow is not dangerous. If it does occur, the program under test must simply be modified.
9.10.2 Size of Short Term Heap
When aggregates like strings are instantiated with the "New"operator, CAB/C300 allocates storage out of Short Term Heap (STH). Refer to the section, Aggregates and the semantics of 'New' for more information on the operator "New." STH has a finite size. After the end of every Execute( ) cycle, STH is emptied of all contents so that it is ready for the next execution. STH allocations are not freed while Execute( ) is processing.
If a CAB program uses heap intensively, it is possible to completely use up STH. The consequences of exhausting STH are not dangerous to the controller as a whole. The CAB instance goes into the Terminated state, ceasing to execute until commanded to do so by an operator. But CAB/C300 programmers must be aware that it is possible to exhaust STH. If an initial implementation does exhaust STH, it must be modified so that it does not.
STH is sized such that running out of space is unlikely for the majority of CAB applications. The following example illustrates a simple program that uses up all of STH and leaves the CAB instance Terminated. In the example, COUNT and MYSTRING are CDPs.
Public Overrides Sub Execute() COUNT.Value = 0 While True MYSTRING.Value = New StringBuilder( _ "01234567890123456789012345678901").ToString() COUNT.Value = COUNT.Value + 1 End While End Sub
By the time STH is used up in the above program, CDP COUNT will have a value greater than 50.
9.10.3
Size of Looping
CAB/C300 is intended to support level one process control applications. As such, the targeted use is predominantly for non-iterative programs. This does not mean that looping cannot be done. But, it does mean that CAB programmers must exercise caution if they choose to do any iterative programming within the C300.
As one point of comparison, it should be noted that CAB/C300 is far less powerful than CAB/ACE when it comes to raw processing power. This difference arises from the following two factors.
l CAB/ACE runs on a far more powerful CPU. The type of PC used to host an ACE can vary, but in general, an ACE CPU can be assumed to perform 20 to 30 times better than a C300 CPU.
l ACE has a much longer base cycle than C300. The CEE base cycle in C300 is 0.05 seconds while in ACE it is 0.5 seconds. This means that CAB/C300 has 10 times less time available to accomplish any processing assigned to it.
Considering the above differentiating factors together, application engineers should bear in mind the following.
l CAB/C300 is roughly 250 times less powerful than CAB/ACE for doing algorithmic computations.
- 190 -
Chapter 9 - CAB/C300 special considerations
An application engineer choosing to program an iterative calculation must observe the following practices.
l Preferably, use loop counts which are fixed. They should be fixed to low values.
l If it is necessary to use a loop count which can change with instance configuration, make sure the assigned configuration is limit checked and no looping takes place if the count falls outside the allowed range. Maximum loop count should be fixed to low values.
l Never do looping which is open ended, such as in a numerical computation where desired precision drives the final loop count.
l Never do looping where the value of the loop count is affected by process data or by run-time computed data.
Like CAB/ACE, the CAB/C300 run-time has built-in measures to protect the host controller if a programmer creates an uncontrolled loop. However, the CAB/C300 implementation is different. In CAB/ACE, a CAB instance is terminated if any single execution takes longer than half of the ACE base cycle (longer than 0.25 seconds). In CAB/C300, an instance is terminated if an activity counter exceeds the limit defined on the block type. This limit is established by the X_BRANCHLIM parameter which has the following characteristics.
l X_BRANCHLIM - Specifies the limit on the total count of backward branches and subroutine calls before the CAB instance is terminated. X_BRANCHLIM has a default value of 10 and a maximum value of 1000.
Using a value of X_BRANCHLIM as large as 10 is reasonable and safe in most C300 configurations. Increasing X_BRANCHLIM beyond this level requires a thorough understanding of both the CAB algorithm itself and the configuration load of the C300s where the CAB type is to be used.
Application engineers must also be aware that when a CAB type which consumes larger than normal CPU is created, it is very easy for that type to be instantiated multiple times within the CEE configuration model. This can be done by creating multiple instances within a single CM or by creating multiple instances of containing CMs. Such configuration can readily lead to processing overruns. In general, if a C300 configuration is getting cycle overruns, the first diagnostic to be performed would be to ask the following questions.
l Is the C300 running any CAB types?
l What are those types doing?
9.10.4
Redundancy Traffic
In a redundant C300, looping CAB programs which are not carefully managed can consume excessive resources. One example is Redundancy Traffic, the number of bytes per second that the primary C300 can transfer to its secondary partner.
Redundancy Transfer Count (RTC)
Every time a CAB program writes to a datum which is not a subroutine-local variable, that datum and its address must be sent from the primary controller, where the CAB executes, to the secondary controller, which is kept synchronized and ready to take over if the primary fails. There is a limit to the total number of bytes of redundancy information that can be sent and then processed by the secondary each cycle before the update mechanism becomes overloaded. Overload can not cause loss of control but can result in loss of synchronization.
Not all kinds of activity performed by a CAB program contribute to RTC. The following table summarizes the activities that do or do not contribute to RTC.
- 191 -
Chapter 9 - CAB/C300 special considerations
Read of any kind of data
Activity
Contributes Does not to RTC contribute to RTC
X
Computation using data read
X
Write of subroutine-local data - Subroutine-local data is data defined
X
using a "Dim" declaration within the Execute() subroutine or within a
user defined subroutine
Write of CABlock member data - CABlock member data is data declared X within the scope of the CABlock class using a "Private", "Protected" or "Public" declarations
Write of PRef data - PRef data is written using PRef.Value assignments X
Write of CDP data - CDP data is written using PRef.Value assignments. X For all practical purposes, no CAB program generates excessive RTC unless it does extensive writing of CDP array values within loops. Furthermore, the data which is written needs to change from its previous value in order to contribute to RTC.
The impact from high RTC comes on a per cycle basis. If any single cycle generates too much traffic, then loss of synchronization could occur, even if all the other cycles do not generate excessive traffic. The level at which RTC could result in a loss of synchronization is as follows.
l RTC Threshold Depending on the nature of the configuration, the level of RTC, which produces loss of synchronization, can vary. However, it does not occur unless RTC exceeds a critical threshold on one or more execution cycles. RTC is like CPU in that excessive use of the resource can cause undesirable behavior. Excessive CPU consumption by CEE blocks can cause cycle overruns. Excessive generation of redundancy traffic can cause loss of synchronization.
l RTC Relatively PlentifulRTC is more plentiful than block execution CPU. It is quite possible for application engineers to create CEE-C300 configurations, which exceed the CPU capacity of the underlying C300 platform, particularly when looping CAB types are used. In contrast, applications focused on the mission of level 1 control are unlikely to exceed the RTC threshold that leads to loss of synchronization.
Though unlikely, a configuration that could lead to loss of synchronization by exceeding RTC capacity would have the following characteristics.
l One or more CAB types are created which do intensive looping.
l CAB loops not only read substantial data but also write non subroutine-local data.
l Data written within the loops change value every time the loops execute.
l Multiple instances of write-intensive, looping, CAB types are created within a single CEE-C300 configuration.
C300 and CEE-C300 provide instrumentation parameters which may be used to assess the level of redundancy traffic being generated by a C300 configuration. Refer to the Redundancy Traffic Instrumentation"for more information.
9.10.5
Redundancy Traffic Instrumentation
The C300 has multiple parameters that report the state of synchronization status and redundancy load. The most important parameters for monitoring RTC resource utilization are as follows.
- 192 -
Chapter 9 - CAB/C300 special considerations
l RDNCNTCYCMAX[I] - Redundancy Count <Per> Cycle Maximum This parameter is similar to CPUCYCLEMAX[I] in that it tracks the maximum resource consumption per cycle over time. It tracks RTC instead of CPU. It can be viewed from the CEE block monitoring form. It is displayed under the CPU Loading tab, directly adjacent to the parameter CPUCYCLEMAX[I], with a column heading named Max Redun Count per Cycle (bytes). RDNCNTCYCMAX is an array. Elements 0 through 39 display the maximum RTC consumption on cycles 0 through 39 respectively. Element 40 reports the maximum of maxima across all the cycles. RDNCNTCYCMAX shows the maximum values that have occurred during the time since the last reset using parameter CEE.STATSRESET. Writing to STATSRESET causes the maxima to be reacquired starting from the present moment. The following figure displays an example of the RDNCNTCYCMAX array under the column heading Max Redun Count per Cycle (bytes).
l RDNXFERMAX - Redundancy Transfer <Rate> Maximum This parameter displays the redundancy count per second transferred from primary to secondary across the entire C300 configuration. It is displayed on the Redundancy tab of the C300 block monitoring form. Accumulation of the maximum redundancy transfer rate begins afresh whenever the parameter C300.STATSRESET is set to "On." The following figure displays an example of RDNXFERMAX (Redundancy Traffic (bytes / sec)) adjacent to the label Redundancy Traffic (bytes / sec).
While the parameters RDNCNTCYCMAX and RDNXFERMAX can be referred to at any point in time to determine the redundancy traffic impressed upon a C300 pair, it is generally not necessary to monitor these statistics while a configuration is being built up. CEE-C300 reports a Redundancy count exceeded alarm if the RTC exceeds a configured trip point. It is at that time that application engineers must consult redundancy instrumentation parameters.
9.10.6
Redundancy count exceeded alarm
CEE-C300 monitors the maximum RTC generated by any cycle once every 2 seconds. It reports a High-priority alarm if RTC exceeds a configurable trip point.
The trip point for the RTC alarms is configured with parameter RDNCNTCYCTP of the CEE-C300 block. This parameter is displayed on the Main tab in the "Alarm Info" group with the label Redun Cnt per Cycle Trippoint. When the alarm fires, the following text appears in the alarm summary display.
RDNCNTCYCTP defaults to a value of 112500 bytes. This is lower than the value at which loss of synchronization might occur. The threshold where loss of synchronization might occur is higher on a C300v5 than a C300v2 or C300v3. If desired, the trip point on a C300v5 can be set, to a value of 173900. However, it is unlikely that an RTC alarm would ever be observed on any C300 platform, even if the trip point were left at its default of 112500 bytes. If the alarm does trip, it does not clear until the maximum RTC detected across a 2-second period falls more than 10% below the configured trip point.
The following table summarizes the properties of the redundancy count exceeded alarm.
Descriptive Redun. Count Exceeded text
Event Type Alarm
Event
Priority is fixed at High
Properties
Reporting CEE-C300 block Block Type
- 193 -
9.11
Chapter 9 - CAB/C300 special considerations
Summary Maximum redundancy count generated by one or more processing cycles of the Description CEE on a C300, over the preceding 2 second interval, has exceeded the configured
trip point
Related
RDNCNTCYCTP, RDNCNTCYCMAX, RDNXFERMAX, RDNXFERAVG of C300 block
Parameters
Detailed Description
The Redundancy Count Exceeded alarm fires whenever the maximum number of redundancy tracking bytes generated in any CEE-C300 cycle exceeds the value of parameter RDNCNTCYCTP. The maximum is accumulated once every 2 seconds. The alarm clears when the observed maximum for all cycles falls to a value that is more than 10% below the configured trip point.
Recovering from redundancy count exceeded alarm
An application engineer must take the following remedial actions when an RTC exceeded alarm goes off.
l Use RTC instrumentation parameters to determine if the maximum load is spread across all cycles or concentrated on a few cycles. Reset statistics while examining the instrumentation to determine if regular, steady state load produces maxima close to the limit or if, instead, a burst condition tripped the alarm .
l Reduce the total configuration being run in the CEE-C300 by deleting CMs. CMs with CAB types would be specifically considered for deletion. Focus on those cycles in which heavy load appears to be concentrated.
l Examine, and if needed, modify CAB types deployed within the CEE-C300. CAB types with intensive looping would be specifically considered for modification or for elimination from the configuration.
l Increase the trip point of the RTC alarm if absolutely necessary, and if it is safe to do so. This might be done as a stop-gap measure to eliminate operators from having to deal with the alarm noise while an engineering solution is being worked out.
It is recommended that if the RTC trip point is increased, it should be done only on a temporary basis. The trip point should be decreased back to the default value after an engineering solution is implemented.
If a decision not to reduce the CEE-C300 configuration after an RTC alarm fires, and to leave an increased trip point value permanently in place is made, then the C300 configuration should be considered sealed and complete from that point on, at least for cycles which produce RTC near the trip point. Additional RTC load should not be added to the sensitive cycles.
Controller Restarts
Applications running within the CEE are typically designed to run continuously over a long period of time. However, in reality, controller operation might be interrupted and subsequently restarted.
When a controller starts up, it might start from a null configuration. In this case all applications, including CAB applications, are loaded from the CB with process data in its initialization state. Engineers then have to perform the complete start up procedure as per the requirements of the process.
Alternatively, a controller might start up with some amount of its previous data state preserved. This would constitute a "restart" operation. Applications must sometimes be designed to perform specific processing when commanded to restart with pre-existing data.
- 194 -
Chapter 9 - CAB/C300 special considerations
ACE supports restart through the operation of checkpoint restore. After checkpoint restore, the operator commands the controller to do either a Cold Restart or a Warm Restart. In response to this command, applications may choose to do different initializations. The initializations associated with a Cold Restart are typically more severe than those associated with a Warm Restart.
C300, like ACE, supports checkpoint restore with the associated Cold and Warm Restart commands. It also supports additional restart modalities that ACE does not support. The following list enumerates all restart modalities supported by C300.
l Warm Restart--Restart initiated by operator command, typically following a checkpoint restore.
l Cold Restart--Restart initiated by operator command, typically following a checkpoint restore.
l RAM Retention Restart--Restart following a power down during which RAM contents were preserved by local battery power.
l Switchover resulting in a Hot Restart--Restart in the new primary after normal redundancy switchover is induced by command or by failure of the old primary. Or, restart in the new primary after OPM is induced by commanded switchover as part of an On Process Migration (OPM ) procedure.
CAB infrastructure supports APIs that allow an executing program to determine whether a restart has occurred since its last execution, and if so, the type of restart.
9.11.1
CAB/C300 data across restarts
Depending upon the events that precede a restart, a CAB/C300 instance will have different elements of data preserved from its previous operating state. It is this data which the CAB program either leaves unchanged or processes in some manner when the restart event is detected.
The following table lists the data elements that are preserved across the several types of restart supported by CAB/C300.
Data category
Table 9.1 Data handling across restarts
Data description
Preserved across
Checkpoint Restore See
Note 1
Preserved Across RAM Retention Restart See
Note 3
FDPs RDERRALM.PR, WRTERRALM.PR,
Yes
Yes
EXCPTALM.PR, TRMNTALM.PR,
RDERRALM.SV, WRTERRALM.SV,
EXCPTALM.SV, TRMNTALM.SV
Preserved Across
Switchover See Note 2 See
Note 6
Yes
CDPs Access Lock Of AppDevOnly
Yes See Note Yes
Yes
4
CDPs Access Lock Of ViewOnly
No
Yes
Yes
CDPs Any Other Access Lock
Yes
Yes
Yes
PRefs Internal Cached Values
No See Note No See Note 5 Yes 5
CABlock Scalar Data Members
No
Yes
Yes
Data marked "Yes" are available for initialization processing in response to detection of Cold Restart and Warm Restart events.
- 195 -
Chapter 9 - CAB/C300 special considerations
9.11.2
APIs for restart handling
CAB supports two APIs through which a running program can learn that a system restart transition has occurred.
l Restart--A property of type RestartEnum that returns the value None on every call unless a controller restart has occurred. When a restart occurs, a non-None value is returned for the first cycle of execution following the restart.
l RRRestart-- A property of type Boolean which returns the value False on every call unless a RAM Retention Restart has occurred. Returns True for the first cycle of execution following the re-power of a C300 in which RAM contents were retained across power down. The mnemonic for the API is "RAM Retention Restart".
API RRRestart only returns True on execution cycles where API Restart returns a value not equal to None.
9.12
On-process migration
Redundant C300 controllers can be migrated from an older to a newer version of firmware without loss of control. This is called On-Process Migration (OPM). The fundamental mechanism is based on a modified form of switchover which allows the primary and secondary to be on different firmware versions.
OPM necessitates the transfer of fresh data from the primary controller to the secondary controller just before switchover occurs. The transfer is done by a mechanism that is different from normal switchover so as to allow for the firmware mismatch. The data transfer must be managed in such a way that data generated by the old firmware version is correctly recognized and deployed by the new firmware version.
9.12.1
Migration constraints
With CAB/C300, run-time data of the CAB instance is transferred from primary to secondary by the system infrastructure with minimal support required from the CAB programmer. This is done subject to the following constraints, which apply to Experion PKSmigration in general and to CAB migration in particular:
l Experion PKScontroller configuration may not change during the course of OPM. l CAB type definitions may not change during the course of OPM. l CAB instance configurations may not change during the course of OPM.
9.12.2
OPM guidelines
In order for OPM to work for CAB/C300 types and instances, CAB programmers need to be aware of the following guidelines:
- 196 -
Chapter 9 - CAB/C300 special considerations
l The state transition that a CAB instance undergoes when the new primary starts up after OPM switchover is functionally equivalent to the transition that it undergoes after a normal switchover.
l If desired, OPM switchover transition can be detected in the same manner as normal switchover, by testing for the condition (Restart = CEESwitchStart). Data may be initialized or left unchanged on OPM switchover in the same manner as any other type of restart transition.
The categories of data that system infrastructure retains across an OPM switchover are equivalent to those which are retained across normal switchover. These are described in CAB/C300 data across restarts.
Operator training simulation
CAB/C300 types and instances can be deployed within an Operator Training Simulation (OTS) system by loading them to a SIM-C300 platform. When operating under OTS, CAB instances support the simulation features of freeze, backup, and replay. They do this by sourcing dynamic state data when the SIM-C300 is frozen for a snapshot save and synchronizing that data later when the SIM-C300 is frozen for a snapshot restore.
The CAB/C300 data which is preserved across snapshot save and restore by an OTS is equivalent to the data which is preserved across C300 switchover. See " Table 46 Data handling across restarts" for a description.
The restore of dynamic state data to a CAB instance by OTS snapshot restore can be thought of as a kind of restart. However, no restart signal is sent to CAB instances when this happens. CAB blocks always start execution on unmodified data following OTS snapshot restore.
9.13
PRef string size
PRefs are defined on CAB types using the PDE in a manner analogous to CDPs. Attributes that can be assigned for each PRef include the following: l Name l Description l Data Type l Size l Data Flow l Dynamic Reference (not supported in CAB/C300)
Related topic:
9.13.1
Configuring the Size attribute
The Size attribute has been exposed and made configurable with the introduction of CAB/C300. This attribute only applies if the Data Type is String. It specifies the maximum number of characters the string may hold. Eight characters is the default value while the maximum supported value is 255 characters. Note that sizes greater than eight characters are supported in peer-topeer data access but impose a higher communication load.
When defining a PRef of type String , you must make a decision as to how large a string value is needed. In many applications, a string size of eight characters or less is sufficient. In other cases a larger string may be needed.
- 197 -
Chapter 9 - CAB/C300 special considerations
In general, declare optimal string sizes. Efficient use of memory resources is more important for CAB/C300 than it is for CAB/ACE. In particular, note that peer-to-peer transport of strings depends on buffer allocations which are reserved as long as the data reference is in use. These allocations are most efficient when the string size is limited to 8 characters or less, though larger allocations may also be used.
9.14
Parameters of time data type
Both CAB/C300 and CAB/ACE provide support for variables of time data type. This includes the following functionalities:
l Representation of absolute time within VB.NET programs using the ECMA .NET data type: DateTime.
l Representation of relative time within VB.NET programs using the ECMA .NET data type: TimeSpan.
l Representation of absolute time as CDPs and PRefs using the Experion PKSdata type TIME. l Representation of relative time as CDPs and PRefs using the Experion PKSdata type:
DELTATIME. l Representation of time of day as CDPs and PRefs using the Experion PKSdata type:
TIMEOFDAY. l Access to current value of absolute time using the ECMA .NET properties: DateTime.Now and
DateTime.UtcNow.
However, there are some differences between the CAB/C300 and CAB/ACE in how they handle time values. These are discussed in the following topics.
9.14.1
Establishing time zone and daylight saving time
CAB/ACE runs on the Windows platform and makes use of the MS .NET run-time. In MS .NET, settings for time zone and daylight saving time are controlled by the Windows operating system. The CAB/ACE is configured with the same settings as that of the OS .
CEE on ACE has additional time functionality beyond those of CAB/ACE. This includes the ACE block parameters YEAR, MONTH, DAY, HOUR, MINUTE, and SECOND, which may be used by nonCAB blocks. For these parameters, the time zone and daylight saving settings are not controlled by the underlying OS. They are controlled by the ACE configuration parameters of TIMEZONE and DAYLIGHTTIME. In a properly configured ACE, TIMEZONE and DAYLIGHTTIME always have values consistent with the settings of the underlying OS.
C300 is different from ACE in that timeTime zone and daylight saving settings are controlled exclusively by the parameters: TIMEZONE and DAYLIGHTTIME. The underlying OS has no impact. As a result, CAB/C300 derives its sense of time zone and daylight saving from these parameters and not from the underlying OS.
For C300, the TIMEZONE and DAYLIGHTTIME parameters are resident on the CEE block.
Configuration of time zone and daylight saving time for CAB/ACE and CAB/C300 are summarized in the following table.
Table 9.2 Configuration of time zone and daylight saving time
CAB/ACE
CAB/C300
Time zone
Configured on Windows OS
Configured using the parameter TIMEZONE on CEE block
- 198 -
Chapter 9 - CAB/C300 special considerations
CAB/ACE
Daylight saving time Configured on Windows OS
Affected CAB functionality
DateTime.Now property
CAB/C300 Configured using the parameter DAYLIGHTTIME on CEE block
DateTime.Now property
9.14.2
9.15
Time zone
Table 9.3 Configuration of time zone and daylight saving time CAB/C300
Configured using the parameter TIMEZONE on CEE block
Daylight saving time
Configured using the parameter DAYLIGHTTIME on CEE block
Affected CAB functionality DateTime.Now property
Precision of conversion
Both CAB/C300 and CAB/ACE store time values according to the ECMA .NET data types of DateTime and TimeSpan. These types represent time with a precision of 100 nanoseconds. The time data types of Experion, in contrast, represent time with a precision of 100 microseconds. This applies to all of the Experion PKStypes: TIME, DELTATIME, and TIMEOFDAY.
When CAB programs use time values internally, the difference in precision of representation has no impact. However, when internal CAB time values are converted to external Experion PKStime values in the form of CDPs or PRefs, there is a loss of precision in moving from the ECMA .NET representation to the Experion PKSrepresentation. The conversion has no practical effect. However, application engineers should be aware of a difference between CAB/C300 and CAB/ACE in the way in which the conversion is handled.
l CAB/ACE conversion of time data types--When converting from the ECMA .NET to the Experion PKSrepresentation, CAB/ACE produces CDP and PRef values with a precision of 1 millisecond.
l CAB/C300 conversion of time data types--When converting from the ECMA .NET to the Experion PKSrepresentation, CAB/C300 produces CDP and PRef values with a precision of 100 microseconds.
Debugging CAB/C300
CAB types with X_PLATOPT = ACEANDC300 can be debugged in any of three different target environments:
l C300 l SIM-C300 l SIM-ACE
Related topic:
9.15.1
Black box debugging on C300
CAB programs can often be debugged purely by viewing the values of CDPs. Thus, programmers can read CDP values to draw conclusions about internal program operations. While PRef values cannot be viewed directly on the CAB instance, they can be exposed by defining additional CDPs. The same applies to internal data members of the CABlock class. In addition, CAB/C300 robustness features allow CAB types to be loaded to a running C300 without affecting the execution of control
- 199 -
Chapter 9 - CAB/C300 special considerations
strategies. Using these features, many CAB/C300 programs can be debugged by loading directly to the C300 and using "black box" techniques. In cases where reading parameter values is not enough, debugging on the C300 can be extended by inserting calls to the Send() function. Any data available during execution, including local variables, can be published for the operator to view. However, if it is necessary to expose program internals with Send(), this can only be done by modifying and reloading the CAB type.
9.15.2
SIM-C300 debugging
SIM-C300 does not provide any additional debug features over C300 but allows CAB types to be debugged using a PC before C300 hardware is available. Multiple controllers can be simulated on a single PC. In addition, SIM-C300 provides for the simulation of IO blocks together with algorithm blocks. This means that control strategies which use IO and CAB together can be debugged on the SIM-C300 with the benefit of IO value substitution.
9.15.3
SIM-ACE debugging
When source level debugging is needed, SIM-ACE must be used. Source debug can save time by allowing the internal data state of the problem to be examined during execution without the need to modify the program and insert calls to Send(). When using SIM-ACE, CAB programmers should be aware that the run-time used for debug is not the same as the run-time that will ultimately be used to execute the CAB program on C300. It is recommended that when debugging a CAB/C300 type you include a step of validation on the C300.
9.16
Versioning of CAB/C300 enablers
Both CAB/ACE and CAB/C300 require compatibility between the build-time (that creates a CAB type) and run-time (that executes it) versions. Version characteristics of the build-time are encoded in FDPs on the type. Version characteristics of the run-time are encoded in parameters on the CEE block.
Because their run-time implementations are different, CAB/C300 and CAB/ACE use different parameters to encode version information. Furthermore, the two may behave differently in certain scenarios where the build-time is at a later version than the run-time of the target controller.
Related topic:
9.16.1
Comparing CAB/ACE versioning with CAB/C300 versioning
For CAB/ACE versioning, when a CAB type is built, it acquires the versioning of the build-time. This is true regardless of the particular functionalities used within the type. You cannot load a CAB type to an ACE whose CAB run-time version is incompatible with the build-time version of the CAB type. ERDB can hold up to two versions of the CAB program for each CAB type, allowing load to two different versions of the ACE target within the same Experion PKSsystem.
CAB/C300 versioning differs from CAB/ACE in that the version does not change unless new functionality is added.
- 200 -
Chapter 9 - CAB/C300 special considerations
9.17
9.17.1
CAB/C300 versioning behavior
When a CAB type is built, it acquires the versioning of the most recent element of functionality used by the type, regardless of the versioning of the build-time. When the type is loaded to a C300, the load is accepted if the target run-time supports the functionality used by the type, and is rejected if it does not. CAB types can be loaded to current or older C300 targets as long as the C300 supports the functionality used within the type. CAB types built on an older release can always be loaded to a C300 at a newer release because in this scenario the C300 will always supports the functionality they use.
CAB versioning characteristics and the associated parameters are summarized in the following table.
Table 9.4 Version related parameters
CAB/ACE
CAB/C300
Comments
FDPs that encode build-time version information on CAB type
DOTNETVER: Records the version of MS.NET used by the CAB build-time when creating the CAB type. CABSOFTVER: Records the version of HON software for each CAB type
X_ CC3MINREQV: Records the minimum version of CAB run-time in C300 required to execute the type.
ERDB can hold up to two ACE program versions for each CAB type. If neither of these has a DOTNETVER that is compatible with the target ACE, the load does not succeed. If neither of these has a CABSOFTVER that is compatible with the target ACE the load does not succeed. ERDB holds one C300 program version for each CAB type. It runs on any C300 which supports the functionality it requires. For ACEONLY CAB types X_CC3MINREQV is always zero.
Parameters DOTNETVER:
that encode Records the
run-time version of MS
version
.NET running
information within ACE.
on CEE
CABSOFTVER:
block
Records the
version of HON
software running
within ACE.
CC3SUPRTDV: Records the version of the CAB/C300 run-time within the C300.
For CAB/C300 the compatibility requirement is: CAB.X_CC3MINREQV <= CEE.CC3SUPRTDV
Note that version information for both CAB types and CEEs can be viewed before attempting a load. CAB parameters DOTNETVER, CABSOFTVER and X_CC3MINREQV can be viewed on the Main tab of the block form, opened either from the type within the library view or from an instance within the Project or Monitor view. CEE parameters DOTNETVER and CABSOFTVER can be viewed on the CAB Types Info. tab of a CEE-ACE block form. Parameter X_CC3MINREQV can be viewed on the CAB Types Info. tab of a CEE-C300 block form.
CM Process Special
Overview
Control Modules running within a CEE-ACE support the parameters: BPS and BPSDELAY. These parameters make it possible for the execution of CMs to be triggered outside of a normal execution cycle:
l CMs not configured with a period can be created which execute only as a result of storing to parameters: BPS or BPSDELAY.
l CMs which do execute periodically can be triggered to perform additional executions
- 201 -
Chapter 9 - CAB/C300 special considerations
CM Process Special (CMPS) is a capability supported by CEE on specific platforms and is independent of CAB. However, applications of CMPS tend to occur most often when coupled with CAB applications.
9.17.2
CAB/C300 behavior
ACE supports CMPS and allows CAB and CMPS to be used in conjunction. However, C300 does not support CMPS. CAB/C300 can only be used within a periodic execution model. If the parameters BPS or BPSDELAY are stored to a CM that is running within C300, they have no effect. To achieve similar behavior, CAB/C300 programmers must program their block types to include or exclude sections of code execution in response to specific CDP values.
9.18 Metadata
VB.NET programs compiled into ECMA.NET binary instructions encode the algorithm itself, rendered in binary form. They also hold additional data, known as "metadata". Metadata is not used by most algorithms. But it can be useful for certain kinds of operations. One such operation is illustrated below.
1 Public Class CABlock 2 Inherits BlockBase 3 Enum MotorState 4 Forward 5 Moving 6 Backward 7 End Enum 8 Public Overrides Sub Execute() 9 Dim CurrentState As MotorState 10 : 11 Send("Current motor stat is " + CurrentState.ToString) 12 STATESTRING.Value = CurrentState.ToString 13 : 14 End Sub 15 End Class
In the above example, the program has declared enumeration MotorState, which defines values Forward, Moving, and Backward. Within the Execute() routine, the programmer wishes to publish information about a device state, using a variable called CurrentState. CurrentState is of type MotorState and can take on any of the values of that type.
Within programming languages such as VB.NET, variables of type enumeration are coded as integers, each ordinal value corresponding to one of the enumeration member names. The ordinal value can be published without difficulty. Publishing the corresponding text name can be more difficult.
In the example above, the member name itself is published very easily in lines 11 and 12. In line 11, the phrase "CurrentState.ToString" converts the ordinal to the name string so that it can be sent to the message display. In line 12, the enumeration name is assigned to a CDP of type string called STATESTRING. What makes it possible to access the name string of an enumeration in ECMA.NET is the presence of metadata.
CAB/ACE supports the full ECMA.NET implementation complete with metadata. CAB/C300 uses a leaner implementation which does not support metadata. Thus, the example above can be successfully coded for a CAB type with X_PLATOPT equal to ACEONLY. But the build will fail for X_ PLATOPT equal to ACEANDC300. The message returned will be as follows.
"CAB Error: Not allowed to use System.Enum::ToString"
- 202 -
9.19
Chapter 9 - CAB/C300 special considerations
Error Examples when writing CAB/C300 programs
This section provides examples of errors that can arise when writing CAB/C300 programs. These examples supplement those presented in preceding sections.
Many of the errors encountered by a CAB programmer writing for C300 arise from differences between CAB/ACE and CAB/C300. Of these, many arise from the fact that CAB/C300 supports only a subset of the CAB/ACE functionality. These kinds of errors can be thought of as "subset violations".
CAB programmers should understand that, although these error descriptions provide guidance on constructs which are disallowed, it is not necessary to remember exactly what is included in the CAB/C300 subset. Most programmers will simply try to use the programming constructs they need. When they run into errors, they can refer to this documentation for further information. The general procedure is as follows.
1. Create a CAB type with X_PLATOPT equal to ACEANDC300. 2. Code an example of the VB syntax or ECMA .NET construct of interest. 3. See if build of the CAB type succeeds. 4. If the build fails and error messages are not immediately understood, refer to CAB
documentation.
9.19.1
PDE Errors And Build Errors
CAB/C300 errors can be reported in two different ways.
l Errors detected at time of PDE Save. Errors in FDP configuration are detected at the time of PDE Save and prevent the PDE Save from being completed. Such errors cause an error message to pop up in a dialog box. Any build commanded with a CAB type in this state will attempt PDE save as the first step and then display the error message again. Any attempt to save to ERDB first attempts a save of PDE, causing the error message to appear. You cannot save the CAB type to ERDB until the error is corrected.
l Errors detected at time of build. Errors in VB.NET code usage are detected at the time of build. They appear as text messages added into the output stream within the Microsoft Visual Studio build output window. Such errors prevent the build operation from being completed and force the CAB type to remain in the Incomplete state.
9.19.2 9.19.3
Dynamic PRef
CAB/C300 supports fixed parameter references but not dynamic parameter references. Any attempt to configure a CAB/C300 type with a dynamic PRef results in a PDE error message as shown below. It is not possible to build or save the type until the error is corrected.
Figure 9.2 CAB/C300 dynamic PRef subset violation error message
Distributed Execution
CAB/C300 supports atomic, periodic execution, but not distributed, background execution. Any attempt to configure a CAB/C300 type as distributed results in a PDE error message as shown below. It is not possible to build or save the type until the error is corrected.
Figure 9.3 CAB/C300 distributed execution subset violation error message
- 203 -
Chapter 9 - CAB/C300 special considerations
If a CAB/C300 program attempts to use APIs reserved for use under distributed execution, a buildtime error will occur. Use of any of the following will produce a build-time error. l X_REFCOMMIT l X_REFSTATE l Wait()
9.19.4 File access
CAB/C300 does not support access to disk resident data. Any attempt to read or write file data results in the report of an error at build-time. The error message derives from the fact that CAB/C300 cannot be defined for distributed execution, yet distributed execution is required to do file access. As an example, the following code will produce a build-time error.
1 Public Overrides Sub Execute ( ) 2 Dim sr As System.IO.StreamReader 3: 4 Sr = New StreamReader ("C:\DataFile.txt") 5 INPUTSTRING.Value = sr.ReadToEnd ( ) 6 Sr.Close ( ) 7 End Sub
The following errors will be reported for lines 4, 5, and 6 respectively. CAB Error: Not allowed to use System.IO.StreamReader. Valid in the following execution mode(s): distributed CAB Error: Not allowed to use System.IO.StreamReader::ReadToEnd. Valid in the following execution mode(s): distributed CAB Error: Not allowed to use System.IO.StreamReader::Close. Valid in the following execution mode(s): distributed
9.19.5 History access
CAB/C300 does not support access to history data from a history server. Such access is only supported under distributed execution which is disallowed for CAB/C300. As an example, the following code will produce a build-time error when X_PLATOPT is ACEANDC300.
1 Public Overrides Sub Execute( ) 2 Dim ExperionServer As Opc.Hda.Server 3 Dim PointParameter As String 4 Dim StartingTime As DateTime 5 Dim EndingTime As DateTime 6 Dim ValueCount As Integer = 0 7 Dim HistoryValues() As Double 8 Dim TimeStamps() As DateTime 9 Dim HistStatuses() As Opc.Da.Quality 10 Dim Statuses() As Opc.Hda.Quality 11 Dim OverallSts As Opc.ResultID 12 PointParameter = "ASSET_105.PIDLOOP.PIDA.PV"13 StartingTime = DateTime.UtcNow ' the current time 14 EndingTime = StartingTime.AddHours(-1) ' 1 hour ago 15 OverallSts = History.GetHistory( _ 16ExperionServer, PointParameter, _ 17StartingTime, EndingTime, _
- 204 -
Chapter 9 - CAB/C300 special considerations
18ValueCount, HistoryValues, _ 19TimeStamps, Statuses, HistStatuses) 20 If OverallSts.Failed Then 21' Report error 22 Else 23' Process data 24 End If 25 End Sub
The following error will be reported for line 15. CAB Error: The History subroutines can be used only in CABs defined for distributed execution mode. The following error will be reported for line 20. CAB Error: Not allowed to use Opc.ResultID::Failed The same applies to any other CAB APIs connected with history access. Attempts to use any of the following in a CAB/C300 block type produces build-time errors. l ExperionHistoryServerName l PHDHistoryServerName l ConnectToHDAServer() l GetHistory() l GetAVGHistory()
9.19.6
Unsupported value types
While CAB/ACE supports all value types defined within ECMA .NET, CAB/C300 supports the following types only:
l Boolean l Char l Int32 l UInt32
l Int64 l UInt64 l Double
l String l DateTime l TimeSpan
Use of value types not listed above will cause an error at the time of CAB/C300 build. An example of this is displayed below.
Public Overrides Sub Execute() Dim Value1 As Integer Dim Value2 As Int16
: Value1 = Value2 : End Sub
For the above code, the build error that appears in the build output window will be as follows.
CAB Error: local variable `Value2' is defined as type Int16 which is not supported if X_PLATOPT is configured for ACEANDC300.
- 205 -
Chapter 9 - CAB/C300 special considerations
9.19.7
Unsupported core class
CAB/C300 supports a small subset of the total set of core classes defined within ECMA .NET. Classes which are supported wholly or partially are as follows:
l Object l Math
l StringBuilder l Array
l Exception l CharEnumerator
Use of any other core classes will produce a build-time error. As an example, the following code produces an error because it uses core class Type.
Public Overrides Sub Execute() : Dim MyType As Type : End Sub
The following error will be reported in the build output window.
"System.Type is not a supported data type for CAB on C300."
9.19.8 Try-Catch clause
Try-Catch clauses cannot be used within a CAB/C300 program. Code such as the following will cause a build time error when X_PLATOPT = ACEANDC300.
1 Public Overrides Sub Execute() 2 Dim DataGroup1 As DataGroup 3 Try 4: 5 Catch e As Exception 6: 7 End Try 8 End Sub
For the above code, the following build errors would appear in the build output window for line 3.
CAB Error: Try-Catch statements are not supported if X_PLATOPT is configured for ACEANDC300.
CAB Error: Not allowed to use Microsoft.VisualBasic.CompilerServices.ProjectData::
SetProjectError
The following error will appear for line 5.
CAB Error: Not allowed to use Microsoft.VisualBasic.CompilerServices.ProjectData::
ClearProjectError
While general purpose Try-Catch clauses cannot be used within CAB/C300, sometimes, a programmer may want to simply abort the current execution when an error is detected. This can be accomplished using the Abort() function.
9.19.9
Keyword 'Structure'
The Structure keyword cannot be used within a CAB/C300 program. Code such as the following would cause a build time error when X_PLATOPT = ACEANDC300.
- 206 -
Chapter 9 - CAB/C300 special considerations
Structure DataGroup Private Value As Double Private Count As Integer
End Structure Public Class CABlock
Inherits BlockBase Public Overrides Sub Execute() Dim DataGroup1 As DataGroup : End Sub End Class
For the above code the build error that appears in the build output window would be as follows. CAB Error: "Structure" statements are not supported if X_PLATOPT is configured for ACEANDC300. Classes can be used in place of Structures within CAB/C300, but only if they do not need to be persisted from one execution to the next. Any data that needs to be persisted must be copied to CDPs.
9.19.10 Keyword 'Shared'
The Shared keyword cannot be used within a CAB/C300 program. Code such as the following would cause a build time error when X_PLATOPT = ACEANDC300.
Public Class CABlock Inherits BlockBase Private Shared CommonValue As Double Public Overrides Sub Execute()
: CommonValue = 50.0 : End Sub End Class
For the above code, the build error that appears in the build output window will be as follows. CAB Error: "Shared" statements are not supported if X_PLATOPT is configured for ACEANDC300. Shared data members are sometimes used to accomplish a form of communication between instances of the same type. With CAB/C300, all communication between block instances, be they of the same or different types, is accomplished using connections. Both PRef connections and CM connections can be used.
9.19.11 Keyword 'Static'
The Static keyword cannot be used within a CAB/C300 program. Code such as the following would cause a build time error when X_PLATOPT = ACEANDC300.
Public Overrides Sub Execute() Static Dim PersistantValue As Double
: PersistantValue = 50.0
: End Sub
For the above code, the build error that appears in the build output window will be as follows. CAB Error: "Static" statements are not supported if X_PLATOPT is configured for ACEANDC300.
- 207 -
Chapter 9 - CAB/C300 special considerations
In CAB/ACE, the Static modifier can be used to cause local variables declared within subroutines to retain their values from one execution to the next. In CAB/C300, any data that must be persisted must be defined as a CDP or as a data member of class CABlock.
9.19.12 Option Strict
CAB/C300 works best with a more rigorous use of data types than is required in the Basic programming language. VB.NET supports either a loose or strict programming style. VS .NET supports the ability to enforce strict data typing through the use of "Option Strict". Normally, a VB.NET programmer can choose whether or not to enforce strict typing for each program that is written. For CAB/C300, only Strict typing is allowed.
When a CAB type is first created, Option Strict is automatically set to On. If Option Strict is turned off and a build attempted, the build will proceed without notification provided the type is ACEONLY. However, if the type has been defined as ACEANCDC300, the following message appears.
After this message is acknowledged, Option Strict is automatically set back to On and the build proceeds.
Under normal circumstances, a CAB programmer will never encounter this message. However, it could be observed if a CAB type from a previous release is imported and changed to be ACEANDC300.
9.19.13
Late Stage Build Processing
Some types of errors cannot be detected until the CAB build-time has reached its final stage of processing. This is the stage when the CAB program is formatted for load to the C300.
When an error is detected at this stage, it is difficult for the CAB build-time to identify the specific cause within user code. The message displayed in the build window when this type of error occurs is as follows.
An error occurred in the final stage of CAB/C300 build processing. The type cannot be loaded. Check for programming errors.
An example of a coding error that can produce this message is shown below.
:
DATA(5).Value = 50.0
DATA.Value = 50.0 :
:
In this example, the programmer has defined a FLOAT64 CDP called "DATA". However, it is an array CDP, with 10 elements, not a scalar CDP. In the first line, the programmer has remembered to supply an index when writing the value of element 5. But in the second line, the programmer has not supplied any index at all. This makes the second line ambiguous. In this example, the error turns up on an attempt to write one of the CDP array elements. But the same error would occur if an attempt was made to read a CDP array element without providing an index.
When X_PLATOPT is set to ACEONLY, this error is not detected at the time of build at all. Instead, it is detected at run time by report of an exception with the following properties.
l EXCPTNTYPE = "Honeywell.CAB.Exception" l EXCPTNMSG = "DATA should have an index"
- 208 -
Chapter 9 - CAB/C300 special considerations
When X_PLATOPT is set to ACEANDC300, the build fails and the message described above appears. If a late stage build error is reported, programmers should check for statements which are referencing a CDP array without supplying an index. If such a case proves difficult to find, programmers can use the technique described in the section Resolution Of Programming Errors. This is to rebuild the CAB type with X_PLATOPT set to ACEONLY. Then load it to an ACE or SIMACE, and see if an exception is produced.
9.19.14 CAB security considerations
To maintain the security of the C300 controller or ACE where CAB blocks are run, and to ensure robust operation, site management and CAB programmers must observe the following practices.
Ensure CAB programmers and all application engineers are competent and trusted
CAB, like other configuration and programming capabilities of CEE, is intended to be applied by trusted and skilled application engineers who understand the requirements and risks of process control. Anyone granted privileges to make configuration or programming changes to CAB in an Experion controller, must be a competent and trusted individual. CAB has been designed to provide protections against catastrophic failure resulting from honest errors in configuration or programming. CAB design cannot protect against CAB programs or instances which have been created or deployed with malicious intent.
CAB programs must validate input data before using it or passing it on
CAB programmers should implement programs so that bad values are detected and rejected before being used in a computation or passed on to other control and IO objects. This applies to any and all forms of input data including data obtained from CDPs and data obtained from PRefs. If bad values were somehow injected for purposes of sabotage the CAB program should reduce system impact by validating input data before using it.
9.20
Functional differences supplement
This section summarizes CAB general functionality that is supported in both CAB/ACE and CAB/C300, but where there are differences in the specific details of the support.
9.20.1
Build stages
Build of an ACEANDC300 CAB type involves an extra stage of processing over and above that which is required to build an ACEONLY CAB type. For CAB/ACE, a successful build completes with the following messages in the build output window. ------ CAB Functionality Check starting on <File Name> ---------- CAB Functionality check complete. Build succeeded. -----For CAB/C300, a successful build is completed with the appearance of the following messages in the build output window. ------ CAB Functionality Check starting on <File Name> ---------- CAB Functionality check complete. Build succeeded. ----------- C300 Build Started ------
- 209 -
Chapter 9 - CAB/C300 special considerations
------ C300 Build Completed with No Errors -----Because they require extra stages, builds of ACEANDC300 CAB types take longer than builds of ACEONLY CAB types.
9.20.2
Character count of CAB type name
The name of each CAB type loaded to a controller, along with its instance count, can be viewed via CB monitoring. This is done by selecting the CAB Types Info tab of the CEE block form. The type name is displayed under the column CAB Friendly Name. The name that is displayed there is stored internally within the CEE block of either the ACE or the C300. There is a discrepancy between CAB/ACE and CAB/C300 in the maximum size allowed for the string stored in the CABTYPNAME. l For CAB/ACE the maximum size is 101 characters. l For CAB/C300 the maximum size is 82 characters.
Note that this string contains both the library name and the block type name as follows. "<Library Name>:<Block Type Name>" The ":" uses one character, so for CAB/C300 the total count of characters used by Library Name and Block Type Name together cannot exceed 81. If library or block are named such that this limit is exceeded, then load of the CAB instance to a C300 will fail.
9.21 Exceptions And Errors
9.21.1
Run-time Exceptions
CAB types support several FDPs which display diagnostic information following an exception. These parameters hold blank values until the CAB instance enters either the Exception or the Terminated state. The values of the exception FDPs can be viewed via CB monitoring on the Main tab of the CAB instance form.
As an example, consider the Index Out Of Range Exception. When a CAB/ACE program attempts to use an index outside the defined range of the array, the following FDPs display non-blank values.
l EXCPTNTYPE--Displays the string "System.IndexOutOfRangeException." l EXCPTNMSG--Displays the string "Index was outside the bounds of the array." l EXCPTNMODULE--Displays the name of the function executing when the exception occurred. l EXCPTNLINENM--Displays the line number where the exception originated within several CAB
related source files, including the user-written VB.NET source file.
CAB/C300 uses a leaner implementation than CAB/ACE. Thus, when an exception occurs, it is not possible to display as much information. For the example of Index Out Of Range the following information would be available.
- 210 -
Chapter 9 - CAB/C300 special considerations
l EXCPTNTYPE--Displays the string "IndexOutOfRangeException." l EXCPTNMSG--Displays the string "Index was outside the bounds of the array." l EXCPTNMODULE--Blank. l EXCPTNLINENM--Blank.
With regard to the display of exception information, ACE and SIM-ACE have equivalent behavior. Likewise, C300 and SIM-C300 have equivalent behavior.
9.21.2
Resolution Of Programming Errors
In most cases, programming errors are relatively easy to resolve by reasoning from the messages supplied. This is true for errors reported at build-time as well as errors reported at run-time as exceptions.
In some cases, it may be more difficult to resolve an error because the available information is not very clear. If this happens, users are encouraged to investigate the behavior of the type when deployed on an ACE platform as well as a C300 platform.
In the case of build-time errors that are difficult to resolve, users may perform the following procedure.
1. Build the CAB type with X_PLATOPT = ACEANDC300.
2. If a build error is reported and proves difficult to resolve, build the type again with X_PLATOPT = ACEONLY. The build error may not be produced by an ACEONLY build.
3. If the build succeeds for the ACEONLY configuration, load an instance of the type to a SIMACE or an ACE. Try to execute the instance.
4. If a run-time exception occurs, use the exception information to help guide the resolution of the problem. In the case of run-time exceptions that are difficult to resolve, users may perform the following procedure.
1. Load an instance of the type to a SIM-C300 or C300. Try to execute the instance.
2. If an exception is thrown but proves difficult to resolve, build the type again with X_PLATOPT = ACEONLY.
3. Load an instance of the type to a SIM-ACE or an ACE. Try to execute the instance.
4. Use the additional exception information provided by the ACE run-time environment to help guide the resolution of the problem.
9.21.3
Execution timing
CAB/ACE supports FDP CABEXECTIMER as a means of measuring execution time of CAB instances. CABEXECTIMER provides a constantly changing value which gives the duration of the last execution of the CAB instance in microseconds.
CAB/C300 does not support FDP CABEXECTIMER. When read from a CAB/C300 instance, CABEXECTIMER always returns the value NaN. However, execution time for CAB/C300 instances can be measured using a more general technique which applies to all CEE blocks. This technique is based on block EXECTIMER.
The general procedure for making timing measurements with EXECTIMER is as follows.
1. Create a STARTTIME instance of EXECTIMER.
- 211 -
Chapter 9 - CAB/C300 special considerations
2. Create an ENDTIME instance of EXECTIMER. 3. Connect the TIMEOUT parameter of STARTIME to the TIMEIN parameter of ENDTIME. 4. Create the CAB or CM instance for which timing is to be measured. This is the Function Block
Under Test (FBUT). 5. Order the three blocks so that the execution sequence is as follows: STARTIME, FBUT, and
ENDTIME. Make sure that all blocks have the same execution period and nothing executes between STARTIME and ENDTIME but FBUT. With a configuration such as this, an application engineer can measure instantaneous duration as is done by CABEXECTIMER. An application engineer can also get values for average, maximum, and minimum durations. While EXECTIMER can be used to measure the execution time of an individual CAB instance, this is typically not what the application engineer wants. Usually, what is of more interest is the total execution time for the CM that is being created as a toolkit item.
TIP EXECTIMER can be used to measure execution time for CMs containing CAB/ACE blocks as well as CAB/C300 blocks.
For more information on EXECTIMER parameter, refer to the Control Builder Parameter Reference.
9.21.4
Mathematical Functions
Results returned by mathematical functions evaluated by CAB/C300 and CAB/ACE programs are completely consistent when used with arguments in the normal ranges of operation. However, in some cases, CAB/C300 returns NaN when arguments are at extreme values even though CAB/ACE does not. The following table provides some examples of this.
Function Call Atan2(-1.0, -INF) Atan2(-11.0, -1.0E+17) Pow(+INF, 0.0) Pow(+INF, 10.0) Pow(+INF, -10.0) Pow(0.0, 0.0) Pow(-INF, 0.0) Pow(-INF, 9) Pow(-INF, -9) Tan(1.5707965)
CAB/ACE Result -3.141593 -3.141593 1 +INF 0 1 1 -INF 0 -5773501.94
CAB/C300 Result NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
The general rule is as follows.
CAB/C300 mathematical functions sometimes return NaN, either because of mathematical singularities at particular argument values, or because of finite precision when applied to extreme argument values. There are cases where this can happen even though it does not happen for the same function evaluation running under CAB/ACE.
- 212 -
Chapter 9 - CAB/C300 special considerations
9.21.5
Array dimensions
CAB/ACE and CAB/C300 support arrays of two different types:
l CDP arrays--CDP arrays can be used to publish data to other FBs and to the Experion PKSsystem in general. The maximum number of elements that can be supported by a CDP array is limited to 10,000.
l Internal VB variable arrays--VB local variable arrays cannot be seen outside of the CAB algorithm itself but can be used to store data internally, while the Execute() method is processing.
The maximum array dimension for custom parameter arrays is 2. This is equivalent for CAB/ACE and CAB/C300.
The maximum array dimension for internal VB arrays is different for CAB/ACE and CAB/C300. With CAB/ACE, MS .NET is used and internal array variables can have a dimension as high as 60. With CAB/C300, the dimension of internal arrays is limited to 3.
Note that, as described in Aggregates and the semantics of 'New', CAB/C300 does not support persistent internal arrays. Internal arrays can only be local subroutine variables.
9.21.6
9.22
Parameter differences
CAB/C300 functionality includes the addition and modification of certain CAB FDPs. These changes are identified here. For more information on these parameters, refer to the Control Builder Parameter Reference. Three new CAB FDPs have been added to support CAB/C300: l X_CC3MINREQV</HH>--This parameter is used in conjunction with the C300 CEE block
parameter <HH><ftw_tps@kb@Cbpr@kb@Cxxxx Parameters@kb@CC3SUPRTV>CCSUPRTDV</HH> to support CAB/C300 versioning. See Versioning of CAB/C300 enablers in this section for details. l X_PLATOPT</HH>--Configuration option that allows the CAB type designer to specify a CAB type supports execution execution on either ACE only or ACE and C300. l X_BRANCHLIM--Controls branching and subroutine calling within a CAB/C300 type to prevent uncontrolled looping or uncontrolled recursion from damaging operation of the host C300 controller.</HH>
The following FDPs are supported on CAB/ACE but are not supported on CAB/C300: l The X_EXECMODE FDP is supported in both CAB/ACE and CAB/C300, but is supported slightly
differently:
l X_EXECMODE</HH>--Distributed mode is not supported in CAB/C300. Only Atomic mode is supported.
The following FDPs are supported in both CAB/ACE and CAB/C300. l The following FDPs are supported in CEE-C300. l ENABLECAB></HH>
CAB/C300 performance and capacity
Information about CAB/C300 performance and capacity is located in this guide along with similar information about CAB/ACE performance and capacity. Click the links below to find information
- 213 -
Chapter 9 - CAB/C300 special considerations
about topics of interest. CAB/C300 configuration limits
Determine C300 configuration limits for CAB types and instances CAB/C300 memory topics
Determine C300 memory utilization Memory fragmentation in CAB/C300 CAB/C300 processing capacity Determine C300 CAB processing capacity
9.23
CAB/C300 migration and interoperability
CAB/C300 types and instances support On-Process Migration (OPM) and Interoperability in a manner that is consistent with the properties and policies of the C300 controller and the wider Experion PKSsystem. Few, if any, disciplines are imposed on application engineers or system engineers in order to achieve this.
CAB types which are created prior to R516, must be re-compiled after migrating to R516. However, it is needed only if you want to load the CAB type to C300v5. This is because C300v5 is based on a different hardware architecture.
9.23.1
Characteristics of CAB/C300 OPM support
CAB/C300 OPM support has the following characteristics:
l CAB types may not be changed during the course of OPM for a C300 which hosts the types. This is consistent with Experion PKSpolicies.
l CAB instance configurations may not be changed during the course of OPM for a C300 which hosts the instances. This is consistent with Experion PKSpolicies.
l During the course of OPM, CAB types are transferred to the C300 secondary on new firmware without explicit actions required on the part of the system engineer.
l During the course of OPM, CAB instance configurations are transferred to the C300 secondary on new firmware without explicit actions required on the part of the system engineer.
l During the course of OPM, CAB dynamic data is transferred to the C300 secondary on new firmware without explicit actions required on the part of the system engineer. The precise set of data that is transferred is described in the Controller Restarts " section.
9.23.2
Characteristics of CAB/C300 interoperability support
CAB/C300 interoperability support has the following characteristics:
l Peer communication between CEEs containing CAB types works for CEEs hosting CAB types and instances in the same manner as it works for CEEs hosting other blocks. The peer communication works when the CEEs are at the same Experion PKSrelease level and when CEEs are at different Experion PKSrelease levels. This applies to both CAB/ACE and CAB/C300.
- 214 -
9.24
Chapter 9 - CAB/C300 special considerations
l Communication between Experion server and CEEs containing CAB types and instances works in the same manner as for CEEs hosting other blocks. This communication works when the CEEs are at the same release level as the Experion server and when they are at different release levels.
l Interoperability between the CAB build-time and the CAB/C300 run-time is regulated by a versioning scheme as described in the section, Versioning of CAB/C300 enablers". This scheme has the property that CAB types created or modified by a newer build-time (CAB build-time at later release level) may be loaded to an older run-time (CAB/C300 run-time within a C300 at earlier release level) as long as the type does not use features introduced later than the release level of the C300.
CAB Types Info Form
Like ACE, the CEE configuration and monitoring form for C300 supports a tab for viewing CAB related information. This information is displayed on the CAB Types Info tab. However, there are some differences between the ACE and C300 versions. The following figure displays an example of the CAB Types Info form for CAB/C300. Parameters on the form are described below.
l CAB Supported Version This field displays the value of the CEE-C300 block parameter, CC3SUPRTDV. It provides the version level of the CAB/C300 run-time supported by the C300. Only CAB types which require this version level or lower can be loaded to the C300. For more information on this parameter, refer to the Control Builder Parameter Reference. Note that the CAB Types Info tab of C300 differs from that of ACE in the type of version information displayed. The ACE form displays the value of CEE-ACE parameters DOTNETVER and CABSOFTVER instead of CC3SUPRTDV.
l Enable CAB Runtime This field displays the value of the CEE-C300 block parameter, ENABLECAB. Unlike ACE, C300 provides users the option of controlling whether or not CAB types and instances may be used. For application engineers to be able to load CAB programs to a C300, parameter ENABLECAB must be turned On. ENABLECAB defaults to Off. It must be turned on before the first CAB load. If a user wishes to disable CAB in a C300 where it was previously enabled, the user must first delete all CAB instances and types from the controller. For more information on the ENABLECAB parameter, refer to the Control Builder Parameter Reference.
l Loaded CAB Types This field displays the value of the CEE-C300 block parameter, NUMCABTYPES. This is the number of CAB types which have been loaded to and are resident in the memory of the C300. NUMCABTYPES has a slightly different interpretation for CAB/C300 from that of CAB/ACE. o For CAB/ACE, CAB types cannot be unloaded. Consequently, NUMCABTYPES indicates the number of types which currently have a nonzero instance count. o For CAB/C300, CAB types can be unloaded so there is no need to distinguish instantiated from noninstantiated types. Hence, on C300, NUMCABTYPES indicates the count of all loaded CAB types.
For more information on the NUMCABTYPES parameter, refer to the Control Builder Parameter Reference. l Max Loaded CAB Types
- 215 -
Chapter 9 - CAB/C300 special considerations
This field displays the value of the CEE-C300 block parameter, MAXCABTYPES. MAXCABTYPES indicates the maximum number of CAB types that can be loaded to CEE. For C300, the limit is 100, for C300 v3 limit is 100, C300 v5 limit is 200 and for ACE, 400. For more information on the MAXCABTYPES parameter, refer to the Control Builder Parameter Reference.
l CAB Friendly Name This field displays the value of the CEE-C300 block array parameter, CABTYPNAME. It lists the name of each CAB type currently resident in the C300 in the format "<library name>:<type name>". For more information on the CABTYPNAME parameter, refer to the Control Builder Parameter Reference.
l CAB Instance Count This field displays the value of the CEE-C300 block array parameter, CABINSTCOUNT. CABINSTCOUNT[I] displays the number of instances of the type CABTYPNAME[I] currently resident in the C300. One difference between the CAB/C300 and CAB/ACE versions of CABINSTCOUNT is that CAB/C300 can display a count of 0 instances for a type whereas CAB/ACE cannot. In CAB/C300, when a type has 0 instances, it means that last instance has been deleted but the type is being held for period of one minute in case another instance of the same type is to be reloaded. After the time period of one minute has elapsed, the type is deleted and removed from the displayed list. In the case of CAB/ACE, CAB types are never deleted and non-instantiated types are never displayed in the list at all.
9.25
Frequently Asked Questions on CAB/C300
l Can CL/AM programs be recreated as CAB/C300 programs? Many CL/AM programs can be reimplemented as CAB/C300 programs. However, CAB/C300 does not support all the capabilities of CL/AM. Dynamic Indirection is not supported nor is any form of disk access. If capabilities such as these are needed, then the CL/AM program must be re-implemented as a CAB/ACE program rather than a CAB/C300 program.
l Can CL/PM programs be recreated as CAB/C300 programs? CAB/C300 supports continuous algorithm programming, not sequence programming. It allows application engineers to create VB.NET programs which run in CEE-C300. CAB instances run within CMs, entering and exiting the program at the same place on each processing cycle. CAB/C300 is very different from CL/PM in that it is not intended to be used for writing sequence programs. CAB does not provide the capability of "pre-emption" which is essential for writing sequences. SCM provides the sequence capability in CEE.
o Some CL/PM programs have been written to support continuous applications, even though CL/PM is structured as a sequence oriented language. These programs can be re-implemented as CAB/C300 types.
o Many CL/PM programs have been written to implement sequences using many PHASE, STEP, WAIT and other statements that employ pre-emption. These programs cannot be implemented as CAB/C300 programs and must be implemented as SCMs.
l Can CAB/C300 do everything that CAB/ACE can do? CAB/C300 is designed to be a consistent subset of CAB/ACE. This means that many CAB types can run on both the ACE and C300 platforms unchanged. However, there are several CAB functionalities supported on the level 2 ACE platform which are not supported on the level 1 C300 platform. These include the following.
- 216 -
Chapter 9 - CAB/C300 special considerations
o Dynamic re-referencing. o Background / distributed execution. o History access. o Any form of disk access, including file access and database access.
l Can CAB/C300 be used with process special CMs? CAB/C300 cannot be used in conjunction with CEE functionalities unless those functionalities are supported by the host platform. Process special CMs are not supported by the C300 platform.
l Can CAB/C300 be used to do iterative calculations? The C300 host platform is far more CPU bound than the ACE platform. In general, CAB/C300 cannot be used for iterative calculations. This restriction is not absolute. Simple calculations which require a few bounded iterations might be possible. But, in general, application engineers must exercise great caution when trying to perform an iterative calculation with CAB/C300.
l Where should I look if my C300 configuration is showing processing overruns? Instrumentation parameters are available in the CEE block monitoring form. These can be used to gather information on total overrun count and overrun count for each execution cycle. They can also be used to gather information on total CPU consumption and CPU consumption for each execution cycle. If overruns occur, then excessive CPU usage by one or more CAB instances would always be a leading hypothesis to investigate. Such an investigation could be started as follows. o Find out if the overruns are accumulating on one or just a few processing cycles. o Identify the CMs which run on those cycles. o Identify if any of those CMs contain CAB instances. o Identify the type of each CAB instance. o Identify the configuration of the CAB type parameter X_BRANCHLIM. o If X_BRANCHLIM. is greater than 10, then its default value has been changed by the CAB type designer. o Study the execution properties of the CAB type.
l Where should I look if my C300 configuration is showing a redundancy count exceeded alarm? The occurrence of this alarm is expected to be rare. No such alarms have been observed in the field. If such an alarm occurs, it should be investigated in a similar fashion to investigating processing overruns. Instrumentation parameters are available in the CEE block monitoring form. These can be used to gather information on total redundancy count and redundancy count for each execution cycle. If the redundancy alarm has occurred, then excessive data writes by one or more CAB instances would always be a leading hypothesis to investigate. Such an investigation could be started as follows. o Find out if the redundancy count has been exceeded on one or just a few processing cycles. o Identify the CMs which run on those cycles. o Identify which of those CMs contain CAB instances. o Identify the type of each CAB instance. o Identify the configuration of the CAB type parameter X_BRANCHLIM. o If X_BRANCHLIM. is greater than 10, then it has been changed from the default by the CAB type designer. o Study the execution properties of the CAB type. o Look for cases where arrays with changing values are being written frequently.
- 217 -
Chapter 9 - CAB/C300 special considerations l Can the SIM-C300 be used to qualify the performance and capacity of a CAB or CEE
configuration? The SIM-C300 emulates the functional capabilities of the C300 embedded controller. It does not emulate the performance and capacity characteristics of the C300 controller. This statement applies to CAB configurations specifically and to CEE configuration as a whole. In order to judge whether a C300 has sufficient capacity to host a particular CEE configuration, application engineers must test the configuration on a C300.
- 218 -
CHAPTER
10
CDB CONFIGURATION
10.1 Create a new CDB type
10.1.1
CDB development environment
The CDB development environment is launched from the Control Builder application. The development environment provided by Honeywell for CDB creation integrates the following features into CB:
l Support for creation of new types for CDBs, and for adding these new types to the CB library. l Support for instantiating the new types into CMs, and for loading the type definitions into the
CEE. l The Honeywell PDE--for configuration of custom data parameters for CDBs.
10.1.2
Summary of configuration steps
The following steps are involved in the creation of a new CDB type: l Open a new block type for edit l Define custom parameters l Save the type
10.1.3
Open a new CDB type for edit
Creating a new CAB type begins from the Control Builder application. You click File > New > Type > Custom Data Block from the CB menu bar. A dialog box appears in which you specify the Custom Library Name, either by typing the name of a new custom library, or by selecting an existing library name from a drop-down list. In this dialog box, you also type the new CDB Block Type Name as shown in the figure that follows.
- 219 -
Chapter 10 - CDB configuration Figure 10.1 Specify Library and CDB Name
Rules for library and block type names are as follows:
l Maximum character count for library and block type name is 40. l Name must include at least one underscore or alpha character. l All alpha characters, all numeric characters, and the underscore character are legal-all other
characters are illegal.
TIP
If you plan to include the block name as part of the instance name(s), be aware that instance name requirements are the same as library and block name requirements as indicated above, except that instance names are limited to 15 characters. Default instance names are assigned as follows (for a block type name "xxx."):
l First instance = "xxxA"
l Second instance = "xxxA_1"
l Third instance = "xxxA_2"
10.1.4
After you specify the library and block names and click OK, the Parameter Definition Editor (PDE) opens as shown in Figure 37. In this window, you type your custom parameters (value CDPs). See Define CDB custom data parameters for details.
Figure 10.2 Parameter Definition Editor
Types of saves for CDB
The following table shows the types of save operations that are available for CDB.
File menu option
Table 10.1 Types of Saves for CDB Action
Save
Saves the PDE data to local storage and to the ERDB. This option is only available if you have made changes. IMPORTANT: If you are using the QVCS versioning system, see topic QVCS support for Custom Data Block for more information. There are certain situations where a Save operation is not allowed and a Save As operation is required. For more information, see Situations that require a Save As operation for a modified CDB.
- 220 -
Chapter 10 - CDB configuration
File menu option
Action
Save Do not use unless prompted to do so. See Save As Renew command below. As Renew
Save As
Allows you to save another copy of the current block. You will be prompted for the desired Library and Block names. If you keep the same Library name, you must type a different Block name. If you choose a new Library name, the Block name can be the same as, or different from, the name of the original block. After the save operation, the block under edit in the PDE will be the new version.
TIP
CDB types are different from CAB types in that there is not a separate command to save to ERDB. The save commands in the table above save data all the way through to the ERDB.
10.1.5
Save As Renew command
CDPs are identified within the system by parameter identification numbers that are invisible to users. Under certain unusual conditions, it may become necessary for the system to regenerate these identification numbers in order to continue with the current operation. If this should occur, you will be notified by an error message that indicates that you need to execute the Save As Renew command. This command requires that you select a new name for the block that you are saving. If you execute the Save As Renew command, the parameter identification numbers within the system are regenerated.
A consequence of the Save As Renew command is that you will have to reload all instances of the block. Alternatively, you may cancel the operation that you were doing when you received the error message indicating the need for Save As Renew.
10.1.6
Save CDB to ERDB
After you have finished parameter definitions, you save them by clicking File > > Save or one of the other save options previously shown in Types of saves for CDB. After the type has been saved, instances can be created.
10.2 Define CDB type parameters
10.2.1
Custom Data Parameter purpose
As the name implies, CDB types support custom data parameters. CDPs as supported within CDB types are equivalent to the CDPs supported on CAB types.
- 221 -
Chapter 10 - CDB configuration
Custom data parameters (CDPs) are parameters (variables) that you define. They are part of the overall definition, or configuration, of your CDB. CDPs are visible within the PKS as a whole. They are "public" in that any agent that has access to the PKS name space can read them. Similarly, CDPs can be written by any PKS agent subject to store access checks specified by you when you design the block. Thus, they represent an effective vehicle for exchanging custom data throughout the PKS.
CDB types are useful in a wide variety of applications. They can be used to hold data that is shared by multiple block instances within a CM or across multiple CMs. They can be used in conjunction with both native blocks and CABs. They can be used as a more self-documenting alternative to flags, flag arrays, numerics, and numeric arrays.
10.2.2
CDP characteristics
Some characteristics of CDPs are:
l CDPs are directly analogous to the parameters of native block types. However, the name, data type, access lock, and other properties, are not predefined. You specify them during the process of defining the block type. Attributes that can be specified for CDPs are described in "Reviewing custom parameters tab (Value CDPs)" in the Parameter Definition Editor Reference. Data types are described in Data types for CDPs and parameter references.
l Their values are persistent as they are maintained from creation until deletion of the block instance. Their values are retained from one execution of the block to the next.
l The data types available for the CDB CDPs are equivalent to those for CAB CDPs.
l CDP values can be changed by writes from external blocks or other agents within the PKS. However, since a CDB has no associated program, values are never changed as a result of internal processing. Also, CDBs do not support parameter references.
l CDPs can be viewed from several different displays within the PKS. CDP values can be configured in the CDB form using the CB project side instance. CDP values can be read and written on process from the CDB form using the CB monitor side instance. Values can be read and written using chart visualization from the Experion PKSStation. They can also be read and written from custom displays.
10.2.3
Define CDB custom data parameters
CDP definitions are entered in the Value CDPs configuration form of the PDE. This form is selected by clicking the Value CDPs tab of the PDE as shown in the following figure.
Figure 10.3 Value CDPs Tab
A portion of the Value CDPs form is shown in Figure 39. Figure 10.4 Value CDPs Configuration Form
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about Value CDP information.
- 222 -
Chapter 10 - CDB configuration
10.2.4 10.2.5
For information about...
In the PDE Reference, see...
Customizing the Value CDPs view (set of attributes that Reviewing PDE views for CAB and CDB are displayed),
Specifying CDP attributes
Reviewing custom parameters tab (Value CDPs)
Do not use names that begin with "X_" when naming your CDPs. Honeywell has adopted the convention of naming its new FDPs with names that begin with "X_" (for example, X_EXECMODE). Reserving all names beginning with "X_" for Honeywell use ensures that Honeywell will not name a new parameter with a name that is already used by a customer.
Validity checks based on CDP attributes
Some of the CDP attributes that you configure are used to condition whether or not the CDB instance will accept writes from external agents. This is true for these attributes:
l Access Lock l Minimum Value l Maximum Value l Dimension 1 Array Element Count l Dimension 1 Array Lower Bound l Dimension 2 Array Element Count l Dimension 2 Array Lower Bound
It is important to understand that these validity checks are done in accordance with the Data Owner Principle. Thus, the CDB instance is considered the owner of all its CDP data. Writes to its CDPs from external agents (such as blocks and displays) are accepted only if they do not violate the validity checks.
For validity checks of Maximum Value and Minimum Value, the special behaviors that follow are supported for CDPs of floating point type.
l Writes of NaN are always accepted. l Writes of non-NaN values are compared to the limits. For programmatic writes, out-of-range
values are never rejected but are clamped instead. For human-initiated writes, out-of-range writes are rejected and an error message is issued indicating that a limit or range was exceeded. l A write of +INF or -INF will be accepted unless a finite limit is set, in which case the value that is stored is clamped at the limit. For human-initiated writes, out-of-range writes are rejected and an error message is issued indicating that a limit or range was exceeded.
There are no validity checks of Maximum Value and Minimum Value for whole-array writes to a CDP of any type. For a write to a single element of an array, the same Maximum Value and Minimum Value validity checks are made as for a write to a scalar CDP of the same type.
A store to any parameter type other than floating point will be rejected if the value is outside the Maximum Value and Minimum Value limits. A store to a parameter of type floating point will clamp the value at the upper/lower limit and allow the store.
Access lock attribute for CDPs
Attributes that can be specified as part of a CDP definition are described in the previous topic. One of these is Access Lock. The access lock of a CDP determines which external agents can initiate
- 223 -
Chapter 10 - CDB configuration
stores to the parameter. External agents are identified by an Access Level identifier that is sent with every write request.
The following table lists external agents that can attempt stores to CDPs and the access level that identifies them. An "X" in a cell indicates that the operation is allowed. Note that for some external agents, the access level can be one of several values, depending on circumstances. In the case of CAB instances, the access level will be either Program or Continuous Control depending on the value of fixed definition parameter ACCESSLEVEL. In the case of human initiated stores from CB Monitoring Displays or Station Displays, the access level will be Engineer, Supervisor or Operator depending on privileges associated with the user ID.
External agent attempting store
Control Builder during load of CM or SCM
Table 10.2 Access Levels in Experion Access level
Application Program Continuous Engineer Supervisor Operator
developer
control
X
Supervisory batch
X
application
SCM
X
CAB instance
X
X
Supervisory control
X
application
Algorithm function block
X
Human storing from CB monitoring display
Human storing from Station display
X
X
X
X
X
X
The following table lists possible values for CDP Access Lock and their meanings. Each cell indicates whether stores with the indicated Access Level will be accepted by a CDP that has been assigned the indicated Access Lock.
Access lock
Table 10.3 Access Locks for CDPs Access level
Application developer
Program Continuous control
Engineer Supervisor Operator
View Only No
No
No
No
No
No
AppDevOnly Yes
No
No
No
No
No
Program
Yes
Yes
Yes
No
No
No
Engineer Yes
Yes
Yes
Yes
No
No
Supervisor Yes
Yes
Yes
Yes
Yes
No
Operator Yes
Yes
Yes
Yes
Yes
Yes
- 224 -
Chapter 10 - CDB configuration
10.2.6 10.2.7
10.2.8
As an example of how to interpret the above tables, consider a CDP defined with Access Lock = Engineer. Suppose a human being with engineering privileges is logged on and using a Station display. This user can store to the CDP. Users logged with only Supervisor or Operator privileges and using the same display cannot store to the CDP. Supervisory Batch or Continuous Control applications can store to the CDP, as can any CEE function blocks that have the capability to initiate stores.
Fixed definition parameter purpose
CDB types support fixed definition parameters (FDPs). These are parameters that are defined by the system in order to provide services essential to every CDB. Some FDPs are for internal use only and are of no concern to users. Others are known to users and are used either at the time of block type creation, block instantiation or both.
Fixed definition parameters in CDBs
FDPs common with native blocks lists CDBs and CABs that support certain FDPs that are common to native blocks. There are no CDB FDPs whose default values are configurable by the user when the CDB is defined in CB. Thus, the PDE does not have a Fixed tab that is present for CABs.
The following table lists CDB FDPs that are not common with native blocks. Note that the EDITLOCK and BLOCKTYPEID parameters are also present in CAB.
Parameter name
Table 10.4 CDB FDPs Not Common with Native Blocks
Summary description
Modification of definition
User Write access for instance
BLOCKTYPEID Holds an identifier unique to each CAB or CDB type. Definition View only fixed
CDBSOFTVER Contains the version of the software that was used Definition View only
to build the user's CDB type.
fixed
EDITLOCK
Prevents simultaneous type edits by holding identifier of CE and machine doing current edit. (EDITLOCK also pertains to CAB.)
Definition View only fixed
LOADSTATE
Operating state of CDB instance (Unloaded, Loading, or Loaded).
Definition View only fixed
Detailed description of CDB FDPs
Detailed descriptions of these parameters are located in the Control Builder Parameter Reference. To access these parameter descriptions, click the parameter name in Table 53.
10.2.9
Specify symbol attributes
As part of the CDB type definition, the Symbol Attributes tab on the PDE allows you to define attributes for the block symbol that appears within project and monitor control charts. As part of the type definition, you can elect do the following: l Expose any CDP as a connectable pin. l Expose any CDP value on the face of the symbol.
- 225 -
Chapter 10 - CDB configuration
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about symbol attributes.
For information about... Configuring symbol attributes
In the PDE Reference, see... Reviewing Symbol Attributes tab
Any modifications you later make to symbol attributes will not propagate to existing CDB instances if you choose a Save and answer Yes when prompted to update instances. There are two ways to change Symbol Attributes in existing instances. Symbol Attribute changes must be done for each instance by deleting and re-adding the block to the CM, or making the change in the block properties form on the project side.
10.2.10
Specify form layout
As part of the CDB type definition, the Form Layout tab of the PDE allows you to specify aspects of the layout of the block properties form. In most cases this is unnecessary as the default form layout will be adequate. In some cases, you might want to change the way the form appears during instance building or during chart visualization in on-process displays.
Operations that you perform in the PDE are covered in the Parameter Definition Editor Reference. The following link leads to information about form layout.
For information about... Defining the layout of the properties form
In the PDE Reference, see... Reviewing Form Layout tab
10.2.11
Form entry steps
CDB parameters and attributes are configured in the PDE forms. Descriptions and references for these parameters and attributes are covered in this guide. Information about using the PDE is covered in the Parameter Definition Editor Reference.
One PDE feature that can be especially useful is the ability to cut, copy, and paste parameters. If your block contains multiple parameters that are similar, you can copy a parameter and paste it into multiple lines. In this case, the PDE renames each parameter, so you may want to change the names to suit your preference. You can also copy parameters and paste them into a separate block that is open for edit. In this case, the PDE will not change the names. To use this PDE feature, right-click a line in the PDE as shown in the following figure.
- 226 -
Chapter 10 - CDB configuration Figure 10.5 Access Cut, Copy, and Paste Options
10.2.12 Save parameter definitions
After completing configuration steps in the PDE, you must save the parameter definitions with the Save command. The PDE will remain open after the Save operation. You must close the PDE to end the edit session. For more information see Types of saves for CDB.
10.2.13 Limitations on number of CDB parameters
There is a limit to how many parameters a CDB can have. CDPs and FDPs both contribute to a total that is constrained as shown in Table 56.
Table 10.5 Configuration Limits for CDB Types and Instances
Parameter Max limit type
Comment
FDPs
200
FDPs are defined by Honeywell and not available for definition by users,
although users can read them and write to some of them. Approximately
50 are currently used and 150 more are reserved for future use.
User-
2800*
defined
parameters
CDPs count as one user-defined parameter.
*Array parameters count as one parameter no matter how many elements they have.
10.3
These limits apply to all platforms--ACE, C200, C200E, and C300. In addition, CDB checkpoint size is limited to a maximum of 32 KB, independent of the number of parameters.
Create a CDB instance
Instance handling for CDBs is equivalent to that of CABs and to that of native blocks that are instantiated within CMs. CDBs cannot be instantiated within SCMs. Project side and monitor side instances have the same meaning and usage for CDB types as they do for CAB and native block types. For more information about creating, loading, and deleting instances, refers to the Control Building Guide.
- 227 -
Chapter 10 - CDB configuration
CDB properties forms have the same meaning for CDB types as they do for CAB and native block types. The look and feel of the form is determined by the parameters that make up the block. The forms can be used for configuring the instance before load. The form can be used for viewing and changing CEE-resident data from the monitoring side of CB or from on-process Station displays using Experion PKSchart visualization.
CDB types are analogous to CAB types in that the existence of run-time instances poses restrictions on the user's ability to change the block type. This is discussed further in Manage instances after modification of CDB type.
10.3.1
Configure Value CDPs tab
Double-clicking the block symbol within the project or monitor control chart accesses the block's properties form, which has several tabs. (There are other ways to open the form that are standard CB functionality.) The form can be used to specify and load configuration parameters, and can also be used to display view only parameters when monitoring. When the block is a CDB, the properties form includes the Value CDPs tab (not available on the forms for native blocks).
The Value CDPs tab on the properties form has two viewing options, depending on whether the Show Parameter Names option at the bottom of the form is checked or unchecked as shown in the following figure.
Figure 10.6 Show Parameter Names Check Box
The following figure shows the Value CDPs tab as it appears when the Show Parameter Names option is unchecked. In this view, the Parameter description that you entered when you created the type is listed for each CDP, along with its default value.
Figure 10.7 Value CDPs Tab with Descriptions Shown
The following figure shows the Value CDPs tab when the Show Parameter Names tab is checked. In this case, the parameter name is listed rather than the parameter description.
- 228 -
Chapter 10 - CDB configuration Figure 10.8 Value CDPs Tab with Parameters Shown
The parameters that are listed on the form are the parameters that you configured when you defined the CDB type in the PDE. The corresponding values shown for each parameter are the default values that you assigned at that time (unless you subsequently changed the default value for the instance, as described in the next paragraph).
If you were in the project tree view when you opened the properties form, you can change a default value on the form and new value will be saved to the ERDB when the form is saved. It will then be saved to the CEE when the block is loaded, provided that the parameter's Configuration load attribute was set to LOAD when you created the type. This change of a default value will apply only to the specific block instance, and will not be reflected in other instances of the type, nor will it change the value in the type definition.
If you opened the properties form from the monitor tree, you can change a parameter value, and when you click OK on the form, you will be prompted as to whether or not you want to save the online value.
10.4 10.5
If you click Yes, the new value will be loaded to the CEE immediately. The change will not be reflected in the ERDB, and the next time the block is loaded, the default value stored in the ERDB will be loaded.
Test the CDB
Since CDBs do not have an algorithm, there is no debug stage as there is with CAB. A CDB will be tested in the context of the control strategy in which it is located. Testing involves verifying that the parameters are properly defined and that values are written and read as intended.
Modify a CDB
10.5.1
Manage instances after modification of CDB type
When saving a modified block type to ERDB, you must make decisions about how to handle any preexisting instances. There are two options. Which one you use depends on whether you are in
- 229 -
Chapter 10 - CDB configuration
the process of developing the block type or whether you are maintaining a block type that is already being used on process. The two options are:
l Save the modified block type under the preexisting name. This will immediately convert the project side instance. The actual operation of the block, if active, is not affected, because it will continue to use the old block until a load operation updates it with the new instance. If you have made changes such as new pins or parameters that are configured to show on the faceplate, there are special considerations. If you made these changes in the Symbol Attributes tab in the PDE, you need to delete and re-add the instance on the project side and then load to update the monitor side. If you made these changes from the project side properties form, the changes will not appear on the monitor side until you load.
l Save the modified block type under a new name. Later, convert the project side instance and reload to reflect the changes in the monitor side.
The first option is used in development scenarios. During development, you are likely to go through multiple cycles of changing CDB CDPs while debugging a strategy. It would be very inconvenient to manually reassign type names at every pass through the cycle. To avoid this, CB and CDB infrastructure allow modified types to be saved without name changes. Existing instances are converted automatically on the project side subject to constraints on the nature of changes that can be made.
When on-process CDBs must be modified, the second option is recommended. In this case, you save the modified CDB type under a new name so that none of the on-process blocks need be disturbed. Then you can convert the blocks one at time to the new type, inactivate them, and reload them. The process of converting blocks can be carried on over an extended period of time without risk.
When you use the second option, the CDB type used by the CEE instances is not overwritten within ERDB. Both the old and new types remain until you have converted all instances. After there are no remaining instances of the old type, you can delete it if desired. You cannot delete it while there are remaining instances. As long as there is an instance of the old CDB type within CEE or within ERDB, the old CDB type cannot be deleted from ERDB.
A procedure to verify that the version of a CDB running in CEE is the same as the version stored in ERDB is described in Verify match of CDB version in ERDB.
10.5.2
User actions when saving modified CDB type
There are several conditions that can affect the save operation. To make this clear, consider the following scenario.
1. You create a block type called MYCDB. 2. You instantiate CONTRCDB under the name MYCDB1 within control module CM1. 3. You assign and load CM1. MYCDB1 to a CEE so that both project and monitor copies exist. 4. You now open type MYCDB once again and make changes.
Now, you attempt to save block type MYCDB to ERDB.
The first relevant condition to affect the save operation is whether instances of the type exist within ERDB. In this case, there is an instance so you will get the following warning message:
"Overwrite type and convert all ERDB instances?"
If saving a modified CDB type that was already on process, you would normally choose Cancel (the default) because you would not want to overwrite an on-process CDB with one that is untested. Similarly, if developing a new type but wanted to leave the old version in ERDB for a while longer, you would choose Cancel. But, suppose that you are still developing and do not need to keep the old version of the type--you choose OK.
- 230 -
Chapter 10 - CDB configuration
At this time, another condition comes into play--the nature of the changes that have been made to the block type. For most changes, CB automatically converts all existing instances to match the new block type. This is what would happen if CDPs had been added to the type. However, under a specific set of conditions, such as deletion of a preexisting CDP, or changing the data type of a CDP, CB does not support automatic conversion.
Suppose that you had modified MYCDB in such a way that a CDP was deleted. CB would then respond to the save command as follows:
A "Save-As" dialog appears that gives the option of changing the name of the block type or of canceling the save operation.
Faced with this dialog, you must now save the MYCDB to ERDB under a new library or block name.
The fully qualified name for a CDB type consists of the library name concatenated with the block type name. Thus, at this stage in the scenario, it is sufficient to change one or the other. If the library name is left unchanged then the modified type goes into the preexisting library under a new block type name. If the block type name is left unchanged then the new block type goes into a different library under the old block type name.
To complete the scenario, suppose that you choose to leave the library name unchanged and change the block type name to "MYCDBA."You have now succeeded in saving the modified version of "MYCDB "to the original library in ERDB, under the new name " MYCDBA." What remains is to convert the preexisting instance, MYCDB1, from an instance of MYCDB to an instance of MYCDBA. The section Convert instances to modified CDB type describes how to use the CB "Convert" command.
Note that when save under a new name is done, the edit lock on the old type is automatically cleared and a new lock is opened for the newly named type. The lock remains active until you close the PDE for the new block type.
If you are using the QVCS versioning system, refer to the topic QVCS support for Custom Algorithm Block for more information.
Figure 44 that follows is a flow diagram that shows how various conditions affect the save operation. This diagram covers the most usual scenarios but does not necessarily cover every special case that might arise.
10.5.3
Situations that require a Save As operation for a modified CDB
When you modify a CDB that has instances, there are certain situations under which you will be required to do a Save As operation. These situations are: l You deleted a CDP. l You changed the name of a CDP. l You changed the data type of a CDP. l You changed from a scalar to an array or from an array to a scalar. l You changed the dimension of an array. For example, you changed from a one-dimensional
array to a two-dimensional array.
10.5.4 10.5.5
Behaviors when saving modified CDB types to ERDB
Although there is only one condition that impacts Convert of block instances from one type to another, there are several conditions that impact the save operation as illustrated in Figure 44.
Convert instances to modified CDB type
CB provides the ability to change a block instance from one type to another type. This is called
- 231 -
Chapter 10 - CDB configuration
converting a block instance. A typical use of this feature is to allow you to modify an existing type, save it as a new type, and then update the existing instances of the old type. This technique avoids the need to delete the old instances and create new instances of the new type. Other scenarios are possible. When conversion is done, the ERDB type definition data is updated in both the project side and monitor side instances. Instances must be converted one at a time, and a subsequent load operation is required to update the CEE. Changes that you can make to the type that are allowed by the conversion function are:
l You can add CDPs or change their data types. l You can delete CDPs unless they have connections to other blocks. If a parameter with an
external connection needs to be deleted, the connection must be removed first.
To convert instances to modified CDB Instances
1. Identify an in-service CDB instance that needs to be converted. 2. Select the block instance to be converted in the project side chart view. 3. Right-click on the instance and click Change Parent. 4. From the list that appears, select the new block type that should be assigned to the instance. 5. Click Convert. 6. After the existing instance has been converted, you can inactivate, load and reactivate the CM
that contains the CDB instance.
10.5.6
Additional notes about the convert function
Note that the convert function has fewer constraints than the Save to ERDB operation. For example, you cannot Save to ERDB a block that has parameter deletions or data type changes if there are existing instances of the block. These operations are permitted in the convert operation.
When a block instance is converted, the new type might have fewer parameters than the old type, have more parameters than the original type, or have parameters with the same name but different data type. These situations are handled as follows:
l Parameters that have the same name and data type receive the value from the original instance.
l Parameters that have the same name but different data type are initialized to their default values.
l Parameters present on the new block type but absent from the old are initialized to their default values.
l Parameters absent from the new block type but present on the old are eliminated from the new instance.
When converting instances, you might need to identify all instances of a block type. See Discover CDB dependency relationships for comments on locating instances of a type using the Search tool in Configuration Studio.
10.5.7
Verify match of CDB version in ERDB
You can compare the values of parameter BLOCKTYPEID to verify that the version of a CDB program running in a CEE is the same as the version stored within ERDB. The easiest way to do
- 232 -
Chapter 10 - CDB configuration
this is to use the Compare Parameters function. Right-click the CM in either the project or monitor views, and select Compare Parameters as shown in Figure 45.
Figure 10.9 Selecting the Compare Parameters Function
10.5.8
Then, the Compare Parameters window opens as shown in Figure 46. Note that the BLOCKTYPEID in the controller is different than the BLOCKTYPEID in the ERDB. This indicates that the type was modified and not loaded to the instance. The Compare Parameters function offers another benefit. If the CM contains more than one custom block, the parameter differences will be listed for all of these blocks.
To verify the CDB instance version
1. Open the properties form for the CDB type defined within ERDB. This may be done in one of two ways. Either open the form directly from the library tree, or open the form for an instance of the CDB type within the project tree.
2. Read the value of BLOCKTYPEID from the form. This is a 36-character alphanumeric value. 3. Open the properties form for an instance of the CDB type within the monitoring tree. 4. Read the value of BLOCKTYPEID from the form. 5. Compare the two values.
View a CDB type as read only
You can use the "View Type" menu option to open as read only a CDB type that is under edit by another engineer. You can also use this command to open the type without setting the Edit Lock flag.
- 233 -
Chapter 10 - CDB configuration
If a type is under edit and you try to open it without using the View Type command, you will be prompted to open as read only or to cancel.
10.5.9
Delete a CDB type from ERDB
You can delete CDB types from the ERDB if they are no longer needed or if they have been superseded by later versions. CB will not allow you to delete block types if there are corresponding instances on the project side or monitor side of ERDB. Similarly, CB will not allow you to delete block types if there are templates on the project side that depend on the type you are attempting to delete. If such instances or templates exist, CB will return an error message on the delete attempt.
Other considerations about deleting CDB types:
l Deletion of a CDB type is not allowed when it is open for edit. l Custom libraries that contain custom block types or user templates can also be deleted. l System security policies allow anyone with engineering access to delete CDB types.
10.5.10
Rename a CDB
You can rename a CDB type except under the following conditions: l You cannot rename a CDB type that is open for edit. l You cannot rename a CDB type or change the library name if the type has an instance loaded
to the monitor side.
There are no restrictions on renaming CDB instances.
10.5.11
Recover a CDB with checkpoint restore
The system is designed to insure that all data associated with a CDB is recovered by using the checkpoint restore command. Using a checkpoint containing CDBs is no different from using a checkpoint that contains only native blocks. You select the ACE, C200, C200E, or C300 controller of interest and command a restore or save.
If the checkpoint restore is commanded to an ACE with a preexisting database, the existing CAB programs will be deleted and only those CAB programs that were loaded to the ACE when the checkpoint save operation was executed are reloaded.
For more information about checkpoint and restore, see the section titled "Using Checkpoint to Save and Restore Data" in the Control Building Guide.
10.5.12 Export CDB
CDBs can be exported from ERDB into a specified directory in the same manner that native blocks are exported through the File > Export menu option. The procedures and the user interface for doing so are covered in the Control Building Guide and are not duplicated here. However, some important differences are highlighted here.
- 234 -
Chapter 10 - CDB configuration
When you export native blocks, it is only the instance data that is extracted from ERDB. In general, there is no need to extract native block types because they will already be defined within the ERDB that is to receive the instances upon import. CDB types, however, are different. In all likelihood, the receiving ERDB will not already have a definition of the CDB type. Therefore, in R300, functionality is provided so that when you export a CM that contains one or more CDB instances, the custom types will be selected automatically along with the CM. System services for export and import provide special handling for name collisions in CDB types. A type name collision would occur if two engineers working with different ERDBs had coincidentally chosen the same block name and the same library name for the type they had created. Such a collision would not matter and would never be discovered unless one engineer tried to import the block type into the ERDB used by the other. But if this did happen, services associated with import would resolve the conflict by renaming the library. To insure name collisions can be properly handled, export processing anticipates the possibility of name change by supplying an internal identifier for associated types and instances. This internal identifier is always unique and never changes. On import the identifier can be used to properly match associated types and instances even when a type name must change. When CDB types are exported, they always bring their library name with them. You may choose whether to export the entire type content of the library or only a subset of the types. Only those block types that have been explicitly selected are exported. To export an entire library, you select all types contained within. When a CDB type is exported, a directory structure is created. This directory structure is used when importing. For more information on importing, see the next topic, Import CDB.
10.5.13 Import CDB
CDBs can be imported from ERDB through the File > Import menu option. Block types are imported first. The system checks to see if a duplicate exists. A duplicate exists if the library/block name and the internal identifier (BLOCKTYPEID) all match. If the block is a duplicate, the import is bypassed. If the library/block name is different, but the BLOCKTYPEID is the same, this indicates that the library/type has gone through a name change. In this case, the instance's library/type name is changed to match that of the type being imported, and a status message is reported in file IXP_ log.txt. If the library and block names are the same but the BLOCKTYPEID is different, the system renames the library by appending an underscore and serialization number. For example, CDBLIB would be renamed the first time as CDBLIB_1. Import messages are recorded in a log file called "IXP_log.txt"within this directory: C:\ProgramData\Honeywell\Experion PKS\Ixport Following import, you have the opportunity to change the automatically generated names if you desire.
10.5.14 Discover CDB dependency relationships
CB supports services for tracing relationships between CDBs and other named entities within the Experion. These services are part of the Search functionality of Configuration Studio. All forms of dependency identification supported for native block instances and templates are also supported for CDB instances and templates. In addition, the Search tool supports identification of certain dependencies that are unique to custom block types. These are as follows.
- 235 -
Chapter 10 - CDB configuration l CDB instances that derive from a given CDB type. l CDB type from which a given CDB instance is derived. l CDB templates that derive from a given CDB type. l CDB type from which a given CDB template is derived.
10.5.15 QVCS support for Custom Data Block
Prior to R400, the Qualification and Version Control System (QVCS) did not support versioning of CAB types or instances. Thus there was no direct way of tracking changes to a type that is instantiated in a control strategy, or to restore an earlier version of the custom type. QVCS, did, however, support versioning of CMs that contained CAB instances. In R400, QVCS supports versioning of CBT types and instances. Unlike the standard system types (such as CM, SCM, RCM, I/O, and so on), all Custom Block Types (CBTs) are user-defined. Once a CBT is defined, it exists in a Custom Block Library, and is available to be used like any other block type in the system for creating instances in container objects (CM, SCM, and RCM) or for creating User Defined Templates (UDTs). CBT objects in the Library tree can be versioned like any other objects in the Project/Library tree. Also, changes to the CBT objects can be tracked in the QVCS database. Refer to the Qualification and Version Control System document for more information about QVCS support for CBT.
- 236 -
CHAPTER
11
CAB AND CDB EXAMPLE SCENARIOS
11.1
11.1.1
Summary of example scenarios
Disclaimer
The examples in this user guide are included solely for the purpose of illustrating CAB and CDB functionality. They are not to be considered, in whole or in part, as suitable for use in your control systems. Honeywell International Inc. makes no representations or warranties, either expressed or implied, of merchantability or fitness of these examples for any particular purpose. Under no circumstances will Honeywell International Inc. be liable to any person or business entity for any damages resulting from the use of any portion of the material in these examples.
11.1.2
Example scenarios included
The following example scenarios are included in this section: l CAB insertion algorithm l Formulation of VLR_CALC without insertion point l CDPs as Engineering Unit labels l A CDB to hold sensor data l A CDB to consolidate array data l A CAB to calculate statistics over arrays l A CAB to calculate statistics over a set of PRefs l Using dynamic re-referencing to move among zones online l Array and scalar variables in CAB l Initializing in response to system events l Example using data type TIME l Example using data type TIMEOFDAY l Example using data type DELTATIME l Use of data access status in CAB l Use of parameter reference variables in CAB l History time examples l Reading history values using wrapped methods l Reading history values using only the OPC .Net API l Reading average history values using wrapped methods
- 237 -
11.2
Chapter 11 - CAB and CDB Example Scenarios
l Reading average history values using the OPC .Net API l Reading history values from redundant servers l Reading history for an extended period l Use of file IO in CAB l Using a CAB to change the MODE of a TPN point
CAB insertion algorithm
11.2.1
Vapor-to-liquid ratio control
In this example, you want to control vapor-to-liquid ratio (VLR) within a fractionation column. VLR is to be used as the PV in a PID loop. It is not available as a direct measurement and must be inferred from other measurements. The algebraic formulafor computing the VLR is provided in the following paragraph. The following figure shows the relevant variables.
The algebraic formulas for computing the VLR are as follows:
WL= [CP/lambda(TT-TR)+1]WR+CP/lambda(TT-TI)WP
WV= WP+WL
R = WV/WL
where:
CP R TI TR TT WL WP WR WV lambda
= heat capacity of liquid = vapor-to-liquid ratio = temperature on tray 5 = external reflux temperature = top vapor temperature = weight-flow rate of liquid through tray 5 = product-draw-flow rate = external reflux-flow rate = vapor flow rate through tray 5 = heat of vaporization
To address this application, you will use the block types shown in the following table.
Name
Table 11.1 Block Types in Vapor-To-Liquid Ratio Solution Description
AICHANNEL
Native block type. Has algorithm and data for one channel of analog input.
PID
Native block type. Does control loop computation and triggers
execution of the insertion point program at the right point in its
sequence.
Control Module
Native block type. One module serves as container for PID and
- 238 -
Chapter 11 - CAB and CDB Example Scenarios
11.2.2
Name
Description
VLR_CALC instances. Other modules serve as containers for AICHANNEL instances.
VLR_CALC*
CAB type. Defines custom data and custom algorithm. Serves as the insertion point program. This block must have its access level FDP configured for Continuous Control.
* VLR_CALC is a CAB type that you create. Each of the other block types is available as a standard algorithm (native block type) within CB libraries.
Creating empty block type VLR_CALC
In CB, command File > New > Type > Custom Algorithm Block. A dialog box opens asking for the library name and block type name. Supply the name "FRACT" for the library and "VLR_CALC" for the block type. After you close the dialog, Microsoft Visual Studio opens. The two main windows for block type creation, the parameter edit window and the source code window, are available as tab selections. At this point, the PDE window does not contain any CDP definitions. The source code window contains framing statements and comments to help you start the algorithm definition.
11.2.3
Setting the access level for VLR_CALC
This CAB will be configured as an insertion algorithm hosted by a PID block. CABs that are used as insertion point algorithms must have their access level set to Continuous Control. Select the Fixed tab in the PDE and set the default value of the ACCESSLEVEL parameter to CONTCONTROL.
11.2.4
Defining value CDPs for VLR_CALC
Although you can choose to work in any order, assume you start by entering definitions for value CDPs. Select the Value CDPs tab in the PDE to display the PDE definition window. This exposes the default definition view. A more detailed CDP definition view is also available but in most cases the default view, similar in content to the table below, is sufficient. Make the entries as shown in the following table.
Parameter name
Table 11.2 Value CDP Definitions for VLR_CALC
Parameter description
Data type First dim array Access lock Config
size
load
Default value
CP
Heat capacity of FLOAT64 0
liquid
ENGINEER LOAD 0.75
LAMBDA
Heat of vaporization
FLOAT64 0
ENGINEER LOAD 650.0
Note that by defining a parameter called "CP," you set up two kinds of name usage. One usage is the external name references. These are always qualified by the independent block name and dependent block name of the VLR_CALC instance as in "VLRATIO.VLR_CALC1.CP." The other usage is the internal name references. These are always qualified by a property name as in "CP.Value."
After definition of the value CDPs is complete, choose File > Save PDE Data (or click the appropriate icon) in Microsoft Visual Studio. This causes the definitions of CP and LAMBDA to be saved in the
- 239 -
Chapter 11 - CAB and CDB Example Scenarios
11.2.5
development area. These definitions are now available for any algorithm development to be done. You can return to add or change value CDP definitions later. Each edit session must be terminated with "Save PDE Data" or "Save All" before the algorithm source code window can become aware of changes.
Define parameter references for VLR_CALC
Although you can choose to work in any order, assume that you now decide to enter definitions for parameter references. Go to the PDE window and select the tab for defining references. Make the entries as shown in the following table. (The meaning of each attribute in the table is described in Define parameter references.)
Table 11.3 Parameter Reference Definitions for VLR_CALC
Parameter name
Parameter description
Reference data type
Data flow
TOPT
Top Vapor Temperature (Temp)
FLOAT64
INPUT
TRAYT
Tray 5 Temp
FLOAT64
INPUT
RFXT
External Reflux Temp
FLOAT64
INPUT
RFXFLOW
Reflux Flow Rate
FLOAT64
INPUT
DRAWFLOW
Draw Flow Rate
FLOAT64
INPUT
PVCALC
Computed PV to PID VLR_CTL1
FLOAT64
OUTPUT
In VLR_CALC, all references except PVCALC are used for reading input values. The PVCALC reference is used for writing the computed PV to the associated PID block.
After parameter reference definitions are complete, click File > Save PDE Data or File > Save All at Microsoft Visual Studio to save the definitions of TOPT through PVCALC in the development area. These definitions are now available for algorithm development.
11.2.6 Define the algorithm for VLR_CALC
Although you can choose to work in any order, assume you now decide to enter source code for the algorithm. Start with an empty code frame as described in Code CAB algorithm. After entering statements for VLR_CALC, you have the following result:
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock
Inherits BlockBase Private K As Double ' Calculate internal vapor/liquid ratio for any column Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim W1, WV, Ratio As Double ' Make value and status available for all input ' parameter references
- 240 -
Chapter 11 - CAB and CDB Example Scenarios
PRefList.Read() ' Calculate constant used to compute flow rate
K = CP.Value / LAMBDA.Value ' Calculate internal liquid flow rate from ' heat and material balance
W1 = ((TOPT.Value - RFXT.Value) * K + 1) * _ RFXFLOW.Value + (TOPT.Value - TRAYT.Value) * _ DRAWFLOW.Value * K
' Calculate internal vapor flow rate from material balance WV = DRAWFLOW.Value + W1
' Calculate vapor/liquid ratio and store as PV Ratio = WV / W1 PVCALC.Value = Ratio
' Store values to destination for any output references ' whose values were written PRefList.Write() End Sub End Class
There are several points worth noting about this program.
l Imports Statements--This section of the automatically generated code consists of several Imports statements at the start of the program. These statements make available classes and support utilities that are typically needed in control programs or which needed for integration with CEE.
l Public Class CABlock--Block types are declared as classes within VB.NET. The name of the class shown here is "CABlock" and is the same for all CAB types. Within CB and CEE, different CAB types are distinguished by their filenames and by internal identifiers rather than by their class names. The name you declared at the time of File > New > Type > Custom Algorithm Block is visible under the library tree in CB after the save to ERDB.
l Inherits BlockBase--The Inherits statement indicates that the CAB type acquires attributes and behaviors from the parent class called "BlockBase." BlockBase is automatically generated by the CAB build-time software to capture the specifications of value CDPs and parameter references that you entered in the PDE.
l Private K As Double--The program computes a persistent constant called K for use within the program. K is a block scope variable as described in Define block scope variables. K is declared at the scope of the class and is thus visible to any subroutine or function defined within the class. K is not visible outside the VLR_CALC program.
l CP.Value, LAMBDA.Value, TOPT.Value, TRAYT.Value, ... , PVCALC.Value--CP and LAMBDA are predefined CDPs. Their values are accessed via the Value property as indicated in CDP classes. TOPT, TRAYT, through PVCALC are predefined PRefs. Their values are also accessed through the Value property as described in Parameter reference classes.
l Public Overrides Sub Execute()--The keyword "Overrides" indicates that Execute() has been defined within BlockBase but the CE provides her/his own definition here.
l Dim W1, WV, Ratio As Double--The program includes three variables, W1, WV, and Ratio, for use only within subroutine Execute(). These are local variables of the subroutine. Their values last only for the duration of subroutine processing. They are not visible outside the VLR_CALC program.
l PRefList.Read()--Since PRefs are used in the Execute() subroutine CAB infrastructure needs to be told to fetch the referenced data so that it will be available via the Value properties. This is accomplished for all PRefs in Execute() with the single PRefList.Read() statement. Alternatively, you could have issued a Read() call for each individual PRef. Using a single statement for all is more convenient.
l K = CP.Value / LAMBDA.Value--References to CP.Value and LAMBDA.Value fetch values local to the VLR_CALC block that correspond to the value CDPs CP and LAMBDA. This is different from the behavior for parameter references as discussed below.
- 241 -
Chapter 11 - CAB and CDB Example Scenarios
l WV = DRAWFLOW.Value + W1--Variables defined within the program differ from names defined within the PDE window in that they are not used with a ".Value" property. Thus, the appearance of WV and W1 in this expression. Unlike CP, DRAWFLOW is a parameter reference. This means that using "DRAWFLOW.Value" in an expression actually references data that has been fetched from a block outside the VLR_CALC block.
l PVCALC.Value = Ratio--After the desired ratio is calculated, it is stored to the PVCALC parameter reference. In this example, PVCALC points to a PID block that serves as the insertion point call driver. In general, PRefs can point to any block.
l PRefList.Write()--To transfer data out through the output PRefs, the Write() subroutine must be invoked, either once for each output PRef or once for all output PRefs using PRefList.Write (). In this case, there is only one output PRef so either method would have been suitable. This program is written according to the prevailing style using a single statement that handles any number of output references.
Note that the VLR_CALC block type is very simple and does not require user-defined subroutines. In general, you can use whatever user-defined subroutines or functions you need. However, they must be included directly within the main source file or they must be included as separate source files within the same Visual Studio project. Also, any files added to the project must be placed within the CAB source directory. If they are pre-existing files, they must be copied into the CAB source directory.
After you enter the program into the source code window, save it into the development area by clicking File > Save Selected Items or File > Save All. After the source code has been saved, you can compile and link. To do this, invoke File > Build > Build Solution. If the build operation generates compile errors, correct the source code and repeat the build until all errors are eliminated.
11.2.7
Save VLR_CALC to ERDB
After a block type, in this case VLR_CALC, is complete and you get a successful build, you save the type to ERDB. Saving to ERDB is an essential step in preparing a block type for use. Until VLR_ CALC is saved, instances of it cannot be used within a CEE. The copy of VLR_CALC that resides in the development area while it is being created or modified is only a temporary copy of which ERDB is unaware. Any work that is not saved to ERDB will be lost when Microsoft Visual Studio is closed. To save VLR_CALC to ERDB, you invoke the "Save To ERDB" command in Microsoft Visual Studio.
It is possible to save an incomplete block type to ERDB. For example, if you had attempted to build VLR_CALC but had not yet eliminated all build errors, you could still save the type into ERDB with the intent of resuming work later. Block types saved in such an incomplete state can be instantiated, but cannot be loaded.
11.2.8
Block instances in the VLR_CALC application
After you have completed the CAB type VLR_CALC, you are ready to build a control strategy for vapor-to-liquid ratio control. A set of control modules and block instances are required to complete the strategy as shown in the following table.
Name
Table 11.4 Block Instances for Vapor-To-Liquid Ratio Solution Description
VLRATIO.VLR_ PID instance contained within control module VLRATIO. Stimulates execution of
CTL1
VLR_CALC1 as an insertion point program.
VLRATIO.VLR_ VLR_CALC instance contained within control module VLRATIO. Hosts CDPs and
CALC1
the custom PV computation algorithm.
TI201.AI1
An AI channel block within control module TI201. Provides the PV for top
- 242 -
Chapter 11 - CAB and CDB Example Scenarios
11.2.9
Name TI202.AI1 TI205.AI1 FI202.AI1 FI203.AI1
Description
temperature (TT, TOPT).
An AI channel block within control module TI202. Provides the PV for reflux temperature (TR, RFXT).
An AI channel block within control module TI205. Provides the PV for tray temperature (TI, TRAYT).
An AI channel block within control module FI202. Provides the PV for reflux flow rate, (WR, RFXFLOW).
An AI channel block within control module FI203. Provides the PV for product draw flow rate, (WP, DRAWFLOW).
Configure VLR_CALC1
The process of configuring CAB instances is basically the same as configuring native block instances. Double-clicking on the block symbol within the control chart accesses the Value CDPs properties form as shown in the following figure. When the form comes up, values can be entered. The form can be used to specify and load properties parameters but can also be used to display view only parameters when monitoring.
Figure 11.1 Value CDP Configuration for VLR_CALC1
One behavior is worthy of note here. When type VLR_CALC was defined, both value CDPs were declared to have Configuration Load attribute = LOAD. Because of this, they would not be grayed out in the configuration VLR_CALC1 form. If either had been declared with Configuration Load = NOLOAD, it would have been grayed out and would not be alterable on the form.
The default values for CP and LAMBDA (defined when VLR_CALC was created) can now be changed or left unchanged. The values that result from configuration will be sent to CEE when VLR_CALC1 is loaded.
Type VLR_CALC also had parameter references defined when it was created. Because of this, the configuration form has a Parameter Reference tab as shown in Figure 11.2 Empty Parameter Reference Properties Form for VLR_CALC1 figure. Note that the parameter names are shown, as opposed to the parameter descriptions. This is achieved by selecting Show Parameter Names on the form as shown in the following figure.
Figure 11.3 Show Parameter Names Check Box
- 243 -
Chapter 11 - CAB and CDB Example Scenarios Figure 11.4 Empty Parameter Reference Properties Form for VLR_CALC1
When the form shown in the above figure first appears, the Parameter References column is blank. Each parameter reference that you declared within the definition of VLR_CALC now requires an address to be entered. A pick list is used to generate each parameter address. You can also type the parameter address. After you have completed all entries, the form would be as shown in the following figure.
Figure 11.5 Completed Parameter Reference Properties Form
Based on this configuration, when a value is read from "TOPT.Value"within the program of VLR_ CALC1, the value of TI201.AI1.PV will be read. Similarly, when "PVCALC.Value" is written to, parameter VLRATIO.VLR_CTL1.PV will be written. VLR_CALC1 is used within VLRATIO as a block whose execution is stimulated by a partner block that calls the Execute() subroutine at an appropriate step in its own execution sequence. In this application, the partner block is VLR_CTL1. Since VLR_CTL1 is to act as execution master, VLRATIO, the parent CM, must not trigger the execution of VLR_CALC1. To arrange this, the system sets the INSERTION parameter on VLR_CALC1 to indicate no execution by the parent CM. This happens when you configure VLR_CALC1 as an insertion point algorithm on the execution master, PID VLR_CTL1 (see the next topic). At the same time, the ORDERINCM parameter on the inserted CAB is changed to match the ORDERINCM setting of the calling master. Note, however,
- 244 -
Chapter 11 - CAB and CDB Example Scenarios
that although a CAB configured as an insertion point adopts the ORDERINCM of its master, if the configuration is changed such that the CAB is no longer configured as an insertion point, its ORDERINCM value does not revert back to the value that it was before the CAB was configured as an insertion point.
11.2.10
Configure VLR_CTL1
VLR_CTL1 is a PID instance and is configured like any other. However, the manner in which insertion points are configured is functionality that is special for CAB. PID supports multiple different points in its execution flow where a call-out to another block can be inserted. These points are: l Post-Input--CAB instance inserted after input processing l Pre-Alg--CAB instance inserted prior to algorithm processing l Ctl-Alg--CAB instance replaces built-in algorithm l Post-Alg--CAB instance inserted after algorithm processing l Post-CtlOut--CAB instance inserted after control output processing
For this example, assume that you choose to configure the PID instance so that the CAB VLR_ CALC1 is inserted into the PID VLR_CTL1 at the Post-Input insertion point.
The method for doing this is covered in Control Builder documentation, but the general procedure is as follows. On the properties form for VLR_CTL1, you select the tab that allows you to configure the insertion point. On this tab, there is a drop-down list box that allows you to select the insertion point. You select "Post-Input." There is also a text box with a browser button that you use to browse to and select the CAB instance that you want to use for the insertion point algorithm. For more information on insertion point configuration, see Configure insertion points.
11.2.11
Control module chart for VLRATIO
The following figure shows project side instances created for the VLR application as they might appear within CB. The project tree is shown on the left. It lists each control module (FI202 through VLRATIO) and within each control module, each basic block. The VLRATIO control module has been opened for chart view. It shows the symbols for the two basic blocks it contains, VLR_CALC1 and VLR_CTL1.
11.3 Formulation of VLR_CALC without insertion point
Insertion points are used when the CAB must execute somewhere in the middle of a PID or Data Acquisition algorithm. But with PV computation, the CAB algorithm runs before the start of the subsequent block algorithm. In this particular case, it is possible and perhaps even desirable, to implement the CAB instance as a normal component block of the parent CM.
This section briefly reformulates the pervious example, the insertion point solution, along these lines. A summary of the changes in this alternate formulation is as follows.
l Since the instance VLR_CALC1 will not be used as an insertion algorithm it can be implemented as a client of CM graphical connections. Thus, although the use of PRefs shown in Define parameter references for VLR_CALC would still work, a simpler design using only CDPs is presented in this example.
l Since the VLR_CALC1 will execute under the command of the parent CM there is no need for an insertion point configuration on VLR_CTL1.
- 245 -
Chapter 11 - CAB and CDB Example Scenarios
As a variation commonly encountered in the use of PV computation algorithms, this new formulation assumes that the computed PV is supplied to a Data Acquisition block rather than directly to a PID.
11.3.1
CDP definitions for alternate formulation of VLR_CALC
There are no PRefs in the new formulation. Each of the data names previously represented as a PRef is now represented as a CDP as shown in the following table.
Parameter name
CP
Table 11.5 Value CDPs for Alternate Formulation of VLR_CALC
Parameter description
Data type First dim array Access lock Config
size
load
Heat capacity of FLOAT64 0 liquid
ENGINEER LOAD
Default value
0.75
LAMBDA
Heat of vaporization
FLOAT64 0
ENGINEER LOAD 650.0
TOPT
Top Vapor Temp FLOAT64 0
ENGINEER NOLOAD NaN
TRAYT
Tray 5 Temp
FLOAT64 0
ENGINEER NOLOAD NaN
RFXT RFXFLOW
External Reflux Temp
Reflux Flow Rate
FLOAT64 0 FLOAT64 0
ENGINEER NOLOAD NaN ENGINEER NOLOAD NaN
DRAWFLOW Draw Flow Rate FLOAT64 0
ENGINEER NOLOAD NaN
PVCALC
Computed PV
FLOAT64 0
VIEWONLY NOLOAD NaN
11.3.2
11.4
Control module chart for alternate formulation of VLRATIO
In the alternate formulation, VLRATIO contains three basic blocks: VLR_CTL1, VLR_CALC1 and a Data Acquisition instance called VLR_DACQ1. Parameter ORDERINCM for each of these blocks is assigned to achieve the desired execution order. One alternative is as follows. VLR_DACQ1.ORDERINCM = 10 VLR_CALC1.ORDERINCM = 20 VLR_CTL1.ORDERINCM = 30 Since VLR_CALC1 is to be executed by the parent, CM it is not configured to disable execution by the parent. This is different from the insertion point formulation in which execution by the parent CM was disabled because the parameter INSERTION was set by the system when VLR_CALC1 was configured as an insertion point algorithm in VLR_CTRL1.
CDPs as Engineering Unit labels
- 246 -
Chapter 11 - CAB and CDB Example Scenarios
11.4.1
11.5
Example
CDPs do not support an Engineering Unit (EU) attribute that can be specified as part of their definition. Instead, you can specify string valued CDPs to hold EU descriptors for other CDPs. This can be done equivalently for CAB types and CDB types. One advantage of this approach is that it can be applied to any of the following situations.
l You want to create a custom block type that will only be instantiated once. Each CDP will never have more than one EU assigned to it.
l You want to create a custom block type that will be instantiated multiple times. Each CDP will use the same EUs in every instantiation.
l You want to create a custom block type that will be instantiated multiple times and used in different ways. Each CDP can have different EUs depending on how the block is instantiated.
As an example, consider the CAB type VLR_CALC described in CAB insertion algorithm. Suppose you want VLR_CALC to work with a fixed set of EUs for CP and LAMBDA. To accomplish this, you can define CDPs as shown in the following table.
Table 11.6 Value CDP Definitions for VLR_CALC with "EU Label" CDPs
Parameter name
Parameter description
Data type First dim array Access lock Config
size
load
Default value
CP
Heat capacity of FLOAT64 0
liquid
ENGINEER LOAD 0.75
CPEU
Heat capacity of STRING 0 liquid
VIEWONLY LOAD
"Joules/ Liter"
LAMBDA
Heat of vaporization
FLOAT64 0
ENGINEER LOAD 650.0
LAMBDAEU Heat of vaporization
STRING 0
VIEWONLY LOAD "Joules"
In this example, you specified CPEU and LAMBDAEU to have ViewOnly access lock. This means that the units are fixed with the type and every instance must specify CP and LAMBDA values with those units. In other applications you might want to specify an Access Lock of Engineer. This would allow CPEU and LAMBDAEU to be specified as part of instance configuration. However, in that case, it would also be necessary to design the CAB algorithm to handle the appropriate EU scaling.
With CP, CPEU, LAMBDA and LAMBDAEU defined as shown in the previous table, all four parameters would be shown in properties form for a VLR_CALC instance, making it clear which units are required. This same form would be visible as an operations display through the chart visualization capability of CB and Experion PKSProcess Knowledge System Server. If a custom display was created to support VLR_CALC, the EU values for CP and LAMBDA could be presented on the display along with the data values.
A CDB to hold sensor data
11.5.1
Temperature at position within PFR
Assume that a control strategy is needed for use with a Plug Flow Reactor (PFR) application. PFRs are tube shaped vessels in which a chemical reaction takes place. They can vary in size from small lab units to very large capital equipment deployed within petrochemical plants. Large units can be up to a mile long.
- 247 -
Chapter 11 - CAB and CDB Example Scenarios
11.5.2
PFRs are typically broken down into zones. Each zone consists of an injection point at the head end of the flow followed by a length of tube in which the reaction takes place. Reactants are injected at the injection point. Thermocouples are arranged below the injection point to monitor temperature as the reaction evolves.
The number of thermocouples used within a zone can vary depending upon the overall size of the PFR. It can be as few as five or as many as twenty or more. The number of zones can vary from as few as five to twenty or more.
A CM that accepts a temperature input, conditions it, and holds associated data can be formulated as one component of an overall PFR control solution. For this example, assume that you want to create a CM that takes in a temperature input and provides as output a data set that characterizes the temperature at one position within the PFR zone. The PFR is assumed to be small.
To create POSTEMP1, you use the block types as shown in the following table.
Name AICHANNEL
Table 11.7 Block Types in PFR Sensor Data Solution Description
Native block type. Has algorithm and data for one channel of analog input
DATAACQ
Native block type. Does signal conditioning and alarming for one analog input or other numeric value.
POSTEMPCDB Custom data block type. Holds data that characterizes temperature at one position within one PFR zone.
Control Module
Native block type. Serves as container for AICHANNEL, DATAACQ and POSTEMPCDB instances.
Creating block type POSTEMPCDB
Start at CB by commanding File > New > Type > Custom Data Block. Enter the name "PFR" for the library and "POSTEMPCDB"for the block type in the dialog box that appears. After the "New"operation completes, block type POSTEMPCDB is visible within the CB library tree and a PDE window is open within CB. The name "POSTEMPCDB"shows up in the heading for the PDE window.
Select the Value CDPs tab of the PDE window and make the definitions as shown in Table 66.
Parameter name
Table 11.8 Value CDP Definitions in POSTEMPCDB
Parameter description
Data type First dim array size
Access lock
Config load
Default value
ZONE
Zone number FLOAT64 0
APPDEVONLY LOAD -----
POSITION Position in zone FLOAT64 0
APPDEVONLY LOAD -----
TEMP
Temp at position FLOAT64 0
PROGRAM NOLOAD -----
BAD
Error flag
BOOLEAN 0
PROGRAM LOAD ON
DESCR
Sensor description
STRING 0
APPDEVONLY LOAD
After CDP definition is complete, execute the Save command at CB to save block type POSTEMPCDB and its parameter definitions to the ERDB-POSTEMPCDB is now available for use. You can return to add, change or delete CDP definitions later.
- 248 -
Chapter 11 - CAB and CDB Example Scenarios
11.5.3 11.5.4
Block instances in temperature at position application
After POSTEMPCDB is created, you have all the block types you need to build control strategy POSTEMP1. Create CM instance POSTEMP1 so that it holds the basic block instances as shown in the following table.
Name POSTEMP1.AI1
Table 11.9 Block Instances in PFR Sensor Data Solution Description
An AI channel block within control module POSTEMP1. Provides the raw temperature reading at one position within a PFR zone.
POSTEMP1.DATAACQ1 A DATAACQ block within control module POSTEMP1. Conditions the temperature value and does alarming as needed.
POSTEMP1.DATA1
POSTEMPCDB instance contained within control module POSTEMP1. Hosts CDPs that describe temperature and position within a PFR zone.
Configure the CM POSTEMP1
Make the following connections on CM POSTEMP1 as shown in the following figure. l Add TEMP as an input pin on DATA1 CDB. l Connect pin AI1.PV to pin DATAACQ1.P1. l Connect pin DATAACQ1.PV to pin DATA1.TEMP.
- 249 -
Chapter 11 - CAB and CDB Example Scenarios Figure 11.6 Graphical Connections for CM POSTEMP1
11.5.5
Configure POSTEMP1.DATA1
The process of configuring CDB instances is the same as that of native or CAB instances. Doubleclick on the block symbol in the control chart to open the properties form.
Block type POSTEMPCDB has five CDPs defined on it. Thus, when the form for POSTEMP1.DATA1 opens, five parameters appear. This is shown in the following table where it is assumed that you have already made data entries for the fields that allow it.
Name
Table 11.10 Value CDP Configuration in POSTEMP1.DATA1
Value
Description
ZONE
3.0
Zone number
POSITION
25.7
Position in zone
- 250 -
11.6
Chapter 11 - CAB and CDB Example Scenarios
Name TEMP BAD DESCR
-----
Value
ON
"K Type, Bottom of Tube"
Description Temperature at position Error flag Description of sensor
On the form, only the value CDP entries for ZONE, POSITION, and DESCR can be modified. The description field that goes with each parameter indicates the meaning of the parameter and is fixed at block type creation time.
The value CDP fields for TEMP cannot be modified because it was declared not configurable. This is indicated above with italics.
The DESCR parameter is a string parameter. This value can and should be defined at instance configuration time. Note how it differs from the description field of CDPs.
When viewed from the monitor side at run-time, all five parameters show data read directly from the CEE.
A CDB to consolidate array data
TIP
This example uses five instances of the CDB type POSTEMPCDB that was described in the previous example, A CDB to hold sensor data. Assume that these five instances exist and are named POSTTEMP1, POSTTEMP2, POSTTEMP3, POSTTEMP4, and POSTTEMP5.
11.6.1
Block type ZONETEMPCDB
As another component of the PFR application, assume you want to transfer temperature readings and position values from C300 to ACE for processing by a CAB program. However, you want to consolidate the data within the C300 and transfer arrays in bulk to the ACE. Assume that to consolidate temperature and position data, you create a CDB type called ZONETEMPCDB, with the CDP definitions shown in the following table.
Parameter name
Table 11.11 Value CDP Definitions in ZONETEMPCDB
Parameter description
Data type
First dim Access lock Config load array size
Default value
POSITION Position in FLOAT64 5 zone
PROGRAM LOAD
-----
TEMP
Temp at position
FLOAT64 5
PROGRAM NOLOAD -----
POSITION and TEMP are each indexed (array) parameters. In this application, each array is specified to have five elements--each corresponds to one thermocouple data set.
You then instantiate ZONETEMPCDB within a CM called ZONETEMP1, calling the instance DATA1. Because of the CDP definitions above, there will be two indexed parameters available on this DATA1. Their fully qualified names are as follows:
- 251 -
Chapter 11 - CAB and CDB Example Scenarios
l ZONETEMP1.DATA1.TEMP l ZONETEMP1.DATA1.POSITION
A reference with a specific index indicates a scalar array element, while a reference with a null index indicates the whole array. These two forms are contrasted below.
l ZONETEMP1.DATA1.TEMP[3] l ZONETEMP1.DATA1. TEMP[ ]
Suppose that within ZONETEMP1 you configure graphical data connections to fill out the TEMP and POSITION arrays with thermocouple data. The source for this data transfer will be POSTEMPCDB instances such as ZONETEMP1.DATA1.
Thus, you configure a connection to transfer the value of POSTEMP1.DATA1.TEMP into ZONETEMP1.DATA1.TEMP[3]. You configure a connection from POSTEMP1.DATA1.POSITION to ZONETEMP1.DATA1.POSITION[3]. You make additional connections from different instances of POSTEMPCDB until all array elements of ZONETEMP1.DATA1 receive data. All in all, there will be five connections each for ZONETEMP1.DATA1.TEMP and ZONETEMP1.DATA1.POSITION. These connections are shown in the following figure.
Now, suppose you assign CM ZONETEMP1 to a C300 resident CEE. This allows both the thermocouple CMs such as POSTEMP1 and the array consolidation CMs such as ZONETEMP1 to reside within a process connected device. To make zone temperature data available for higher level processing, you can later configure graphical connections that do bulk transfer for each of ZONETEMP1.DATA1.TEMP and ZONETEMP1.DATA1.POSITION.
11.7
A CAB to calculate statistics over arrays
TIP This example uses an instance of the CDB type ZONETEMPCDB, described in the previous example, "A CDB to consolidate array data". Assume that this instance is named DATA1 and is located in CM ZONETEMP1.
11.7.1
Block type ZONESTATSCAB
Assume that you want to calculate statistics on zone temperatures as another component in an overall PFR application. The statistics are to summarize the overall temperature state of the zone. They can then be presented within a graphical schematic display that allows the operator to monitor the reaction over the entire length of the PFR without being overwhelmed by many individual readings.
Assume that you create a CAB type called ZONESTATSCAB to compute zone statistics. You design ZONESTATSCAB so that it can receive as input whole array parameters that hold temperature and position data. ZONESTATSCAB will then use this data to compute scalar values that characterize the zone as a whole.
11.7.2
Value CDPs for ZONESTATSCAB
ZONESTATSCAB has the Value CDP definitions as shown in the following table.
- 252 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
POSITION
Table 11.12 Value CDP Definitions in ZONESTATSCAB
Parameter description
Data type First dim array Access lock Config
size
load
Default value
Position in zone FLOAT64 5
PROGRAM NOLOAD -----
TEMP
Temp at position FLOAT64 5
PROGRAM NOLOAD -----
MAXTEMP MAXPOS MINTEMP
Max Temp in zone
FLOAT64 0
Position of Max Temp
FLOAT64 0
Min Temp in zone FLOAT64 0
VIEWONLY NOLOAD ----VIEWONLY NOLOAD ----VIEWONLY NOLOAD -----
MINPOS AVGTEMP
Position of min Temp
FLOAT64 0
Average Temp in FLOAT64 0 zone
VIEWONLY NOLOAD ----VIEWONLY NOLOAD -----
POSITION and TEMP are array parameters. They are designed to connect directly with parameters of the same name on an instance of CDB type ZONETEMPCDB called DATA1. See A CDB to consolidate array data"which describes the creation of this CDB.
MAXTEMP, MAXPOS, MINTEMP, MINPOS and AVGTEMP are real valued statistics parameters computed by looping over the TEMP array. The access lock of these parameters is declared to be VIEWONLY. This means that external agents cannot write to these parameters, but program ZONESTATSCAB can.
MAXPOS and MINPOS give, respectively, the position of maximum and minimum temperature within the zone. They are computed by looping over data received in POSITION and TEMP.
Block type ZONESTATSCAB has value CDP definitions but no parameter reference definitions. The output parameters provided by ZONESTATSCAB (MAXTEMP, MAXPOS, MINTEMP, MINPOS, AVGTEMP) are collected asynchronously by displays. Thus, they can only be supported by value CDPs.
The inputs needed by ZONESTATSCAB require bulk array transport from the source, which is not supported by CAB parameter references. Thus, value CDPs POSITION and TEMP are used to bring in array data from a process-connected controller. Connectivity to source data is accomplished through the use of CM graphical connections rather than CAB parameter references (see Bulk array connection on ZONESTATSCAB instance).
11.7.3 Algorithm for ZONESTATSCAB
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock
- 253 -
Chapter 11 - CAB and CDB Example Scenarios
Inherits BlockBase Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim I As Integer If Restart <> RestartEnum.None Then DoInitialize()
SetOutputsToBad() AVGTEMP.Value = 0.0
For I = 0 To 4 If IsNaN(TEMP(I).Value) Or IsNaN(POSITION(I).Value) Then SetOutputsToBad() Exit For Else AVGTEMP.Value = AVGTEMP.Value + TEMP(I).Value If IsNaN(MAXTEMP.Value) Or MAXTEMP.Value < _ TEMP(I).Value Then MAXTEMP.Value = TEMP(I).Value MAXPOS.Value = POSITION(I).Value End If If Not (MINTEMP.Value <= TEMP(I).Value) Then MINTEMP.Value = TEMP(I).Value MINPOS.Value = POSITION(I).Value End If End If Next I AVGTEMP.Value = AVGTEMP.Value / 5 End Sub Private Sub DoInitialize() Dim I As Integer For I = 0 To 4 POSITION(I).Value = NaN TEMP(I).Value = NaN Next I End Sub Private Sub SetOutputsToBad() MAXTEMP.Value = NaN : MAXPOS.Value = NaN MINTEMP.Value = NaN : MINPOS.Value = NaN AVGTEMP.Value = NaN End Sub End Class
TIP
There are CABMath functions to calculate Average (Avg), Minimum (Min), and Maximum (Max) values by passing in an array, but we chose not to use them due to the need to also calculate the position of the min and max temperatures.
Some things to note about the previous program are:
l The TEMP and POSITION CDP arrays use the default base index of 0. Thus, all loops range from 0 to 4 in this program.
l The programmer has chosen to isolate initializations within a private subroutine called DoInitialize().
l The programmer is following the convention that all initialized CDPs show the value NaN after the program is activated. TEMP and POSITION are intended to serve as input arrays. In case they are not initialized by the time of the first execution, DoInitialize() was written to set them to NaN.
- 254 -
Chapter 11 - CAB and CDB Example Scenarios
l The output CDPs are initialized to NaN in subroutine SetOutputsToBad(). Output CDPs do not need to be initialized because SetOutputsToBad() is called at the start of Execute().
l The VB.NET line separator has been used in SetOutputsToBad(). For example, "MAXTEMP.Value = NaN : MAXPOS.Value = NaN," could have been written with each assignment statement on a different line.
l For assignment of MAXTEMP and MAXPOS within the loop, TEMP(I) is explicitly tested for NaN before doing any compare. This insures that nothing unexpected will happen if a NaN value is passed into the comparison. For assignment of MINTEMP and MINPOS the programmer has written the program to handle NaN correctly, but in a more subtle way. The programmer has not used IsNan(), but instead has written the comparison operation as a negative so that the correct outcome will occur regardless of whether MINTEMP.Value is NaN or ordered. The more transparent approach of using explicit IsNan() calls is the recommended style.
l The final assignment, "AVGTEMP.Value = AVGTEMP.Value / 5"can happen with a NaN value on the right hand side if inputs are bad. If so, the division operation results in a NaN output.
l Subroutine Execute() is declared with VB.NET access type of Public. In contrast, subroutines Initialize() and SetOutputsToBad() are declared with an access type of Private. Execute() must be declared Public in order for CEE services to access them. It is an interface subroutine whose declaration should not be changed to vary from the declaration automatically generated when the block type was first created.
l SetOutputsToBad() and DoInitialize() are different in that these are subroutines used as utilities by type ZONESTATSCAB alone. Thus, they are declared to be Private. In point of fact, they would still be private even if the access type declaration were left out or if it was declared to be Public. CAB does not support utility functions that can be shared across block types. The recommended style is to declare all internal utility functions as Private since this documents the true behavior.
11.7.4
11.8
Bulk array connection on ZONESTATSCAB instance
Assume that after creating the block type, you create a CM instance called "ZONESTATS1" and instantiate ZONESTATSCAB within it as "ALG1."You create graphical connections within ZONESTATS1 that accomplish the following whole-array data flow: l ZONESTATS1.ALG1.TEMP[ ] ZONETEMP1.DATA1.TEMP[ ] l ZONESTATS1.ALG1.POSITION[ ] ZONETEMP1.DATA1.POSITION[ ]
The following figure illustrates these graphical connections. At run-time, the values of TEMP and POSITION are used internally within ZONESTATS1.ALG1 for computing the statistics parameters as indicated in the algorithm above. Note that CM hierarchies are well suited to the logical representation of a PFR control application such as described in this and preceding sections. For example, a top level CM could be used to model the entire PFR. It could hold multiple CMs each representing a zone. The zone CMs could hold each of the temperature-position CMs. However, the use of CM hierarchies in control applications is not specific to CAB or CDB functionality and is not described in detail within this document.
A CAB to calculate statistics over a set of PRefs
TIP
- 255 -
Chapter 11 - CAB and CDB Example Scenarios
This example is similar to the previous example A CAB to calculate statistics over arrays except that this example uses PRefs to access data whereas the previous example used CDPs.
What if the temperatures and zone positions in the previous example were not arranged into a CDP array, but were contained in an assortment of targets not otherwise organized?
You can use Parameter References (PRefs) to separately reference each zone position and temperature. But PRefs are not organized into arrays.
This next example is a second ZONESTATSCAB, called ZONESTATSCABP, with PRefs rather than CDP arrays as input. This example shows some techniques to partially mitigate the inconvenience of non-arrayed PRefs. The basic concept is that the list of PRefs is copied to an internal Visual Basic array for easy manipulation, and then, if necessary, copied back to the PRefs for I/O.
11.8.1
Block type ZONESTATSCABP
Assume that you want to calculate statistics on zone temperatures as another component in an overall PFR application. The statistics are to summarize the overall temperature state of the zone. They can then be presented within a graphical schematic display that allows the operator to monitor the reaction over the entire length of the PFR without being overwhelmed by many individual readings.
Assume that you create a CAB type called ZONESTATSCABP to compute zone statistics. You design ZONESTATSCABP so that it can receive as input individual parameter references that hold temperature and position data. ZONESTATSCABP will then use this data to compute scalar values that characterize the zone as a whole.
11.8.2
Value CDPs for ZONESTATSCABP
ZONESTATSCABP has the Value CDP definitions as shown in the following table.
Parameter name
MAXTEMP
Table 11.13 Value CDP Definitions in ZONESTATSCABP
Parameter description
Data type First dim array Access lock Config
size
load
Default value
Max Temp in zone
FLOAT64 0
VIEWONLY NOLOAD -----
MAXPOS
Position of max Temp
FLOAT64 0
VIEWONLY NOLOAD -----
MINTEMP Min Temp in zone FLOAT64 0
VIEWONLY NOLOAD -----
MINPOS AVGTEMP
Position of min Temp
FLOAT64 0
Average Temp in FLOAT64 0 zone
VIEWONLY NOLOAD ----VIEWONLY NOLOAD -----
MAXTEMP, MAXPOS, MINTEMP, MINPOS and AVGTEMP are real valued statistics parameters computed by looping over the TEMP array. The access lock of these parameters is declared to be VIEWONLY. This means that external agents cannot write to these parameters, but program ZONESTATSCABP can.
- 256 -
Chapter 11 - CAB and CDB Example Scenarios
MAXPOS and MINPOS give, respectively, the position of maximum and minimum temperature within the zone. They are computed by looping over data received for position and temperature.
Block type ZONESTATSCABP has value CDP definitions and parameter reference definitions. The output parameters provided by ZONESTATSCAB (MAXTEMP, MAXPOS, MINTEMP, MINPOS, AVGTEMP) are collected asynchronously by displays. Thus, they can only be supported by value CDPs.
The zone position and temperature inputs needed by ZONESTATSCABP use CAB parameter references in the example shown in the following table.
Table 11.14 Parameter Reference Definitions for ZONESTATSCABP
Parameter name
Parameter description
Reference data type
Data flow
POSITION01
01 Position in zone
FLOAT64
INPUT
POSITION02
02 Position in zone
FLOAT64
INPUT
POSITION03
03 Position in zone
FLOAT64
INPUT
POSITION04
04 Position in zone
FLOAT64
INPUT
POSITION05
05 Position in zone
FLOAT64
INPUT
TEMP01
01 Temperature
FLOAT64
INPUT
TEMP02
02 Temperature
FLOAT64
INPUT
TEMP03
03 Temperature
FLOAT64
INPUT
TEMP04
04 Temperature
FLOAT64
INPUT
TEMP05
05 Temperature
FLOAT64
INPUT
11.8.3 Algorithm for ZONESTATSCABP
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase
Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim I As Integer ' Setup internal arrays to hold PRef data for manipulation Dim Position(5) As Double Dim Temp(5) As Double ' Make value and status available for all input PRefs PRefList.Read() ' Copy values from PRefs to internal arrays Position(0) = POSITION01.Value Position(1) = POSITION02.Value Position(2) = POSITION03.Value Position(3) = POSITION04.Value Position(4) = POSITION05.Value
- 257 -
Chapter 11 - CAB and CDB Example Scenarios
Temp(0) = TEMP01.Value Temp(1) = TEMP02.Value Temp(2) = TEMP03.Value Temp(3) = TEMP04.Value Temp(4) = TEMP05.Value SetOutputsToBad() AVGTEMP.Value = 0.0
For I = 0 To 4 If IsNaN(Temp(I)) Or IsNaN(Position(I)) Then SetOutputsToBad() Exit For Else AVGTEMP.Value = AVGTEMP.Value + Temp(I) If IsNaN(MAXTEMP.Value) Or MAXTEMP.Value < Temp(I) Then MAXTEMP.Value = Temp(I) MAXPOS.Value = Position(I) End If If IsNaN(MINTEMP.Value) Or MINTEMP.Value > Temp(I) Then MINTEMP.Value = Temp(I) MINPOS.Value = Position(I) End If End If Next I AVGTEMP.Value = AVGTEMP.Value / 5 End Sub Private Sub SetOutputsToBad() MAXTEMP.Value = NaN : MAXPOS.Value = NaN MINTEMP.Value = NaN : MINPOS.Value = NaN AVGTEMP.Value = NaN End Sub End Class
Some things to note about the program above are:
l The Temp and Position internal arrays use the default base index of 0. Thus, all loops range from 0 to 4 in this program.
l The sequential, non-looping copying is not elegant, but it enables elegance and clarity in the rest of the program. It only has to be accomplished once for input, and again for output if necessary (it was not necessary in this case). Also, for longer lists, some copy/paste tricks can help speed the typing.
l DoInitialize().is not required in this case, as we are not dealing with CDPs. All the other CDPs are initialized in SetOutputsToBad().
l The output CDPs are initialized to NaN in subroutine SetOutputsToBad(). Output CDPs do not need to be initialized because SetOutputsToBad() is called at the start of Execute().
l The VB.NET line separator has been used in SetOutputsToBad(). For example, "MAXTEMP.Value = NaN : MAXPOS.Value = NaN," could have been written with each assignment statement on a different line.
l The final assignment, "AVGTEMP.Value = AVGTEMP.Value / 5"can happen with a NaN value on the right hand side if inputs are bad. If so, the division operation results in a NaN output.
l Subroutine Execute() is declared with VB.NET access type of Public. In contrast, subroutine SetOutputsToBad() is declared with an access type of Private. Execute() must be declared Public in order for CEE services to access them. It is an interface subroutine whose declaration should not be changed to vary from the declaration automatically generated when the block type was first created.
- 258 -
Chapter 11 - CAB and CDB Example Scenarios
11.8.4
Configuring the parameter references on the ZONESTATSCABP instance
The following table shows the configuration of parameter reference targets for the instance of ZONESTATSCABP.
Table 11.15 ZONESTATSCABP Instance PRef Target Configuration
Parameter name
Reference target
POSITION01
POSTTEMP1.DATA1.POSITION[0]
POSITION02
POSTTEMP2.DATA1.POSITION[1]
POSITION03
POSTTEMP3.DATA1.POSITION[2]
POSITION04
POSTTEMP4.DATA1.POSITION[3]
POSITION05
POSTTEMP5.DATA1.POSITION[4]
TEMP01
POSTTEMP1.DATA1.TEMP[0]
TEMP02
POSTTEMP2.DATA1.TEMP[1]
TEMP03
POSTTEMP3.DATA1.TEMP[2]
TEMP04
POSTTEMP4.DATA1.TEMP[3]
TEMP05
POSTTEMP5.DATA1.TEMP[4]
11.9
Using dynamic re-referencing to move among zones online
TIP
This example does not compile if X_PLATOPT is set to ACEANDC300 because dynamic rereferencing is not supported on CAB/C300.
In CAB, specified parameter references can have their target references changed at run time. This is called dynamic re-referencing.
What if you wanted to use one CAB instance to report on zone statistics, but you also wanted to redirect that instance, at run time, to report on one zone some times, and a different zone at other times? The next example shows the setup and run-time operation for using ZONESTATSCABR to do just that.
The user-written source code for ZONESTATSCABR changes slightly from the previous example in the addition of more error checking. The parameter reference definitions change slightly, and we add the output parameters as parameter references.
11.9.1
Value CDPs for ZONESTATSCABR
ZONESTATSCABR has no Value CDP definitions.
11.9.2
Parameter Reference definitions for ZONESTATSCABR
The zone position and temperature inputs needed by ZONESTATSCABR use CAB parameter
- 259 -
Chapter 11 - CAB and CDB Example Scenarios
references. In addition, the outputs are parameter references.
The following table is similar to the example, A CAB to calculate statistics over a set of PRefs, except for the addition of an indicator, entered in the PDE, which identifies these parameters as enabled for dynamic re-referencing, and the addition of the output parameters. The following figure that follows shows the associated PDE.
Table 11.16 Parameter Reference Definitions for ZONESTATSCABR
Parameter name Parameter description Reference data type Data flow Dynamic rereference
POSITION01
01 Position in zone FLOAT64
INPUT enabled
POSITION02
02 Position in zone FLOAT64
INPUT enabled
POSITION03
03 Position in zone FLOAT64
INPUT enabled
POSITION04
04 Position in zone FLOAT64
INPUT enabled
POSITION05
05 Position in zone FLOAT64
INPUT enabled
TEMP01
01 Temperature
FLOAT64
INPUT enabled
TEMP02
02 Temperature
FLOAT64
INPUT enabled
TEMP03
03 Temperature
FLOAT64
INPUT enabled
TEMP04
04 Temperature
FLOAT64
INPUT enabled
TEMP05
05 Temperature
FLOAT64
INPUT enabled
MAXTEMP
Maxi temp in zone
FLOAT64
OUTPUT enabled
MAXPOS
Position of max temp FLOAT64
OUTPUT enabled
MINTEMP
Min temp in zone
FLOAT64
OUTPUT enabled
MINPOS
Position of min temp FLOAT64
OUTPUT enabled
AVGTEMP
Average temp in zone FLOAT64
OUTPUT enabled
11.9.3 Dynamic re-referencing settings for ZONESTATSCABR
The default mode for a CAB type for dynamic re-referencing is "automatic." This mode allows each re-referencing to occur wholly on its own. That is not what we want for this example. We want all the references to point to either one zone, or another zone. If the references were allowed to change individually, we would get nonsensical results for the statistics.
We want to set the mode for dynamic re-referencing for ZONESTATSCABR to "manual." This means that the entity changing the references, whether a person or a program, must follow a prescribed protocol. The protocol ensures that all of the references are changed as one action. That is what we want for a zone change.
To set ZONESTATSCABR's dynamic re-referencing mode to "manual,"we use PDE to set the fixed parameter named "X_REFMODE" to the enumeration "MANUAL." This setting is not changeable when configuring instances of ZONESTATSCABR-it is set for the type. The following figure shows the associated PDE.
11.9.4 Algorithm for ZONESTATSCABR
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase
- 260 -
Chapter 11 - CAB and CDB Example Scenarios
Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim I As Integer ' Setup internal arrays to hold PRef data for manipulation Dim Position(5) As Double Dim Temp(5) As Double ' Make value and status available for all input PRefs,
' & check read statuses PRefList.Read() If POSITION01.ReadStatus() <> CABAccStatusEnum.OK Then POSITION01.Value = NaN
End If If POSITION02.ReadStatus() <> CABAccStatusEnum.OK Then POSITION02.Value = NaN End If If POSITION03.ReadStatus() <> CABAccStatusEnum.OK Then POSITION03.Value = NaN End If If POSITION04.ReadStatus() <> CABAccStatusEnum.OK Then POSITION04.Value = NaN End If If POSITION05.ReadStatus() <> CABAccStatusEnum.OK Then POSITION05.Value = NaN End If If TEMP01.ReadStatus() <> CABAccStatusEnum.OK Then TEMP01.Value = NaN End If If TEMP02.ReadStatus() <> CABAccStatusEnum.OK Then TEMP02.Value = NaN End If If TEMP03.ReadStatus() <> CABAccStatusEnum.OK Then TEMP03.Value = NaN End If If TEMP04.ReadStatus() <> CABAccStatusEnum.OK Then TEMP04.Value = NaN End If If TEMP05.ReadStatus() <> CABAccStatusEnum.OK Then TEMP05.Value = NaN End If ' Copy values from PRefs to internal arrays Position(0) = POSITION01.Value Position(1) = POSITION02.Value Position(2) = POSITION03.Value Position(3) = POSITION04.Value Position(4) = POSITION05.Value Temp(0) = TEMP01.Value Temp(1) = TEMP02.Value Temp(2) = TEMP03.Value Temp(3) = TEMP04.Value Temp(4) = TEMP05.Value SetOutputsToBad()
- 261 -
Chapter 11 - CAB and CDB Example Scenarios
AVGTEMP.Value = 0.0 For I = 0 To 4 If IsNaN(Temp(I)) Or IsNaN(Position(I)) Then SetOutputsToBad() Exit For Else AVGTEMP.Value = AVGTEMP.Value + Temp(I) If IsNaN(MAXTEMP.Value) Or MAXTEMP.Value < Temp(I) Then MAXTEMP.Value = Temp(I) MAXPOS.Value = Position(I) End If If IsNaN(MINTEMP.Value) Or MINTEMP.Value > Temp(I) Then MINTEMP.Value = Temp(I) MINPOS.Value = Position(I) End If End If Next If AVGTEMP.Value <> NaN Then AVGTEMP.Value = AVGTEMP.Value / 5 End If ' Write the output PRefs PRefList.Write() End Sub Sub SetOutputsToBad() MAXTEMP.Value = NaN MAXPOS.Value = NaN MINTEMP.Value = NaN MINPOS.Value = NaN AVGTEMP.Value = NaN End Sub End Class
11.9.5
Configuring an instance of ZONESTATSCABR
Assume that each zone is controlled by its own Control Module, and that all of the temperatures and associated positions in the zone are accessible through named blocks that follow the following convention: l CMname.POSITION01.PV through CMname.POSITION05.PV l CMname.TEMP01.PV through CMname.TEMP05.PV
Assume that the results should be placed back into those blocks, into these parameters: l CMname.MAXTEMP.PV l CMname.MAXPOS.PV l CMname.MINTEMP.PV l CMname.MINPOS.PV l CMname.AVGTEMP.PV
Let us further assume that we are interested in two zones, zone A and zone B, and that they are represented by Control Modules named CMZA and CMZB, respectively. We will configure an instance of ZONESTATSCABR in its own Control Module named CMZSTATS. For the instance CMZSTATS.ZONESTATSCABR, we will start by configuring the parameter references to show statistics for zone A, by connecting to CMZA's targets as shown in the following table.
- 262 -
Chapter 11 - CAB and CDB Example Scenarios
11.9.6
Table 11.17 Assigning Parameter References for Zone A
Name
Value
POSITION01.TEXTREF
"CMZA.POSITION01.PV"
POSITION02.TEXTREF
"CMZA.POSITION02.PV"
POSITION03.TEXTREF
"CMZA.POSITION03.PV"
POSITION04.TEXTREF
"CMZA.POSITION04.PV"
POSITION05.TEXTREF
"CMZA.POSITION05.PV"
TEMP01.TEXTREF
"CMZA.TEMP01.PV"
TEMP02.TEXTREF
"CMZA.TEMP02.PV"
TEMP03.TEXTREF
"CMZA.TEMP03.PV"
TEMP04.TEXTREF
"CMZA.TEMP04.PV"
TEMP05.TEXTREF
"CMZA.TEMP05.PV"
MAXTEMP.TEXTREF
"CMZA.MAXTEMP.PV"
MAXPOS.TEXTREF
"CMZA.MAXPOS.PV"
MINTEMP.TEXTREF
"CMZA.MINTEMP.PV"
MINPOS.TEXTREF
"CMZA.MINPOS.PV"
AVGTEMP.TEXTREF
"CMZA.AVGTEMP.PV"
ZONESTATSCABR in operation, controlled by an operator
When Control Module CMZSTATS is placed into operation, CMZSTATS.ZONESTATSCABR collects and reports statistics for zone A.
Let's assume that an HMIWeb display has been configured to view zone statistics, and to also switch the zone being reported, between zone A and zone B. Let's assume that there is a button on the display that enables an operator to choose zone B for the statistics reporting. Associated with the button might be the following script:
TIP
The following is pseudo code, not HMIWeb script. Consult the HMIWeb Display Builder documentation for information about actual implementation.
Store "CMZB.POSITION01.PV" into CMZSTATS.ZONESTATSCABR.POSITION01.TEXTREF Store "CMZB.POSITION02.PV" into CMZSTATS.ZONESTATSCABR.POSITION02.TEXTREF Store "CMZB.POSITION03.PV" into CMZSTATS.ZONESTATSCABR.POSITION03.TEXTREF Store "CMZB.POSITION04.PV" into CMZSTATS.ZONESTATSCABR.POSITION04.TEXTREF Store "CMZB.POSITION05.PV" into CMZSTATS.ZONESTATSCABR.POSITION05.TEXTREF Store "CMZB.TEMP01.PV" into CMZSTATS.ZONESTATSCABR.TEMP01.TEXTREF Store "CMZB.TEMP02.PV" into CMZSTATS.ZONESTATSCABR.TEMP02.TEXTREF Store "CMZB.TEMP03.PV" into CMZSTATS.ZONESTATSCABR.TEMP03.TEXTREF Store "CMZB.TEMP04.PV" into CMZSTATS.ZONESTATSCABR.TEMP04.TEXTREF
- 263 -
Chapter 11 - CAB and CDB Example Scenarios
Store "CMZB.TEMP05.PV" into CMZSTATS.ZONESTATSCABR.TEMP05.TEXTREF Store "CMZB.MAXTEMP.PV" into CMZSTATS.ZONESTATSCABR.MAXTEMP.TEXTREF Store "CMZB.MAXPOS.PV" into CMZSTATS.ZONESTATSCABR.MAXPOS.TEXTREF Store "CMZB.MINTEMP.PV" into CMZSTATS.ZONESTATSCABR.MINTEMP.TEXTREF Store "CMZB.MINPOS.PV" into CMZSTATS.ZONESTATSCABR.MINPOS.TEXTREF Store "CMZB.AVGTEMP.PV" into CMZSTATS.ZONESTATSCABR.AVGTEMP.TEXTREF Assume that the operator activates the button, executing the above script to switch the parameter references to zone B. At this point, because we are in "Manual" mode, we have the following conditions: l The parameter reference texts for CMZSTATS.ZONESTATSCABR have been changed. l The new parameter references have not been acquired, or are in progress of being acquired. l The current parameter references that CMSTATS.ZONESTATSCABR is using will report errors. l CMSTATS.ZONESTATSCABR.X_REFSTATE = "TRANSLATING."
To complete the operation, the HMIWeb display script does the following: Store "COMMIT" into CMZSTATS.ZONESTATSCABR.X_REFCOMMIT At this point, we have the following condition: l CMSTATS.ZONESTATSCABR.X_REFSTATE = "COMMITTING."
When the parameter references have been resolved (this may take several execution cycles), we have the following conditions: l CMSTATS.ZONESTATSCABR.X_REFSTATE = "IDLE." l The parameter references are now targeting zone B. l CMSTATS.ZONESTATSCABR is producing statistics for zone B.
11.10
Array and scalar variables in CAB
Preceding sections illustrated the various ways in which scalar and array data can be used in CAB programs. This next example uses scalar and array value CDPs and parameter references in various contexts of scope to demonstrate, in a single example, their similarities and differences. This section also includes sample code in Two-dimensional array example to illustrate how to initialize a two-dimensional array.
11.10.1
Example variables
The variables used in this example are as follows. These names were chosen to signify the type of variable rather than the meaning of the variable within an application.
l LclSclrVar ("Local Scalar Variable")--Declared explicitly within the Execute() subroutine of the user's source code.
l LclArrVar ("Local Array Variable")--Declared explicitly within the Execute() subroutine of the user's source code.
- 264 -
Chapter 11 - CAB and CDB Example Scenarios
l BlkScpSclrVar ("Block Scope Scalar Variable")--Declared explicitly within the CAB class outside the scope of any subroutine.
l BlkScpArrVar ("Block Scope Array Variable")--Declared explicitly within the CAB class outside the scope of any subroutine.
l SCLRCDP("SCaLar value CDP")--Declared through PDE CDP definition. Defined in program context by automatically generated declaration within BlockBase.
l ARRCDP ("ARRay value CDP")--Declared through PDE CDP definition. Defined in program context by automatically generated declaration within BlockBase.
l SCLRPREFSCLR ("SCaLar Parameter REFerence To SCaLar Parameter")-Declared through PDE Par. Ref. definition. Defined in program context by automatically generated declaration within BlockBase.
l SCLRPREFFXD ("SCaLar Parameter REFerence To FiXeD Element Of Array Parameter")-- Declared through PDE Par. Ref. definition. Defined in program context by automatically generated declaration within BlockBase.
11.10.2 PDE definitions
PDE definitions for the value CDPs and PRefs could be as shown in Table 76. In this example, it is assumed that you want to create parameter ARRCDP as a one-dimensional array with a base index different from the default. To do so, you must expose more attributes than are presented within the default view of PDE (refer to the Parameter Definition Editor Reference for information). Table 76 shows all supported CDP attributes.
You will need to modify the default PDE view by adding the attribute "First dimension lower bound" so that this attribute can be configured for the array CDP. On the Visual Studio main menu, select View > Configure PDE Views and then select the First dimension lower bound check box. If you want to change the attributes for minimum and/or maximum values (see "Minimum and maximum values"), you will need to add these attributes to the PDE view using the same technique.
Parameter name
Table 11.18 76 Value CDP Definitions
SCLRCDP
ARRCDP
Parameter description
Scalar value
Ten-element array value
Data type
FLOAT64
FLOAT64
First dimension array size
0
10
First dimension array lower bound
0
1
Access lock
ENGINEER
ENGINEER
Configuration load
LOAD
LOAD
Default value
100.0
0.0
Minimum value
-1.78E308
-1.78E308
Maximum value
1.78E308
1.78E308
11.10.3 Minimum and maximum values
The minimum and maximum values for SCLRCDP and ARRCDP correspond to the maximum finite magnitudes for a FLOAT64. These values are defaulted by PDE. You can narrow the range if you desire. If the default values are acceptable, you do not need to enter them. In accordance with the Data Owner Principle, range limits are checked whenever an external agent makes a store into a
- 265 -
Chapter 11 - CAB and CDB Example Scenarios
CAB instance. They are not checked for writes by the CAB program itself.
PDE definitions for the parameter references could be as shown in the following table.
Name
Table 11.19 Parameter Reference Definitions Description
Data type Data flow
SCLRPREFSCLR Scalar parameter reference to scalar parameter
SCLRPREFFXD Scalar parameter reference to element of array parameter
FLOAT64 INPUT FLOAT64 INPUT
11.10.4
Instance configuration
Instance configuration for the Value CDPs could be as shown in the following table. Note that although the table shows all elements of ARRCDP(), the properties form would show the array in scrollable form.
Name SCLRCDP
Table 11.20 Value CDP Configuration
Index
Value
Description
-----
175.0
Scalar value
ARRCDP
1
1000.0
Ten-element array value
ARRCDP
2
1000.0
Ten-element array value
ARRCDP
3
1000.0
Ten-element array value
ARRCDP
4
1000.0
Ten-element array value
ARRCDP
5
1000.0
Ten-element array value
ARRCDP
6
1000.0
Ten-element array value
ARRCDP
7
1000.0
Ten-element array value
ARRCDP
8
1000.0
Ten-element array value
ARRCDP
9
1000.0
Ten-element array value
ARRCDP
10
1000.0
Ten-element array value
Instance configuration for the parameter references could be as shown in the following table.
Table 11.21 Parameter Reference Configuration
Reference alias Reference address
Description
SCLRPREFSCLR TI100.PID1.PV
Scalar parameter reference to scalar parameter
SCLRPREFFXD FC100.NN1.PV(7) Scalar parameter reference to element of array parameter
The parameter reference configuration above assumes that the first reference is pointing to a PID block renamed to PID1 in a CM called TI100, and the second reference is pointing to the seventh element in a NumericArray block with 10 elements that is renamed to NN1 and is in a CM called FC100.
11.10.5
Program
The following program uses the variables defined above. The algorithm is not intended to be
- 266 -
Chapter 11 - CAB and CDB Example Scenarios
useful--it is intended to demonstrate the variable syntax. Note that whereas the indices for BlkScpArrVar and LclArrVar are in the range of 0 to 9, the index for ARRCDP is in the range of 1 to 10. 'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC
'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml
Public Class CABlock Inherits BlockBase
Dim BlkScpSclrVar As Double Dim BlkScpArrVar(10) As Double
Public Overrides Sub Execute() 'TODO: User should insert their Execute code here
Dim LclSclrVar As Integer Dim LclArrVar(10) As Double
' Make value and status available for all input ' parameter references PRefList.Read()
If Restart <> RestartEnum.None Then Initialize()
For LclSclrVar = 0 To 9 LclArrVar(LclSclrVar) = _ BlkScpArrVar(LclSclrVar) * SCLRPREFSCLR.Value ARRCDP(LclSclrVar + 1).Value = _ LclArrVar(LclSclrVar) * SCLRPREFFXD.Value
Next LclSclrVar
End Sub
Private Sub Initialize()
Dim LclSclrVar As Integer
BlkScpSclrVar = 0 For LclSclrVar = 0 To 9 BlkScpArrVar(LclSclrVar) = LclSclrVar / SCLRCDP.Value BlkScpSclrVar = BlkScpSclrVar + BlkScpArrVar(LclSclrVar) Next LclSclrVar
End Sub
End Class
11.10.6 Two-dimensional array example
The following code segment illustrates how to access a two-dimensional array. For this example,
- 267 -
Chapter 11 - CAB and CDB Example Scenarios
assume that a CDP called TESTARRAY was defined in the PDE as an array with type STRING and with first and second dimension array size of five. ` Example of initializing a two-dimensional 5x5 string array For i As Integer = 0 To 4 For x As Integer = 0 To 4 Me.TESTARRAY(i, x).Value = "test"Next
11.11
Initializing in response to system events
This example illustrates use of the Restart API to select alternative initializations based on system start-up events. The majority of CAB applications need not be concerned with Restart. But in some cases, you might want to design a block type that can be widely applied and that provides behavior that is consistent across all state transitions.
11.11.1 Fast history block
In this example, you create a simple block type to collect data into a history buffer. The block type is called HISTBUF. The intent is to collect history within the CEE at a rate that is faster than can be supported by Experion server. The collected history data could be shown in the operator view by an appropriately designed custom display.
You use an array CDP called HISTORY to hold the history values. HISTORY has 64 elements. It is organized as a "wrapping" buffer in which new data constantly overwrites the oldest data by wrapping around to the beginning of the array. Another CDP called LASTINDEX gives the index of the most recent history value.
Data is input to the block through a CDP called PVIN. In this block design, parameter references are not used. Instead, you plan for input data to PVIN to arrive through a Control Module graphical connection.
11.11.2
PDE definitions
Assume that you decided not to use PRefs in the solution to this problem. HISTORY is a onedimensional array CDP. You leave its index lower bound at the default of 0 as this is natural with a wrapping buffer. CDP definitions are shown in the following table.
Parameter name
Table 11.22 Value CDP Definitions
Parameter description Data type First dim array size
Access lock Config load
Default value
PVIN
Data element to be historized
FLOAT64 0
OPERATOR NOLOAD --
LASTINDEX Index of most recent INT32 0 history value
VIEWONLY NOLOAD --
HISTORY History value array
FLOAT64 64
VIEWONLY NOLOAD --
11.11.3 Program
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase
- 268 -
Chapter 11 - CAB and CDB Example Scenarios
Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System. Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() If Restart <> RestartEnum.None Then Initialize() LASTINDEX.Value = (LASTINDEX.Value + 1) Mod 64 HISTORY(LASTINDEX.Value).Value = PVIN.Value End Sub Private Sub Initialize() Dim i As Integer Select Case Restart Case RestartEnum.CEEWarmStart PVIN.Value = NaN ' Assume most of the history is valid but insert some ' Nan values so operator can see there is discontinuity. For i = LASTINDEX.Value + 1 To LASTINDEX.Value + 3 HISTORY(i Mod 64).Value = NaN Next i LASTINDEX.Value = ((LASTINDEX.Value + 3) Mod 64) Case Else ' This is where we end up for Restart of BlockLoad, ' BlockActivate or CEEColdStart. In all of these cases ' we must assume there is no valid history. PVIN.Value = NaN LASTINDEX.Value = 63 For i = 0 To LASTINDEX.Value HISTORY(i).Value = NaN Next i End Select End Sub End Class
11.12 Example using data type TIME
11.12.1
Shift calculations
One use of time processing within CAB would be to run a block periodically, synchronous with local wall clock time. This could be useful in calculating relevant data at the end of an operator shift.
There is more than one way to address this need within ACE. This example solves the problem with a CAB type called SHIFTCALC. SHIFTCALC is intended to run within a CM that executes periodically, perhaps once per minute. Every minute, the SHIFTCALC instance checks whether it is time to do shift calculations and if so, does them.
The shift interval is hard coded at eight hours within the program and is phased to correspond to midnight, 8:00 A.M., and 4:00 P.M. SHIFTCALC uses the Now property of the .NET structure DateTime to identify when to execute calculations. Now returns the value of local time. Thus, in SHIFTCALC, shift calculations always occur at the local target times regardless of changes in daylight savings time. The interval between the midnight calculations and the 8:00 A.M. calculations is normally eight hours. When local time shifts into daylight savings time in spring, the interval is shortened to seven hours. When local time shifts out of daylight savings time in fall, the interval is lengthened to nine hours.
- 269 -
Chapter 11 - CAB and CDB Example Scenarios
SHIFTCALC records the actual time at which the calculations have occurred within the value CDP LASTRUNTIME. LASTRUNTIME has the Experion PKSdata type TIME. Since TIME is always transported as universal time, the program must be written to adjust for the difference between its internal timing (local time) and the externally transported time (universal time). The ToUniversalTime method of DateTime is used to do this.
Although Experion PKStransports TIME values as universal time, they are always displayed as local time. Thus a supervisor can verify timely execution of a SHIFTCALC instance by examining LASTRUNTIME on an operational display. The display will show the time of last calculation as local time.
11.12.2 Value CDP definition for SHIFTCALC
The CAB uses one value CDP, as shown in the following table.
Parameter name
Table 11.23 Value CDP Definition for SHIFTCALC
Parameter description
Data First dim type array size
Access lock Config load
Default value
LASTRUNTIME Time of last shift calculation
TIME 0
VIEWONLY NOLOAD -----
11.12.3 Algorithm for SHIFTCALC
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock
Inherits BlockBase Dim NextCalcHour As Integer Public Overrides Sub Execute() Dim CurrentTime As DateTime Dim CurrentHour As Integer If Restart <> RestartEnum.None Then 'Calculate next shift change on startup 'Shift changes are midnight, 8:00am and 4:00pm NextCalcHour = Now.TimeOfDay.Hours NextCalcHour = (NextCalcHour + 8 - NextCalcHour Mod 8) Mod 24 End If CurrentTime = Now CurrentHour = CurrentTime.TimeOfDay.Hours If CurrentHour = NextCalcHour Then 'Shift change of midnight, 8:00am and 4:00pm has occurred 'Do some shift calculations and calculate the next shift change NextCalcHour = (CurrentHour + 8) Mod 24 LASTRUNTIME.Value = CurrentTime.ToUniversalTime DoShiftCalculations() End If End Sub Private Sub DoShiftCalculations()
- 270 -
Chapter 11 - CAB and CDB Example Scenarios
' Do shift calculations. End Sub End Class
Note that in the code above the internal subroutine DoShiftCalculations() is declared with VB.NET access type Private. This is not strictly necessary. But it is recommended as it accurately documents the way in which the subroutine can be used. Subroutines in CAB types can only be used internally to the type.
11.13 Example using data type TIMEOFDAY
11.13.1 Slow monitoring calculations
Another example of the use of time processing within CAB is to have a calculation execute periodically at regular intervals, or upon the occurrence of special events, but asynchronous with wall clock time. This could be useful for an application that does process monitoring with associated calculations.
There is more than one way to address this need within ACE. This example solves the problem with a CAB type called MONCALC. MONCALC is intended to run within a CM that runs periodically, perhaps once per minute. Every minute, the MONCALC instance checks whether it is time to do monitoring calculations and if so, does them.
MONCALC is set up to run under three conditions:
l On demand if the operator requests it by writing ON to the Boolean value CDP "RUNNOW."
l Whenever the block is loaded or activated and whenever you go through a cold or warm start.
l Periodically every three hours since its last execution.
MONCALC uses the DateTime property UtcNow rather than Now as the basis for its timing. Now returns local time whereas UtcNow returns universal time. Using UtcNow insures that the time between calculations will always be three hours since last execution unless there is a special event to make execution happen sooner. This is true regardless of changes in daylight savings time.
MONCALC always records the time of last execution in the value CDP "LASTRUNTIME." In this example it is assumed that LASTRUNTIME is only of interest to within the time of day so it is assigned the Experion PKStype TIMEOFDAY. Within the program LASTRUNTIME is derived form a universal time value using the DateTime property TimeOfDay. But it is always displayed as local time within operational displays.
11.13.2 Value CDP definitions for MONCALC
The CAB includes two value CDPs as shown in the following table.
Parameter name
Table 11.24 Value CDP Definitions for MONCALC
Parameter description
Data type
First dim Access lock Config
array size
load
Default value
RUNNOW
If ON causes program to run
BOOLEAN 0
OPERATOR LOAD TRUE
LASTRUNTIME Time of last calculation
TIMEOFDAY 0
VIEWONLY NOLOAD -----
- 271 -
Chapter 11 - CAB and CDB Example Scenarios
11.13.3 Algorithm for MONCALC
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock
Inherits BlockBase Dim NextRunTime As DateTime Public Overrides Sub Execute() 'This code performs monitoring calculations under three conditions: '1. On demand if the operator requests it by writing ON to the 'Boolean value CDP RUNNOW '2. Whenever the block is loaded or activated and whenever you go 'through a cold or warm start '3. Periodically every three hours since its last execution If Restart <> RestartEnum.None Then Initialize() If RUNNOW.Value Then RUNNOW.Value = False NextRunTime = Now.UtcNow End If If (Now.UtcNow >= NextRunTime) Then LASTRUNTIME.Value = Now.UtcNow.TimeOfDay NextRunTime = NextRunTime.AddHours(3.0) DoCalculation() End If End Sub Private Sub Initialize() RUNNOW.Value = True If Restart = RestartEnum.BlockLoad Then _ LASTRUNTIME.Value = New TimeSpan(0, 0, 0) Send("Executing Initialize subroutine") End Sub Private Sub DoCalculation() Send("Executing DoCalculation") End Sub End Class
Note that in the code above the internal subroutine DoCalculations() is declared with VB.NET access type Private. This is not strictly necessary. But it is recommended as it accurately documents the way in which the subroutine can be used. Subroutines in CAB types can only be used internal to the type.
11.14 Example using data type DELTATIME
11.14.1
Time-out monitor
Another example of time processing within CAB is a type, TIMEOUTMON, which looks for a start
- 272 -
Chapter 11 - CAB and CDB Example Scenarios
and stop signal within a specified time period. Such a block could be used to send alarms or to take other action if a process operation took too long. This functionality already exists within the CEE native block set. So TIMEOUTMON would not be implemented within CAB unless there was a particular reason to have the timing logic closely integrated with other programmatic processing. It does serve as a good illustration of how to use a CDP of type DELTATIME within CAB.
In this example, TIMEOUTMON supports two Boolean CDPs, STARTTIMING and STOPTIMING. It supports a configuration CDP called TIMEOUT that allows the timeout interval to be specified. TIMEOUT is of type DELTATIME. TIMEOUTMON also supports a ViewOnly CPD called TARGETTIME. TARGETTIME is assigned during timing operations and displays the time by which the operation must complete. Timing operations can be retriggered by setting STARTTIMING to ON if timing has already started.
Note that within the program, TIMEOUT has the .NET type TimeSpan and can be added to a variable of type DateTime to develop a target time.
11.14.2 Value CDP definitions for TIMEOUTMON
The value CDPs for this example are shown in the following table.
Parameter name
Table 11.25 Value CDP Definitions for TIMEOUTMON
Parameter description
Data type
First dim Access lock Config
array
load
size
Default value
STARTTIMING Start or restart timing operation
BOOLEAN 0
OPERATOR NOLOAD -----
STOPTIMING Stop timing operation
BOOLEAN 0
OPERATOR NOLOAD -----
TIMEOUT
Timeout interval default is one minute
DELTATIME 0
OPERATOR LOAD 01:00.0000
TARGETTIME Time when
TIME
0
operation must
complete
VIEWONLY NOLOAD -----
11.14.3 Algorithm for TIMEOUTMON
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock
Inherits BlockBase Dim Running As Boolean Public Overrides Sub Execute() 'TODO: User should insert their Execute code here If Restart <> RestartEnum.None Then STOPTIMING.Value = False
- 273 -
Chapter 11 - CAB and CDB Example Scenarios
STARTTIMING.Value = False 'Set the default TARGETTIME of 1/1/2000 7:00:00AM TARGETTIME.Value = _ New DateTime(2000, 1, 1, 0, 0, 0, 0).AddHours(7) End If If STOPTIMING.Value Then STARTTIMING.Value = False STOPTIMING.Value = False Running = False End If If STARTTIMING.Value Then STARTTIMING.Value = False Running = True TARGETTIME.Value = Now.UtcNow.Add(TIMEOUT.Value) 'Set timeout target value by adding CDP value of TIMEOUT 'to current time. The default timeout is 1 minute. TARGETTIME.Value = TARGETTIME.Value.Add(TIMEOUT.Value) End If If Running And (Now.UtcNow >= TARGETTIME.Value) Then Running = False HandleTimeOut() End If End Sub Private Sub HandleTimeOut() ' Take appropriate actions. Send("CAB TimeOut.") Send("TargetTime = " + TARGETTIME.Value.ToString) Send("TimeOut = " + TIMEOUT.Value.ToString) End Sub End Class
Note that in the code above the internal subroutine HandleTimeOut() is declared with VB.NET access type Private. This is not strictly necessary. But it is recommended as it accurately documents the way in which the subroutine can be used. Subroutines in CAB types can only be used internal to the type.
11.15 Use of data access status in CAB
11.15.1 Device monitor with Stop/Run command
This example illustrates a CAB type DEVMON that monitors a remote device that is connected through an OPC Server FB. DEVMON reads device status to report if there is a communication problem or if the device is not operating. It also supports a simple stop/run command. As part of stop/run handling, DEVMON issues stores and verifies status of the store requests. DEVMON's program is intended to run at a moderately high rate to insure that device status changes are reported quickly. But let us assume that you are unsure of whether the OPC connection will always return status information as quickly as the block executes. You could design the program to assume it always runs more slowly than the round trip communication time. But instead, you prefer to set things up so that DEVMON will always work, regardless of whether it runs faster or slower than communications. Under this assumption, values read from the device might come back more slowly than the DEVMON execution rate. This is not really a problem for the design because the last value read will
- 274 -
Chapter 11 - CAB and CDB Example Scenarios
be held until the next is available. The only effect would be that the response time is limited by the communication speed. Slow communication response is more of an issue for stores since you want to do status verification. But this can be handled by using "WritePending" status of parameter references.
11.15.2 Value CDP for DEVMON
One value CDP is used for DEVMON, as shown in the following table.
Parameter name
Table 11.26 Value CDP Definition for DEVMON
Parameter description Data First dim type array size
Access lock Config load
Default value
OPERCMD Receives Stop/Start commands
INT32 0
OPERATOR NOLOAD --
Parameter OPERCMD is intended to take on three possible values. l "0" means no command has been issued. l "1" commands the device to stop. l "2" command the device to run.
The operator is intended to use only values "1" and "2"--storing "0" is to have no effect.
11.15.3
Parameter references for DEVMON
Two parameter references are used in DEVMON as defined in the following table.
Table 11.27 Parameter Reference Definitions for DEVMON
Parameter name
Parameter description
Reference data type
DEVICECMD
Writes Stop/Start commands
INT32
DEVICESTS
Reads Stopped/Running status
INT32
Data flow OUTPUT INPUT
At instance configuration time, DEVICECMD is to be configured to point to the command parameter of a particular remote device while DEVICESTS is to be configured to point to the status parameter of that same device. The values for these references are determined by the device specifications. Assume they are as follows: l DEVICECMD points to a parameter that uses these values:
o "0" means stop. o "1" means run.
l DEVICESTS points to a parameter that uses these values: o "0" means stopped. o "1" means running. o "2" means failed.
11.15.4 Algorithm for DEVMON
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon
- 275 -
Chapter 11 - CAB and CDB Example Scenarios
Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Imports System.DateTime Imports CABlock.CommandEnum Imports CABlock.DeviceCommandEnum Imports CABlock.DeviceStatusEnum Public Enum DeviceCommandEnum : DeviceStop : DeviceRun : End Enum Public Enum DeviceStatusEnum
DeviceStopped DeviceRunning DeviceFailed End Enum Public Enum CommandEnum : NoCommand : Stop_ : Run : End Enum Public Class CABlock Inherits BlockBase Dim CommandState As Integer Public Overrides Sub Execute() If Restart <> RestartEnum.None Then CommandState = NoCommand OPERCMD.Value = NoCommand End If If OPERCMD.Value <> NoCommand And CommandState = NoCommand Then Select Case OPERCMD.Value Case Stop_ DEVICECMD.Value = DeviceStop DEVICECMD.Write() CommandState = Stop_ Case Run DEVICECMD.Value = DeviceRun DEVICECMD.Write() CommandState = Run Case Else ' Operator error, ignore OPERCMD.Value = NoCommand End Select ElseIf CommandState <> NoCommand Then If Not DEVICECMD.WriteStatus <> _ CABAccStatusEnum.WritePending Then CommandState = NoCommand If DEVICECMD.WriteStatus <> CABAccStatusEnum.OK Then PROGSTSDESC.Value = "Write to DEVICECMD failed: " + _ DEVICECMD.WriteStatus.ToString() Abort() End If OPERCMD.Value = NoCommand End If Else ' CommandState = NoCommand And OPERCMD.Value = NoCommand DEVICESTS.Read() If DEVICESTS.ReadStatus <> CABAccStatusEnum.OK Then PROGSTSDESC.Value = "Read of DEVICESTS failed: " + _ DEVICESTS.ReadStatus.ToString() Abort() ElseIf DEVICESTS.Value <> DeviceRunning Then PROGSTSDESC.Value = "Device not running"Abort()
- 276 -
Chapter 11 - CAB and CDB Example Scenarios
End If End If End Sub End Class
Notes about this program: l Three enumeration types are defined to make the program more self-documenting:
DeviceCommandEnum, DeviceStatusEnum, and CommandEnum. To avoid having to use fully qualified enumeration member names (for example, using "None" instead of "CommandEnum.None"), three imports statements were added near the top of the program. Each of these enumerations is defined within the VB.NET namespace called "CAB." Thus, the imports statements take the form, "Imports CAB.CommandEnum." l There is a member called "Stop_" in the CommandEnum enumeration. The name "Stop" would have been more natural but could not be used because it collides with a VB.NET keyword. l There is no apparent reason to expose the value of CommandState to the outside world. Thus, it is defined as a block scope variable rather than a CDP. l The program checks for bad values of OPERCMD within the Select statement. If found, it simply over-writes them. l The program uses the built-in PROGSTSDESC parameter to publish any problems it discovers. l The program uses the Abort() subroutine to force an exception and event when a problem is discovered.
11.16 Use of parameter reference variables in CAB
TIP This example does not compile if X_PLATOPT is set to ACEANDC300 because the variable CMRef(4) is of aggregate type (Class) and is declared to be a persistent data member of CABlock.
11.16.1
Setting control state for a group of CMs
In this example, you implement a CAB type called SETMODE to serve as a utility for an SCM. Usually, an instance of SETMODE does nothing. But when requested by an SCM, it puts a set of up to five CMs into a state of performing automatic regulatory control. SETMODE also supports the operation of taking CMs out of automatic operating mode. SETMODE takes three actions in response to an SCM request to go on control.
l Verifies that EXECSTATE is Active for each CM. If an InActive EXECSTATE is found it does not change it automatically. Instead it asks a human being to do so.
l Sets MODEATTR to Program.
l Sets MODE to Auto.
11.16.2
Value CDPs for SETMODE
Two value CDPs are used in SETMODE as defined in the following table.
- 277 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
Table 11.28 Value CDP Definitions for SETMODE
Parameter description
Data First dim Access lock Config
type array size
load
Default value
REQUEST SCM writes to request change in control action.
INT32 0
PROGRAM NOLOAD 0
RESPONSE SCM reads to learn of completion of request.
INT32 0
VIEWONLY NOLOAD 0
REQUEST can take these possible values: l "0" means no request. l "1" means request for manual control. l "2" means request for automatic control.
RESPONSE can take these possible values: l "0" means the requested action is underway. l "1" means the request succeeded. l "2" means the request failed.
11.16.3 Parameter references for SETMODE
In the design of SETMODE, you anticipate up to five CMs to be manipulated. Thus, you have five sets of parameters to reference. You design SETMODE to handle a total of 15 parameter references as shown in the following table.
Table 11.29 Parameter Reference Definitions for SETMODE
Parameter name
Parameter description
Reference data type Data flow
EXECSTATE1
Points to EXECSTATE for Control Module 1 INT32
INPUT
MODEATTR1 MODE1 EXECSTATE2
Points to MODEATTR for Control Module 1 INT32
Points to MODE for Control Module 1
INT32
Points to EXECSTATE for Control Module 2 INT32
OUTPUT OUTPUT INPUT
MODEATTR2 MODE2 EXECSTATE3
Points to MODEATTR for Control Module 2 INT32
Points to MODE for Control Module 2
INT32
Points to EXECSTATE for Control Module 3 INT32
OUTPUT OUTPUT INPUT
MODEATTR3 MODE3 EXECSTATE4
Points to MODEATTR for Control Module 3 INT32
Points to MODE for Control Module 3
INT32
Points to EXECSTATE for Control Module 4 INT32
OUTPUT OUTPUT INPUT
MODEATTR4 MODE4 EXECSTATE5
Points to MODEATTR for Control Module 4 INT32
Points to MODE for Control Module 4
INT32
Points to EXECSTATE for Control Module 5 INT32
OUTPUT OUTPUT INPUT
- 278 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
Parameter description
Reference data type Data flow
MODEATTR5 MODE5
Points to MODEATTR for Control Module 5 INT32
Points to MODE for Control Module 5
INT32
OUTPUT OUTPUT
SETMODE is written to manipulate parameters EXECSTATE, MODEATTR and MODE for each CM referenced.
11.16.4 Algorithm for SETMODE
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC Imports Honeywell.CAB.BlockMap Imports Honeywell.CAB.SysCommon.CABAccStatusEnum 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Imports System.DateTime Imports CABlock.RCModeAttrEnum : Imports CAB.RCModeEnum Imports CABlock.CMExecStateEnum Imports CABlock.MyRequestEnum : Imports CAB.MyResponseEnum Imports CABlock.MyStateEnum Enum CMExecStateEnum Inactive = 0 : Active = 1 End Enum Enum RCModeAttrEnum Operator = 1 : Program = 2 End Enum Enum RCModeEnum
RCManual = 0 : RCAutomatic = 1 End Enum Enum MyRequestEnum NoRequest = 0 : ControlManual = 1 : ControlAutomatic = 2 End Enum Enum MyResponseEnum Pending = 0 : Succeeded = 1 : Failed = 2 End Enum Enum MyStateEnum NoAction = 0 : DoWrite = 1 : DoCheck = 2 End Enum Class CMRefClass
Public IsNull As Boolean Public ExecState As Int32PRef Public ModeAttr As Int32PRef Public Mode As Int32PRef End Class Public Class CABlock Inherits BlockBase Dim CMRef(4) As CMRefClass Dim State, ModeTarget As Integer
- 279 -
Chapter 11 - CAB and CDB Example Scenarios
Dim IllegalNullRef As Boolean Dim LastI As Integer Private Sub Initialize() Dim I As Integer, FoundNullCMRef As Boolean State = NoAction ModeTarget = RCManual REQUEST.Value = NoRequest RESPONSE.Value = Succeeded IllegalNullRef = False For I = 0 To 4 CMRef(I) = New CMRefClass Next If Restart = BlockLoad Then ' For each CMRef assign the PRefs and check for consistency. ' If inconsistency is found, flag bad configuration. If Not SetUpCMRef(0, EXECSTATE1, MODEATTR1, MODE1) Then IllegalNullRef = True : Exit Sub End If If Not SetUpCMRef(1, EXECSTATE2, MODEATTR2, MODE2) Then IllegalNullRef = True: Exit Sub End If If Not SetUpCMRef(2, EXECSTATE3, MODEATTR3, MODE3) Then IllegalNullRef = True: Exit Sub End If If Not SetUpCMRef(3, EXECSTATE4, MODEATTR4, MODE4) Then IllegalNullRef = True: Exit Sub End If If Not SetUpCMRef(4, EXECSTATE5, MODEATTR5, MODE5) Then IllegalNullRef = True: Exit Sub End If ' CMRef(0) at least must be non-null LastI = 0 If CMRef(LastI).IsNull Then IllegalNullRef = True : Exit Sub End If ' Find the last non-null CMRef For I = 1 To 4 If Not CMRef(I).IsNull Then LastI = I Else Exit For End If Next I ' All non-null CMRefs must be at the low indices For I = LastI + 1 To 4 If Not CMRef(I).IsNull Then IllegalNullRef = True : Exit Sub End If Next I End If End Sub Function SetUpCMRef(ByVal I As Integer, ByVal ExecState As _ Int32PRef, ByVal ModeAttr As Int32PRef, ByVal Mode As _ Int32PRef) As Boolean ' Assign the PRefs into the CM reference object CMRef(I).ExecState = ExecState CMRef(I).ModeAttr = ModeAttr CMRef(I).Mode = Mode ' Make sure that for each CM reference ' either all PRefs or none are null CMRef(I).IsNull = ExecState.IsNull
- 280 -
Chapter 11 - CAB and CDB Example Scenarios
If CMRef(I).IsNull <> ModeAttr.IsNull Or _ CMRef(I).IsNull <> ModeAttr.IsNull Then ' This is a disallowed configuration, indicate error SetUpCMRef = False Else ' This is an allowed configuration, indicate no error SetUpCMRef = True End If End Function Public Overrides Sub Execute() If Restart <> None Then Initialize() ' If CE who created instance made mistake with ' null PRef configuration ' report an error and force the instance into exception state If IllegalNullRef Then PROGSTSDESC.Value = "Bad parameter reference configuration"Abort() End If ' Make value and status available for all input ' parameter references PRefList.Read() If REQUEST.Value <> NoRequest Then Select Case REQUEST.Value Case ControlManual ModeTarget = RCManual State = DoWrite Case ControlAutomatic ModeTarget = RCAutomatic State = DoWrite Case Else ' Bad REQUEST.Value entered, will overwrite End Select REQUEST.Value = NoRequest RESPONSE.Value = Failed End If If State <> NoAction Then Select Case State Case DoWrite Select Case ProcessWrite() Case Failed Response.Value = Failed State = NoAction Case Else ' MyResponseEnum.Pending State = DoCheck End Select Case DoCheck Select Case CheckWriteStatus() Case Failed Response.Value = Failed State = NoAction Case Succeeded Response.Value = Succeeded State = NoAction Case Else ' MyResponseEnum.Pending ' Keep checking End Select End Select End If ' Store values to destination for any output references ' whose values were written PRefList.Write() End Sub
- 281 -
Chapter 11 - CAB and CDB Example Scenarios
Function ProcessWrite() As Integer Dim I As Integer Dim InactiveFound As Boolean InactiveFound = False For I = 0 To LastI If CMRef(I).ExecState.Value <> Active Then Send("EXECSTATE Inactive at CM number" + I.ToString) InactiveFound = True End If Next I If InactiveFound Then Return Failed For I = 0 To LastI CMRef(I).ModeAttr.Value = Program CMRef(I).Mode.Value = ModeTarget Next I Return MyResponseEnum.Pending End Function Function CheckWriteStatus() As Integer Dim I As Integer Dim Response As Integer For I = 0 To LastI Response = Check1ParameterWrite(CMRef(I).ModeAttr) If Response <> Succeeded Then Return Response Else Response = Check1ParameterWrite(CMRef(I).Mode) If Response <> Succeeded Then Return Response End If Next I Return Succeeded End Function Function Check1ParameterWrite(ByVal Parameter As Int32PRef) _ As Integer If Parameter.WriteStatus = WritePending Then Return MyResponseEnum.Pending ElseIf Parameter.WriteStatus <> OK Then Return Failed Else Return Succeeded End If End Function End Class
Notes about this program:
l In VB.NET, enumeration members can each be defined on a separate line or they can be defined on the same line if each is separated by the VB.NET line separator, ":". Here, the program listing is made a little more compact by putting enumeration members on the same line, as in the following.Enum enumMyRequest None = 0 : ControlManual = 1 : ControlAutomatic = 2 End Enum
l The program uses a simple VB.NET class to group parameter references that point to the same Control Module. This is the class "CMRefClass."
l CMRefClass has 3 data members of type "Int32PRef." There is an additional Boolean data member, "IsNull." When True, IsNull indicates that all of the parameter references are null. When false, IsNull indicates that none of the parameter references are null. The IsNull data member of CMRefClass is set by using the IsNull property of Int32PRef to identify null references.
l The program uses a block scope array variable, "CMRef(5)"to allow indexing over each CM.
- 282 -
Chapter 11 - CAB and CDB Example Scenarios
11.17
l Within the Initialize() subroutine are copies of the parameter references established at configuration time into CMRef(). This is a way to work around the fact that CAB does not support indexed parameter references.
l The CMRef array is only initialized as a result of block configuration load. It's not necessary to do this initialization at any other time as the address of a parameter reference can only change during load.
l Initialize() also does validation checking on the parameter reference configuration of the instance. The CAB type is designed so that all instances must obey these rules: o If any of the three parameters on a particular CM are referenced then all three must be referenced. o Up to five CMs can be referenced but at least one CM must be referenced. o If only one CM is referenced then the parameter references labeled "1" must be used.
o The non-null references must be at low indices and the null references at high indices.
l The program has defined four internal functions to make the program simple and readable. These are Initialize(), SetUpCMRef(), ProcessWrite(), CheckWriteStatus() and Check1ParameterWrite(). These routines are distinct from Execute() in that they are unknown to the CAB system infrastructure. Also, no other CAB type can use them.
l Two of the internal functions, SetUpCMRef() and Check1ParameterWrite(), pass arguments of type Int32PRef.
History time examples
TIP This discussion does not apply to CABs that have X_PLATOPT set to ACEANDC300 because history is not supported on C300.
This is not a complete example, but a discussion that includes short code examples to illustrate some of the techniques of using time when accessing history.
11.17.1 What is UTC time?
UTC is an acronym that does not have a clear translation but it is the most convenient acronym for international use. Roughly translated to English, UTC stands for "Universal Time Coordinated." As a successor to GMT (Greenwich Mean Time), UTC removes a local place name from a standard intended to be used internationally. Additionally, the exact UTC time is maintained by techniques differing from the maintenance of GMT.
Time zones around the world are kept as offsets from UTC. When not on daylight savings time, London, England has a zero offset. Locations west of London have negative offsets until they reach 12 hours. Locations east of London have positive offsets until they reach 12 hours.
Why is UTC an important concept? It represents a standard or absolute time value independent of the location of the user. History servers store timestamps in UTC.
11.17.2
Data types that store time
Visual Basic .NET has a data type called DateTime, which is the time data type that CAB's wrapped history calls use. DateTime stores a time without regard to whether that time is UTC or not--in
- 283 -
Chapter 11 - CAB and CDB Example Scenarios
other words, there is no Time Zone indicator stored with a DateTime type of time. You have to know what you stored into it.
Among the DateTime methods, four may be of interest:
l .ToUniversalTime--this method assumes that the stored time is in "local time," and applies the local offset to move it to UTC time.
l .ToLocalTime--this method assumes that the stored time is in UTC time, and applies the local offset to move it to "local time."
l .UtcNow--this method loads the current time, in UTC terms, into the variable. l .Now--this method loads the current time, in terms of the local time zone, into the variable.
If you are using straight OPC calls, you need to use the OPC-provided time data type Opc.Hda.Time. It has a slightly different internal format than DateTime. You can make a new Opc.Hda.Time typed variable from a DateTime typed variable.
11.17.3
Some CAB rules related to time
These rules are listed elsewhere in this guide, but are duplicated here for continuity of the discussion.
l All parameters of type TIME and TIMEOFDAY are stored internally (in ERDB) in UTC time format.
l If you enter a TIME or TIMEOFDAY CDP default value in the PDE, it should be entered in regional (local) time. The value will be converted automatically to UTC time when stored in the ERDB.
l Control Builder will display TIME and TIMEOFDAY parameters in PC regional time.
l Displays will display TIME and TIMEOFDAY parameters in PC regional time.
l CAB programs that convert TIME and TIMEOFDAY parameters to a string format are responsible for converting TIME and TIMEOFDAY to regional time using the VB.NET conversions (.ToLocalTime) that are available.
11.17.4 Time usage examples
Let us assume that we are working remotely, from a house in Hawaii. Hawaii is -10 hours from UTC; that is, 10 hours west, or "behind,"UTC. Let us further assume that we are accessing an OPC Server--for example, an Experion OPC HDA Server--in Kuwait City. Kuwait City is +3 hours from UTC; that is, 3 hours east, or "ahead of," UTC.
We make the following set of calls:
Dim StartingTime, EndingTime As System.DateTime StartingTime = System.DateTime.UtcNow ' The time now in UTC EndingTime = StartingTime.AddMinutes(-15) ' 15 minutes ago
The StartingTime is "now" in UTC (not Kuwait or Hawaii local time), and the EndingTime is "15 minutes before now." UTC is the technique used to store these, and UTC is what OPC wants, so these calls will work as expected. They have the correct data in them so that when they are used in an OPC History call, the user gets the last 15 minutes of data.
Next, consider the following set of calls:
- 284 -
Chapter 11 - CAB and CDB Example Scenarios
StartingTime = System.DateTime.UtcNow.Today.AddDays(-1) ' Start of the current day minus 1 day, so yesterday at midnight EndingTime = System.DateTime.UtcNow.Today ' today at midnight OverallSts = History.GetHistory(ExperionServer, _ "ASSET_105.PIDLOOP.PIDA.PV", StartingTime, EndingTime, _ ValueCount, HistoryValues, TimeStamps, Statuses)
These calls are similar to the "StartingTime" and "EndingTime"calls in the previous example. It is important to note that the "midnight"in these calls is midnight UTC time, not midnight in Kuwait. So, these are probably not the calls someone might use if they were interested in a "what happened yesterday at my plant?" type of history request. Be aware that calls using the System.DateTime class (like the one directly above) get their UTC time from the ACE. Calls using the Opc.Hda.Time class get their UTC time from the server. In most situations, the ACE and the server are keeping track of time in a reasonably coordinated manner. This is not guaranteed, however. If you see some oddities relative to history data, you might check the differences in time on the ACE and the Server. If we wanted to set up starting and ending times that make sense in the local time zone, we can do this:
' StartingTime is the start of today - 1 day, so yesterday at midnight StartingTime = System.DateTime.Now.Today.AddDays(-1) ' EndingTime is the start of today (at midnight) EndingTime = System.DateTime.Now.Today OverallSts = History.GetHistory(ExperionServer, _ "ASSET_105.PIDLOOP.PIDA.PV", StartingTime.ToUniversalTime, _ EndingTime.ToUniversalTime, ValueCount, HistoryValues, _ TimeStamps, Statuses)
Note that we are using Now, not UtcNow, and in the GetHistory calls, we are using the method ToUniversalTime on the StartingTime and EndingTime variables. Here is another example, similar to the one above, but using the straight OPC calls:
Dim OPCStartingTime, OPCEndingTime As Opc.Hda.Time ' OPCStartingTime is the start of today - 1 day + 7 hours, ' so 7:00 am yesterday OPCStartingTime = New Opc.Hda.Time(System.DateTime.Now.Today.Add Days(-1).AddHours(7).ToUniversalTime) ' OPCEndingTime is the start of today - 1 day + 8 hours, ' so 8:00 am yesterday OPCEndingTime = New Opc.Hda.Time(System.DateTime.Now.Today.Add Days(-1).AddHours(8).ToUniversalTime)
This one sets up starting and ending times for "yesterday, 7 A.M. to 8 A.M." in terms of local time. Since the Opc.Hda.Time class does not have a rich set of methods, we took advantage of the System.DateTime class's methods. Remember that all time specified to the OPC Server must be in UTC.
11.18 Reading history values using wrapped methods
TIP This example does not compile if X_PLATOPT is set to ACEANDC300 because history is not supported in CAB/C300.
- 285 -
Chapter 11 - CAB and CDB Example Scenarios
This example shows a CAB type called READHIST that reads the last 15 minutes worth of history data from the point ASSET_105.PIDLOOP.PIDA.PV from the Experion server HIST_SRV. The values retrieved are copy to the CDP array HISTVALUES, their corresponding time stamps to HISTTSS, their corresponding history statuses to HISTHSTS, and their corresponding statuses HISTSTS showing whether each value was good (true)or bad (false). HISTCOUNT will be set to the number of history values read. Any errors that occur will be written to the PROGSTSDESC FDP and other information will be written to STATUS. See "History APIs" for more information.
TIP If your system uses redundant Experion servers, use the Redirection Manager when accessing the Experion PKSOPC HDA server (see the Reading history values from redundant servers example).
As a good practice, a programmer should use try catch blocks around any OPC .NET API calls or the wrapped method calls to catch any exception that the OPC .NET API calls may throw. Throwing exceptions is the mechanism that OPC uses to report errors.
11.18.1 Value CDPs for READHIST
Several Value CDPs are used in READHIST as defined in the following table.
Parameter name
Table 11.30 Value CDP Definitions for READHIST
Parameter description Data type First dim array size
Access lock
Config load
Size Default value
HISTVALUES History Values
FLOAT64 500
PROGRAM NOLOAD -- --
HISTTSS
History Time Stamps TIME
500
PROGRAM NOLOAD -- --
HISTHSTS
History Value's History Statuses
HISTSTS
Indicates if value is good (true) or bad (false)
HISTCOUNT Number of values retrieved
STATUS
Status information
INT32
500
BOOLEAN 500
INT32
0
STRING 0
PROGRAM NOLOAD -- -PROGRAM NOLOAD -- --
PROGRAM NOLOAD -- -PROGRAM NOLOAD 255 --
11.18.2 Algorithm for READHIST
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double
- 286 -
Chapter 11 - CAB and CDB Example Scenarios
Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Dim ExperionServer As Opc.Hda.Server Dim ExperionURL As New Opc.URL Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim StartingTime As DateTime Dim EndingTime As DateTime Dim ValueCount As Integer = 0 Dim OverallSts As Opc.ResultID Dim HistoryValues() As Double Dim TimeStamps() As DateTime Dim HistStatuses() As Opc.Hda.Quality Dim Statuses() As Opc.Da.Quality Dim i As Integer STATUS.Value = ""If Restart <> RestartEnum.None Or _ CABSTATE.Value = CABStateEnum.Exception Then 'The first time the CAB executes, we will connect
'to the HDA server or if the CAB previously had 'an Exception, we will reconnect to the HDA server 'to see if this clears up the problem ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "HIST_SRV"ExperionURL.Path = History.ExperionHistoryServerName Try 'Create unconnected instance to the Hda server object then ' connect to it ExperionServer = New Opc.Hda.Server(New OpcCom.Factory, _ ExperionURL) History.ConnectToHDAServer(ExperionServer) Catch ex As Exception PROGSTSDESC.Value = "Unable to connect to History Server."STATUS.Value = ex.Message Abort() End Try End If StartingTime = System.DateTime.UtcNow EndingTime = StartingTime.AddMinutes(-15) ' 15 minutes ago Try OverallSts = History.GetHistory(ExperionServer, _ "ASSET_105.PIDLOOP.PIDA.PV", StartingTime, EndingTime, _ ValueCount, HistoryValues, TimeStamps, HistStatuses, _ Statuses) Catch ex As Exception PROGSTSDESC.Value = "Unable to get history data."STATUS.Value = ex.Message Abort() End Try If OverallSts.Failed Then ' problem reading history data PROGSTSDESC.Value = OverallSts.ToString STATUS.Value = OverallSts.ToString Else 'transfer history data to CDPs HISTCOUNT.Value = HistoryValues.GetLength(0) If HISTCOUNT.Value > 0 Then For i = 0 To HISTCOUNT.Value - 1 HISTVALUES(i).Value = HistoryValues(i) HISTTSS(i).Value = TimeStamps(i) HISTHSTS(i).Value = HistStatuses(i) If Statuses(i).Equals(Opc.Da.Quality.Good) Then
- 287 -
Chapter 11 - CAB and CDB Example Scenarios
HISTSTS(i).Value = True Else
HISTSTS(i).Value = False End If
Next End If STATUS.Value = HISTCOUNT.Value.ToString + " values read."End If End Sub End Class
11.19 Reading history values using only the OPC .Net API
TIP This example does not compile if X_PLATOPT is set to ACEANDC300 because history is not supported in CAB/C300.
This example shows a CAB type called READHIST2 that performs the same scenario as in the previous example, but uses only the OPC.Net API classes and methods, except for the wrapped method to connect to the Experion server (see "History APIs").
11.19.1 Algorithm for READHIST2
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Dim ExperionServer As Opc.Hda.Server Dim ExperionURL As New Opc.URL Dim HistItemID(0) As Opc.ItemIdentifier Dim HistIDResults() As Opc.IdentifiedResult Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim OPCStartingTime As Opc.Hda.Time Dim OPCEndingTime As Opc.Hda.Time Dim ValueCount As Integer = 0 Dim OverallSts As Opc.ResultID Dim HistoryValues() As Opc.Hda.ItemValueCollection Dim i As Integer STATUS.Value = "" If Restart <> RestartEnum.None Or _ CABSTATE.Value = CABStateEnum.Exception Then 'The first time the CAB executes, we will connect
'to the HDA server or if the CAB previously had 'an Exception, we will reconnect to the HDA server 'to see if this clears up the problem
- 288 -
Chapter 11 - CAB and CDB Example Scenarios
ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "HIST_SRV"ExperionURL.Path = History.ExperionHistoryServerName Try 'Create unconnected instance to the Hda server object
' then connect to it ExperionServer = New Opc.Hda.Server(New OpcCom.Factory, _ ExperionURL) History.ConnectToHDAServer(ExperionServer) Catch ex As Exception PROGSTSDESC.Value = "Unable to connect to History Server."STATUS.Value = ex.Message Abort() End Try Try 'Set the History ItemID HistItemID(0)= _ New Opc.ItemIdentifier("ASSET_105.PIDLOOP.PIDA.PV") 'then create this Item ID to be used in the history access HistIDResults = ExperionServer.CreateItems(HistItemID) Catch ex As Exception PROGSTSDESC.Value = _ "Unable to create item for history access."STATUS.Value = ex.Message Abort() End Try End If OPCStartingTime = New Opc.Hda.Time(System.DateTime.UtcNow) OPCEndingTime = New Opc.Hda.Time(Date.UtcNow.AddMinutes(-15)) _ ' 15 minutes ago
Try HistoryValues = ExperionServer.ReadRaw(OPCStartingTime, _ OPCEndingTime, ValueCount, False, HistIDResults) Catch ex As Exception PROGSTSDESC.Value = "Error trying to read history data."STATUS.Value = ex.Message Abort() End Try OverallSts = HistoryValues(0).ResultID If OverallSts.Failed Then ' problem reading history data PROGSTSDESC.Value = OverallSts.ToString STATUS.Value = OverallSts.ToString Else 'transfer history data to CDPs HISTCOUNT.Value = HistoryValues(0).Count If HISTCOUNT.Value > 0 Then For i = 0 To HISTCOUNT.Value - 1 HISTVALUES(i).Value = HistoryValues(0).Item(i).Value HISTTSS(i).Value = HistoryValues(0).Item(i).Timestamp HISTHSTS(i).Value = _ HistoryValues(0).Item(i).HistorianQuality If HistoryValues(0).Item(i).Quality.Equals _
(Opc.Da.Quality.Good) Then HISTSTS(i).Value = True
Else HISTSTS(i).Value = False
End If Next End If STATUS.Value = HISTCOUNT.Value.ToString + " values read."End If
If Not HistIDResults Is Nothing Then HistServer.ReleaseItems(HistIDResults) End If
- 289 -
Chapter 11 - CAB and CDB Example Scenarios
End Sub End Class
11.20 Reading average history values using wrapped methods
TIP This example does not compile if X_PLATOPT is set to ACEANDC300 because history is not supported in CAB/C300.
This example shows a CAB type called READAVGHIST that get yesterday's one-hour averages from the point ASSET_105.PIDLOOP.PIDA.PV from the Experion server HIST_SRV. The values retrieved are copied to the CDP array AVEHISTVALS, their corresponding time stamps to HISTTSS, and their corresponding history statuses to HISTHSTS, and their corresponding statuses HISTSTS showing whether each value was good (true) or bad (false). It will also copy the minimum values, maximum values, and the number of sample values into the CDP arrays MINARRAY, MAXARRAY, and NUMSAMPLES, respectively. AVECOUNT will be set to the number of hourly average retrieved. Any errors that occur will be written to the PROGSTSDESC FDP and other information will be written to STATUS. See "History APIs" for more information.
TIP If your system uses redundant Experion servers, use the Redirection Manager when accessing the Experion PKSOPC HDA server (see the Reading history values from redundant servers example).
11.20.1 Value CDPs for READAVGHIST
Several Value CDPs are used in READAVGHIST as defined in the following table.
Parameter name
Table 11.31 Value CDP Definitions for READAVGHIST
Parameter description
Data type
First dim array size
Access lock
Config load
Size Default value
AVEHISTVALS Average History Values
FLOAT64 500 PROGRAM NOLOAD -- --
MINVALUES
Minimum value used FLOAT64 500 in Average History Value
PROGRAM NOLOAD -- --
MAXVALUES
Maximum value used FLOAT64 500 in Average History Value
PROGRAM NOLOAD -- --
NUMSAMPLES Number of samples INT32 used to calculate the average value
500 PROGRAM NOLOAD -- --
- 290 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
HISTTSS
Parameter description
Data type
First dim array size
Access lock
Config Size Default
load
value
History Time Stamps TIME
500 PROGRAM NOLOAD -- --
HISTHSTS HISTSTS
AVECOUNT STATUS
History Value's History Statuses
Indicates if value is good (true) or bad (false)
Number of values retrieved
Status information
INT32
500
BOOLEAN 500
INT32
0
STRING 0
PROGRAM NOLOAD -- -PROGRAM NOLOAD -- --
PROGRAM NOLOAD -- -PROGRAM NOLOAD 255 --
11.20.2 Algorithm for READAVGHIST
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Dim ExperionServer As Opc.Hda.Server Dim ExperionURL As New Opc.URL Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim HourInterval As New TimeSpan(1, 0, 0) ' 1 hour interval Dim StartingTime As DateTime Dim EndingTime As DateTime Dim ValueCount As Integer Dim OverallSts As Opc.ResultID Dim AveValues() As Double Dim TimeStamps() As DateTime Dim HistStatuses() As Opc.Hda.Quality Dim Statuses() As Opc.Da.Quality Dim NumberSamples() As Integer Dim Minimums() As Double Dim Maximums() As Double Dim i As Integer STATUS.Value = ""If Restart <> RestartEnum.None Or _ CABSTATE.Value = CABStateEnum.Exception Then 'The first time the CAB executes, we will connect
'to the HDA server or if the CAB previously had 'an Exception, we will reconnect to the HDA server 'to see if this clears up the problem
- 291 -
Chapter 11 - CAB and CDB Example Scenarios
ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "HIST_SRV"ExperionURL.Path = History.ExperionHistoryServerName Try
'Create unconnected instance to the Hda server 'object then connect to it ExperionServer = New Opc.Hda.Server(New OpcCom.Factory, _ ExperionURL) History.ConnectToHDAServer(ExperionServer) Catch ex As Exception PROGSTSDESC.Value = "Unable to connect to History Server."STATUS.Value = ex.Message Abort() End Try End If ' StartingTime is the start of today - 1 day, ' so yesterday at midnight StartingTime = System.DateTime.Now.Today.AddDays(-1) ' EndingTime is the start of today (at midnight) EndingTime = System.DateTime.Now.Today Try OverallSts = History.GetAvgHistory(ExperionServer, _ "ASSET_105.PIDLOOP.PIDA.PV", StartingTime.ToUniversalTime, _ EndingTime.ToUniversalTime, HourInterval, _ ValueCount, AveValues, TimeStamps, HistStatuses, Statuses, _ NumberSamples, Minimums, Maximums) Catch ex As Exception PROGSTSDESC.Value = "Unable to get history data."STATUS.Value = ex.Message Abort() End Try If OverallSts.Failed Then ' problem reading history data PROGSTSDESC.Value = OverallSts.ToString STATUS.Value = OverallSts.ToString Else 'transfer history data to CDPs AVECOUNT.Value = ValueCount If AVECOUNT.Value > 0 Then For i = 0 To AVECOUNT.Value - 1 AVEHISTVALS(i).Value = AveValues(i) HISTTSS(i).Value = TimeStamps(i) HISTHSTS(i).Value = HistStatuses(i) If Statuses(i).Equals(Opc.Da.Quality.Good) Then HISTSTS(i).Value = True Else HISTSTS(i).Value = False End If ' A zero length array means that kind of data ' is not available through this server If NumberSamples.GetLength(0) > 0 Then NUMSAMPLES(i).Value = NumberSamples(i) End If If Minimums.GetLength(0) > 0 Then MINVALUES(i).Value = Minimums(i) End If If Maximums.GetLength(0) > 0 Then MAXVALUES(i).Value = Maximums(i) End If Next End If STATUS.Value = AVECOUNT.Value.ToString + " values read."End If End Sub
- 292 -
Chapter 11 - CAB and CDB Example Scenarios
End Class
11.21 Reading average history values using the OPC .Net API
TIP This example does not compile if X_PLATOPT is set to ACEANDC300 because history is not supported in CAB/C300.
The following CAB Source code could be used to perform a function similar to the previous example, but using only the OPC.Net API classes and methods (except for the wrapped method to connect to the Experion PKSServer). The only difference is that only the one-hour averages (along with their associated timestamps and statuses) are retrieved. The Number of Samples, Minimum value, and Maximum values are not retrieved. See "History APIs" for more information.
11.21.1 Algorithm for READAVGHIST2
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Dim ExperionServer As Opc.Hda.Server Dim ExperionURL As New Opc.URL Dim ItemID(0) As Opc.ItemIdentifier Dim HistIDResults() As Opc.IdentifiedResult Dim HistItemID(0) As Opc.Hda.Item Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim HourInterval As New TimeSpan(1, 0, 0) ' 1 hour interval Dim OPCStartingTime As Opc.Hda.Time Dim OPCEndingTime As Opc.Hda.Time Dim ValueCount As Integer Dim OverallSts As Opc.ResultID Dim HistoryValues() As Opc.Hda.ItemValueCollection Dim i As Integer Dim aggregates() As Opc.Hda.Aggregate Dim found As Boolean = False STATUS.Value = ""If Restart <> RestartEnum.None Or _ CABSTATE.Value = CABStateEnum.Exception Then 'The first time the CAB executes, we will connect
'to the HDA server or if the CAB previously had 'an Exception, we will reconnect to the HDA server 'to see if this clears up the problem ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "HIST_SRV"ExperionURL.Path =
- 293 -
Chapter 11 - CAB and CDB Example Scenarios
History.ExperionHistoryServerName Try 'Create unconnected instance to the Hda server object
'then connect to it ExperionServer = New Opc.Hda.Server(New OpcCom.Factory, _ ExperionURL) History.ConnectToHDAServer(ExperionServer) Catch ex As Exception PROGSTSDESC.Value = "Unable to connect to History Server."STATUS.Value = ex.Message Abort() End Try ' First, we will make sure that this HDA server has the
' AVERAGE aggregate defined aggregates = ExperionServer.GetAggregates() For Each aggr As Opc.Hda.Aggregate In aggregates If aggr.ID = Opc.Hda.AggregateID.AVERAGE Then found = True Exit For End If Next If Not found Then PROGSTSDESC.Value = _ "Average History values not available."STATUS.Value = PROGSTSDESC.Value Abort() End If Try 'Set the History ItemID for the Point.Parameter ItemID(0) = New _ Opc.ItemIdentifier("ASSET_105.PIDLOOP.PIDA.PV") 'then create this Item ID to be used in the
'history access HistIDResults = ExperionServer.CreateItems(ItemID) 'then copy this ItemID to a History Item (needed for the 'ReadProcessed call) HistItemID(0) = New Opc.Hda.Item(HistIDResults(0)) 'and set the AVERAGE aggregate id. HistItemID(0).AggregateID = Opc.Hda.AggregateID.AVERAGE Catch ex As Exception PROGSTSDESC.Value = _ "Unable to create item for history access."STATUS.Value = ex.Message Abort() End Try End If
'OPCStartingTime is the start of today - 1 day, so 'yesterday at midnight OPCStartingTime = New Opc.Hda.Time( _ System.DateTime.Now.Today.AddDays(-1).ToUniversalTime 'OPCEndingTime is the start of today (at midnight) OPCEndingTime = New Opc.Hda.Time( _ System.DateTime.Now.Today.ToUniversalTime)' Try HistoryValues = _ ExperionServer.ReadProcessed(OPCStartingTime, _ OPCEndingTime, _ Convert.ToDecimal(HourInterval.TotalSeconds), _ HistItemID) Catch ex As Exception PROGSTSDESC.Value = _ "Error trying to read average history data."STATUS.Value = ex.Message Abort() End Try OverallSts = HistoryValues(0).ResultID
- 294 -
Chapter 11 - CAB and CDB Example Scenarios
If OverallSts.Failed Then ' problem reading history data PROGSTSDESC.Value = OverallSts.ToString STATUS.Value = OverallSts.ToString Else 'transfer history data to CDPs AVECOUNT.Value = HistoryValues(0).Count If AVECOUNT.Value > 0 Then For i = 0 To AVECOUNT.Value - 1 AVEHISTVALS(i).Value = _ Convert.ToDouble(HistoryValues(0).Item(i).Value) HISTTSS(i).Value = HistoryValues(0).Item(i).Timestamp HISTHSTS(i).Value = _ HistoryValues(0).Item(i).HistorianQuality If HistoryValues(0).Item(i).Quality.Equals _
(Opc.Da.Quality.Good) Then HISTSTS(i).Value = True
Else HISTSTS(i).Value = False
End If Next End If STATUS.Value = AVECOUNT.Value.ToString + " values read."End If
If Not HistIDResults Is Nothing Then HistServer.ReleaseItems(HistIDResults) End If End Sub End Class
11.22 Reading history values from redundant servers
TIP
This example does not compile if X_PLATOPT is set to ACEANDC300 because history is not supported in CAB/C300.
This scenario shows the changes that need to be made to the example Reading history values using wrapped methods for the case where the Experion PKSserver is on redundant nodes (for example, HIST_SRVA and HIST_SRVB). The entire example will not be reproduced here. Only the necessary changes are included. See "History APIs for more information.
11.22.1
Preparation
The following preliminary steps must be performed. 1. Load the Redirection Manager (RDM) on the ACE node that the CABs will be running on. See
"Installing Redirection Manager"in the Redirection Manager User's Guide. 2. Configure the RDM to access the Experion PKSOPC HDA server from the two redundant
nodes. See "Configuring Redirection Manager"in the Redirection Manager User's Guide.
See the Redirection Manager User's Guide for more information about RDM.
- 295 -
Chapter 11 - CAB and CDB Example Scenarios
11.22.2 Code changes
In this example, assume that the Base PROGID of Honeywell.Redirect1 was configured. The code for this example is the same as the code in the example Reading history values using wrapped methods with the following exceptions: Replace the following code: ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "HIST_SRV"ExperionURL.Path = History.ExperionHistoryServerName with the following code: ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "localhost"ExperionURL.Path = "Honeywell.Redirect1"
11.23 Reading history for an extended period
TIP
This example does not compile if X_PLATOPT is set to ACEANDC300 because history is not supported in CAB/C300.
This example shows a CAB type called READ_1DAY that reads up to one day's worth of one-minute snapshots from an Experion server HIST_SRV from the point ASSET_105.PIDLOOP.PIDA.PV. It then uses CABMath functions to find the average of all good history values along with the minimum and maximum values. Since a day's worth of one-minute snapshots is 1440 values and the Experion PKSHDA server retrieves less than 1440 values at a time, this example shows a way to retrieve all of the values. See "History APIs" for more information.
The CAB reads the history values and copies them to a FLOAT64 CDP array HISTVALUES, copies their related time stamps to HISTTSS, copies their related history statuses to HISTHSTS, and their related statuses HISTSTS showing whether each value was good (true) or bad (false). HISTCOUNT is set to the number of history values read. Any errors that occur are written to the PROGSTSDESC FDP, and other information is written to STATUS. The average value is written to AVERAGE, the minimum value is written to MINIMUM, and the maximum value is written to MAXIMUM.
Several Value CDPs are used in READ_1DAY as defined in the following table.
Parameter name
Table 11.32 Value CDPs for READ_1DAY
Parameter description Data type First dim Access array lock size
Config Size Default
load
value
HISTVALUES History Values
FLOAT64 1440 PROGRAM NOLOAD -- --
HISTTSS
History Time Stamps TIME
1440 PROGRAM NOLOAD -- --
HISTHSTS HISTSTS
History Value's History Statuses
Indicates if value is good (true) or bad (false)
INT32
1440
BOOLEAN 1440
PROGRAM NOLOAD -- -PROGRAM NOLOAD -- --
- 296 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
Parameter description Data type First dim Access array lock size
Config Size Default
load
value
HISTCOUNT Number of values
INT32
0
retrieved
PROGRAM NOLOAD -- --
STATUS
Status information STRING 0
PROGRAM NOLOAD 255 --
AVERAGE MINIMUM MAXIMUM
Average of all 1minute snapshots
FLOAT64 0
Minimum value of all FLOAT64 0 1-minute snapshots
Maximum value of all FLOAT64 0 1-minute snapshots
PROGRAM NOLOAD -- -PROGRAM NOLOAD -- -PROGRAM NOLOAD -- --
TIP
If you must know the maximum number of values that the OPC HDA server will return, the MaxReturnValues property, accessed from the GetStatus method from the HDA Server object, contains this data. In the following code example, ExperionServer.GetStatus.MaxReturnValues will contain the maximum number of values that an Experion OPC HDA server will return.
11.23.1 Algorithm for READ_1DAY
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Dim ExperionServer As Opc.Hda.Server Dim ExperionURL As New Opc.URL Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim StartingTime As DateTime Dim EndingTime As DateTime Dim ValueCount As Integer = 0 Dim OverallSts As Opc.ResultID Dim HistoryValues() As Double Dim TimeStamps() As DateTime Dim HistStatuses() As Opc.Hda.Quality Dim Statuses() As Opc.Da.Quality Dim i, j As Integer STATUS.Value = ""If Restart <> RestartEnum.None Or _ CABSTATE.Value = CABStateEnum.Exception Then
- 297 -
Chapter 11 - CAB and CDB Example Scenarios
'The first time the CAB executes, we will connect 'to the HDA server or if the CAB previously had 'an Exception, we will reconnect to the HDA server 'to see if this clears up the problem
ExperionURL.Scheme = Opc.UrlScheme.HDA ExperionURL.HostName = "HIST_SRV"ExperionURL.Path = History.ExperionHistoryServerName Try 'Create unconnected instance to the Hda server object
'then connect to it ExperionServer = New Opc.Hda.Server(New OpcCom.Factory, _ ExperionURL) History.ConnectToHDAServer(ExperionServer) Catch ex As Exception PROGSTSDESC.Value = _ "Unable to connect to History Server."STATUS.Value = ex.Message Abort() End Try End If OverallSts = Opc.ResultID.Hda.S_MOREDATA StartingTime = System.DateTime.UtcNow EndingTime = StartingTime.AddDays(-1) ' 1 day ago from now HISTCOUNT.Value = 0 j=0 'we will keep looping and getting history data until
'no more data is found While OverallSts.Equals(Opc.ResultID.Hda.S_MOREDATA) ValueCount = 0 Try OverallSts = History.GetHistory(ExperionServer, _ "ASSET_105.PIDLOOP.PIDA.PV", StartingTime, EndingTime, _ ValueCount, HistoryValues, TimeStamps, HistStatuses, _ Statuses) Catch ex As Exception PROGSTSDESC.Value = "Error trying to read history data."STATUS.Value = ex.Message Exit While End Try If OverallSts.Failed Then 'problem reading history data PROGSTSDESC.Value = OverallSts.ToString STATUS.Value = OverallSts.ToString Exit While Else 'transfer history data to CDPs HISTCOUNT.Value += ValueCount If ValueCount > 0 Then For i = 0 To ValueCount - 1 HISTVALUES(j + i).Value = HistoryValues(i) HISTTSS(j + i).Value = TimeStamps(i) If Statuses(i).Equals(Opc.Da.Quality.Good) Then HISTSTS(j + i).Value = True
Else HISTSTS(j + i).Value = False
End If Next End If j += ValueCount 'adjust the Starting time for the next history call StartingTime = HISTTSS(j - 1).Value.AddSeconds(-30) End If End While
- 298 -
Chapter 11 - CAB and CDB Example Scenarios
If STATUS.Value = "" Then STATUS.Value = HISTCOUNT.Value.ToString + " values read."End If ' We will copy the HISTVALUES to an array that will have
' the exact number of good values found. This way we can use the 'CABMath functions to determine the average, minimum, 'and maximum values. J=0 Dim DataArray(HISTCOUNT.Value - 1) As Double For i = 0 To HISTCOUNT.Value - 1 If HISTSTS(i).Value Then 'The value is good so we will use it in the calculations DataArray(i) = HISTVALUES(i).Value J += 1 End If Next AVERAGE.Value = CABMath.Avg(DataArray) MINIMUM.Value = CABMath.Min(DataArray) MAXIMUM.Value = CABMath.Max(DataArray) If STATUS.Value = "" Then STATUS.Value = HISTCOUNT.Value.ToString + " values read. " + _ j.ToString + " values used in calculations."End If End Sub End Class
11.24 Use of file IO in CAB
TIP
This example does not compile if X_PLATOPT is set to ACEANDC300 because file IO is not supported in CAB/C300.
11.24.1 Description of CAB Type FILEIO
This example illustrates the use of CAB file I/O (introduced in R300). File I/O requires that a CAB type run in Distributed mode which can be set in PDE on the FIXED tab. The CAB Type example FILEIO is a simple scenario of creating a text file, using basic file manipulation commands for copying and deleting a file, and reading a text file.
It is important to note that the CAB code that does file I/O has the responsibility to not keep the file open for an extended amount of time. It is also important to use the "Try...Catch...Finally" clauses to handle any exceptions that may occur so that you do not get into an exception loop if the file happens to be busy.
CAB supports local file I/O on the ACE that the CAB is running on. This example creates the file on the desktop of the ACE node itself. In order for a user to create and execute CAB types that are able to create, delete, read, or write files that are on nodes other then the ACE, the ACE (and cabblient.exe) process must be executing under a userid that has network credentials, see Appendix C: Configuring CAB to support accessing files on remote systems.
11.24.2
Value CDPs for FILEIO
Several Value CDPs are used for FILEIO as defined in the following table.
- 299 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
FILENAME
Table 11.33 Value CDP Definitions for FILEIO
Paramete r
descriptio n
Data type
First dim arra y size
Access lock Config load
Default value Siz e
File name STRING 0 of file to create on ACE
LOAD OPERATO R
32 Hello World.txt
FILESTRING String to STRING 0 write to file on ACE
LOAD OPERATO R
32 Hello World
FLOATCDP
Float
FLOAT64 0
number
to append
to convert
to string
in file
LOAD OPERATO R
-- 1.1
String
STRING 0
STRINGREA read from
D
file
32 --
OPERATO NOLOA
R
D
FILEPATH
Path
STRING 0
where file
resides
on ACE
LOAD OPERATO R
51 c:\users\default\deskto p
SENDMSG
Set ON if
0
you want BOOLEA
to send N
info to
msg
summary
-- --
OPERATO NOLOA
R
D
EXCOUNT
Count of number of exception s
INT32
0
-- --
OPERATO NOLOA
R
D
Parameter FILEPATH is the path where the file will be created. In this case the path will write the file onto the ACE desktop. Depending on the security restrictions under which ACE is running (based on what the service Experion PKSCDA-SP Service is running as on ACE) may restrict where you can create the file on the ACE node. If ACE is running under an account that does not have Administrator privileges, it is recommended that you create the files under this directory: C:\users.
In the previous example, the FILESTRING to create the file is set to "Hello World," which is less than the 32-character limit for both FILESTRING and STRINGREAD. If a value other than "Hello World" is used--one that is more than 32 characters--the value will be truncated to 32 characters.
11.24.3
Symbol Attributes for FILEIO
In the PDE Symbol Attributes tab, you can format your CAB type to have pins and parameters appearing on the faceplate for each instance you create (see the following table). The number represents the ordinal position that the parameter will appear.
- 300 -
Chapter 11 - CAB and CDB Example Scenarios
Parameter name
CABSTATE
Table 11.34 Symbol Attribute Definitions for FILEIO
Input Top Input Left Output Bottom Output Right Config
pin
pin
pin
pin
face
--
--
--
--
--
CABCOMMAND --
--
--
--
--
FILENAME
--
--
--
--
--
STRINGREAD --
--
--
--
--
SENDMSG
--
0
--
--
--
EXCOUNT
--
--
--
--
--
Monitor face 0 1 2 3 -4
11.24.4 Algorithm for FILEIO
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase 'Define sw and sr here so the handle will 'be retained across CAB execution cycles 'in case we need to close the file due to file contention Dim sw As StreamWriter Dim sr As StreamReader Public Overrides Sub Execute() If Restart <> RestartEnum.None Then
' Initialize the exception count to zero on startup EXCOUNT.Value = 0 End If ' Get the filename to create from CDP named FILENAME Dim path As String ' Add 1 to CDP called FLOATCDP to write the file If Me.FLOATCDP.Value > 100 Then FLOATCDP.Value = 1 End If FLOATCDP.Value += 1 Try
path = FILEPATH.Value.TrimEnd(" ") + FILENAME.Value If File.Exists(path) = False Then ' Create a file to write to. sw = File.CreateText(path) sw.WriteLine(Me.FILESTRING.Value) sw.WriteLine(FLOATCDP.Value) sw.Flush() sw.Close() End If
Catch e As Exception 'If file i/o gets an exception, put the exception msg 'in PROGSTSDESC. If we get more than 10 'exceptions, make CAB go to DORMANT by setting the
- 301 -
Chapter 11 - CAB and CDB Example Scenarios
'CABCOMMAND to QUIT to prevent an endless exception 'loop from occurring PROGSTSDESC.Value = "ERR:" + e.ToString() Send("FILEIO ERR:" + e.ToString()) EXCOUNT.Value += 1 If EXCOUNT.Value > 10 Then Me.CABCOMMAND.Value = CABCommandEnum.Quit End If Finally ' Close the file in the Finally clause in case we get ' an exception and the close didn't happen above If Not sw Is Nothing Then sw.Close() End If End Try Try ' Open the file to read from. sr = File.OpenText(path) Me.STRINGREAD.Value = "" 'Peek Returns the next available character but does ' not consume it. The current position of the ' StreamReader is not changed by Peek. The returned ' value is -1 if no more characters are currently ' available Do While sr.Peek() >= 0 STRINGREAD.Value = STRINGREAD.Value + sr.ReadLine() Loop If SENDMSG.Value Then Send("CABLIB:FILEIO - Info read from file is " + STRINGREAD.Value) End If sr.Close() Dim path2 As String = FILEPATH.Value + "temp." + FILENAME.Value ' Ensure that the target does not exist. File.Delete(path2) ' Copy the file. File.Copy(path, path2) If SENDMSG.Value Then Send("CABLIB:FILEIO - " + path + " was copied to " + path2) End If ' Delete the newly created file. File.Delete(path) If SENDMSG.Value Then Send("CABLIB:FILEIO - " + path + " was successfully deleted.") End If Catch e As Exception 'If file i/o gets an exception, put the exception msg in PROGSTSDESC. If we get ' more than 10 exceptions, make CAB go to DORMANT by setting the ' ' CABCOMMAND to QUIT to prevent an endless exception loop from occurring PROGSTSDESC.Value = "ERR:" + e.ToString() Send("FILEIO ERR:" + e.ToString()) EXCOUNT.Value += 1 If EXCOUNT.Value > 10 Then Me.CABCOMMAND.Value = CABCommandEnum.Quit End If Finally ' Close the file in the Finally clause in case we get an exception and the close didn't happen above If Not sr Is Nothing Then sr.Close() End If End Try End Sub
- 302 -
Chapter 11 - CAB and CDB Example Scenarios
End Class
Notes about this program:
l Use of the StreamReader and StreamWriter classes for file I/O. These classes are available in the .Net Framework library under the system.IO namespace to read/write files within CAB. In order to find out more information about these specific classes and their available API function members, search for the class name (System.IO.StreamReader or System.IO.StreamWriter) in the CAB Developer Visual Studio environment under Help->Search and select the class description. This will list all the available functions that you can use for file IO.
l The "Try...Catch...Finally" is used to handle any exceptions that may occur during file I/O. An example exception that you may get is if a file is busy due to another application using the file and having it busy. The FILEIO example doesn't stop on the first exception because it wants to keep trying (a CAB in exception will attempt to run again on the next CM cycle) for 10 tries and then quit. It is important to use the Finally clause to close your file in case an exception occurs. The Finally code will always be executed regardless if an exception occurs or not.
l File.Delete is used to delete files and File.Copy is used to copy files. Both of these functions are a part of the system.IO namespace under the File class. To find out more information about the File class the available API function members, search for the class name (system.io.file) in the CAB Developer Visual Studio environment under Help->Search and select the File class description. This will list all the available functions that you can use for file manipulation.
l Setting CABCOMMAND.Value = CABCommandEnum.Quit can be used in Distributed CABs to change the CABSTATE from NORMAL to DORMANT. When a CAB is in a DORMANT state, it will no longer run until a manual change of CABCOMMAND to RUN. You should only use the QUIT command when there is something unexpected happening in the program that the Engineer should take a look at and fix before re-deploying the CAB. In this example, we gave the file IO ten chances of handling an exception but trying again (keep in mind that a CABSTATE of EXCEPTION means the CAB will run again to see if the exception has cleared). If we receive over ten exceptions, it is possible that there is a conflict of the file usage and the Engineer should take a look at changing the CM scheduling to not have file contention with other applications if that was the cause of the exceptions.
11.25
Using a CAB to change the MODE of a TPN point
The MODE parameter is an enumeration on the TPN. Enumerations on the TPN can be expressed as either a numeric (ordinal value) or as a string, and the following examples will show how to use both an integer and a string to change a MODE. The examples will describe the implementation of CAB types called INTMODE and STRMODE that use a parameter reference accessing a TPN point via OPC Gateway.
The system on which these examples were created contains an OPC Gateway named OPC_APP038 and an Application Module (AM) containing a Regulatory AM point named FC381. The OPC Gateway name and the AM point name are used to configure CAB parameter references in these examples.
The following table shows the integer (ordinal) values, and the corresponding string values, for the AM Regulatory point MODE parameter. For other point types, refer to the appropriate Parameter Reference Dictionary.
Table 11.35 MODE Parameter Values for AM Regulatory Control Point
Integer (ordinal) value
String value
0
"MAN"
1
"AUTO"
2
"CAS"
- 303 -
Chapter 11 - CAB and CDB Example Scenarios
11.26 Method 1: Using an integer to change a MODE
11.26.1 Integer method (INTMODE) PDE definitions
On the Fixed tab in PDE, set the value of the fixed definition parameter ACCESSLEVEL to CONTCONTROL. When the CAB has ACCESSLEVEL set to CONTCONTROL there is no need to have the TPN point MODATTR set to PROGRAM. PDE definitions for the value CDPs and the Parameter Reference could be as follows.
11.26.2
Value CDP definitions for INTMODE
Two Value CDPs are used in INTMODE as defined in the following table.
Parameter name
Table 11.36 Value CDP Definitions for INTMODE
Parameter description Data First dim Access lock Config
type array size
load
Default value
CURRENTMODE The current mode of the INT32 0 target point
OPERATOR NOLOAD 0
NEWMODE
The value to write to the INT32 0 target point's MODE
OPERATOR NOLOAD 0
11.26.3
Parameter reference definition for INTMODE
INTMODE uses one parameter reference as defined in the following table.
Table 11.37 Parameter Reference Definition for INTMODE
Parameter name Parameter description
Reference data type
MODEREF
Points to the MODE of the target point INT32
Data flow IN/OUT
Before loading the CM containing INTMODE, open the INTMODE properties form, select the Monitoring Parameters tab, and add the CURRENTMODE and NEWMODE CDPs. Now, select the Parameter References tab and enter the path to the point whose mode is to be changed. In this example, OPC_APP038.FC381.MODE.INTERNAL was entered. Note that to use an integer to set a MODE, the string ".INTERNAL" must be added after "MODE" when configuring a parameter reference.
To change the mode in the target point, the user will select the NEWMODE CDP on the faceplate of INTMODE and enter the desired value. This is done from the Monitoring View. For example, to change the MODE to AUTO, you would enter the integer value of 1 (one) as previously indicated in Using a CAB to change the MODE of a TPN point.
11.26.4 Algorithm for INTMODE
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC
- 304 -
Chapter 11 - CAB and CDB Example Scenarios
'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() MODEREF.Read()
`Verify the MODEREF read was OK before using the value. If MODEREF.ReadStatus = CABAccStatusEnum.OK Then
CURRENTMODE.Value = MODEREF.Value If CURRENTMODE.Value <> NEWMODE.Value Then MODEREF.Value = NEWMODE.Value MODEREF.Write() End If Else CURRENTMODE.Value = "???"End If End Sub End Class
11.27 Method 2: Using a string to change a MODE
11.27.1
String method (STRMODE) PDE definitions
On the Fixed tab in PDE, set the value of the fixed definition parameter ACCESSLEVEL to CONTCONTROL. When the CAB has ACCESSLEVEL set to CONTCONTROL there is no need to have the TPN point MODATTR set to PROGRAM. PDE definitions for the value CDPs and the Parameter Reference could be as follows.
11.27.2 Value CDP definitions for STRMODE
Two value CDPs are used in STRMODE as defined in the following table.
Parameter name
Table 11.38 Value CDP Definitions for STRMODE
Parameter description Data type
First dim Access lock Config
array size
load
Default value
CURRENTMODE The current mode of the STRING 0 target point
OPERATOR NOLOAD 0
NEWMODE
The value to write to the STRING 0 target point's MODE
OPERATOR NOLOAD 0
11.27.3 Parameter reference definition for STRMODE
STRMODE uses one parameter reference as defined in the following table.
Table 11.39 Parameter Reference Definition for STRMODE
Parameter name
Parameter description
Reference data type
MODEREF
Points to the MODE of the target point STRING
Data flow IN/OUT
- 305 -
Chapter 11 - CAB and CDB Example Scenarios
Before the CM containing STRMODE is loaded, open the STRMODE properties form and select the Monitoring Parameter tab and add the CURRENTMODE and NEWMODE CDPs. Now select the Parameter References tab and enter the path to the point whose mode is to be changed. In this example, OPC_APP038.FC381.MODE. To change the mode in the target point, the user will select the NEWMODE CDP on the faceplate of INTMODE and enter the desired value. This is done from the Monitoring View. For example, to change the MODE to AUTO, you would enter the string value of "AUTO" as previously indicated in Using a CAB to change the MODE of a TPN point.
11.27.4 Algorithm for STRMODE
'Imports for the standard Honeywell supplied namespaces Imports Honeywell.CAB.SysCommon Imports Honeywell.CAB.SysBase Imports Honeywell.CAB.BlockBase Imports Honeywell.CAB.Math Imports Honeywell.CAB.OPC 'Imports for the Math namespace Imports System.Math Imports System.Double Imports System.IO Imports System.Xml Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() MODEREF.Read()
`Verify the MODEREF read was OK before using the value If MODEREF.ReadStatus = CABAccStatusEnum.OK Then
`Standardize strings by trimming and making them uppercase `to ensure that comparisons are valid CURRENTMODE.Value = MODEREF.Value.Trim().ToUpper() NEWMODE.Value = NEWMODE.Value.Trim().ToUpper() If CURRENTMODE.Value <> NEWMODE.Value Then MODEREF.Value = NEWMODE.Value MODEREF.Write() End If Else CURRENTMODE.Value = "???"End If End Sub End Class
- 306 -
CHAPTER
12
CAB AND CDB OPERATIONS
12.1 Startup and shutdown
12.1.1
Custom Algorithm Blocks
Startup and shutdown of the CAB build-time environment (tools for creating CAB types) are manual procedures within the Experion PKSCB application. Startup of the Microsoft Visual Studio development environment occurs when you use CB menu selections to initiate the creation or edit of a CAB type. Shutdown occurs when you end the creation or edit session by closing Microsoft Visual Studio.
Startup and shutdown behavior of CABs in the run-time environment follows that of the ACE application on which they are hosted. Behavior is equivalent to that of any native block running on ACE. This includes block activation or deactivation. In addition, CAB/ACE algorithm execution (atomic execution mode) terminates automatically if its execution time exceeds 250 milliseconds (see Transition descriptions). CAB/C300 has a different execution time limit. (see CAB/C300 execution time limit).
12.1.2
Custom Data Blocks
Startup and shutdown of the CDB build-time environment (tools for creating CDB types) are manual procedures within the Experion PKSCB application. Startup of the PDE tool occurs when you use CB menu selections to initiate the creation or edit of a CDB type. Shutdown occurs when you end the creation or edit session by closing the PDE.
CDBs run on PC hardware, hosted by the ACE application, and on controller hardware hosted by the controller's CEE application. In this case, startup and shutdown behavior within the run-time environment is equivalent to that of any native blocks running under Experion PKSACE or controller applications.
12.2 Process operations
12.2.1
Monitor CAB and CDB
Monitoring CAB and CDB operations is the same as for strategies using native blocks. The normal Experion PKSmonitoring features apply to CAB and CDB. CAB and CDB can be monitored as part of routine process operations, which would normally be conducted from Station. You can also use standard Windows performance monitoring tools. See Configuring the Local Security Policy for
- 307 -
Chapter 12 - CAB and CDB operations more information.
12.2.2
View CAB alarms
CAB alarms are reported in exactly the same manner as other Experion PKSalarms. For information on alarms specific to CAB, see CAB alarms.
12.3
View CAB and CDB from Station
As with native blocks, CAB and CDB can be monitored in Station. Some of the applicable Station capabilities are: l Faceplate display--you can view selected parameters such as:
o CDPs that you have configured to be visible on the faceplate. o CABSTATE and CABCOMMAND FDPs that appear on the faceplate by default. o Other FDPs that you select (they must be FDPs that are allowed to be exposed).
l Detail Display l Custom schematics--can include CDPs from CABs and CDBs. l Alarm Summary--CAB alarms will appear here. l Message Summary--allows you to view CAB message strings generated in the CAB program
with the Send() subroutine. l CM charts. l Block Properties forms.
All of these functions are standard with Experion PKSStation.
12.4
Properties forms specific to CAB and CDB
CAB and CDB property forms can be viewed in CB and in Station, in the same manner as native block forms. CAB and CDB forms have some parameters and tabs that are unique, and these are described here.
TIP The block property forms can be customized in PDE when the type is defined. The form configurations shown below are the default configurations.
12.4.1
Where to find information
For a summary of the FDPs displayed on the following forms, see FDPs specific to CAB. Detailed descriptions of the parameters are in Detailed description of CAB specific FDPs. Information on how to customize the Block Configuration Forms is found in the Parameter Definition Editor Reference.
- 308 -
Chapter 12 - CAB and CDB operations
12.4.2 12.4.3 12.4.4 12.4.5 12.4.6
12.4.7
Main tab of a CAB property form
The following table shows the portion of the CAB Property form Main tab that contains CAB-specific parameters. See the references cited in Where to find information for information on each parameter shown. Note that all of these parameters are read-only on both the project and monitor side instances.
Main tab of a CDB property form
The following figure show portions of the CDB Main tab that contain CDB-specific parameters. See the references cited in Where to find information above for information on each parameter shown. Note that these parameters are read-only on both the project and monitor side instances.
Value CDPs tab for CAB and CDB
In the following figure, this tab is present for both CAB and CDB if value CDPs were configured when the type was defined. The figure shows a portion of a CAB properties form. A CDB form will not have the Parameter References, Source, and Alarms tabs. If you view the Value CDPs tab on the monitor side, you can change CDP values on the running CAB. If you view the tab on the project side, you can change values only if the parameter's Configuration load attribute was set to LOAD when you created the type, but they will not be reflected in the monitor side instance until you do a load.
Parameter References tab
In the following figure, this tab is present for CAB if parameter references were configured when the type was defined. If you view this tab on the project side, you can use the browse buttons to configure parameter references (or change existing references). You can also type or paste a parameter reference address instead of using the browse button. You must do a load for these parameters to be reflected on the monitor side instance. If you view the tab from the monitor side, you can see the last-loaded references but you cannot change them unless the parameters are enabled for dynamic re-referencing capability (see Entering a new reference manually).
Source tab
In the following figure, this tab is present for CAB instances. It displays the CAB algorithm. On the project side, it displays the most recent code saved to ERDB from Microsoft Visual Studio. On the monitor side, it shows the last-loaded version of code (the code that the instance is using). If you modify and save code, you must do a load to transfer the new code to the monitor side instance. The Source tab has some important uses. It can be used to compare the code that is running in the CEE (monitor side) with the code stored in the ERDB (project side). It can also be used to recover code that has been saved over. See ` Recover CAB source code.' There are situations where the CAB may not include the source code that was used to generate its algorithm. This could occur in the case where Honeywell or a third-party developer created a CAB type and considered the code to be proprietary. In these cases, the Source tab will appear as shown in the following figure.
Alarms tab
In Figure, this tab is present on CAB Properties forms. For information on the parameters that are displayed on this tab, see CAB alarms.
- 309 -
Chapter 12 - CAB and CDB operations You can change configuration values on the project side, but you must do a load to reflect them on the monitor side. You cannot change values on the monitor side.
- 310 -
CHAPTER
13
CAB AND CDB SYSTEM ADMINISTRATION
13.1 CAB development environment administration
13.1.1
Recovering from a Control Builder crash
In the unlikely event that Control Builder crashes while Visual Studio is open to create or edit a CAB type, the Visual Studio process may not terminate properly. If this happens, you must close all Visual Studio sessions and use Task Manager to delete all instances of devenv.exe that are running. Since an edit session was in progress, the Edit Lock will be set, and you will need to use the ERDB administration tool, DBAdmin to clear Edit Lock. For information, see "Using DBADMIN"in the Control Hardware Troubleshooting and Maintenance Guide.
13.2 User management
13.2.1
User management functions
CAB and CDB use the standard Experion PKSuser management features. For example, access to Control Builder requires a logon password. Access to parameters in the run-time environment are determined by the Access Lock attributes that are configured when the block type is created.
The CAB developer's license is a user management function that is special for CAB. A developer's license is required for users to be able to create and edit CAB types. For more information, see Licensing considerations.
13.2.2
Setting user permissions
Creating and editing CAB types in Microsoft Visual Studio .NET, requires the user to have Administrative privileges on the target PC or be a member of the Engineers group.
13.2.3
Establishing a User account for SIM-ACE
In order for a user to be able to debug CAB programs that are executing in a SIM-ACE, the following setup must be performed.
- 311 -
Chapter 13 - CAB and CDB system administration
l The NT user account that the user is logged on the client must also exist on the SIM-ACE with the same password.
l The User account on the SIM-ACE must be a member of the "Administrators"group. l To prevent the user from logging on the SIM-ACE, the "Deny logon locally" Policy should be set
for the user. This is done by executing "Local Security Settings" under Administrative Tools and clicking on "User Rights Assignment." l On the client, the User account should be added to the "Debugger Users" group.
13.3
Remote debugging using Visual Studio
To debug CAB types, you need to attach Visual Studio to a remote SIM-ACE. This is only supported when attaching to a SIM-ACE that is running .Net 4.0 or higher. The version of the CAB type that is opened for debugging in Visual Studio must match with the version of the CAB type that was loaded to the ACE. For example, if you have a CAB type built prior to R410 loaded to an ACE, you cannot debug it using Visual Studio 2012. You have to rebuild the CAB type and then reload it to debug in this instance.
Remote debugging involves the following steps.
l Administrator Setup on the SIM-ACE -- A set up that the administrator must perform to allow users to attach to the remote debugger. See Administrator Setup on the SIM-ACE.
l Attach to the Remote Debugger -- How to attach the remote system with the debugger. See Attaching to the Remote Debugger.
13.4 Administrator Setup on the SIM-ACE
13.4.1
Setting up the Firewall and Remote Debugging Monitor
Opening a port on the firewall to allow programs access to your system makes your system a little less secure. The more programs that are allowed access and the more ports that you open in the firewall increases the opportunities for hackers or malicious software to make use of one of these openings. If you open a port, it stays open until you close it, whether it is being used or not. To decrease the security risk, you should only open a port or allow a program when you need to and close the port and remove the program from the allowed list as soon as your task is complete.
To set up the firewall and the Remote Debugging Monitor.
1. Through Windows Explorer, browse to the Program Files (x86) \Honeywell\Experion PKS\Engineering Tools\CAB\Remote Debugger directory.
2. Right-click the AceFirewall.bat file and select run as administrator. If you are using workgroups instead of domains, then you must modify the AceFirewall.bat file as follows: Modify the lines that has "profile=domain,private" to "profile=domain,private,public."
3. Enter the administrator user ID and password or click Continue if prompted. The firewall is now configured for access by Visual Studio 2017 (x86).
- 312 -
Chapter 13 - CAB and CDB system administration
13.4.2
Configuring the CAB Remote Debug Service
The CAB Remote Debug Service is a service that must be used to start the Microsoft Remote Debug process (msvsmon.exe). This is because changes in the Operating System make it impossible to attach the Microsoft Remote Debug Process to CAB inst ances if you execute only this process. The CAB Remote Debug Service will setup the Microsoft Remote Debug Process to allow only the users that you specify when you start this service.
To configure the CAB Remote Debug Service
1. To open the Services, choose Start > Programs > Administrator Tools > Services. 2. Select CAB Remote Debug Service in the Services pane. 3. Right-click the CAB Remote Debug Service and select Properties. The CAB Remote Debug
Service Properties dialog box appears. 4. Click the Log On tab. 5. Under the Log on As section, select the This Account option.. 6. Enter the user ID for manager and the password.
This user ID must be identical to the user ID that the cdasp service, the ACE.exe, and the cabclient.exe process are running. 7. Click Apply. 8. Click the General tab.
9. From the Startup type list, select Manual. Note: You must select Manual in the Startup list to enter values in the Start parameters field.
10. In the Start Parameters box, type the users that you want to allow to debug their CAB types. The syntax must be in the following format. -user <{domain\}user{;<user2>...}>{-timeout <value in seconds>} where -user is mandatory and the -timeout is optional Note: l -user specifies the user(s) that you want to allow to debug. l Use ";" to separate more than one user. l If the user is a domain user then you must specify the "domain\"prior to the user ID. If the user is not a domain user, you can omit the domain. l -timeout specifies the number of seconds of inactivity before the msvsmon.exe process terminates. If you do not specify this then the process runs until you stop the CAB Remote Debug Service.
You can always stop the CAB Remote Debug Service and then configure it for a different user. 11. Click Start to start the CAB Remote Debug Service.
13.4.3
Configuring the Local Security Policy
Local Security Policy identifies the users who can attach to processes with a debugger.
- 313 -
Chapter 13 - CAB and CDB system administration
To configure the Local Security Policy
1. To open the Local Security Policy, choose Start > Programs > Administrator Tools > Local Security Policy.
2. Expand the Local Policies folder in the left pane. 3. Click the User Rights Assignments folder in the left pane. 4. Double-click the Debug Programs in the right pane.
The Debug programs Properties dialog box appears. 5. Click Add User or Group and search for the user ID of the user on the client node who wants
to debug their CAB type on this ACE. 6. Click OK.
13.5
13.5.1
Administrator Setup on the Client (Station, Flex, and so on)
For Visual Studio to access the remote SIM-ACE, the firewall on the client must be configured to allow the Visual Studio process to access the network. This requires Administrator access. Most users who create/debug CAB types do not have Administrator access. If the firewall is not configured prior to a user trying to attach the debugger, a message appears indicating that the firewall must be configured.
Opening a port on the firewall to allow programs access to your system makes your system a little less secure. The more programs that are allowed access and the more ports that you open in the firewall increases the opportunities for hackers or malicious software to make use of one of these openings. If you open a port, it stays open until you close it, whether it is being used or not. To decrease the security risk, you should only open a port or allow a program when you need to and close the port and remove the program from the allowed list as soon as your task is complete.
Opening a port on the firewall to allow programs access to your system makes your system a little less secure. The more programs that are allowed access and the more ports that you open in the firewall increases the opportunities for hackers or malicious software to make use of one of these openings. If you open a port, it stays open until you close it, whether it is being used or not. To decrease the security risk, you should only open a port or allow a program when you need to and close the port and remove the program from the allowed list as soon as your task is complete.
To allow Visual Studio access to the network
1. Through Windows Explorer, browse to the Program Files (x86)\Honeywell\Experion PKS\Engineering Tools\CAB directory.
2. Right-click the VisualStudioFirewall.bat file and select run as administrator. If you are using workgroups instead of domains, then you must modify the VisualStudioFirewall.bat file as follows: Modify the lines that has "profile=domain,private" to "profile=domain,private,public."
3. Enter the administrator user ID and password or click Continue if prompted. The firewall should now be configured properly for access by Visual Studio 2017.
13.6
Resource management
Most resource management functions for CAB and CDB are the same as for Experion PKSsystems.
- 314 -
Chapter 13 - CAB and CDB system administration
Because of the nature of CAB, however, you might want to pay special attention to monitoring ACE processor and memory utilization. The Determine ACE shutdown horizon section contains information about how to estimate ACE memory usage, especially the memory consumed by "orphan" CAB types resulting from development and debug activities. For information on CDB memory utilization in C200, C200E, and C300, refer to Determine CDB memory utilization and C200, C200E, and C300 memory availability.
This section describes three CAB FDPs that may help you determine if a CAB instance is nearing its performance limits. This section also contains some tips for using standard Windows monitoring tools to observe ACE memory and processing statistics.
You can also get information from Experion PKSmonitoring functions. For example, if your CAB applications start to experience timeout errors, it could be an indication that you are starting to overload the CPU or a CAB algorithm is in an unintended loop.
13.6.1 Use performance monitoring FDPs
TIP
These FDPs are only supported on ACE. See Execution timing for information on determining CAB/C300 execution time.
CAB infrastructure includes three FDPs that can be used to view certain CAB performance-related measurements. For detailed descriptions of these parameters, see Detailed description of CAB specific FDPs.
The three parameters are:
l CABEXECTIMER--This parameter contains the time in microseconds required during the last execute cycle to run the user's CAB code. This timer starts when the user's code is invoked and ends after the user's code is finished and all associated CAB error handle and watchdog code is complete. By using this parameter, you can determine if the execution time of your CAB is approaching the 250 millisecond limit (since CABEXECTIMER values are in microseconds, 250 milliseconds would be the number 250000 in this parameter). If you determine that the CAB is at or near the execution time limit and it has a significant number of parameter references, you can use the CABPREFRDTIM and CABPREFWRTIM parameters to determine the contribution of parameter reference processing times to the overall execution time.
CABEXECTIMER for atomic blocks shows the amount of time in milliseconds that the Execute subroutine ran. It is updated after exiting the Execute() subroutine.
CABEXECTIMER for distributed blocks has a dual purpose. To help in determining how long a distributed program has been running, there will be a negative number in SECONDS showing how long the distributed CAB had been in the Execute() subroutine. Once the Execute() subroutine has exited, the CABEXECTIMER will be updated to a positive number to reflect the amount of time in milliseconds that the Execute() subroutine actually ran (as it does in an atomic block). This mechanism can be used to determine if a distributed CAB is "runaway." An engineer or operator can give the "QUIT" command on a runaway distributed CAB and it will terminate.
l CABPREFRDTIM--This parameter contains the total time in microseconds spent outside of CAB user code processing parameter reference read requests during the current execute cycle.
l CABPREFWRTIM--This parameter contains the total time in microseconds spent outside of CAB user code processing parameter reference write requests during the current execute cycle.
13.6.2
Use Task Manager
You can view memory and processor utilization graphically from the Performance tab of Windows
- 315 -
Chapter 13 - CAB and CDB system administration
Task Manager as shown in the following figure. Figure 13.1 Task Manager Performance Tab
13.6.3
Use Performance Monitor
Another useful tool is the Windows performance monitor (perfmon), which can be configured to monitor one or more system functions. The following procedure shows how to configure perfmon to monitor ACE processor and memory utilization.
- 316 -
To use Performance Monitor
Chapter 13 - CAB and CDB system administration
- 317 -
Chapter 13 - CAB and CDB system administration 1. Click Start > Run, type "perfmon" in the Open field, and then click OK. 2. Right-click in the display pane and then click Properties.
3. On the System Monitor Properties window that appears, click the Data tab and then Add.
- 318 -
Chapter 13 - CAB and CDB system administration 4. On the Add Counters window that appears, do the following steps:
l Open the Performance Object menu and then click Process. l Click Select counters from list and then click % Processor Time. l Click Select instances from list and then click ACE. l Click Add. l Do not close this window yet.
5. Next, do the following steps: l Click Select counters from list. l Click Private Bytes. l Click Add.
- 319 -
Chapter 13 - CAB and CDB system administration
6. Click OK to close the System Monitor Properties window. The ACE processor and memory utilization will be shown and monitored. In this manner, other items of interest can be added to the display for monitoring. Note:You may need to return to the property pages and adjust the Scale on the Data tab and the Maximum and Minimum values on the Graph tab in order to get a meaningful display.
- 320 -
13.7
Chapter 13 - CAB and CDB system administration
Custom Install Paths
The CAB software can be installed in different locations based on the input that was provided during Experion PKSinstallation. This feature is identified as "Custom Install Paths." When custom install paths are used for installing the CAB software, it affect the locations of the files specified to be in "C:\Program Files (x86)" and "C:\ProgramData" that are identified in this document. The correct location for the files that are identified as "C:\Program Files (x86)" will be the location specified in the Experion PKSSoftware field in the Installation Path(s) Selection dialog box during Experion PKSinstallation. The correct location for the files that are identified as "C:\ProgramData" will be the location specified in the Experion PKSRuntime Data field in the Installation Path(s) Selection dialog box during Experion PKSinstallation.
13.8
Backup and restore
Backup and restore functions for the ERDB and other Experion PKSsystem components are covered in the ExperionAdministration and Startup Guide.
CAB and CDB take advantage of the ACE checkpoint and restore functions. See the Application Control Environment User Guide for information. You can also refer to Recover a CAB with checkpoint restore and Recover a CDB with checkpoint restore.
13.8.1
ACE shutdown procedure for reclaiming CAB memory
ACE must be shut down and restarted to reclaim .NET memory used to hold obsolete CAB types ( see Determine ACE shutdown horizon or more information).
To shutdown the ACE to reclaim CAB memory
1. Create an up-to-date checkpoint for the ACE. 2. Use CB to open the ACE configuration form on the monitoring side. 3. Use the CEE Command to set the CEE State to IDLE. 4. Use the ACE Command to set the ACE State to SHUTDOWN. 5. Load the ACE. 6. Restore the checkpoint. 7. Use the CEE Command to set the CEE State to RUN.
- 321 -
CHAPTER
14
CAB AND CDB TROUBLESHOOTING AND
MAINTENANCE
14.1
CAB troubleshooting approach
Debugging takes place in the three stages of CAB development: l Development activity in the CB/Microsoft Visual Studio/PDE environment. l Off-process debugging using SIM-ACE (using SIM-ACE is optional but highly recommended).
SIM-C300 can also be used, but it does not support source level debugging. l On-process debugging.
These three stages are discussed at an overview level in Test and debug the CAB. The section you are reading now presents more detailed information.
14.1.1
Troubleshooting approaches and tools
This section covers troubleshooting approaches and tools that you can use in troubleshooting strategies that include CAB instances. These topics that are covered are:
l CAB instance states--This topic covers the states that a CAB can be in. You can monitor the CABSTATE parameter to determine if the CAB is operating normally or if an exception has occurred.
l CAB alarms--This topic covers the four alarms that are specific to CAB.
l Debug with SIM-ACE--This topic covers the process of debugging a CAB in an off-process environment using SIM-ACE and the Microsoft Visual Studio debugging tools.
l CAB fault handling--This topic contains detailed information about how faults are handled by CAB infrastructure. It includes a table of CAB faults and error codes. It also includes a summary of faults that can be prevented by site practices.
14.2
CAB instance states
The state of the CAB instance is shown in the CABSTATE FDP, which appears on the faceplate by default. This section defines the various states and the conditions that cause the CAB instance to transition from one state to another.
14.2.1
State diagram
All CAB types have the CABSTATE parameter. This parameter provides summary information on
- 322 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.2.2
the operating state of the CAB instance. CABSTATE is a view only parameter. In some cases the operator can affect the value of CABSTATE by writing to parameter CABCOMMAND.
Th e following figure that follows shows the behaviors of CABSTATE and CABCOMMAND. Transitions are indicated as either "auto" or "man." Automatic transitions are triggered automatically by system infrastructure or by actions taken by the CAB program. Manual transitions are caused by explicit user command.
The following conditions can also cause a currently executing distributed CAB to transition to Terminated:
l CEE transition to IDLE
l CM transition to InActive
Quit command behavior depends on CAB execution mode and whether it is asserted manually or programmatically as shown in the following table.
Command type
Table 14.1 Quit Command Behavior CABSTATE transition
Atomic execution mode
Distributed execution mode
Manual Quit
TERMINATED to DORMANT (Not allowed NORMAL to TERMINATED or
from NORMAL)
TERMINATED to DORMANT
Auto Quit NORMAL to DORMANT
NORMAL to DORMANT
State descriptions
Each value of CABSTATE is described in the following table.
CABSTATE
Table 14.2 CAB Instance States Description
Unloaded
CAB instance has been created and is waiting for completion of program load. Unloaded is a transient state. It only becomes a persistent state in the event of a communication or processing error that prevents program load from completing.
Normal
CAB instance is processing the Execute() subroutine whenever its parent CM is running. CAB program has been loaded. CAB instance is executing or not, depending on whether its parent CM has EXECSTATE = Active. Data access to FDPs and CDPs is fully operative.
Exception
CAB instance is processing the Execute() subroutine whenever its parent CM is running. An exception is being thrown within Execute(). An event has been reported. Program is running and access to FDPs and CDPs is fully operative. Execute() processing repeatedly results in "throw" of an unhandled exception. The exception could be caused by a program defect (for example, integer-divide-by-zero) or by intentional program action (for example, Abort() function being called without Catch). Exception reverts to Normal automatically on the first execution cycle that ceases to produce any unhandled exceptions. If there is a program defect, the state persists until the program is corrected and the CAB instance is reloaded. Depending on design of the CAB type, an event is issued on initial entry into state Exception. This event remains active until the state ends or until the parent CM is inactivated. Information on exception type is available from parameters EXCPTNTYPE and EXCPTNMSG (see Detailed description of CAB specific FDPs) whenever CABSTATE = Exception. A program can detect that it is operating in the Exception state by using the CABSTATE API (see CABSTATE).
Terminated CAB instance is not processing the Execute() subroutine. A low alarm is active. CAB
- 323 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.2.3
CABSTATE
Description
instance responds to read/write requests for FDPs and CDPs but is not processing the Execute() subroutine regardless of the state of its parent CM. One reason that the Terminated state is entered is as a result of uncontrolled program execution. Uncontrolled execution is defined as processing that lasts longer than the ACE base cycle of 500 milliseconds. For a list of the conditions that can cause a CAB to terminate, see CAB notifications. Terminated state does not return to Normal automatically. Instead, either the CAB instance must be reloaded or the operator must write Run or Quit to CABCOMMAND. Run causes the CAB instance to resume Execute() processing but in all likelihood execution will again go out of control leading to Terminated. An alarm is issued on initial entry into Terminated. The default level of this alarm is low, but both the level and severity are configurable (see CAB state Terminated). The alarm remains active until the state changes to Normal or Dormant, or until the parent CM is inactivated. A distributed mode CAB is terminated if the parent CM is inactivated or the CEE goes to IDLE while the CAB is executing. If you have a large number of parameters and are executing in the atomic mode, see CABs with large numbers of parameters.
Dormant
CAB instance is not processing the Execute() subroutine. No alarm is active. CAB instance responds to read/write requests for FDPs and CDPs but is not processing the Execute() subroutine regardless of the state of its parent CM. This state is supported to allow an operator to eliminate alarm noise while waiting for an engineer to correct program defects. If appropriate to an application, programs can be written to automatically turn themselves off by entering this state. System infrastructure never causes an automatic transition into the Dormant state. A program can place itself in the Dormant state by using the CABCOMMAND API (see CABCOMMAND). Be aware that CABSTATE Dormant is completely independent of the EXECSTATE of the parent CM of the CAB instance. Thus, if the CAB instance has CABSTATE = Normal and the parent CM goes through the transition EXECSTATE -> Inactive and then EXECSTATE -> Active, CABSTATE remains Normal. Although CAB does not execute when EXECSTATE = Inactive, CABSTATE never goes Dormant in response to a change in EXECSTATE.
Status of I/O performed by a block that terminates
The question arises as to what happens to parameter reference writes or parameter reference list writes that are performed during execution of a CAB, and that block subsequently terminates for reasons outlined above. The answer is that these writes will take place as soon as the write call is made. Similarly, if a value is assigned to a CDP prior to termination, that value is cached at the time of the assignment and will be provided to recipient blocks when they execute.
Users who are concerned about validity of data written by a CAB that could potentially be terminated could arrange the code to do the PRef writes and CDP assignments at the very end of the execute subroutine so that they would be unlikely to go out while the block was unstable or unpredictable. CABs that are recipients of data could look at the CABSTATE parameter of the originator to be sure it NORMAL before using the I/O. These measures would only be appropriate if you are coding to maximize data integrity in the case of a CAB that terminates.
14.2.4
Transition descriptions
Each possible transition in CABSTATE is described in the following table.
Transition
Table 14.3 Transitions in CAB State Description
Load
Occurs automatically after completing load of the CAB instance.
- 324 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.3
Transition Completion
Description
Unhandled Exception
Occurs automatically if a program defect causes an exception to be thrown (for example, divide-by-zero error) or if the program design has intentionally caused an exception to be thrown without being caught. Use of the Abort() API without a corresponding Catch causes this transition.
Exception Clear
Occurs automatically on the first processing cycle where conditions leading to throw of the exception are no longer present.
Timeout
Occurs automatically if program execution lasts longer than \ the ACE base cycle of 500 ms. CAB/C300 has a different execution time limit--see CAB/C300 execution time limit.
CABCOMMAND Occurs when a human being explicitly commands the CAB instance to stop
-> Quit
executing (Quit is only allowed for distributed execution CABs). This might be
done to eliminate alarm noise if the instance has repeatedly gone to
Terminated, indicating that it is defective and cannot execute. It might also be
commanded when CABSTATE was Normal or Exception, though this would
happen rarely if ever. Quit could also occur automatically if the CAB program
was designed to cease execution in response to specific detected conditions.
Quit can also be used to terminate execution of a CAB that is in the distributed
execution mode and has entered an infinite loop.
CABCOMMAND Occurs when a human being explicitly commands the CAB instance to resume
-> Run
execution. This would generally be used when CABSTATE is Dormant. It could
be used when CABSTATE is Terminated. But in that case the instance would
most likely go right back to state Terminated.
CAB alarms
CAB programs can work in conjunction with other blocks to generate process alarms. For example, a CAB instance can deliver a computed PV value to a Data Acquisition block to generate one or more PV alarms. Similarly, it can set the PV value on a Flag block to generate a discrete alarm.
Beyond this, there are four notifications (all are alarms) built into the CAB infrastructure: CAB state Terminated, CAB state Exception, Read error, and Write error. Two of the notifications, although associated with values of CABSTATE, are not reported as state change notifications. The other two notifications are associated with CAB parameter access. They are optionally enabled at the time the CAB type is designed.
Full notification recovery is supported for each of these notifications without burden on the CAB programmer. Support is built into the CAB infrastructure. Also, each notification is implemented so as not to overburden the notification-reporting channel. After an alarm goes active, it is never rereported until it has returned to normal.
14.3.1
CAB state Terminated
Typically, this alarm is reported when the CAB instance execution is terminated because of overly long execution, or because the parent CM of a distributed execution CAB goes to InActive or the CEE goes to IDLE. For a list of the conditions that can cause a CAB to terminate, see CAB notifications. The alarm's priority and severity are instance-configurable using the TRMNTALM.PR and TRMNTALM.SV parameters (see Detailed description of CAB specific FDPs). These parameters default to Low priority and 0 severity. The alarm remains active until the operator changes CABSTATE to Normal or to Dormant. Information reported with the alarm includes parent CM tag name, CAB instance descriptor, the condition (shown as "TERMINATED"), and whether the report indicates alarm or return to normal.
- 325 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.3.2
CAB state Exception
This alarm (condition shown as "EXCEPTION") is reported whenever a CAB instance incurs an exception. It remains active until the first subsequent execution that incurs no exception. CAB programs can be designed to induce the Exception alarm under special conditions. This is described in 'Subroutine Abort()." The alarm priority and severity are configurable using the EXCPTALM.PR and EXCPTALM.SV parameters (see Detailed description of CAB specific FDPs). This alarm's priority and severity are instance-configurable and default to JOURNAL priority and 0 severity. Information reported with the alarm includes parent CM tag name, CAB instance descriptor, the condition (the condition value distinguishes the three from one another), and whether the report indicates alarm or return to normal.
14.3.3
Read error
This alarm (condition shown as "READERR") is optionally enabled at CAB type design time by setting the default value of parameter READERROPT to Event. The alarm is reported whenever parameter READSTATUS <> OK. The alarm priority and severity are configurable using the RDERRALM.PR and RDERRALM.SV parameters (see Detailed description of CAB specific FDPs "). This alarm's priority and severity are instance-configurable and default to JOURNAL priority and 0 severity. Information reported with the alarm includes parent CM tag name, CAB instance descriptor, the condition (the condition value distinguishes the three from one another) and whether the report indicates alarm or return to normal.
14.3.4
Write error
This alarm (condition shown as "WRITEERR") is optionally enabled at CAB type design time by setting the default value of parameter WRITEERROPT to Event. The alarm is reported whenever parameter WRITESTATUS <> OK. The alarm priority and severity are configurable using the WRTERRALM.PR and WRTERRALM.SV parameters (see Detailed description of CAB specific FDPs "). This alarm's priority and severity are instance-configurable and default to JOURNAL priority and 0 severity. Information reported with the alarm includes parent CM tag name, CAB instance descriptor, the condition (the condition value distinguishes the three from one another) and whether the report indicates alarm or return to normal.
14.3.5
FDPs that capture exception information
To help debug code that is causing exceptions, CAB infrastructure has these four FDPs:
l EXCPTNLINENM--Contains the source file name and source line number of the function executing on the last exception incurred by CAB program. This parameter is not supported in CAB/C300.
l EXCPTNMODULE--Contains the name of the function executing on the last exception incurred by CAB program. This parameter is not supported in CAB/C300.
l EXCPTNMSG--Publishes descriptive information on the last exception incurred by CAB program.
l EXCPTNTYPE--When CABSTATE=Exception, EXCPTNTYPE contains a string indicating the type of exception that has been thrown. Refer to the detailed description for the format and examples.
Note;These FDPs only show the exact information about the exception when the program was built to the Debug target. For detailed descriptions of these FDPs, see Detailed description of CAB specific FDPs.
- 326 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.4
Debug with SIM-ACE
Simulation ACE (SIM-ACE) is the ACE application in simulation mode (it is not a separate application). It allows you to run a debug version of a CAB application in a defined strategy in an off-process environment.
14.4.1
The Microsoft Visual Studio debugger
The Microsoft Visual Studio debugger is a powerful tool that allows you to observe the run-time behavior of your program and determine the location of coding errors. Historically, many programmers debugged their software by incorporating output functions such as print or MsgBox at various points in the code to provide visibility into the code operation. CL programmers have used Send statements or writes to CDS parameters for the same purpose. While this can be an effective technique, it is cumbersome to add the additional code and then to remove it when debug is complete. And, there is always the risk that the added code will affect the operation of the program.
Using the Microsoft Visual Studio debugger, you can monitor the variables in your program without adding special debugging code. You can insert breakpoints to freeze code execution at points of interest. When the program is halted in the break mode, you can view local variables and other relevant data using Microsoft Visual Studio facilities such as Watch Window, QuickWatch Dialog Box, and Memory Window. You can even edit your code and change variable values when halted at a breakpoint.
14.4.2
Scope
This guide contains only an outline of how to use SIM-ACE. For detailed information, refer to the Simulation ACE User Guide. Similarly, this guide does not cover the details of using Microsoft Visual Studio, including using the debugger capabilities. Refer to the Microsoft Help for these details. For example, in Microsoft Visual Studio, choose Help > Contents. Then, choose Visual Basic from the Filtered by list. Navigate as follows: Development Tools and Languages > Visual Studio > Application Development in Visual Studio > Building Debugging and Testing > Debugging in Visual Studio as shown in the figure that follows.
- 327 -
Chapter 14 - CAB and CDB troubleshooting and maintenance Figure 14.1 Microsoft Visual Studio Help Contents
14.4.3
This would be a good place to start when looking for general information about using the debugger.
Basic characteristics of SIM-ACE
l A dual processor node will support up to four SIM-ACEs. A single processor ACE node will support up to two SIM-ACEs.
l The SIMENABMLE parameter in the CEEACE FB determines whether the ACE is in the ACE or SIM-ACE mode (TRUE = SIM-ACE mode).
- 328 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.4.4
l Only one Microsoft Visual Studio debug session at a time can be attached to a SIM-ACE for CAB debugging. Refer to Step 7 in the procedure in Attaching to the Remote Debugger for information about detecting that another user has a debugger attached to the SIM-ACE and determining who that user is.
Attach the debugger ONLY to ace.exe or to cabclient.exe. Do not attach the debugger to any other process on the same node or on a remote node. If you attach to another process, the process might crash when you terminate the debugging session resulting in loss of view or other undesirable consequences.
Attaching to the Remote Debugger
After the administrator has configured the ACE to allow the Remote Debugging Monitor to execute and you have the required permissions, you can now attach to the Remote Debugger from your client.
TIP
Note that the procedure to attach the remote system to the debugger is different from the one performed from Visual Studio 2003.
To attach to the remote debugger:
1. On the client, open the CAB type that you want to debug and that has been loaded to the ACE for edit or view only.
2. Click Debug > Attach to Process.... 3. If the program that you want to debug is running on another computer, in the Qualifier list,
select or specify the remote computer. For more information, refer to the Visual Studio Remote Debugging Setup documentation. 4. If the process is running under a different user account, select the Show processes from all users check box.
5. If the Attach to field is not set to Managed code, click Select... - 329 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.4.5
6. Select Debug these code types and then choose the Managed code option leaving all the others unchecked and click OK.
7. From the list of Available Processes, select the appropriate process: ace.exe for an atomic execution CAB, or cabclient.exe for a distributed execution CAB.
8. Click Attach.
Tips for using Microsoft Visual Studio with SIM-ACE
l You can step through your code using step buttons with the Debug toolbar displayed. l You can view or change values of CDPs defined for the CAB within the Auto/Locals tabs.
l You can also view or change values in the Command Window.
14.5
TIP When debugging a CAB that has terminated due to an infinite loop, you must single step through the code or run the code with breakpoints set inside the infinite loop. If the infinite loop is allowed to execute unbounded, the debugger will freeze due to the infinite loop. When it is time to stop debugging the CAB, the execution pointer (yellow pointer cursor) in the debugger must be moved (dragged) beyond the infinite loop code prior to un-attaching the debugger. If the debugger is unattached with the execution pointer in the infinite loop code, the CAB will continue to loop and may freeze the SIM-ACE process.
If you are debugging a CAB and you have stopped the debug and closed Visual Studio, DO NOT select to Save Changes. Rather, select Discard.
CAB fault handling
The CAB system incorporates built-in fault handling to insure that you can produce safe behavior of control applications at run time. Some of the key principles are:
- 330 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
l A run-time fault detected by a CAB instance impacts only that instance and does not impact any other block instance.
l External process and system disruptions are normal. Conditions such as process variable over range, external node failure, or inter-node communication failure do not cause CABs to stop executing. Instead, they optionally report a notification, continue to execute, and clear the notification after the disruption goes away.
There are a wide variety of faults that can affect CAB programs. Overall system detection and response is implemented within multiple subsystems. Some faults are detected and handled at execution time. Others are detected before execution occurs and are prevented.
14.5.1
Function limiter and supported namespaces
The function limiter in CAB will catch code that is not allowed and will display an error message in the output window within the CAB Developer environment (Microsoft Visual Studio IDE). For example, the Function Limiter will catch Declare statements, which are not allowed in CAB. The namespaces and classes allowed for CAB/ACE are shown in Supported namespaces and classes and are supported and enforced within the CAB Developer environment. Function limiter catches code that is not allowed; that is, use of classes not listed in the table. Supported namespaces and classes also contains the supported subset of namespaces and classes allowed for CAB/C300.
14.5.2
Supported namespaces and classes
Table 14.4 NET constructs allowed for CAB/ACE applications
Functional area
.NET Namespace
Class/Structure
Method
Visual Basic .NET run-time library
Microsoft.VisualBasic
Collection, Constants, Any ControlChars, Conversion, DateAndTime, ErrObject, Financial, Globals, Information, Strings, VbMath
.NET run-time
Any
Any
Compiler
Microsoft.VisualBasic.CompilerServ
Services. The ices System.Run-
Visual Basic time.CompilerServices.RuntimeHel
compiler needs per
this.
Fundamental System .NET Classes and Structures
Any Exception class,
Any
Activator, Array,
BitConverter, Buffer,
CharEnumerator,
Convert, DBNull, Enum,
Environment4,
EventArgs, Math, Object,
OperatingSystem,
Random,
ResolveEventArgs,
String, TimeZone, Type,
ValueType, Version
ArgIterator, Boolean,
- 331 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Functional area
.NET Namespace
Class/Structure
Method
Various Collections Classes
Various Specialized Collections Classes
Type converters
Performance Data
System.Collections System.Collections.Specialized
System.ComponentModel System.Diagnostics
Debug help System.Diagnostics
Culture-related System.Globalization information
Text and String System.Text manipulate classes
.NET regular expression engine
File I/O3
System.Text.RegularExpressions System.IO
XML and XML
Schema support3
System.XML, System.XML.Schema, System.XML.Serialization, System.XML.XPath, System.XML.Xsl
OPC History2, 3 Opc.Hda
Byte, Char, DateTime, Decimal, Double, Guid, Int16, Int32, Int64, SByte, Single, TimeSpan, UInt16, UInt32, UInt64 ICloneable, IComparable, IConvertible, ICustomFormatter, IDisposable, IFormatProvider, IFormattable
Any
Any
Any
Any
Any Type Converter
Any
class
Any Counter class, Any Any InstanceData class, Any PerformanceCounter class CounterSample
Debug
Close, Flush, Indent, Unident, Any Write methods
Any
Any
Any
Any
Any
Any1 Any
Any
Any1 Any
Aggregate,
Any
AggregateCollection,
AggregateID,
AnnotationValue,
- 332 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Functional area
.NET Namespace
OPC History2, 3 Opc.Hda (continued)
OPC (needed Opc to support OPC History)3
Class/Structure
Method
AnnotationValueCollecti on, Attribute, AttributeCollection, AttributeID, AttributeValue, AttributeValueCollection, BrowseElement, BrowseFilter, BrowseFilterCollection, BrowsePosition, EditType, IActualTime, IBrowser, IServer, Item, ItemAttributeCollection, ItemCollection, ItemResult, ItemTimeCollection, ItemValue, ItemValueCollection, ModifiedValue, ModifiedValueCollection, Operator , Quality, RelativeTime, Result, ResultCollection, ServerState, ServerStatus, Time, TimeOffset, TimeOffsetCollection
Server
Clone, Connect, CreateBrowser, CreateItems, Disconnect, GetAggregates, GetAttributes, GetObjectData, GetStatus, ReadAnnotatio ns, ReadAttributes, ReadAtTime, ReadModified, ReadProcessed, ReadRaw, ReleaseItems, Server, ValidateItems, Aggregates, Attributes, Items
All *Exception classes, Any ConnectData, Factory, IdentifiedResult, IdentifiedResultCollectio n, IDiscovery, IFactory, IResult, ItemIdentifier, ItemIdentifierCollection, Namespace, ResultID
- 333 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Functional area
.NET Namespace
Class/Structure
Method
and all ResultID codes, Server, Specification, Type, URL, UrlScheme
OPC Data
OPC.Da
Access (needed
to support OPC History)3
Quality
Any
OPC Com wrapper (needed to support OPC History)3
OpcCom
Factory,
Any
ServerEnumerator
Needed to
System
Uri, IntPtr
Any
support a few different File System.Net
Any
Any
I/O, XML, and System.Run-time.Serialization
Any
Any
OPC History
classes/metho System.Security
Any
Any
ds3
System.Security.Permissions
Any
Any
System.Security.Policy
Any
Any
CAB Wait
---
Subroutine3
---
Wait
CAB History Honeywell.CAB.OPC
History
Any
Subroutines3
1. Asynchronous File I/O calls will not be allowed. This essentially means that the BeginRead, EndRead, BeginWrite, and EndWrite methods associated with the FileStream and Stream classes will not be allowed. Also, the method Directory.SetCurrentDirectory will not be allowed.
2. In general for OPC History access, the allowed constructs include everything except asynchronous calls, callbacks, playbacks, and any methods that change or update data on the server.
3. Constructs identified with this superscript can only be used by CABs executing in the distributed mode. All others can be used by either distributed or atomic execution CABs.
4. Setting the property Environment.CurrentDirectory will not be allowed. Additional comments: l When just the namespace is specified, the user can use any construct (such as class or structure) in this namespace.
l When items are listed in the Class/Structure column, just those classes and structures specified in that namespace can be used by the programmer. For example, the class System.Int32 can be used, but System.UIntPtr cannot.
l When items are listed in the Method column, just those methods specified for that class in that namespace can be used. For example, the method System.Diagnostics.Debug.WriteLine can be used, but System.Diagnostics.Debug.Assert cannot.
- 334 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.5.3
Functional area
Table 14.5 .NET constructs allowed for CAB/C300 applications
.NET Namespace
Class/Structure
.NET runtime Compiler Services.
System.Run-
Any
time.CompilerServices.RuntimeHelper
Method Any
Fundamental System .NET Classes and Structures
Activator, Array, BitConverter, Any Buffer, CharEnumerator, Convert, DBNull, Environment1, EventArgs, Math, Object, OperatingSystem, Random, ResolveEventArgs, String, TimeZone, Type, ValueType, Version ArgIterator, Boolean, Char, DateTime, Double, Int32, Int64, TimeSpan, UInt32, UInt64
Various
System.Collections
Any
Any
Collections
Classes
Various
System.Collections.Specialized
Any
Any
Specialized
Collections
Classes
Type converters
System.ComponentModel
Any Type Converter class
Any
Culture-
System.Globalization
Any
Any
related
information
Text and
System.Text
Any
Any
String
manipulate
classes
.NET regular System.Text.RegularExpressions
Any
Any
expression
engine
1. Setting the property Environment.CurrentDirectory will not be allowed.
Summary of fault handling
The following table summarizes information about CAB faults. The information is organized around two fundamental items--Fault Cause and Fault Detection and Response. The table covers faults specific to CAB. There are various types of instance configuration faults that CABs have in common with native blocks. These are discussed elsewhere within Experion PKSdocumentation.
- 335 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Fault cause
Attempt to use programming construct inappropriate to control mission.
Table 14.6 Summary of CAB Fault Handling
Fault detection
and response
Examples
Comments
Detection at program build time leading to CAB "compiler" error.
Use of programming statements that attempt to access the system registry. Invocation of graphical user interface services. Attempted file access under atomic execution. Attempted use of thread scheduling services. Attempted use of OS timer utilities for CAB program execution scheduling.
After a CAB is built in Visual Studio with no error, the CAB will scan the user's program and verify that its constructs are appropriate for process control. Inappropriate constructs are shown to the user as CAB "compiler" errors and must be removed before the user's program can be built successfully. But this feature may not flag every inappropriate construct. Thus, site practices must also be in place to prevent this fault category. Consequences of not preventing a specific construct varies depending on the particular fault. In some cases, they may be as bad as a crash of the entire CEE. In other cases, they may be detected and neutralized by the long execution time-out built into the CAB infrastructure.
Attempt to load program in presence of communication or resource error.
Detection at program load time leading to reject.
Communication error occurs during load causing timeout or packet corruption. Resources reserved for CAB programs are exceeded during the course of program load.
The fault is detected at the time the CAB type is loaded to the CEE. The program load is rejected. Note that program load happens implicitly when user commands instance load if the program is not already present within the CEE.
Attempt to load block instance in presence of configuration or resource error.
Detection at instance load time leading to reject.
Loading a block instance with a configuration parameter assigned to a value outside the allowed range defined for the block type. Loading a block when a memory resource limit has been exceeded.
The fault is detected at the time the CAB instance is loaded to the CEE. The instance load is rejected. Users will be forced to correct the error and reload the instance.
Attempt to execute in presence of data access error.
Detection at run time signaled by status information and optional
Parameter store check fails at target block. Indexed parameter on external block is
Data access errors cause program readable status to be set without causing program execution to cease. The degree to which these errors are detected and managed within the CAB program is a decision made by the program designer. Data access errors also cause status feedback to the operator
- 336 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.5.4
Fault cause
Fault detection
and response
event.
Examples
Comments
accessed with out- and optionally enabled events. See of-range index. Parameter access faults after this table. Parameter is accessed on external block that no longer exists. Target block is not loaded. Host node of target block has failed. Communication link to target node has failed.
Attempt to execute in presence of short duration algorithmic design defect.
Detection at Flawed algorithm run-time design causes signaled by integer-divide-byexception. zero. See Divide-
by-zero handling after this table. Algorithm design causes out-ofrange index to be used on array local to CAB.
This type of algorithmic defect is detected by language run-time support. It causes an exception to be thrown which halts the current cycle of program execution. Program execution is attempted again on the subsequent cycle. See Exception handling after this table.
Attempt to execute in presence of long duration algorithmic design defect.
Detection at Algorithm design run-time causes loop leading to execution which termination. prolongs block
execution for \ base cycle or longer. Function call recursion prolongs block execution for \ base cycle or longer. See Unbounded recursion after this table.
This error type is detected by a CEE monitoring service. It causes program execution to be terminated. Execution does not resume until the CAB is taken out of the terminated state by explicit human intervention. Both engineer and operator access rights are sufficient to restart the block. See Overlong execution and Loops In 'Catch' Or 'Finally' clauses after this table. For a list of the conditions that can cause a CAB to terminate, see CAB notifications.
Parameter access faults
CAB infrastructure supports detection of parameter access faults in two ways: information provided to the CAB program, and information provided to the operator.
For the program, the APIs "ReadStatus" and "WriteStatus" are provided for each parameter reference. This information can be used or ignored by the CAB programmer. CAB infrastructure itself never aborts program execution or throws an exception in response to a parameter access error. If this behavior is desired, it must be deliberately designed into the program. Further information on the status API values can be found in the section Enumeration CABAccStatusEnum. Note that Warning statuses (for example, Clamped Value Warning) return a status of OK.
- 337 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
For the operator, two FDPs are supported: READSTATUS and WRITESTATUS. READSTATUS normally shows OK. If a read error occurred on the last execution, READSTATUS shows the first non-OK status encountered during execution. WRITESTATUS behaves analogously for parameter writes. This behavior also applies to PRefList reads and writes. Two other parameters, READERROPT and WRITERROPT, allow CAB types to report events in response to read or write errors. For further information on READSTATUS, WRITESTATUS, READERROPT and WRITEERROPT, see the section Detailed description of CAB specific FDPs.
14.5.5
Divide-by-zero handling
System treatment of divide-by-zero is different depending on whether the numbers are integer or floating point. The former causes an exception to be thrown. The latter continues processing as normal. The reason for the difference is that, unlike integers, IEEE 754 floating-point numbers have a representation for infinity. This allows for consistent handling of floating-point divide-byzero without the use of an exception.
14.5.6
Unbounded recursion
Unbounded recursion will result in the block being terminated. Termination will be caused by either a StackOverflow or by expiration of \ base cycle duration.
14.5.7
Exception handling
Some faults are detected by language run-time services, causing an exception to be thrown. Response to the exception varies depending on how the CAB program has been written.
If an exception handler has been provided within user-written code, it catches the exception and continues processing according to its own design. It may cause the program to run to completion or it may break program execution early. If program execution breaks for the current cycle, it starts fresh at the next execution cycle.
If the program does not contain a user-written handler to catch the exception, then exception handling is provided by system code. Default system behavior is to cause program execution to break and then start fresh at the next execution cycle. After program execution has been broken, parameter CABSTATE is set to Exception. This allows the abnormal state to be read by the operator in cases where an exception fires repeatedly. In addition, system implementation causes an event to be reported under the name of the CAB instance and its CM parent. For further information on CABSTATE and the exception event see CAB instance states.
14.5.8
Overlong execution
ACE-CEE has a built-in monitoring service that allows CAB programs to use, at most, 250 milliseconds, which is \ of the base cycle time, if they are executing in the atomic execution mode (distributed execution mode CABs do not have this restriction). C300-CEE has a different time limit for executing CABs. See CAB/C300 execution time limit. If execution of an individual CAB instance exceeds this duration, execution is stopped, the CABSTATE is set to Terminated, and an alarm is reported. The block instance never runs again until it is restarted by a human being. After it is restarted, the alarm and state parameter return to normal. For further information on CABSTATE and the long execution alarm, see CAB instance states.
Loop overrun detection is done on the basis of CAB instances rather than on CAB types. Thus, if a given instance uses a flawed program and has data conditions that allow the flaw to be triggered, it is taken out of service. If another instance uses the same program but does not have data conditions that trigger the defect, it is not taken out of service.
- 338 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
In some cases, an individual block using the fully allowed execution time will be enough to cause a control processing cycle overrun. Forcing the block into a termination state prevents this from happening repeatedly.
14.5.9
Loops In 'Catch' Or 'Finally' clauses
ACE-CEE uses .NET thread abort services to terminate a block that has executed too long. Characteristics of these services make it impossible for CEE to terminate a block under certain unusual circumstances. In particular, a block cannot be terminated if it is looping within the Catch or Finally clauses of a "Try" statement. It is recommended that site practices forbid the use of loops within Catch or Finally clauses. The need for such loops does not arise within CAB control programs.
14.5.10 Site responsibilities in CAB fault handling
The following table shows specific fault types that must be prevented by site practices.
Fault cause
Table 14.7 Summary of Site Responsibilities for Fault Handling
Specific case
Additional information
Attempt to use programming construct inappropriate to control mission.
Use of any programming construct that accesses disk. Use of any programming construct that uses command line monitor input or output. Use of any programming construct that uses Graphical User Interface. A list of specific .NET constructs that should not be used in CEE control applications is given in CAB error reporting.
See the first row of the table in Summary of fault handling.
Attempt to Use of loops in "Catch" or execute in "Finally" clauses. presence of long duration algorithmic design defect.
See the last row of the table in Summary of fault handling.
Attempt to allocate large amounts of data.
Static allocation of very large data structure such as an array. Dynamic data structure growth such as calls to `new' in a loop.
The majority of excessive memory allocations would cause an OutOfMemoryException to be thrown if sufficient memory resources are not available. The OutOfMemoryException error is detected by a CEE monitoring service. It causes program execution to be terminated. Execution does not resume until the CAB is taken out of the terminated state by explicit human intervention. Both engineer and operator access rights are sufficient to restart the block.
14.5.11
CAB error reporting
System infrastructure reports CAB related errors in several different ways. Error reporting can vary depending on where the error is detected within the CAB life cycle.
- 339 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
The following table shows how users learn of errors depending on the phase of the CAB life cycle. See CAB error messages and codes for exact error messages and possible workarounds.
Phase of detection
Table 14.8 Techniques for Reporting CAB Errors Where error Information is reported
Type creation time
Errors such as source code syntax errors are reported directly in Microsoft Visual Studio 2017. Errors related to commissioning the CAB type within ERDB are reported by CB as they occur. Errors related to commissioning the CAB type within ERDB are also recorded in the Experion PKSerror log files. These files have the name "ErrLog_n.txt" where n is an integer. They are found in this folder: C:\ProgramData\Honeywell\Experion PKS.
Instance conversion time
Errors related to the process of converting CAB instances to a different type are reported by CB as they occur. These errors are also recorded in the Experion PKSerror log files.
Instance
Errors related to the process of configuring CAB instances are reported by CB as
configuration they occur. These errors are also recorded in the Experion PKSerror log files.
time
Instance assignment time
Errors related to the process of assigning the CM parent of CAB instances are reported by CB within error dialogs as they occur. These errors are also recorded in the Experion PKSerror log files.
Instance load Errors related to the load of CAB instances and to the load of the CAB programs
Time
associated with the instances are reported by CB as they occur. These errors are
also recorded in the Experion PKSerror log files.
Program execution time
Program defects that result in throw of an exception that is not caught by user written code are reported by issuing an event and by setting parameters CABSTATE, EXCPTNTYPE and EXCPTGNMSG. Program defects that result in excessive execution time are reported by issuing an alarm and by setting parameter CABSTATE. Parameter access errors are reported in parameters READSTATUS and WRITESTATUS and are also reported as events depending on the design of the CAB type.
Operations Time
Errors that result from attempts to store inappropriate values to CAB parameters are reported by Experion PKSStation with a status indication at the time they occur.
Export/Import Time
Errors detected at import are reported within the error log files. Informational messages associated with import that are not errors are reported within a supplementary log file. This file is called "IXP_Log.txt" and are found in this folder :C:\ProgramData\Honeywell\Experion PKS.
The following table provides examples of CAB error conditions that are detected by the system. It also shows how the user is informed of the error and recommends a user response.
Phase of detection
Table 14.9 CAB Error Type Examples and Recommended Actions
Type of error
System response
Recommended user action
Type creation time
User attempts to open a CAB type for edit while it is under edit by another engineer.
CB presents error message indicating that operation is disallowed and why.
If it is only desired to view the type, open with the View command. If it is desired to edit the type read EDITLOCK to identify the engineer who is editing the type. Contact the
- 340 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Phase of detection
Type of error
System response
Recommended user action
engineer. EDITLOCK may be viewed by opening the CAB form from the library tree (see Note 1).
Type creation time
Program source code has compile errors.
Microsoft Visual Studio reports build errors (see Note 2).
If meaning of error is unclear, see Microsoft Visual Studio help documentation. Correct error, rebuild.
Type creation time
User attempts save of preexisting type to ERDB after deleting or modifying a parameter definition.
Microsoft Visual Studio presents error message with options to Save As or Cancel.
Use Save As to save type with a different type name and/or library name. Later, convert existing instances to new type (see Note 3).
Instance conversion time
User attempts conversion of existing instance to a modified type after parameter deletion. A deleted parameter has been referenced in instance connections.
CB presents error message.
Cancel the convert operation. Remove connection that references the parameter that has been deleted. Re-attempt conversion (Note 3).
Instance conversion time
User attempts conversion of existing instance with parameter references to a different instance with parameter references pointing to data that is a different data type.
The value (name/address of referenced parameter) of the PRef is retained even if the user has changed the data type of the PRef at the CAB type that is the destination of the convert operation. On a read of the converted PRef type, the FailSafe value will appear. On a write of the converted PRef type, the FailSafe value will appear in the block.param that the PRef is pointing to.
On the project side, modify the block.param values that the PRef instance is pointing to.
Instance configuration time
User attempts to point a parameter reference to a parameter of unsupported data type such as STRUCT.
CB presents error message indicating that operation is disallowed and why.
Change parameter reference to point to a parameter of supported data type (see Note 4).
Instance
User attempts CB presents error message
Assign CM to an ACE
- 341 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Phase of detection
assignment time
Type of error
System response
to assign a CM containing a CAB instance to a platform that does not support CAB.
indicating that operation is disallowed and why.
Recommended user action platform.
Instance load time
User attempts to load an instance whose CAB type has not been successfully built.
CB presents error message indicating that operation is disallowed and why.
User can see that value of parameter INCOMPLETE is On by opening the CAB form from the library tree. User must rebuild CAB type (see Note 1).
Instance load time
User attempts to load an instance to an ACE for which the CAB runtime license has not been purchased.
CEE returns parameter access error on load. CABSTATE shows value Unloaded.
Load instance to ACE platform which has CAB run-time.
Instance load time
Communication CEE returns parameter access failure occurs error on load. CABSTATE shows during load of value Unloaded. CAB program.
Repeat instance load.
Instance load time
User assigns configuration CDP with value outside the defined range.
CEE returns parameter access error on load.
Change CDP configuration value in instance or modify CAB type to support wider configuration range.
Instance load time
User attempts to load a CAB that is referencing a PMIO/Series C I/O module.
CEE returns a 2299 error "initiator Use a different I/O
cannot establish connection to interface, such as a 1756
the responder."
channel.
Program execution time
Parameter reference points to local block that has not been loaded, or to a block that has been moved to a different controller.
CEE returns data access error (CABAccStatusEnum.ConfigMis) to CAB instance. CAB program responds as designed. Error information is posted in parameter READSTATUS or parameter WRITESTATUS. Depending on design of the CAB type an event may be reported (see Note 5).
Load the missing block to complete configuration of the overall control strategy. In the case of a block that has been moved, reload the requesting CAB so that it acquires the handle of the moved target.
Program execution time
Parameter reference points to remote block in node that has failed.
CEE returns data access error (CABAccStatusEnum.CommFail) to CAB instance. CAB program responds as designed. Error information is posted in parameter READSTATUS or
Fix the node that has failed.
- 342 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Phase of detection
Program execution time
Program execution time
Program execution time
Program execution time
Type of error
System response
Recommended user action
parameter WRITESTATUS. Depending on design of the CAB type an event may be reported (see Note 5).
Program has been designed to invoke the Abort() subroutine in response to a run-time detected error condition.
CEE puts CAB instance into state Exception. Parameter CABSTATE has value Exception. Parameter EXCPTNTYPE has the value "Honeywell.CAB.AbortException." Exception event is active (see Note 6).
Operator responds as directed by defined operational practices for the site.
Program has defect that causes exception to be thrown.
CEE puts CAB instance into state Exception. Parameter CABSTATE has value Exception. Exception event is active. Parameter EXCPTNTYPE contains a string that indicates the type of exception. For example, for an integer-divide-by-zero error, EXCPTNTYPE would contain "System.OverflowException" (see Note 6).
Operator may change CABSTATE to Dormant to cause the event to go inactive. CE should correct program defect and reload instance.
Program has defect that causes overly long execution.
CEE puts CAB instance into state Terminated. Parameter CABSTATE has value Terminated. Terminated alarm is active. Parameter EXCPTNTYPE has the value "System.Threading.ThreadAbort Exception." Parameter EXCPTNMSG has the value "Thread was being aborted."
CE should correct program timing defect and reload instance. To exit the Terminate state, set the CABCOMMAND to RUN. You can run the CAB on SIM-ACE with a debug build and use theEXCPTNMODULE (Exception Module) and EXCPTNLINENUM (Exception Line Number) parameters to determine the location of the code that caused the exception.
Program runs out of ACE memory.
CEE puts CAB instance into state Check for algorithms that
Terminated. Parameter
are allocating excessive
CABSTATE has value Terminated. amounts of memory. Use
Terminated alarm is active.
Windows tools to monitor
Parameter EXCPTNTYPE has the memory usage and look for
value
spikes (see Configuring the
"System.OutOfMemoryException." Local Security Policy.) CE
Parameter EXCPTNMSG has
should correct the memory
value "Exception of type
allocation defect and
System.OutOfMemoryException reload instance. To exit the
was thrown."
Terminate state, set the
CABCOMMAND to RUN.
You can run the CAB on
SIM-ACE with a debug
build and use the
- 343 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Phase of detection
Type of error
System response
Recommended user action
EXCPTNMODULE (Exception Module) and EXCPTNLINENUM (Exception Line Number) parameters to determine the location of the code that caused the exception.
Operations time
Operator stores inappropriate value to FDP or CDP.
CEE rejects the store and returns status code.
Store correct value or wait for CAB instance to enter a state when the store can be accepted.
Export/Import Import of CAB
time
type is
attempted
when identical
library name
and type name
are already
used within
target ERDB.
CB automatically changes library name and places status message in error log.
Inspect library name after import. If desired, modify the automatically assigned name to a preferred name (see Note 7).
Export/Import Import of CAB
time
instance is
attempted
when
corresponding
type was not
included with
the export files
and is not
already in
ERDB.
CB reports error and fails the import.
Go back to system from which CAB instance was exported. Repeat the export including the CAB type. Go to target system. Repeat the import (see Note 7).
Program execution time
ACE memory usage increases during instance of CAB types that have String or Time CDPs wired for input, and are either Distributed CAB types or an Atomic or Distributed CAB type that goes to a DORMANT state.
ACE running instances of CAB types gets overruns or, in a worst case, crashes.
Instead of using CDPs for inputs of these data types, use Parameter References instead so that you control when data is retrieved from the remote blocks (see Note 8).
Notes: 1. Block type locking flags are discussed in Block type locking flags. 2. All VB.NET compile errors are documented within Microsoft Visual Studio. 3. Procedures involved in the modification of CAB types are discussed in Modify a CAB.
- 344 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Phase of detection
Type of error
System response
Recommended user action
4. Data types supported by CAB parameter references are discussed in Data types for CDPs and parameter references.
5. Parameter access errors are returned to the CAB program at run time as members of enumeration CABAccStatusEnum. This is further discussed in Enumeration CABAccStatusEnum. Also, see description of parameters READSTATUS, WRITESTATUS, READERROPT and WRITEERROPT in Detailed description of CAB specific FDPs.
6. CABSTATE and related functionality is discussed in CAB instance states.
7. Import of CAB types is described in Import CAB"
8. This condition id discussed in Organizing CAB programs for best performance.
14.5.12 CAB error messages and codes
This section covers errors that occur in Microsoft Visual Studio. The following table summarizes these errors, which can appear in pop-up dialog boxes or other Microsoft Visual Studio windows. These errors are not identified by error codes. Other errors detected by Honeywell code that are identified by error codes are documented in the Control Builder Error Codes Reference. You can search for the error code number in Control Builder Error Codes Reference to locate information about the error. In addition, you might see Microsoft Visual Studio compiler errors that are identified by Microsoft error code numbers. These are documented in MSDN.
TIP Select a Microsoft error code number and press F1 to open MSDN help.
If any of these errors occur, and the workaround provided is not sufficient, contact your TAC representative.
Error type VS CAB build-time pop-up dialog
Error message
Operation failed because connections owned by this block could not be processed. Parameter RTOD was referenced in a connection, and the parameter does not exist.
Description Indicates during a Change Parent operation, a reference to a PRef could not be resolved.
Cause
A Change Parent operation was attempted after a referenced PRef was deleted.
Workaround Re-add the Parameter Reference before doing the Change Parent. This can be done manually, with the point picker, or copy and paste in the Parameter Reference from another source.
Error type VS CAB build-time pop-up dialog
Error message
Warning: Data Type of Parameter LOADDATA1 does not match the selected block.
Description
Indicates during a Convert operation, the LOADDATA1 parameters of the instance you are converting, and the type you are converting from, do not match. LOADDATA1 parameter is an internal parameter that contains the CAB program (dll) when the program is built.
- 345 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Cause
If you use the Change Parent to convert a CAB type to another CAB type and the new CAB type is in an incomplete state, you will get this warning in the Convert dialog. You will get the same error in the case where you have a CAB instance that is incomplete and now you convert it to a CAB type that is complete.
Workaround It will convert okay and the result will have the Incomplete Lock set.
Error type VS CAB build-time pop-up dialog
Error message
<CAB name> is being used by <Machine name/ User name>. The CAB type is locked either by an open project chart, configuration form, or an Import/Export operation by the user named in the message above. Do you want to correct the problem before continuing? If you select "No," you will need to contact your administrator to clear this CAB's Active Lock before it can be used again.
Description This indicates that the database has locks set related to the CAB type.
Cause
DB locks are set by a chart being open, a properties form open, or import/export by another user when attempting to do a Save As to ERDB operation or the user is exiting Visual Studio and is saving their data to the ERDB.
Workaround You will need to either release the DB lock (or have the user that has the DB lock release it) by finding the operation that has it locked (e.g. close a chart or properties form, wait for export to finish) and try the operation again. If you do not do this, you will need to have the lock removed later by an Admin using the DBAdmin tool.
Error type VS CAB build-time pop-up dialog
Error message
The EditLock value cannot be reset. You will need contact your administrator to clear the EditLock from this CAB. You will not be able to reedit this CAB until this is done.
Description It means that a serious failure occurred while trying to reset the Edit Lock.
Cause
Failure with Honeywell code.
Workaround You can contact TAC and provide the error logs to find out why the Edit Lock could not be reset. You can have the admin reset the Edit Lock by using the DBAdmin tool.
Error type VS CAB build-time pop-up dialog
Error message
The EditLock value for <block name> in <library name> cannot be reset. You will need to contact your administrator to clear the EditLock from this CAB. You will not be able to reedit this CAB until this is done.
Description This is the same as the previous only on a Save To ERDB As operation.
Cause
Failure with Honeywell code.
Workaround You can contact TAC and provide the error logs to find out why the Edit Lock could not be reset. You can have the admin reset the Edit Lock by using the DBAdmin tool.
Error type Error
VS CAB build-time pop-up dialog An unexpected error occurred within the CAB Development Environment. Contact
- 346 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
message
your Honeywell representative.
Description Error in CAB edit session.
Cause
This indicates that a serious problem occurred.
Workaround You should contact TAC and provide the ErrorLog file.
Error type VS CAB build-time pop-up dialog
Error message
An unexpected error occurred within the CAB Development Environment and it will be closed. The Development Area is <Development Area Path>' and contains this project and will not be deleted. Contact your Honeywell representative.
Description Error in CAB edit session.
Cause
This indicates that a serious error occurred.
Workaround There probably are changes that were not saved to the ERDB. The Build Directory will be left with the modified def files and programs. You should contact TAC to investigate the problem. The Error Log will show more detailed information for TAC.
Error type VS CAB build-time pop-up dialog
Error message
Custom Library Name must contain at least one alphabetic character or an underscore.
Description Invalid name for Library was entered.
Cause
Indicates on a Save As to ERDB, that you entered a library name that does not contain at least one alphabetic character ("A"-"Z") or an underscore ("_").
Workaround See Open a new CAB type for edit for proper naming conventions.
Error type VS CAB build-time pop-up dialog
Error message
Block Type Name must contain at least one alphabetic character or an underscore.
Description Invalid name for CAB was entered.
Cause
Indicates on a Save As to ERDB, that you entered a CAB name that does not contain at least one alphabetic character ("A"-"Z") or an underscore ("_").
Workaround See Open a new CAB type for edit for proper naming conventions.
Error type VS CAB build-time pop-up dialog
Error message
<New block name> is an invalid name or is already being used in <library name>.
Description Invalid name for CAB was entered.
Cause
Indicates on a Save As to ERDB, that you entered a name that is already used or the name and/or library has invalid characters in it.
Workaround See Open a new CAB type for edit for proper naming conventions and/or check to make sure the CAB name isn't already being used.
- 347 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Error type
VS CAB build-time pop-up dialog
Error message This command is not available when editing a CABlock.
Description CAB edit session VS message.
Cause
You tried to do an operation that is not allowed. (for example, adding a reference).
Workaround Do not attempt VS option.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window.
Error message
CAB Error: Not allowed to use <class or method name>.
Description Inappropriate construct for process control.
Cause
You are trying to use a class or method not appropriate for process control.
Workaround
Do not use this class or method. Click the Task List item to go to the construct that is not allowed. Building the CAB will not be successful until all inappropriate constructs are removed. If you believe that this construct is appropriate for process control, contact TAC.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window
Error message
CAB Error: Not allowed to use <class or method name>. Valid in the following execution mode(s): <execution mode(s)>
Description Inappropriate construct for the current configuration.
Cause
You are trying to use a class or method that is not appropriate for the execution mode as defined in the CAB.
Workaround Reconfigure the CAB for the correct execution mode or do not use the class or method. If you believe that this construct is appropriate for the execution mode you are trying to use it in, contact TAC.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window
Error message
CAB Error: Not allowed to Declare references to external procedures.
Description Using Declare Statement.
Cause
You are trying to use the Declare statement to access external procedures-this is not allowed.
Workaround
Do not use the Declare statement. Click on the Task List item to take you to the approximate area where the Declare statement is located. Building the CAB will not be successful until all Declare statements are removed. Any procedures that you want to access must be part of the CAB.
Error type
Error message
VS CAB build-time pop-up dialog
Ildasm.exe has generated errors and will be closed by Windows. You will need to restart the program. An error log is being created.
- 348 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Description Error occurred during a build of a CAB.
Cause
This indicates that a serious problem occurred with the .Net Framework.
Workaround You should contact TAC.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window
Error message
<cdpname>.Value: Value of type `<VBDataType>' cannot be converted to Honeywell.CAB.BlockMap.<CABDataType>CDP.
Description Syntax error.
Cause
You failed to add ".Value" to a CDP name when referencing its value.
Workaround Add ".Value" to the CDP name and rebuild.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window
Error message
<prefname>.Value: Value of type `<VBDataType>' cannot be converted to Honeywell.CAB.BlockMap.<CABDataType>PRef'.
Description Syntax error.
Cause
You failed to add ".Value" to a PRef name when referencing its value.
Workaround Add ".Value" to the PRef name and rebuild.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window
Error message
CAB Error: Not allowed to use Microsoft.VisualBasic.FileSystem::<method>. Use the equivalent System.IO construct.
Description Using a disallowed FileSystem class.
Cause
You used a disallowed method in the Microsoft.VisualBasic.FileSystem class.
Workaround Recode using a method in the System.IO class.
Error type VS CAB build-time "Compiler" error shown in the Task List and Output Window
Error message
CAB Error: The Wait subroutine can be used only in CABs defined for distributed execution mode.
Description Using a subroutine that is disallowed in the current configuration.
Cause
You used the Wait() subroutine in a CAB that is configured for atomic execution mode, which is not allowed.
Workaround Reconfigure the CAB for distributed execution mode, or do not use this subroutine.
Error type
Error message
VS CAB build-time "Compiler" error shown in the Task List and Output Window
CAB Error: The History subroutines can be used only in CABs defined for distributed execution mode.
- 349 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Description Using a class that is disallowed in the current configuration.
Cause
You are using a subroutine in the History class in a CAB that is configured for atomic execution mode, which is not allowed.
Workaround Reconfigure the CAB for distributed execution mode or do not use this subroutine.
Error type VS CAB build-time pop-up dialog
Error message
An unexpected error occurred while trying to backup the Development Area. The files will be left in the original location at`{0}'. Please contact your Honeywell representative. [`{0}' is the path to the location of the files.]
Description
After an unexpected error from the CAB build time environment, the CAB infrastructure was attempting to move the project files to a new location, and an error occurred while attempting to do so.
Cause
The most likely cause would be a disk problem.
Workaround Try to reuse the original files in the location specified in the error message.
Error type VS CAB build-time pop-up dialog
Error message
There are instances of this CAB type that are being used as Insertion Points. You cannot configure CAB types used as insertion points for Distributed processing. Unable to update the existing CAB type. Do you want to save this CAB under a different name.
Description User is attempting to save a CAB type that is configured for distributed execution and configured as an insertion point algorithm.
Cause
A distributed execution CAB cannot be used as an insertion point algorithm.
Workaround Reconfigure the CAB for atomic execution, or Save the CAB under a new name for use in distributed execution applications where the CAB is not an insertion point algorithm.
The following errors will appear in the Application Event Log for CAB Startup Errors.
Error type VS CAB run-time Error on creation of temp blob directory
Source
CABOnACE
Error message
"Unable to create the temporary directory to hold the DLLs " + "<" + BlobFilePath + "> " + e.Message, EventLogEntryType.Error."
Description CAB run-time attempted to create a temporary directory during CAB startup and received an error.
Cause
Windows exception on directory creation .
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error on creation of CAB trace directory
- 350 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Source
CABOnACE
Error message
"Unable to create the CAB Trace directory " + "<" + TracePath + "> " + e.Message, EventLogEntryType.Error."
Description CAB run-time attempted to create the CAB trace directory during CAB startup and received an error.
Cause
Windows exception on directory creation.
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error starting tracing
Source
CABOnACE
Error message
"Unable to start CAB Tracing " + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to use the CAB trace directory during CAB startup and received an error.
Cause
If you received the error on not being able to create the trace directory, this error would also result or it could be the directory is busy which would not allow CAB to create the trace file.
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error creating ACE working directory (under bin directory)
Source
CABOnACE
Error message
"Unable to create the working directory for the CAB types " + "<" + AssemblyPath + "> " + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to create the ACE working directory during CAB startup and received an error.
Cause
Windows exception on directory creation.
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error on CAB loader startup
Source
CABOnACE
Error message
"Unable to create BlockLoader " + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to start up using the block loader file and received an error.
Cause
Missing the honeywell.cab.blockloader.dll under ...\system\bin possibly due to an installation error or file is busy.
- 351 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Workaround Verify CAB installed correctly on ACE node by reviewing the C:\install\cab_ install.txt file. Contact TAC if install appears correct.
Error type VS CAB run-time Error on CAB client startup
Source
CABOnACE
Error message
"Unable to Start Distributed CAB environment. " + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to start up the distributed CAB process cabclient.exe and received an error or file is busy.
Cause
Cabclient.exe under ...\system\bin is missing, possibly due to installation error.
Workaround Verify CAB installed correctly on ACE node by reviewing the C:\install\cab_ install.txt file. Contact TAC if install appears correct.
Error type VS CAB run-time Error on creation of the CAB file I/O default directory
Source
CABOnACE
Error message
"Unable to create File I/O default directory for distributed CABs " + "<" + fileIOPath + ">" + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to create a default file I/O directory during CAB startup, and received an error.
Cause
Windows exception on directory creation.
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error on creation of temp blob directory
Source
CABOnACE
Error message
"Unable to create File I/O default directory for distributed CABs " + "<" + fileIOPath + ">" + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to create a default file I/O directory during CAB startup, and received an error.
Cause
Windows exception on directory creation.
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error on creation of default file I/O directory
Source
CABOnACE
Error message
"Unable to create a default File I/O directory for distributed CABs " + "<" + fileIOPath + ">" + e.Message, EventLogEntryType.Error
Description CAB run-time attempted to create a default file I/O directory during CAB startup, and received an error.
- 352 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Cause
Windows exception on directory creation.
Workaround Verify that cdasp/ace is running and has sufficient permission to create the directory whose path is indicated in the event log and also make sure that there are no Windows Explorers open that could have the directory busy.
Error type VS CAB run-time Error NullReferenceException when using a PRef
Source
CABOnACE
Error message
"Object reference not set to an instance of an object."
Description When trying to use or set the TEXTREF property of a PRef that is not enabled for dynamic re-referencing, this exception is thrown.
Cause
The TEXTREF property is valid only when dynamic re-referencing is enabled.
Workaround Do not use this property with a PRef if it is not enabled for dynamic rereferencing. Or, if appropriate, enable dynamic re-referencing for the PRef.
14.5.13
Error Messages associated with CAB/C300
The following table describes error messages associated with the use of CAB/C300. Most arise when an attempt is made to use programming constructs or CAB functionalities which are outside the subset supported by CAB/C300. Messages are listed in the leftmost column with supplementary information provided in adjacent columns. The table does not list all possible error messages but presents a set sufficient to cover all categories. In each case it is assumed that FDP X_PLATOPT has been set equal to ACEANDC300.
TIP
The error messages described in the following table are specific to CAB/C300. These occur when you are coding for a CAB/C300; specifically if you attempt to use CAB/ACE functionality that is not included in the CAB/C300 functionality subset.
Type of error
Table 14.10 CAB/C300 error messages
Error message example
Cause
When Additional detected information
Aggregate Data Member
Distributed Execution
Data Type (System.Array) is not legal to use in persistent memory such as statics or CAB user block data members.
A variable (data member) of Aggregate Type (nonscalar) is defined within the CABlock class within the VB.NET code. String, Array and Class are all Aggregate Types.
CAB Types with X_ EXECMODE configured as DISTRIBUTED are not supported if X_PLATOPT is configured as
FDP X_EXECMODE is set to DISTRIBUTED within the PDE.
Build
PDE Save
Aggregates and the semantics of "New"
Distributed Execution
- 353 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Type of error Error message example
Cause
When Additional detected information
Dynamic PRef
File Access
File Access
File Access
History Access History Access
ACEANDC300.
You cannot specify Parameter References as being dynamic References if the X_PLATOPT is configured as ACEANDC300.
A PRef defined within the PDE
PDE has the Dynamic
Save
Reference option checked.
CAB Error: Not allowed to use System IO StreamReader Valid in the following execution mode (s): distributed
A statement is used to do file IO within the VB.NET code.
Build
CAB Error: Not allowed to use System IO StreamReader::Close Valid in the following execution mode(s): distributed
A statement is used to do file IO within the VB.NET code.
Build
CAB Error: Not allowed to use System IO StreamReader::ReadToEnd Valid in the following execution mode(s): distributed
A statement is used to do file IO within the VB.NET code.
Build
CAB Error: Not allowed to use Opc.ResultID::Failed
A statement is used to do OPC based history data access within the VB.NET code.
Build
CAB Error: The History subroutines can be used only in CABs defined for distributed execution mode.
A statement is used to do OPC based history data access within the VB.NET code.
Build
Dynamic PRef
File access
File access
File access
History access History access
Late Stage Build Processing
An error occurred in the final stage of CAB/C300 build processing. The type cannot be loaded. Check for programming errors.
An array CDP has been accessed without specifying an index value.
Build
Metadata usage
CAB Error: Not allowed to use System.Enum::ToString.
A statement has been coded which requires the use of ECMA .NET metadata.
Build
Option Strict
For a CABlock when X_ PLATOPT is configured for ACEANDC300, Option Strict must be ON.
An attempt has been made Build to build an ACEANDC300 type with Option Strict Off.
Shared Keyword
CAB Error: "Shared" statements are not supported if X_PLATOPT is configured for
The Shared keyword is used to declare a class data member as shared within the VB.NET code
Build
Late Stage Build Processing
Metadata
Option Strict
Keyword 'Shared'
- 354 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
Type of error Error message example
Cause
When Additional detected information
ACEANDC300.
tab.
Static Keyword
CAB Error: "Static" statements are not supported if X_PLATOPT is configured for ACEANDC300.
The Static keyword is used to declare a local procedure variable as static within the VB.NET code tab.
Build
Structure Keyword
CAB Error: "Structure" statements are not supported if X_PLATOPT is configured for ACEANDC300.
The Structure keyword is used to define a structure within the VB.NET code.
Build
Try-Catch Clause
CAB Error: Try-Catch statements are not supported if X_PLATOPT is configured for ACEANDC300.
A Try-Catch construct is used within the VB.NET code.
Build
Unsupported Core Class
System.Type is not a supported data type for CAB on C300.
A core class defined within the ECMA .NET standard but not supported by CAB/C300 is used within the VB.NET code tab.
Build
Unsupported CAB Error: local variable Value Type "Value2" is defined as type
Int16 which is not supported if X_PLATOPT is configured for ACEANDC300.
A value of data type defined within the ECMA .NET standard but not supported by CAB/C300 is used to define a variable within the VB.NET code tab.
Build
VB-Only Construct
CAB Error: Not allowed to use Microsoft VisualBasic CompilerServices StringType FromDouble
A VB.NET programming construct has been used which relies upon a class or function defined within namespace Microsoft VisualBasic or one of its sub-namespaces.
Build
VB-Only Construct
CAB Error: Not allowed to use Microsoft VisualBasic CompilerServices CharArrayType FromString
A VB.NET programming construct has been used which relies upon a class or function defined within namespace Microsoft VisualBasic or one of its sub-namespaces.
Build
VB-Only Construct
CAB Error: Not allowed to use Microsoft VisualBasic CompilerServices ProjectData SetProjectError
A VB.NET programming construct has been used which relies upon a class or function defined within namespace Microsoft VisualBasic or one of its sub-namespaces.
Build
Keyword 'Static'
Keyword 'Structure'
Try-Catch clause
Unsupported core class
Unsupported value types
VB-only constructs and TryCatch clause
VB-only constructs and TryCatch clause
VB-only constructs and TryCatch clause
- 355 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.6
Type of error Error message example
Cause
When Additional detected information
VB-Only Construct
CAB Error: Not allowed to use Microsoft VisualBasic CompilerServices ProjectData ClearProjectError
A VB.NET programming construct has been used which relies upon a class or function defined within namespace Microsoft VisualBasic or one of its sub-namespaces.
Build
VB-only constructs and TryCatch clause
CDB troubleshooting approach
Typically, CDBs will be debugged in the context of the control strategy in which they are deployed. If this strategy also involves CABs, the CAB troubleshooting tools such as SIM-ACE and the Microsoft Visual Studio debugging tools may be helpful in pinpointing CDB problems. Some error conditions that can occur with CDBs are covered in the following topics.
14.6.1 14.6.2 14.6.3
CDB exceeds maximum checkpoint size
CDB checkpoint data size is limited in size to 32 KB (actually, 32,767 bytes). If you try to create a CDB type whose checkpoint size would exceed the limit, and you try to save the PDE data, an error shows as in the following figure.
If you get this error, you must reduce the size of the CDB. One solution might be to split up the data into two or more CDBs.
Array parameter exceeds maximum size
Whole array transfer supports a maximum parameter size of 8 KB. If you try to connect arrays that exceed the maximum size, an error shows as in the following figure. This condition is not unique to CDB. For calculating the size of an array, you can use the information in Storage requirements for data types.
Storage requirements for data types
For estimating the size of a CDB, the following table shows the storage requirements for the various data types. These values can be used to compute the size of the actual data defined for a CDB but does not account for the overhead of the CDB infrastructure.
Table 14.11 Storage Requirements for Data Types
Data type
Storage required
FLOAT64
8 bytes
INT32
4 bytes
BOOLEAN
2 bytes
STRING
2 bytes per character
TIME
8 bytes
- 356 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.6.4
Data type DELTATIME TIMEOFDAY
8 bytes 8 bytes
Storage required
Unloaded state is an error
In CAB, Unloaded is a transient state that is a valid state while the CAB is being loaded. In CDB, the Unloaded state after a load operation indicates that the CDB did not load and therefore represents an error condition that will require troubleshooting. The most likely cause would be an out of memory condition.
14.7
Contacting TAC
If you encounter a CAB or CDB problem that you cannot resolve it using information and troubleshooting procedures from this guide, you will need to contact TAC. This section lists the information required.
14.7.1
Information required for build-time problems
1. Provide the ErrLog.txt from both the client (where the error was returned) and the server. This is located under "ProgramData/Honeywell/Experion PKSPKS."
2. If the error indicates that the files were left in the Build Directory and a path is given to this directory, these files are needed. They will be in a directory " Users/AppData/Roaming/Honeywell/Experion PKSPKS/Engineering Tools/CAB/Build/<GUID>."
3. Export the CAB Type that for which the error occurred and provide these files. 4. Include an exact description of what the user was doing and the replies by the user to any
prompts that were displayed. 5. Provide any Event Messages in the Event Viewer. 6. Provide the exact error that was displayed to the user.
14.7.2
Information required for CAB/ACE run-time problems
1. Provide the CAB log file from the ACE server. This is located under " C:/ProgramData/Honeywell/Experion PKS/CAB/Trace/<ACE server name>/CABBlockManager_x_y.txt." The "x" and "y" are unimportant - just whatever trace file is there. If there is more than one, provide all.
2. Export the CAB Type(s) that might be involved in the error, along with the CM that the CAB instance(s) are in, and provide these files. Some users may be unwilling to send the types and CMs for security and/or proprietary reasons.
3. Provide any Event Messages in the Event Viewer.
4. Provide the exact error that was displayed to the user.
5. It may be necessary for TAC to get involved to enable the internal CAB tracing that is available. The users are not informed on how to enable this feature.
- 357 -
Chapter 14 - CAB and CDB troubleshooting and maintenance
14.7.3
Information required for CAB/C300 run-time problems
1. Export the CAB Type(s) that might be involved in the error, along with the CM that the CAB instance(s) are in, and provide these files.
2. Provide the exact error that was displayed to the user.
- 358 -
CHAPTER
15
CAB API REFERENCE
15.1
The overall CAB map
The following figure is a map of the overall CAB API. The CAB type is shown in the center of the diagram. Solid arrows indicate that CAB types have a general dependence on the designated elements. The dashed arrow from the CAB box to the BlockBase box indicates a particular kind of dependence--that class CAB inherits from class BlockBase.
15.1.1
15.2
Object Browser
More information about the CAB APIs can be obtained thru the Visual Studio .Net Object Browser by right-clicking on the CAB API and selecting Go To Definition as shown in the following figures.
API quick reference
The following summary lists the API categories with their specific APIs. Click on any item in the list to go to that specific topic. Page numbers are included for those who are using a paper copy of this document.
15.2.1
Summary of APIs
Class CAB l Subroutine Execute() of class CAB
Enumerations l Enumeration RestartEnum l Enumeration CABAccStatusEnum l Enumeration CABCommandEnum l Enumeration CABStateEnum l Enumeration CABReRefCommitEnum l Enumeration CABReRefStateEnum
CDP classes l Summary of CDP classes
Parameter reference classes
- 359 -
15.3
Chapter 15 - CAB API reference
l Summary of parameter reference classes l Read(), ReadStatus, and Value l Write() l WriteStatus l Parameter reference list class
CABMath class l Min Methods l Max Methods l Sum Methods l Avg Methods
BlockBase l FDP classes l PROGSTSDESC l CABCOMMAND l CABSTATE l X_REFCOMMIT l X_REFSTATE l PERIOD l PROCSPECEXEC l Subroutine Send() l Subroutine Abort() l Subroutine Wait() l Property Restart()
History APIs l ExperionHistoryServerName property l PHDHistoryServerName property l ConnectToHDAServer method l GetHistory method l GetAvgHistory method
VB.NET APIs
Class CAB
The CAB class is the block type definition that the CAB programmer supplies to the system. Many of its characteristics are actually supplied by class BlockBase from which it inherits. BlockBase is automatically provided by system infrastructure. When a CAB type is created, the system automatically generates a code frame to serve as the starting point for algorithm development. This is described in Layout of the development environment. The main task of the CAB programmer is to provide definitions for the one public method of class CAB: Execute().
- 360 -
Chapter 15 - CAB API reference
15.3.1
Subroutine Execute() of class CAB
Definition of algorithm content for this subroutine is required. See Code CAB algorithm for further information.
15.4 Enumerations
15.4.1
Enumeration RestartEnum
Enumeration RestartEnum provides the type for the Restart API as defined in the following table.
None
Table 15.1 Members of Enumeration RestartEnum
Member name
Value
0
CABToNormal
5
CEESwitchStart
8
CEEWarmStart
10
CEEColdStart
20
BlockInActivate
30
BlockActivate
30
BlockLoad
40
Restart can be used to identify whether system events have occurred that may need special initializations. A value of None indicates that no system event has occurred. Usage is illustrated as follows. BlockInActivate is only used internally within the CAB run-time and will not be seen within a CAB program since the block is inactive and not running.
Public Overrides Sub Execute() If Restart <> RestartEnum.None Then Select Case Restart Case RestartEnum.CABToNormal ' initializations for CABToNormal event Case RestartEnum.BlockLoad ' initializations for BlockLoad event Case RestartEnum.BlockActivate ' initializations for BlockActivate event Case RestartEnum.CEEColdStart ' initializations for CEEColdStart event Case RestartEnum.CEEWarmStart ' initializations for CEEWarmStart event End Select End If ' do regular processing
End Sub
Member CEESwitchStart is the value returned for the first cycle of execution following either a normal redundancy switchover of a C300 or an OPM switchover of a C300.
- 361 -
Chapter 15 - CAB API reference
If required, CAB programmers can test for the value of CEESwitchStart and do appropriate initializations when that transition is detected. In most applications, no initializations are required following a switchover, so the value CEESwitchStart would not be used for triggering initializations. If a CAB running on ACE tests the value of CEESwitchStart, it always returns False.
The values returned by API Restart have an inherent priority represented by the numerical value of the ordinals. If multiple conditions have become true since the last block execution, then the highest value ordinal wins. For example, suppose a CAB instance is within an inactive CM in the old primary after which a switchover occurs. The CM is activated within the new primary. Under such conditions, the CAB instance would see a Restart transition of BlockActivate and not CEESwitchStart.
Members of RestartEnum can be referenced by the full name (such as "RestartEnum.BlockLoad") or by the short name (such as "BlockLoad"). To use the short name, you must insert an Imports statement ahead of other program declarations:
Imports Honeywell.CAB.SysCommon.RestartEnum
For many CAB implementations, special initializations in response to system events are unnecessary. Enumeration RestartEnum and the Restart API merely give the programmer a range of options to handle any eventuality. See Data initializations under Execute() and Property Restart () for more information on Restart and RestartEnum.
15.4.2
Enumeration CABAccStatusEnum
Enumeration CABAccStatusEnum is predefined for use with the ReadStatus and WriteStatus properties of the parameter reference classes as defined in the following table.
Member name
OK
Table 15.2 Members of Enumeration CABAccStatusEnum
Value
Descriptive name
0
OK--CABAccStatusEnum.OK will be returned for PRef I/O that is
completely successful (OK) and for all I/O that returns a Warning status
(for example, Clamped Value Warning).
Bad
10 Bad--This indicates an error that is not covered by other enumeration
values in this table.
RightsViol
11 Rights Violation--Indicates that the store is currently locked out because of a condition that can be changed by the operator. A classic example would be if CAB had an access level of Program and was trying to store MODE but MODEATTR was not equal to Program.
AccLevelViol 12
Access Level Violation--A store is being attempted by the CAB instance which is rejected because the access level in use for the CAB (Program or Continuous Control) is permanently forbidden by the parameter (see Access Lock attribute for CDPs).
IllegalValue 13 Illegal Value.
RangeLimExc 14 Range Limit Exceeded.
IndexLimExc 15
ConfigMis
16
Index Limit Exceeded.
Configuration Mismatch--the PRef points to a block that has not been loaded, or has been moved to a different controller. In the latter case, reload the CM to reconnect the parameter reference. This status will also be returned if you attempt to read an OUTPUT PRef or write an INPUT PRef, or if the PRef is not connected to any target (is null).
- 362 -
Chapter 15 - CAB API reference
Member name
Value
CommFail
17 Communication Failure.
WritePending 18 PRef Write is Pending.
Descriptive name
WriteRejected 19
ReRefBusy 20
ReRefFail
21
ReadPending 22
PRef Write was Rejected because a write was attempted while status was WritePending.
The PRef is being modified. It remains unusable until the new reference is connected to the PRef.
The last re-reference action failed.
PRef Read is Pending.
In release 210, ReadStatus and WriteStatus are initialized to "OK" when the block is loaded. Beginning with release 300, ReadStatus and WriteStatus are initialized to "Bad" when the block is loaded, or when a parameter re-reference action is completed.
The value returned by the ReadStatus property is of type CABAccStatusEnum. Usage is illustrated below where FLOW is a parameter reference used for input.
If Not FLOW.ReadStatus = CABAccStatusEnum.OK Then ' do error processing Else ' do normal processing End If
To use the short form of a CABAccStatusEnum member name (such as "OK" instead of "CABAccStatusEnum.OK"), the following statement can be inserted ahead of any other program declarations:
Imports Honeywell.CAB.SysCommon.CABAccStatusEnum
For a more detailed example on the usage of CABAccStatusEnum and the parameter reference property ReadStatus, see Use of data access status in CAB.
15.4.3
Enumeration CABCommandEnum
Enumeration CABCommandEnum is predefined for use with the CABCOMMAND property of BlockBase (see CABCOMMAND). It can also be used with a parameter reference that points to the CABCOMMAND FDP of another CAB. See the definitions in the following table.
None
Table 15.3 Members of Enumeration CABCommandEnum
Member name
Value
0
Quit
1
Run
2
15.4.4
Enumeration CABStateEnum
Enumeration CABStateEnum is predefined for use with the CABSTATE property of BlockBase (see CABSTATE). It can also be used with a parameter reference that points to the CABSTATE FDP of another CAB. See the definitions in the following table.
- 363 -
Chapter 15 - CAB API reference
Unloaded Normal Exception Terminated Dormant
Table 15.4 Members of Enumeration CABStateEnum Member name 0 1 2 3 4
Value
15.4.5
Enumeration CABReRefCommitEnum
Enumeration CABReRefCommitEnum describes the values of the X_REFCOMMIT parameter (see Using the X_REFCOMMIT parameter). See the definitions in the following table.
IDLE
Table 15.5 Members of Enumeration CABReRefCommitEnum
Member name
Value
0
COMMIT
1
CANCEL
2
15.4.6
Enumeration CABReRefStateEnum
Enumeration CABReRefStateEnum describes the values of the X_REFSTATE parameter (see Using the X_REFSTATE parameter). See the definitions in the following table.
IDLE
Table 15.6 Members of Enumeration CABReRefStateEnum
Member name
Value
0
TRANSLATING
1
COMMITTING
2
15.5
CDP classes
CAB infrastructure provides a predefined class for each supported CDP data type. When the CAB program reads and writes CDPs, it reads and writes a VB property of these classes.
15.5.1
Summary of CDP classes
The complete set of classes is listed in the following table.
BooleanCDP
Table 15.7 Custom Data Parameter Classes Class name
Int32CDP
- 364 -
Chapter 15 - CAB API reference
15.5.2
Float64CDP StringCDP TimeCDP DeltaTimeCDP TimeOfDayCDP
Class name
CDP classes are not usually used to explicitly declare variables within CAB programs. Instead, they are used implicitly by virtue of predefined CDP objects declared within class BlockBase.
CDP class usage
Each CDP class is defined to have a property called "Value."This property has the type implied by the name of the class and is used to read or write the value of the CDP. The declaration of the Value property and other properties for class Float64CDP is shown in Parameter reference class usage. For all other classes the properties are declared with syntax that is equivalent except for data type in the Value and Item properties, with the following exception: Min, Max, Sum, and Avg apply to Float64CDP class only.
Member name
Value
Declaration Public Property Value() As Double
Description
Allows read and write of value for the CDP.
Rank
Public ReadOnly Property Rank() As Integer Gets the rank (number of dimensions) of the array. For a scalar parameter, it is zero. For a single dimension array, it is one. For a twodimension array, it is two.
Dim1
Public ReadOnly Property Dim1() As Integer
Gets the size of dimension 1 of an array CDP. For a scalar parameter, this returns zero. For a singledimension array or a two-dimension array, this returns the size of the first dimension.
Dim2
Public ReadOnly Property Dim1() As Integer
Gets the size of dimension 2 of an array CDP. For a scalar parameter or single-dimension array, this returns zero. For a two-dimension array, this returns the size of the second dimension.
LowBound1 Public ReadOnly Property LowBound1() As Integer
Gets the lower bound of dimension 1 of the array CDP. For a scalar parameter, this returns zero. For a single dimension array or a twodimension array, this returns the lower bound of the first dimension.
LowBound2 Public ReadOnly Property LowBound2() As Gets the lower bound of dimension 2
Integer
of the array CDP. For a scalar
parameter or a single dimension
- 365 -
Chapter 15 - CAB API reference
Member name Item
GetType() Min Max Sum Avg
Declaration
Description
array, this returns zero. For a twodimension array, this returns the lower bound of the second dimension.
Public ReadOnly Default Property Item
No reason to access this property. It is
(Index as Integer)As
added by .NET because there is an
Honeywell.CAB.BlockMap.Float64CDPIndex "Indexer" property on the class (for
array access). "Item" is a method that
behaves like the array specification -
used instead of "(index)." There is no
reason for the CAB to use this
because the normal array
specification is simpler.
Public Function GetType() As System.Type
No reason to access this property. GetType comes with all classes and returns the system "type" of this object.
Public Function Min() As Double
If the CDP is an array parameter (1D or 2D), this returns that smallest value found in all of the elements. If this is a scalar parameter, it returns that value.
Public Function Max() As Double
If the CDP is an array parameter (1D or 2D), this returns that largest value found in all of the elements. If this is a scalar parameter, it returns that value.
Public Function Sum() As Double
If the CDP is an array parameter (1D or 2D), this returns the sum of all of the elements. If this is a scalar parameter, it returns that value.
Public Function Avg() As Double
If the CDP is an array parameter (1D or 2D), this returns the average of all of the elements. If this is a scalar parameter, it returns that value.
For any of these Float64CDP member functions, if the CDP value is NaN (for scalar CDPs) or any element in the array (for array CDPs) is a NaN, a NaN is returned. If Temp1 is defined as a Float64CDP then CABMath.Min (Temp1) is equivalent to Temp1.Min(). This is true for all CABMath functions. The following example shows how CDP objects are used. Here it is assumed that two Float64CDPs, Temp1 and Temp2, have been defined for the CAB type using PDE.
TEMP1.Value = 50.0 TEMP2.Value = TEMP1.Value
15.6 Parameter reference classes
CAB infrastructure provides a predefined class for each supported reference data type. When the CAB program reads and writes parameter references, it is reading and writing members of these
- 366 -
classes.
Chapter 15 - CAB API reference
15.6.1 15.6.2
Summary of parameter reference classes
The complete set of classes is listed in the following table.
BooleanPRef
Table 15.8 Parameter Reference Classes Class name
Int32PRef
Float64PRef
StringPRef
TimePRef
DeltaTimePRef
TimeOfDayPRef
Parameter reference class usage
PRef classes can be used to explicitly declare variables within CAB programs. However, this is a minority use case. Usually, the PRef classes are used implicitly by virtue of pre-defined PRef objects declared within class BlockBase. For an example of explicit use of PRef classes, see Use of parameter reference variables in CAB.
Each PRef class has several members. Member declarations are shown in the following table, using Float64PRef as an example. For all other PRef classes, member declarations are equivalent except for the Value property. Declaration of the Value property differs only in data type.
Member name
Value
Table 15.9 Declaration of Members for Class Float64PRef
Declaration
Description
Public Property Value() As Double
Accesses the value of a parameter that was read by a PRef Read(), or sets the value to be written by a PRef Write().
Read()
Public Sub Read()
Called for input or input/output PRefs before the Value property is read. Causes data to be transferred into the block. Attempt to call Read() on a PRef whose data flow attribute is output causes a data access error. The data flow attribute is configured in the PDE and allows you to specify INPUT, OUTPUT, or both (IN/OUT) for a PRef's data direction.
Write()
Public Sub Write()
Called for output or input / output PRefs after the Value property has been written. Causes data to be transferred out of the block. Attempt to call Write on a PRef whose data flow attribute is input causes a data access error. Attempt to call Write on a PRef whose WriteStatus is WritePending causes a data access error and the WriteStatus will change to WriteRejected. The data flow attribute is configured in the PDE and allows you to specify INPUT, OUTPUT, or both (IN/OUT) for a PRef's data direction.
GetType() Public Function GetType() As
No reason to access this property. GetType comes with all classes and returns the system "type" of this object.
- 367 -
Chapter 15 - CAB API reference
15.6.3
Member name
Declaration System.Type
Description
ReadStatus
Public ReadOnly Property ReadStatus() As CABAccStatusEnum
Returns the data access status for the last Read() or PRefList.Read() transaction of the PRef. Can be used to identify data access failures before using the Value. See Enumeration CABAccStatusEnum for a description of possible values returned by ReadStatus.
WriteStatus
Public ReadOnly Property WriteStatus() As CABAccStatusEnum
Returns the data access status for the last Write() or PRefList.Write() transaction of the PRef. For local writes, the WriteStatus is available during the same cycle of execution as the Write() invocation. For remote writes, WriteStatus will be WritePending during the same cycle of execution and change to a different status in subsequent cycle of execution if and when the write is completed. See "Enumeration CABAccStatusEnum" for a description of possible values returned by Write Status. Attempting a Write() when the WriteStatus is WritePending will cause the WriteStatus to change to WriteRejected.
IsNull
Public ReadOnly Property IsNull() As Boolean
Returns True when the PRef is undefined. Allows for instance configurations that define some but not all PRefs. This property is used if a CE wants to define a generalpurpose block type that allows varying numbers of references. For an example of the use of IsNull see " Use of parameter reference variables in CAB."
IsValid
Public ReadOnly Property IsValid As Boolean
Returns True if the parameter reference is currently bound to a parameter. This is applicable to both CAB/ACE and CAB/C300. Returns False if a re-reference action is in progress, the most recent re-reference action failed, or if the parameter reference is null. This is not applicable to CAB/C300. Can also be used with static references to determine whether or not the reference is valid. For an example of usage, see Checking for re-reference errors.
TextRef
Public Property TextRef As String
Contains the text name of the current parameter reference for a parameter that is enabled for dynamic re-reference. It will be set to a string that starts with "<err" if an error occurs in the binding of the new reference. For examples of usage, see Reading the reference name and Changing the reference name. Note 1: This is also not valid with CAB on ACE if the reference is not a dynamic reference. If you access this on a static reference, run-time exception occurs. Note 2: TextRef is not supported in CAB/C300.
Although the PRef classes support several members, few are used with any frequency. Valueessential in any program that has PRefs--is used most often. Read() and Write() are used occasionally. But for most programs, PRefList.Read() and PRefList.Write() can be used instead with less coding effort (see "Parameter reference list class"). ReadStatus is used occasionally depending on how the programmer has chosen to organize error handling for data access. IsNull is used rarely.
The following paragraphs illustrate the use of the most frequently used PRef members--Read(), ReadStatus, Value, Write(), and WriteStatus.
Read(), ReadStatus, and Value
The following example shows the use of Read(), Value, and ReadStatus. Here, it is assumed that PV
- 368 -
Chapter 15 - CAB API reference
is a predefined Float64PRef while LASTPV and BADPVCOUNT are predefined Float64CDPs.
PV.Read() If PV.ReadStatus = CABAccStatusEnum.OK Then LASTPV.Value = PV.Value BADPVCOUNT.Value = 0
' use PV.Value ElseIf BADPVCOUNT.Value <= 3 Then BADPVCOUNT.Value = BADPVCOUNT.Value + 1
' use LASTPV.Value Else
' handle case of PV which has become unusable End If
In this example, ReadStatus is used to obtain a binary indication of whether the PV value is useable. Since PV is real valued, the IsNan() function of the VB.NET Double structure could equally well be used. This is because PRefs automatically set Value to the fail-safe value for any read access that does not complete successfully. For reals, the fail-safe value is NaN. Thus, the first two lines of the code could be replaced with the following:
PV.Read() If Double.IsNan(PV.Value) Then
Of course, many applications using process variables would not be implemented to hold a last good PV value over execution cycles where the current PV was unavailable. For these applications, there might not be any need to use ReadStatus or IsNan() at all.
PV.Read() ' use PV.Value regardless of whether it's bad or good
In this segment, the computation implied by the comment would process correctly if there had been no error on the PV access. If there had been an error, it would propagate NaN values. The final computation would result either as a useable value or as NaN.
Examples of conditions that would cause a data access error for Read() of a PRef are deletion of the block supplying the input, failure of the node supplying the input, or communication failure. Note, however, that an error in definition of the CAB type could also cause this condition.
If parameter reference PV was declared as an output and not an input, the error path discussed above would execute. Similarly, if a parameter reference was used as an output but was not declared as such within PDE, the run-time output reference would not work.
15.6.4 Write()
A more compelling motivation for the use of ReadStatus can be found in the case of references that are not real-valued.
Consider the following example which uses ReadStatus and Write() as well. Here, it is assumed that MODE and MODEATTR are Int32PRefs, SP is a Float64PRef and LocalModeAttr is a local INTEGER. The PRefs point to parameters on a block in the same CEE as the CAB instance. It is also assumed that the CAB type has been designed to write parameters with an access level of "PROGRAM" (that is, FDP ACCESSLEVEL was set to PROGRAM at the time the CAB type was created).
MODEATTR.Read() If MODEATTR.ReadStatus <> CABAccStatusEnum.OK Then
' handle error condition Else LocalModeAttr = MODEATTR.Value
' Program Mode Attribute is 2 MODEATTR.Value = 2 MODEATTR.Write()
' Auto Mode is 1 MODE.Value = 1
- 369 -
Chapter 15 - CAB API reference
SP.Value = 50.0 MODEATTR.Value = LocalModeAttr MODE.Write() : SP.Write() : MODEATTR.Write() End If
There are several things to note about the above example. First, observe that the code is written with a general sequence in which invocations of Read() precede the use of Value for input PRefs, and stores to Value precede invocations of Write() for output PRefs. The Value property acts like a local data cache with no connection to the world outside the CAB. To transfer data into Value, Read () must be invoked first. To transfer data out of Value, Write() must be invoked afterwards.
Next, observe the use of ReadStatus. MODE and MODEATTR are not real-valued. Thus there are fewer options for error detection. CAB infrastructure does automatically supply a fail-safe value for Int32PRefs (zero). But this fail-safe value is not uniquely different from all operational values. To get around this, ReadStatus is used to unambiguously identify whether the referenced data is useable.
Now, observe the use of Write() in the above example. The purpose of this code segment is to write \50.0 to the set point of a RegCtl block.
As noted above, the CAB type has been designed to write with access level of Program. This means that MODE at the PID target must be Auto in order for SP stores to be accepted. To accomplish the MODE and SP write, MODEATTR must first be set to Program. If this is not done and done in the right order, then the target RegCtl block will ultimately reject the SP write. However, the example assumes the MODEATTR change must be temporary. Thus, MODEATTR must be returned to its original value after the write is complete.
The previous code accomplishes these objectives. MODEATTR is written twice-once to change into program mode attribute and once to return to its original value. The sequencing of writes to MODEATTR, MODE, and SP are such that the SP write will be accepted.
Note, however, that the code is somewhat verbose. Every PRef used for input requires a call to Read() and an access to Value. Every PRef used for output requires an access to Value and at least one call to Write. In fact, the style of coding shown above is not frequently used. "Parameter reference list class" describes a style of coding that requires fewer statements.
Be aware that the example above applies to cases where the CAB instance and the destination block for writes are in the same CEE. For considerations on communications between CAB and remote blocks, see Data access integrity.
15.6.5 WriteStatus
The following code segments illustrate two potential uses for WriteStatus. They attempt to set a CM's EXECSTATE to Active and then verify that the store went through. Here EXECSTATE is an Int32PRef.
EXECSTATE.Value = 1 EXECSTATE.Write() If EXECSTATE.WriteStatus <> CABAccStatusEnum.OK Then
' do error processing End If
The code segment above assumes that the value of WriteStatus is available for use immediately after the invocation of Write(). This would be true if the EXECSTATE reference pointed to a block within the same CEE as the CAB. If this constraint were always met, the above code would accomplish the intended purpose. However, if the program designer wanted to avoid this constraint, the program would have to be written differently.
To handle status collection for remote writes, the programmer must first realize that they can only be detected after sufficient time has passed for the write to be sent and for the status to be
- 370 -
Chapter 15 - CAB API reference
returned. Since CAB and VB.NET do not support preemption, the program would have to be written to detect write status in a later execution cycle. Furthermore, depending on the latency of the status return and on the period of the CAB, the status value may or may not be available by the first execution to follow the Write() invocation.
The following code segment illustrates the use of WriteStatus in a manner that is valid for both local and remote references. DoCheck and DoWrite are local Boolean state variables used to control the check and write actions.
If DoCheck Then If EXECSTATE.WriteStatus = CABAccStatusEnum.WritePending Then ' no status to check yet Else If EXECSTATE.WriteStatus <> CABAccStatusEnum.OK Then
' handle error Else ' write went through DoCheck = False End If
End If If DoWrite Then
DoWrite = False EXECSTATE.Value = 1 EXECSTATE.Write()
DoCheck = True End If
When status is collected after a parameter write operation, it may or may not be available immediately after the write. If the parameter is remote--that is, if it is owned by a block in an environment different from the one hosting the CAB program--then the write status is unknown until a subsequent CAB execution. For an example of using the Status property with output references, see Use of data access status in CAB.
15.6.6
Parameter reference list class
There is a single PRef list class whose purpose is to group predefined PRefs so that Read() and Write() operations may be commanded in bulk. Parameter References are allowed to be loaded with a NULL reference. When a read or write operation is commanded, only "non-NULL"PRefs will be read or written.
15.6.7
PRef writes to C200, C200E or C300
The maximum number of PRef writes that a C200, C200E, or C300 controller can accept is 50 parameters-per-second (see "Limitations on PRef writes to C200, C200E, or C300").
Table 15.10 Parameter Reference List Class Class name
PRefListClass
Class PRefListClass is never used to explicitly declare variables within CAB programs and is not exposed within the CAB API. Instead, it is used implicitly by virtue of the predefined object in BlockBase called "PRefList." Members of PRefListClass are described in the following table.
- 371 -
Chapter 15 - CAB API reference
Table 15.11 Description of Members of Class PrefListClass
Member Declaration name
Description
Read()
Public Sub Read()
The Read() method of PRefListClass is typically called at the start of Execute() to fetch data into the Value property of each input or input/output PRef. Using Read() generally prevents the need to call the Read() subroutine for individual PRefs. However, the list Read() and individual Read() calls may both be used within the same subroutine. At the completion of the Read operation, the ReadStatus property for each PRef read will be updated to reflect the status of the Read. The list Read will only attempt to read parameter references that have been configured (non-NULL).
Write()
Public Sub Write()
The Write() method of PRefListClass is typically called at the end of Execute() to store data out of the Value properties of output and input/output PRefs. Using Write() generally prevents the need to call Write() subroutine for individual PRefs. However, the list Write() and individual Write() calls may be used within the same subroutine. A call to Write() does not cause write of all outgoing PRefs. Instead, it writes only those outgoing PRefs whose Value properties have been assigned at least once during the current execution cycle. If the Value property on an input PRef is set, the WriteStatus property for that PRef will be set to ConfigMis (Configuration Mismatch). This will not affect the overall PRefList.Write status (the WRITESTATUS parameter), which only reflects the overall status of output PRefs. Write() performs writes in an order that matches the order assignments were made to the Value properties during execution. At the completion of the Write operation, the WriteStatus property for each PRef written will be updated to reflect the status of the Write. The list Write will only attempt to write parameter references that have been configured (non-NULL). Only the "last" value set for a PRef will be written by the list Write. Multiple "PRef.Value = <value">" statements may be executed prior to the PrefList.Write(), but only the last value set for each PRef will be stored.
GetType Public
()
Function
GetType()
The GetType function comes with .Net. It will probably not be used by the general CAB programmer. It gets the System.Type of the current instance.
Init()
Public sub The Init() method should NOT be called by user code. This is an internal
Init()
method used to set up the list for all of the PRefs.
PRefListClass usage can be illustrated using a variant of the example from the "Write()" section. Note that it is still assumed here that the target PID block being written to is in the same CEE as the CAB instance.
PRefList.Read() If MODEATTR.ReadStatus <> OK Then
' handle error condition Else LocalModeAttr = MODEATTR.Value
'Program Mode Attribute is 2 MODEATTR.Value = 2 MODEATTR.Write()
' Auto Mode is 1 MODE.Value = 1 SP.Value = 50.0 MODEATTR.Value = LocalModeAttr End If PRefList.Write()
- 372 -
15.7
Chapter 15 - CAB API reference
In this example, PRefList is the single instance of PRefListClass that is predefined within BlockBase. The Read() call of the example from the section "Write()" has been replaced with a call to PRefList.Read(). Three of the four Write() calls have been replaced with a single call to PRefList.Write(). The Write() call after the first assignment to MODEATTR.Value is still required as MODEATTR is written twice within the same execution cycle. The order of assignments to MODEATTR.Value, MODE.Value, and SP.Value are faithfully preserved by PRefList.Write(). This example applies to cases where the CAB instance and the destination block for writes are in the same CEE. For considerations on communications between CAB and remote blocks, see "Data access integrity."
CABMath class
Four CABMath functions are available - Min, Max, Sum, and Avg. For examples of the usage of these functions, see Examples of CABMath functions usage.
15.7.1
Methods in the CABMath class
Min Methods, Max Methods, Sum Methods, and Avg Methods contain the declarations for the Min, Max, Sum, and Avg methods of the CABMath class. In the tables, "Logical Declaration" shows how the function would be logically used. "Actual Declaration" shows how the method is actually declared and how it would appear in IntelliSense.
For any CABMath function, if any value passed in is a NaN, the function returns a NaN.
15.7.2
Min Methods
Logical declaration
Table 15.12 Min Methods Actual declaration
Description
Public Function Min(value1 As Double, value2 as Double, ...) As Double
Public Shared Function Min(ByVal ParamArray values() As Double) As Double
Returns the smallest value found in all of the values specified.
Public Function Min(values() As Double) As Double
Public Shared Function Min(ByVal ParamArray values() As Double) As Double
Returns the smallest value found in all of the elements of the 1 dimensional array.
Public Function Min(values(,) As Double) As Double
Public Shared Function Min(ByVal values(,) As Double) As Double
Returns the smallest value found in all of the elements of the 2 dimensional array.
Public Function Min(value1 As Float64CDP, value2 as Float64CDP, ...) As Double
Public Shared Function Min(ByVal
When all of the parameters passed in
ParamArray values() As
are scalar parameters, this returns
Honeywell.CAB.BlockMap.Float64CDP) the smallest value found in all of the
As Double
CDP parameters specified. If any of
the CDP parameters are arrays, an
ArgumentException is thrown.
Public Function Min(value As Float64CDP) As
Public Shared Function Min(ByVal
When value is an array parameter
value As
(either a 1D or 2D), this returns the
Honeywell.CAB.BlockMap.Float64CDP)
- 373 -
Chapter 15 - CAB API reference
15.7.3 15.7.4
Logical declaration
Double
Actual declaration As Double
Description
smallest value found in all of the elements in the array. If it is not an array parameter, it just returns the value of the CDP.
Max Methods
Logical declaration
Table 15.13 Max Methods Actual declaration
Description
Public Function Max(value1 As Double, value2 as Double, ...) As Double
Public Shared Function Max(ByVal ParamArray values() As Double) As Double
Returns the largest value found in all of the values specified.
Public Function Max(values() As Double) As Double
Public Shared Function Max(ByVal ParamArray values() As Double) As Double
Returns the largest value found in all of the elements of the 1 dimensional array.
Public Function Max(values(,) As Double) As Double
Public Shared Function Max(ByVal values(,) As Double) As Double
Returns the largest value found in all of the elements of the 2 dimensional array.
Public Function Max(value1 As Float64CDP, value2 as Float64CDP, ...) As Double
Public Shared Function Max(ByVal
When all of the parameters passed in
ParamArray values() As
are scalar parameters, this returns
Honeywell.CAB.BlockMap.Float64CDP) the largest value found in all of the
As Double
CDP parameters specified. If any of
the CDP parameters are arrays, an
ArgumentException is thrown.
Public Function Max(value As Float64CDP) As Double
Public Shared Function Max(ByVal
When value is an array parameter
value As
(either a 1D or 2D), this returns the
Honeywell.CAB.BlockMap.Float64CDP) largest value found in all of the
As Double
elements in the array. If it is not an
array parameter, it just returns the
value of the CDP.
Sum Methods
Logical declaration
Table 15.14 Sum Methods Actual declaration
Description
Public Function Sum(value1 As Double, value2 as Double, ...) As Double
Public Shared Function Sum(ByVal ParamArray values() As Double) As Double
Returns the sum of all of the values specified.
Public Function Sum(values() As Double) As
Public Shared Function Sum(ByVal ParamArray values() As Double) As Double
Returns the sum of all of the elements of the 1 dimensional array.
- 374 -
Chapter 15 - CAB API reference
15.7.5 15.7.6
Logical declaration
Double
Actual declaration
Description
Public Function Sum(values(,) As Double) As Double
Public Shared Function Sum(ByVal values(,) As Double) As Double
Returns the sum of all of the elements of the 2 dimensional array.
Public Function Sum(value1 As Float64CDP, value2 as Float64CDP, ...) As Double
Public Shared Function Sum(ByVal When all of the parameters passed in
ParamArray values() As
are scalar parameters, this returns
Honeywell.CAB.BlockMap.Float64CDP) the sum of all of the CDP parameters
As Double
specified. If any of the CDP
parameters are arrays, an
ArgumentException is thrown.
Public Function Sum(value As Float64CDP) As Double
Public Shared Function Sum(ByVal When value is an array parameter
value As
(either a 1D or 2D), this returns the
Honeywell.CAB.BlockMap.Float64CDP) sum of all of the elements in the
As Double
array. If it is not an array parameter,
it just returns the value of the CDP.
Avg Methods
Logical declaration
Public Function Avg(value1 As Double, value2 as Double, ...) As Double
Table 15.15 Avg Methods Actual declaration
Description
Public Shared Function Avg(ByVal ParamArray values() As Double) As Double
Returns the average of all of the values specified.
Public Function Avg(values() As Double) As Double
Public Shared Function Avg(ByVal ParamArray values() As Double) As Double
Returns the average of all of the elements of the 1 dimensional array.
Public Function Avg(values(,) As Double) As Double
Public Shared Function Avg(ByVal values(,) As Double) As Double
Returns the average of all of the elements of the 2 dimensional array.
Public Function Avg(value1 As Float64CDP, value2 as Float64CDP, ...) As Double
Public Shared Function Avg(ByVal
When all of the parameters passed in
ParamArray values() As
are scalar parameters, this returns
Honeywell.CAB.BlockMap.Float64CDP) the average of all of the CDP
As Double
parameters specified. If any of the
CDP parameters are arrays, an
ArgumentException is thrown.
Public Function Avg(value As Float64CDP) As Double
Public Shared Function Avg(ByVal
When value is an array parameter
value As
(either a 1D or 2D), this returns the
Honeywell.CAB.BlockMap.Float64CDP) average of all of the elements in the
As Double
array. If it is not an array parameter,
it just returns the value of the CDP.
Examples of CABMath functions usage
The examples below show how the CABMath functions are used. Here it is assumed that three
- 375 -
Chapter 15 - CAB API reference
Float64CDPs, Flow1, Flow2, and Flow3, have been defined for the CAB Type using PDE and that MinFlow, MaxFlow, TotalFlow, and AverageFlow have been defined as double variables.
MinFlow = CABMath.Min(FLOW1, FLOW2, FLOW3) MaxFlow = CABMath.Max(FLOW1, FLOW2, FLOW3) TotalFlow = CABMath.Sum(FLOW1, FLOW2, FLOW3) AverageFlow = CABMath.Avg(FLOW1, FLOW2, FLOW3)
A Min and Max function also exists in the Microsoft Visual Studio Math class found under the System namespace of the .NET framework. However, these only take two parameters where the CABMath functions allow any number of parameters. Also, the System.Math functions do not allow the user to specify an array.
15.8 BlockBase
15.8.1 15.8.2
FDP classes
CAB infrastructure defines classes to make a subset of FDPs accessible from within the CAB program. They are never used to explicitly declare variables and are not exposed within the API. Instead, they are used implicitly by virtue of instances predefined in BlockBase. The following table lists these classes, which are inherited from CAB infrastructure.
Float64FDP
Table 15.16 Fixed Definition Parameter Classes Class name
StringFDP
CABCommandEnumFDP
CABReRefCommitEnumFDP
CABStateEnumFDP
CABReRefStateEnumFDP
BooleanFDP
Each FDP class is defined to have a single property called "Value." This property has the type implied by the name of the class and is used to read or write the value of the FDP.
The declaration of Value for class Float64FDP is shown in the following table. For all other classes, Value is declared with syntax that is equivalent except for data type.
Member name
Table 15.17 Declaration of Members for Class Float64FDP
Declaration
Description
Value
Public Property Value Allows access to value for the FDP. Depending on
() As Double
characteristics of the FDP, it may be view only.
Base class
Class "BlockBase" is the parent of class "CABlock" that establishes the algorithm definition for the CAB type. The only reference to BlockBase within a CAB program occurs in the declaration of class CAB. The CAB programmer uses BlockBase through the variables, properties, and subroutines that it defines and that are inherited by class CAB. Inherited content includes the following items:
- 376 -
Chapter 15 - CAB API reference
l Predefined CDP variables inherited from BlockBase are the internal expression of the custom parameter definitions established within PDE. Examples of predefined CDPs include TEMP1 and TEMP2 in CDP classes, and BADPVCOUNTand LASTPV in Read(), ReadStatus, and Value. See CAB and CDB Example Scenarios for more examples.
l Predefined PRef variables inherited from BlockBase are the internal expression of the reference definitions established within PDE. Examples of predefined PRefs include FLOW in Enumeration CABAccStatusEnum, PV in Read(), ReadStatus, and Value, MODEATTR, MODE, and SP in Write(), and EXECSTATE in WriteStatus. Other examples can be found in CAB and CDB Example Scenarios.
l Predefined PRef list - BlockBase defines an object called "PRefList" that is an instance of PRefListClass. See Parameter reference list class for a description.
l Predefined FDPs and subroutines - Your CAB inherits certain predefined items from BlockBase that provide access to your block information as maintained by the system. These items are:
o FDPs and the associated programming constructs to access them: PROGSTSDESC CABCOMMAND CABSTATE X_REFCOMMIT (Not supported in CAB/C300) X_REFSTATE (Not supported in CAB/C300) PERIOD PROCSPECEXEC (Not supported in CAB/C300)
o Three subroutines: Send(), Abort(). Wait()
o One Property: Restart
These items are described in the following topics.
15.8.3
PROGSTSDESC
PROGSTSDESC is an instance of StringFDP inherited from BlockBase. It is a string that holds up to 64 characters and maps directly into the PROGSTSDESC FDP of the CAB instance. In most cases, the Value property of PROGSTSDESC has read/write permission from a CAB program even though a read returns only what was written.
PROGSTSDESC can be used by the CAB algorithm to inform operators of errors detected during execution. It can be used alone or in combination with an exception condition that is generated intentionally by invoking the Abort() subroutine. This generates an event that is recorded in the event summary display and the event journal.
The CAB infrastructure never writes to PROGSTSDESC except to automatically clear it for the following conditions:
l On CAB instance load.
l When the parent CM transitions to Active.
l When CABSTATE transitions to Normal.
The following code example illustrates the use of PROGSTSDESC. This is an extension of the example given in Read(), ReadStatus, and Value. In the following example, PV is a parameter reference while LASTPV and BADPVCOUNT are CDPs.
If PV.ReadStatus = OK Then LASTPV.Value = PV.Value BADPVCOUNT.Value = 0
' use PV.Value ElseIf BADPVCOUNT.Value <= 3 Then BADPVCOUNT.Value = BADPVCOUNT.Value + 1
' use LASTPV.Value Else
' handle case of PV which has become unusable PROGSTSDESC.Value = "Bad PV: " + PV.ReadStatus.ToString Abort() End If
- 377 -
Chapter 15 - CAB API reference
15.8.4
In this example, the programmer has chosen to send out an event with the statement "Abort()." This causes the CAB instance to go into state Exception as soon as the Abort() subroutine is called. No further statements within the program are executed on the current execution cycle.
Before generating the event the programmer publishes the cause of the error by writing a description into PROGSTSDESC. To produce the error description, the programmer has used the "Bad PV: " string literal. The string literal is combined with the string representation of the current value of the parameter access status for the PV parameter reference. To convert the binary enumeration value into a string representation, the programmer has used the VB.NET "ToString" method.
In this example, the displayed value of PROGSTSDESC would vary depending on what kind of parameter access error had occurred. If the access status had been CommFail then PROGSTSDESC would take on the following value:
"Bad PV: CommFail"
CABCOMMAND
CABCOMMAND is an instance of CABCommandEnumFDP inherited from BlockBase. It allows the CAB to cause a transition in its own CABSTATE. The only value that can be written to CABCOMMAND is CABCommandEnum.Quit. The Value property of CABCOMMAND is write-only from a CAB program.
TIP
A CAB algorithm containing the statement "CABCOMMAND.Value = CABCommandEnum.Run" will compile, load, and run without errors, but the statement will have no effect.
The following code example illustrates how CABCOMMAND might be used. This example assumes that other code within the program detects conditions that warrant a shutdown of self. The need for shutdown is signaled within the program by setting the internal variable Shutdown to True.
If ShutDown Then CABCOMMAND.Value = CABCommandEnum.Quit End If
The action of the code above is different from that of the Abort() subroutine. Abort() causes immediate cessation of the current cycle of execution, immediately changing the CABSTATE to Exception. Setting CABCOMMAND to Quit allows all statements in the current cycle to complete and then causes CABSTATE to go to Dormant. When Abort() is called, the CAB program resumes execution on the next cycle. When CABCOMMAND is set to the value of Quit, the CAB program does not resume execution until commanded to do so by a human being or by another application.
15.8.5 CABSTATE
CABSTATE is an instance of CABStateEnumFDP inherited from BlockBase. Its type is CABStateEnum. It provides the current value of the CABSTATE FDP of the block. The Value property of CABSTATE is view only from a CAB program.
Although CABStateEnum has four possible values, only two can be seen using CABSTATE FDP-- CABStateEnum.Normal and CABStateEnum.Exception. For the other two states, the CAB program is never executing so it cannot observe these states through use of the CABSTATE FDP.
Circumstances under which it is useful for a program to read its own CABSTATE are probably rare. The following code example illustrates how CABSTATE might be used.
- 378 -
Chapter 15 - CAB API reference
If CABSTATE.Value = CABStateEnum.Exception Then ' We've entered an unexpected exception ... ' do special error processing
End If
Note that the CABSTATE FDP is used for examining the self state of a CAB instance. For examining the state of different CAB instances, a PRef must be used. When CABSTATE of other CAB instances is observed, it is possible for any of the four states to be seen.
15.8.6
X_REFCOMMIT
X_REFCOMMIT is not supported in CAB/C300. When read in CAB/C300, always returns zero.
X_REFCOMMIT is an instance of CABReRefCommitEnumFDP inherited from BlockBase. It allows program access to the parameter X_REFCOMMIT. It allows the CAB to set the COMMIT or CANCEL action. The only values that can be written to X_REFCOMMIT are CABReRefCommitEnum.COMMIT and CABReRefCommitEnum.CANCEL. The Value property of X_REFCOMMIT is write-only from a CAB program. The COMMIT and CANCEL commands can also be entered manually through the X_ REFCOMMIT parameter if it is displayed on the faceplate or a schematic.
The following code illustrates how X_REFCOMMIT might be used. This example assumes that other code within the program has stored new references to one or more PRefs. The need for setting the COMMIT is due to the re-ref mode being set to MANUAL.
X_REFCOMMIT.Value = CABReRefCommitEnum.COMMIT
15.8.7 X_REFSTATE
X_REFSTATE is not supported in CAB/C300. When read in CAB/C300, always returns zero. X_REFSTATE is an instance of CABReRefStateEnumFDP inherited from BlockBase. It provides the current value of the X_REFSTATE FDP to the CAB. The value property is read-only. The following code illustrates how X_REFSTATE might be used.
If X_REFSTATE.Value = CABReRefStateEnum.IDLE Then ' do something End If
15.8.8 PERIOD
PERIOD is an instance of Float64FDP inherited from BlockBase. It provides the value of the SCALEPERIOD parameter of the parent CM of the CAB instance. Units are seconds. The Value property of PERIOD is view only. This FDP does not exist as an external parameter on the block. It is only available to the user code. For information about the SCALEPERIOD parameter, refer to the topic "Initiating a process special request" in the Application Control Environment User Guide.
PERIOD appears like an FDP to the program but it is only available to the program and cannot be accessed from outside of the block.
Use of PERIOD is illustrated by the following example in which DelayCycles is assumed to be a block scope variable with units of CAB execution cycles. DelayCycles is computed at initialization time from a configuration parameter called DELAYMINS. DELAYMINS units are minutes.
If Restart <> None Then DelayCycles = DELAYMINS.Value * 60.0 / PERIOD.Value End If
- 379 -
Chapter 15 - CAB API reference
15.8.9 PROCSPECEXEC
PROCSPECEXEC is not supported in CAB/C300. When read in CAB/C300, always returns False.
PROCSPECEXEC is an instance of BooleanFDP inherited from BlockBase. It provides the current value of the BPS parameter of the CAB instance's parent CM. The Value property of PROCSPECEXEC is read/write from a CAB program even though writing this parameter has no effect on the block execution. It is intended only to provide information to the block about how it was started. PROCSPECEXEC can only be referenced in the CAB program. It cannot be viewed on the properties form, cannot be placed on the faceplate, and cannot be referenced by parameter reference or by connectors. It simply mirrors the parent CM's Block Process Special (BPS) parameter and is for use in the CAB program only.
PROCSPECEXEC appears like an FDP to the program but it is only available to the program and cannot be accessed from outside of the block.
PROCSPECEXEC returns True whenever the current execution of the CAB instance was caused by a process special request to the parent CM.
If PROCSPECEXEC.Value Then ' Do special processing End If
' Do normal processing
Note that the mnemonic for this restricted FDP is "PROCess SPECial EXECution."
15.8.10 Subroutine Send()
Subroutine Send() allows text to be sent to the operator message display. Messages appear in those consoles mapped to the area assigned to the parent CM of the CAB instance. Send() supports a single string argument that can be up to 132 characters long. Each string sent corresponds to one line in the message display. The signature of Send() is shown in the following table.
Member name
Table 15.18 Declaration of Subroutine Send() Declaration
Send()
Protected Sub Send(ByVal Message As String)
The single argument of Send() can be constructed using the inherent string conversion capabilities of VB.NET. In the example below, Send()is used to present a string literal and floatingpoint values. ReportPressValues is a local Boolean variable and the array Press is a block scope variable. The VB.NET line continuation character, "_," is used to put multiple floating point values on a single message line even though they do not conveniently fit into a single line of source code.
If ReportPressValues Then Me.Send("Pressure Array:") Send(Press(0).ToString + " " + Press(1).ToString + " " + Press(2).ToString _ + " " + Press(3).ToString + " " + Press(4).ToString) Send(Press(5).ToString + " " + Press(6).ToString + " " + Press(7).ToString _ + " " + Press(8).ToString + " " + Press(9).ToString) End If
Note that in the example above, two of the send statements have the syntax "Send()," but one has the syntax "Me.Send()." The name "Me" refers to the CAB class instance. Any members of the CAB instance can be referred to by their name directly or by the contstruct "Me.<member name>." The two different syntaxes are equivalent in terms of execution properties. The advantage of using Me.<member name> is that it causes the Visual Studio IntelliSense feature to display a list of all members of the CAB class right after the user types "Me." This prevents the need to remember all members inherited from BlockBase when coding.
- 380 -
Chapter 15 - CAB API reference
Message notifications issued with the Send() subroutine differ from alarms and other notifications in that they do not support automatic event recovery. It is unlikely but possible that under conditions of notification overload, one or more messages requested by a CAB program might not be sent. If this happens, an error message is sent after the notification communication channel clears. The text of the message is as follows:
"!! Message(s) lost due to notification overload !!"
Messages reported through the Send() API can be seen in the same Station displays as messages sent by the CEE message block. They are visible from the message summary display or from the event journal.
15.8.11
Subroutine Abort()
BlockBase supports a subroutine which allows the program to break the current cycle of execution. Calling Abort() when there is no surrounding Catch clause does the following: l Prevents any further instructions from executing in the current cycle. l Puts CABSTATE into Exception. l As with any Exception condition, reports an alarm if configured to do so. This is configurable on
the Alarms tab. l As with any Exception condition, execution of the block resumes on the next cycle.
Abort() is supported for programmer convenience. Almost the same effect could be achieved by calling the VB.NET Throw statement without an enclosing Catch statement. Abort() can be used if the progammer prefers not to throw exceptions explicitly. There are slight differences between Abort() and Throw in the way in which CAB FDPs reflect the Exception state. For example, parameter EXCPTNTYPE contains the following string after Abort() has been called:
"Honeywell.CAB.AbortException"
If a Throw is explicitly called the contents of EXCPTNTYPE are determined by the exception type used for the Throw.
The declaration of Abort() is shown in the following table.
Table 15.19 Declaration of Subroutine Abort()
Member name
Declaration
Abort()
Protected Sub Abort()
Use of Abort() is illustrated in the example of PROGSTSDESC.
15.8.12 Subroutine Wait()
This subroutine is used to wait a specified amount of time before resuming execution. The following tables show two ways this subroutine is declared.
Member name
Table 15.20 Declaration of Subroutine Wait() Declaration
Wait()
Public Sub Wait(ByVal MillisecondsToWait As Integer)
Wait()
Public Sub Wait(ByVal TimeToWait As TimeSpan)
Parameters
- 381 -
Chapter 15 - CAB API reference
Name
Table 15.21 Parameters for Subroutine Wait()
Mode
Description
MillisecondsToWait Input The number of milliseconds to wait.
TimeToWait
Input The amount of time to wait. This can be any combination of days, hours, minutes, seconds, and milliseconds.
Return value--None
Comments
l If the amount of time to wait is negative, an ArgumentOutOfRangeException will be thrown. l This subroutine can only be used in CABs defined for distributed execution mode. The function
limiter enforces this.
Examples
Wait(500)
This will cause the execution of the CAB to wait for 500 milliseconds (0.5 seconds) before continuing.
Wait(New TimeSpan(0, 0, 0, 2, 500))
This will cause the execution of the CAB to wait for 0 days, 0 hours, 0 minutes, 2 seconds, and 500 milliseconds before continuing (a total of 2.5 seconds).
15.8.13 Property Restart()
BlockBase supports the Restart property that allows code executing under the Execute() calling tree to detect whether one of a set of system events has occured. The set of events that can be detected is defined by the enumeration RestartEnum. The following table shows the declaration of Restart.
Member name
Table 15.22 Declaration of Property Restart() Declaration
Restart()
Public ReadOnly Property Restart As Honeywell.CAB.SysCommon.RestartEnum
The parentheses are optional as there are no variables to pass. Use of Restart is illustrated by the example of Enumeration RestartEnum. Further information can be found in Data initializations under Execute().
15.8.14
Property RRRestart
RRRestart stands for "Ram Retention Restart." It is a property of type Boolean. It returns "True" for the first cycle of execution following the re-power of a C300 in which RAM contents were retained across power down. The following table displays the declaration of property RRRestart.
Member name
Table 15.23 Declaration of Property RRRestart Declaration
RRRestart
Public ReadOnly Property RRRestart As Boolean
- 382 -
Chapter 15 - CAB API reference
RRRestart is rarely used. Most CAB programs in which restart initializations is required, the Restart API is used.
A common example concerns the restart that follows a Checkpoint Restore when the state of the CEE, as reflected in parameter CEESTATE, is changed from Idle to Run. The Operator can command this transition in one of two ways: either as a Cold Restart or a Warm Restart. When the transition occurs, all CAB instances which call Restart will see a non-None value on their first execution after the CEESTATE transition. A CAB instance might perform special initializations with code organized as follows.
Public Overrides Sub Execute() If Restart <> RestartEnum.None Then If Restart = RestartEnum.CEEColdStart Then ' Do special initializations for cold restart. ElseIf Restart = RestartEnum.CEEWarmStart Then ' Do special initializations for warm restart. Else ' Do nothing. This CAB type doesn't need special ' initializations except for CEEColdStart and ' CEEWarmStart. End If End If ' Do regular processing End Sub
As it happens, the very same code can be used to perform initializations following the RRR transition. C300 is designed such that when an RRR occurs, a CEE that transitions to run will always perform either a cold or a warm initialization. This means that a CAB program could use the code above to handle the RRR transition as well as the transition of CEE to Run.
RRRestat is used rarely but may optionally be used if it is necessary to perform a special initialization when cold start or warm start happens after a repower. In such a case, the code shown previously might be modified as follows.
: If Restart <> RestartEnum.None Then If RRRestart Then ' Treat RRR start up as a special case. Do ' those initializations here. End If If Restart = RestartEnum.CEEColdStart Then ' Do special initializations for cold restart. ElseIf Restart = RestartEnum.CEEWarmStart Then ' Do special initializations for warm restart. Else ' Do nothing. This CAB type doesn't need special ' initializations except for RRRestart, CEEColdStart ' and CEEWarmStart. End If End If :
RRRestart is not supported by CAB on ACE. It always return False when called in CAB types intended to run only on ACE.
15.9 History APIs
History access requires distributed mode execution, which is not supported in CAB/C300.
- 383 -
Chapter 15 - CAB API reference
Beginning with R300, a CAB/ACE program can access history data through the Experion PKSOPC HDA Server or the PHD OPC HDA Server using the OPC .NET API calls provided by the OPC Foundation. In addition, several wrapped methods are provided that can also be used to access history data. These are easier to use than the direct OPC .NET API, but do not allow as many options to the user.
In general for OPC History access, the OPC HDA .NET API constructs allowed will be everything except asynchronous calls, callbacks, playbacks, and any methods that change or update data on the server. The function limiter will prevent the use of any constructs that are not allowed (see Supported namespaces and classes).
15.9.1
Programming CAB to access history data
Table 134 outlines the general steps that are used to access history data.
To program a CAB to Access History Data
1. Create an instance of the OPC HDA server that you will use to access the history data. You do this by creating a new instance of the Opc.Hda.Server class by specifying the name of the OPC HDA (using either the ExperionHistoryServerName property or the PHDHistoryServerName property) and the host name the HDA server is located on.
2. Connect to the history server. You can do this in one of the following ways: l Use the ConnectToHDAServer wrapped method. l Use the Connect method on the OPC HDA Server. However, this is not recommended if connecting to an Experion or PHD HDA server since the use of the straight OPC .Net API method will go against the number of HDA servers you are licensed for.
3. Read the history data. This can be done either by using one of the wrapped methods provided or by using the OPC .Net API classes and methods.
4. Disconnect from the history server. You do this by using the Disconnect method on the OPC HDA Server, or this will occur automatically when the CM that contains the CAB is deleted from the controller.
TIP
As a good practice, you should use try-catch blocks around any OPC .NET API calls, or around the wrapped method calls, to catch any exception that the OPC .NET API calls may throw. Throwing exceptions is the mechanism that OPC uses to report serious errors. If a try-catch block is not used and an OPC .NET API call throws an exception, the CAB Infrastructure will catch the exception and the CAB will go into an exception state.
15.9.2
Summary of wrapped functionality properties and methods
Honeywell provides wrapped methods that can be used for history access. These methods are implemented using the OPC .NET API and provide higher-level, easier methods. These methods are in the History class found in the Honeywell.CAB.OPC namespace. The following tables provide an overview of the properties and methods available.
- 384 -
Chapter 15 - CAB API reference
15.9.3
Table 15.24 Properties Available in Wrapped Functionality
Property
Description
ExperionHistoryServerName The string value "HwHsc.OPCServer." This is the Name (ProgID) of the Experion PKSOPC HDA Server.
PHDHistoryServerName
The string value "OPC.PHDServerHDA.1." This is the Name (ProgID) of the PHD OPC HDA Server.
Table 15.25 Methods Available in Wrapped Functionality
Method
Description
ConnectToHDAServer (HDAServer), or, ConnectToHDAServer (HDAServer, Credentials)
Using either the default credentials or the credentials specified, connects to the HDA Server specified
GetHistory(HistoryServer, PointParameterName, BeginTime, EndTime, NumValues, Values, TimeStampArray, HistStatusArray, StatusArray) as Opc.ResultID
Returns arrays of the History Values along with their associated TimeStamps and two Statuses (one from the historian and one when the data was acquired) for the specified PointParameterName within the specified time interval. The method itself returns the overall status of the read.
GetAvgHistory(ServerName, PointParameterName, BeginTime, EndTime, SampleInterval, NumValues, Values, TimeStampArray, HistStatusArray, StatusArray, NumSamplesArray, MinArray, MaxArray) as Opc.ResultID
Returns arrays of the History Values along with their associated TimeStamps, two Statuses (one from the historian and one when the data was acquired), number of samples in each average, minimum value used in each average, and maximum value used in each average for the specified PointParameterName within the specified time interval. The method itself returns the overall status of the read.
The following table shows the underlying OPC.NET API constructs used by the wrapped methods.
Method
Table 15.26 Underlying OPC .NET Constructs Underlying OPC .NET API constructs
ConnectToHDAServer Opc.ConnectData, Opc.Hda.Server.Connect
GetHistory GetAvgHistory
Opc.ItemIdentifier, Opc.IdentifiedResults, Opc.Hda.ItemValueCollection, Opc.Hda.Server.CreateItems, Opc.Hda.Server.ReadRaw Opc.Hda.Server.ReleaseItems, Opc.Hda.Time
Average, Count, Minimum, and Maximum Aggregates, Opc.ItemIdentifier, Opc.IdentifiedResults, Opc.Hda.ItemValueCollection, Opc.Hda.Item, Opc.Hda.Server.CreateItems, Opc.Hda.Server.ReadProcessed Opc.Hda.Server.ReleaseItems, Opc.Hda.Time
ExperionHistoryServerName property
This string value, "HwHsc.OPCServer," is the name of the Experion PKSOPC HDA server (the ProgID).
- 385 -
Chapter 15 - CAB API reference
15.9.4
PHDHistoryServerName property
This string value, "OPC.PHDServerHDA.1," is the name of the PHD OPC HDA server (the ProgID).
15.9.5 ConnectToHDAServer method
Connects to the specified HDA Server using default credentials or specified credentials.
Public Sub ConnectToHDAServer ( ByVal HDAServer As Opc.Hda.Server) or Public Sub ConnectToHDAServer ( ByVal HDAServer As Opc.Hda.Server ByVal Credentials As System.Net.NetworkCredential)
Parameters
Name
Table 15.27 Parameters for the ConnectToHDAServer Method
Mode
Description
HDAServer input The HDA Server being connected to.
Credentials input The user name/password used when connecting to the HDA Server.
Return Value
If a problem occurs, an exception is thrown. Some exceptions that may occur are:
Table 15.28 Exceptions Thrown by ConnectToHDAServer
Exception
Description
System.Runtime.InteropServices. ExternalException
CoCreateInstanceEx: The RPC Server is unavailable. This indicates that the host name specified is completely unknown.
System.Runtime.InteropServices. ExternalException
CoCreateInstanceEx: Access is denied. The Experion PKSCDA-SP process on the ACE is not executing under mngr account. See Configuring for OPC history data access.
Opc.Connect.FailedException E_NETWORKERROR. Most likely causes are: l The host name specified was incorrect
l An invalid OPC HDA Server Name (Class ID)
l The Experion PKSCDA-SP process on the ACE is not executing under mngr account. See Configuring for OPC history data access.
l Mngr account is not set up properly on the server node and the ACE node. The passwords to the mngr account must be the same on both systems.)
System.InvalidCastException
Specific cast is not valid. The most probable cause is that you are trying to access history data from a PHD 20x system. One of the OPC components that was distributed with PHD 20x is not compatible with the OPC .Net API. You will need to update the OPC Core Components on the PHD node and reboot it. Contact TAC to get the latest version of the OPC Core Components. You can also get this error if the Honeywell.cab.opc.dll does not match the version of the OPCNetAPi dlls that you are referencing in your CAB type.
- 386 -
Chapter 15 - CAB API reference
Comments
Using this method will not go against the number of HDA servers the user is licensed for.
Example
Dim ExperionServer As Opc.Hda.Server ' ExperionServer previously set to an instance of an Experion Server Try History.ConnectToHDAServer(ExperionServer)
' additional code Catch ex As Exception
' error in connecting to the Experion Server End Try
15.9.6 GetHistory method
This method returns arrays of history values with their associated TimeStamps and two Statuses (one from the historian and one when the data was acquired) for the specified PointParameterName within the specified time interval. The method itself returns the overall status of the read.
Public Function GetHistory( ByVal HDAServer As Opc.Hda.Server, ByVal PointParameterName As String, ByVal BeginTime As DateTime, ByVal EndTime As DateTime, ByRef NumValues As Integer, ByRef Values() As Double, ByRef TimeStampArray() As DateTime, ByRef HistStatusArray() As Opc.Hda.Quality) ByRef StatusArray() As Opc.Da.Quality)
As Opc.ResultID
Parameters
Name
Table 15.29 Parameters for the GetHistory Method
Mode
Description
HDAServer
input The history server being accessed.
PointParameterName input
The full point.parmeter name whose history data will be read. For Experion PKSpoints, this is in a form similar to <Asset Name>.<CM Name>.<Point Name>.<Parameter Name>.
BeginTime
input The date/time in which the data retrieval will begin.
EndTime
input The date/time in which the data retrieval will end.
NumValues
input/ The number of history values returned. Before calling this method, the user can set the parameter to the maximum
output number of values to retrieve. To retrieve all values in this time interval, set this to 0.
Values()
output The array containing the history data values.
TimeStampArray() HistStatusArray StatusArray
output The array containing the corresponding time stamps associated with the returned history values.
output The array containing the corresponding quality associated with each value when it was retrieved from the historian database.
output The array containing the corresponding quality associated with each value when it was acquired from the data source.
- 387 -
Chapter 15 - CAB API reference
Return Value
An Opc.ResultID (which includes the OpcResultID.Hda or OpcResultID.Da) result code is returned that is the overall status of the history read. Some are listed in the following table.
Return Value S_OK
Table 15.30 Return Values for the GetHistory Method Description
Completed successfully.
S_NODATA
There is no data within the specified parameters.
S_MOREDATA
There is more data satisfying the query than was returned.
S_EXTRADATA
Additional data satisfying the query was found.
S_
Server only returns current values for the requested item attributes.
CURRENTVALUE
E_FAIL
Unspecified error.
E_
The supplied value for the attribute is not a correct data type.
INVALIDDATATYPE
E_
Point specified is not a valid point or the point is not being historized.
INVALIDHANDLE
E_MAXEXCEEDED The maximum number of values requested exceeds the server's limit.
E_OUTOFMEMORY Not enough memory--this can happen any time the server needs to allocate memory to complete the requested operation.
E_INVALIDARG
One or more parameter values are invalid. This is generally used in place of a more specific error where problems are expected to be unlikely or easy to identify (such as when there is only one parameter).
E_TIMEDOUT
Operation exceeded time limit.
The S_ statuses are success statuses while the E_ statuses are failed statuses. To generically check for success or failure, use the Succeeded or Failed methods, respectively, associated with the ResultID class (see the following example). If a serious problem occurs, an exception is thrown. The following table shows one exception that may occur:
Exception
Table 15.31 GetHistory Method Exception Example Description
Opc.ResultIDException E_FAIL. The most likely cause is that the CAB lost its connection to the OPC HDA server, but it does not know it. The solution is to reconnect to the OPC HDA server using the ConnectToHDAServer routine.
Opc.ResultIDException
E_FAIL. The COM server does not support the interface OpcRcw.Hda.IOPCHDA_Server. The Connect method on the server was used and you have exceeded the number of Experion PKSOPC HDA connections you are licensed for. Always use the ConnectToHDAServer routine since this will not count against your license.
Comments
The use of the BeginTime, EndTime, and NumValues provides much flexibility. Only two of these three parameters need to be specified. As noted above, if the NumValues is 0, all values in the time interval specified will be returned. If the BeginTime and numValues are specified, the number of values specified starting at the BeginTime will be returned. Similar behavior occurs when the EndTime and numValues are specified. If the EndTime is less than the BeginTime, the values are
- 388 -
Chapter 15 - CAB API reference
returned in reverse order. A value falling at the EndTime is not included so requests made for successive, contiguous time requests will include every value in the archive exactly once. The BeginTime and EndTime can be set to absolute date/time values, or you can use the methods provided by the DateTime class to set these parameters to relative date/time values (see example).
In R210, the Experion PKSOPC HDA Server provides history data to an OPC client at the standard history rate (if configured for standard history). In R300, the Experion PKSOPC HDA Server returns data at the fastest rate configured. If there is insufficient history data at the fastest rate configured to meet the request, the OPC HDA Server will move onto the next fastest rate to meet the request, and so on.
The number of history items that can be returned with one call is limited. The MaxReturnValues property that can be accessed from the GetStatus method from the HDA Server object contains this value. Using the following coding example, ExperionServer.GetStatus.MaxReturnValues will contain the maximum number of values that an Experion OPC HDA server will return. For R300, this is 100. See Reading history for an extended period" for an example of how to code around these limitations.
Example
Dim ExperionServer As Opc.Hda.Server Dim PointParameter As String Dim StartingTime As DateTime Dim EndingTime As DateTime Dim ValueCount As Integer = 0 Dim HistoryValues() As Double Dim TimeStamps() As DateTime Dim HistStatuses() As Opc.Da.Quality Dim Statuses() As Opc.Hda.Quality Dim OverallSts As Opc.ResultID ' ExperionServer previously connected to an Experion Server PointParameter = "ASSET_105.PIDLOOP.PIDA.PV"StartingTime = DateTime.UtcNow ' the current time EndingTime = StartingTime.AddHours(-1) ' 1 hour ago OverallSts = History.GetHistory(ExperionServer, PointParameter, StartingTime, EndingTime, ValueCount, HistoryValues, TimeStamps, HistStatuses, Statuses) If OverallSts.Failed Then ' problem reading history data PROGSTSDESC.Value = OverallSts.ToString Else
' additional code End If ' additional code
15.9.7 GetAvgHistory method
This method returns arrays of the history values along with their associated TimeStamps, two Statuses (one from the historian and one when the data was acquired), number of samples in each average, the minimum value used in each average, and maximum value used in each average, for the specified PointParameterName within the specified time interval. The method itself returns the overall status of the read.
Example
Public Function GetAvgHistory( ByVal HDAServer As Opc.Hda.Server, ByVal PointParameterName As String, ByVal BeginTime As DateTime, ByVal EndTime As DateTime, ByVal SampleInterval As TimeSpan, ByRef NumValues As Integer, ByRef Values() As Double,
- 389 -
Chapter 15 - CAB API reference
ByRef TimeStampArray() As DateTime, ByRef HistStatusArray() As Opc.Hda.Quality, ByRef StatusArray() As Opc.Da.Quality, ByRef NumSamplesArray() As Integer, ByRef MinArray() As Double, ByRef MaxArray() As Double) As Opc.ResultID
Parameters
Name HDAServer
Table 15.32 Parameters for the GetAvgHistory Method
Mode
Description
input The history server being accessed.
PointParameterName input
The full point.parmeter name whose history data will be read. For Experion PKSpoints, this is in a form similar to <Asset Name>.<CM Name>.<Point Name>.<Parameter Name>.
BeginTime
input The date/time in which the data retrieval will begin.
EndTime
input The date/time in which the data retrieval will end.
SampleInterval
input The amount of time that is included in each average (for example, 1 hour, 1 day, and so forth).
NumValues
output The number of history values returned.
Values()
output The array containing the average history data values.
TimeStampArray() HistStatusArray() StatusArray() NumSamplesArray() MinArray() MaxArray()
output The array containing the corresponding time stamp associated with the returned average values.
output The array containing the corresponding quality associated with each value when it was acquired from the data source.
output The array containing the corresponding quality associated with each value when it was acquired from the data source.
output The array containing the number of samples associated with each average value.
output The array containing the minimum value associated with each average value.
output The array containing the maximum value associated with each average value.
Return Value
An Opc.ResultID (which includes the OpcResultID.Hda or OpcResultID.Da) result code is returned that is the overall status of the history read. Some are listed in the following table.
Return Value S_OK
Table 15.33 Return Values for the GetAvgHistory Method Description
Completed successfully.
S_NODATA
There is no data within the specified parameters.
S_MOREDATA
There is more data satisfying the query than was returned.
- 390 -
Chapter 15 - CAB API reference
Return Value S_EXTRADATA
Description Additional data satisfying the query was found.
S_CURRENTVALUE Server only returns current values for the requested item attributes.
E_FAIL
Unspecified error.
E_
The supplied value for the attribute is not a correct data type.
INVALIDDATATYPE
E_MAXEXCEEDED The maximum number of values requested exceeds the server's limit.
E_OUTOFMEMORY Not enough memory--this can happen any time the server needs to allocate memory to complete the requested operation.
E_INVALIDARG
One or more parameter values are invalid. This is generally used in place of a more specific error where problems are expected to be unlikely or easy to identify (such as when there is only one parameter).
E_TIMEDOUT
Operation exceeded time limit.
E_
This indicates that the Average aggregate is not implemented in the OPC
INVALIDAGGREGATE HDA Server being accessed.
The S_ statuses are success statuses while the E_ statuses are failed statuses. To generically check for success or failure, use the Succeeded or Failed methods, respectively, associated with the ResultID class (see example below).
Comments
This method uses the Average, Count (to get the number of samples), Minimum, and Maximum aggregates. If the Average aggregate is not implemented in the OPC HDA Server being accessed, all returned arrays will be 0 length arrays and an E_INVALIDAGGREGATE status will be returned. If the Average aggregate is implemented, the status returned is based on the access of the Average data. For the other aggregates being used (Count, Minimum, and Maximum), for each that is not implemented, a 0 length array will be returned for that array of values.
If the EndTime is less than the BeginTime, the values are returned in reverse order. The BeginTime and EndTime can be set to absolute date/time values or the user can use the methods provided by the DateTime class to set these parameters to relative date/time values (see example).
The number of history items that can be returned with one call is limited. The MaxReturnValues property that can be accessed from the GetStatus method from the HDA Server object contains this value. Using the following coding example, ExperionServer.GetStatus.MaxReturnValues will contain the maximum number of values that an Experion OPC HDA server will return. For R300, this is 100. See Reading history for an extended period" for an example of how to code around these limitations.
Example
Dim ExperionServer As Opc.Hda.Server Dim PointParameter As String Dim StartingOffset As DateTime Dim EndingOffset As DateTime Dim HourInterval As New TimeSpan(1, 0, 0) ' 1 hour interval Dim OverallSts As Opc.ResultID Dim ValueCount As Integer = 0 Dim HistoryValues() As Double Dim TimeStamps() As DateTime Dim HistStatuses() As Opc.Hda.Quality Dim Statuses() As Opc.Da.Quality Dim NumberSamples() As Integer Dim MinValues() As Double
- 391 -
Chapter 15 - CAB API reference
Dim MaxValues() As Double ' ExperionServer previously connected to an Experion Server PointParameter = "ASSET_105.PIDLOOP.PIDA.PV"StartingOffset = DateTime.UtcNow.Today.AddDays(-1) ' Yesterday EndingOffset = StartingOffset.AddDays(-7) ' One week ago yesterday 'Reading hourly averages from the last 7 days starting yesterday OverallSts = History.GetAvgHistory(ExperionServer, PointParameter, StartingOffset, EndingOffset, HourInterval, ValueCount, HistoryValues, TimeStamps, HistStatuses, Statuses, NumberSamples, MinValues, MaxValues) If OverallSts.Failed Then
' problem reading history data PROGSTSDESC.Value = OverallSts.ToString Else
' additional code End If
' additional code
15.9.8
OPC functionality
OPC functionality can be used directly without using wrapped functions. The function limiter will allow the user to use certain OPC .NET API constructs to access history data. For the constructs that are allowed by the function limiter, see Supported namespaces and classes. Note that the OPC HDA server being accessed may not support all of these functions.
15.9.9
Example scenarios for reading history
The scenarios section of this guide includes the following examples for reading history: l Reading history values using wrapped methods l Reading history values using only the OPC .Net API l Reading average history values using wrapped methods l Reading average history values using the OPC .Net API l Reading history for an extended period
If Opc.Hda.Server.CreateItems is called during each execution of the CAB, make sure you also call Opc.Hda.Server.ReleaseItems. If this is not done, a memory leak may occur.
Example
Dim HistItemID(0) As Opc.ItemIdentifier Dim HistIDResults() As Opc.IdentifiedResult ' Additional Code ' Set the History ItemID HistItemID(0)= New Opc.ItemIdentifier("ASSET_105.PIDLOOP.PIDA.PV") ' then create this Item ID to be used in the history access HistIDResults = ExperionServer.CreateItems(HistItemID) ' Additional Code ' Release the handle to the Item ID that was created If Not HistIDResults Is Nothing Then
ExperionServer.ReleaseItems(HistIDResults) End If
15.10 VB.NET APIs
Many of the functionalities essential for CAB are built into VB.NET. Functionalities specific to VB.NET are not described here.
- 392 -
Chapter 15 - CAB API reference
Some .NET constructs often used in CAB applications are as follows. l System Namespace l System.Math Class l System.Double Structure l System.String Class l System.DateTime Structure l System TimeSpan Structure
These and other .NET APIs are described in the Visual Studio 2017 documentation.
15.10.1
Private and public access types In CAB programs
VB.NET is used in CAB types in a way that specifically supports CEE control block applications in CEE. Thus, using VB.NET in CAB is somewhat different from using VB.NET for a general-purpose application on a PC platform. Some key points are:
l Exactly one subroutine defined in a CAB type is known to CEE--the Execute() subroutine.
l The declaration of Execute() is established in an automatically generated code frame when a CAB type is first created. This declaration should not be altered.
l Execute() is always declared with the VB.NET access type Public. This is required in order for CEE to access these subroutines.
l Aside from Execute(), subroutines and functions declared internal to a CAB type are always private. This is true regardless of whether they are declared with access type Private, access type Public or with no explicit access type at all. Within CEE one CAB type cannot call the subroutines or functions defined by another. It is recommended that CAB subroutines always be declared with access type Private to make the code self-documenting.
l Class variables (block scope variables) are always private within CAB. Regardless of whether they are declared with access type Private, access type Public, or with no explicit access type, they can only be used by the CAB instance that owns them.
l CDPs declared for a CAB type using PDE are effectively public. But they are not made public through the same mechanism as a Public class variable in VB.NET. The mechanism depends on CEE services and allows the CDP to be visible beyond the hardware platform that hosts the CAB instance. For one CAB instance to access the CDPs of another CAB instance or of a native block instance, PRefs must be used. This cannot be done through inherent data reference capabilities of VB.NET.
- 393 -
CHAPTER
16
GLOSSARY OF TERMS AND ACRONYMS
16.1
This section contains a collection of special terms and acronyms used in this guide.
Special terms and acronyms
16.1.1
.NET
Next generation integrated software platform for distributed computing offered by Microsoft. CAB builds its functionality on programming language capabilities that are part of the .NET suite of functionalities.
16.1.2
.NET CLR
.NET Common Language Run time. A set of language services which make it possible for .NET programs to run on a target platform.
16.1.3
ACE
Application Control Environment
16.1.4
Aggregate types
Data types that describe non-scalar values. Within this document, classes, structures, arrays and strings are all considered to be aggregate types.
16.1.5
AICHANNEL
One type of IO block supported within CEE.
16.1.6
AND
Definition
Logical operator.
- 394 -
Chapter 16 - Glossary of terms and acronyms
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
See "LOGICAL." Visual Basic Boolean operator. See "LOGICAL." R210
16.1.7
API
Application Programming Interface
16.1.8
Basic block
Blocks that can exist only as dependent blocks within container blocks. Basic blocks have dependent names. That is, their names are not unique within the PKS name space until qualified by the name of their parent container block. CABs and CDBs are always basic blocks.
16.1.9
Black box debugging
A form of program debugging in which the programmer does not have visibility into the internals of code execution. Instead, he or she must rely on externally visible data. The programmer must make deductions about what the code is doing based on external data.
16.1.10
Block instance
A single copy or instance of a block type. Holds a unique set of data values that can specify the properties of a block type. See block type and block template.
16.1.11
Block template
A concept of block that incorporates some qualities of block type and some qualities of block instances. A template is like a type in that it can serve as the pattern from which one or more instances are created. It is like an instance in that one template can be copied to make another. A template can serve as the master for changes to parameters that propagate to all derived instances. Like an instance, a template is always dependent on an independently defined block type. See also the definitions for block type and block instance.
16.1.12 Block type
A universal definition of block data set and or block algorithm that can be physically realized in multiple different copies or instances. See also Block Instance and Block Template.
- 395 -
Chapter 16 - Glossary of terms and acronyms
16.1.13
Build a program
The operation of compiling and linking a CAB program is often referred to within this document as "building" it.
16.1.14 C200, C200E, C300
Experion PKSsystem Process Controllers.
16.1.15 CAB
Custom Algorithm Block
16.1.16
CAB algorithm
The control computation of a CAB. The algorithm is to be distinguished from the data definition of the block. The algorithm is expressed within the CAB program.
16.1.17 CAB/ACE
A set of Experion PKSenablers for creating and running custom programs. The programs are fashioned as types each of which can be instantiated as multiple instances. In addition to an algorithm expressed as a program, each CAB type defines a set of custom parameters for publishing internal data and a set of parameter references for referencing external data. The CAB/ACE enablers consist of a build-time used to create CAB types and a run-time capable of hosting the types on the ACE soft controller. CAB/ACE was the first set of enablers supported within Experion.
16.1.18 CAB/C300
A set of Experion PKSenablers for creating and running custom programs. The programs are fashioned as types each of which can be instantiated as multiple instances in a manner equivalent to that of CAB/ACE programs. In addition to a custom algorithm expressed as a program, each CAB/C300 type defines a set of custom parameters and a set of parameter references in a manner equivalent to CAB/ACE. The CAB/C300 enablers consist of a build-time used to create CAB types and a run-time capable of hosting the types on the C300 embedded controller. CAB/C300 was delivered in a release that followed CAB/ACE, augmenting its capabilities. A single build-time supports both CAB/ACE and CAB/C300 while the run-time enablers are separate.
16.1.19
CAB program
The programming language description of the CAB algorithm written in VB.NET. While the algorithm is defined with the CAB program, the public, persistent data of a CAB is defined as a set of CDPs through the use of PDE. CDP definitions established by PDE are known to the CAB Program but are not explicitly declared within the CAB program.
- 396 -
Chapter 16 - Glossary of terms and acronyms
16.1.20
CB
Control Builder
16.1.21 CDB
Custom Data Block
16.1.22 CDP
Custom Definition Parameter
16.1.23
CDS
Custom Data Segment
16.1.24 CE
Control Engineer
16.1.25 CEE
Control Execution Environment
16.1.26
Change Parent
Within Control Builder this operation changes a block from one template to another or from one type to another. In the case of CAB, Change Parent causes an instance of one CAB type to be converted into an instance of another CAB type. The "Change Parent" operation was formerly called the "Convert" operation.
16.1.27 CM
Control Module
16.1.28 Configuration of block instances
This document maintains a distinction between the activity of "configuring" the instance of a block and "creating" or "modifying"the type definition of a block. In the context of native blocks, the type definition cannot be changed so there is no ambiguity about what "configuration" might mean. In the context of custom blocks the activity of creating a block type is very different from the activity of configuring a block instance. This document uses the term "configure" when referring to the assignment of data values to a block instance.
- 397 -
Chapter 16 - Glossary of terms and acronyms
16.1.29
Component block
Within CEE, a component block is a block contained in a container block. Component blocks are usually Basic Blocks, though within Experion, CMs can be components of other CMs.
16.1.30 Connections
See "Graphical connections."
16.1.31 Container Block
Within the CEE architecture a container block is one capable of holding other blocks. There are two types of container blocks: SCMs and CMs. SCMs are inherently single-level. Their component blocks can only be basic blocks. In Experion, CMs can be multi-level. They can hold basic blocks as components but they can also hold other CMs. Container blocks have independent names (tag names). Some people prefer to think of container blocks as "modules."
16.1.32
Control Builder
The Experion PKSgraphical development tool used for creating control strategies to run on CEE and other Experion PKSrun-time environments. CB can launch the MS Visual Studio for the creation and maintenance of CAB types.
16.1.33 Control Module
A container block that supports execution of continuous algorithm blocks. In Experion, It also supports containment hierarchies by being able to contain other Control Modules. CAB and CDBs are always contained in CMs.
16.1.34 Convert
In the context of block types and block instances this term refers to a configuration operation supported by CB. It allows an instance of one block type to be converted into an instance of another block type. Renamed "Change Parent" - see Change Parent definition above.
16.1.35
Custom Data Block
A block for which the Control Engineer provides the definition. CDBs are similar to CABs except that they have no program. They have only data, defined within custom data parameters.
16.1.36 Custom Definition Parameter
A parameter defined by an end user as part of the definition of a CAB type. CDPs allow CAB instances to publish their internal data for read or write access by the rest of the DCS.
- 398 -
Chapter 16 - Glossary of terms and acronyms
16.1.37
Custom Data Segment
A CDS, represented as a parameter group in TPS Builder, which is equivalent to a Custom Data Block in an Experion system.
16.1.38 DATAACQ
A signal conditioning and alarm block supported within CEE.
16.1.39 Data owner principle
A principle sometimes used in object oriented programming. The data owner is the agent that owns the data. His ability to modify the data is unrestricted. Distinct from the data owner are agents that may want to modify the data but do not own it. Writes from external agents are subject to validity checks by the data owner before being accepted. In CAB, the instance is considered the data owner of all CDPs. Writes by the CAB program to its own CDPs is unrestricted. Writes from external agents are subject to automatic validity checks that are determined by attributes that define the CDPs.
16.1.40
DLL
Dynamic Link Library
16.1.41 ECMA
European Computer Manufacturer's Association-- An electronics trade organization that has published a standard for .NET functionalities. The ECMA .NET standard comprises a subset of the MS .NET framework.
16.1.42 Edit Lock
A string parameter associated with all CAB and CDB types. When blank, it indicates that the type is available for edit. When non-blank it contains the machine name and user name of the person who is editing the type. Edit Lock is automatically set when an edit session starts and automatically cleared when the session ends. A type may be opened for viewing when it is already open but it cannot be saved to ERDB. The value of Edit Lock can be viewed for a block type by opening the form from the library tree.
16.1.43
EE
Execution Environment
16.1.44 ERDB
Engineering Repository Database
- 399 -
16.1.45
EU
Engineering Unit
Chapter 16 - Glossary of terms and acronyms
16.1.46 EULA
End User License Agreement
16.1.47 European Computer Manufacturer's Association
An electronics trade organization which has published a standard for .NET functionalities. The ECMA .NET standard comprises a subset of the MS .NET framework.
16.1.48
Exception handler
A programming construct provided in modern programming languages such as VB.NET. Exception handlers allow error conditions to be detected and forwarded to the software agent designed to respond. Error handling can be coded more concisely with Exception handlers than through the traditional technique of passing error status up through a calling tree. Exception handling is expressed through the use of "Try," "Catch,"and "Finally" clauses in VB.NET. Within CAB programs, Exception handlers can be used at the discretion of the CE. When not used, run-time exceptions (for example, integer-divide-by-zero exception) are caught by CAB system services, which terminate current execution and resume it on the next cycle.
16.1.49 FDP
Fixed definition parameter
16.1.50 Fixed Definition Parameter
A parameter of a CAB type which is common to all CAB types and is defined by Honeywell. Most FDPs support internal infrastructure and are never seen by end users. Some FDPs are exposed to end users to publish information about the state of a CAB instance or to allow certain characteristics of CAB types to be controlled by block designers.
16.1.51
GPL
GNU Public License
16.1.52 Graphical connections
Connections used to interconnect parameters. Wire connections are used within a CM between pins exposed on blocks. Parameter connections are used between blocks in different CMs, (although they can also be used within the same CM). Parameter connections are implemented using symbol pins that are also exposed on the blocks.
- 400 -
Chapter 16 - Glossary of terms and acronyms
16.1.53
GUID
Globally Unique Identifier. This identifier is generated in such a way that it will not reoccur on any other PC. In CAB, it is stored in the BLOCKTYPEID parameter and appears on the source code tab in Microsoft Visual Studio. A new GUID is generated on each build.
16.1.54 HON
Honeywell
16.1.55 ICG
Inter Cluster Gateway. This block acts as a means of communication between Experion PKSclusters. It makes CDA data from one Experion PKScluster available to the other Experion PKScluster. It can act as the client to the corresponding block in the other Experion PKScluster.
16.1.56
IDE
Integrated Development Environment
16.1.57 IEEE 754
Prevalent standard for floating point arithmetic in computing.
16.1.58 Incomplete Lock
A flag parameter associated with all CAB types. When On it indicates that the parameter definitions and algorithm definition of the type have not been rebuilt since changes were made. The act of rebuilding clears the lock. A CAB type can be instantiated when the Incomplete Lock is set, but it cannot be loaded.
16.1.59
INF
+INF and -INF are bit patterns in IEEE 754 that represent respectively positive and negative infinity. Any magnitudes that are too large to not be represented within the defined range of the floating-point number are represented instead as +INF or -INF.
16.1.60 I/O
Input/Output
16.1.61 Long Term Heap
Heap memory in which allocations persist for indefinitely long periods of time. In CAB/ACE, all
- 401 -
Chapter 16 - Glossary of terms and acronyms
allocations created with the VB.NET "New" operator go to long term heap. In CAB/C300 allocations created with "New" do not go to Long Term Heap but got to Short Term Heap instead.
16.1.62 LTH
Long Term Heap
16.1.63 Monitor Side Instance
Every block instance within ERDB can have two distinct copies: the monitor side instance and the project side instance. The monitor side instance corresponds to data within the ERDB but also maps directly to the run-time data within the execution environment and within the Experion server. This is the copy that is viewed when the block is live and operative within the system.
16.1.64
MSVS
Microsoft Visual Studio.
16.1.65 NaN
Not A Number. A set of bit patterns in IEEE 754 numbers that are not part of the defined, ordinal numerical range. They can be used to represent alternative data states such as "bad data."
16.1.66 Native blocks
Blocks whose type cannot be created or modified by application engineers who use the Experion PKSsystem. Examples include PID, Device Control and Data Acquisition.
16.1.67
OLE
Object Linking and Embedding
16.1.68 OPC
OLE for Process Control
16.1.69 OPC Gateway
An Experion PKSsubsystem and allied capabilities that allows CEE blocks that can communicate through Control Data Access (CDA) to achieve parameter access to OPC servers. When acting as clients of the OPC Gateway, CEE blocks do not act as direct OPC clients themselves. Instead, they rely on CDA and the OPC Gateway to serve as translation agents in answering their access requests. . The ACE soft controller can communicate through the OPC Gateway but the C300 embedded controller cannot
- 402 -
Chapter 16 - Glossary of terms and acronyms
16.1.70
Operator Training Simulation
Simulation of a process and control system done with the objective of training operators who will run the process. CAB/C300 design helps to enable OTS systems which use the SIM-C300 controller simulator product. CAB/C300 types and instances can operate within a SIM-C300 in a manner analogous to their operation within a C300.
16.1.71 OPM
On-Process Migration
16.1.72 OS
Operating System
16.1.73
OTS
Operator Training Simulation
16.1.74 Parameter Definition Editor
A GUI tool used for creating and assigning attributes of custom data parameters. For CAB types, the Parameter Definition Editor is used within MS Visual Studio 2017. For CDB types it is used directly within Control Builder.
16.1.75 Parameter reference
A label for an externally accessible parameter that is used within the VB.NET program of a CAB type for reading or writing data external to the CAB instance.
16.1.76
PDE
Parameter Definition Editor
16.1.77 PKS
Process Knowledge System
16.1.78 PRef
Parameter reference
- 403 -
Chapter 16 - Glossary of terms and acronyms
16.1.79
Project side instance
Every block instance within ERDB can have two distinct copies: the monitor side instance and the project side instance. The project side instance corresponds to the one that is under edit and has not yet been deployed within the run-time system. It is stored exclusively within ERDB.
16.1.80 Redundancy Transfer Count
Total byte count of data and address information transferred in a cycle from primary to secondary to maintain synchronization of a redundant controller pair. Redundancy Transfer Count (RTC) is visible through the run-time instrumentation parameter, RCNCNTCYCMAX, of the monitoring form of the CEE-C300 block.
16.1.81 RTC
Redundancy Transfer Count
16.1.82
SCM
Sequence Control Module
16.1.83 SCO
Strategy Check Out
16.1.84 Sequence Control Module
A container block that supports execution of blocks specifically designed to support sequence control. SCMs support a limited number of components blocks: Handlers, Transitions and Steps. SCMs support only a single level of containment.
16.1.85
Short Term Heap
Heap memory in which allocations persist only as long as the CAB instance is being executed. In CAB/ACE, there is no Short Term Heap and all memory allocations created with the VB.NET "New" operator go to Long Term Heap. In CAB/C300, any allocations created with the VB.NET "New" operator go to the Short Term Heap and last only as long as the current execution cycle.
16.1.86 SIM-ACE
Simulation environment for the ACE supervisory controller. SIM-ACE cannot be used for onprocess control. It is the intended platform for CAB source level debugging in which break point activity can disrupt the main execution thread.
- 404 -
Chapter 16 - Glossary of terms and acronyms
16.1.87
SIM-C200E
Simulation environment for the C200E controller.
16.1.88 SIM-C300
Simulation environment for the C300 controller.
16.1.89 Source Level Debug
The act of debugging a program such as a VB.NET program that implements a CAB type, using a tool that allows program execution to be halted with break points inserted in the source code and that allows program data state to be examined while halted, from the context of the source code. Source level debugging for CAB/C300 block types is supported on the SIM-ACE controller simulator but not on the SIM-C300 controller simulator.
16.1.90
SR
System Repository
16.1.91 STH
Short Term Heap
16.1.92 Strategy Check Out
The operation of qualifying a control strategy or group of interacting control strategies before deploying them for on-process control. SCO is often performed with the use of a controller simulator such as SIM-C300. CAB/C300 supports strategy check out operations when running on a SIM-C300.
16.1.93
System Repository
The runtime Cache Service that act as the common operational Database for all ECI subsystems, adding a persistent store for ECI sub system points. SR provides look up and data conversions services to its clients..
16.1.94 System template
Block profile
16.1.95 Template
Block template
- 405 -
16.1.96
UI
User Interface
Chapter 16 - Glossary of terms and acronyms
16.1.97 User template
Block template
16.1.98 VB-Only
Some constructs of the VB.NET programming language require support that is not part of the general functionality of ECMA.NET. VB-Only functionalities are always associated with classes or functions that are part of the name space Microsoft.VisualBasic or one of its sub-namespaces. These language constructs can be used in CAB/ACE but not CAB/C300. There is always an alternative way to accomplish the same task using inherent ECMA.NET capabilities that does not depend on VB-Only constructs.
- 406 -
CHAPTER
17
APPENDIX A: CL/AM TO CAB MAPPING TABLES-
IDENTIFIERS
17.1
The following tables map between CL/AM functionality and equivalent CAB functionality. The mapping uses CL/AM as a base, using a table of CL/AM Identifiers and a table of CL/AM Reserved Words to construct the mapping. Following the tables is a discussion about CL/AM background processing and CAB distributed processing.
This mapping is not intended to be an absolute guide, directing an automatic translation from CL/AM to CAB. It is intended to show, in general terms, that CAB functionality is a viable migration target for most CL/AM applications. However, some CL/AM applications might be best translated to native Experion PKScontroller functions, and some CL/AM applications might be best translated to Sequence Control Modules (SCMs).
ABS
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Built-in arithmetic function. Returns the absolute value of the argument. Abs(x), where the argument and the return are of type Number. Visual Basic Math.Abs method from the Math class library. m_shortBase = Math.Abs(shortbase) R210
17.2
ALLOW_BAD
Definition Allows the programmatic act of writing a NaN (that is, a bad value) to the targeted variable. The default settings for CL/AM are that NaNs are not valid values to store. This overrides the default setting.
How used in CL/AM
Allow_Bad (x, y) This subroutine stores the value of y into the numeric variable x. If x is a parameter of a data point and y is a bad value, the store proceeds without error. Note that if a SET statement had been used, an attempt to store a bad value into a parameter of a data point would constitute a run-time error; the store would not be completed and the program would abort.
CAB
There is no equivalent in CAB--none is necessary. Any CAB variable can receive a
equivalent NaN as a valid value.
- 407 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
How used N/A in CAB First seen N/A in this release Remarks See "BADVAL," "SET_BAD," "FINITE."
17.3
ATAN
Definition
Built-in arithmetic function. Returns the arc tangent of the argument. All angles are specified in radians.
How used in CL/AM
Atan(x) - where the argument and the return are of type Number.
CAB equivalent Visual Basic Math.Atan method from the Math class library.
How used in CAB radians = Math.Atan(result)
First seen in this R210 release
Remarks
17.4
AVG
Definition
Built-in arithmetic function. Returns the average value of the arguments, or the average value of the elements in an array.
How used in CL/AM
Avg (x, y, ...) -- average, where x, y, ... are arguments to be averaged Avg(x) -average, where x is an array to be averaged
CAB equivalent Visual Basic CABMath.Avg method from the CABMath class library.
How used in CAB
AverageFlow = CABMath.Avg(FLOW1, FLOW2, FLOW3)
First seen in this release
""""`
Remarks
See "CABMath class" in the CAB User's Guide for a full set of examples.
17.5
BACKGRND
Definition
Regulatory, Custom, or Switch insertion point name, used to attach a CL block for "background" execution. In CL, a CL block is inserted to a point at the BACKGRND insertion point in order to run in the "background," that is, to not be limited to execution within a cycle. The block must specify, in code, the BACKGRND insertion point.
- 408 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
How used BLOCK abc (GENERIC; AT BACKGRND) in CL/AM
CAB
CAB does not use a "background" insertion point. The CAB facility is called
equivalent "Distributed Processing."
How used in CAB
A CAB type is designated for Distributed Processing, so that when an instance of this type executes, it is not terminated by the system at the end of 250 milliseconds (the maximum allotted time for "atomic" CABs). The type is designated as suitable for Distributed Execution at type creation time. The "Distributed Execution" CAB type is compiled with less constraints on language features available than the constraints applied to "Atomic Execution" CAB types.
First seen R300 in this release
Remarks See "BKG_CHANGE_PRIORITY," "BKG_DELAY," "BKG_SWITCHOVER_RESTART."
17.6
BADVAL
Definition The built-in predicate BADVAL(X) returns ON if, and only if, X is a bad value.
How used SET x = flow.pv * specheat * density *delta_t / convert - - If any of the inputs has a in CL/AM bad value, the value of x will be - - bad; in such cases set the calculated pv bad. IF
BADVAL(x) THEN GOTO badpv
CAB
CAB uses "IsNan" to test for "Not a Number," the equivalent of a bad value.
equivalent
How used If Double.IsNaN(<param name>.Value) Then ` This expression returns True if
in CAB
<param name>.Value is NaN, or False if not.
First seen in this release
R210
Remarks See "ALLOW_BAD," "SET_BAD," "FINITE."
17.7
BKG_CHANGE_PRIORITY
Definition
On the AM, there is only one thread available for background execution, and all background CL programs are queued to that thread. The BKG_CHANGE_PRIORITY command is necessary so that the CL programs can be somewhat coordinated on the single thread available.
How used in CL/AM
BLOCK abc (GENERIC; AT BACKGRND) LOCAL prior : $BKGPRTY CALL BKG_ CHANGE_PRIORITY (LOW) -- starts at high priority and can be changed on entry -and at any time during execution SET prior = HIGH CALL BKG_CHANGE_PRIORITY (prior) END abc
CAB
No equivalent is necessary.
equivalent
How used For CAB on ACE, Distributed Mode CAB instances are executed each on their own
- 409 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
in CAB
thread, in a separate non-real-time process. The non-real-time process does not interfere with the real-time CEE process, so each executing Distributed Mode CAB instance has less need for explicit priority control.
First seen R300 in this release
Remarks See "BACKGRND," "BKG_DELAY," "BKG_SWITCHOVER_RESTART."
17.8
BKG_DELAY
Definition For Background CL, a program can use BKG_DELAY to suspend program execution for a specified period of time.
How used CALL BKG_DELAY (20 SECS) in CL/AM
CAB
For Distributed CAB types, we can use the WAIT call for the same effect.
equivalent
How used in CAB
Wait(500) This will cause the execution of the CAB to wait for 500 milliseconds (0.5 seconds) before continuing. Wait(New TimeSpan(0, 0, 0, 2, 500)) This will cause the execution of the CAB to wait for 0 days, 0 hours, 0 minutes, 2 seconds, and 500 milliseconds before continuing (a total of 2.5 seconds).
First seen R300 in this release
Remarks See "BACKGRND," "BKG_CHANGE_PRIORITY," "BKG_SWITCHOVER_RESTART."
17.9
BKG_SWITCHOVER_RESTART
Definition This function is used to detect and report, to the executing background CL program, that a switchover, from primary to secondary AM, has occurred.
How used BKG_SWITCHOVER_RESTART returns an ON value only if called during the first in CL/AM execution of a CL block following switchover.
CAB equivalent
Since this function is used only on redundant AM solutions, and we are not offering redundant CAB/ACE solutions, there is no translation, as yet, for an equivalent CAB.
How used N/A in CAB
First seen N/A in this release
Remarks See "BACKGRND," "BKG_CHANGE_PRIORITY," "BKG_DELAY."
- 410 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.10
CDS_READ
Definition Read values from a file into a CDS.
How used Used to retrieve from storage the values of a particular CDS. in CL/AM
CAB
There is no Experion/CAB equivalent to the CDS. In CAB, all parameters are defined
equivalent for each CAB Type via the PDE. There is no CAB concept of a parameter list to attach
to a CAB Type.
How used Not available in CAB. in CAB
First seen N/A in this release
Remarks
It is possible to automate some parameter definitions using PDE and Microsoft Excel. The rows and columns in the PDE can be copied to an Excel spreadsheet, and rows and columns from an Excel spreadsheet can be copied into rows and columns of the PDE. Thus, a "list" (the spreadsheet) of parameters can be used for several CAB Types without manual retyping effort.
17.11
COMM_ERROR
Definition
Built-in logical function used to check status of an upcoming attempted communication so that some attempts might be skipped, and default values used, instead of going ahead with the communication and dealing with the resulting failure. Often, the resulting failure would automatically abort the CL block, so this "pre-fetch check"is important.
How used in CL/AM
Comm_Error (x) Comm_Error accepts an argument that is an unsubscripted data point/PRef of any data type. If there is a communications error when this parameter is prefetched, it returns ON; otherwise, it returns OFF. The data point may be onLCN or off-LCN. If the data point is one that is not subject to prefetch, a communications error cannot occur and this function always returns OFF.
CAB
CAB and Experion PKShave no equivalent "look ahead" functionality. All
equivalent communication accesses result in statuses that indicate degrees of success or
failure. No communication attempts automatically result in aborted CABs.
How used N/A in CAB
First seen N/A in this release
Remarks Compare to "EXISTS."
17.12
COS
Definition
Built-in arithmetic function. Returns the cosine of the argument. All angles
- 411 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
are specified in radians. Cos(x) - where the argument and the return are of type Number.
Visual Basic Math.Cos method from the Math class library. x = Math.Cos(y) R210
17.13
CTL_ALG
Definition Insertion-point name. The name of an insertion point to which a CL/AM block is attached.
How usedin CL/AM
A CL/AM block is a program (usually small) that is used to augment the standard features of the processing cycle of continuous control. It can be inserted at any of several defined insertion points in the point processing cycle (see Table 2-3 below). A CL/AM block is the unit of CL/AM execution in continuous control. A block can be bound to a Regulatory Control, Custom, or Switch data point. It can substitute for that point's PV Algorithm or Control Algorithm, or can be inserted into its pointprocessing cycle at a predefined insertion point. The insertion point is specified in the header of the CL/AM block as shown in the following example: BLOCK BtuSwCtl (GENERIC $REG_CTL; AT ctl_alg)
Table 2-3 Insertion Points by Build Type
Regulatory Control Pre_GI Pre_PVPr Pre_PVAg PV_Alg Pst_PVAg
Pst_PVFL Pre_PVa Ctl_Alg Pst_CtAg Pst_PVPr Pre_ Pst_CtPr Pst_GO CTPr Pre_SP Pre_ Backgrnd CtAg
Custom General Backgrnd
Switch General Backgrnd
CAB
CAB instances can be configured to execute in the "normal" way that blocks are
equivalent processed in a Control Module (CM). Alternatively, a CAB instance can be configured
to execute at an insertion point in the processing sequence of certain other block
types.
Insertion points for RegCtl points
Insertion
Description
Post-Input
CAB instance inserted after input processing
Pre-Alg
CAB instance inserted prior to algorithm processing
Ctl-Alg
CAB instance inserted in place of the built in algorithm
Post-Alg
CAB instance inserted after algorithm processing
Post-CtlOut
CAB instance inserted after control output processing
Insertion points for Data ACQ point
Insertion
Description
PV-Alg
Custom PV algorithm
- 412 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
Post-PVchar
Post-Clampfilt
Post-PVsrc
Post-Alarmproc First seen R210 in this release
Remarks
CAB instance inserted after PV characterization CAB instance inserted after PV filtering and clamping CAB instance inserted after PV source selection CAB instance inserted after alarm processing
17.13.1
Insertion point configuration
1. When you are defining the CAB type in the development environment, be sure to configure the Access Level as Continuous Control--this is important.
2. Configure the RegCtl or DataAck instance and the insertion CAB instance in the same CM and do a Save.
3. Open the properties form for the RegCtl or DataAck instance and then click the Insertion tab. 4. Configure the NUMINSERT (number of insertions), the Insert Type, and the CAB Instance
name. (You can use the browser button to select the name, but do not select a parameter, although they are listed.) The result will resemble this figure: 5. Open the CAB properties form and configure values for any PRefs that you have defined. 6. Use one of these methods to verify that the insertion is configured correctly.
l With the CAB properties form open, select either the Configuration Parameters or the Monitoring Parameters tab, select INSMASTER, and then click Add.
l With the RegCtl or DataAck properties form open, select the Configuration Parameters tab, select INSBLOCK, and then click Add.
7. Save, load, and activate the CM.
17.14
DATE_TIME
Definition A built-in function. Date_Time returns the absolute TotalPlant Solution (TPS) System date/time; that is, seconds since midnight of 1 Jan 1979.
How used LOCAL t1, sked: TIME ... SET t1 = DATE_TIME -- current date and time in CL/AM
CAB equivalent
There is no exact CAB equivalent, but CAB can handle any CL/AM date and time requirement. CAB uses Visual Basic date and time classes and methods, which are too numerous for this table. Visual Basic's system.timespan and system.datetime routines handle time.
How used N/A in CAB
First seen in this release
R210
- 413 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
Remarks
See Visual Basic documentation for the "Date," "DateAndTime," "DateFormat," "DateInterval," "DateTime," "DayOfWeek," "TimeSpan," and "TimeZone" classes and their methods.
17.15
DAY_TIME
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
For Multifunction Controller (MC) only--makes settings for history. Not used in CL/AM. No equivalent necessary. N/A N/A
17.16
DELETE_FILE
Definition
A built-in subroutine, part of the file management system for background CL/AM blocks.
How used in CL/AM
Delete_File (s, fm, p) This subroutine deletes the named HistoryModule file (unless the file is protected). Where:
l "s" will contain the return status of the read request.
l "fm" will contain additional status information for some failure types.
l "p" is the full pathname of the file to be deleted (must be uppercase).
CAB equivalent
CAB uses the Visual Basic file system and syntax. File I/O in CAB is limited to Distributed Execution CAB Types. In Visual Basic, see system.io.file.delete.
How used in Dim x As File x.Delete() CAB
First seen in R300 this release
Remarks
17.17
ENGINEER
Definition
An Access_Lock state name, used for controlling access to parameters on a CDS. One of a set of Access_Lock states that include:
l PROGRAM
l OPERATOR
l SUPERVISOR
l ENGINEER
- 414 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
l ENTITY_BLDR
How used CUSTOM PARAMETER SWDBD "switch deadband value" --number by default in CL/AM ACCESS Engineer EU "psi" VALUE 0.5
CAB equivalent
CAB does not have the concept of CDSs. In CAB's PDE, however, a CAB (or CDB) Type author can specify the Experion PKSequivalent access control state names. For CAB/Experion, these are:
l PROGRAM
l OPERATOR
l SUPERVISOR
l ENGINEER
l APPDEVONLY
l VIEWONLY
How used The "Access lock" attribute is entered for each parameter through the PDE. in CAB
First seen in this release
R210
Remarks
17.18
ENTITY_BLDR
Definition
An Access_Lock state name.
How used in CL/AM See "ENGINEER."
CAB equivalent
See "ENGINEER."
How used in CAB
See "ENGINEER."
First seen in this release
R210
Remarks
See "ENGINEER" for an explanation of CL/AM and CAB/Experion PKSaccess control.
17.19
ENUM_VALUE_STORE
Definition
Enum_Value_Store (e, o, s) This built-in subroutine takes a real number input, converts it to integer, stores that value as the state of an enumeration or SDE and returns a success/fail status value. Where:
l "e" is a reference to a standard enumeration, or custom enumeration, or selfdefining enumeration (the enumeration can be a CL LOCAL variable, a parameter on the Bound Data Point, or a parameter on another point) to be stored to.
l "o" is a NUMBER value that represents the desired ordinal state of the referenced enumeration (where zero is the first enumeration state).
- 415 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
l "s" is a CLERRSTS enumeration value expressing return status.
How usedin CL/AM
BLOCK enmx (GENERIC; AT GENERAL) BLOCK enmx (GENERIC; AT GENERAL) EXTERNAL x100 -- other AM point with valid PTEXECST parameter LOCAL status : CLERRSTS LOCAL m : PTEXECST -- set local variable active through Enum_Value_ Store CALL ENUM_VALUE_STORE (m, 1.0, status) IF status <> NOERROR THEN SEND: "enum val store err", ORD (status) -- set external point active through Enum_ Value_Store CALL ENUM_VALUE_STORE (x100.PTEEXCST, ORD(M), status) IF status <> NOERROR THEN SEND: "enum val store err", ORD (status) -- the following produces similar results, but Enum_Value_Store -- has the advantage of returning a success/fail status SET x100.PTEXECST = ACTIVE END enmx
CAB
CAB, through Visual Basic, supports the construction and use of VB enumerations
equivalent inside CAB code. Refer to Visual Basic documentation (and see the example below).
CAB does not support access to Experion PKSenumerations held in Experion
PKSdatabases in anything but ordinal form.
How usedin CAB
(From Visual Basic documentation.) Enum SecurityLevel IllegalEntry = -1 MinimumSecurity = 0 MaximumSecurity = 1 End Enum You must qualify every reference to an enumeration member, either with the name of an enumeration variable or the enumeration name itself. For example, in the prior example, you can refer to the first member as SecurityLevel.IllegalEntry, but not as IllegalEntry.
First seen N/A inthis release
Remarks
17.20
EQUAL_NULL_POINT_ID
Definition
The built-in function Equal_Null_Point_id allows comparison of a CDS parameter of type entity_id to a Null id (point name value does not have a corresponding LCN point--that is, a "no-point" value). This tests to see if an entity_id is pointing to some point.parameter, vs. being null, or not initialized.
How usedin CL/AM
IF (NOT EQUAL_NULL_POINT_ID (pnt1.null)) THEN &CALL SET_NULL_POINT_ID (pnt1.null, stat) END sbr_ind
CAB
There is no Experion PKSequivalent to the TDC/AM entity_id concept. CAB, with its
equivalent Dynamic Re-referencing facility, provides the ability for PRefs to respond to real-time
changes in their references. These references are accessible externally, and from
CAB programs, in the form of textual representations of the address of the target
reference, stored in the ".TEXTREF" attribute for the PRef. For PRefs, the "IsNull"
method is analogous to EQUAL_NULL_POINT_ID.
How usedin CAB
Checking for a null PRef reference: If MIXTANKSP.IsNull Then ... End If Checking for rereference errors If a re-reference action fails for a PRef (example, the text name entered does not exist), the CAB algorithm can use the PRef IsValid property to detect the error.If <parameter_reference_name>.IsValid then ' do process for the ReReference success <parameter_reference_name>.Read() ' else process the error The CAB algorithm can also use the PRef read or write to detect the error.<parameter_reference_name>.Read() If <parameter_reference_ name>.ReadStatus = CABAccStatusEnum.ReRefFail then ' do error process for the Re-Reference failure The CAB algorithm can also examine the PRef TextRef property to see if it has been set to the error string to detect an error in the rebinding. The TextRef property will be set to a string that starts with "<err." Checking for a TextRef
- 416 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
property equal to "" (an empty string) could also be used as an analog of EQUAL_ NULL_POINT_ID. First seen Dynamic Re-referencing is in R300. inthis release Remarks
17.21
EQUAL_POINT_ID
Definition
Equal_Point_id (p1, p2) This built-in function compares two CDS parameters of type point_id (either value being compared can be a single CDS parameter or a subscripted element of an array). The points may be on-LCN or off-LCN It returns ON if the two CDS point_id values are equal. It will return OFF for any of the following reasons:
l Point_id values of the arguments are not the same.
l Cannot access either parameter.
l Either point_id specifies an entire array.
l Either point_id is not of type entity_id.
How usedin CL/AM
PACKAGE CUSTOM PARAMETER pt1 : $REG_CTL EU "PT_IDENT"VALUE a100 -- a valid system point identifier END CUSTOM BLOCK eqlpnt (GENERIC; AT GENERAL) EXTERNAL x100 -- another point with the above package attached IF NOT EQUAL_ POINT_ID (pt1, x100.pt1) THEN &SEND: "pt1 does not equal x100.pt1" -- sends message if the point names are not equal END eqlpnt END PACKAGE
CAB
There is no Experion PKSequivalent to the TDC/AM entity_id concept. CAB has no
equivalent direct equivalent to EQUAL_POINT_ID. CAB, with its Dynamic Re-referencing facility,
provides the ability for PRefs to respond to real-time changes in their references.
These references are accessible externally, and from CAB programs, in the form of
textual representations of the address of the target reference, stored in the
".TEXTREF" attribute for the PRef. The ".TEXTREF" attribute for one PRef can be
compared to another, using Visual Basic string manipulation techniques. This
comparison is analogous to the EQUAL_POINT_ID test.
How usedin CAB
If (FIRSTREF.TextRef = SECONDREF.TextRef) Then ' Do things because the two references point to the same target End If
First seen Dynamic Re-referencing is in R300. inthis release
Remarks
17.22
EXISTS
Definition
A built-in logical function, used to check the existence of a point.parameter, so that some access attempts might be skipped, and default values used, instead of going ahead with the communication and dealing with the resulting failure. Often, the resulting failure would automatically abort the CL block, so this "pre-fetch check"is
- 417 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
important.
How usedin CL/AM
Exists (p) This function accepts an argument that is an unsubscripted data point/PRef of any data type. It returns ON if the data point and parameter exist. It returns OFF if either the data point does not exist or the point exists but the parameter does not, or if the Exists check is through a null point identifier, or if a communications error occurs on the Exists call, or if a software inconsistency exists between CL and the data owner (ERROR1). The data point may be on-LCN or offLCN. The argument of Exists is restricted in the same way as that of Comm_Error.
CAB
CAB and Experion PKShave no equivalent "look ahead" functionality. All
equivalent communication accesses result in statuses that indicate degrees of success or
failure. No communication attempts automatically result in aborted CABs.
How
N/A
usedin
CAB
First seen N/A inthis release
Remarks Compare to "COMM_ERROR."
17.23
EXP
Definition Built-in arithmetic function. Returns the natural log exponent of the argument.
How used in CL/AM
Exp(x) - where the argument and the return are of type Number. CL statement: block dog(generic; at general) Local x,y SET x = 0.0 SET y = exp(x) SEND: y ---would output 1.0 SET x = 1.0 SET y = exp(x) SEND: y ---would output 2.71823 SET x = 2.0 SET y = exp(x) SEND: y ---would output 7.38905 end dog
CAB
Visual Basic Math.Exp method from the Math class library.
equivalent
How used y = Math.Exp(x) in CAB
First seen R210 in this release
Remarks
17.24
FINITE
Definition The built-in predicate FINITE(X) returns ON if, and only if, X is finite; that is, neither a bad value or an infinite value.
How used IF NOT FINITE(x) THEN GOTO badpv in CL/AM
CAB
CAB uses "IsNan" to test for "Not a Number", the equivalent of a bad value. CAB
equivalent uses "IsInfinity," "IsNegativeInfinity," "IsPositiveInfinity" to test for various
- 418 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
categories of infinity.
How used If MIXTANKSP.Value.IsNegativeInfinity() Then ... End If If
in CAB
MIXTANKSP.Value.IsPositiveInfinity Then ... End If If MIXTANKSP.Value.IsInfinity
Then ... End If If MIXTANKSP.Value.IsNaN Then ... End If
First seen in this release
R210
Remarks See "ALLOW_BAD," "SET_BAD," "BADVAL."
17.25
GENERAL
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.26
GET_CL_SLOT
Definition
Get_CL_Slot (s, i) This subroutine takes a string input (s), compares it with the names of all CL blocks on the point, and returns real number index value (i) if a match is found (returns -1 if no match is found). If the input string is longer than eight characters, only the first eight characters are used for the comparison. The character string must all be in upper case. Reasons for Get_CL_Slot index to be invalid are:
l Slot name cannot be found (-1.0).
l Character string contains lower case characters (-1.0)
How used in CL/AM
BLOCK gtslt (GENERIC; AT GENERAL) LOCAL i CALL GET_CL_SLOT ("GTSLT", i) -note upper case string IF i <;>; -1.0 THEN SEND: "gtslt is cl slot", i ELSE SEND: "gtslt not found" -- is similar to the following (however, get_cl_slot can find -- other onpoint block names SET i = SELF SEND: "gtslt is cl slot ", i CALL GET_CL_SLOT ("ABCDEFGHIJKL", i) -- note that only a-h are used for the comparison IF i <>-1.0 THEN SEND: "abcdefgh is cl slot", i ELSE SEND: "gtslt not found"END gtslt
CAB
There is no CAB equivalent. CABs are contained in Control Modules, and are
equivalent addressed via Experion PKSnaming and addressing techniques. Slots on points are
not used.
How used N/A in CAB
First seen N/A in this
- 419 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
release Remarks
17.27
INT
Definition Built-in arithmetic function. Truncates to integer.
How used Int(x), where the argument and the return are of type Number. in CL/AM
CAB
CAB uses Visual Basic implicit and explicit conversions. Converting from a floating-
equivalent point to an integer would need to be an explicit conversion.
How used in CAB
(This is from .NET documentation and is also available for Int32 and Int64.) Dim testnum As String Dim testint As Int16 testint = System.Convert.ToInt16(testnum) (In the above example, "double" is used, but the "ToInt16" method can be overloaded with any data type.) (This is from Visual Basic documentation, for reference to legacy functionality still supported. The .NET calls are preferred.) An explicit conversion uses a type conversion keyword. Visual Basic .NET provides several such keywords, which coerce an expression in parentheses to the desired data type. These keywords act like functions, but the compiler generates the code inline, so execution is slightly faster than with a function call. In the following extension of the preceding example, the CInt keyword converts the value of Q back to an integer before it is assigned to K: Dim K As Integer Dim Q As Double Q = Math.Sqrt(Q) ' Q had been assigned the value 432. K = CInt(Q) ' K now has the value 21 (rounded square root of 432).
First seen R210 in this release
Remarks
17.28
LEN
Definition
Built-in function. Returns the length of the string it is passed.
How used in CL/AM
Len("abcde") = 5; Len("") = 0.
CAB equivalent
Visual Basic method on the String class. See the VB system.string class.
How used in CAB
Dim jk As String Dim jklength As Integer jklength = jk.Length()
First seen in this release R210
Remarks
- 420 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.29
LN
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Built-in arithmetic function. Returns natural log (base e) of the argument. Ln(x), where the argument and the return are of type Number. Visual Basic Math.Log method from the Math class library. result = Math.Log(logtest) R210
17.30
LOG10
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Built-in arithmetic function. Returns common log (base 10) of the argument. Log10(x), where the argument and the return are of type Number. Visual Basic Math.Log10 method from the Math class library. result = Math.Log10(logtest) R210
17.31
LOGICAL
Definition Logical is a predefined discrete type that has two states: ON and OFF. The following operations are defined on Logical values: NOT, AND, OR, and XOR.
How used LOCAL flag: Logical LOCAL x: Number IF x <; 5 THEN SET flag = On ELSE SET flag = in CL/AM Off
Logical Operators Truth Table
a
b
NOT a
a AND b
a OR b
a XOR b
ON
ON
OFF
ON
ON
OFF
ON
OFF
OFF
OFF
ON
ON
OFF
ON
ON
OFF
ON
ON
OFF
OFF
ON
OFF
OFF
OFF
CAB
Visual Basic's Boolean data type and Boolean operations.
equivalent
How used Dim RunningVB As Boolean ' Check to see if program is running on VB engine. If
- 421 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
in CAB
ScriptEngine ="VB"Then RunningVB = True End If Dim x As Boolean x = Not 23 >; 12 ' x equals False x = Not 23 >; 67 ' x equals True x = 23 >; 12 And 12 >;4 ' x = True x = 12 >; 23 And 12 >; 4 ' x = False x = 23 >; 12 Or 4 >; 12` ' x = True x = 23 >; 45 Or 4 >; 12 ' x = False x = 23 >; 45 Xor 12 >; 4 ' x = True x = 23 >; 12 Xor 12 >; 4 ' x = False x = 12 >; 23 Xor 4 >; 12 ' x = False
First seen R210 in this release
Remarks
17.32
MAX
Definition
Built-in arithmetic function. Returns the maximum value of the arguments, or the maximum value of the elements in an array.
How used in Max (x, y, ...) is maximum, where x and y are arguments to be evaluated. Max(x) is
CL/AM
maximum, where x is an array whose elements are to be evaluated.
CAB equivalent
Visual Basic CABMath.Max method from the CABMath class library. Max() is also a method in the normal VB Math class.
How used in MaximumFlow = CABMath.Max(FLOW1, FLOW2, FLOW3) CAB
First seen in R210 this release
Remarks
See"CABMath class" in the CAB User's Guide for a full set of examples.
17.33
MC
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
For Multifunction Controller (MC) only, a sequence program type. Not used in CL/AM. No equivalent necessary. N/A N/A
17.34
MIN
Definition
Built-in arithmetic function. Returns the minimum value of the arguments, or the minimum value of the elements in an array.
How used in Min (x, y, ...) is minimum, where x and y are arguments to be evaluated. Min(x) is
CL/AM
minimum, where x is an array whose elements are to be evaluated.
- 422 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
CAB equivalent
Visual Basic CABMath.Min method from the CABMath class library. Min() is also a method in the normal VB Math class.
How used in MinimumFlow = CABMath.Min(FLOW1, FLOW2, FLOW3) CAB
First seen in R210 this release
Remarks
See"CABMath class" in the CAB User's Guide for a full set of examples.
17.35
MODIFY_STRING
Definition
Modify_String (s, ts, tp, n, ss, sp) This subroutine changes the value of a substring in a target string to the value of a substring copied from a source string. It can be called by either Background or Foreground CL Blocks. Where:
l "s" is a $MODSTR enumeration value expressing return status.
l "ts" is the target string to be modified (IN OUT).
l "tp" is the index to the first character of the target string to modified.
l "n" is the number of characters to move from the source string to the target string.
l "ss" is the string from which characters will be fetched.
l "sp" is the index to the first character to be fetched from the source string. If the number of characters (n) is greater than the number of characters between the source position index (sp) and the end of the source string, only the number of characters that exist in the source substring are moved to the target substring. A status of"OK" is returned. If the number of characters (n) is greater than the number of characters between the target position index (tp) and the end of the target string, the number of characters that will be moved is limited by the maximum target string length of 78 characters. A status of"OK" is returned. If the target position index (tp) is greater than 78, or the source position index (sp) is greater than the length of the source string, a status of FAILED is returned. If the target position index (tp) is greater than the current length of the target string, blanks will be inserted between the current length position and the target position.
How usedin CL/AM
Modify_String Example 1: LOCAL stat : $MODSTR LOCAL target, source : STRING LOCAL tindex, sindex, chars SET target ="net>;cust>;recipenn.x" SET tindex = 16.0 SET chars = 2.0 SET source ="ab" SET sindex = 1.0 CALL MODIFY_STRING (stat, target, tindex, chars, source, sindex) (Results of this example are target ="net>;cust>;recipeab.x" and stat = OK) Modify_String Example 2: SET target ="net>;cust>;recipenn.x" SET tindex = 16.0 SET chars = 2.0 SET source ="ab" SET sindex = 2.0 CALL MODIFY_STRING (stat, target, tindex, chars, source, sindex) (Results of this example are target ="net>;cust>;recipebn.x" and stat = OK)
CAB
CAB uses Visual Basic .NET string manipulation techniques, and also supports
equivalent the"ToString" method. See the VB system.string class.
How usedin CAB
Refer to Visual Basic documentation--the variations in string manipulation techniques are too large for this table.
First seen R210 inthis release
Remarks
- 423 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.36
MOVE_PARAMETER
Definition
Move_Parameter (x, y, s) This subroutine fetches a parameter value, copies it to a specified destination, and returns a success/fail status value. Where:
l "x" is the parameter that is to receive the value (destination data).
l "y" is the parameter value to be fetched (source data).
l "s" is a CLERRSTS enumeration value that defines the success or failure of the store request.
The parameters being moved can be scalar (single elements), array elements, or entire arrays. The parameters may be on on-LCN or off-LCN points.
How usedin CL/AM
BLOCK locarr (GENERIC; AT GENERAL) -- local array and array element examples LOCAL l, ll : LOGICAL ARRAY (1..2) LOCAL t, tt : TIME ARRAY (1..2) LOCAL r, rr : NUMBER ARRAY (1..2) LOCAL e, ee : MODE ARRAY (1..2) LOCAL s, ss : STRING ARRAY (1..2) LOCAL status : CLERRSTS SET l(1) = ON SET l(2) = ON SET ll(1) = OFF SET ll(2) = OFF CALL MOVE_PARAMETER (ll, l, status) -- overwrite "ll" parameter -- array "OFF" values with "l" -- parameter array "ON" values IF status <> NOERROR THEN SEND: "logical array move failed"
CAB
There is no CAB or Experion PKSdirect equivalent for this function.
equivalent
How usedin CAB
CAB authors can code a CAB to mimic a MOVE_PARAMETER type of action, but there is no built-in CAB functionality.
First seen N/A inthis release
Remarks
17.37
NOW
Definition
A built-in function, returns wall-clock time (seconds since midnight of the current day).
How used LOCAL cur_time : TIME -- Current time SET cur_time = Now in CL/AM
CAB
CAB uses Visual Basic date and time functions. Visual Basic's system.timespan and
equivalent system.datetime routines handle time.
How used This example uses the Now property to return current system date and time. Dim
in CAB
ThisMoment As Date ThisMoment = Now ' Assign current system date and time.
First seen in R210 this release
Remarks
- 424 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.38
NUMBER
Definition A data type name. All numeric values in CL/AM are of the single type, Number, which is conceptually a subset of the real numbers and is internally implemented in floating point.
How used in CL/AM
LOCAL x, y, z: NUMBER -- three local numbers Examples of assignments to a Number: 1000 -- valid 1000. -- NOT VALID; no trailing digit 1000.0 -- valid; same as 1000 0.5 -- valid .5 -- NOT VALID; no leading digit 10.02E1 -- valid 10.02e1 -- valid; same as 10.02E1 10.02 e1 -- NOT VALID; embedded space 1234.0E-2 -- valid 1234E2 -- NOT VALID; "1234E" is an identifier 1234.0E -2 -- NOT VALID; embedded space 1234.0E+2 -- valid
CAB
CAB uses Visual Basic. The nearest equivalent is Double.
equivalent
How used Dim x as Double in CAB
First seen R210 in this release
Remarks
17.39
NUMBER_TO_STRING
Definition
Number_to_String (s, str, i, f) This subroutine creates a human readable characterization of a real number. It can be called by either Background or Foreground CL Blocks. Where:
l "s" will contain the return status of the store request.
l OK = successful conversion
l BADFORM = the format string was incorrect
l BADVALU = the number provided was bad
l "str" will contain the character representation of the specified real value
l "i" identifies the number to convert
l "f" is a format specification describing the desired character representation of the converted number.
How usedin CL/AM
LOCAL i LOCAL str : STRING LOCAL fmt : STRING LOCAL stat: : $CONVRS SET fmt = "G99999" SET i = 23.44 CALL NUMBER_TO_STRING (stat, str, i, fmt) SEND: "The number is =", str This example will produce the following message in the operator message display: The number is = 23.44
CAB
CAB uses Visual Basic. Visual Basic supplies a "ToString" method for the "Double"
equivalent class.
How usedin CAB
Private Sub HandleTimeOut() ' Take appropriate actions. Send("CAB TimeOut.") Send("TargetTime = " + TARGETTIME.Value.ToString) Send("TimeOut = " + TIMEOUT.Value.ToString) End Sub
First seen R210 inthis release
- 425 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
Remarks
Visual Basic's "ToString" method can be complex. Refer to Visual Basic documentation for more information. VB.Net supplies the "ToString" method for any object. This functionality may be useful to coders.
17.40
OFF
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Logical state name. See "LOGICAL." Visual Basic Boolean state name "False." See "LOGICAL." R210
17.41
ON
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Logical state name. See "LOGICAL." Visual Basic Boolean state name "True." See "LOGICAL." R210
17.42
OPERATOR
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
An Access_Lock state name. See "ENGINEER." See "ENGINEER." See "ENGINEER." R210
See "ENGINEER" for details about CL/AM and CAB/Experion PKSaccess control.
- 426 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.43
ORD
Definition
Ord (e) This built-in function takes the current state of a standard enumeration, custom enumeration, or self-defining enumeration and returns a number value (where zero represents the first enumeration member). The enumeration can be in a CL LOCAL variable, a parameter on the Bound Data Point, or a parameter on another point.
How usedin CL/AM
BLOCK ordx (GENERIC; AT GENERAL) EXTERNAL x100 -- other AM point with valid PTEXECST parameter LOCAL i -- type number LOCAL m : PTEXECST SET m = ACTIVE SET i = ORD (m) SEND: "local ptexecst active is ", i IF ORD (x100.PTEXECST) = i THEN & SEND: "x100 active is ", ORD(x100.PTEXECST) ELSE SEND: "x100 inactive is " , ORD (x100.PTEXECST) END ordx
CAB equivalent
CAB, through Visual Basic, supports the construction and use of VB enumerations inside CAB code. Refer to VB documentation (and the example below). CAB does not support access to Experion PKSenumerations held in Experion PKSdatabases in anything but ordinal form.
How usedin CAB
(From Visual Basic documentation.)Enum SecurityLevel IllegalEntry = -1 MinimumSecurity = 0 MaximumSecurity = 1 End Enum You must qualify every reference to an enumeration member, either with the name of an enumeration variable or with the enumeration name itself. For example, you can refer to the first member as SecurityLevel.IllegalEntry, but not as IllegalEntry.
First seen N/A inthis release
Remarks
17.44
PM
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
For Process Manager (PM) only. Not used in CL/AM. No equivalent necessary. N/A N/A
17.45
PRE_CTAG
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
- 427 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
First seen in this release
Remarks
R210
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.46
PRE_CTPR
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.47
PRE_GI
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.48
PRE_PVA
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
- 428 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.49
PRE_PVAG
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.50
PRE_PVPR
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.51
PRE_SP
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Insertion-point name. See "CTL_ALG." See "CTL_ALG." See "CTL_ALG." R210
17.52
PROGRAM
Definition How used in CL/AM
An Access_Lock state name. See "ENGINEER."
- 429 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
CAB equivalent How used in CAB First seen in this release Remarks
See "ENGINEER." See "ENGINEER." R210
See "ENGINEER" for details about CL/AM and CAB/Experion PKSaccess control.
17.53
PST_CTAG
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.54
PST_CTPR
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.55
PST_GO
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this
R210
- 430 -
release Remarks
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.56
PST_PVAG
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.57
PST_PVFL
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.58
PST_PVPR
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
- 431 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.59
PV_ALG
Definition
Insertion-point name.
How used in CL/AM See "CTL_ALG."
CAB equivalent
See "CTL_ALG."
How used in CAB
See "CTL_ALG."
First seen in this release
R210
Remarks
See "CTL_ALG" for details about CL/AM insertion points and CAB/ACE insertion points.
17.60
ROUND
Definition
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
Built-in function. Round(x) rounds x and returns an integer as a result. SET y = round(x). Note that CL/AM does not have an integer data type. "y" contains an integer value, stored in a Number data type. Visual Basic Math.Round method from the Math class library.
y = Math.Round(x)
R210
17.61
SET_BAD
Definition
Built-in subroutine. Sets a targeted variable to Nan ("Not a Number").
How used in CL/AM
badpv : CALL SET_BAD (pvcalc)
CAB equivalent Visual Basic Double.NaN constant. VB also can store positive infinity and negative infinity via built-in constants.
How used in CAB x = Double.NaN x = Double.PositiveInfinity x = Double.NegativeInfinity
First seen in this R210 release
Remarks
See also "ALLOW_BAD," "BADVAL," "FINITE."
- 432 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
17.62
SET_NULL_POINT_ID
Definition Set_Null_Point_id (p, s) This subroutine will store a null point identifier to a CDS parameter (p) of type data point identifier (this can be either a single CDS parameter or a subscripted element of an array) and returns a success/fail status (s).
How usedin CL/AM
CALL SET_NULL_POINT_ID (pt1, status)
CAB
There is no Experion PKSequivalent to the TDC/AM entity_id concept. CAB has no
equivalent direct equivalent to SET_NULL_POINT_ID. CAB, with its Dynamic Re-referencing
facility, provides the ability for PRefs to respond to real-time changes in their
references. These references are accessible externally, and from CAB programs, in
the form of textual representations of the address of the target reference, stored in
the ".TEXTREF" attribute for the PRef. The ".TEXTREF" attribute can be stored to,
using Visual Basic string manipulation techniques. If the CAB program stores an
empty string to the ".TEXTREF" attribute for a PRef , this storage is analogous to the
SET_NULL_POINT_ID storage of CL/AM.
How usedin CAB
FIRSTREF.TextRef() = "" ' Storing an empty string, to null the reference
First seen Dynamic Re-referencing is in R300. inthis release
Remarks
17.63
SIN
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Built-in arithmetic function. Returns the sine of the argument. All angles are specified in radians. Sin(x), where the argument and the return are of type Number.
Visual Basic Math.Sin method from the Math class library. x = Math.Sin(y) R210
17.64
SQRT
Definition How used in CL/AM CAB equivalent
Built-in arithmetic function. Returns the square root of the argument. Sqrt(x), where the argument and the return are of type Number. Visual Basic Math.Sqrt method from the Math class library.
- 433 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
How used in CAB
x = Math.Sqrt(y)
First seen in this release R210
Remarks
17.65
STRING
Definition A data type - a sequence of zero or more characters enclosed at each end by quotation marks (").
How used "This is a String" -- a String "&@$?*! system" -- can contain any printable characters in CL/AM "" -- the empty String "He said ""hello""" -- he said "hello" "A" " " """" -- three
Strings of length 1
CAB
CAB uses Visual Basic .NET strings, and also supports the "ToString" method. See
equivalent the VB system.string class.
How used Refer to Visual Basic documentation--the variations in strings are too large for this
in CAB
table.
First seen in this release
R210
Remarks
17.66
SUM
Definition
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
Built-in arithmetic function. Returns the sum of the arguments, or the sum of the elements in an array. Sum (x, y, ...) -- sum, where x, y, ... are arguments to be summed. Sum(x) -- sum, where x is an array whose elements are to be summed. Visual Basic CABMath.Sum method from the CABMath class library.
FlowSum = CABMath.Sum(FLOW1, FLOW2, FLOW3)
R210
See "CABMath class" in the CAB User's Guide for a full set of examples.
17.67
SUPERVISOR
Definition How used in CL/AM
An Access_Lock state name. See "ENGINEER."
- 434 -
Chapter 17 - Appendix A: CL/AM to CAB mapping tables-identifiers
CAB equivalent How used in CAB First seen in this release Remarks
See "ENGINEER." See "ENGINEER." R210
See "ENGINEER" for details about CL/AM and CAB/Experion PKSaccess control.
17.68
TAN
Definition
Built-in arithmetic function. Returns the tangent of the argument. All angles are specified in radians.
How used in CL/AM
Tan(x), where the argument and the return are of type Number.
CAB equivalent Visual Basic Math.Tan method from the Math class library.
How used in CAB x = Math.Tan(y)
First seen in this R210 release
Remarks
17.69
TIME
Definition The data-type Time represents an interval of time in the TPS format. Time values can be expressed in seconds, minutes, hours, or days, or any combination of these.
How used LOCAL t1, sked: TIME LOCAL n,m: NUMBER ... SET t1 = DATE_TIME -- current date in CL/AM and time SET sked = 20 SECS -- set a time variable SET t1 = n SECS
CAB equivalent
CAB uses the Visual Basic .NET DateTime class for time declarations and manipulations. Visual Basic's system.timespan and system.datetime routines handle time.
How used Refer to Visual Basic documentation--the variations in time storage and
in CAB
manipulation are too large for this table.
First seen in this release
R210
Remarks
- 435 -
CHAPTER
18
APPENDIX B: CL/AM TO CAB MAPPING TABLES-
RESERVED WORDS
18.1
ABORT
Definition
CL/AM termination statement. This statement causes abnormal program termination. When executed in a subroutine, it terminates both the subroutine and its caller. The effect of ABORT on point processing depends on the build type of the bound data point.
How usedin CL/AM
ABORT
CAB equivalent
Subroutine Abort() BlockBase supports a subroutine which allows the program to break the current cycle of execution. Calling Abort() when there is no surrounding Catch clause does the following:
l Prevents any further instructions from executing in the current cycle.
l Puts CABSTATE into Exception.
l As with any Exception condition, reports an alarm.
l As with any Exception condition, execution of the block resumes on the next cycle.
How usedin CL/AM
If PV.ReadStatus = OK Then LASTPV.Value = PV.Value BADPVCOUNT.Value = 0 ' use PV.Value ElseIf BADPVCOUNT.Value <= 3 Then BADPVCOUNT.Value = BADPVCOUNT.Value + 1 ' use LASTPV.Value Else ' handle case of PV which has become unusable PROGSTSDESC.Value = "Bad PV: " + PV.ReadStatus.ToString Abort() End If
CAB
R210
equivalent
Remarks
18.2
ACCESS
Definition A keyword in CDS headings to indicate various access levels for the data segment.
How used in CL/AM
SET_NULL_POINT_IDACCESS Operator) Or PACKAGE ENUMERATION traflite = green/amber/red PARAM_LIST lite_pt PARAMETER PV, OP: traflite PARAMETER 1_ back, & 1_ahed: lite_pt PARAMETER cycles: Logical ARRAY (traflite) END lite_pt CUSTOM PARAMETER 1_back, & 1_ahed: lite_pt ACCESS PROGRAM PARAMETER
- 436 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
cycles: Logical ARRAY (traflite) VALUE (ON, ON, OFF) PARAMETER all_red: Logical END CUSTOM END PACKAGE
CAB
CAB does not have the concept of CDSs. But in CAB's PDE, a CAB (or CDB) Type
equivalent author can specify the Experion PKSequivalent access control state names.
How used The "Access lock" attribute is entered for each parameter, via the PDE. in CAB
First seen R210 in this release
Remarks See "ENGINEER."
18.3
ALARM
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.4
AND
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Logical operator. See "LOGICAL." Visual Basic Boolean operator. See "LOGICAL." R210
18.5
ANY_ENUMERATION
Definition ANY_ENUMERATION is a reserved word, but is otherwise undefined in the CL/AM Reference Manual.
How used N/A in CL/AM
- 437 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
CAB
CAB Type coding uses only the ordinal values of enumerations. CAB Type authors
equivalent must know the ordinal values for the enumeration states they want to read or write
for any given enumerated variable.
How used N/A in CAB
First seen N/A in this release
Remarks
18.6
ARRAY
Definition In the AM, arrays are composed of any scalar type, data point type, or the String type and can have one or two dimensions. They can be indexed by any scalar type except Time. String arrays can have only one dimension.
How usedin CL/AM
Array examples: l coeff(6) -- one dimension l matrix(6, 8) -- two dimensions l status(Casc) -- indexed by discrete type l pump(x+y*z) -- indexed by expression
CAB
Arrays can be used within CAB programs as consistent with the syntax and
equivalent semantics of the underlying .NET language. For arrays that are only used internally
to CAB programs (block scope variables or local variables), the full indexing
capabilities of the VB.NET language are supported. CAB CDPs can be defined to be of
one- or two-dimensional array type. The element type of CDP arrays is always a
simple type and is restricted to the set supported by scalar CDPs. The CAB that owns
the array CDP can do index computations at run time in order to access elements of
the array. All CDPs support properties Dim1, Dim2, LowBound1, and LowBound2,
which can be used to determine the dimension sizes and lower bounds of arrays.
CAB PRefs are always scalar. Thus, the block designer cannot create an array of
PRefs. Scalar PRefs can point to scalar parameters or to individual elements of array
parameters. References to external parameter arrays always use fixed indices and
are thus equivalent to ordinary scalar references.
How usedin CAB
Visual Basic techniques are used to access arrays. An example' Example of initializing a two-dimensional 5x5 string array For i As Integer = 0 To 4 For x As Integer = 0 To 4 Me.TESTARRAY(i, x).Value = "test" + x.ToString Next Next
First seen R210 inthis release
Remarks
18.7
AT
Definition
A compiler reserved word - used in CL/PM.
- 438 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
How usedin CL/AM CABequivalent How usedin CAB First seen inthis release Remarks
Not used in CL/AM. No equivalent necessary. N/A N/A
18.8
BLD_VISIBLE
Definition
The BLD_VISIBLE attribute displays the parameter to the engineer at CDS buildtime. The engineer can enter a value for the parameter or change the value if one is entered through the VALUE statement. NOT BLD_VISIBLE prevents display of the parameter at build-time. If not specified in the CDS heading, the default is BLD_ VISIBLE.
How usedin CL/AM
PACKAGE CUSTOM (BLD_VISIBLE) ...
CAB
"Load" or "Noload" Configuration Load attribute for each CDP.
equivalent
How used Using the PDE, CAB Type authors can mark each CDP with a Configuration Load
in CAB
attribute of "load" or "noload." "Load" enables values to be written to the parameter
at configuration time, whereas "noload" prevents this.
First seen R210 in this release
Remarks
18.9
BLOCK
Definition The basic CL entity, and a keyword identifying a CL block.
How used BLOCK dir (GENERIC: AT PRE_GI) ... END dir in CL/AM
CAB
CABlock, a custom algorithm block, with Experion PKSControl Execution
equivalent Environment function block features.
How used in CAB
Note: The following code is not code that a CAB Type author needs to fill in. This code, as well as code which specifies the proper include libraries, is already filled in to start the CAB editing session in Visual Studio. In the filled-in code is a comment "TODO" that indicates where the CAB Type author should insert code.)Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() 'TODO: User should insert their Execute code here End Sub End Class
First seen R210 in this release
Remarks
- 439 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.10
CALL
Definition A statement used to invoke subroutine execution.
How used Example: IF stat = noerror THEN CALL MOVE_PARAMETER (pnt2.prev, pnts(2), stat) in CL/AM
CAB
CAB uses Visual Basic techniques, which do not need the "call" keyword. "Call" is
equivalent acceptable, but not necessary. If functions are used with the "Call" statement, they
work, but do not return any value.
How used Public Class CABlock ... Public Overrides Sub Execute() 'TODO: User should insert
in CAB
Execute code here .... If Restart <>None Then Initialize() .... End Sub Private Sub
Initialize() ... End Sub End Class
First seen in this release
R210
Remarks
18.11
CLASS
Definition
The CLASS attribute, in a CDS heading, defines the display class (General, PV_Alg, or Ctl_Alg) of the parameters in the Custom data definition. If no display class is named, the default is General.
How used CUSTOM (CLASS PV_Alg; ACCESS Operator) CUSTOM (NOT BLD_VISIBLE) CUSTOM in CL/AM (CLASS Ctl_Alg)
CAB
There is no Experion/CAB equivalent to the CDS. In CAB, all parameters are defined
equivalent for each CAB Type via the PDE in the CDP tab. There is no CAB concept of a
parameter list to attach to a CAB Type.
How used Not available in CAB. in CAB
First seen N/A in this release
Remarks
18.12
CUSTOM
Definition A keyword identifying a CDS. Less used-a type of point.
How used CUSTOM PARAMETER pntl : mytyp -- Parameter of type point id. VALUE A100 -in CL/AM Indirect ref via CDS parameter EU "IND_ID"-- of type parameter list (A100 is --
established as the DEB default -- value). END CUSTOM
CAB
There is no Experion/CAB equivalent to the CDS. In CAB, all parameters are defined
equivalent for each CAB Type via the PDE in the CDP tab. There is no CAB concept of a
- 440 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
parameter list to attach to a CAB Type. CDSs (lists to attach to many blocks) have no equivalent in CAB. CDBs are independent containers of Experion PKSdata. CDPs and PRefs can be attached to CAB Types.
How used A sample PDE display is shown below. in CAB
First seen R210 in this release
Remarks
It is possible to automate some parameter definitions using PDE and Microsoft Excel. The rows and columns in the PDE can be copied to an Excel spreadsheet, and rows and columns from an Excel spreadsheet can be copied into rows and columns of the PDE. Thus, a "list" (the spreadsheet) of parameters can be used for several CAB Types without retyping effort.
18.13
DATA_POINT_ID
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
DATA_POINT_ID is a reserved word, but is otherwise undefined in the CL/AM Reference Manual. N/A
N/A N/A N/A
18.14
DAYS
Definition Part of a time literal.
How used in CL/AM
Time Literals Examples: 5 MINS -- five minutes 300 SECS -- five minutes (1/12) HOURS -- five minutes 4 MINS 60 SECS -- five minutes 6 MINS (-60) SECS -- five minutes 2 MINS 3 MINS -- NOT VALID (MINS twice) 10 SECS 5 MINS -- NOT VALID (out of order) 1 DAYS 6.5 HOURS -- valid (x * y + z) SECS -- valid h HOURS m MINS s SECS -- valid Max (x,y) DAYS -- valid 0.5 MINS -- 30 seconds 0.125 DAYS -- three hours 0.01667 HOURS -- one minute
CAB
CAB uses the Visual Basic .NET DateTime class for time declarations and
equivalent manipulations. VB's system.timespan and system.datetime routines handle time.
How used Refer to Visual Basic documentation--the variations in time storage and
in CAB
manipulation are too large for this table.
First seen R210 in this release
Remarks
- 441 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.15
DEFINE
Definition
A keyword used to define single-statement functions to be used in CL.
How used in CL/AM
DEFINE sign(x) = (WHEN x > 0: 1; & WHEN x = 0: 0; & WHEN x < 0: -1)
CAB equivalent CAB uses Visual Basic techniques, which do not use the "define" keyword, and which are not restricted to one-line functions.
How used in CAB
Function ProcessWrite() As Integer ' returns an Integer Dim I As Integer ... ' some calculations Return I End Function
First seen in this release
R210
Remarks
18.16
ELSE
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Used for program control flow. See "IF." CAB uses Visual Basic program control flow techniques. See "IF." R210
18.17
EMERGENCY
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.18
END
Definition
END Statement This must be the last statement of a block, subroutine, CDS, parameter list, or package. Execution of this statement is identical to the EXIT statement.
- 442 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
How used PACKAGE PARAM_LIST plist1 ... END plist1 CUSTOM ... END CUSTOM BLOCK fred in CL/AM (generic; at general) ... END fred END PACKAGE
CAB
CAB uses Visual Basic techniques.
equivalent
How used in CAB
Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() 'TODO: User should insert their Execute code here ... End Sub Sub SetOutputsToBad() ... End Sub End Class
First seen in this release
R210
Remarks
18.19
ENUMERATION
Definition
Enumeration data types recognized by CL include the following: l Honeywell-defined standard enumerations. Examples include MODE, PTEXECST, and ALENBST.
l Customer-defined standard enumerations. These are defined by the CL ENUMERATION statement.
l Self-defined enumerations (where the customer defines the state names). Examples are the PVs of digital points and flag points.
l Enumerations defined in the CL context only
l LOCAL flavors: chocolate/vanilla/strawberry The only operations defined on Enumeration types are assignment and comparison for equality and inequality.
How used LOCAL flavors : chocolate/vanilla/strawberry LOCAL myflavor : flavors ... SET in CL/AM myflavor = vanilla
CAB equivalent
CAB cannot create self-defining enumerations for use in Experion. CAB Type coding, when referring to Experion PKSenumerations, can only operate on the ordinal values of those enumerations' states. CAB, through Visual Basic, supports construction and use of VB enumerations inside CAB code. Refer to Visual Basic documentation and example below.
How used in CAB
(From Visual Basic documentation.)Enum SecurityLevel IllegalEntry = -1 MinimumSecurity = 0 MaximumSecurity = 1 End Enum You must qualify every reference to an enumeration member, either with the name of an enumeration variable or with the enumeration name itself. For example, in the preceding example, you can refer to the first member as SecurityLevel.IllegalEntry, but not as IllegalEntry.
First seen N/A, except for Visual Basic native capabilities which are first seen in R210 in this release
Remarks
- 443 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.20
ERROR
Definition Error is a compiler reserved word in CL.
How used in CL/AM
WHEN ERROR clause [syntax error_clause :: = (WHEN ERROR non_if)] ERROR reserved word (just a general statement that the keyword "ERROR" cannot be used as a variable name. A general discussion of CL/AM error handling, for all CL/AM functions and add-on functions, is not appropriate for this mapping table. Refer to the latest CL/AM Reference Manual for the definitive discussion.
CAB
There is no CAB direct equivalent. CAB uses a combination of Experion PKSerror
equivalent handling techniques, and Visual Basic .NET error handling techniques.
How used A general discussion of CAB error handling is not appropriate for this mapping table.
in CAB
Refer to the description of each function in the CAB User's Guide for the definitive
discussion.
First seen N/A in this release
Remarks
18.21
EU
Definition EU is an attribute of a parameter. Parameters are defined in a CDS definition. The EU attribute defines the parameters Engineering Units.
How used PACKAGE CUSTOM PARAMETER pt1 : $REG_CTL EU "PT_IDENT" VALUE a100 -- a in CL/AM valid system point identifier END CUSTOM ... END PACKAGE (Other Examples) EU
"pounds" EU "gallons" EU "days"
CAB equivalent
CABs each have an FDP named EUDESC, which is typically used to describe engineering units of the block. CDPs do not support an EU attribute that can be specified as part of their definition. Instead, you can specify string valued CDPs to hold EU descriptors for other CDPs. This can be done equivalently for CAB types and CDB types. One advantage of this approach is that it can be applied to many situations.
How used in CAB
Example (CPEU as the EU container for CP): CDP: Name - CP; Desc: "Heat capacity of liquid"; Type: Float; Access: Engineer; Config load: Load; Default Value: 0.75 CDP: Name - CPEU; Desc: "Heat capacity of liquid"; Type: String; Access: Viewonly; Config load: Load; Default Value: "Joules / Liter"
First seen R210 in this release
Remarks
18.22
EXIT
Definition When the EXIT statement is executed in a subroutine, it returns control to the subroutine's caller. When executed in a main program, it terminates the program. A program termination resulting from the execution of an EXIT statement is
- 444 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
considered a normal termination (as opposed to that caused by the ABORT statement). Executing an EXIT statement is equivalent to falling off the end of a program.
How usedin CL/AM
-- BLOCK BTUswPV (GENERIC $REG_CTL; AT pv_alg) -- -- This routine performs the functions of PMX PV algorithm No. 102. -- (HTCALC) -- Calculate the total heat input to the furnace. -- First, test input variables. -- IF (oilpnt.pvautost<>normal)or (gaspnt.pvautost<>normal) & THEN EXIT -- -- Now solve for the total heat input. -SET PVCALC = HG*CG*GASPNT.PV+ HO*CO*OILPNT.PV SET PVAUTOST=NORMAL END BtuswPV
CAB equivalent
CAB uses Visual Basic program syntax. This excerpt from VB documentation explains the use of EXIT in VB. The Exit statement allows you to exit directly from any decision structure, loop, or procedure. It immediately transfers execution to the statement following the last control statement. The syntax for the Exit statement specifies which type of control statement you are transferring out of. The following versions of the Exit statement are possible:
l Exit Select, Exit Try, Exit Do, Exit While, Exit For You can also exit directly from a Function, Sub, or Property procedure; the syntax is similar to that of Exit For and Exit Do:
l Exit Sub, Exit Function, Exit Property Exit Sub, Exit Function, and Exit Property can appear as many times as needed, anywhere within the body of the procedure. They can even appear inside a control statement such as If...Then...Else. These statements are useful when a procedure has done everything it needs to do and can return immediately. "Return" can also be used to exit functions, subroutines, and properties.
How usedin CAB
For I = 0 To 4 If IsNaN(TEMP(I).Value) Or IsNaN(POSITION(I).Value) Then SetOutputsToBad() Exit For Else ... (Another example)If Restart = BlockLoad Then ' For each CMRef assign the PRefs and check for consistency. ' If inconsistency is found, flag bad configuration. If Not SetUpCMRef(0, EXECSTATE1, MODEATTR1, MODE1) Then IllegalNullRef = True Exit Sub End If
This example uses the Return statement several times to return to the calling code when the procedure does not need to do anything else.Public Function GetAgePhrase(Age As Integer) As String If Age > 60 Then Return "Senior"If Age > 40 Then Return "Middle-aged" If Age > 20 Then Return "Adult" If Age > 12 Then Return "Teen-aged" If Age > 4 Then Return "School-aged" If Age > 1 Then Return "Toddler" Return "Infant"End Function
First seen R210 inthis release
Remarks
18.23
EXTERNAL
Definition
CL/AM statements can read/write/compare the parameters of other LCN data points (those external to the Bound Data Point), both on and off-LCN, through both direct and indirect references to the point and parameter names, using dot notation (and the PIN identifier for off-LCN points). A direct reference to a data point parameter external to the Bound Data Point requires an EXTERNAL declaration. The point and parameter names of direct references must exist as valid references and data types at compile time. If an off-LCN point is referenced directly in a CL Block using the EXTERNAL statement, the Block must either be linked to a point on the Internetwork Point Processor (IPP), or be at the BACKGRND insertion point. This is checked by the linker.
- 445 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
How usedin CL/AM
BLOCK dir (GENERIC: AT PRE_GI) EXTERNAL A100 -- A100 is the name assigned to a -- previously built on-LCN data point EXTERNAL ab\C100 -- C100 is the name assigned to a -- previously built off-LCN data point IF A100.SP > ab\C100.SP THEN SEND: "A100's SP is larger" -- reads the sp of point A100 and point -- ab\C100 and sends a message if -- A100's SP is larger than ab\C100's SP ELSE SEND : "ab\C100's SP is larger" -- otherwise send a message that -- ab\C100's SP is larger END dir
CAB
CAB uses PRefs, which are traditional process control data elements that exist
equivalent external to the CAB but whose values can be used within the CAB. PRefs are
configured on the Parameter References tab of the PDE in the Microsoft Visual
Studio Development Environment within Control Builder. CAB Types are always
generic. In a CAB Type, no direct reference to a target or source for a PRef can be
made. CAB Instances are created, at configuration time, from CAB Types. All
references that bind the instance to specific equipment and specific external
function blocks are contained within the instance.
How usedin CAB
From the following PDE entry, the Parameter Reference "MIXTANKSP" is created.
We could consider it to be an external reference, because it has the capability to refer to data sources and targets outside of the Control Module containing the CAB instance, and even off-node from the ACE Node containing the CEE that the CAB instance is executing within. Here is a simple example of CAB code using this PRef:Public Class CABlock Inherits BlockBase Public Overrides Sub Execute() 'TODO: User should insert their Execute code here MIXTANKSP.Read() MIXTANKSP.Value = MIXTANKSP.Value + 12 MIXTANKSP.Write() End Sub End Class At configuration time, the PRef is assigned to a source/target.
First seen R210, with Dynamic Re-referencing (the ability to change the reference at run-time
inthis
in addition to configuration time) introduced in R300.
release
Remarks
18.24
FAIL
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
- 446 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.25
FOR
Definition
Used for program control flow. "LOOP," "FOR," "IN," and "REPEAT" are a part of this flow control. See "LOOP."
How used in CL/AM
See "LOOP."
CAB equivalent CAB uses Visual Basic program control flow techniques. "For" "To," "Exit For," and "Next" are a part of this flow control.
How used in CAB
See "LOOP."
First seen in this release
R210
Remarks
18.26
FROM
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
FROM is a CL/AM compiler reserved word, but is not a part of the CL/AM syntax. Not used in CL/AM. No equivalent necessary. N/A N/A
18.27
FUNCTION
Definition
A CL/AM program can define single-statement functions. These functions are conceptually like statement functions in Fortran. They are valid for only the program in which they are defined, and any subroutines compiled with that program. Function declarations can be intermixed with data declarations.
How used See "DEFINE." in CL/AM
CAB
CAB uses Visual Basic techniques, which do not use the "define" keyword, and
equivalent which are not restricted to one-line functions.
How used See "DEFINE." in CAB
First seen R210 in this release
Remarks
- 447 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.28
GENERIC
Definition
A CL/AM program written so that it can be bound to any of several similar data points is called generic. A generic program does not specify a particular point id in its heading, but is bound to a specified point on the local LCN at link time. Any parameters of the Bound Data Point that are referenced in the program must have their names and data types defined to the compiler but they are not required to exist until the CL program is linked to an AM point.
How used in CL/AM
BLOCK cusc2 (GENERIC ; AT GENERAL) PARAMETER running : LOGICAL -- defines one logical PARAMETER numarray : NUMBER ARRAY (1..10) -- parameter and an -array of numbers -- The custom parameters "running" and "numarray" must exist on the -- AM data point when the CL is linked to it -- When "running" parameter is true, move 10th number to first number IF running = ON THEN (SET numarray(1) = numarray(10); & SET running = OFF) ELSE SEND: "cusc2 is not running" END cusc2
CAB
No equivalent is necessary. All CAB Types are generic. None are bound at Type
equivalent creation time. CAB instances, created from CAB Types, are bound at configuration
time.
How used N/A in CAB
First seen R210 in this release
Remarks
18.29
GOTO
Definition Used for program control flow.
How used IF BADVAL(x) THEN GOTO badpv ELSE (SET pvcalc = x; & SET pvautost = normal; & in CL/AM EXIT) - - - - One or more of the inputs required to calculate heat density is - - bad;
therefore, set the pv bad and exit. - - badpv : CALL SET_BAD (pvcalc)
CAB
CAB uses Visual Basic program control flow techniques. GOTO is available (see
equivalent below), but we recommend more structured code flow control routines.
How used in CAB
(This example is from Visual Basic documentation.)Sub GotoStatementDemo() Dim Number As Integer dim MyString As String Number = 1 ' Initialize variable. ' Evaluate Number and branch to appropriate label. If Number = 1 Then GoTo Line1 Else GoTo Line2 Line1: MyString = "Number equals 1" GoTo LastLine ' Go to LastLine. Line2: ' The following statement never gets executed because Number = 1. MyString = "Number equals 2" LastLine: ' Print "Number equals 1" in the Output window. ' Debug.WriteLine (MyString) (This is not a valid CAB statement.) End Sub
First seen R210 in this release
Remarks
- 448 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.30
HANDLER
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.31
HELP
Definition
HELP, a reserved word, is mentioned in CL/AM syntax production rules ... help_ attribute :: = HELP String ... but is not further used in production rules, or as an identifier or built-in function or subroutine.
How used N/A in CL/AM
CAB
No equivalent necessary.
equivalent
How used N/A in CAB
First seen N/A in this release
Remarks
18.32
HOLD
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
- 449 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.33
HOURS
Definition Part of a time literal.
How used in CL/AM
Time Literals Examples: 5 MINS -- five minutes 300 SECS -- five minutes (1/12) HOURS -- five minutes 4 MINS 60 SECS -- five minutes 6 MINS (-60) SECS -- five minutes 2 MINS 3 MINS -- NOT VALID (MINS twice) 10 SECS 5 MINS -- NOT VALID (out of order) 1 DAYS 6.5 HOURS -- valid (x * y + z) SECS -- valid h HOURS m MINS s SECS -- valid Max (x,y) DAYS -- valid 0.5 MINS -- 30 seconds 0.125 DAYS -- three hours 0.01667 HOURS -- one minute
CAB
CAB uses the Visual Basic .NET DateTime class for time declarations and
equivalent manipulations. Visual Basic's system.timespan and system.datetime routines handle
time.
How used Refer to Visual Basic documentation-the variations in time storage and
in CAB
manipulation are too large for this table.
First seen R210 in this release
Remarks
18.34
IF
Definition Used for program control flow.
How used IF i <> -1.0 THEN SEND: "gtslt is cl slot", i ELSE SEND: "gtslt not found" in CL/AM
CAB
CAB uses Visual Basic program control flow techniques.
equivalent
How used in CAB
Example: If Response <> Succeeded Then Return Response Else Response = Check1ParameterWrite(CMRef(I).Mode) If Response <>Succeeded Then Return Response End If
First seen in this release
R210
Remarks
18.35
IN
Definition
Used for program control flow. "LOOP," "FOR," "IN," and "REPEAT" are a part of this flow control. See "LOOP." Used to define data flow direction for subroutine arguments. See "SUBROUTINE."
How used See "LOOP." See "SUBROUTINE." in CL/AM
CAB
CAB uses Visual Basic program control flow and subroutine data-passing
- 450 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
equivalent techniques.
How used See "LOOP." See "SUBROUTINE." in CAB
First seen in this release
R210
Remarks
18.36
INITIATE
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.37
LOCAL
Definition
Keyword to define local variables or constants. Local variables are declared in the heading of a sequence program, block, or CL/AM subroutine. In the AM, their lifetime is that of the program; when the program or subroutine exits, its local variables cease to exist. Local constants of the data types Number and Time can be declared.
How usedin CL/AM
Examples of local variables: LOCAL x, y, z: NUMBER -- three local numbers LOCAL i, j, k -- three more (default) LOCAL pop: coke/pepsi/7up -- enumeration LOCAL color: red/green/amber -- another LOCAL hue: amber/green/red -- incompatible with "color" LOCAL foo: LOGICAL ARRAY (1..5) -- an array LOCAL bar: ARRAY (1..16, 1..16) -- a 2-d number array LOCAL sam: NUMBER ARRAY (Mode) -- indexed by enumeration LOCAL p: up/down ARRAY (1..5) -- enumeration array Examples of local constants: LOCAL pi = 3.14159265 -- a numeric constant LOCAL ten_K = 1.0e4 - another LOCAL 2_pi = pi * 2 -- a constant expression LOCAL pi_2 = pi/2 -- illegal: divide operator LOCAL mix_time = 2 HOURS 5 MINS -- a Time constant
CAB
Local variables are declared within the Execute() subroutine that is included in the
equivalent skeleton code framework supplied by Honeywell. The Execute() subroutine is where
you insert your custom algorithm code. Values of local variables are not persistent
from one block execution to the next. Visual Basic uses the keyword "Dim," for
Dimension, instead of "Local."
How usedin CAB
Public Class CABlock Inherits BlockBase Private K As Double ' Calculate internal vapor/liquid ratio for any column Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim W1, WV, Ratio As Double ' Local Variables 'Make value and status available for all input parameter references PRefList.Read() 'Calculate constant used to compute flow rate K = CP.Value / LAMBDA.Value 'Calculate internal liquid flow rate from ' heat and material balance W1 =
- 451 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
((TOPT.Value - RFXT.Value) * K + 1) * _ RFXFLOW.Value + (TOPT.Value - _ TRAYT.Value) * _ DRAWFLOW.Value * K ' Calculate internal vapor flow rate from material balance WV = DRAWFLOW.Value + W1 ' Calculate vapor/liquid ratio and store as PV Ratio = WV / W1 PVCALC.Value = Ratio 'Store values to destination for any output references whose values were written PRefList.Write() End Sub End Class
First seen R210 inthis release
Remarks
18.38
LOOP
Definition
Used for program control flow. "LOOP," "FOR," "IN," and "REPEAT" are a part of this flow control. The LOOP statement's FOR clause names a counter variable which must be a scalar local variable or scalar subroutine argument of data type Number. The upper and lower bounds of the range are evaluated. If their values are not integers, they are rounded to the nearest integer. In CL/AM, the upper bound of the FOR range is evaluated only when beginning the loop. The lower bound must be stated first. The counter variable is initialized to the value of the lower bound. Each time that loop's REPEAT statement is executed, the counter variable is incremented by 1. If that value does not exceed the range's upper bound (previously computed), the loop is repeated; otherwise the loop terminates. On normal exit from the loop, the counter variable is equal to the final expression plus 1. If the LOOP statement does not contain a FOR clause, it never normally terminates. It can be exited by a GOTO or EXIT statement, or by the occurrence of an abnormal condition. A LOOP statement must have a label. The target of a REPEAT statement must be a label in the current block or subroutine. The label_ID must define a loop; i.e., the label referred to must have a LOOP statement attached to it. A loop can have only one REPEAT statement. REPEAT statements are contextually, although not syntactically, bound to the LOOP statement having the given label.
How usedin CL/AM
BLOCK ex1 (GENERIC; AT GENERAL) LOCAL i EXTERNAL ct\contrlpt -- direct reference to a point on LCN ct -- label: LOOP FOR i IN 1..5 IF (fepoints(i).pv<>fepoints (i).sp) OR (fepoints(i).sp<>ct\contrlpt.sp) & THEN SEND : "mismatch on LCN fe on element number", i -- example of referencing off-LCN points directly and indirectly IF (azpoints(i).pv<>azpoints(i).sp) OR (azpoints(i).sp<>ct\contrlpt.sp) & THEN SEND :"mismatch on LCN az on element number", i REPEAT label END ex1 Conditional REPEAT: setx: LOOP FOR i IN 1 .. 5 SET x.SP = 2 IF x.PV <> 2 THEN (REPEAT setx; & SEND: "x.PV bad"; & FAIL) Nested REPEAT: outer: LOOP FOR i IN 1 .. 10 inner: LOOP FOR j IN 1 .. i SET a (i, j) = -1.0 REPEAT inner REPEAT outer
CAB
CAB uses Visual Basic program control flow techniques. "For" "To," "Exit For," and
equivalent "Next" are a part of this flow control. "Loop" is used in Visual Basic, but not for a
"For" loop - rather, "Loop" is used as the closing identifier for a "Do" loop.
How usedin CAB
Example: Public Overrides Sub Execute() 'TODO: User should insert their Execute code here Dim I As Integer If Restart <> None Then DoInitialize() SetOutputsToBad() AVGTEMP.Value = 0.0 For I = 0 To 4 If IsNaN(TEMP(I).Value) Or_ IsNaN(POSITION (I).Value) Then SetOutputsToBad() Exit For Else AVGTEMP.Value = AVGTEMP.Value_ + TEMP(I).Value If IsNaN(MAXTEMP.Value) Or_ MAXTEMP.Value < _TEMP(I).Value Then MAXTEMP.Value = TEMP(I).Value MAXPOS.Value = POSITION(I).Value End If If Not (MINTEMP.Value <= TEMP(I).Value) Then MINTEMP.Value = TEMP(I).Value MINPOS.Value = POSITION(I).Value End If End If Next I AVGTEMP.Value = AVGTEMP.Value / 5 End Sub
- 452 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
First seen R210 inthis release Remarks
18.39
MINS
Definition Part of a time literal.
How used in CL/AM
Time Literals Examples 5 MINS -- five minutes 300 SECS -- five minutes (1/12) HOURS -- five minutes 4 MINS 60 SECS -- five minutes 6 MINS (-60) SECS -- five minutes 2 MINS 3 MINS -- NOT VALID (MINS twice) 10 SECS 5 MINS -- NOT VALID (out of order) 1 DAYS 6.5 HOURS -- valid (x * y + z) SECS -- valid h HOURS m MINS s SECS -- valid Max (x,y) DAYS -- valid 0.5 MINS -- 30 seconds 0.125 DAYS -- three hours 0.01667 HOURS -- one minute
CAB
CAB uses the Visual Basic .NET DateTime class for time declarations and
equivalent manipulations. Visual Basic's system.timespan and system.datetime routines handle
time.
How used Refer to Visual Basic documentation-the variations in time storage and
in CAB
manipulation are too large for this table.
First seen R210 in this release
Remarks
18.40
MOD
Definition
Built-in arithmetic operator. Returns the remainder of a division between two numbers. There is no separate Integer type in CL/AM; numbers may, of course, have integer values, and CL/AM built-in functions support truncation and rounding of non-integer values. In CL, the MOD operator, usually used to obtain the fractional remainder from an integer division, also can be applied to non-integer values. (In CL, the MOD value is calculated by subtracting the INT value of a divide result from the divide result.)
How used SET C = A MOD B in CL/AM
CAB
CAB uses Visual Basic syntax and techniques. The MOD operator is supported.
equivalent
How used in CAB
(This is from Visual Basic documentation.) This example uses the Mod operator to divide two numbers and return only the remainder. If either number is a floatingpoint number, the result is a floating-point number representing the remainder. Dim myResult As Double myResult = 10 Mod 5 ' Returns 0. myResult = 10 Mod 3 ' Returns 1. myResult = 12 Mod 4.3 ' Returns 3.4. myResult = 12.6 Mod 5 ' Returns 2.6. myResult = 47.9 Mod 9.35 ' Returns 1.15.
First seen R210 in this
- 453 -
release Remarks
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.41
NAME
Definition
NAME is a compiler reserved word in CL.
How used in CL/AM
NAME reserved word (just a general statement that the keyword "NAME" cannot be used as a variable name.
CAB equivalent No equivalent necessary.
How used in CAB N/A
First seen in this N/A release
Remarks
18.42
NOT
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Logical operator. See "LOGICAL." Visual Basic Boolean operator. See "LOGICAL." R210
18.43
OR
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Logical operator. See "LOGICAL." Visual Basic Boolean operator. See "LOGICAL." R210
- 454 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.44
OTHERS
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Part of a conditional SET statement. See "SET." See "SET." See "SET." R210
18.45
OUT
Definition
How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Used to define data flow direction for subroutine arguments. See "SUBROUTINE." See "SUBROUTINE." CAB uses Visual Basic subroutine data-passing techniques. See "SUBROUTINE." R210
18.46
PACKAGE
Definition PACKAGE collects Parameter Lists, CDSs, and CL Blocks into a grouping that can be bound to a point.
How usedin CL/AM
PACKAGE -- CL source file (e.g., entid.cl) PARAM_LIST refptr PARAMETER running : LOGICAL -- defines a logical parameter and PARAMETER numarray : NUMBER ARRAY(1..10) -- an array of numbers END refptr CUSTOM PARAMETER cuspt : refptr -- Parameter of type point id PARAMETER regpt : $REG_CTL -- Parameter of type point id used END CUSTOM BLOCK entcl (GENERIC; AT GENERAL) IF cuspt.running = ON THEN (SET cuspt.numarray(1) = cuspt.numarray(10); & SET cuspt.running = OFF) ELSE SEND: "entcl is not running" IF regpt.MODE = MAN THEN SEND: "mode is manual" IF regpt.OP > 50 THEN SEND: "op > 50" IF regpt.SP < 50 THEN SEND: "sp < 50" SEND: "pv is ", regpt.PV END entcl END PACKAGE
CAB
CAB and Experion do not use the PACKAGE concept. Control Builder collects
equivalent functions and data structures (native function blocks, CABs, CDBs) into Control
Modules, and attaches Control Modules to execute in CEEs and exchange data with
each other. Experion PKSdoes not have the concept of Parameter Lists or CDSs, but
CDBs offer a centralized data location, and each CAB can have its own list of
parameters.
How usedin CAB
Control Builder and Control Modules are fundamental Experion PKSconcepts. Refer to Control Builder documentation for more information.
- 455 -
First seen R210 inthis release
Remarks
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.47
PARALLEL
Definition
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
PARALLEL is a reserved word, but is not mentioned in CL/AM syntax production rules, or as an identifier or built-in function or subroutine. N/A
No equivalent necessary.
N/A
N/A
18.48
PARAM_LIST
Definition
How used in CL/AM CAB equivalent How used in CAB
A parameter list is a list of the names and types that the parameters of a data point can have. At compile time, the compiler can refer to a parameter list to get a description of the referenced data points; as such, the parameter list serves as a surrogate for the on-process database (because the database may not yet be fully described).
PARAM_LIST my_PList PARAMETER PV, SP: Number PARAMETER OP -Number by default PARAMETER Specvals: ARRAY(1..12) PARAMETER Backup: my_PList END my_PList
CAB uses a graphical PDE to describe parameters for the CAB Type.
The PDE for CAB is shown below.
style="width:400px;height:161px;"/>
First seen in this release
Remarks
R210
- 456 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.49
PAUSE
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.50
PHASE
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.51
POINT
Definition
The POINT keyword is used to define a specific CL/AM program. A CL/AM program written so that it can only be bound to one specific point is called specific. Any parameter of the data point identified in the program header can be referenced in the program without need to specify the parameter name and data type. The point named in the header must exist at compile time, must be an AM Regulatory, Switch, or Custom point, and must be on the local LCN.
How used in CL/AM
BLOCK somename (POINT reg44; AT PRE_GI) -- The compiler "understands" the parameters pv and mode, -- and their data types. IF pv > 10.0 THEN SEND : "PV of reg44 is in trouble" IF mode = man THEN SEND : "mode of reg44 is manual" END somename
CAB
CAB Types are always generic-that is, CAB Types are never tied or bound to a specific
equivalent "point," or other Experion PKSstructure, at compile time. At configuration time,
Value Custom Data Parameters associated with the CAB Type can be connected to
other function block parameters <control_module.block.parameter> via graphical
means using Control Builder. Also, at configuration time, PRefs associated with the
CAB Type can be connected to data sources and targets <control_
module.block.parameter> by updating their references. With Dynamic Re-
referencing, PRefs can have their references modified at run time, and the PRefs
will re-resolve and then use the new reference without a need to stop and
reconfigure.
How used See CAB and Control Builder documentation on CDPs and PRefs. in CAB
- 457 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
First seen R210. Dynamic Re-referencing is introduced in R300. in this release Remarks
18.52
RANGE
Definition
RANGE is a compiler reserved word not otherwise used in CL/AM. Range is also a CL/AM feature, another use of the reserved word "IN." Range tests (x IN y..z, a NOT IN b..c) are defined on only Number data type. The test is inclusive; for example, 5 IN 5..10 is true. The value of the left-most expression in range must be less than the value in the right-most expression.
How used IF x NOT IN 1..10 THEN (SEND: "range error", x; & GOTO retry) in CL/AM
CAB
No direct equivalent exists.
equivalent
How used In CAB, a programmer would need to test "greater than or equal to" the lower
in CAB
bound, AND "less than or equal to" the upper bound, to duplicate the intent of this
built-in function.
First seen N/A in this release
Remarks
18.53
READ
Definition
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
READ is a reserved word, but is not mentioned in CL/AM syntax production rules, or as an identifier or built-in function or subroutine. N/A
No equivalent necessary.
N/A
N/A
- 458 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.54
REFERENCE
Definition
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
REFERENCE is a reserved word, but is not mentioned in CL/AM syntax production rules, or as an identifier or built-in function or subroutine. N/A
No equivalent necessary.
N/A
N/A
18.55
REFERENCE_N
Definition
REFERENCE_N is a reserved word, but is not mentioned in CL/AM syntax production rules, or as an identifier or built-in function or subroutine.
How used in N/A CL/AM
CAB equivalent
No equivalent necessary.
How used in N/A CAB
First seen in N/A this release
Remarks
18.56
RELAX
Definition RELAX is a linker directive to relax certain link-time checks for self-defining enumerations.
How used %RELAX Linker_SDE_Checks -- must come before first -- executable statement in CL/AM
CAB equivalent
CAB, through Visual Basic, supports the construction and use of VB enumerations inside CAB code. Refer to Visual Basic documentation (and see the example below). CAB does not support access to Experion PKSenumerations held in Experion PKSdatabases in anything but ordinal form. For relaxing or tightening compiler checks, CAB has a different structure than CL/AM, using .NET and Visual Studio techniques for enforcing various compile-time and link-time directives.
How used (From Visual Basic documentation.) Enum SecurityLevel IllegalEntry = -1 in CAB
- 459 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
MinimumSecurity = 0 MaximumSecurity = 1 End Enum You must qualify every reference to an enumeration member, either with the name of an enumeration variable or with the enumeration name itself. For example, in the preceding example, you can refer to the first member as SecurityLevel.IllegalEntry, but not as IllegalEntry.
First seen N/A in this release
Remarks
18.57
REPEAT
Definition
Used for program control flow. "LOOP," "FOR," "IN," and "REPEAT" are a part of this flow control. See "LOOP."
How used in CL/AM
See "LOOP."
CAB equivalent CAB uses Visual Basic program control flow techniques. "For" "To," "Exit For," and "Next" are a part of this flow control.
How used in CAB
See "LOOP."
First seen in this release
R210
Remarks
18.58
RESTART
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.59
RESUME
Definition How used in CL/AM
A compiler reserved word used in CL/PM. Not used in CL/AM.
- 460 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
CAB equivalent How used in CAB First seen in this release Remarks
No equivalent necessary. N/A N/A
18.60
SECS
Definition Part of a time literal.
How used in CL/AM
Time Literals Examples 5 MINS -- five minutes 300 SECS -- five minutes (1/12) HOURS -- five minutes 4 MINS 60 SECS -- five minutes 6 MINS (-60) SECS -- five minutes 2 MINS 3 MINS -- NOT VALID (MINS twice) 10 SECS 5 MINS -- NOT VALID (out of order) 1 DAYS 6.5 HOURS -- valid (x * y + z) SECS -- valid h HOURS m MINS s SECS -- valid Max (x,y) DAYS -- valid 0.5 MINS -- 30 seconds 0.125 DAYS -- three hours 0.01667 HOURS -- one minute
CAB
CAB uses the Visual Basic .NET DateTime class for time declarations and
equivalent manipulations. Visual Basic's system.timespan and system.datetime routines handle
time.
How used Refer to Visual Basic documentation--the variations in time storage and
in CAB
manipulation are too large for this table.
First seen R210 in this release
Remarks
18.61
SEND
Definition
The SEND statement sends a message to the operator of the Bound Data Point's ProcessUnit. It also can be used to request the issuing of Event Initiated Reports. These messages go to both the operator's CRT and Log device, unless the destination is specified as CRT_Only or Log_Only.
How used SEND: "Begin cleanup" SEND CRT_Only: "This is a CRT message" in CL/AM
CAB
Subroutine Send() allows text to be sent to the operator message display. Messages
equivalent appear in those consoles mapped to the area assigned to the parent CM of the CAB
instance. Send() supports a single string argument that can be up to 132 characters
long. Each string sent corresponds to one line in the message display. The single
argument of Send() can be constructed using the inherent string conversion
capabilities of VB.NET. In the example below, Send()is used to present a string literal
and floating-point values. ReportPressValues is a local Boolean variable and the
array Press is a block scope variable. The VB.NET line continuation character, "_," is
used to put multiple floating point values on a single message line even though they
do not conveniently fit into a single line of source code.
How used If ReportPressValues Then Me.Send("Pressure Array:") Send(Press(0).ToString + " "
in CAB
+ Press(1).ToString + " " + Press(2).ToString + " " + Press(3).ToString +_ " " + Press
- 461 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
(4).ToString) Send(Press(5).ToString + " " +_ Press(6).ToString +_ " " + Press (7).ToString + " " +_ Press(8).ToString + Press(9).ToString) End If First seen R210 in this release Remarks
18.62
SEQUENCE
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.63
SET
Definition
A SET statement with a simple expression on the right-hand side of the equal sign unconditionally assigns the value of that expression to each of the variables on the left side of the equal sign. The assignments are executed in reverse order from the order in which the variables are declared. A SET statement whose right-hand side begins with (WHEN... is called a conditional SET statement. When this statement is executed, its WHEN conditions are successively evaluated, until a true condition is found. The expression corresponding to the true condition is then evaluated and its value is assigned to the variables on the left-hand side of the equal sign. After one true condition is found, no other conditions are evaluated. Execution proceeds with the next statement. The data type of the assignment on the right-hand side must match the data type of the variable(s) on the left-hand side. A conditional SET statement can have any number of WHEN clauses. The last WHEN clause can name the special condition OTHERS, which is always true.
How usedin CL/AM
SET x = x + 1 -- simple SET SET x, y, z = 0 -- multiple SET -- first z is set to 0, -- then y is set to 0 -- then x is set to zero last SET color = (WHEN x > lim: red; -- conditional SET & WHEN x < lim-db: green; & WHEN OTHERS: yellow) SET ab\A100.sp, x,m4\A122.t2 = 44 -- SET referencing off-LCN points
CAB
Visual Basic does not use a SET statement. Assignments are direct, to the left side of
equivalent an "=" sign, from the expression to the right of the "=" sign. Visual Basic uses a
WHEN statement. However: WHEN in Visual Basic is not used for conditional
assignment, but is reserved for use in exception handling, as a conditional applied to
Try..Catch..Finally routines. For conditional execution (and thus possibly as a
substitute for conditional assignment), Visual Basic has the Select..Case statement.
How usedin CAB
(This is an example of a simple assignment statement.) MIXTANKSP.Value = 12 (This is an example of a Select..Case statement, from Visual Basic documentation.)Function Bonus(ByVal Performance As Integer, ByVal Salary As
- 462 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
Decimal) _ As Decimal Select Performance Case 1 ' Performance is 1. Return Salary * 0.1 Case 2, 3 ' Performance is 2 or 3. Return Salary * 0.09 Case 5 To 7 ' Performance is 5, 6, or 7. Return Salary * 0.07 Case 4, 8 To 10 ' Performance is 4, 8, 9, or 10. Return Salary * 0.05 Case Is < 15 ' Performance is 11, 12, 13, or 14. Return 100 Case Else ' Performance is < 1 or > 14. Return 0 End Select
First seen R210 inthis release
Remarks
18.64
SHUTDOWN
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.65
STEP
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word - used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.66
SUBROUTINE
Definition Used to define a subroutine callable by the CALL statement. CL/AM enforces data flow direction for subroutine arguments, using OUT, IN, and IN OUT.
How used in CL/AM
SUBROUTINE sub1 (x : state1/state2; y : OUT off/on) SUBROUTINE sub2 (index; log1 : IN OUT LOGICAL) SUBROUTINE sub3 (flag : IN LOGICAL; num1 : IN NUMBER; output : & OUT NUMBER) SUBROUTINE sub4 (a : IN NUMBER) SUBROUTINE sub5 (arr1 : IN OUT LOGICAL ARRAY (1..3)) SUBROUTINE sub6 (status : IN mode; value1, value2 :IN OUT NUMBER) SUBROUTINE sub7 (state : IN open/close/bad/moving/inbtwn)
- 463 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
CAB equivalent
CAB uses Visual Basic. Visual Basic's argument-passing syntax does not include the concepts of in-only or out-only, but enables each argument to be both, and to be passed by reference or by value. Passing an argument by value is somewhat analogous to "IN,"because modifications to the value from inside the subroutine will not be visible to the calling routine.
How used in CAB
(This example is from Visual Basic documentation.)' Sub procedure definition. ' Sub procedure with two arguments. Sub SubComputeArea(ByVal Length As Double, ByVal Width As Double) Dim Area As Double ' Declare local variable. If Length = 0 Or Width = 0 Then ' If either argument = 0. Exit Sub ' Exit Sub immediately. End If Area = Length * Width ' Calculate area of rectangle. Debug.WriteLine(Area) ' Print Area to Immediate window. End Sub
First seen R210 in this release
Remarks
18.67
THEN
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Used for program control flow. See "IF." CAB uses Visual Basic program control flow techniques. See "IF." R210
18.68
UNIT
Definition
How used in CL/AM
CAB equivalent
How used in CAB
First seen in this release
Remarks
UNIT is a reserved word, but is not mentioned in CL/AM syntax production rules, or as an identifier or built-in function or subroutine. N/A
No equivalent necessary.
N/A
N/A
- 464 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.69
VALUE
Definition How used in CL/AM CAB equivalent
How used in CAB
Describes a default value on a CDS.
CUSTOM PARAMETER running : LOGICAL -- defines one logical PARAMETER numarray : NUMBER ARRAY (1..10) -- parameter and an VALUE (1,2,3,4,5,6,7,8,9,10) -- array of numbers END CUSTOM
CAB does not have the equivalent of CDSs. The closest equivalent is the PDE, which has capability for CAB Type authors to specify default values for CAB Type CDPs (Custom Data Parameters). To specify a default value, the configuration load value must be set to "LOAD," as in the examples below.
The PDE for CAB is shown below.
style="width:400px;height:161px;"/>
First seen in this release
Remarks
R210
18.70
WAIT
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.71
WHEN
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Part of a conditional SET statement. See "SET." See "SET." See "SET." R210
- 465 -
Chapter 18 - Appendix B: CL/AM to CAB mapping tables-reserved words
18.72
WRITE
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
A compiler reserved word used in CL/PM. Not used in CL/AM. No equivalent necessary. N/A N/A
18.73
XOR
Definition How used in CL/AM CAB equivalent How used in CAB First seen in this release Remarks
Logical operator. See "LOGICAL." Visual Basic Boolean operator. See "LOGICAL." R210
18.74
Background execution and distributed processing
For CL/AM, Background Execution is replaced by CAB's Distributed Processing, provided in the R300Experion PKSrelease.
Distributed Processing is not available in CAB/C300.
In CL, a CL block is inserted to a point at the BACKGRND insertion point in order to run in the "background," that is, to not be limited to execution within a cycle. The block must specify, in code, the BACKGRND insertion point.
In CAB, a CAB type is designated for Distributed Processing, so that when an instance of this type executes, it is not terminated by the system at the end of 250 milliseconds (the maximum allotted time for "atomic" CABs). The type is designated as suitable for Distributed Execution at type creation time. The "Distributed Execution" CAB type is compiled with less constraints on language features available than the constraints applied to "Atomic Execution" CAB types.
On the AM, there is only one thread available for background execution, and all background CL programs are queued to that thread. The BKG_CHANGE_PRIORITY command is necessary so that the CL programs can be somewhat coordinated on the single thread available.
For CAB on ACE, Distributed Mode CAB instances are executed each on their own thread, in a separate non-real-time process. The non-real-time process does not interfere with the real-time CEE process, so each executing Distributed Mode CAB instance has less need for explicit priority control.
For Background CL, a program can use BKG_DELAY to suspend program execution for a specified period of time. For Distributed CAB types we can use the WAIT call for the same effect (R300).
- 466 -
CHAPTER
19
APPENDIX C: CONFIGURING CAB TO SUPPORT
ACCESSING FILES ON REMOTE SYSTEMS
19.1
19.1.1
Configuring the ACE process to execute under the 'mngr' account
By default, the ACE process will execute under the "Local System"account which does not have network credentials. The Administrator will have to configure the ACE process to execute under the "mngr"account. This is done by configuring the CDA-SP service on the ACE to execute under the "mngr" account.
To configure the CDA-SP service
1. Click Start > Control Panel > Administrative Tools > Services to open the Services window. 2. Locate and double-click Experion PKS CDS-SP Service to open the Properties window. 3. Click the Log On tab. 4. In the Log on as section,
l Select This account. l Click Browse and browse to the "mngr"account. l Type the "mngr" password in the Password and Confirm password text boxes.
5. Click Apply. 6. Click the General tab. 7. In the Service status section,
l Click Stop to stop the service. l Click Start to start the service under the new configured logon.
8. Click OK to close the Properties window.
19.2
Sharing a folder that you want to access files remotely from CAB
If a user wants to write a CAB program that accesses a network drive, they must first share the desired drive or folder. They must also configure the correct permissions to limit access to the share. Once they have configured a shared folder on a network drive, they can write their CAB program to access this folder. It is suggested that you create the share such that only the configured group can access the share to read/write files. You should remove the ability for anyone to execute files from this directory. This will help lock down this share from users
- 467 -
Chapter 19 - Appendix C: Configuring CAB to support accessing files on remote systems
19.2.1
performing tasks that you would not be doing with a CAB.
To share the folder that you want to access files remotely from CAB
1. If the folder does not already exist, create it. 2. Right click the folder and select the Sharing and Security ... menu item. 3. Click the Sharing tab if not already selected. 4. Select share this folder. 5. Type a share name, if you do not like the default. 6. Click Permissions. 7. By default, "Everyone" is given Read permissions to the share. You should remove this by
clicking Everyone and then Remove. 8. Click Add. 9. Click Advanced. 10. Click Find Now. 11. Click Local Engineers in the list and then click OK. 12. Click OK to close the Select Users and Groups window. 13. With Local Engineers selected, select the Change and Read check boxes but leave the Full
Control check box cleared. 14. Click OK to close the window. 15. Click the Security tab at the top of the Properties window. 16. Click Add. 17. Click Advanced. 18. Click Find Now. 19. Click Local Engineers from the list and then click OK. 20. Click OK to close the Select Users and Groups window. 21. With Local Engineers selected in the Group or User names window, make the appropriate
selections in the Permissions for Local Engineers such that only the Read and Write check boxes are selected for Allow. 22. Click Advanced. 23. Click Local Engineers from the Permission Entries pane. 24. Click Edit. 25. Add Delete subfolders and files and Delete to the list of items that were already selected. 26. Click OK to close the window. 27. Clear the Allow inheritable permissions from the parent .. check box. 28. Click OK to close the Advanced Security settings window. The Special Permissions check box should now be selected, along with the Read and Write check boxes. 29. Click OK to close the Properties window of the share. Write a CAB program to access the shared folder. To access the shared folder in your CAB program, you must use the UNC name format (such as, \\server\shared folder\filename) for the filename. You cannot use the traditional local drive format (such as w:\). This is because the shared folder is not mapped to the ACE for you to be able to access it in this manner.
- 468 -
CHAPTER
20
APPENDIX D:ECMA .NET DATA TYPES
20.1
CAB/C300 supports a subset of the ECMA .NET Value Types and Core Classes that are supported by CAB/ACE. The following sections list the classes and methods which are supported. Any class or method which is not listed in the following sections is not supported by CAB/C300.
Classes
ECMA .NET Classes supported by CAB/C300, fully or partially, are shown in the following table. Table 20.1 ECMA .NET Classes Supported By CAB /C300 Class
System.Array System.Boolean System.Boolean[,,] System.Boolean[,] System.Boolean[] System.Char System.Char[,,] System.Char[,] System.Char[] System.CharEnumerator System.DateTime System.DateTime[,,] System.DateTime[,] System.DateTime[] System.DayOfWeek System.Double System.Double[,,] System.Double[,] System.Double[] System.Enum System.Int32
- 469 -
Chapter 20 - Appendix D:ECMA .NET Data Types
System.Int32[,,] System.Int32[,] System.Int32[] System.Int64 System.Math System.Object System.Object[,,] System.Object[,] System.Object[] System.String System.String[] System.Text.StringBuilder System.TimeSpan System.TimeSpan[,,] System.TimeSpan[,] System.TimeSpan[] System.UInt32 System.ValueType System.Void
Class
20.2
Methods
ECMA .NET methods supported by CAB/C300, fully or partially, are shown in the following table.
Class System.Array
Table 20.2 ECMA .NET Methods Supported By CAB /C300 Method
Clear(System.Array,System.Int32,System.Int32)
System.Array
Clone()
System.Array
Copy(System.Array,System.Array,System.Int32)
System.Array
Copy(System.Array,System.Int32,System.Array, System.Int32,System.Int32)
System.Array
CopyTo(System.Array,System.Int32)
System.Array
GetLength(System.Int32)
System.Array
GetLowerBound(System.Int32)
System.Array
GetUpperBound(System.Int32)
- 470 -
Class System.Array System.Array System.Array System.Array System.Array System.Array System.Array System.Array System.Array System.Array System.Boolean System.Boolean System.Boolean System.Boolean System.Boolean System.Boolean System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char System.Char
Chapter 20 - Appendix D:ECMA .NET Data Types
GetValue(System.Int32)
Method
GetValue(System.Int32,System.Int32)
GetValue(System.Int32,System.Int32, System.Int32)
GetValue(System.Int32[])
Length()
Rank()
SetValue(System.Object,System.Int32)
SetValue(System.Object,System.Int32, System.Int32)
SetValue(System.Object,System.Int32, System.Int32,System.Int32)
SetValue(System.Object,System.Int32[])
CompareTo(System.Boolean)
CompareTo(System.Object)
Equals(System.Boolean)
Equals(System.Object)
Parse(System.String)
ToString()
CompareTo(System.Char)
CompareTo(System.Object)
Equals(System.Char)
Equals(System.Object)
GetNumericValue(System.Char)
GetNumericValue(System.String,System.Int32)
IsControl(System.Char)
IsControl(System.String,System.Int32)
IsDigit(System.Char)
IsDigit(System.String,System.Int32)
IsLetter(System.Char)
IsLetter(System.String,System.Int32)
IsLetterOrDigit(System.Char)
IsLetterOrDigit(System.String,System.Int32)
IsLower(System.Char)
IsLower(System.String,System.Int32)
IsNumber(System.Char)
IsNumber(System.String,System.Int32)
- 471 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class System.Char
Method IsPunctuation(System.Char)
System.Char
IsPunctuation(System.String,System.Int32)
System.Char
IsSeparator(System.Char)
System.Char
IsSeparator(System.String,System.Int32)
System.Char
IsUpper(System.Char)
System.Char
IsUpper(System.String,System.Int32)
System.Char
IsWhiteSpace(System.Char)
System.Char
IsWhiteSpace(System.String,System.Int32)
System.Char
Parse(System.String)
System.Char
ToLower(System.Char)
System.Char
ToString()
System.Char
ToString(System.Char)
System.Char
ToUpper(System.Char)
System.CharEnumerator Current()
System.CharEnumerator MoveNext()
System.CharEnumerator Reset()
System.DateTime
.ctor(System.Int32,System.Int32,System.Int32)
System.DateTime
.ctor(System.Int32,System.Int32,System.Int32, System.Int32,System.Int32,System.Int32)
System.DateTime
.ctor(System.Int32,System.Int32,System.Int32, System.Int32,System.Int32,System.Int32,System.Int32)
System.DateTime
.ctor(System.Int64)
System.DateTime
Add(System.TimeSpan)
System.DateTime
AddDays(System.Double)
System.DateTime
AddHours(System.Double)
System.DateTime
AddMilliseconds(System.Double)
System.DateTime
AddMinutes(System.Double)
System.DateTime
AddMonths(System.Int32)
System.DateTime
AddSeconds(System.Double)
System.DateTime
AddTicks(System.Int64)
System.DateTime
AddYears(System.Int32)
System.DateTime
Compare(System.DateTime,System.DateTime)
System.DateTime
CompareTo(System.DateTime)
System.DateTime
CompareTo(System.Object)
System.DateTime
Date()
- 472 -
Class System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.DateTime System.Double System.Double System.Double System.Double System.Double System.Double System.Double System.Double System.Double System.Double
Chapter 20 - Appendix D:ECMA .NET Data Types
Day()
Method
DayOfWeek()
DayOfYear()
DaysInMonth(System.Int32,System.Int32)
Equals(System.DateTime)
Equals(System.DateTime,System.DateTime)
Equals(System.Object)
Hour()
IsLeapYear(System.Int32)
Millisecond()
Minute()
Month()
Now()
Second()
Subtract(System.DateTime)
Subtract(System.TimeSpan)
Ticks()
TimeOfDay()
Today()
ToLocalTime()
ToString()
ToUniversalTime()
UtcNow()
Year()
CompareTo(System.Double)
CompareTo(System.Object)
Equals(System.Double)
Equals(System.Object)
IsInfinity(System.Double)
IsNaN(System.Double)
IsNegativeInfinity(System.Double)
IsPositiveInfinity(System.Double)
Parse(System.String)
ToString()
- 473 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class System.Int32 System.Int32 System.Int32 System.Int32 System.Int32 System.Int32 System.Int64 System.Int64 System.Int64 System.Int64 System.Int64 System.Int64 System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math
CompareTo(System.Int32)
Method
CompareTo(System.Object)
Equals(System.Int32)
Equals(System.Object)
Parse(System.String)
ToString()
CompareTo(System.Int64)
CompareTo(System.Object)
Equals(System.Int64)
Equals(System.Object)
Parse(System.String)
ToString()
Abs(System.Double)
Abs(System.Int32)
Abs(System.Int64)
Acos(System.Double)
Asin(System.Double)
Atan(System.Double)
Atan2(System.Double,System.Double)
Ceiling(System.Double)
Cos(System.Double)
Cosh(System.Double)
Exp(System.Double)
Floor(System.Double)
Log(System.Double)
Log(System.Double,System.Double)
Log10(System.Double)
Max(System.Double,System.Double)
Max(System.Int32,System.Int32)
Max(System.Int64,System.Int64)
Max(System.UInt32,System.UInt32)
Min(System.Double,System.Double)
Min(System.Int32,System.Int32)
Min(System.Int64,System.Int64)
- 474 -
Class System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Math System.Object System.Object System.Object System.Object System.String System.String System.String System.String System.String System.String
System.String
System.String System.String System.String
System.String System.String System.String System.String System.String
Chapter 20 - Appendix D:ECMA .NET Data Types
Method Min(System.UInt32,System.UInt32) Pow(System.Double,System.Double) Round(System.Double) Round(System.Double,System.Int32) Sign(System.Double) Sign(System.Int32) Sign(System.Int64) Sin(System.Double) Sinh(System.Double) Sqrt(System.Double) Tan(System.Double) Tanh(System.Double) Truncate(System.Double) .ctor() Equals(System.Object) Equals(System.Object,System.Object) ToString() .ctor(System.Char,System.Int32) .ctor(System.Char[]) .ctor(System.Char[],System.Int32, System.Int32) Chars(System.Int32) Clone() Compare(System.String,System.Int32, System.String,System.Int32,System.Int32) Compare(System.String,System.Int32,System.String, System.Int32,System.Int32,System.Boolean) Compare(System.String,System.String) Compare(System.String,System.String, System.Boolean) CompareOrdinal(System.String,System.Int32, System.String,System.Int32,System.Int32) CompareOrdinal(System.String,System.String) CompareTo(System.Object) CompareTo(System.String) Concat(System.Object) Concat(System.Object,System.Object)
- 475 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String System.String
Method Concat(System.Object,System.Object, System.Object) Concat(System.Object[]) Concat(System.String,System.String) Concat(System.String,System.String, System.String) Concat(System.String,System.String, System.String,System.String) Concat(System.String[]) Copy(System.String) CopyTo(System.Int32,System.Char[], System.Int32,System.Int32) EndsWith(System.String) Equals(System.Object) Equals(System.String) Equals(System.String,System.String) Format(System.String,System.Object) Format(System.String,System.Object, System.Object) Format(System.String,System.Object, System.Object,System.Object) Format(System.String,System.Object[]) GetEnumerator() IndexOf(System.Char) IndexOf(System.Char,System.Int32) IndexOf(System.Char,System.Int32, System.Int32) IndexOf(System.String) IndexOf(System.String,System.Int32) IndexOf(System.String,System.Int32, System.Int32) IndexOfAny(System.Char[]) IndexOfAny(System.Char[],System.Int32) IndexOfAny(System.Char[],System.Int32, System.Int32) Insert(System.Int32,System.String) Join(System.String,System.String[]) Join(System.String,System.String[], System.Int32,System.Int32) LastIndexOf(System.Char) LastIndexOf(System.Char,System.Int32) LastIndexOf(System.Char,System.Int32, System.Int32) LastIndexOf(System.String) LastIndexOf(System.String,System.Int32)
- 476 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class System.String
Method LastIndexOf(System.String,System.Int32, System.Int32)
System.String
LastIndexOfAny(System.Char[])
System.String
LastIndexOfAny(System.Char[],System.Int32)
System.String
LastIndexOfAny(System.Char[],System.Int32, System.Int32)
System.String
Length()
System.String
PadLeft(System.Int32)
System.String
PadLeft(System.Int32,System.Char)
System.String
PadRight(System.Int32)
System.String
PadRight(System.Int32,System.Char)
System.String
Remove(System.Int32,System.Int32)
System.String
Replace(System.Char,System.Char)
System.String
Replace(System.String,System.String)
System.String
Split(System.Char[])
System.String
Split(System.Char[],System.Int32)
System.String
StartsWith(System.String)
System.String
Substring(System.Int32)
System.String
Substring(System.Int32,System.Int32)
System.String
ToCharArray()
System.String
ToCharArray(System.Int32,System.Int32)
System.String
ToLower()
System.String
ToString()
System.String
ToUpper()
System.String
Trim()
System.String
Trim(System.Char[])
System.String
TrimEnd(System.Char[])
System.String
TrimStart(System.Char[])
System.Text.StringBuilder .ctor()
System.Text.StringBuilder .ctor(System.Int32)
System.Text.StringBuilder .ctor(System.Int32,System.Int32)
System.Text.StringBuilder .ctor(System.String)
System.Text.StringBuilder .ctor(System.String,System.Int32)
System.Text.StringBuilder .ctor(System.String,System.Int32, System.Int32,System.Int32)
System.Text.StringBuilder Append(System.Boolean)
System.Text.StringBuilder Append(System.Char)
- 477 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class
Method
System.Text.StringBuilder Append(System.Char,System.Int32)
System.Text.StringBuilder Append(System.Char[])
System.Text.StringBuilder Append(System.Char[],System.Int32, System.Int32)
System.Text.StringBuilder Append(System.Double)
System.Text.StringBuilder Append(System.Int32)
System.Text.StringBuilder Append(System.Int64)
System.Text.StringBuilder Append(System.Object)
System.Text.StringBuilder Append(System.String)
System.Text.StringBuilder Append(System.String,System.Int32, System.Int32)
System.Text.StringBuilder Append(System.UInt32)
System.Text.StringBuilder AppendFormat(System.String, System.Object)
System.Text.StringBuilder AppendFormat(System.String, System.Object,System.Object)
System.Text.StringBuilder AppendFormat(System.String, System.Object[])
System.Text.StringBuilder AppendFormat(System.String,System.Object, System.Object,System.Object)
System.Text.StringBuilder Capacity()
System.Text.StringBuilder Capacity(System.Int32)
System.Text.StringBuilder Chars(System.Int32)
System.Text.StringBuilder Chars(System.Int32,System.Char)
System.Text.StringBuilder EnsureCapacity(System.Int32)
System.Text.StringBuilder Equals(System.Text.StringBuilder)
System.Text.StringBuilder Insert(System.Int32,System.Boolean)
System.Text.StringBuilder Insert(System.Int32,System.Char)
System.Text.StringBuilder Insert(System.Int32,System.Char[])
System.Text.StringBuilder Insert(System.Int32,System.Char[], System.Int32,System.Int32)
System.Text.StringBuilder Insert(System.Int32,System.Double)
System.Text.StringBuilder Insert(System.Int32,System.Int32)
System.Text.StringBuilder Insert(System.Int32,System.Int64)
System.Text.StringBuilder Insert(System.Int32,System.Object)
System.Text.StringBuilder Insert(System.Int32,System.String)
System.Text.StringBuilder Insert(System.Int32,System.String, System.Int32)
System.Text.StringBuilder Insert(System.Int32,System.UInt32)
System.Text.StringBuilder Length()
System.Text.StringBuilder Length(System.Int32)
- 478 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class System.Text.StringBuilder MaxCapacity()
Method
System.Text.StringBuilder Remove(System.Int32,System.Int32)
System.Text.StringBuilder Replace(System.Char,System.Char)
System.Text.StringBuilder Replace(System.Char,System.Char, System.Int32,System.Int32)
System.Text.StringBuilder Replace(System.String,System.String)
System.Text.StringBuilder Replace(System.String,System.String, System.Int32,System.Int32)
System.Text.StringBuilder ToString()
System.Text.StringBuilder ToString(System.Int32,System.Int32)
System.TimeSpan
.ctor(System.Int32,System.Int32, System.Int32)
System.TimeSpan
.ctor(System.Int32,System.Int32, System.Int32,System.Int32)
System.TimeSpan
.ctor(System.Int32,System.Int32, System.Int32,System.Int32,System.Int32)
System.TimeSpan
.ctor(System.Int64)
System.TimeSpan
Add(System.TimeSpan)
System.TimeSpan
Compare(System.TimeSpan,System.TimeSpan)
System.TimeSpan
CompareTo(System.Object)
System.TimeSpan
CompareTo(System.TimeSpan)
System.TimeSpan
Days()
System.TimeSpan
Duration()
System.TimeSpan
Equals(System.Object)
System.TimeSpan
Equals(System.TimeSpan)
System.TimeSpan
Equals(System.TimeSpan,System.TimeSpan)
System.TimeSpan
FromDays(System.Double)
System.TimeSpan
FromHours(System.Double)
System.TimeSpan
FromMilliseconds(System.Double)
System.TimeSpan
FromMinutes(System.Double)
System.TimeSpan
FromSeconds(System.Double)
System.TimeSpan
FromTicks(System.Int64)
System.TimeSpan
Hours()
System.TimeSpan
Milliseconds()
System.TimeSpan
Minutes()
System.TimeSpan
Negate()
System.TimeSpan
Parse(System.String)
System.TimeSpan
Seconds()
- 479 -
Chapter 20 - Appendix D:ECMA .NET Data Types
Class System.TimeSpan System.TimeSpan System.TimeSpan System.TimeSpan System.TimeSpan System.TimeSpan System.TimeSpan System.TimeSpan System.UInt32 System.UInt32 System.UInt32 System.UInt32 System.UInt32 System.UInt32
Method Subtract(System.TimeSpan) Ticks() ToString() TotalDays() TotalHours() TotalMilliseconds() TotalMinutes() TotalSeconds() CompareTo(System.Object) CompareTo(System.UInt32) Equals(System.Object) Equals(System.UInt32) Parse(System.String) ToString()
- 480 -
CHAPTER 21
21.1
21.2 21.3 21.4 21.5
Trademarks NOTICES
Experion®, PlantScape®, SafeBrowse®, TotalPlant®, and TDC 3000® are registered trademarks of Honeywell International, Inc. ControlEdgeTM is a trademark of Honeywell International, Inc. OneWirelessTM is a trademark of Honeywell International, Inc. Matrikon® and MatrikonOPCTM are trademarks of Matrikon International. Matrikon International is a business unit of Honeywell International, Inc. Movilizer® is a registered trademark of Movilizer GmbH. Movilizer GmbH is a business unit of Honeywell International, Inc.
Trademarks
Experion®, PlantScape®, and SafeBrowse® are registered trademarks of Honeywell International, Inc.
Trademarks
Experion® and SafeBrowse® are registered trademarks of Honeywell International, Inc. PlantCruiseTM is a trademark of Honeywell International, Inc.
Trademarks
Experion® is a registered trademark of Honeywell International, Inc. ControlEdgeTM is a trademark of Honeywell International, Inc. OneWirelessTM is a trademark of Honeywell International, Inc.
Other trademarks
Microsoft and SQL Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Trademarks that appear in this document are used only to the benefit of the trademark owner, with no intention of trademark infringement.
481
Chapter 21 - Notices
21.6 21.7 21.8
21.9 21.10
Third-party licenses
This product may contain or be derived from materials, including software, of third parties. The third party materials may be subject to licenses, notices, restrictions and obligations imposed by the licensor. The licenses, notices, restrictions and obligations, if any, may be found in the materials accompanying the product, in the documents or files accompanying such third party materials, in a file named third_party_licenses on the media containing the product, or at http://www.honeywell.com/ps/thirdpartylicenses.
Documentation feedback
You can find the most up-to-date documents on the Honeywell Process Solutions Support website at: http://www.honeywellprocess.com/support If you have comments about Honeywell Process Solutions documentation, send your feedback to: hpsdocs@honeywell.com Use this email address to provide feedback, or to report errors and omissions in the documentation. For immediate help with a technical problem, contact HPS Technical Support through your local Customer Contact Center, or by raising a support request on the Honeywell Process Solutions Support website.
How to report a security vulnerability
For the purpose of submission, a security vulnerability is defined as a software defect or weakness that can be exploited to reduce the operational or security capabilities of the software. Honeywell investigates all reports of security vulnerabilities affecting Honeywell products and services. To report a potential security vulnerability against any Honeywell product, please follow the instructions at: https://honeywell.com/pages/vulnerabilityreporting.aspx
Support
For support, contact your local Honeywell Process Solutions Customer Contact Center (CCC). To find your local CCC visit the website, https://www.honeywellprocess.com/en-US/contactus/customer-support-contacts/Pages/default.aspx.
Training classes
Honeywell holds technical training classes that are taught by process control systems experts. For more information about these classes, contact your Honeywell representative, or see http://www.automationcollege.com.
482
madbuild