B0193YL

REV E

I/A Series
Information Suite
AIM*Historian Users Guide
December 17, 2002

AIM*API, AIM*AT, AIM*Historian, AIM*SPC, Fox, Foxboro, and I/A Series are registered trademarks of
Invensys Systems, Inc.
Invensys is a trademark of Invensys plc.
Access, Windows, and Windows NT are registered trademarks of Microsoft Corporation.
Applicom is a trademark of Applicom International.
BASEstar is a trademark of Compaq Computer Corporation.
Computer Highway Interface Program (CHIP) is a trademark of Fisher-Rosemount Systems.
Informix is a trademark of IBM Corporation.
Modbus and ModbusPlus are trademarks of AEG Schneider Automation, Inc.
OPC is a trademark of the OPC Foundation.
Oracle is a trademark of Oracle Corporation.
Sun and Solaris are registered trademarks of Sun Microsystems, Inc.
UNIX is a registered trademark of X/Open Company Ltd.
All other brand names may be trademarks of their respective companies.
Copyright 1999-2002 Invensys Systems, Inc.
All rights reserved

SOFTWARE LICENSE AND COPYRIGHT INFORMATION

Before using the Invensys Systems, Inc. supplied software supported by this documentation, you
should read and understand the following information concerning copyrighted software.
1. The license provisions in the software license for your system govern your obligations
and usage rights to the software described in this documentation. If any portion of
those license provisions is violated, Invensys Systems, Inc. will no longer provide you
with support services and assumes no further responsibilities for your system or its
operation.
2. All software issued by Invensys Systems, Inc. and copies of the software that you are
specifically permitted to make, are protected in accordance with Federal copyright
laws. It is illegal to make copies of any software media provided to you by
Invensys Systems, Inc. for any purpose other than those purposes mentioned in the
software license

Contents
Figures.................................................................................................................................... xi
Tables.................................................................................................................................... xv
Preface................................................................................................................................. xvii
Who Should Read This Book ................................................................................................ xvii
What You Should Know ....................................................................................................... xvii
Revision Information ........................................................................................................... xviii
Related Documents ................................................................................................................ xix
Document Overview .............................................................................................................. xix
Conventions ........................................................................................................................... xxi
Request for Comments .......................................................................................................... xxii
1. Overview ........................................................................................................................... 1
AIM*Historian Features ............................................................................................................ 1
AIM*Historian Architecture ...................................................................................................... 2
AIM*Historian Product Structure ............................................................................................. 3
AIM*Historian Instance ....................................................................................................... 3
Instance Components ........................................................................................................... 4
Collectors ............................................................................................................................. 4
Default Collector Configuration ...................................................................................... 5
I/A Series Real-Time Collector ........................................................................................ 5
I/A Series Event Message Collector .................................................................................. 5
I/O Gate Data Collector .................................................................................................. 6
Real-Time Points ................................................................................................................. 7
Time Stamps ................................................................................................................... 9
Collection Frequency ....................................................................................................... 9
Event Messages ..................................................................................................................... 9
Control Groups .................................................................................................................. 11
Reduction Groups .............................................................................................................. 12
AIM*Historian Interface Structure ..........................................................................................
AIM*API Interface .............................................................................................................
ODBC Interface .................................................................................................................
I/A Series Interface .............................................................................................................
Export to Oracle .................................................................................................................
AIM*AT OPC Server .........................................................................................................
AIM*AT OLE DB Provider ...............................................................................................

13
15
15
15
15
15
15

iii

B0193YL Rev E

Contents

2. AIM*Historian Configuration......................................................................................... 17
AIM*Historian Configuration Tools ....................................................................................... 17
AIM*Historian Configurator Window .................................................................................... 18
Configuring Server Connections for Wizard Browsing ............................................................
Starting the AIM*Historian Configurator ..........................................................................
Selecting an Instance ..........................................................................................................
AIM*Historian Components Tree ......................................................................................
Configuration File Windows ..............................................................................................
Application Menu Bar ........................................................................................................
Command Buttons .............................................................................................................

19
20
22
24
24
26
26

Creating an AIM*Historian Instance ....................................................................................... 27

Configuring Real-time Points ..................................................................................................
Adding RTPs with the Data Object Wizard .......................................................................
Filter Page Controls ............................................................................................................
AIM*AT Server Filter .........................................................................................................
I/A Series Compound-Block Filter .....................................................................................
Parameter Type Filter .........................................................................................................
Filtering by I/A Series Descriptions ...............................................................................
Searching Dialog Box ....................................................................................................
Results Page .......................................................................................................................
Defining the RTP Configuration .......................................................................................

28
29
29
31
33
35
36
37
38
41

Configuring Messages ............................................................................................................. 42

Creating Control Groups ........................................................................................................ 45
Adding Reduction Groups ...................................................................................................... 50
Editing Configuration Files .....................................................................................................
Instance Configuration File ................................................................................................
RTP Configuration Window ..............................................................................................
Editing RTPs .................................................................................................................
Deleting RTPs ...............................................................................................................
Adding a Collector .............................................................................................................
Other Configuration File Windows ....................................................................................

55
55
56
57
59
59
62

Server Status ............................................................................................................................ 62

Finishing an AIM*Historian Configurator Session .................................................................. 63
Configuration Using Input Text Files .....................................................................................
Instance Configuration .......................................................................................................
Collector Stations ...............................................................................................................
Real-Time Points ...............................................................................................................

64
65
68
69

Event Message Configuration ..................................................................................................

I/A Series Legacy Message Groups ......................................................................................
I/A Series Alarms ................................................................................................................
Reduction Groups ..............................................................................................................
Control Groups ..................................................................................................................
Committing the Session .....................................................................................................
Permanent Delete ...............................................................................................................

72
72
74
76
77
77
78

iv

Contents

B0193YL Rev E

Using histsave ......................................................................................................................... 79

Instance Configuration with histbatch .................................................................................... 81
Instance Configuration with histcbatch ................................................................................... 83
Modifying Maximum Value Attributes ................................................................................... 84
3. AIM*Historian Operation............................................................................................... 87
AIM*Historian Manager Window ..........................................................................................
Application Menu Bar and Tool Bar ..................................................................................
AIM*Historian Components Tree ......................................................................................
Tree Menu ....................................................................................................................
AIM*Historian Manager Pages ...........................................................................................
On/Off Controls ...........................................................................................................
Server Page ....................................................................................................................
Instance Page .................................................................................................................
Collector Page ...............................................................................................................
Communications Page ...................................................................................................
Log File Page .................................................................................................................

87
89
91
92
93
93
94
94
96
97
99

Configuration Tools .............................................................................................................. 100

Displaying Process History .................................................................................................... 100
An Overview of the AIM*Historian Data Display ............................................................ 100
Starting the AIM*Historian Data Display ........................................................................ 101
Defining the Sampled RTP Data to Display .........................................................................
Saving, Opening, and Deleting Configurations ...........................................................
Selecting the AIM*Historian Instance and Server ........................................................
Specifying the Time Interval and Data Type for the RTPs ..........................................
Assigning RTPs to Report Columns ............................................................................
Viewing the Data Report or Trend Display .................................................................
Exiting the AIM*Historian Data Display .....................................................................
Viewing the Data Report ..................................................................................................
The Data Report Window Format ..............................................................................
Using the Data Report Menu Bar ................................................................................
Printing Reports ...............................................................................................................
Printer Setup ....................................................................................................................
Viewing the Data Trend Display ......................................................................................

102
103
103
103
104
105
105
105
106
107
107
108
111

Manual Data Entry ............................................................................................................... 112

Annotating MDE Values ............................................................................................. 115
AIM*Historian Archiver ....................................................................................................... 116
AIM*Historian Spy ............................................................................................................... 116
Server Status .......................................................................................................................... 119
AIM*Historian Demand Writes ............................................................................................ 120
Legacy Interface Servers ......................................................................................................... 122
Starting Legacy Servers for Local Instances ....................................................................... 122
Starting Legacy Servers for Remote Instances ................................................................... 123

B0193YL Rev E

Contents

Stopping AIM*Historian ....................................................................................................... 124

4. Database Management .................................................................................................. 127
AIM*Historian Database ....................................................................................................... 127
File Maintenance Functions ..................................................................................................
Configuration Files ...........................................................................................................
Event Message Files ..........................................................................................................
Sample Files .....................................................................................................................
Reduced RTP Files ...........................................................................................................
Deleting an AIM*Historian Instance ................................................................................

128
129
130
130
131
132

Optimizing Disk Space Usage for RTP Files .........................................................................

Starting the DB Wizard ....................................................................................................
Selecting an AIM*Historian Instance ...............................................................................
Using the Optimization Window .....................................................................................
Using the DB Wizard Menus and Tool Bar .................................................................
Filtering the RTP List ..................................................................................................
RTP Information Displayed in the Optimization Window .........................................
Selecting RTPs ............................................................................................................
Optimizing RTP Sample File Disk Usage ....................................................................
Reviewing Results .............................................................................................................

133
134
135
137
138
138
140
140
141
143

On-Demand Archiving .........................................................................................................

AIM*Historian Archiver Window ....................................................................................
Application Menu Bar and Tool Bar ................................................................................
Selecting Database Files ....................................................................................................
Selecting an AIM*Historian Instance ...........................................................................
Locating a File in the Database List .............................................................................
Filtering the Database List ...........................................................................................
Checking Files .............................................................................................................
Deleting Database Files ....................................................................................................
Moving Database Files .....................................................................................................
Copying Database Files ....................................................................................................

143
144
145
147
149
150
151
152
152
153
153

Using the AutoArchiver .........................................................................................................

AutoArchiver Features ......................................................................................................
AutoArchiver Configuration .............................................................................................
AutoArchiver Test Mode ..................................................................................................

154
154
156
160

Display of Archived Files ....................................................................................................... 161

5. Troubleshooting............................................................................................................ 163
Version Information .............................................................................................................. 163
Troubleshooting Tools .......................................................................................................... 164
Diagnostic Utilities ...............................................................................................................
clearcfg .............................................................................................................................
dumpcvs ...........................................................................................................................
dumprcol ..........................................................................................................................
dumpred ..........................................................................................................................
vi

166
168
168
169
172

Contents

B0193YL Rev E

histspy ..............................................................................................................................
apitst ................................................................................................................................
Example 1 ...................................................................................................................
Example 2 ...................................................................................................................
Example 3 ...................................................................................................................
Example 4 ...................................................................................................................
Example 5 ...................................................................................................................
msgcheck ..........................................................................................................................
Known Problems .........................................................................................................
msgfix ...............................................................................................................................
Known Problems .........................................................................................................
msgtst ...............................................................................................................................
sec2asc ..............................................................................................................................
rtpcheck ...........................................................................................................................
rtpfix ................................................................................................................................
testhv ................................................................................................................................
testvar ...............................................................................................................................
xrebuild ............................................................................................................................
fh_sacego .....................................................................................................................
Stub Library for Off-Platform Testing ..............................................................................
Tailoring Default Collector Stub Values ......................................................................

172
173
173
175
175
176
176
176
177
178
179
180
181
181
183
184
186
188
189
189
190

Troubleshooting Procedures ..................................................................................................

No RTP Values Inserted in .fdb Files ...............................................................................
No Event Messages Inserted in .fdb Files ..........................................................................
No RTP Values or Event Messages Inserted in .fdb Files ..................................................
No TCP/IP Connection to Remote Collector ..................................................................
AIM*Historian Client Cannot Connect with Server .........................................................
AIM*Historian Data Not in Trend Display .....................................................................
Incorrect AIM*Historian Data in Trend Display ..............................................................
Unexplained Program Crashes; Inability to Start Programs ..............................................
Sample vmstat Output .................................................................................................
Adding Swap Space .....................................................................................................

190
192
193
193
194
195
195
197
198
199
199

Appendix A. Error Codes................................................................................................... 201

Error Codes Returned by AIM*API ...................................................................................... 201
Appendix B. AIM*Historian Sample Status and Quality ................................................... 207
Status Definition for I/A Series Version 4.3 and Later ........................................................... 207
RTP Value Types .................................................................................................................. 209
Quality Definition ................................................................................................................ 211
Appendix C. AIM*Historian Reduction Status and Quality .............................................. 213
Appendix D. Data Reduction Algorithms.......................................................................... 215
Data Reduction Formulas ..................................................................................................... 215

vii

B0193YL Rev E

Contents

I/A Series and AIM*Historian Data Reduction ..................................................................... 216

Configuring Reduction Intervals and Managing RTP Data Files ...........................................
Overview of RTP Data File Choice ..................................................................................
Time Stamps of Data in Reduction Files ..........................................................................
Algorithm for Choosing File Type to Satisfy a Reduction Request ..............................
Configuring Reduction Intervals ......................................................................................
Use of Sample Files ..........................................................................................................
Examples .....................................................................................................................
How Long to Keep Data Files ..........................................................................................

218
218
218
218
219
220
220
221

Appendix E. AIM*Historian Component Attributes ......................................................... 223

Session Component .............................................................................................................. 225
Session Component How To ........................................................................................... 225
Session Attribute Descriptions .......................................................................................... 225
Instance Component .............................................................................................................
Instance Component How To ..........................................................................................
Instance Attribute Descriptions ........................................................................................
Note on Reduction Intervals ........................................................................................

226
226
228
236

Collector Component ........................................................................................................... 237

Collector Component How To ........................................................................................ 237
Collector Station Attribute Descriptions .......................................................................... 238
RTP Component .................................................................................................................. 247
RTP Component How To ............................................................................................... 247
RTP Attribute Descriptions .............................................................................................. 249
Event Message Component ................................................................................................... 257
Event Message Component How To ................................................................................ 257
Event Message Attribute Description ............................................................................... 258
Control Group Component .................................................................................................. 260
Control Group Component How To ............................................................................... 260
Control Group Attribute Descriptions ............................................................................. 261
Reduction Group Component .............................................................................................. 263
Reduction Group Component How To ........................................................................... 263
Reduction Group Attribute Descriptions ......................................................................... 264
Note on Time Stamps ...........................................................................................................
IATIME Parameter Change .............................................................................................
Collector Time Format ....................................................................................................
TZ and DST Parameters ..................................................................................................
TZ Parameter ..............................................................................................................
DST Parameter ............................................................................................................
Migrating Data from Previous Versions ............................................................................

266
266
267
267
267
267
268

Appendix F. Sizing Guidelines........................................................................................... 269

Sizing Factors ........................................................................................................................ 269
RTP Samples .................................................................................................................... 269

viii

Contents

B0193YL Rev E

Reduction Values ............................................................................................................. 270

Event Messages ................................................................................................................. 270
Other Sizing Considerations .................................................................................................
Finding an Appropriate Data Collection Rate ..................................................................
Data Collection Rate Parameters .................................................................................
Which Points to Collect ..............................................................................................
Specifying RTP File Sizes ............................................................................................

271
271
271
273
273

Appendix G. Exporting to Oracle ...................................................................................... 275

HistExport ............................................................................................................................ 277
HistMove .............................................................................................................................. 278
Hist2Oracle .......................................................................................................................... 279
Data Export Configuration Files ...........................................................................................
The export.ini File ............................................................................................................
The msg.ini File ...............................................................................................................
The hist2oracle.ini File .....................................................................................................
The createtables.sql Script File ..........................................................................................

279
279
280
280
281

Created Files ......................................................................................................................... 282

Database Tables ....................................................................................................................
Database Table: msgs .......................................................................................................
Messages Table Example ..............................................................................................
Database Table: <msggroup>_<msgname> .......................................................................
Message Name Table Example ....................................................................................
Database Table: rtps .........................................................................................................
RTP Table Example ....................................................................................................
Database Table: rtps_strings .............................................................................................
String Type RTP Table Example .................................................................................
Database Table: rtps_numbers .........................................................................................
Non-String RTP Table Example .................................................................................
Database Table: rgroup_data ............................................................................................
Reduction Group Example ..........................................................................................

283
283
284
285
285
287
288
289
290
291
292
293
294

Running Data Export ............................................................................................................ 295

Naming Conventions for Exported Files ...............................................................................
Message Files ....................................................................................................................
RTP Files .........................................................................................................................
Reduction Groups ............................................................................................................

296
296
296
296

Appendix H. AIM*OLE DB Provider ............................................................................... 297

Client/Server Architecture and Remote Access ...................................................................... 297
Supported Standards ........................................................................................................ 297
Installation and Authorization ............................................................................................... 297
Sample Project ...................................................................................................................... 298
Data Structures ..................................................................................................................... 298

ix

B0193YL Rev E

Contents

Dictionary Schema ...........................................................................................................

InstCfg ........................................................................................................................
RTPCfg .......................................................................................................................
MsgTableCfg ...............................................................................................................
MsgFieldCfg ................................................................................................................
CollectorStationCfg .....................................................................................................
ControlGroupCfg ........................................................................................................
ControlGroupRTPs .....................................................................................................
ControlGroupMsgs .....................................................................................................
ReductionGroupCfg ....................................................................................................
REDUCTIONGroupRTPs .........................................................................................
Message Schemas ..............................................................................................................
RTP Data Schema ............................................................................................................
RTPEntries ..................................................................................................................
LinearRTPEntries ........................................................................................................
AIM*OLE DB Provider Schemata ...............................................................................

299
299
300
301
301
302
302
303
303
303
304
304
304
304
305
305

Usage ....................................................................................................................................
Connect Statement ...........................................................................................................
Select Statement ...............................................................................................................
Column Exp ................................................................................................................
Table Spec ...................................................................................................................
Condition ....................................................................................................................
Lexicon ........................................................................................................................
Insert Statement ...............................................................................................................

306
306
309
310
310
311
311
311

Index .................................................................................................................................. 313

Figures
1-1.
1-2.
1-3.
1-4.
1-5.
2-1.
2-2.
2-3.
2-4.
2-5.
2-6.
2-7.
2-8.
2-9.
2-10.
2-11.
2-12.
2-13.
2-14.
2-15.
2-16.
2-17.
2-18.
2-19.
2-20.
2-21.
2-22.
2-23.
2-24.
2-25.
2-26.
2-27.
2-28.
2-29.
2-30.
2-31.
2-32.
2-33.
2-34.
2-35.
2-36.
2-37.
2-38.
2-39.

AIM*Historian Client/Server Architecture .................................................................... 2

AIM*Historian Instance ................................................................................................ 4
Sample Message Definition ......................................................................................... 10
AIM*Historian Data Retrieval .................................................................................... 14
AIM*Historian Interface Structure .............................................................................. 16
AIM*Historian Configuration Overview ..................................................................... 17
Server Connection Dialog Box .................................................................................... 19
AIM*Historian Configurator Window ........................................................................ 21
Instance Selection Dialog Box ..................................................................................... 22
Real Time Points Page ................................................................................................ 23
AIM*Historian Components Tree .............................................................................. 24
AIM*Historian Configurator Window with Instance Configuration File Open .......... 25
Create AIM*Historian Instance Dialog Box ................................................................ 27
Real Time Points Page ................................................................................................ 28
Data Object Wizard Filter Controls ............................................................................ 29
Selected Server Stations Dialogue Box ......................................................................... 30
Data Object Wizard Server Filter Page ........................................................................ 32
Compound-Block Filter Page Sorted by Compound ................................................... 33
Compound-Block Filter Page Sorted by Block ............................................................ 34
Parameter Type Filter Page ......................................................................................... 35
Description Filter Page ................................................................................................ 36
Object Search Dialog Box ........................................................................................... 37
Data Object Wizard Results Page ................................................................................ 38
Add Item Dialog Box .................................................................................................. 39
Data Object Tree in the RTP/Message Dialog Box ..................................................... 40
Messages Page ............................................................................................................. 42
Message Definition Dialog Box ................................................................................... 43
New Key Dialog Box ................................................................................................... 44
Control Page in the Groups Dialog Box ...................................................................... 45
Control Group Dialog Box ......................................................................................... 46
Trigger RTPs Dialog Box ............................................................................................ 47
Controlled RTPs Dialog Box ...................................................................................... 48
Controlled Messages Dialog Box ................................................................................. 49
Reduction Group Dialog Box ..................................................................................... 51
Parameters Dialog Box ................................................................................................ 52
Reduction Group RTPs Dialog Box ............................................................................ 53
Reduction Group Operations Dialog Box ................................................................... 54
AIM*Historian Cfg Window and Instance Parameters ................................................ 55
RTP Configuration Window ...................................................................................... 57
Edit RTP Window ...................................................................................................... 58
Collector Station Configuration File Window ............................................................. 60
Collector Station Type Dialog Box ............................................................................. 60
Collector Setup Window ............................................................................................. 61
Server Status Dialog Box ............................................................................................. 62
xi

B0193YL Rev E

2-40.
2-41.
2-42.
2-43.
2-44.
2-45.
2-46.
2-47.
2-48.
2-49.
2-50.
2-51.
2-52.
2-53.
2-54.
2-55.
2-56.
2-57.
2-58.
2-59.
3-1.
3-2.
3-3.
3-4.
3-5.
3-6.
3-7.
3-8.
3-9.
3-10.
3-11.
3-12.
3-13.
3-14.
3-15.
3-16.
3-17.
3-18.
3-19.
3-20.
3-21.
3-22.
3-23.
3-24.
3-25.
3-26.
4-1.
4-2.

xii

Figures

Closing Options Dialog Box ....................................................................................... 63

Establishing the Instance ............................................................................................. 65
Configuring Instance Attributes .................................................................................. 66
Configuring Instance Attributes, Continued ............................................................... 67
Configuring a Remote I/O Gate Collector .................................................................. 68
Configuring a Remote I/O Gate Collector, Continued ............................................... 69
Configuring an RTP ................................................................................................... 70
Condensed Syntax for Configuring RTPs ................................................................... 71
Updating RTP Configurations .................................................................................... 71
Configuring I/A Series Event Message Collection ........................................................ 73
Configuring the iaalarm Message Group ..................................................................... 74
Replicating the Message Fields .................................................................................... 75
Configuring a Reduction Group ................................................................................. 76
Configuring a Control Group ..................................................................................... 77
Committing the Configuration ................................................................................... 77
Deleting an RTP ......................................................................................................... 78
histsave Window ......................................................................................................... 79
histbatch Window ....................................................................................................... 81
Completed Configuration Session ............................................................................... 82
MAXIMA Input File ................................................................................................... 85
AIM*Historian Manager Window .............................................................................. 88
AIM*Historian Components Tree .............................................................................. 91
On/Off Controls on the Instance and Collector Pages ................................................ 93
AIM*Historian Manager Server Page .......................................................................... 94
AIM*Historian Manager Instance Page ....................................................................... 95
AIM*Historian Manager Collector Page ..................................................................... 97
AIM*Historian Manager Communications Page ......................................................... 97
AIM*Historian Manager Log File Page ....................................................................... 99
RTP Definition Window .......................................................................................... 102
Data Report Window ................................................................................................ 105
AIM*Historian Data Report Components ................................................................ 106
Print Dialog Box for Solaris Systems ......................................................................... 107
Printer Setup Dialog Box for Solaris Systems ............................................................ 108
Add Printer Dialog Box for Solaris Systems ............................................................... 109
Modify Printer Dialog Box on Solaris Systems .......................................................... 109
Delete Printer Dialog Box on Solaris Systems ............................................................ 110
The Data Trend Display ........................................................................................... 111
Manual Data Entry Window ..................................................................................... 112
MDE Window Tool Bar ........................................................................................... 113
MDE Annotation Window ....................................................................................... 115
AIM*Historian histspy Window ............................................................................... 116
AIM*Historian Spy RTP Database File ..................................................................... 117
RTP Values Window ................................................................................................ 118
Server Status Dialog Box ........................................................................................... 119
AIM*AT Control Panel Applet Dialog Box ............................................................... 125
AIM*Historian Page ................................................................................................. 125
The AIM*Historian Instance Selection Dialog Box ................................................... 135
DB Wizard Optimization Window ........................................................................... 137

Figures

4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
4-9.
4-10.
4-11.
4-12.
4-13.
4-14.
4-15.
4-16.
4-17.
4-18.
5-1.
5-2.
5-3.
5-4.
G-1.
H-1.

B0193YL Rev E

Filter Tools for Selectively Displaying RTPs .............................................................

Optimization Window Command Buttons ...............................................................
Tools for Adjusting RTP Storage Load ......................................................................
Estimated Results of a Read Delta Changes ...............................................................
Dialog Box for Confirming Application of New Read Delta Attributes .....................
Dialog Box for Adjusting the AutoArchiver Configuration ........................................
AIM*Historian Archiver Window .............................................................................
Select AIM*Historian Instance Dialog Box ...............................................................
Selecting Instances from the Tool Bar .......................................................................
Go To File Dialog Box ..............................................................................................
Filter File List Dialog Box .........................................................................................
AIM*Historian AutoArchiver Configurator Window ................................................
AutoArchiver Scheduling Page ..................................................................................
AutoArchiver Sample Page ........................................................................................
Cfg and Xref Page in the AutoArchiver Window .......................................................
Display of Archived RTP Files in the AIM*Historian Spy Window ..........................
Sample dumprcol Output .........................................................................................
Generating Hourly Reduced Values ..........................................................................
testvar Usage Synopsis ...............................................................................................
Values Returned by testvar ........................................................................................
A Summary of the AIM*Historian Data Export Process ............................................
AIM*OLE DB Provider Dialog Box .........................................................................

138
139
141
141
142
143
145
149
149
150
151
156
157
158
160
161
170
174
186
187
276
308

xiii

B0193YL Rev E

xiv

Figures

Tables
1-1.
1-2.
2-1.
2-2.
2-3.
2-4.
3-1.
3-2.
3-3.
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
5-1.
5-2.
5-3.
5-4.
5-5.
5-6.

RTP Data Types ........................................................................................................... 8

RTP Trigger Values .................................................................................................... 12
AIM*Historian Configurator Application Menu Bar ................................................... 26
Message Definition Fields ........................................................................................... 43
RTP Trigger Values .................................................................................................... 48
Default AIM*Historian Installation Directories .......................................................... 64
AIM*Historian Manager Functions ............................................................................ 89
Components Tree Pop-Up Menus .............................................................................. 92
Data Report Window Menu Bar ............................................................................... 107
Reduced RTP Files .................................................................................................... 131
Samples and Storage for Different Deltas .................................................................. 133
DB Wizard Functions ............................................................................................... 138
RTP Information Provided in the Optimization Window ......................................... 140
Archivable Database Files .......................................................................................... 144
AIM*Historian Archiver Functions ........................................................................... 146
Summary of Diagnostic Utilities ............................................................................... 166
Circular File Header Fields in dumprcol Output ....................................................... 171
No RTP Values Inserted in .fdb Files ........................................................................ 192
No Event Messages Inserted in .fdb Files .................................................................. 193
No RTP Values or Event Messages Inserted in .fdb Files ........................................... 193
No TCP/IP Connection Between histreceive and histsend
at the Remote Collector ............................................................................................ 194
5-7. Error Message Server Name Unknown .................................................................. 195
5-8. Failure to Display AIM*Historian Data in Trend Display ......................................... 195
5-9. Incorrect AIM*Historian Data in Trend Display ...................................................... 197
5-10. Unexplained Crashes; Inability to Start Programs ..................................................... 198
A-1. AIM*API Function Returns ...................................................................................... 201
A-2. AIM*API Error Codes .............................................................................................. 201
B-1. Status Definition with I/A Series Version 4.3 and Later ............................................ 207
B-2. RTP Value Types ...................................................................................................... 209
B-3. RTP Quality Definition with I/A Series Version 4.2 and Later ................................. 211
C-1. Status Returned by Reductions APIs ......................................................................... 213
C-2. Reduction Value Types ............................................................................................. 214
D-1. Algorithms for Reducing Data .................................................................................. 215
D-2. Supported Reduction Operations .............................................................................. 217
D-3. Selection of Sample Files for a Reduction Request .................................................... 220
D-4. Selection of Reduced Data Files for a Reduction Request .......................................... 221
D-5. Selection of Medium and Fast Reduction Files for a Reduction Request ................... 221
E-1. AIM*Historian Components .................................................................................... 224
E-2. AIM*Historian Defined Actions ............................................................................... 224
E-3. AIM*Historian Session Attributes ............................................................................. 225
E-4. AIM*Historian Instance Component Attributes ....................................................... 228
E-5. Collector Station Component Attribute .................................................................... 239
E-6. TZ Attribute Values .................................................................................................. 246
xv

B0193YL Rev E

E-7.
E-8.
E-9.
E-10.
E-11.
G-1.
G-2.
G-3.
G-4.
G-5.
G-6.
G-7.
H-1.
H-2.
H-3.
H-4.
H-5.
H-6.
H-7.
H-8.
H-9.
H-10.
H-11.
H-12.
H-13.
H-14.
H-15.
H-16.
H-17.

xvi

RTP Component Attributes ......................................................................................

RPT Data Types .......................................................................................................
Event Message Component Attributes ......................................................................
Control Group Component Attributes ......................................................................
Reduction Group Component Attributes ..................................................................
Oracle Database Tables Used to Store Historian Data ...............................................
Columns in the msgs Database Table ........................................................................
Columns in the <msggroup>_<msgname> Database Table .......................................
Columns in the rtps Database Table .........................................................................
Columns in the rtps_strings Database Table .............................................................
Columns in the rtps_numbers Database Table ..........................................................
Columns in the rgroup_data Database Table ............................................................
AIM*OLE DB Provider Table Hierarchy ..................................................................
AIM*OLE DB Provider Table InstCfg .....................................................................
AIM*OLE DB Provider Table ..................................................................................
AIM*OLE DB Provider Table MsgTableCfg ............................................................
AIM*OLE DB Provider Table MsgFieldCfg .............................................................
AIM*OLE DB Provider Table CollectorStationCfg ..................................................
AIM*OLE DB Provider Table ControlGroupCfg .....................................................
AIM*OLE DB Provider Table ControlGroupRTPs ..................................................
AIM*OLE DB Provider Table ControlGroupMsgs ..................................................
AIM*OLE DB Provider Table ReductionGroupCfg .................................................
AIM*OLE DB Provider Table ReductionGroupRTPs ..............................................
AIM*OLE DB Provider Table <MsgGroup>.<MsgName> .......................................
AIM*OLE DB Provider Table RTPEntries ...............................................................
AIM*OLE DB Provider LinearRTPEntries ...............................................................
AIM*OLE DB Provider Schemata Tables .................................................................
Connect Arguments .................................................................................................
Lexical Elements Used in AIM*OLE DB Provider ....................................................

Tables

249
256
258
261
264
283
283
285
287
289
291
293
298
299
300
301
301
302
302
303
303
303
304
304
304
305
305
307
311

Preface
The AIM*Historian client/server software collects, stores, and archives process data from
I/A Series nodes and other distributed control systems on the enterprise intranet. You can
retrieve historical data stored in the AIM*Historian database and perform:
Graphical and statistical analysis

Regulatory and Batch reporting

Product quality analysis

Financial reporting.

This guide explains how to:

Configure AIM*Historian instances for collection, storage, and retrieval

Configure real-time point (RTP), message, reduction group, and control group
components
Operate AIM*Historian instances

Maintain AIM*Historian databases

Troubleshoot instances.

Who Should Read This Book

This document is intended for process engineers, system administrators, developers using
AIM*Historian data for other applications, and operators who are responsible for starting and
stopping AIM*Historian instances.

What You Should Know

Prior to using this book, you should be familiar with the target control systems from which the
AIM*Historian is to collect process data and have a working knowledge of the platforms involved
in the applications.

xvii

B0193YL Rev E

Preface

Revision Information
For Version 3.2 of the AIM*AT, the following changes were made:
Chapter 1 Overview
Revised to describe AIM*Historian support for HPS Message Manager and sequence
of events (SOE) data collection
Updated to include the AIM*Historian OLE DB Provider, an optional interface
that provides access to AIM*Historian data from customer-developed OLE DB
applications
Updated description of support for UTC time stamps when supplied by the I/A Series
system or other control systems
Chapter 2 AIM*Historian Configuration
Modified to describe the revised histsave program.
Chapter 3 AIM*Historian Operation
Modified to describe new On/Off controls in the AIM*Historian Manager
Revised to reflect improved collector operation, implementation of the histstop
command, and new start scripts for the Legacy Interfaces
Chapter 4 Database Management
Updated to include a description of the DB Wizard, which enables users to analyze
data storage loads for an AIM*Historian instance and optimize the real-time point
(RTP) configurations accordingly
Chapter 5 Troubleshooting
Modified to reflect changes in collector operation and changes to the dumprcol
utility
Appendix A Error Codes
Updated to include new error codes related to collector operation
Appendix E AIM*Historian Component Attributes
Updated to reflect new instance and collector attributes
Appendix H AIM*OLE DB Provider
Added to describe a new interface for accessing AIM*Historian data.
Various minor changes have been made throughout the document to reflect changes made for
Version 3.2.

xviii

Preface

B0193YL Rev E

Related Documents
The following documents provide information related to installing, maintaining, and sourcing
AIM*Historian:

AIM*AT Installation Guide (B0193YM)

AIM*AT I/O Gate Drivers Users Guide (B0193YU)

AIM*API Users Guide (B0193YN)

AIM*SPC Users Guide (B0193YH)

AIM*DataLink Users Guide (B0193YJ)

AIM*Explorer Users Guide (B0193YK)

AIM*API Users Guide (B0193YN)

AIM*AT OPC Server Users Guide (B0400DG)

AIM*Inform Users Guide (B0400DS)

Wonderlink I/O Server Users Guide (B0193YP)
NetAPI MFC Class Users Guide (B0400BJ).
The following I/A Series documents provide information for AIM*Historian instances that access
I/A Series data:
Historian (B0193BL)

Process Operation and Displays (B0193MM)

System Operation Guide (Windows NT Operating System) (B0400CR)

System Operation Guide (B0193CR).

Document Overview
This guide is organized into the following sections:
Chapter 1 Overview
Features, architecture and information about product structure.
Chapter 2 AIM*Historian Configuration
Using AIM*Historian Configurator and other tools to configure
AIM*Historian instances and individual instance components such as
RTP and Event message configuration files.
Chapter 3 AIM*Historian Operation
Using AIM*Historian Manager and other tools to start, monitor, and stop
operation of AIM*Historian instances.
Chapter 4 Database Management
AIM*Historian file structure, database packing and reduction, and
on-demand and automatic archiving.

xix

B0193YL Rev E

Preface

Chapter 5 Troubleshooting
Diagnostic utilities and troubleshooting tables.
Appendix A Error Codes
Error codes returned by AIM*API calls to access AIM*Historian.
Appendix B AIM*Historian Sample Status and Quality
Description of the AIM*Historian RTP status word.
Appendix C AIM*Historian Reduction Status and Quality
Description of the status word returned by AIM*Historian
reduction APIs.
Appendix D Data Reduction Algorithms
Table listing the algorithms for reducing data.
Appendix E AIM*Historian Component Attributes
Attribute descriptions of the AIM*Historian components.
Appendix F Sizing Guidelines
Information for determining the amount of disk space required to hold
AIM*Historian database files.
Appendix G Exporting to Oracle
A description of the AIM*Historian interface for exporting RTP and message data to Oracle DBMS tables.
Appendix H AIM*OLE DB Provider
Documents the command interface and data structures used to access
AIM*Historian data from customer-developed OLE DB applications.

xx

Preface

B0193YL Rev E

Conventions
In this document, the following conventions are used:

Verbatim keyboard entries are shown in this type, while variable information is
shown in italic. For example,

Invoke the sec2asc program.

sec2asc <Seconds>
In numbered instructions, this type is used for menu items, options, and buttons that
are to be selected on the screen.
Instructions for making selections from the application menu bar and associated
pull-down menus use the following format:
1. Choose File > New.
The example is shorthand for Pull down the File menu from the application
menu bar and select the New option from the menu.
Instructions for using the mouse on Windows platforms assume the mouse is configured for the right hand, that is, the left mouse button is used for normal select and
drag operations, and the right mouse button is used for context menus and special
drag operations.
Appendix E AIM*Historian Component Attributes and other sections of this guide
use the UNIX convention when giving file or directory names. If you have a
Windows NT based system, please adjust these accordingly:

Prefix with drive letters such as d:

Use a backslash (\) instead of a forward slash (/)
Add .exe to the executable file name.

The table below lists the location of AIM*Historian programs and instances for various platforms if the AIM*Historian software was installed using default
directories. The instruction examples in this guide assume the software was installed
using the default locations.
Platform

Solaris Servers including

I/A Series AW/AP51s
Windows NT Servers
I/A Series AW70s

Program Directory

Database Directory

/opt/aim/bin

/opt/aim/inst

c:\Program Files\aim\bin
d:\opt\aim\bin

c:\Program Files\aim\inst
d:\opt\aim\inst

xxi

B0193YL Rev E

Preface

Request for Comments

Please direct your comments and suggestions concerning the AIM*Historian, other AIM*AT
products, and this documentation to:
Customer Satisfaction Center
Invensys Systems, Inc.
33 Commercial Street
Foxboro, MA 02035-2099
Telephone within the US: 866-746-6477
Telephone from outside the US: 508-549-2424
Facsimile: 508-549-4999

xxii

1. Overview
This chapter introduces AIM*Historian, describes the product architecture and the major
software components, and defines key concepts used throughout this guide.
AIM*Historian is a client/server application that collects, organizes, and stores historical data.
AIM*Historian accepts data from I/A Series systems and other types of automation and control
systems, including distributed control systems (DCSs), programmable logic controllers, and
supervisory control and data acquisition (SCADA) systems. Historical data can include real-time
point (RTP) values and Event messages such as process alarms and Batch definition messages.

AIM*Historian Features
AIM*Historian provides diversified platform support and operates on network servers running
any of the following:
Solaris 2.5.1 or later, including I/A Series AP/AW51s

Windows NT 4.0 or later, including I/A Series AW70s

Windows Terminal Server, including I/A Series Server 70s

Windows 2000
Windows XP Professional.
AIM*Historian and the I/A Series Historian can run on the same I/A Series node. You can
migrate Historian configurations and data to an AIM*Historian instance (see AIM*Historian
Instance on page 3), but not vice versa. AIM*Historian can also emulate the I/A Series Historian
and support the following I/A Series software:

Display Manager
FoxView
FoxAnalyst
I/A Series Report Package.
AIM*Historian supports other AIM*AT applications and sources data to AIM*Inform,
AIM*DataLink, AIM*Explorer, and AIM*SPC, as well as to custom applications developed with
AIM*API.
AIM*Historian also supports other programs using the libhist.a interface.
For backward compatibility only, you can interface with AIM*Historian using the I/A Series
Historian servers supplied with AIM*Historian. However, the interface for I/A Series
Historian servers does not support the AIM*Historian configuration function.

B0193YL Rev E

1. Overview

AIM*Historian operates on I/A Series stations and on corporate networks to provide these
features:
Support for databases of up to 250,000 points each
Data collection from proprietary systems via the I/O Gate Data Collector and specific
I/O Gate Drivers.

Support for numerous data types including:

Simple value types such as integers, floats, and booleans

Files and arrays

Binary large objects (BLOBS).

An ODBC driver that supports access to AIM*Historian from Windows desktops

Option to time stamp data in either coordinated universal time (UTC) or I/A Series
time
Export of sample and message databases to Oracle DBMS applications.

AIM*Historian Architecture
An AIM*Historian instance contains a user-defined configuration that specifies the data to be collected and where to store the historized data.
Multiple AIM*Historian instances can reside on a host computer. For example, you can define
one instance to collect recent data for support of local displays and define another instance for
long-term collection and storage of plant-wide data. Each AIM*Historian instance has one server
component and one or more data collector components. Figure 1-1 displays the AIM*Historian
client/server architecture.

AIM*Historian Archives
AIM*Historian Database
Local Event Message and
RTP Collector
I/O Gate Collector

The AIM*Historian instance

server operates on Solaris
and Windows NT stations
including I/A Series
AP/AWs

Remote I/A Series

Event Message
and Real-Time
Collector

I/O Gate
Device
Process Unit

Process Unit

Figure 1-1. AIM*Historian Client/Server Architecture

1. Overview

B0193YL Rev E

The AIM*Historian server component performs the following tasks:

Manages additions to the AIM*Historian data repository from local or
remote collectors
Manages AIM*Historian archives

Provides services to applications such as desktop displays and remote databases.

AIM*Historian collectors collect RTP and Event message data. When communication with the
server component is not available, remote AIM*Historian collectors buffer the data.

AIM*Historian Product Structure

The AIM*Historian product structure consists of:
AIM*Historian instance

AIM*Historian database

AIM*Historian interface structure.

AIM*Historian Instance
An AIM*Historian instance consists of a set of configuration and database files residing on an
AIM*Historian server. You can create, configure, and modify AIM*Historian instances using one
of the following methods:
AIM*Historian Configurator (histcfg)

Batch configuration using a configuration input text file (histbatch or histcbatch)

AIM*API fh_Cfg() call.

AIM*Historian supports multiple instances on a single host computer. An AIM*Historian
instance name must be unique within the host computer on which AIM*Historian is installed.
However, AIM*Historian instance names on different host computers can be the same. The files
associated with a specific AIM*Historian instance are stored in a separate directory in the /inst
directory. The name of the separate directory is the instance name. For example, the hist01
instance files are stored in /opt/aim/inst/hist01.

B0193YL Rev E

1. Overview

Instance Components
An AIM*Historian instance consists of the following components:

One or more data collectors

Zero or more real-time points (RTPs)
Zero or more Event messages

Zero or more control groups

Zero or more reduction groups.
Figure 1-2 displays the components that represent an AIM*Historian instance.

AIM*Historian
Instance
Data
Collectors

Reduction
Groups

Real-Time
Points

Control
Groups

Event
Messages
Figure 1-2. AIM*Historian Instance

The principal instance program, histmain, activates the instance, checks for changes in the
configuration, and processes optional control groups.

Collectors
AIM*Historian uses collectors to acquire and historize process data and messages (collector types
are defined on page 5). An AIM*Historian instance can have as many as 100 collectors.
All collector types can reside on the same computer as the AIM*Historian instance or on another
computer connected to the instance host via a network. The remote collector saves all send data in
a file to facilitate burst-mode communication. Remote collectors save the updates when the connection to the instance host breaks. When communication is restored, the collector sends the data
to the instance. The configuration information is always configured at the AIM*Historian
instance.

1. Overview

B0193YL Rev E

The collectors are installed from the AIM*AT CD. AIM*Historian provides three distinct collector types:
Real-time collectors for I/A Series systems
Event message collectors for I/A Series systems

The I/O Gate Collector for any I/O Gate Device driver.

AIM*Historian also allows configuration of collectors to support Sequence of Event (SOE) data
collection applications developed by Invensys. Information on configuring these specialized collectors is not provided in this document, but is supplied with the application.

Default Collector Configuration

When you create an AIM*Historian instance, the program automatically creates a local I/A Series
real-time point (RTP) collector with the same name as the instance.
When an off-platform instance collects I/A Series data points, the instance requires an I/A Series
collector on an AW/AP to serve as a remote collector for the data.

I/A Series Real-Time Collector

The I/A Series real-time collector collects real-time values from the I/A Series system, and sends
the value updates to the receiver program in the AIM*Historian server software. The default collector, which resides on the same system as the receiver, stores the changes directly into the
instance database files. An instance can have multiple local I/A Series collectors and multiple
remote collectors.
The I/A Series real-time collector operates on AW/AP51s and AW70s running I/A Series software
Version 6.1 and higher. The task requires AIM*API on the station.

I/A Series Event Message Collector

The I/A Series Event message collector (ipchisti) collects I/A Series messages such as CP alarms,
Operator Action Journal messages, and System Monitor messages. The task sends all configured
Event messages to the AIM*Historian instance and selected messages to the Alarm Summary file.
The AIM*Historian application also accepts messages from the HPS Message Manager.
The collector can operate on AW/AP51s and AW70s running I/A Series software Version 6.1 and
higher. The collector can run as either a local or a remote collector.
The ipchisti message collector program registers with the I/A Series Inter-Process Communication subsystem for each AIM*Historian instance directory on the instance host server, and checks
periodically to account for the creation and deletion of AIM*Historian instances.

B0193YL Rev E

1. Overview

If the histsend program has been run for a specific instance, histsend marks an internal flag which
tells the message running on the same machine to write its messages for the instance to a predefined circular file. The histsend program reads the circular file and transmits the messages over
the network to the histreceive program running at the machine where the data files for the
instance reside. The histreceive program writes the messages to the message data files.
NOTE

The histsend program is run for a particular instance and for the I/A Series
real-time collector. If the histsend program has not been run for a specific instance,
that is, the data files for the instance reside on the same system, the message collector writes its messages directly to the message data files for the instance, that is, to
m10.fdb, m20.fdb, and so on.

I/O Gate Data Collector

The I/O Gate Data Collector acquires real-time values from an I/O Gate Driver that supports a
specific protocol. There are eight I/O Gate Drivers:
Applicom

Collects data from Siemens S7 and other PLCs that support the
Applicom network protocol.

BASEstar

Links AIM*Historian instances with factory automation systems that use

the Compaq Computer Corporation BASEstar Networking Solution.

CHIP

Interfaces with control products that use the Computer Highway Interface Program (CHIP) provided by Fisher-Rosemount.

DDE

Communicates with control process using Microsofts Dynamic Data

Exchange (DDE) protocol.

ModbusPlus

Supports data collection from PLCs, such as AEG Schneider Automation

Modicon 984 Compact and 984 Slot-Mount Controller, via an RS-232C
serial connection and the ModbusPlus protocol.

ModbusTCP

Reads values from Modbus controllers using a TCP/IP connection to the

control system.

OPC

Connects with systems using OLE for Process Control protocol (OPC)
developed by the OPC Foundation.

REMIO

Provides connections for the AIM-Supervisor Remote Input/Output

(REMIO) subsystem provided by Simulation Sciences Inc.
The collector is a client program accessing data remotely from the I/O Gate based device drivers.
The AIM*Historian instance sends initialization information defining the RTPs to be collected to
the I/O Gate data collector. The collector then accesses the configured points from the I/O Gate
drivers and accumulates the points at the configured frequency.
The collector can retrieve and store values from multiple ports and multiple devices per port, but
it can only collect for one AIM*Historian instance.

1. Overview

B0193YL Rev E

The I/O Gate collector is installed from the AIM*AT CD. The collector is not automatically
installed. You must select the collector type as an option in the integrated AIM*AT setup program. You must then specifically configure the collector in the Collector Station Cfg window, as
described in Adding a Collector on page 59 or Collector Stations on page 68.
The I/O Gate Collector and the selected I/O Gate Driver must be installed on the same
station. See AIM*AT I/O Gate Drivers Users Guide (B0193YU) for information on installing and
operating the drivers.

Real-Time Points
Real-time values are defined by real-time point objects (RTPs). RTP values are collected by realtime collectors such as the I/A Series collector, or generated by applications such as the
AIM*Historian manual data entry program. The values are sent to AIM*Historian for storage in
the AIM*Historian database. A real-time data collector requires a definition of the RTP it has to
collect. The collector starts the collection of the data as specified in the RTP configuration and
stores the data in the AIM*Historian database.
The operation of an RTP is determined by its collection method (COLMETH attribute). There
are four options:
Connected

The default configuration for RTPs is the Connected method in which

the real-time collector reads values of connectable points in the I/A Series
system or other DCS.

Getval

This method is used for collecting I/A Series block parameters that are
non-configurable/non-connectable. This method is also used when
collecting string data.

MDE

The Manual Data Entry (MDE) configuration enables you to enter values
into an instance database as if they had been collected from the DCS.
Using the AIM*Historian MDE window or an AIM*API application, you
can enter time stamp, value, status, and optional annotations. MDE only
writes values to the AIM*Historian Database; it does not change values in
the control system database.

WRITE

RTPs configured for the WRITE collection method are used to write values to the DCS and record that output in the AIM*Historian database.
The values to be written to the DCS are entered with one of three
AIM*API functions calls:

an_write_objects()
an_write_valstat()

fh_FdbPutValue().
Refer to AIM*Historian Demand Writes on page 120 and to AIM*API
Users Guide (B0193YN) for information on the use of these calls.

B0193YL Rev E

1. Overview

An RTP has the following name attributes:

A tag name (NAME attribute) which uniquely defines an RTP within an
AIM*Historian instance. For backwards compatibility with the I/A Series
Historian and AIM*API, the NAME can be up to 32 characters long.

A name specific to a DCS system (NAMEINCOL attribute) which uniquely defines a

point within an AIM*Historian collector. NAMEINCOL can be up to 256
characters.

RTPs can represent many data types as displayed in Table 1-1.

Table 1-1. RTP Data Types

Data Type
Category
I/A Series
array types

non-I/A Series
array types

String

BLOBS
Files

Time Stamp

Data Type
Integer
Float
Long
Boolean
Character
Packed integer
Packed long
Character array
Short array
Unsigned short array
Integer array
Unsigned integer array
Float array
Double array
String

Number of Bytes
4 Bytes

Number of Elements
1 Element

1 Byte
User-defined
2 Bytes
2 Bytes
4 Bytes
4 Bytes
4 Bytes
8 Bytes
User-defined, including
User-defined
the longest possible
string plus null
terminator byte.
Binary large objects
User-defined
1 Element
The data content of BLOBs is unknown to AIM*Historian.
Data file contents
1 Byte
Number of elements is
the number of bytes in
the file
File contents are sent if file data is updated or RTP is triggered.
Time stamp for distin4 Bytes
1 Element
guishing a time value
from a long data type

1. Overview

B0193YL Rev E

Time Stamps
An AIM*Historian instance can be configured to store time stamps in either coordinated
universal time (UTC) format or in I/A Series time. AIM*Historian can provide collection of data
from a mixed I/A Series environment in which IATIME and UTC are used by different control
stations.

Collection Frequency
An RTP has a fast and slow collection frequency. You specify those frequencies in the RTP configuration. The data collectors send RTP values at a fast frequency. The value is stored at either
the fast or slow frequency, according to the currently selected frequency for the RTP.
For example, an RTP is configured with a fast frequency of one sample per minute and a slow frequency of one every five minutes. The collector always sends the data to the instance at the oneper-minute rate, but you can set the instance to accept all data (fast frequency) or any one sample
every five minutes (slow frequency).
A real-time data collector collects and sends RTP data if one of the following has occurred:

The RTP value changes significantly, that is, the change is more than or equal to the
specified delta.
The RTP files time stamp changes.

The RTP is triggered by a significant change in another point. The triggering point
can be any RTP in the same data collector.
The maximum time between samples (MTBS) of the RTP is reached.

The RTP status changes.

Event Messages
Event messages represent data that cannot be defined by an RTP. Event messages may have a
variable length and a combination of data types within the data.
Event messages include:
Alarm messages

Annotation messages
Batch definition messages such as those sent from FoxBatch.
Event messages are stored in AIM*Historian databases. You first configure an event message
and initiate the data collection process to start storing the messages in the
AIM*Historian database. The event message definition consists of assigning a key to each field in
the message.
A message key is defined by:

Key name
If this key is ODBC accessible, the key name also represents an ODBC column (the
ODBC driver only recognizes single element columns).
ODBC accessibility
Key sequence number
Field data type
Number of elements in the field data type.
9

B0193YL Rev E

1. Overview

You can add new message types at any time, but you can remove or modify the definition of existing message types only if no messages have been collected for the message type at the time of
modification.
Event message definitions also include a message group name and a message name. Examples of
group names are iaalarm and foxbatch. Use the group name definitions to avoid name conflicts
between two application packages using the same message name. The message group
AIMHistorian is reserved for use by AIM*Historian.
Figure 1-3 is a sample message definition.

Figure 1-3. Sample Message Definition

In the example, a definition is established for a message in the group my_message_group with the
message name my_message_name.
The first three keys (group, message, and time) are compulsory and cannot be modified or deleted.
The flag, alarm_type, event_nr, and text keys are optional.

The first field after the equal sign in the sample represents the sequence number and is
used to check for omitted key definitions.
The second field after the equal sign represents the ODBC flag. If the field is Y, the
key is read by the ODBC driver.

The third field after the equal sign represents the data type.
The fourth field after the equal sign represents the number of elements of the
specified data type.
NOTE

The message configuration input file includes complete definitions for all I/A Series
messages (See Configuration Using Input Text Files on page 64).

10

1. Overview

B0193YL Rev E

Control Groups
Some client applications require that groups of AIM*Historian RTPs or event messages be
switched in one operation to a different state or frequency. You can associate certain RTPs and
event messages in a control group that can be controlled by a client application or by triggering
RTPs.
For example, a plant runs from 8:00 a.m. to 5:00 p.m. and there is a shared variable
(PlantONOFF) that indicates the running of the plant. The value of the shared variable is
represented as 1 for the plant running and 0 for the plant when it is stopped. All historical
collection of all the control values in the plant can be started and stopped by creating a control
group that holds all the RTPs in the instance. The On/Off trigger RTP in the control group is the
PlantONOFF RTP and the threshold value is 1.
RTPs in a control group are switched in one autonomous operation between the following states:

On and Off
Bad and OK

Fast collection frequency and Slow collection frequency (see Collection Frequency
on page 9).
The changes can be based on the same or different triggers. Event messages in a control group are
switched in one autonomous operation between on and off.
A Control Group can be controlled either by a function call or by up to three RTPs.
NOTE

In addition, you can use two AIM*API calls, fh_RTPControl() and

fh_MsgControl (), to change RTP and Event message status individually.
Up to three RTPs can be assigned as the controlling RTPs for the control group. Switching
is performed at a specified threshold value. A triggering value falling below the threshold
value turns the control groups RTPs to Off, OK, or Slow. A triggering value rising to or
above the threshold value turns the control groups RTPs to On, Bad, or Fast. One triggering
RTP determines the Bad/OK state of all the RTPs, one triggering RTP determines the Slow/Fast
state of all the RTPs, and another triggering RTP determines the On/Off state of all the RTPs
and event messages.

11

B0193YL Rev E

1. Overview

Table 1-2 displays the RTP point values and the results for trigger values.
Table 1-2. RTP Trigger Values

Trigger
Type
OnOff

BadOK

FastSlow

If the trigger value is:

Then:

Less than the threshold value

All RTP and event messages in the group are

turned Off.
Greater than or equal to the All RTP and event messages in the group are
threshold value
turned On.
Less than the threshold value Do not force the setting of the bad bit in the status
word for subsequent values for all RTPs in the
group.
Greater than or equal to the Set the bad bit in the status word for subsequent
threshold value
values for RTPs in the group.
Less than the threshold value All RTPs in the group are collected at the slow
collection frequency.
Greater than or equal to the All RTPs in the group are collected at the fast
threshold value
collection frequency.

Reduction Groups
A reduction group is an AIM*Historian component you configure to allow another application
such as the I/A Series Historian to retrieve reduced data from AIM*Historian.
The parameters for the reduction group are:
Reduction group name

Description
Reduction interval

Percent of RTPs in the interval that must be valid for the points to be reduced
Operations list including name and type for each operation (the operation name is
used as the column name for ODBC and database export purposes)

Member RTP name list.

A reduction group cannot contain other reduction groups, nor can a reduction groups values be
the basis for the reduction.
NOTE

A reduction group is a retrieval mechanism only. It does not cause the generation of
reduced data in reduction data files.

12

1. Overview

B0193YL Rev E

AIM*Historian Interface Structure

AIM*Historian instances reside on a host computer that runs AIM*Historian. The
AIM*Historian server stores data from the data collectors and communicates with client
applications.
The AIM*Historian server interfaces with the AIM*API server for AIM*Historian instances and
with I/A Series stations for I/A Series Historians. The I/A Series station is accessed by an
I/A Series Historian name such as hist01. The I/A Series station interface can only be used for
data retrieval of I/A Series Historians and MDE (manual data entry) update. The I/A Series station interface does not support configuration interface functions such as adding an RTP. Use the
AIM*API server interface to retrieve and store data for an AIM*Historian instance and perform
configurations for an AIM*Historian instance.
The AIM*Historian server that interfaces with the I/A Series station communicates with
I/A Series client applications such as Display Manager, FoxView, and FoxTrend. The
AIM*Historian server that interfaces with the AIM*API server communicates with AIM*API
client applications such as AIM*Historian Configurator.
When you access an AIM*Historian instance from an AIM*API client application using an
AIM*API server, the instance is identified first by its IP name and then by its instance name.
First, connect to the AIM*API server where the AIM*Historian instance resides; for example, by
calling an_open_server(). Then reference the desired AIM*Historian instance by its instance
name in the Historian argument of the API you are using.
You can access data from an AIM*Historian instance using one of these interfaces:
AIM*API Interface, ODBC Interface, I/A Series Interface, AIM*AT OLE DB Provider, and
Oracle Export Utility.
Figure 1-4 illustrates how AIM*Historian information is retrieved.

13

B0193YL Rev E

1. Overview

AIM*API Client
Application

ODBC Client
Applications

FoxView, DM
FoxAnalyst

AIM*API Server
Interface

ODBC Driver
for Historian

I/A Series
Legacy Interface

AIM*Historian Database

Export
Utility

AIM*AT
OPC Server

AIM*AT
OLE DB Provider

Oracle
Applications

OPC Client
Applications

OLE DB Client
Applications

Figure 1-4. AIM*Historian Data Retrieval

14

1. Overview

B0193YL Rev E

AIM*API Interface
For fast access to AIM*Historian data, you can use the proprietary AIM*API interface and write
programs that access the AIM*Historian database. AIM*API functions access data locally or
remotely through networked AIM*API on various platforms.

ODBC Interface
AIM*Historian includes an ODBC driver to access AIM*Historian databases using the ODBC
API. This driver enables you to integrate AIM*Historian data into the many desktop applications
that support Microsoft ODBC API including Microsoft Access and AIM*DataLink.

I/A Series Interface

Data can be retrieved from AIM*Historian databases and integrated into legacy I/A Series
applications such as FoxView, FoxAnalyst, and Display Manager. AIM*Historian
emulates an I/A Series Historian for use in I/A Series applications, and provides modified servers
that can access AIM*Historian data rather than I/A Series Historian data.
Figure 1-5 illustrates the interface structure for the AIM*Historian system in the enterprise
intranet with emphasis on the application interfaces.

Export to Oracle
An AIM*Historian utility supports export of RTP files and message files to Oracle data files at a
configured frequency. The programs in the utility are described in Appendix G Exporting to
Oracle.

AIM*AT OPC Server

AIM*AT OPC Server is an optional software package that enables OPC compliant field
devices and business applications to access both current RTP values and historical data from the
AIM*Historian. The software supports the latest OPC Foundation standards for data access (DA)
and historical data access (HDA), as well as many of the optional features of both standards. Refer
to AIM*AT OPC Server Users Guide (B0400DG).

AIM*AT OLE DB Provider

AIM*AT OLE DB Provider is an optional AIM*AT program that enables you to develop
OLE DB clients using Visual Basic, Crystal Reports, and similar tools.
Appendix H AIM*OLE DB Provider describes the interface and data structures used by
the AIM*Historian OLE DB Provider to enable access to AIM*Historian data by means
of customer-developed OLE DB applications.

15

B0193YL Rev E

1. Overview

I/A Series Programs such

as Display Manager,
FoxView, and FoxTrend
use libhist.a to
communicate with
AIM*Historian or
legacy Historian.

Legacy
Applications

Legacy library libhist.a is

installed on I/A Series
systems.

libhist.a

Legacy applications
interface with
AIM*Historian without
re-coding or re-linking.

AIM*API Client
Applications

AIM*API Client
Libraries

Legacy
Interface

AIM*API
Server

The remote version of

the legacy interface
uses the AIM*API
client library to retrieve
data from off-platform
AIM*Historian instances.

Applications such as histspy

access internal databases directly.

Internal
AIM*Historian
Applications

I/A Series collectors:

Collect I/A Series
RTPs and Event
messages.
Send values to
AIM*Historian
Receiver.

Clients such as ODBC

Driver, FoxDraw, FoxCAE,
and AIM*Historian Configurator use AIM*API client
libraries to communicate
with local AIM*API libraries.
Libraries:
Translate calls into
TCP/IP messages.
Interface with AIM*API
Servers.
Support all AIM*Historian
and AIM*API functions
calls.
AIM*API Server:
Receives messages from
client libraries.
Calls local AIM*API
functions.
Translates the result into
a network message.
Sends the result to
AIM*API client libraries.

Local AIM*API
Library

Local Library supports internal

Invensys applications.

AIM*Historian
Database
Collector

AIM*Historian Instance is activated.

Configuration changes are checked.
Data from collectors is updated and
stored in AIM*Historian databases.

AIM*Historian
Server

I/A Series
RTP
Collectors

Event
Message
Collectors

I/O Gate
RTP
Collectors

Figure 1-5. AIM*Historian Interface Structure

16

2. AIM*Historian Configuration
This chapter describes setup of AIM*Historian instances with AIM*Historian Configurator
and instance configuration using a text editor.

AIM*Historian Configuration Tools

AIM*Historian Configurator is a client program that configures AIM*Historian instances on any
server on the network. You can also use AIM*Historian Configurator to modify an existing
instance even while it is active. This utility can be installed on either a Solaris workstation or a
Windows platform as described in the AIM*AT Suite Installation Guide (B0193YM).
You can configure an instance by creating a configuration input text file and then running the
histbatch program or histcbatch command line program to read the input file and create the
instance. You create and modify the configuration input text file using a text editor available on
your system. AIM*Historian provides these other tools for creating input text files:
leg2fh

Command line utility that reads legacy I/A Series Historian configuration
information and generates an AIM*Historian configuration input text
file.

cfgcmd.inp

A sample AIM*Historian instance configuration input text file that can be

used as a starting point.

histsave

AIM*Historian Save window saves the configuration of an existing

instance to a configuration input text file.

Figure 2-1 shows the programs and data involved in creating and maintaining an AIM*Historian
configuration.
I/A Series
Historian
Configuration
Information

leg2fh

cfgcmd.inp
(Sample File)

text editor

Copy the Sample File

AIM*Historian Configurator,
histbatch, and histsave are
GUIs invoked from
AIM*Historian Manager.

histbatch
AIM*Historian
Configurator can
also be installed
separately on a
networked PC.

AIM*Historian Configuration
Input Text File
(e.g., hist01.inp)

histcbatch

AIM*Historian
Configurator

fh_Cfg()
calls using
AIM*API

histsave

AIM*Historian Instance Configuration Files

(e.g., *.cfg files in /opt/aim/inst/hist01)

Figure 2-1. AIM*Historian Configuration Overview

17

B0193YL Rev E

2. AIM*Historian Configuration

AIM*Historian Configurator Window

The AIM*Historian Configurator utility can be used to configure a new AIM*Historian instance
on any Solaris or Windows server on the network. You can also use AIM*Historian Configurator
to modify an existing instance, even while it is operating. The changes you make to the instance
are not implemented until you commit the new configuration at the AIM*Historian Configurator
session. When you commit, the instance reads the changes from temporary configuration files to
its permanent files. Depending on the amount of data the instance is collecting, AIM*Historian
may require several collection cycles to copy and implement all of the configuration changes.
AIM*Historian Configurator supports the following configuration actions:

Name and configure an AIM*Historian instance

Configure RTPs
Set up event message collection

Configure a collector station

Create reduction groups

Set up control groups.

The AIM*Historian Configurator does not deal with authorization codes, security access
privileges, or individual users read/write access to specific objects. Refer to the AIM*AT Suite
Installation Guide (B0193YM) for information on API Admin.
NOTE

To use AIM*Historian Configurator, you must have AIMHIS package privileges

and system security access as configured in the AIM*API server. See the AIM*AT
Suite Installation Guide (B0193YM).
AIM*Historian Configurator includes the Historian Setup Wizard. The wizard queries the network for available servers, discovers the existing AIM*Historian instances on those servers, and
allows you to create and configure new instances. For configuring RTPs, the wizard calls the Data
Object Wizard, which provides a series of database filters for selecting data objects. The use of the
Data Object Wizard is described on page 29. Working with AIM*Historian Configuration File
windows is described in Editing Configuration Files on page 55.

18

2. AIM*Historian Configuration

B0193YL Rev E

Configuring Server Connections for Wizard Browsing

When you start the AIM*Historian Configurator, it broadcasts a request to the network to establish connections to AIM*Historian servers and to I/A Series stations for browsing for points. The
AIM*Historian Configurator also checks the local configuration file for specified connections in
the event that the broadcast function is disabled.
Use the applicable procedure below to add I/A Series stations to the configuration file.
If the IP name of the second Ethernet port of the I/A Series station has no more than six
characters, use the following procedure:
1. Run API Admin on the AIM*Historian Configurator host.
2. Select the Settings page.
3. Click Edit Server Connections to open a dialog box for adding server connections
(Figure 2-2).

Figure 2-2. Server Connection Dialog Box

4. Enter the IP name of the I/A Series stations Second Ethernet connection as the Path
Alias.
5. Enter its IP Address.
6. Click Apply.
API Admin now updates the [TCPIP] and [AIMServer Connections] sections of the
an_init.cfg file.

19

B0193YL Rev E

2. AIM*Historian Configuration

If the IP name of the second Ethernet port of the I/A Series station has more than six
characters, use the following procedure:
1. Edit the an_init.cfg file on the AIM*Historian Configurator host.
The file is located in /opt/windu on Solaris, and in c:\winnt or c:\windows on
Windows systems.
2. Add a line to the [TCPIP] section using the following format:
<Station IP Name>="<IP Address> 45678 /dev/tcp 1024"
For example:
SUNW504="152.155.196.61 45678 /dev/tcp 1024"

3. Add a line to the [AIMServer Connections] section using the following format:
<Alias>=<IP name> TCPIP 1 0 1 1 / 1
For example:
SUNW504=SUNW504 TCPIP 1 0 1 1 / 1

Starting the AIM*Historian Configurator

To start AIM*Historian Configurator on a Solaris platform:

Open a Command Tool window, and enter: /opt/aim/bin/histcfg

To open the AIM*Historian Configurator on a Windows platform:

Click the AIM*Historian Configurator icon in the AIM*AT folder, or choose:

Start > Programs > AimAT > Historian Configurator

On either platform you can start the utility from the AIM*Historian Manager window:
Start the AIM*Historian Manager and choose Tools > Configurator.
Each of these selections opens the AIM*Historian Configurator window displaying the application menu bar, a row of action buttons and the status bar at the bottom of the window.
The Historian Setup Wizard has been set to start up automatically. This preference can be
changed with the check box in the wizards first dialog box or with the Options menu in the
AIM*Historian application menu bar. The descriptions in this section assume the automatic
startup preference is set.
The window is otherwise empty until the Historian Setup Wizard has queried the network for
connected servers. The wizard then displays the Server dialog box in the middle of the window so
you can select one of the available servers. Figure 2-3 shows the AIM*Historian Configurator
window with the Server dialog box.

20

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-3. AIM*Historian Configurator Window

The Server dialog box is the first of four presented by the wizard. The other dialog boxes enable
you to select or create an AIM*Historian instance (Figure 2-4), configure RTPs and event messages for the selected instance (Figure 2-5), and set up control and reduction groups
(Figure 2-24).
AIM*Historian Configurator can be configured to automatically open the wizard when you start
AIM*Historian Configurator.
To set the startup preference:
Click Show wizard at startup in the Server dialog box, or choose:
Options > Show Startup Wizard
The options menu is available after the server has been selected.

21

B0193YL Rev E

2. AIM*Historian Configuration

Selecting an Instance
The next step is to select an existing AIM*Historian instance or start a new one. This section covers selection of an existing instance in order to describe other features of the AIM*Historian Configurator window. Instructions for creating a new instance begin on page 27.
To select an instance:
1. Highlight the name of the server you want to configure and click Next.
AIM*Historian Configurator opens the Historian dialog box for selecting or creating
an instance (Figure 2-4).

Figure 2-4. Instance Selection Dialog Box

The list box shows the instances already configured for the selected server. The New
button raises a dialog box for creating a new instance (Figure 2-8).
2. Choose one of the existing instances and click Next to view the third dialog box in the
wizard.
The Historian Setup Wizard opens the RTP/Messages dialog box, which includes two
tabbed pages: one for adding real-time points (Figure 2-5) and the other for
configuring event messages (Figure 2-21).

22

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-5. Real Time Points Page

When the Real Time Points page is selected, the dialog box allows you to add points
to the configuration.
NOTE

At this point, you can configure RTPs and Messages. Click Next to configure
control and reduction groups, or exit the wizard by choosing Finish.
3. Click Finish to close the wizard.

23

B0193YL Rev E

2. AIM*Historian Configuration

AIM*Historian Components Tree

The AIM*Historian Components Tree is a three-level display of servers, instances and instance
configuration files. You can manipulate the tree in much the same way you would use
Microsoft Explorer displays, clicking the plus sign and minus sign to the left of an item to expand
and collapse the display:
1. Click the plus sign to the left of a server name or the server name itself to display the
instances configured on that server.
Each instance is identified with an FH folder icon and the name of the instance.
2. Click the plus sign next to an instance or the instance name itself to display the six
configuration files associated with the application.
Figure 2-6 shows a fully expanded tree.

Server icon
and name
Configuration files
of the selected
instance

Instance icon
and name

Figure 2-6. AIM*Historian Components Tree

Configuration File Windows

To display a component configuration file:
1. Expand an instance to show the six components.
2. Click Instance Cfg to display the main configuration file for the instance.
AIM*Historian Configurator opens a window to the right of the components tree
containing a three-column grid to display the name, current value and description of
each attribute in the selected file. Figure 2-7 shows the main configuration file for
hist05, the selected AIM*Historian instance.
The center column in the grid is editable. Instructions for using component windows
start on page 55.
You can open several Configuration File windows for a single instance and switch
between them by clicking the file type in the AIM*Historian Components Tree.

24

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-7. AIM*Historian Configurator Window with Instance Configuration File Open

3. Click Ok in the tool bar to close the Configuration File window.

To prevent changes from being applied to the wrong instance, AIM*Historian
Configurator allows modification of only one instance at a time. Before you can select
another instance, all Configuration File windows for that instance must be closed.

25

B0193YL Rev E

2. AIM*Historian Configuration

Application Menu Bar

The AIM*Historian Configurator application menu bar includes six pull-down menus, which are
described in Table 2-1.
Table 2-1. AIM*Historian Configurator Application Menu Bar

Menu
File

Item
Create Historian
Instance

Run Historian Setup

Wizard
Server Status

Save and Exit

Edit

Window

Copy (Ctrl + C)
Cut (Ctrl + X)
Paste (Ctrl + V)
Tool bar
Status bar
Close

Options

Show Startup Wizard

Help

Help Topics
About histcfg

View

Description
Opens a dialog box for naming an
AIM*Historian instance. Places the instance name
under the designated server in the AIM*Historian
Components Tree.
Opens a wizard for naming an instance and configuring
RTPs, messages, control groups, and reduction groups.
Opens a dialog box to view the status of a selected server
and recent error messages, display user access privileges,
and connect AIM*Historian Configurator with the
selected server.
Raises a dialog box that asks if you want to commit the
configuration changes you have made before closing
AIM*Historian Configurator window. If no changes
were made, the AIM*Historian Configurator exits.
Provides standard Windows editing tools when you
select an editable item in a configuration file window.
Toggles the display of the respective window component on and off.
Closes the currently selected Configuration File
window.
Functionally equivalent to clicking the Ok button in the
tool bar.
When this option is checked, the
AIM*Historian Configurator displays the
Historian Setup Wizard when it opens the main
program window.
Displays an index of application-related help topics.
Displays program version and copyright information.

Command Buttons
The five command buttons immediately below the application menu bar are applied to the currently selected configuration file or the selected attribute within the file. Each button is active or
grayed out depending on which window items are selected.
For example, in Figure 2-7 with the Instance Cfg file open, only the Ok and Cancel buttons are
active. When you select the RTP Cfg file, Add becomes active for creating additional RTPs.
Delete and Modify are active when you select a specific RTP in the configuration file window.

26

2. AIM*Historian Configuration

B0193YL Rev E

Creating an AIM*Historian Instance

You can create one or more AIM*Historian instances on the workstation where the
AIM*Historian server software is installed. The AIM*Historian authorization code entered during AIM*API configuration allows the server to process up to a specified maximum number of
RTPs among all of the instances created for that server. You can set up as many as 100 instances
as long as you do not exceed the authorized RTPs.
You create an AIM*Historian instance with the Historian Setup Wizard or from the application
menu bar. Both actions open the Create AIM*Historian Instance dialog box (Figure 2-8).
To name a new AIM*Historian instance:
1. Choose File > Create Historian Instance from the application menu bar, or click New
in the Historian dialog box in the wizard (Figure 2-4).
AIM*Historian Configurator opens a dialog to associate a new instance name with the
selected server (Figure 2-8).

Figure 2-8. Create AIM*Historian Instance Dialog Box

The dialog box includes the name of the currently selected server in the first data field
and allows you to enter an instance name in the second field. The other data fields
show default values for size attributes for various instance components.
2. Use the pull-down menu in the first data field to change the server name.
3. Enter the instance name in the second field.
The name must be six characters long, using numbers and lower-case letters, to provide compatibility with I/A Series Historian and other applications configured to
access Historian databases.
An error message is displayed if the name does not contain six characters or if the
name duplicates another instance name on the same server.
27

B0193YL Rev E

2. AIM*Historian Configuration

4. Edit the size parameters if you want to change the supplied defaults.
NOTE

Before changing instance attributes that set maximum values, see the instructions
and cautions in Modifying Maximum Value Attributes on page 84.
5. Click OK.
AIM*Historian Configurator closes the dialog box and adds the instance to the
AIM*Historian Components Tree.

Configuring Real-time Points

This section describes the use of the Historian Setup Wizard to build the RTP component of an
AIM*Historian instance.
To configure RTPs:
1. Choose File > Run Historian Setup Wizard.
2. Use the first two dialog boxes to select or create the instance.
The wizard opens the RTP/Messages dialog box with the Real Time Points page
selected (Figure 2-9).

Figure 2-9. Real Time Points Page

3. Click Add.

28

2. AIM*Historian Configuration

B0193YL Rev E

Adding RTPs with the Data Object Wizard

The Data Object Wizard allows you to construct a series of database filters that search the configured servers for desired data objects. The wizard consists of five filter pages:
AIM*AT Server Filter
Defines connected AIM*AT servers and control stations as sources of data
objects.
Compound-Block Filter
Identifies blocks in the selected stations as sources of the control objects.
Parameter Type Filter
Completes specification of the data objects through selection of block
parameters. The parameters are grouped by type: Input, Output, and
String.
I/A Descriptor Filter
Allows you to select I/A Series DESCR parameters as retrieved criteria.
Results

Displays the data objects that meet the selection criteria set with the
preceding pages and allows you to make adjustments to the list.
As each page is used to specify selection criteria, the wizard queries the configured servers and
identifies resources available for the next level.

Filter Page Controls

The filter pages in the Data Object Wizard share a common set of button controls that assist in
the selection of objects (Figure 2-10).

Figure 2-10. Data Object Wizard Filter Controls

29

B0193YL Rev E

Filter

2. AIM*Historian Configuration

Filters the display to show only items that match the criteria specified in
the adjacent text box. The filter is applied to the lowest level of items that
can be displayed in the page:
Stations in the Server Filter page
Blocks in the Compound-Block page when the page is sorted by
Compound

Compounds in the Compound-Block page when the page is

sorted by Block
Block parameters in the Parameter Type page.
You can use an asterisk as a wildcard for one or more characters and a
question mark as a wildcard for a single character. For example, *PKY? in
Figure 2-10 finds 57PKY1, 57PKY3, and 6PKYA, but not 6PKY01.
Show Selected

Opens a dialog box that displays the currently selected items in the page.
Figure 2-11 is a Show Selected dialog box opened from the Server Filter
page.

Figure 2-11. Selected Server Stations Dialogue Box

30

2. AIM*Historian Configuration

B0193YL Rev E

Expand

Expands the display of each item in the list box to show the next level.
This button is the equivalent of clicking the plus sign adjacent to each
server, compound, block type, or block icon.

Collapse

Collapses the entire display to the next higher level. This button is the
equivalent of clicking the minus sign adjacent to each server, compound,
block type, or block icon.

Select All

Selects all items in the list box. The function is only applied to the current
filter page. For example, when you choose Select All on the
Compound-Block Filter page, it does not affect the CP selection made on
the previous page.
If you have narrowed the displayed list using the filter button prior to
clicking Select All, all items matching the filter criteria, and only those
items, are selected.

Clear All

Clears all selections displayed in the list box. The function is only applied
to the current filter page. For example, when you choose Clear All on the
Compound-Block Filter page, it does not affect the CP selection made on
the previous page.

There are four function buttons across the bottom of the Filter pages (as seen in Figure 2-13).
Back

Returns to the previous page. You can always return to the previous page
to make additional selections. Going back one page does not clear the
selections made at the lower levels.

Next

Implements the selections made in the current page and opens the next
page in the wizard.

Cancel

Closes the Data Object Wizard and returns to the main

AIM*Historian window.

Help

Raises the Help window with information specific to the dialog box.

AIM*AT Server Filter

The AIM*AT Server Filter page in the Data Object Wizard (Figure 2-12) displays the aliases of
the stations that have been configured as servers for the AIM*Historian application.
Each server is identified by an icon and the server alias. A plus sign to the left of the icon indicates
that you can expand the display to show the Control Processors (CPs) and other stations hosted
by the server.
When the display is expanded or there are more servers than can be displayed in the list box, a
scroll bar and arrow buttons on the right side of the box are active.

31

B0193YL Rev E

2. AIM*Historian Configuration

Figure 2-12. Data Object Wizard Server Filter Page

1. Click + to the left of the first server icon and name.

The display expands to show the names of the CPs and other stations which you can
access through the selected server. To the left of each station name is a check box to
show that the station has been selected.
The Expand (+) button changes to the Collapse () button, which collapses the
individual server display.
2. Click the name of each station you want to include as a source of data objects.
The station is selected when a check mark appears in the box to the left of the name.
3. Click a stations name a second time to exclude it from the view.
4. Click Next.
The wizard displays a search icon as AIM*Historian queries the servers for the
compounds and blocks in the control databases of the selected stations. When the
discovery is complete, the wizard opens the Compound-Block Filter page
(Figure 2-13).

32

2. AIM*Historian Configuration

B0193YL Rev E

I/A Series Compound-Block Filter

After you narrow your selection to specific servers and stations using the Server Filter page, the
Data Object Wizard opens a page for selecting specific I/A Series blocks (Figure 2-13).

Figure 2-13. Compound-Block Filter Page Sorted by Compound

The list box in this page shows I/A Series compounds and blocks in the stations you selected in
the previous page. The compounds are represented by the compound name and a multicolored
icon of three boxes. When a compound display is expanded, each of its blocks is listed by the
block name and the block type in parenthesis. A check box to the left of the listing allows you to
select or deselect the block.
Option buttons to the left of the list box allow you to sort the display by compound or by block
name.

Click Compound-Block for an alphabetical list of compound names, which can be

expanded to show the blocks within each compound (Figure 2-13). When this sort is
used, Filter is applied to the blocks.
Click Block-Compound for a list of block names, which can be expanded to show the
compounds that include these blocks (Figure 2-14). When this sort is used, Filter is
applied to the compounds.

33

B0193YL Rev E

2. AIM*Historian Configuration

Figure 2-14. Compound-Block Filter Page Sorted by Block

To continue specifying data objects:

1. Select one or more blocks individually or by using the Filter and Select All buttons.
2. Click Next.
The wizard displays a search icon as it constructs a list of parameters for each block
type in the selection. When the discovery is complete, the wizard opens the
Parameter Type Filter page (Figure 2-15).

34

2. AIM*Historian Configuration

B0193YL Rev E

Parameter Type Filter

This page allows you to define the compound and block parameters used in the selection of data
objects (Figure 2-15). The list box has a three-level display of parameters:
The first level divides all block parameters into Input, Output, and String type
parameters (represented by circles with I, O, and S, respectively).
The next level is a list of block types that have the parameter type.

Each block type can be expanded to show its Input, Output, or String parameters on
the third level.

Figure 2-15. Parameter Type Filter Page

To further define your selections for the Data Object View:

1. Use the tree display or the filter to select the parameters of interest in the selected
blocks.
For example:
a. Enter OUT in the text box and click Filter to show only block types with an OUT
parameter.
b. Click Select All.
The wizard is set to find all OUT parameters in the selected blocks.
2. Click Next.

35

B0193YL Rev E

2. AIM*Historian Configuration

Filtering by I/A Series Descriptions

The I/A Series Description Filter (Figure 2-16) supports the selection of compounds and blocks
associated with certain descriptors. This page appears only when one of the servers is on an
I/A Series system and when certain files are loaded on that server. This filter is not essential for
selecting data objects and is ignored by the browser when the Automatic Load option on the page
has been checked.

Figure 2-16. Description Filter Page

To continue:
1. Using the Descriptor list as a guide, select the Compound:Block combinations of
interest.
2. Click Next.
AIM*Historian opens the Searching dialog box (Figure 2-17).

36

2. AIM*Historian Configuration

B0193YL Rev E

Searching Dialog Box

The Searching dialog box applies the filter criteria set in the preceding pages to create the list of
block parameters (Figure 2-17).

Figure 2-17. Object Search Dialog Box

The Searching Criteria drop-down list at the top of the box provides various search options based
on your selections in the previous pages:
Compound-Block
This is the only option presented if you did not select parameters in the
Parameter Type Filter page. The wizard constructs a view that includes all
parameters of the selected blocks.
(Compound-Block or Descriptor) AND Parameter Type
This option is one of three available if you have selected one or more
parameters in the Parameter Type Filter page and identified one or more
blocks in either the Compound-Block Filter page or the Descriptor page.
Make this choice to construct a view that has only the selected parameters
in the selected blocks.
(Compound-Block or Parameter Type) AND Descriptors
This option is one of three available if you have selected one or more
descriptions in the Descriptors page and identified one or more blocks in
the Compound-Block Filter page or parameters in the Parameter Type
page. Make this choice to construct a view that has only the selected
parameters in the selected blocks.

37

B0193YL Rev E

2. AIM*Historian Configuration

(Compound-Block or Descriptor) OR Parameters

This option is one of two available if you have selected parameters in the
Parameter Type Filter page and identified blocks in the Compound-Block
Filter page. Use this option to construct a view that includes all parameters of the selected blocks, all instances of the parameter types in the control databases of selected stations, and all parameters with the descriptors.
Parameters

This is the only option presented if you did not select blocks in the Compound-Block Filter page but did choose parameter types in the next window. Use this option to construct a view that includes all instances of the
parameter types in the control databases of selected stations.

RTP

This option is available when the AIM*Historian filter has been selected.

To start the search for the data points:

1. Click the drop-down list arrow button and select the search criteria.
2. Click Begin.
As the wizard conducts the search, it lists the data objects it discovers and reports the
total number found. When the search is complete, the wizard displays the Results
page, the final page in the sequence (Figure 2-18).

Results Page
The Results page window (Figure 2-18) displays objects that met the selection criteria defined
with the Filter pages, and allows you to make final adjustments to the object list.

Figure 2-18. Data Object Wizard Results Page

38

2. AIM*Historian Configuration

B0193YL Rev E

The list box contains a four-column display showing an object descriptor, the object source type,
the server alias, and the object tag.
When Check Historian Membership is selected, the AIM*Historian identifies and displays historized objects. A blue object descriptor icon with an H in the center indicates that the data point is
Historized, that is, the block parameter is configured in at least one I/A Series Historian or
AIM*Historian instance accessible through the configured servers. In Figure 2-18, the first, second, and fifth objects listed are Historized objects. A circle with no letter indicates an unhistorized
data object.
The object type is IA for a I/A Series compound or block parameter, and the tag uses the
<Compound>:<Block>.<Parameter> syntax.
Four control buttons above the list box allow you to make adjustments to your selection:
Add

Enables you to add data points to the view without changing the search
criteria. This button opens the Add Item dialog box (Figure 2-19).

Figure 2-19. Add Item Dialog Box

To add an item to the view:

Use the drop-down menus to select the object type and the server
alias.
Identify the object in the Item text box by entering the object tag.
Click OK.
The Add Item dialog box allows you to enter I/A Series Shared Variables,
which are not accessed by the filter pages. The tag is the Shared Variable
name. In Figure 2-19, the Shared Variable ALRMONOFF is being added to
the object list.
Refresh

Searches the servers using new selection criteria, if the criteria have
changed. Opens the Searching dialog box (Figure 2-17). This action
reverses any additions or deletions made from the Results page.

Select All

Selects all items in the list box. Use this function to delete all items from
the view.

Clear All

Clears all selections made in the list box.

39

B0193YL Rev E

2. AIM*Historian Configuration

To complete construction of the object list:

1. Review the objects selected.
2. Click Add to open the Add Item dialog box to include data objects not specified in
the Filter pages.
3. Highlight any objects you want to exclude and press the Delete key.
4. Click Next.
AIM*Historian closes the Data Object Wizard and makes the selected objects available in a data object tree in the Real Time Points page (Figure 2-20).
5. Click Next.
The Data Object Wizard closes and the selected objects appear in a data object tree in
the RTP/Messages dialog box (Figure 2-20).

Source Type

Server

Data Object

Figure 2-20. Data Object Tree in the RTP/Message Dialog Box

The tree is a three-level display of object types (currently always IA for I/A Series data
objects), server names and objects (listed as Compound:Block.Parameter). A plus sign
to the left of an item in the tree indicates that the display can be expanded to show the
next level. A minus sign indicates that the display can be collapsed to show the item
only.

40

2. AIM*Historian Configuration

B0193YL Rev E

6. Click an object to display the RTP parameters to the right of the data object tree.
7. Place the cursor on an object and hold the left mouse button down to highlight the
full name of the object.

Defining the RTP Configuration

The default attribute settings on the right side of the dialog box are applied to the RTPs created
from the data object tree.
Refer to Table E-7 for a detailed description of RTP attributes.
To define the RTP configuration:
1. Click one of the four options in the Collection Method area:
Connected for connectable points to be received from an I/A Series Collector or
an I/O Gate Collector.
MDE for points to be added via the AIM*Historian Manual Data Entry option
(see Manual Data Entry on page 112).

Getval for

non-connectable points.
WRITE to be able to write to points in the DCS via an I/A Series or I/O Gate collector (see AIM*Historian Demand Writes on page 120).
The Fast Collection Frequency is the interval at which the collector samples the point.
The Slow Collection Frequency is an optional slower rate at which AIM*Historian
can store the RTP samples.
2. To set the rates, enter a numeric value in the left data field for each setting and use the
pull-down menus to the right to choose the time units.
The selectable units are seconds, minutes, hours and days.
3. Click On in the Triggering box if the RTP samples are to be collected when there is a
significant change in another point configured in the collector.
If you select Triggering, enter the name of the trigger in the Point data field below the
options.
4. Configure the maximum interval between samples by entering a numeric value in the
data field on the left in the Time Between Sample box, and using the pull-down menu
on the right to set the time units.
The selectable units are seconds, minutes, hours and days.
5. Choose the Initial State and the Restart State by clicking options in their respective
boxes.
The Previous selection in the Restart State box recalls the operating state of each RTP
when the AIM*Historian instance was stopped.
When you have finished modifying the RTP configuration, click Finish in the RTP/Messages
dialog box to exit the Historian Setup Wizard.

41

B0193YL Rev E

2. AIM*Historian Configuration

Configuring Messages
The second page in the RTP/Messages dialog box is for entering event message components.
The maximum number of messages you can add to the AIM*Historian instance is defined by
the MSGDEFS field in the AIM*Historian cfg window (Figure 2-33). For an overview of event
messages, refer to Event Messages on page 9.
NOTE

A message configuration input file supplied with AIM*Historian contains complete

definitions of all I/A Series alarm and system monitor messages. To configure
messages using the configuration input file, refer to Configuration Using Input
Text Files on page 64.
To add an event message:
1. Click Messages in the RTP/Messages dialog box.
The wizard raises the Messages page which displays the currently configured messages
and provides control buttons for adding and deleting messages (Figure 2-21).

Figure 2-21. Messages Page

42

2. AIM*Historian Configuration

B0193YL Rev E

2. Click New.
The wizard opens the Message Definition dialog box (Figure 2-22). The dialog box
presents a spreadsheet for defining the message by inserting values in the cells for the
message parameters.

Figure 2-22. Message Definition Dialog Box

NOTE

Blue text means that the keys are committed and cannot be changed.
Each message definition includes the parameters listed in Table 2-2.
Table 2-2. Message Definition Fields

Field

Description

Message Group
Message Name
Messages will be logged

Message group of up to 32 characters.

Message name of up to 32 characters.
Indicates if the messages collected can be updated in the database.
Select Yes or No.
Keyword of up to 14 characters, to identify the name of the field
in the message.

Keyword

43

B0193YL Rev E

2. AIM*Historian Configuration

Table 2-2. Message Definition Fields (Continued)

Field
ODBC Option

Type

Number of Elements

Description
Indicates if the specific keyword is to be represented through the
ODBC interface. For example, change the value to Yes using the
scroll arrows for the message group field Group if you want the
group name to be used through the ODBC interface. Indicate No
in this field if the specific keyword is not to be represented
through the ODBC interface.
Select the data type for the key displayed in the keyword column.
The data types are shown in the pull-down menu. Use the scroll
bar to select your choice of data types.
Number of array elements of the specified type. For non-array
value types, Number of Elements must be 1. For array value
types, Number of Elements must be greater than or equal to 1
and less than or equal to the AIM*Historian instance ARCHSIZE
value divided by 2.

3. Click Add to create a new key.

AIM*Historian Configurator opens the New Key dialog box (Figure 2-23).

Figure 2-23. New Key Dialog Box

4. Enter the new Keyword in the Enter name field, check or uncheck the ODBC option,
and enter the data type specifications.
5. Click OK.
AIM*Historian Configurator closes the dialog box and returns you to the Message
Definition dialog box.
6. Click OK when you have completed the message definitions.
The wizard returns to the RTP/Messages dialog box.

44

2. AIM*Historian Configuration

B0193YL Rev E

Creating Control Groups

Some client applications that use AIM*Historian data require that groups of AIM*Historian
RTPs or event Messages be switched in one operation to a different state or frequency. You can
associate certain RTPs and event Messages in a control group that can then be controlled by a
trigger RTP, or by client application.
RTPs in a control group are switched in one autonomous operation between the following states:

On and Off
Bad and OK

Fast and Slow.

Event messages in a control group are switched in one autonomous operation between On
and Off.
To set up a control group:
1. Click Next in the RTP/Messages dialog box.
The wizard displays the Groups dialog box (Figure 2-24). The dialog box contains
two tabbed pages, one for control groups and the other for reduction groups.

Figure 2-24. Control Page in the Groups Dialog Box

45

B0193YL Rev E

2. AIM*Historian Configuration

The list box in the center of the page displays the currently configured control groups
by group name.
2. Click New.
The wizard raises the Control Group dialog box (Figure 2-25).

Figure 2-25. Control Group Dialog Box

3. Enter the group name and a description in their respective data fields.
The control group name can be any alphanumeric string up to 10 characters long.
The descriptor can have 32 alphanumeric characters.
The Next button becomes active when there are entries in the fields.

46

2. AIM*Historian Configuration

B0193YL Rev E

4. Click Next.
The wizard opens a dialog box for identifying up to three real-time points that are to
trigger a change in the state or frequency for the RTPs and event messages in the
group (Figure 2-26).

Figure 2-26. Trigger RTPs Dialog Box

The dialog box consists of a Filter text box and button, the Historized RTPs list box
that shows the available real-time points, and text fields for the trigger RTPs. Initially,
the Historized RTPs list box is empty.
5. Enter a selection criteria in the Filter field and click Filter.
The asterisk is a wildcard character. Entering * by itself retrieves all objects.
The list box shows RTPs matching the criteria. Figure 2-27 shows the results of selecting object names beginning with FHLE.
6. Select a point for each trigger type by highlighting the RTP and clicking the rightpointing arrow next to ON/OFF, BAD/OK or FAST/SLOW.
You can deselect a point by clicking the left facing arrow next to the trigger type.
7. Enter a threshold value next to the type.
The use of the threshold value is described in Table 2-3.

47

B0193YL Rev E

2. AIM*Historian Configuration

Table 2-3. RTP Trigger Values

Type

Trigger Value

Action

ON/OFF

Less than the threshold

BAD/OK

Greater than or equal to

the threshold
Less than the threshold

FAST/SLOW

Greater than or equal to

the threshold
Less than the threshold

All RTP and event messages in the group are turned

Off.
All RTP and event messages in the group are turned
On.
Do not force the setting of the bad bit in the status
word for subsequent values for all RTPs in the group.
Set the bad bit in the status word for subsequent
values for RTPs in the group.
All RTPs in the group are collected at the Slow
collection frequency.
All RTPs in the group are collected at the Fast
collection frequency.

Greater than or equal to

the threshold

8. Click Next.
The wizard opens a dialog box for identifying the real-time points to be included in
the control group (Figure 2-27).

Figure 2-27. Controlled RTPs Dialog Box

The list box on the left displays RTPs selected from those configured in the instance.
One or more of the selected RTPs can be moved to the Controlled RTPs list box to be
included in the control group. Initially, both list boxes are empty.

48

2. AIM*Historian Configuration

B0193YL Rev E

9. Enter a selection criteria in the Filter field and click Filter.

The asterisk is a wildcard character. Entering * by itself retrieves all objects.
The list box shows RTPs matching the criteria. Figure 2-31 shows the results of selecting object names beginning with FHLEA. (Some of the objects have already been
moved to the Controlled RTPs list.)
10. Select an RTP and click the right pointing arrow to include the RTP in the control
group.
Select a control point and click the left pointing arrow to remove it from the group.
11. When the list is complete, click Next.
The wizard opens a dialog box for identifying the event messages to be included in the
control group (Figure 2-28).

Figure 2-28. Controlled Messages Dialog Box

The list boxes and arrow buttons in the Controlled Messages dialog box work the
same way as those in the Controlled RTPs dialog Box.
12. Select events messages to be controlled by the ON/OFF trigger RTP.
13. Click Next to end the Control Group configuration and return to the Groups
dialog box in the Historian Setup wizard.

49

B0193YL Rev E

2. AIM*Historian Configuration

Adding Reduction Groups

A reduction group allows an I/A Series Historian application to retrieve reduced data from
AIM*Historian.
The parameters for the reduction group are:
Reduction group name

Description
Reduction interval

Percent valid: the percent of values in the interval that must be valid for
AIM*Historian to calculate a reduced value for the interval
Operations list.
A reduction group cannot contain other reduction groups, nor can a reduction groups values be
the basis for the reduction.
Supported AIM*Historian reduction operations are:

Average
Min

Max
Sum

Standard deviation
Kurtosis

Linearization
HiLo.
To configure a reduction group:
1. Click the Reduction page in the Historian Setup Wizard Groups dialog box.
The wizard raises a dialog box for naming and describing the new Reduction Group
(Figure 2-29).

50

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-29. Reduction Group Dialog Box

2. Enter the group name and a description in their respective data fields.
The reduction group name can be any alphanumeric string up to 10 characters long.
The descriptor can have 32 alphanumeric characters.
The Back and Next buttons become active when there are entries in the fields.

51

B0193YL Rev E

2. AIM*Historian Configuration

3. Click Next.
The wizard opens the Parameters dialog box (Figure 2-30).

Figure 2-30. Parameters Dialog Box

4. In the first data field, enter the percentage of values in the interval that must be OK
before a value can be reduced.
You can enter the value directly into the field, or use the spinner buttons to increase
or decrease the default percentage.
An RTP value is considered OK for inclusion as part of the reduction calculation if
the status word corresponds to the following values:
Bits 0 to 4
Bit 8
Bit 11

Value type
Bad bit
Out Of Service (OOS)
bit

A numeric: 2, 3, 5, 6, 22 to 26, or 28 to 30
Not Bad: 0
In service: 0

5. Enter a value in the Frequency field or use the spinner buttons to increase or decrease
the default frequency.
The count represents the number of reduction for the group during each period. The
period is specified in the Frequency Units field.

52

2. AIM*Historian Configuration

B0193YL Rev E

6. Use the pop-up menu in Frequency Units to select milliseconds, seconds, minutes,
hours, or days for the frequency units.
7. Click Next.
The wizard opens a dialog box for identifying the real-time points to be included in
the reduction group (Figure 2-31).

Figure 2-31. Reduction Group RTPs Dialog Box

The list box on the left displays RTPs selected from those configured in the instance.
One or more of the selected RTPs can be moved to the Reduction RTPs list box to be
included in the reduction group. Initially, both list boxes are empty.
8. Enter a selection criteria in the Filter field and click Filter.
The asterisk is a wildcard character. Entering * by itself retrieves all objects.
The list box shows RTPs matching the criteria. Figure 2-31 shows the results of selecting object names beginning with FHLEA. (Some of the objects have already been
moved to the Reduction RTPs list.)
9. Select an RTP and click the right-pointing arrow to include it in the reduction group.
Select a reduction point and click the left-pointing arrow to remove it from the group.

53

B0193YL Rev E

2. AIM*Historian Configuration

10. When the list is complete, click Next.

The wizard opens a dialog box to specify the reduction operation to be performed on
the selected RTPs (Figure 2-32).

Figure 2-32. Reduction Group Operations Dialog Box

11. Check one of the eight operations to be used in reducing the real-time points.
12. Click Finish to complete the reduction group configuration and return to the Groups
dialog box in the Historian Setup Wizard.
13. Click Finish in the Groups dialog box to close the wizard and return to the
AIM*Historian Configurator window.

54

2. AIM*Historian Configuration

B0193YL Rev E

Editing Configuration Files

Instance Configuration File
When you create an instance, AIM*Historian Configurator applies default values to most of the
instance configuration parameters. You can modify these values and configure the other parameters, such as the database search path, using the AIM*Historian Cfg window (Figure 2-33).

Figure 2-33. AIM*Historian Cfg Window and Instance Parameters

55

B0193YL Rev E

2. AIM*Historian Configuration

To modify an AIM*Historian instance configuration:

1. Expand the components tree to display the six configuration files for the instance and
select Instance Cfg.
2. Use the vertical scroll bar to display additional parameters in the file.
Numeric fields have spinner buttons on the right so you can increase or decrease the
value by clicking the up or down arrow. Other fields have drop-down menus which
you display by clicking the single arrow button in the field.
NOTE

Before changing instance attributes that set maximum values, see the instructions
and cautions in Modifying Maximum Value Attributes on page 84.
3. Select the Value field for the parameter you want to modify and enter the new value.
4. Click OK to close the configuration window and return to the components tree.
For more detailed descriptions of AIM*Historian fields, see Appendix E AIM*Historian Component Attributes.

RTP Configuration Window

You can also use the RTP Configuration window to add RTPs and modify ones you have already
configured.
To view configured RTPs:
1. Expand the components tree to display the six configuration files for the instance and
select RTP Cfg.
AIM*Historian Configurator displays the RTP Configuration window, a grid that
identifies the currently configured points. Approximately a third of the RTP parameters (columns) can be displayed at one time.
2. Use the horizontal scroll bar or the arrow keys to view additional parameters for each
RTP. Use the vertical scroll bar or arrow keys to view additional configured points.
Figure 2-34 shows all the RTP parameters in three separate bands.

56

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-34. RTP Configuration Window

You can edit the RTP values by selecting the appropriate field and entering new values. A
separate Edit RTP window is available that presents all of the attributes of a selected RTP in a single display that eliminates the need to scroll the view.

Editing RTPs
To edit an RTP:
1. Double-click the RTP entry in the listing, or select the RTP entry number and click
Modify.
AIM*Historian Configurator opens a window for editing the RTP parameters
(Figure 2-35).

57

B0193YL Rev E

2. AIM*Historian Configuration

Figure 2-35. Edit RTP Window

NOTE

When you specify an RTP value type (other than FILE), the size of the value is
fixed. The size of a given RTP value is not necessarily the same as that of the target
point in the DCS. For example, the size of the integer type RTP (FH_INTEGER,
2) is 4 bytes. This type is used to collect integer values from an I/A Series system.
Integers in I/A Series software (also referred to as Type 2) are only 2 bytes. Thus,
when collecting integer values from the I/A Series system, AIM*Historian stores a
2-byte value in a 4-byte field. Likewise, when you write values to an I/A Series system integer using a demand write RTP, you must limit the range of the value to fit
into a 2-byte field. The range for the integer value is 32768 to 32767.

58

2. AIM*Historian Configuration

B0193YL Rev E

2. Select the Value field for the parameters you want to change and enter the new
values.
3. Click Ok.
The Edit RTP window closes, returning the RTP Configuration window to view.
NOTE

When you enter a new RTP name in the Name field, the AIM*Historian
Configurator automatically updates the NAMEINCOL field to the same name.

Deleting RTPs

To remove an RTP from the configuration, select the point RTP Configuration
window and click Delete.
Deleting an RTP removes the point from the count of total points allowed under your
AIM*Historian license.

If there are no samples collected for the RTP, you can re-use the RTP name.
If there are samples collected, to re-use the RTP name you must use
FORCE_DELETE, as described in Permanent Delete on page 78.

Adding a Collector
An AIM*Historian collector station represents the data collector used for a specific
AIM*Historian instance. When you create an instance, AIM*Historian automatically creates a
local real-time collector, giving it the same name as the instance. You do not need to create a local
message collector. You can add up to 100 collector stations to reside either on the same computer
as the AIM*Historian instance you are configuring or on another computer with a network connection to the host.
To add a collector:
1. Open the AIM*Historian Configurator window, select the instance, and expand the
instance component tree.
2. Select Collector Station Cfg from the component tree for the AIM*Historian instance
you are modifying.
The configuration window for the collector station component is displayed
(Figure 2-36).

59

B0193YL Rev E

2. AIM*Historian Configuration

Figure 2-36. Collector Station Configuration File Window

The Collector Configuration window in Figure 2-36 lists the default local real-time
collector (aim001) on line 3 below two server elements (which you do not need to
configure). When the collector is selected, you change its configuration by clicking
the Modify button in the tool bar.
3. Click Add.
AIM*Historian Configurator opens a dialog box for selecting the collector type
(Figure 2-37).

Figure 2-37. Collector Station Type Dialog Box

60

2. AIM*Historian Configuration

B0193YL Rev E

The dialog box lists three options:

IA_RT_COLLECTOR
IA_MSG_COLLECTOR

IOGATE_COLLECTOR

To collect RTPs from the I/A Series system.

This collector can be either local or remote.
To set up a named message collector.
This is only necessary if you plan to implement a remote
message collector and the remote collector machine will
not have a real-time collector.
To collect RTPs from a non-I/A Series control system.
The IO Gate Data Collector requires configuration
of a protocol-specific I/O Gate Driver as described in
AIM*AT I/O Gate Drivers Users Guide (B0193YU).
This collector can be either local or remote.

4. Select the collector type and click Ok.

AIM*Historian Configurator opens a setup window for the new collector
(Figure 2-38).
If you are using the I/O Gate Collector, refer to the AIM*AT I/O Gate Drivers Users
Guide (B0193YU) for information on configuring the appropriate drivers.

Figure 2-38. Collector Setup Window

5. Enter a Collector Name of up to 48 alphanumeric characters.

6. Enter the hostname of the collector machine computer in the HOSTNAME field.
This HOSTNAME value is assigned to the collector host computer when the
AIM*Historian software is installed on the collector machine. AIM*Historian
server uses this hostname to establish a network connection to the collector machine.
See the AIM*AT Installation Guide (B0193YM).

61

B0193YL Rev E

2. AIM*Historian Configuration

7. If appropriate, use the pull-down menus and rotary buttons to change the default
settings in the other attribute fields.
See Collector Component on page 237 for attribute definitions and descriptions.
8. Select File > Close to close the Collector Setup window.
The new collector information appears in the Collector Station Configuration File
window with the other collector stations associated with the particular
AIM*Historian instance you are configuring.

Other Configuration File Windows

You can modify the message, control group and reduction group components using their
respective Configuration File windows and the same techniques as used for modifying the
instance, RTP, and collector configuration files.

Server Status
To check the status of the servers:
1. Choose File > Server Status.
AIM*Historian Configurator opens the AIM*Historian Server Status dialog box
(Figure 2-39).

Figure 2-39. Server Status Dialog Box

The dialog box displays a page view for each server accessible from the
AIM*Historian Configurator application.
In the Server box, the page lists the server name, the current user name, and recent
error messages.

62

2. AIM*Historian Configuration

B0193YL Rev E

The User Function Access box displays the security access privileges configured in
AIM*API for the named user on this server. You need access to API Admin to change
these settings; they are not accessible from AIM*Historian Configurator. See the
AIM*AT Installation Guide (B0193YM) for additional information about security
access privileges.
When the AIM*Historian Configurator is not connected to the server, the
Reconnect button is active.
2. Click Reconnect if you want the AIM*Historian Configurator to attempt to
establish a connection with the selected server.
3. Click Close to return to the AIM*Historian Configurator window.

Finishing an AIM*Historian Configurator Session

To end an AIM*Historian Configurator session:
1. Determine whether you want the Historian Setup Wizard to open automatically the
next time you start AIM*Historian Configurator.
2. Choose Options > Show Startup Wizard to change the option.
3. Choose File > Exit.
If you have made any changes to any configuration files, AIM*Historian
Configurator displays a dialog box to specify whether the changes are to be
implemented (Figure 2-40).

Figure 2-40. Closing Options Dialog Box

There are three closing options:

Commit saves the changes to the configuration files and implements the
changes.
Save stores the work from the session but does not implement the changes.
Save allows you to resume configuration of the instance at a later time.

cancels the changes and maintains the configurations files as they

were when you began the AIM*Historian Configurator session.
4. Click one of the three options.
Discard

63

B0193YL Rev E

2. AIM*Historian Configuration

Configuration Using Input Text Files

AIM*Historian provides two resources to assist in creating a configuration input text file: an
example configuration (described in Instance Configuration on page 65) and histsave
(described in Using histsave on page 79).
The sample file, cfgcmd.inp, is installed with the AIM*Historian software. It provides
instructions and a template for creating both an instance and component configuration files. The
file is located in the examples directory. For modification, copy the files to another directory such
as /opt/aim/myfiles. Table 2-4 lists the locations of these files on different platforms if the
software was installed to the default directories.
Table 2-4. Default AIM*Historian Installation Directories

Platform
Solaris Servers including I/A Series AW/AP51s
I/A Series AW70s
Other Windows NT Servers

Sample Batch File Locations

/opt/aim/examples
d:\opt\aim\examples
c:\Program Files\aim\examples

Copy the file and modify it as necessary using a text editor on your system. Once the file is
created, you can use either histbatch (page 81) or histcbatch (page 83) to implement the
configuration.
A modified version of the cfgcmd.inp is listed below with headings and comments marking the
major sections of the file:
Instance and Instance Attributes
Collector Stations

RTPs
Event Messages

Control Groups
Reduction Groups

Committing the Session.

The configuration input text files follow these rules:

In its most complete form, a line has the following structure:

fhsd <action> <component> <component name> <attribute> <value> <indicator>
A line can be specified in shorter format as shown in the file.
Blank lines and lines beginning with pound signs are ignored.
Field values that include spaces or punctuation marks must be enclosed in quotes.
Note that in the example configurations quotation marks enclose the values for various attributes that provide descriptions of the component, such as the instance
attribute FHDESC and the RTP attribute DESC. The use of the quotation marks
prevents AIM*Historian from interpreting a blank space and other punctuation in a
description as the end of the attribute value.

64

2. AIM*Historian Configuration

B0193YL Rev E

Instance Configuration
The first section of the file creates the instance and starts an instance session (Figure 2-41).
Each command in the file is preceded by a description of the command. Refer to Appendix E
AIM*Historian Component Attributes for detailed information on specific component
attributes.

Figure 2-41. Establishing the Instance

If the instance already exists, the create instance (CREATE AIMHIST <Instance Name>)
command is ignored.
When you are updating an existing instance, you must start the file with a create session command and end the file with a commit session command, and both must reference the instance
name
NOTE

Before setting or changing instance attributes that set maximum values, see the
instructions and cautions in Modifying Maximum Value Attributes on page 84.
After creating the instance and starting a session, the sample input sets the instance attributes
(Figure 2-42 and Figure 2-43). Refer to Table E-4 in Appendix E AIM*Historian Component
Attributes for an explanation of each instance attribute.

65

B0193YL Rev E

2. AIM*Historian Configuration

Figure 2-42. Configuring Instance Attributes

Note that only a few of the commands are commented out. Most attributes in the sample file are
set to the default values.
The second part of the instance configuration section (Figure 2-43) sets performance attributes
such as collection frequency and reduction intervals.

66

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-43. Configuring Instance Attributes, Continued

67

B0193YL Rev E

2. AIM*Historian Configuration

Collector Stations
This section provides models for setting up collector stations. The file contains example input for
these configuration actions:
Modify the default local real-time collector (I/A Series collector or I/O Gate collector,
depending on the platform)
Set up a remote I/A Series Real-time Collector

Configure a local I/O Gate Collector

Create a remote I/O Gate Collector.
Figure 2-44 and Figure 2-45 show the input for configuring a remote I/O Gate Collector.

Figure 2-44. Configuring a Remote I/O Gate Collector

If an attribute is not specified in the input for a new collector, AIM*Historian sets the attribute to
the appropriate default.
If the named collector already exists, the CREATE STATION command is ignored. Attributes
that are set in the input file overwrite the existing attributes; the other attributes in the
configuration are unchanged.

68

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-45. Configuring a Remote I/O Gate Collector, Continued

Real-Time Points
The RTP section provides sample input to configure RTPs for the following:
Collect samples from a typical I/A Series object using the default I/A Series real-time
collector (Figure 2-46)
Trigger collection of the I/A Series object when another RTP is collected
Collect manually entered data (MDE type RTP).
See Manual Data Entry on page 112 for additional information on MDE
Manually enter data for a Double Array (8 bytes)
Collect a string

Trigger Collection of a file when another RTP is collected

Collect samples from a typical I/A Series object using the remote real-time collector

Collect data from a non-I/A Series DCS using a local I/O Gate collector.
Refer to the AIM*AT I/O Gate Drivers Users Guide (B0193YU) for configuring the
NAMEINCOL attribute and other driver-specific requirements.
Collect data from a non-I/A Series DCS using a remote I/O Gate collector

Write to an I/A Series object (Demand Write RTP).

Refer to AIM*Historian Demand Writes on page 120 for information on this RTP
type.
69

B0193YL Rev E

2. AIM*Historian Configuration

The input in Figure 2-46 creates the RTP C1:B1.RI01 of type FLOAT in collector hist01.
The NAMEINCOL attribute is the DCS-specific name of the point; in this case, the I/A Series
object name using the compound:block.parameter syntax is specified (C1:B1.RI01). The collection method is CONNECTED, that is, via Object Manager list. The fast collection frequency is
5 seconds, slow collection frequency is 30 seconds, and maximum time between samples 3600
seconds (that is, force a sample every hour regardless of the current value). The initial state is ON,
which is used once. The RSTRTSTATE then determines the RTP state when the collector is
restarted. The high range and low ranges for trending are 100.0 and 0.0, respectively.

Figure 2-46. Configuring an RTP

Note that the input does not contain all RTP attributes. AIM*Historian supplies defaults for
attributes not specified, some of which are based on other attributes. For example, the SIZE
attribute is configured based on the TYPE attribute, and NUMELEMS defaults to 1.
Most of the RTP examples in the file use a full syntax in which a separate PUT command is
provided for each RTP attribute. The file also includes model RTP input in two other formats
in which the attributes are simply listed after the CREATE POINT command.
In the semi-condensed format, the attributes are separated by line breaks.
in the condensed format, the attributes are separated by semicolons.
Figure 2-47 shows the condensed format example, in which three RTPs are created.

70

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-47. Condensed Syntax for Configuring RTPs

You can use an input text file to change the configuration of existing RTPs. The file must start
with a line that creates the session and end with a line committing the session, both of which reference the instance name. Note that the session is 1. Between these two lines, you can specify
updates to existing RTPs or create new ones. For example, the input in Figure 2-48 modifies the
engineering units, description, and high range attributes for C1:B1:RI01 (as set up in
Figure 2-46). (The sample input in Figure 2-48 is not in the cfgcmd.inp file.) If the point does
not already exist, the input creates the point with the attributes as specified and default settings
for those not specified.

Figure 2-48. Updating RTP Configurations

71

B0193YL Rev E

2. AIM*Historian Configuration

Event Message Configuration

Sample input for message configuration is provided in two files in the examples directory:

cfgcmd.inp, which includes input for the other instance components

messages.inp, which contains only message configuration input.
Either file can be used to quickly configure message groups for standard I/A Series messages and
alarms. They also include a model for creating custom messages.
In all AIM*Historian messages, the first three keys are mandatory:

group

message

time.

Fields with embedded spaces must be enclosed with double quotes. The general format of a
message field definition is:
DEFN "<field

name> = <field number> <ODBC access> <type> <elements>"

where:
field name
field number
ODBC access
type

elements

The name of the field, that is the key.

The field number starting with 1.
Enter Y if ODBC-accessible.
Enter N if not ODBC-accessible.
The string name of the data type (CHAR, INTEGER, and so on) as
listed in Table E-8. You can specify any type listed in Table E-8,
except USER and FILE.
The number of elements of the indicated type. For strings, elements is
the maximum string length plus 1 for the null terminator. All string
sizes include a null-terminator. For example, to define a string field
with up to 80 characters plus a null-terminator, specify the number of
elements as 81.
For array types, it is the number of array elements.

I/A Series Legacy Message Groups

The cfgcmd.inp and messages.inp files contain ready-to-use configuration input for setting up
collection of all standard I/A Series event message types. These legacy message types are not
user-modifiable.
Note the extra group of quotes between MSG and GROUP; these are necessary and must be
included. All string sizes include a null-terminator, and are therefore one greater than the
definitions in the original MSG_CFG.c file. Figure 2-49 shows creation of the message group
and definition of three message types.

72

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-49. Configuring I/A Series Event Message Collection

In addition to the three message types shown in Figure 2-49, the file contains input to create the
following messages:

legacy applic
legacy unit
legacy run

legacy report
legacy form
legacy batch

legacy procedure

legacy path
legacy equipment
legacy path_excep
legacy mesgsys
73

B0193YL Rev E

2. AIM*Historian Configuration

I/A Series Alarms

The next section of the two input files is ready-to-use input that creates a group for collecting
I/A Series Alarms, with a separate message configured for each alarm type. The configuration
begins with setup of the group and definition of the first alarm (Figure 2-50).

Figure 2-50. Configuring the iaalarm Message Group

74

2. AIM*Historian Configuration

B0193YL Rev E

All the alarm types have the same format. Thus, once the first alarm type is configured, the other
30 types are quickly created using the LIKE function (Figure 2-51). Comment out any message
type that you do not want to collect.

Figure 2-51. Replicating the Message Fields

The example files also include a model for a user-defined message type to collect annotations
made to MDE type RTPs.

75

B0193YL Rev E

2. AIM*Historian Configuration

Reduction Groups
Use the reduction groups section of cfgcmd.inp (Figure 2-52) to create reduction groups,
specifying the group name, reduction interval, percent valid, reduction operations, and the RTPs
to be included in the group. The maximum number of RTPs that can be configured per reduction group is defined by the MAXRGENTS attribute for the instance.

Figure 2-52. Configuring a Reduction Group

76

2. AIM*Historian Configuration

B0193YL Rev E

Control Groups
This section of the file provides a model for creating a control group, specifying the control group
name and a description, adding the RTPs and messages to the group, and defining the triggering
RTPs for various actions (Figure 2-53). The maximum number of controlled RTP or event
message members you can define per control group is set by the MAXCGENTS attribute for the
instance.

Figure 2-53. Configuring a Control Group

Committing the Session

The final section commits the session (Figure 2-54).

Figure 2-54. Committing the Configuration

77

B0193YL Rev E

2. AIM*Historian Configuration

Permanent Delete
The FORCE_DELETE action allows you to create another RTP with the same RTP name and
then assign the other attributes of the new RTP, such as a different NAMEINCOL, COLLECTOR, and TYPE. This feature is useful when you configure an RTP incorrectly and one or more
samples are collected for that RTP, preventing you from modifying certain attributes of the RTP.
To create an input file that permanently deletes an RTP:
Use a text editor to create an .inp file.
1. Start the file with a CREATE SESSION command specifying the instance name and
using 1 for a session number (Figure 2-55).
2. Enter the FORCE_DELETE command using the following syntax:
1 DELETE POINT

<RTP Name> NAME FORCE_DELETE

3. Specify other changes to the instance configuration.

4. Enter a line to commit the session.

Figure 2-55. Deleting an RTP

Both DELETE and FORCE_DELETE actions free up an RTP for number-of-points license
checking, but do not free up the slot in the real-time configuration file for MAXPTS limit
checking.
The DELETE action on an RTP with no collected samples has the same result as a
FORCE_DELETE.

78

2. AIM*Historian Configuration

B0193YL Rev E

Using histsave
You can create configuration input text files by using histsave, which saves the configuration of an
existing AIM*Historian instance to text files. You can use these files to:

Modify the instance

Restore the instance configuration

Configure an entirely new instance.

The histsave function creates two input files that can be used as input files for histbatch: one
containing only active RTPs, the other with active and deleted RTPs (including forced deleted
RTPs).
You can use the first file to manually edit configurations. If you use this file to create a new
instance, you cannot import RTP files that you collected with the original instance, as the point
indices do not match.
The second file, which includes deleted and force-deleted points, is intended for backup of the
instance configuration. When this file is used to regenerate the original instance, all internal point
indices match and the original RTP files can be used in this instance. Run the xrebuild utility
after importing old RTP files to rebuild the cross reference files, as described in xrebuild on
page 188.
To save an instance configuration to a text file:
1. Open AIM*Historian Manger and click the Save icon (
window (Figure 2-56).

) to open the histsave

Figure 2-56. histsave Window

79

B0193YL Rev E

2. AIM*Historian Configuration

2. Select an instance name from the list box on the right and click Specify Output File
Name And Start Saving Configuration.
An Open dialog box prompts you to specify a name for the file. The file type field displays the Batch Configuration input file (extension inp).
3. Use this dialog box to specify the name and location of the first file (the one with
active RTPs only), and click Open.
histsave names the second file by appending _del to the name of the first file.
Any files with the same name in the directory are overwritten.
As the configuration is being saved, the Progress Status area in the histsave dialog box
shows:
Instance name
Specified .inp file

Current line number in the file being written

AIM*Historian component being written.
When the task is complete, the Component Name field changes to Done, and an
information dialog box displays the full path names of each .inp file.
4. Click OK to close the information dialog box.
The files can now be modified with a text editor, or used without change as the input file for
histbatch, the Batch Configurator.
! CAUTION
Do not change the order of the RTPs in the second file (*_del.inp) if you are
keeping the file as a configuration backup.

NOTE

You may notice the line HASVALUE=1 being appended to the configuration of
each RTP in the second file (*_del.inp). This attribute is intended only for use in
these automatically generated files. Do not use this attribute in any other way
because such use may compromise features that safeguard configuration validity.

80

2. AIM*Historian Configuration

B0193YL Rev E

Instance Configuration with histbatch

The Batch Configuration GUI configures an AIM*Historian instance by processing a
configuration input text file (for example, <Instance Name>.inp).
NOTE

To facilitate re-use of an .inp file for making changes to a configuration, histbatch

avoids recreating components that already exist in the instance.
To configure an AIM*Historian instance based on an input file:
1. Change to the AIM*AT program directory and enter the Batch command.
cd /opt/aim/bin
histbatch

or
Open the AIM*Historian Manager and choose Tools > Batch.
The selection opens the histbatch window (Figure 2-57).

Figure 2-57. histbatch Window

2. Click Get File Name And Start Batch Configuration.

The Batch Configurator raises a Windows Open File dialog box for selecting the
input file. The display defaults to the AIM*AT myfiles directory and is filtered to
show only files with the extension inp.

81

B0193YL Rev E

2. AIM*Historian Configuration

3. Use the dialog box to browse for and select the file.
When you click Open, the Batch Configurator creates the configuration file based on
the input file, and displays the resulting instance name, source file, percent complete,
and number of errors in the Progress Status area in the lower half of the dialog box
(Figure 2-58).
If errors are reported in the Progress Status area, you can troubleshoot by reviewing
the error messages using the histbatch.lst button.

Figure 2-58. Completed Configuration Session

4. Select another input file for configuration or click Exit to return to the
AIM*Historian Manager window.
The Batch Configurator is also available from the Tools menu in the AIM*Historian Manager
window, along with the Save Configuration dialog box which copies the configuration of an
AIM*Historian instance to a text file in the format understood by the Batch Configurator. See
Configuration Tools on page 100.

82

2. AIM*Historian Configuration

B0193YL Rev E

Instance Configuration with histcbatch

AIM*Historian also includes a command line program that configures instances by processing a
configuration input text file (for example, <Instance Name>.inp).
NOTE

To facilitate re-use of an .inp file for making changes to a configuration, histcbatch

avoids recreating components that already exist in the instance.
To use the command line configuration program:
1. Switch to the AIM*Historian program directory:
/opt/aim/bin on Solaris servers
on I/A Series AW70s
c:\Program Files\aim\bin on other Windows NT servers
2. Enter the configuration command using the following format:
d:\opt\aim\bin

histcbatch

<Input File> | STDIN [<Output File> |STDOUT]

where:
Input File
Output File

Name of the configuration input file, for example, hist01.inp.

Enter STDIN for the program to read standard input.
Name of the output file for error reporting.
Enter STDOUT for the program to write the results to
standard output.
If no output file is specified, no errors are reported.

The histcbatch program reads the configuration input text file one line at a time and parses each
line into one or more fh_Cfg() function calls.
The Input File contains the histcbatch command lines, comment lines, and blank lines. The
Output File is used by the histcbatch program to report errors.

83

B0193YL Rev E

2. AIM*Historian Configuration

Modifying Maximum Value Attributes

Once you have committed the configuration for an AIM*Historian instance, you cannot modify
the maximum values unless you first stop all programs which access the AIM*Historian
configuration files.
The instance attributes that set maximum values are:
MAXPTS

Maximum number of RTPs

MSGDEFS

Maximum number of message definitions

MSGFILE

Maximum size of message configuration file

MAXCGENTS

Maximum number of RTPs and messages in a control group

MAXRGENTS

Maximum number of RTPs in a reduction group

TRACKKEY
Maximum number of track keys
You should carefully consider the values for these attributes prior to configuring the instance.
See Instance Attribute Descriptions on page 228.
NOTE

You can only increase the maximum values.

To modify the maximum value attributes after the instance configuration is committed:
1. Stop all AIM*Historian programs, AIM*API programs, and applications that make
AIM*API calls.
2. If you have remote collectors, stop the collector programs as follows:
a. At the instance machine, run AIM*Historian Manager, select each collector, and
turn it off using the Collector Page (see Collector Page on page 96).
b. At each remote I/A Series collector machine, stop the event message collector and
the legacy servers by entering:
/opt/aim/bin/start_server STOP

c. At each remote collector machine, kill histsend.

d. At each remote collector machine, delete the instance directory on the remote collector host.
3. On the instance host, create a configuration input text file to modify the attributes of
interest, using the sample file maxima.inp as a model.
The file maxima.inp (Figure 2-59) is located in the examples directory (see Table 2-4,
Default AIM*Historian Installation Directories on page 64).

84

2. AIM*Historian Configuration

B0193YL Rev E

Figure 2-59. MAXIMA Input File

Note that the example file creates a session for the named instance (hist01), changes
the five instance attributes with the PUT command, and then commits the session.
4. Run histbatch and specify the new input file name.
5. Restart all affected programs.
NOTE

You may also have to increase the maxobj attribute in the aimapi.cfg file.

85

B0193YL Rev E

86

2. AIM*Historian Configuration

3. AIM*Historian Operation
This chapter describes how to use the AIM*Historian Manager Window to start and stop
operation of an instance, enter values for RTPs with an MDE collection method, and access
other services available from the AIM*Historian Manager Window.
The AIM*Historian Manager is a graphical user interface for starting and monitoring data
collection with one or more AIM*Historian instances.
The interface can be used to manage local instances or to remotely operate instances on other
servers on the network. AIM*Historian Manager runs on both Solaris and Windows platforms.
The examples in this chapter are taken from the Windows version. However, once the window is
opened, the Solaris version of the interface is virtually identical to the Windows version.
With the AIM*Historian Manager Window (and the programs launched by AIM*Historian
Manager), you can perform the following tasks:

Start and stop an instance (histmain) or a collector (iacol or iogatecol)

View historized data (histspy)

Configure an AIM*Historian instance (histcfg or histbatch)

Back up and restore databases (histarc)

Save configurations (histsave)

Enter values in an RTP database (histmde)
Check the status of servers, instances, and collectors including reviewing log files
Configure automatic archiving (arccfg)

Configure and display data displays (histddef, histdisp)

Determine optimal parameters for disk usage (dbwizard).

AIM*Historian Manager Window

To open AIM*Historian Manager from an I/A Series workstation:

Choose Config > AIM*Historian from FoxView or the Display Manager.

To open AIM*Historian Manager from an AW51 or other Solaris platform:
Open a command tool and enter the histmgr command from the AIM*Historian
program directory:
/opt/aim/bin/histmgr

To open AIM*Historian Manager on a Windows system:

Click the application icon in the AIM*AT folder or choose:
Start > Programs > AimAT > Historian Manager

87

B0193YL Rev E

3. AIM*Historian Operation

The AIM*Historian Window (Figure 3-1) consists of the following components:

Application menu bar

Tool bar for frequently accessed functions

AIM*Historian Components Tree showing the servers, instances and collectors that
can be accessed by the AIM*Historian Manager

Five tabbed pages to monitor and control components selected in the tree

Status bar in the lower left corner of the window.

After a description of the window components, this chapter provides step-by-step instructions for
using the programs available from the Tools menu.
Menu Bar

Tool Bar

Tabs

Server Tab View

AIM*Historian
Components
Tree

Status Bar

Figure 3-1. AIM*Historian Manager Window

88

3. AIM*Historian Operation

B0193YL Rev E

Application Menu Bar and Tool Bar

The application menu bar provides access to programs for configuring and managing
AIM*Historian databases, and options for arranging the application window. Many of the menu
selections can be accessed using keyboard shortcuts, such as Alt+S to open the AIM*Historian Spy
program. Functions available from the Tools and Help menus can also be accessed by clicking
icons in the Tool bar, which is optionally displayed immediately below the application menu bar.
Table 3-1 summarizes the menu selections and shows the tool bar icons and keyboard shortcuts
for each selection.
Table 3-1. AIM*Historian Manager Functions

Menu
File

Submenu
Refresh View (F5)

Exit
Edit

Copy (Ctrl+C)

Select All (Ctrl+A)

View

Tool Bar
Status Bar

Tools

AutoArchiver
Configurator (Alt+U)
Batch (Alt+B)

Configurator (Alt+N)

DBWizard

Tool Bar Icon

Description
Reconnects to the AIM*API servers and
rebuilds the AIM*Historian Components
Tree (Figure 3-2).
Closes AIM*Historian Manager. Operation
of the instances is not affected.
Copies the messages selected in the Log page
listing so they can be pasted as ASCII text
into a document or spreadsheet for analysis
or record-keeping. See Log File Page on
page 99.
Selects all messages in the Log page listing.
Active when at least one item is selected.
Toggles the display of the tool bar on and off.
Toggles the status display in the lower left
corner component on and off. The status
bar shows both operating messages and a
description of the selected menu pick, icon,
or command button.
Raises the AIM*Historian AutoArchiver so
you can schedule the system to move database files to an archival directory.
Initiates the AIM*Historian Batch
Configuration program, as described in
Instance Configuration with histbatch on
page 81.
Opens the AIM*Historian Configurator.
See Chapter 2 AIM*Historian Configuration.
Starts the DBWizard, which helps you
determine and implement new RTP Read
Delta parameters for optimal disk usage.

89

B0193YL Rev E

3. AIM*Historian Operation

Table 3-1. AIM*Historian Manager Functions (Continued)

Menu

Submenu
Data Display

Manual Data Entry

(Alt+M)

Manual Archiver
(Alt+A)

Save (Alt+V)

Spy (Alt+S)

AIM*API
Server Status (F4)

Help

Help Topics

Help

About histmgr

90

Tool Bar Icon

Description
Opens the Data Definition window for the
Historian Data Display, which is used to
select up to eight RTPs to be viewed in a tabular report or in an I/A Series Trend graphic.
See Displaying Process History on
page 100 for instructions on using the
AIM*Historian Archiver.
Opens the Manual Data Entry (MDE)
Window to add RTP values to the databases.
See Manual Data Entry on page 112 for a
description of the MDE Window.
Opens the AIM*Historian Archiver Window
so you can copy, back up and restore
AIM*Historian databases.
See On-Demand Archiving on page 143
for instructions on using the AIM*Historian
Archiver.
Saves the current configuration for the
selected AIM*Historian instance, as
described in Instance Configuration with
histbatch on page 81.
Starts the AIM*Historian Spy, which displays configuration and database files for the
selected AIM*Historian instance. AIM*Historian Spy is described in AIM*Historian
Spy on page 116.
Opens a dialog box to view status of a
selected server and recent error messages, display user access privileges, and connect
AIM*Historian Manager with the selected
server. The dialog box is described in Server
Status on page 119.
Displays an index of application-related help
topics.
Displays program version and copyright
information.

3. AIM*Historian Operation

B0193YL Rev E

AIM*Historian Components Tree

The AIM*Historian Components Tree on the left side of the AIM*Historian Manager
window displays the servers, instances, and data collectors accessible via the window (Figure 3-2).
Server

Instance

Collector
Right-click on any
component for its
short-cut menu.

Figure 3-2. AIM*Historian Components Tree

The tree in Figure 3-2 shows five servers, each represented by a computer icon and the server
name. The presence of the slider bar on the right side of the pane indicates that additional servers
can be scrolled into view. The monitor in the server icon is blue when the AIM*Historian Manager is connected to the server (TEST964d in Figure 3-2, for example). The monitor is gray when
there is no connection to the server (P7AW05, for example).
When a plus sign appears to the left of the server, you can expand the display to view the instances
on that server. Each instance is identified by dual-arrow icon and the instance name. The instance
is on when the arrows are maroon (hist01 in Figure 3-2, for example); the instance is off when the
arrows are gray (gatexx, for example).
When a plus sign appears to the left of the instance icon, you can expand the display to view the
collectors configured for the instance. Each collector is identified by a smaller computer icon and
the collector name. When the monitor in the icon is green, the collector is operating (rtcol1 in
Figure 3-2, for example); when the collector is off, the monitor is gray (gatexx for example).
Click the plus sign to expand the display of an item.
Click the minus sign to collapse the display.
Click on any item to select a component.
Press the F5 key to refresh the display.
AIM*Historian Manager empties the pane, queries the servers on the network, and
constructs a new AIM*Historian Components Tree.

91

B0193YL Rev E

3. AIM*Historian Operation

Tree Menu
The Components Tree has its own set of pop-up menus, which are accessed by right-clicking on a
component. The menu selections depend on the component selected and its status (Table 3-2).
Table 3-2. Components Tree Pop-Up Menus

Component
Server

Menu Item

Description

AIM*API Server Status

Opens the Server Status dialog box, which you can

use to reconnect to the server (see Server Status
on page 119).
Displays the Server Page for the selected server, as
described in Server Page on page 94.
Starts selected instance. Available when the server
is connected and the instance is off.
Stops selected instance. Available when the server
is connected and the instance is on.
Opens the Server Status dialog box, which you can
use to reconnect to the server (see Server Status
on page 119).
Displays the Instance Page for the selected
instance, as described in Instance Page on
page 94.
Starts the AIM*Historian Configurator (refer to
Chapter 2 AIM*Historian Configuration starting on page 17).
Starts selected collector. Available when the server
is connected and the collector is off.
Stops selected collector. Available when the server
is connected and the collector is on.
Opens the Server Status dialog box, which you can
use to reconnect the server (see Server Status on
page 119).
Displays the Collector Page for the selected collector, as described in Collector Page on page 96.

Properties
Instance

Start Instance
Stop Instance
AIM*API Server Status

Properties

Configurator

Collector

Start Collector
Stop Collector
AIM*API Server Status

Properties

92

3. AIM*Historian Operation

B0193YL Rev E

AIM*Historian Manager Pages

The five tabbed pages that appear to the right of the AIM*Historian Components tree provide
the principal means of monitoring operation of the AIM*Historian instances.

On/Off Controls
The Instance page and the Collector page include On and Off buttons and traffic light icons that
are used to stop and start the selected instance or collector (Figure 3-3). The instance or collector
is not operating when the red light is on and the Off button label is bold. The instance or collector is operating when the green light is on and the On button label is bold. The amber light and
status message displayed below the controls are used to indicate transitions between the two
states.

Instance/
collector
is off.

Instance/
collector
is starting.

Instance/
collector
is operating.

Instance/
collector is
shutting down.

Instance/
collector
is off.

Figure 3-3. On/Off Controls on the Instance and Collector Pages

To start an instance or collector:

Click the On button.

The amber light is on and the word Starting is displayed below the controls. The red
light remains on when the instance or collector is not fully operational.

When the instance or collector is fully operational, the red and amber lights are off,
and the green light is on. The On button label is bold and the Off button label uses a
plain font.
To stop an instance or collector:
Click the Off button.
The green light is off and the amber light is on. The word Stopping is displayed below
the controls.
When the instance or collector is fully shut down, the amber light is off and the red
light is on. The Off button label is bold and the On button label uses a plain font.

93

B0193YL Rev E

3. AIM*Historian Operation

Server Page
The Server page displays information about the selected server, its operating status and software
versions (Figure 3-4). A server is selected when any of the instances or associated collectors is
highlighted.

Figure 3-4. AIM*Historian Manager Server Page

Instance Page
The Instance page provides command buttons for starting and stopping operation of the selected
AIM*Historian instance (Figure 3-5). An instance is selected when it, or one of its collectors, is
highlighted in the AIM*Historian Components Tree.

94

3. AIM*Historian Operation

B0193YL Rev E

Figure 3-5. AIM*Historian Manager Instance Page

The principal AIM*Historian controls are located in the Instance group, which identifies the
instance name and platform.
1. Click On to start the AIM*Historian instance.
The controls depict the transition to the on state as described in On/Off Controls
on page 93. AIM*Historian also starts the collectors for the instance, if they are configured with the FOLLOWINSTON attribute enabled.
2. Check Start on Reboot if you want the instance to begin operation when its host
server is booted.
3. Click Off to shut down the selected AIM*Historian Instance.
The controls depict the transition to the off state as described in On/Off Controls
on page 93. AIM*Historian also stops the collectors for the instance, if they are configured with the FOLLOWINSTOF attribute enabled.
The Session group provides information about the current configuration session if
there is one. The Session states can be:
Not Active
Active
Committed
Saved
Dirty Saved
In Process.
See AIM*Historian Configurator Window on page 18 for a discussion of
configuration sessions and committing configurations.

95

B0193YL Rev E

3. AIM*Historian Operation

4. Click Clean Up to reset the parameters in the instance configuration files to their start
states.
Clean Up deletes temporary configuration files (*.cfg.RW), discarding the changes
made during the configuration session. Clean Up resets the configuration file state to
Inactive.
NOTE

If .cfg.RW files remain after clicking Clean Up, run clearcfg utility (see clearcfg on
page 168).
The Real-Time Points group shows the number of RTPs configured for the specific instance
(including inactive, or deleted, RTPs) and the total number of points across instances
authorized for the server. The maximum number is set by the Authorization Code entered during
AIM*API configuration. The server selected in Figure 3-5 has room for 127 RTP database files
(r<n>.fdb) for the selected AIM*Historian instance. The number of files is based on the free
storage space available to all instances on the server and the maximum file size configured for the
instance.
Refer to the AIM*AT Installation Guide (B0193YM) for additional information on authorizing
the AIM*API and AIM*Historian servers. Additional points can be configured for the instance
using AIM*Historian Configurator (see Chapter 2 AIM*Historian Configuration).

Collector Page
The Collector page shows the name, host (as configured in the Hostname attribute), type, and
platform of the selected collector, and allows you to stop and start real-time collector operation
(Figure 3-6).
For a local collector, the Host field displays the server name (Name and Path Alias fields on the
Server page).
The page displays the operating status of message collection on the collector station
(see Adding a Collector on page 59).
1. Click On to start the selected collector.
The controls depict the transition to the on state as described in On/Off Controls
on page 93.
2. Click Off to shut down the selected collector.
The controls depict the transition to the off state as described in On/Off Controls
on page 93.

96

3. AIM*Historian Operation

B0193YL Rev E

Figure 3-6. AIM*Historian Manager Collector Page

The lower group on the page shows the current database files for RTPs and event messages on the
instance host.

Communications Page
The Communications page reports the status of communications between the AIM*Historian
server and the collector (Figure 3-7).

Figure 3-7. AIM*Historian Manager Communications Page

97

B0193YL Rev E

3. AIM*Historian Operation

There are no input controls in the Communications page.

The collector Name and Type (I/A Realtime Collector, I/O Gate Collector, or I/A Series Message
Collector) are displayed at the top of the Collector group. For remote collectors, the Collector
and Status groups also list Port Number, Connection State, Burst Interval, Last Message, and
Rate.
The Port Number is the IP port number used to make the TCP/IP connection with the remote
collectors.
Connection State reports the current status of the communications with the remote collector and
is usually Waiting for Updates. Other possible states are:
OFF

DISCONNECTED (burst mode)

DISCONNECTED (database full)

Address resolution FAILED

Connect FAILED
Resolving IP address
Connecting

RTP Update
Message Update

Sending .cfg files

Sending demand writes.
If the collector is operating in Burst Mode, it connects with the instance at defined intervals to
send collected data. If the Burst Interval is 0, the collector is continuously connected and sends
RTP values and messages as it collects the data.
The RTP Updates and Message Updates fields show counts of RTP samples and event messages
written to the AIM*Historian database collector.
Message collectors do not need to be explicitly configured in AIM*Historian, except when you
want to collect messages only with a remote collector machine. Message updates for the collector
with the same name as the AIM*Historian instance show the current count of event messages
collected by the I/A Series message collector program (ipchisti) and by other applications which
write event messages running on the same system as the instance.
The collector showing the count of event messages from a remote collector is the message collector, if configured. Otherwise, it is the first configured remote real-time collector running in the
remote collector machine.

98

3. AIM*Historian Operation

B0193YL Rev E

Log File Page

The Log File page (Figure 3-8) enables you to view a log file for the status of an AIM*Historian
instance to troubleshoot problems that can occur during data collection. The log file displays
error codes, the date and time they occurred, the process identifiers, and the error message.

Figure 3-8. AIM*Historian Manager Log File Page

The log messages are displayed in reverse chronological order with the most recent messages at the
top of the text box. The page is not dynamically updated.
1. Use the scroll bars to view additional text of a message or earlier messages in the file.
2. Click Refresh to display the latest messages.
3. Click Clear to delete the messages from the log file.
You can copy all or some of the messages to another application for analysis or storage using
selections from the View menu. For example, you can copy to a text editor such as vi on a Solaris
workstation or Wordpad on a Windows NT system. Or, they can be pasted into an e-mail
message to a service representative.
To copy message records to another application:
1. Click on one of the message records on the Log File page.
With the record selected, the Copy and Select All choices in the Edit are now active.
2. Use the Windows or Solaris native functions for multiple selection, or choose
Edit > Select All to choose all message records.
3. Choose Edit > Copy.
4. Change to the other application and use the tools in that application to paste the
records.

99

B0193YL Rev E

3. AIM*Historian Operation

Configuration Tools
AIM*Historian Manager provides access to two configuration programs:

The Batch Configurator configures an AIM*Historian instance by processing

configuration input text files that have been created with a text editor or saved for an
existing instance.
To access the Batch Configurator, choose Tools > Batch or click the
Batch icon (
).
Save Configuration copies the configuration of an AIM*Historian instance
to a text file in the format understood by the Batch Configurator.
To access the Save Configuration Window, choose Tools > Save or click the
Save icon (
).
Both programs are described in Configuration Using Input Text Files on page 64.

Displaying Process History

The AIM*Historian Data Display allows process operators and others to review historical data
and ascertain data trends quickly and easily. The program enables operators to select RTPs from
multiple instances and servers and display recently collected values in either a tabular report or
graph using a familiar I/A Series Trend format. The AIM*Historian Data Display is a client program that can be installed on any Solaris or Windows platform connected to the target
AIM*Historian instances. The Trend display is not available if the program is running on a
non-I/A Series workstation.

An Overview of the AIM*Historian Data Display

The AIM*Historian Data Display is an easy-to-use tool that enables you to retrieve sampled Real
Time Point (RTP) data and display the historical data in a tabular report or trend display. The
tabular report allows you to verify and review collected RTP data in an easy-to-read format, while
the Trend display enables you to recognize trends in the sample data quickly and accurately.
The AIM*Historian Data Display enables you to:
Select the AIM*Historian instance and server from which to retrieve RTP data
Specify from which RTPs to collect the data
Specify the report start time and duration
Select either linear or average data
Generate a report of collected RTP data
Print report data
Save AIM*Historian Data Display configurations for future use

Display the RTP data in a standard I/A Series Trend display

Save report data to an ASCII text file.

100

3. AIM*Historian Operation

B0193YL Rev E

Starting the AIM*Historian Data Display

You can start the AIM*Historian Data Display tool from:

I/A Series Display Manager or FoxView

AIM*Historian Manager
Windows Start button

Solaris Command Tool window.

To start the AIM*Historian Data Display from Display Manager or FoxView:

Choose Config > Historian > Data Display.
To start the AIM*Historian Data Display from the AIM*Historian Manager:
1. Open AIM*Historian Manager, if it is not already available.
On a Windows NT system:

Choose Start > Programs > AimAT > Historian Manager.

On a Solaris platform:

Open a command tool and enter: /opt/aim/bin/histmgr.

2. Click the AIM*Historian Data Display icon (
), the ninth button from the left on
the AIM*Historian Manager tool bar, or choose Tools > Data Display.
Alternatively, you can start the AIM*Historian Data Display directly from the workstation
operating system:
On a Windows NT system:
Choose Start > Programs > AimAT > Historian Data Display.
On a Solaris platform:
Open a Command Tool window and enter: /opt/aim/bin/histddef.
AIM*Historian opens the AIM*Historian Data Display histddef window (RTP Definition
window).

101

B0193YL Rev E

3. AIM*Historian Operation

Defining the Sampled RTP Data to Display

The RTP Definition window shown in Figure 3-9 allows you to specify which RTPs to retrieve
from the sample database and define how the data points should be displayed in the Data Report
window or standard I/A Series Trend display.

Figure 3-9. RTP Definition Window

Use the RTP Definition window to:

Save, open, and delete AIM*Historian Data Display configurations
Select the AIM*Historian instance and server from which to retrieve RTP data
Specify the start time, duration, and data type
Assign RTPs to specific columns within the tabular data report
Open the Data Report window or standard I/A Series Trend display
Exit the AIM*Historian Data Display.

102

3. AIM*Historian Operation

B0193YL Rev E

Saving, Opening, and Deleting Configurations

AIM*Historian Data Display stores its configuration settings in an ASCII text file. By default, its
configuration files are stored in a separate subdirectory in the /opt/aim/myfiles/hdd directory.
When the AIM*Historian Data Display runs, it loads its default configuration file (default.cfg).
The Select Configuration group in the upper left corner of the window displays the currently
loaded configuration and three buttons:

Open

Save enables

provides a dialog box for selecting another configuration file.

you to save changes to the configuration or create a new configuration

by specifying a new file name in the Save dialog box.
Delete allows you to delete the file displayed in Current Config.

Selecting the AIM*Historian Instance and Server

To select the AIM*Historian server and instance from which to retrieve RTP data:
1. Select the desired server from the Server pull-down list.
The Historian drop-down list is updated to include only the AIM*Historian instances
on the selected server.
2. Select the instance from the Historian pull-down list.
The RTPs configured for the instance are displayed in the Select Desired Tag list box.
3. Optionally, filter the list of RTP sample names by entering characters in the RTP
Filter field.
Filtering the RTP list simplifies the selection of RTP samples by limiting the
displayed list to only those RTP Names that contain the string entered in the RPT
Filter text box. For example, the list in Figure 3-9 has been filtered to include only
RTP Names that contain TEST1.
You can configure a report using points from different instances and different servers.
For example, the RTPs assigned in Figure 3-9 are from two different instances: arctst
and hist03. Assign the points from the first instance, then use the Server and
Historian pull-down menus to display and assign the other RTPs.

Specifying the Time Interval and Data Type for the RTPs
To specify the time interval and data type for RTPs in the report:
1. Click Current Date/Time to display the current date and time.
The current date is displayed in the Start Date field and the current time is displayed
in the Start Hour and Start Minutes field.
2. Enter the starting date from which RTP data will be included in the report in the
Start Date field.
You may enter any valid date directly in the field, or you may select a date from the
drop-down list. The drop-down list contains date strings corresponding to the last
15 days from the current date.
3. Enter the starting hour from which RTP data will be included in the report in the
Start Hour field.
You may enter any hour in 24-hour format (00 to 23) directly in the field, or you may
select the starting hour from the drop-down list.
103

B0193YL Rev E

3. AIM*Historian Operation

4. Enter the starting minute from which RTP data will be included in the report in the
Start Minute field.
You may enter any minute (00 to 59) directly in the field, or you may select the starting minute from the drop-down list.
5. Enter the span of time that the report will cover in the Time Span field.
Enter a time span directly in the field, or select the time span from the drop-down list.
The entered time span must be in the format nn u, where nn represents an integer corresponding to the desired value (0 through 10000) and u is one of the following unit
designators: s = seconds, m = minutes, h = hour, and d = day. You may enter either
the entire unit or its single letter designator.
6. Enter the time between each row of data in the report by specifying a value in the
Time Interval field.
Enter a time interval directly in the field, or select the time interval from the
drop-down list.
The entered time interval must be in the format nn u, where nn represents an integer
corresponding to the desired value (0 through 10000) and u is one of the following
unit designators: s = seconds, m = minutes, h = hour, and d = day. You may enter
either the entire unit or its single letter designator.
7. Specify the data type for the RTP data in the report.
Select either Linear or Average from the Data Type drop-down list.
The selected data type represents the data reduction algorithm used on the RTP data
in the report.

Assigning RTPs to Report Columns

The data report can display up to eight columns of RTP data. You are not required to assign an
RTP to all columns. The report displays data only in columns which have an RTP assigned; other
columns are left blank and labeled Not Used.
To assign an RTP to a report column:
1. Select an RTP tag from the Select Desired Tag list box.
The selected RTPs name appears in the Selected Tag field, and its associated
description appears in the Description field.
2. Assign the selected RTP to one of the eight report columns by clicking the columns
corresponding button (TAG 1 to TAG 8).
The RTP assigned to the column and the Historian instance from which it was
acquired are listed in the columns Assigned RTPs and Historian fields.
NOTE

You can remove an RTP assignment by clicking the columns corresponding Clear
button (1 to 8).

104

3. AIM*Historian Operation

B0193YL Rev E

Viewing the Data Report or Trend Display

You are now ready to display the historical RTP data in a Data Report window or standard
I/A Series Trend display.
Click View Data to display the specified RTP data in a Data Report window.
Use of the Data Report window is described in Viewing the Data Report in the next
section.

Click View Trend to display the specified RTP data in a standard I/A Series Trend
display within the default Display Manager or FoxView window on your I/A Series
workstation.
Use of the data trend display is described in Viewing the Data Trend Display on
page 111.

Exiting the AIM*Historian Data Display

Click Quit to close the RTP Definition window and exit AIM*Historian Data Display.

Viewing the Data Report

Clicking View Data from the RTP Definition window opens the AIM*Historian Data Display
histdisp window (Data Report window) with the specified RTP data displayed in a 9-column
tabular format (Figure 3-10).

Figure 3-10. Data Report Window

105

B0193YL Rev E

3. AIM*Historian Operation

The Data Report Window Format

The Data Report window is split into two regions, as shown in Figure 3-11 (which is a portion of
the window in Figure 3-10). The upper region lists the report statistics and the individual RTP
column headers. The column headers provide the following six rows of RTP information:

Compound

Block

Parameter
Engineering Units

Server

Instance.

By default, only the first five rows of header information are visible. Use the vertical scroll bar on
the right to view the last row.

Report
Statistics
and Column
Headers

Click the header

box to sort
report on the
column.
Report
Data

Figure 3-11. AIM*Historian Data Report Components

The lower region provides the report data. There are nine columns displayed. The first lists the
date and time of the data set. The remaining eight columns list data for the individual RTPs you
have selected for inclusion in the report.
Each column in the lower region contains a header box. Select a columns header box to sort the
data in the report based on the values listed in the column. By default, the data report is sorted in
time stamp order.
You can move, resize, minimize, and close the Data Report window using standard Windows
controls.

106

3. AIM*Historian Operation

B0193YL Rev E

Using the Data Report Menu Bar

Table 3-3 summarizes functions available from the Data Report window menu bar.
Table 3-3. Data Report Window Menu Bar

Menu

Submenu

Print

Print
Print Setup
Print Preview

Save

Save As

Quit
Help

Description
Prints the displayed data report.
Defines the printers available to print the data report.
Provides an on-screen preview of the printed report, from
which you can access Printer Setup and send the report to
the printer.
Saves the displayed data report to an ASCII text file using
any valid file name you specify.
Closes the Data Report window.
Displays an informational dialog listing the AIM*Historian
Data Display version and copyright information.

Printing Reports
When the AIM*Historian Data Display is running on a Windows platform, the Print menu
provides access to standard Windows Print and Print Setup menus, enabling you to select a
printer, printer properties, number of copies, and other print options as you would for any other
Windows application.
When the AIM*Historian Data Display is running on a Solaris platform, the Print menu provides
access to a set of dialog boxes specific to this application.
To print a report from a Solaris workstation:
1. Choose Print > Print.
The AIM*Historian Data Display opens a dialog box for selecting a printer
(Figure 3-12).

Figure 3-12. Print Dialog Box for Solaris Systems

107

B0193YL Rev E

3. AIM*Historian Operation

The dialog box includes a list of printers available to the workstation and configured
for the AIM*Historian Data Display.
2. Select one of the printers in the list box and click Print.
If the printer you want is not listed, click Cancel and use the Printer Setup menu to
configure the printer for the AIM*Historian Data Display.

Printer Setup
To add the list of printers:
1. Choose Print > Printer Setup.
The AIM*Historian Data Display opens the Printer Setup dialog box (Figure 3-13).

Figure 3-13. Printer Setup Dialog Box for Solaris Systems

The dialog box lists the currently configured printers, giving the device name and
description of each. The description is specific to the application.

108

3. AIM*Historian Operation

B0193YL Rev E

2. Click Add to open the Add Printer dialog box (Figure 3-14).

Figure 3-14. Add Printer Dialog Box for Solaris Systems

3. Use the pull-down menu to select a printer from a list of devices available to the
workstation.
4. Use the optional Enter Printer Description text box to identify the printer.
5. Click OK to close the Add Printer dialog box (Figure 3-14).
The AIM*Historian Data Display adds the printer device name and description to the
list of configured printers in the Printer Setup dialog box (Figure 3-13).
6. Select a printer in the Printer Setup dialog box and click OK.
To change a printer description:
1. Choose Print > Printer Setup.
The AIM*Historian Data Display opens the Printer Setup dialog box (Figure 3-13).
2. Select the printer you want to change and click Modify.
The AIM*Historian Data Display opens the Modify Printer dialog box (Figure 3-15).

Figure 3-15. Modify Printer Dialog Box on Solaris Systems

109

B0193YL Rev E

3. AIM*Historian Operation

3. Enter the new description on the text field, and click OK.
AIM*Historian Data Display closes the dialog box and updates the list of configured
printers.
4. Click OK to complete the change and close the Printer Setup dialog box.
To remove a printer from the printer selection list:
1. Choose Print > Printer Setup.
The AIM*Historian Data Display opens the Printer Setup dialog box (Figure 3-13).
2. Select the printer you want to remove and click Delete.
The AIM*Historian Data Display opens the Delete Printer dialog box (Figure 3-16).

Figure 3-16. Delete Printer Dialog Box on Solaris Systems

3. Click OK.
AIM*Historian Data Display closes the dialog box and updates the list of configured
printers.
4. Click OK to complete the change and close the Printer Setup dialog box.

110

3. AIM*Historian Operation

B0193YL Rev E

Viewing the Data Trend Display

Clicking View Trend from the Data Definition window displays the specified RTP data in a standard I/A Series Trend display within Display Manager or FoxView. Figure 3-17 shows a sample
Data Trend display.

Figure 3-17. The Data Trend Display

The Data Trend display plots traces of up to eight different RTP variables, four in the upper half
of the display and four in the lower half of the display.
By default, there are four trend durations: 1 hour, 4 hours, 8 hours, and 24 hours.
AIM*Historian Data Display displays the RTP data using the trend duration that is equal to or
greater than the time span configured for the data.

111

B0193YL Rev E

3. AIM*Historian Operation

Manual Data Entry

The AIM*Historian Manual Data Entry window enables you to view and enter data points into
the AIM*Historian RTP database as if the points had been collected in real-time (Figure 3-18).
The points must first be configured with the collection method MDE in the RTP Configuration
file.
NOTE

Manually entered values are only entered into the AIM*Historian databases. They
have no effect on the control system databases.

Figure 3-18. Manual Data Entry Window

112

3. AIM*Historian Operation

B0193YL Rev E

To open the MDE Window from the AIM*Historian Manager:

1. Choose Tools > Manual Data Entry or click the MDE icon in the tool bar.
The top of the MDE Window includes a menu bar, an MDE tool bar, and pull-down
menus for selecting the server and AIM*Historian instance. The tool bar icons are
identified in Figure 3-19.
Printer (not active)
View Annotations

About MDE
Online Help

Filter Data
Figure 3-19. MDE Window Tool Bar

2. Use the pull-down menus to select the server and instance if the target instance is not
already selected.
There are three groups on the left side of the window:

Value group

Annotations group

Time Stamp group

Provides data fields for modifying an existing value or

entering a new value. In addition to the numeric
value, you can enter information about the status and
quality of the point.
Allows you to add comments for RTPs with manually
entered values.
Provides tools for setting the time and date of the
value or annotation.

The list box on the right displays the MDE type points configured in the instance.
3. Select the RTP by clicking on its name in the list box.
The manually entered values already in the database are displayed in the area at the
bottom of the window.
NOTE

When you view the value for an MDE point, you see only the first value in an array.
To view all of the values, click the time stamp for the value.

113

B0193YL Rev E

3. AIM*Historian Operation

To enter a new value:

1. Choose a point from the list of MDE points in the manual data entry window to view
the values for the point.
The values are retrieved and displayed in the bottom half of the Main Window.
2. Enter the value.
If the RTP is a non-array value type:
a. Enter the value in the field above the Change Value button.
b. Click Change Value or press the Enter key.
For each element in an array type RTP:
a. Click the Entry Number in the Array Element list.
b. Enter the value in the field above the Change Value button.
c. Click Change Value or press the Enter key.
3. Enter a new Status if the default status (3) is not correct.
4. Enter a numeric value in Quality if this quality rating is useful.
5. Enter the time stamp information in the Time Stamp group.
Time stamp information that can be entered includes: a month, day, year, hour,
minute, second and millisecond prior to the current system time. You cannot enter a
future time.
6. Click Clear when you want to start with empty value, status, and quality fields when
adding a point.
7. Click Insert MDE.
If a value already exists for the RTP with the same time stamp, AIM*Historian
prompts you to confirm that it is to write the new value.
The value and time stamp information for the MDE point is displayed on the
bottom half of the screen.
You can also filter data by defining start and end times:
1. Click the Filter Data icon in the MDE Window tool bar.
The MDE program opens a filter dialog box.
2. Enter the start and end time for filtering your data, and click OK.
The MDE points displayed for the selected instance are defined by the filtered time
span just entered.

114

3. AIM*Historian Operation

B0193YL Rev E

Annotating MDE Values

You can use annotations to document the time of manual entry for a value for a MDE point.
To enter annotations:
1. Click within the Annotations group of the MDE Window.
2. Enter the annotation text and one or more keys.
The note text can be up to 200 characters in length. The keys are optional text
strings which can be used as search keys.
3. Enter a date and time in the Time Stamp group if you want to indicate an
Event Time.
The Event Time is user-defined and can be the time stamp of a process event, a
change in factory procedure, or any other factor related to the annotations.
4. Click Insert Annotation.
5. Click the View Annotations icon on the MDE tool bar.
The MDE program displays the Annotation Window (Figure 3-20).

Figure 3-20. MDE Annotation Window

The window displays all the annotations made to manually entered values for the
selected RTP. The information is displayed in seven columns:
Annotation Time

RTP Name
Key1, Key2, Key3
Event Time
Annotations

The time and date the annotation was made.

The time stamp is automatically generated by
AIM*Historian.
The name of the annotated MDE RTP.
Optional search keys for retrieving annotations.
Optional time stamp entered with the
annotation.
Text of the note.

115

B0193YL Rev E

3. AIM*Historian Operation

AIM*Historian Archiver
The Tools > Archiver pick opens the AIM*Historian Archiver Window which provides a variety
of a database management tools including backup, restoration, and moving databases. The window is described in On-Demand Archiving on page 143.

AIM*Historian Spy
With AIM*Historian Spy, you can view any component of an instance including the instance
configuration, configuration information that has been copied to remote collector hosts, and
database files. You can open several windows and view several configuration files or database files
for a specific instance and make comparisons.
NOTE

AIM*Historian Spy provides read-only access to configuration and database files.

Use AIM*Historian Configurator or Batch Configuration to change an instance
configuration. Use the MDE Window to add RTP values.
To use AIM*Historian Spy:
1. Choose Tools > Spy or click the Spy icon in the AIM*Historian Manager tool bar.
AIM*Historian opens the AIM*Historian histspy window (Figure 3-21).

Figure 3-21. AIM*Historian histspy Window

116

3. AIM*Historian Operation

B0193YL Rev E

The Instances Window uses a components tree similar to the ones used in the
AIM*Historian Manager Instances and AIM*Historian Configurator Windows to
display instances, their configurations and database files.
Configuration files that have been copied to remote collector host systems are listed at
the end of the Historian Instances and their Component Trees Window.
2. Click on a database or the configuration component to view the component file.
AIM*Historian Spy opens a second window. Figure 3-22 shows a database file for
r10.fdb viewed with AIM*Historian Spy for an instance named hist01.

Double-click
the Index to
access the
RTP

Figure 3-22. AIM*Historian Spy RTP Database File

117

B0193YL Rev E

3. AIM*Historian Operation

3. Double-click the RTP index number for the desired RTP.

AIM*Historian Spy opens the RTP Values Window (Figure 3-23) which displays
collected values for an RTP (an RTP is listed only if it has data).

Figure 3-23. RTP Values Window

NOTE

If you view a component and then close the window, you need to change the screen
activation to another window before you can reselect the previously viewed
component.

118

3. AIM*Historian Operation

B0193YL Rev E

Server Status
To check the status of the servers:
1. Choose Tools > AIM*API Server Status.
AIM*Historian Manager opens the AIM*API Server Status dialog box (Figure 3-24).

Figure 3-24. Server Status Dialog Box

The dialog box displays a tabbed page for each server accessible from the
AIM*Historian Manager application.
The Server group in the upper half of the page lists the server name, the current user
name, and the recent error messages.
The User Function Access group displays the security access privileges configured in
AIM*API for the named user on this server. You need access to an_setup or API
Admin to change these settings; they are not accessible from AIM*Historian
Manager. See AIM*AT Installation Guide (B0193YM) for additional information
about security access privileges.
When the AIM*Historian Manager is not connected to the server, the Reconnect
button is active.
2. Click Reconnect if you want the AIM*Historian Manager to attempt to establish a
connection with the selected server.
3. Click Close to return to the AIM*Historian Manager Window.

119

B0193YL Rev E

3. AIM*Historian Operation

AIM*Historian Demand Writes

The AIM*Historian Demand Write feature enables you to use AIM*Historian RTPs to write
values to an I/A Series or I/O Gate collector. The collector in turn writes the values to another
application such as the I/A Series system, another DCS, or a programmable logic controller
(PLC). The collector also provides these outputs to the AIM*Historian instance so they can be
historized in the appropriate sample database.
Unlike MDE which inserts values into the database as if they had been collected from a control
system or other application (see Manual Data Entry on page 112), the collector actually writes
the values to the target control system database, if the interface between the collector and the
application permits writes.
The RTP values are entered through an AIM*API application using one of the following
AIM*API function calls:
fh_FdbPutValue()

Writes a single value and status. This is the recommended method for
programming Demand Writes.
Before invoking fh_FdbPutValue(), use fh_RTPIndex() to retrieve an
index for the RTP.

wrtval()

Writes a value for an RTP.

Before invoking wrtval(), use getidx() to retrieve an index for the point
(which consists of an index for the historian instance and one for the RTP
itself).

an_write_objects()

Writes values for multiple RTPs.

Before invoking an_write_objects(), use getidx() to retrieve an index for
each point (which consists of an index for the historian instance and one
for the RTP itself).

an_write_valstat()

120

Writes a value and status for a single point. When the write is to an
I/A Series system, the control database accepts the standard status word.
When the writes are to an I/O Gate collector, the call should include a
status of 0.
Before invoking an_write_valstat(), use getidx() to retrieve an index for
the point (which consists of an index for the historian instance and one for
the RTP itself).

3. AIM*Historian Operation

B0193YL Rev E

Refer to AIM*API Users Guide (B0193YN) for details on the parameters used with these calls.
NOTE

The calls wrtval, an_write_objects, and an_write_valstat only function with data
types that are 4 bytes or less. For writes to string-type objects, use
fh_FdbPutValue().

NOTE

While the output of Demand Writes are collected in the instance database, the
AIM*Historian does not guarantee that the writes were received and accepted by
the DCS. A loss of connectivity between the collector and the target system because
of an application or network failure could result in the writes being discarded. The
instance should include other RTPs to read the points in the application after the
Demand Write.
To configure RTPs for Demand Writes:
Use the AIM*Historian Configurator to set the collection method to WRITE
(COLMETH = WRITE).
NOTE

When you specify an RTP value type (other than FILE), the size of the value is
fixed. The size of a given RTP value is not necessarily the same as that of the target
point in the DCS. For example, the size of the integer type RTP (FH_INTEGER,
2) is 4 bytes. This type is used to collect integer values from an I/A Series system.
Integers in I/A Series software (also referred to as Type 2) are only 2 bytes. Thus,
when you write values to an I/A Series system integer using a demand write RTP,
you must limit the range of the value so that it fits into a 2-byte field in the
I/A Series system. The range for the integer value is 32768 to 32767.
If the RTP is turned off, historization stops, but the values are still sent to the
collector for writes to the target system.

121

B0193YL Rev E

3. AIM*Historian Operation

Legacy Interface Servers

Legacy interface servers run on I/A Series stations, respond to data requests from I/A Series stations, and retrieve the data from one of the following sources:

Legacy I/A Series Historians

AIM*Historian instances residing on the same I/A Series station

AIM*Historian instances residing on another machine.

NOTE

Only one version of these servers can be running at a given time on one machine.
These servers reside in the AIM*Historian program directory (/opt/aim/bin).

Starting Legacy Servers for Local Instances

Use the start_server command to control local legacy servers:
start_server { FH | IA | STOP | WHICH }

where:
FH

IA
STOP
WHICH

122

Starts the local AIM*Historian versions of the legacy

servers (histsrv, hsfetch, hrfetch, and ipchisti), which
retrieve data from AIM*Historian instances residing on
the same I/A Series station.
Starts the I/A Series version of the legacy servers (hist_srv, hs_fetch, hr_fetch, and
ipchisti), which retrieve data from the legacy I/A Series Historian.
Stops all legacy servers.
Reports which servers are operating:
0= none
1= AIM*Historian legacy servers
2= Remote AIM*Historian legacy servers
3 = I/A Series version of the servers

3. AIM*Historian Operation

B0193YL Rev E

Starting Legacy Servers for Remote Instances

Use the start_server command to start legacy servers for remote instances:
start_server RFH

where:
hostname

<hostname> [TZ [DST ] ]

Hostname of the remote AIM*Historian instance.
The legacy servers (r_histsrv, r_hsfetch, r_hrfetch, and ipchisti) retrieve
data from AIM*Historian instances residing on the station specified by the
hostname.
The instance host machine must have the AIM*API server running.
For example, to start remote AIM*Historian legacy servers to retrieve data
from AIM*Historian instances on machine AW5100:
start_server RFH AW5100

TZ

DST

Identifies the time zone in which the legacy servers are operating. The
default is the time zone for the instance. Use the TZ argument only if the
legacy servers are in a different time zone than any of the collectors in the
instance.
Specifies whether Daylight Savings Time is in effect where legacy servers
are operating.
Enter 1 for Yes.
Enter 0 for No.
Use the DST argument only if the DST is different than the collectors.

You must restart the servers when Daylight Savings Time changes. Refer to Note on Time
Stamps on page 266 for additional information on the TZ and DST arguments.
Ensure that AIM*API server (apisvr.exe or apisvr.tcp) is operating on the legacy server machine.
The legacy servers preserve the arguments supplied to the start_server script for the next
automatic startup. The histstart program restarts the local or remote legacy servers using the same
parameters specified in the previous restart.
The legacy servers use the an_init.cfg file to map the hostname to an IP address. On Solaris
systems, the file can be found in the /opt/windu directory. On Windows platforms, the file is in
the ..\aim\Common folder. The file can be changed with a text editor.
To map the hostname to an IP address:
1. Open an_init.cfg with a text editor.
2. Add a line in the [TCPIP] section using the following format:
<hostname>=<TCP/IP address> 45678 /dev/tcp 1024
For example: AW5100=152.155.144.101 45678 /dev/tcp 1024

123

B0193YL Rev E

3. AIM*Historian Operation

Stopping AIM*Historian
The histstop command shuts down all local AIM*Historian applications, including collectors
configured for instances on other machines. Use the On/Off controls in the AIM*Historian
Manager if you want to stop an individual instance on a server without shutting down others.
To shut down AIM*Historian programs on a server:
1. Open a command prompt window.
2. Change to the AIM*AT program directory and enter the histstop command.
cd /opt/aim/bin
histstop

The histstop program gracefully shuts down instances and AIM*Historian programs that normally run in the background. It may take several minutes for some processes such as the archiver
to stop.
3. After several minutes, check for processes still operating (such as histsend) and shut
them down.
On Solaris servers:
a. Run histps to display the process identifiers of active AIM*Historian programs.
b. Enter kill -2 <PID> for each PID listed in the second column of the display.
On Windows servers:
a. Right-click the Task Bar and select Task Manager from the pop-up menu.
b. Select the active AIM*Historian processes, histsend for example, and click Stop.
On Windows servers, you can shut down AIM*Historian programs using a Control Panel applet:

124

Choose Start > Settings > Control Panel and double-click the AIM*AT icon in the
Control Panel window to display the AIM*AT dialog box (Figure 3-25).

3. AIM*Historian Operation

B0193YL Rev E

Figure 3-25. AIM*AT Control Panel Applet Dialog Box

4. Select the AIM*Historian tab to display the AIM*Historian page (Figure 3-26), and
click Stop AIM*Historian Applications.

Figure 3-26. AIM*Historian Page

125

B0193YL Rev E

126

3. AIM*Historian Operation

4. Database Management
This chapter describes the resources available for managing and protecting AIM*Historian
databases and configuration files.
This chapter is organized into four parts:
A description of AIM*Historian data files

Instructions on optimizing disk space usage using the DB Wizard

A how-to for the on-demand Archiver

Instructions on setting up the AutoArchiver.

AIM*Historian Database
AIM*Historian instances and their configuration and data files reside in instance-specific
directories. If you selected the default directory when installing AIM*Historian, the instances
are stored in one of the following locations:
/opt/aim/inst/<Instance Name> on Solaris servers
d:\opt\aim\inst\<Instance Name> on I/A Series AW70s
c:\Program Files\aim\inst\<Instance Name> on other Windows NT servers
For example, data and configuration files for AIM*Historian instance hist01 on a Solaris server
are stored in the /opt/aim/inst/hist01 directory.
NOTE

Directory and path specifications in this chapter assume that the AIM*Historian
software was installed to the default locations.
Two types of files are not located in the instance-specific directory:
historian.log file
The historian log file is common to all AIM*Historian instances on a system and is
located in the /opt/aim/inst directory.
Real-time or message database files which you move to other directories.
Once created in the instance directory, you can move the RTP data files and event
message data files to another directory.
If the other directory is specified by the DBPATH attribute for the instance, the files
remain accessible to AIM*Historian, even if the files are located in a directory
mounted to another computer. Requests requiring access to a data file are satisfied as
long as the data file resides in one of the directories specified by DBPATH. However,
files that must still be updated with MDE insertions must remain in the instance
directory.

127

B0193YL Rev E

4. Database Management

File Maintenance Functions

Each AIM*Historian instance database consists of a series of files that can be archived and
restored using whatever commercially available archival system you maintain for other applications. The AIM*Historian Archiver supports three file maintenance functions on a demand basis
to facilitate your normal data security routines.
Moving

Copies the file to a specified directory in the network file system and
deletes the file from the instance directory. If the destination directory is
listed in the instances DBPATH attribute, the file remains accessible to
AIM*Historian. Moving files to a bulk storage subsystem on the
network enables you to conserve disk space on the instance server and still
have ready access to historical data for applications using AIM*Historian.

Copying

Duplicates the database files and maintains the originals in the instance
directory. Use copying for making redundant backups, documenting
history for regulatory reporting, and making data available for off-site
analysis.

Deleting

Removes the data from the instance directory without copying it. To conserve disk space, you may schedule deletion of sample files after reduction
files for the same periods have been archived. If the directories specified in
instance DBPATH attribute are not accessible, the files are not deleted,
and a mapping error message (such as
FH_CANNOT_MAP_RTP_FILE) is inserted into historian.log.

The AIM*Historian AutoArchiver allows you to schedule copying and/or deletion of database
files based on time and/or file size.
AIM*Historian database files are stored in the AIM*Historian database with a .fdb filename
extension.
There are four types of files:
Configuration files

Event message files

Sample files
Reduced RTP files.

128

4. Database Management

B0193YL Rev E

Configuration Files
Configuration files contain the attribute information for all the component members of an
AIM*Historian instance. Component attributes can be added, read, and modified during a configuration session.

A read session interrogates the AIM*Historian files directly.

A modification session copies the configuration files into files with an .RW extension.
When the configuration is committed, AIM*Historian transfers the modified
information from the .cfg.RW files to active .cfg configuration files. When a configuration session is canceled or committed, AIM*Historian deletes the .cfg.RW files.
archiver.cfg

Holds the AutoArchiver schedule for the instance and the archiving status,
both on demand and scheduled, of the instances files.

hist_inst.cfg(.RW)

Contains attribute information for an AIM*Historian instance and the

accompanying data collectors.

hist_message.cfg(.RW)
Contains event message definitions.
hist_msgoffset.cfg(.RW)
Contains an offset into the message definition file for each message type.
hist_msgoffset_hash.cfg(.RW) and
hist_msgoffset_ni.cfg(.RW)
Provide support for mapping messages to a message index.
hist_real_time.cfg(.RW)
Contains RTP definitions.
hist_real_hash.cfg(.RW) and
hist_real_ni.cfg(.RW)
Provide support for mapping RTPs to an RTP index.
hist_rgroup_<rgname>.cfg(.RW)
Contains the reduction group definitions where rgname represents the
reduction group name. For example, hist_rgroup_ rgroup1.cfg contains
the configuration for reduction group rgroup1.
hist_cgroup_<cgname>.cfg(.RW)
Contains control group definitions, where cgname represents the control
group name. For example, hist_cgroup_cgroup1.cfg contains the
configuration for control group cgroup1.

129

B0193YL Rev E

4. Database Management

Event Message Files

Event message database files contain the collected event message data and index tables necessary
to quickly retrieve historical data for use with a client application.
An event message is stored in an event message file:
m<n>.fdb
where n is 10 for the first file and is then incremented by 10 for each new message file. Event
messages are stored in order of arrival time.
Message index information is stored in an event message index file:
im<n>.fdb
so that the message indexes remain in the sequence of the message time stamp. Each message in
an m<n>.fdb file has its own record with index information in an im<n>.fdb file. The ordering of
the message index records by message time stamp ensures quick retrieval of messages.
The message cross-reference file (mxref.fdb) works with the event message database files
(m<n>.fdb). The mxref.fdb file contains the arrival time of the first message in each event message file.
The message index cross-reference file (imxref.fdb) works with the event message index database
files (im<n>.fdb). The imxref.fdb file contains the message time stamp of the first message in each
event message index database file.
imxref.fdb

Indexes into the im<n>.dfb files and cross references between message
time stamp and message index file.

im<n>.fdb

Contains an index for each message in message time stamp order and
indexes into the m<n>.fdb files.

m<n>.fdb

Contains the messages in order of arrival.

mxref.fdb

Indexes into the m<n>.fdb files and cross references between arrival time
and message file.

Sample Files
Sample files contain the collected RTP data and the index table for data retrieval. RTP data files
are ordered by data value time stamp. An RTP insertion before the time of the first value for the
instance is not collected.
NOTE

AIM*Historian forces the start time of the first sample file in an instance (r10.fdb)
to be 24 hours prior to the first collected sample. This earlier start time ensures that
samples are not lost because of incorrect time stamp configuration in the instance
and remote collectors.
The rxref.fdb file contains the starting time of every r<n>.fdb file. There is only one rxref.fdb file,
although there can be many r<n>.fdb files.

130

4. Database Management

B0193YL Rev E

In a new RTP file, each RTP is initially stored as a linked list of value sets with each value set
containing only one value packet. This is a fast and efficient way to store the data, but not
necessarily the fastest way to retrieve data.
When an RTP file is closed, the repack program first sorts the file by RTP, combining all of the
value packets for an RTP into a single value set. If the AIM*Historian instance has the RTP file
compression attribute set (COMPRESS = YES), the value set is then compressed into one or
more compressed value sets. A compressed value set can have a maximum of 1000 value packets.
rxref.fdb

Indexes into the r<n>.fdb files, and cross references between time and file.

r<n>.fdb

The RTP values in time order, where n is the sequential number incremented by 10 as each RTP file is filled.

Reduced RTP Files

AIM*Historian supports both reduction-on-the-fly, which generates reduced values on request
using RTP raw samples as input, and the configured, scheduled generation of reduced values at
three speeds: fast (shortest interval), medium, and slow (longest interval). The reduced data files
minimize the need for keeping the raw RTP sample files (r<n>.fdb) available.
Reduced RTP files contain RTP data which has been reduced and index tables for data retrieval.
Reduced RTP data files are ordered by data value time stamp and contain information for
calculating average (AVG), minimum (MIN), maximum (MAX), and standard deviation
(STDV) values for each RTP configured in the AIM*Historian instance. As shown in Table 4-1,
there is a set of reduced RTP files and one index table for each of the three reduction frequencies.
Reduction files have the same format as RTP database files except that the size of a reduction
value packet is always 52 bytes.
Table 4-1. Reduced RTP Files

Reduction
Frequency

Filename

Fast

rfxref.fdb

Medium

rf<n>.fdb
rmxref.fdb

Slow

rm<n>.fdb
rsxref.fdb
rs<n>.fdb

Description
Indexes into the rf<n>.fdb files, and cross references between time
and file.
RTP values reduced at the fast reduction period.
Indexes into the rm<n>.fdb files, and cross references between time
and file.
RTP values reduced at the medium reduction period.
Indexes into the rs<n>.fdb files, and cross references between time
and file.
RTP values reduced at the slow reduction period.

131

B0193YL Rev E

4. Database Management

Deleting an AIM*Historian Instance

AIM*Historian organizes files associated with an instance into one directory. You can remove the
instance by deleting the directory, but you must first stop AIM*Historian instance and AIM*API
programs that access the instance before deleting the directory.
In the following procedure, all actions are to be done at the machine where the instance resides,
unless otherwise noted.
To delete an instance:
1. Use the AIM*Historian Manager to stop all collectors for the instance, including any
remote collectors, and then stop the instance.
2. If the remote collectors are configured for the instance, stop the histsend process for
the instance to be deleted at each remote collector machine.
Use kill on Solaris systems and the Task Manager on Windows NT systems.
3. At the collector machine, verify that the histsend child processes for the instance have
exited, and kill if necessary.
On Solaris systems, run /opt/aim/bin/histps L to check for proper PID.
On Windows NT systems, check the file histsend_<instance name>_<instance
host name>_pid.dat in the ..\aim\bin\pid directory.
4. At remote collector machines, delete the directory for the instance.
5. If an instance resides on an I/A Series station, ensure that the legacy servers are
stopped by entering start_server STOP from a command line.
6. Exit all command line and GUI programs that are accessing the instance such as
histspy, apitst, and the AIM*Historian Manager.
7. Stop AIM*API.
On Solaris systems, enter: /opt/aim/bin/apistop
On Windows NT systems, use the AIM*AT Control Panel applet.
8. Delete the directory for the instance (../inst/<instance name>) using a native tool such
as Explorer on Windows NT, and rm or File Manager on Solaris.
For example, to remove the hist01instance:

On an AW70, delete:
On Windows NT, delete:
On an AW51 or Solaris servers, delete

d:\opt\aim\inst\hist01
c:\Program Files\aim\inst\hist01
/opt/aim/inst/hist01

9. Restart programs such as AIM*API, legacy servers, and AIM*Historian Manager, as

needed.

132

4. Database Management

B0193YL Rev E

Optimizing Disk Space Usage for RTP Files

The RTP Read Delta (READDELTA) attribute is a key component in controlling the amount of
disk space required to store samples from the process. This deadband defines the change in value
that must occur before a new sampled value is stored (refer to Table E-7 for definitions of the
RTP component attributes). Configuring the optimal delta can involve a trade-off between the
granularity needed for analysis and the overhead required to store the data.
For example, a line temperature value is sampled as the RTP Point006. The temperature normally fluctuates between 50 C and 53 C, and occasionally spikes to 60 C. Table 4-2 shows the
number of samples of Point006 collected over the course of an hour with four different Read
Delta settings for Point006. The scanning rate is once every 30 seconds. During the hour the
temperature spiked to 59 C, and within a minute settled back to 53 C.
Table 4-2. Samples and Storage for Different Deltas

Case
1
2
3
4

Read Delta
0.1
1.0
5.0
10.0

Number of
Samples
120
22
3
0

Disk Space
Used
1920 bytes
352 bytes
48 bytes
0 bytes

The Read Delta set for Case 1 in Table 4-2 is set too low, as it results in a new value being stored
with every scan, and committing valuable disk space to record flutter. At the other extreme, the
Delta for Case 4 is set far too high, as it results in no samples being collected. While the RTP
requires no storage space, the spike in temperature is missed completely. The setting in either
Case 2 or Case 3 is more appropriate depending on your information requirements and the storage demand of other RTPs.
With the AIM*Historian DB Wizard, you can quickly identify the RTPs with the greatest storage
load and then incrementally optimize their Read Delta attributes to decrease the disk space usage.
In addition to the analysis, the wizard actually makes the attribute changes in the configuration
file, so that you do not have to open the AIM*Historian Configurator and modify RTPs one by
one.
The DB Wizard allows you to:

Filter RTPs by name or activity ranking

Select all or some of the RTPs for optimization
Decrease an RTPs storage load by increasing the points Read Delta
Evaluate the effects of optimization settings before applying the settings.

133

B0193YL Rev E

4. Database Management

Starting the DB Wizard

You can start the DB Wizard from the AIM*Historian Manager.
1. Open AIM*Historian Manager, if it is not already available.
On a Windows NT system:
Choose Start > Programs > AimAT > Historian Manager.
On a Solaris platform:
Open a command tool and enter: /opt/aim/bin/histmgr.
2. Click the DB Wizard icon
.
Alternatively, you can start the AIM*Historian DB Wizard without opening AIM*Historian
Manager by following these steps:
On a Windows NT system:
Choose Start > Programs > AimAT > Deadband Wizard.
On a Solaris platform:
Open a command tool and enter: /opt/aim/bin/dbwizard.
The DB Wizard runs.

134

4. Database Management

B0193YL Rev E

Selecting an AIM*Historian Instance

The first dialog box in the DB Wizard (Figure 4-1) prompts you to select an
AIM*Historian instance and define the period of time as the basis for reviewing RTP disk usage.

Figure 4-1. The AIM*Historian Instance Selection Dialog Box

The dialog box consists of a tree view of servers and instances, and controls for selecting the time
span to be used. The DB Wizard bases its calculations on AIM*Historian samples that have
already been collected.
NOTE

To optimize Read Deltas, run the wizard using data from periods of normal plant
operation so you can identify those RTPs which use the most disk space during normal historian operation. During plant upsets the RTPs associated with the disruption are likely to update often. This is history you want to capture. Basing
optimization on the atypical disk usage during plant upsets may result in missing
important process history for both normal and abnormal plant operation.

135

B0193YL Rev E

4. Database Management

To select an AIM*Historian instance and define the time span:

1. Browse the displayed tree structure and select the AIM*Historian server and the
AIM*Historian instance in which you are interested.
2. Define the period to be used.
a. Enter a time and date in the End Date/Time field using the mm/dd/yyyy
hh:mm:ss format.
The dialog box defaults to the current system time when the wizard starts, and
displays the time of day using a 24-hour clock.
b. Use the pull-down menu in the Duration field to specify the length of the
interval.
The choices are 1, 4, 8, 24, 48, or 72 hours, or 1 week. The dialog box defaults to
24 hours. When you select a duration, the wizard updates the Starting Date and
Time field accordingly.
3. Click Next to proceed with the deadband optimizations.
The DB Wizard retrieves every RTP from the AIM*Historian files falling within the specified
date/time range and computes the average samples collected per minute.
The wizard then converts the average samples collected per minute to an average disk usage per
minute. Average samples per minute are computed by taking into consideration the total number
of samples collected over the entire specified time period. Because each sample translates into a
certain number of bytes of hard disk space, the DB Wizard can then compute the disk usage per
minute for each RTP.

136

4. Database Management

B0193YL Rev E

Using the Optimization Window

The DB Wizard ranks every RTP based on its calculated disk usage per minute and displays this
ranking in the Optimization window (Figure 4-2).

Figure 4-2. DB Wizard Optimization Window

The RTPs are ranked by disk usage using the criteria specified at the top of the screen. By default,
the RTPs are displayed in descending order starting with the RTP requiring the greatest use of
hard disk space.
The Criteria for Filtering group above the RTP display enables you to customize the display. The
buttons to the right of the group are for selecting RTPs and applying the new Read Delta settings.
Control groups below the RTP display allow you to increase or decrease the Read Deltas of
selected RTPs and view the results.

137

B0193YL Rev E

4. Database Management

Using the DB Wizard Menus and Tool Bar

Table 4-3 describes the functions available from the application menu bar. The single icon in the
tool bar displays an About dialog box with program version and copyright information.
Table 4-3. DB Wizard Functions

Menu
File

View

Submenu
Save Default
Settings
Reset To Original
Settings
Exit
Tool Bar
Status Bar

Help

Help Topics
About Deadband
Wizard

Description
Saves the current DB Wizard settings as
defaults for the application.
Resets current default settings to their original
values.
Closes the Optimization window.
Displays/hides the DB Wizard tool bar
immediately below the application menu bar.
Displays/hides the status bar at the bottom of
the Optimization window.
Displays an index of application-related help
topics.
Displays program version and copyright
information.

Filtering the RTP List

By default, the RTPs are listed in descending order starting with the RTP with the greatest use
of hard disk space. The filtering tools above the listing (Figure 4-3) allow you to customize the
RTP list by applying either of the following filters: Name and Disk Usage. Additionally, you can
combine these filters using a Boolean OR or AND operation.

Figure 4-3. Filter Tools for Selectively Displaying RTPs

138

4. Database Management

B0193YL Rev E

The name filter works by matching RTP names with the string you enter in the Name by Filter
text box. The question mark is a wild card for any single character, while the asterisk is a wild card
for any number of characters including zero.
For example, the filter specified in Figure 4-3 accepts any RTP name containing the string
1:B?.RI0, where the question mark can be any single character. As shown in the example, the filter
accepted RTPs that are based on Real Input parameters in an I/A Series control database. The filter would have also accepted RTP names such as MEAS1:B7.RI07, but not C1:B88.R107.
When filtering the RTPs by disk usage, you can filter based on a percentage or a specific number.
Select Filter By Top% or Filter By Top Number to list RTPs in ascending order with the number 1
ranking assigned to the RTP that uses the most disk space. Select Filter By Bottom% or Filter By
Bottom Number to list RTPs in descending order.
Use a Boolean AND or OR to combine the name and disk usage filters. If you select the Boolean
AND, then only those RTPs that pass both filter criteria are displayed. If you select the Boolean
OR, then RTPs that pass either filter criteria are displayed.
To filter the list of RTPs displayed:
1. Enter the RTP name on which you wish to filter in the Filter by Name field.
Enter only a * character in the field if you do not want to filter the RTP list by name.
2. Specify one of the following disk usage filters.
The Filter by Top Number filter with a setting of 100 is the default disk usage filter.
3. Specify how to combine the Name and Disk Usage filters.
Select one of these Boolean operators:

Click AND to list only those RTPs that pass both filter criteria.
Click OR to list those RTPs that pass either filter criteria.
4. Click Refresh in the command button group to the right (Figure 4-4) to apply the
filter and refresh the RTP display.

Figure 4-4. Optimization Window Command Buttons

139

B0193YL Rev E

4. Database Management

RTP Information Displayed in the Optimization Window

The Optimization Window provides eight fields of information for the listed RTPs. These fields
of information are summarized in Table 4-4.
Table 4-4. RTP Information Provided in the Optimization Window

RTP Field
RTP Name
Description
Curr. DB
Proj. DB

Curr. Samp.s/Hr
Proj. Samp.s/Hr

Disk Usage Ranking

%Change in Samp.s/Hr
or
%Change in Deadband

Description
Name stored in AIM*Historian for the RTP.
Description stored in AIM*Historian for the RTP.
The existing Read Delta attribute setting for the RTP.
The estimated Read Delta attribute setting for the RTP
based on the value entered in the %Change in Deadband or
%Change in Samp.s/Hr. fields.
The number of samples per hour taken for the RTP.
The estimated number of samples per hour to be taken for
the RTP based on the number entered in the %Change in
Samples/Hr. field.
The ranking relative to all other listed RTPs in terms of disk
usage.
This is a dynamic field of information that changes to
reflect the information entered in the %Change in
Deadband or %Change in Samples/Hr. fields for the RTP.

Selecting RTPs
To select RTPs for inclusion in the evaluation and optimization processes:

Click individual RTP names.

Click the name a second time to deselect the RTP.
Click a name and click a second name while pressing the Shift key to select the two
RTPs and those in between them.

Click Select All to include all displayed RTPs.

When you refresh the display using a different filter criteria, previously checked RTPs remained
selected.

140

4. Database Management

B0193YL Rev E

Optimizing RTP Sample File Disk Usage

The Hard Disk Optimization group (Figure 4-5) below the RTP display allows you to modify the
disk usage by changing the deadbands directly or indirectly by increasing or decreasing the number of samples per hour.

Figure 4-5. Tools for Adjusting RTP Storage Load

The group to the right of the Hard Disk Optimization group shows the predicted results based on
the selected interval (Figure 4-6).

Figure 4-6. Estimated Results of a Read Delta Changes

To optimize the amount of disk space used by one or more RTPs:

1. Select the RTPs to include in the evaluation and optimization processes.
2. Specify the method used to perform the RTP disk space usage optimizations by clicking one of these options:
%Change in Deadband Enter a positive or negative value defining the percent by which to increase or decrease the deadband setting for the selected
RTPs. Decreasing the deadband setting results in an increased sampling rate
for the selected RTPs.
%Change in Samples/hr Enter a negative value defining the percent by
which to decrease the sampling rate for the selected RTPs.
3. Click ReCalculate.
The DB Wizard estimates the effect of the change for the selected RTPs for a
24-hour period and displays these estimations in the following Disk Usage (in Megabytes/day) fields:

Current Rate The current estimated number of megabytes of disk space

being used by the selected RTPs.

Projected Rate with Optimization The estimated number of megabytes of

disk space being used by the selected RTPs based on the optimization method
currently being evaluated.
Net Reduction in Rate This statistic applies only if you are trying to
decrease the disk space used by the selected RTPs.
141

B0193YL Rev E

4. Database Management

The following fields reflect estimated disk space usage for the selected RTPs. These
estimates are updated when you click the ReCalculate button.
Free Space Available The estimated amount of free disk space in megabytes
available on the AIM*Historian server.
No. of Days Available The number of days available before the
AIM*Historian server hard disk would run out of space based on the current
deadband and sampling rate settings. Again, this value does not reflect the
current optimization session settings.
4. Review the disk space usage savings and click Apply DBs (Figure 4-4) if you wish to
apply the current deadband optimization to the selected RTPs.
The wizard displays a dialog box prompting you to confirm the action (Figure 4-7).

Figure 4-7. Dialog Box for Confirming Application of New Read Delta Attributes

5. Click Yes to confirm application of the deadband optimizations.

The DB Wizard modifies the Read Delta for each RTP configuration.
The wizard then checks the effect of the optimization on the operation of the
AutoArchiver (see Using the AutoArchiver on page 154).
The wizard first adds the estimated number of days of disk storage available (as displayed in the Estimates group) and the number of days currently collected.
The wizard then compares the sum with the Archive by Age settings in the AutoArchiver configuration. (See Figure 4-16 and the accompanying instructions on
page 158 for a description of these settings.)
If the new total days is less than the Archive by Age settings, it presents a warning in a
dialog box and gives you the opportunity to adjust the AutoArchiver configuration
(Figure 4-8).

142

4. Database Management

B0193YL Rev E

Figure 4-8. Dialog Box for Adjusting the AutoArchiver Configuration

6. Click OK to implement the change.

The dialog box closes and the DB Wizard window is active.
7. Click Exit to close the DB Wizard application.

Reviewing Results
It may take several iterations to optimize RTPs in a particular instance. After using the wizard,
allow the instance to run for a day or more, so that you have a variety of sample files created with
the new Read Deltas.
When reviewing the effects of a change, start with a comparable time frame. For example, if you
used a three-hour period at the start of the first shift, review the results of the new configuration
using the same three hours. However, before changing Read Deltas again, select a different time
frame.

On-Demand Archiving
The AIM*Historian archiving tools are used to:
Copy selected database files to another directory
Move selected database files to another defined directory within DBPATH

Delete selected AIM*Historian database files

Make files marked Deleted available again to the AIM*Historian after they have
been restored using commands such as tar and ftp, or Windows Explorer and other
non-AIM*Historian tools.
You can move the archived files from the DBPATH directory to another medium using commercially available data backup systems.
This section describes how to archive AIM*Historian data on demand. An AutoArchiver is also
available to move and delete database files, based on parameters such as time and date. The
AutoArchiver is described in Using the AutoArchiver on page 154.

143

B0193YL Rev E

4. Database Management

Table 4-5 lists the file types that can be archived on demand.
Table 4-5. Archivable Database Files

File Type
RTP database files
Message database files
Message index database files
Slow reduction database files
Medium reduction database files
Fast reduction database files

File Name
r<n>.fdb
m<n>.fdb
im<n>.fdb
rs<n>.fdb
rm<n>.fdb
rf<n>.fdb

AIM*Historian Archiver Window

The on-demand archiving tools are selected from the AIM*Historian Archiver window.
1. Open the AIM*Historian Manager window, if it is not already available.
On a Windows NT system:
Choose Start > Programs > AimAT > Historian Manager.
On a Solaris platform:
Open a command tool and enter: /opt/aim/bin/histmgr.
2. Click the Archiver button (
) on the AIM*Historian Manager tool bar.
You can also open the AIM*Historian Archiver window without opening
AIM*Historian Manager:
On a Windows NT system:
Choose Start > Programs > AimAT > Historian Archiver.
On a Solaris platform:
Open a command tool and enter: /opt/aim/bin/histarc.
The AIM*Historian Archiver window (Figure 4-9) includes an application menu bar, a tool bar, a
listing of database files, and status bar.

144

4. Database Management

B0193YL Rev E

Menu
Bar
Tool Bar

Database Listings

Status
Bar
Figure 4-9. AIM*Historian Archiver Window

When a sample, cross-reference, or reduction file is removed from the DBPATH directory,
AIM*Historian tags the file as Deleted, and thus, it is no longer available to AIM*Historian
programs.
When you open the AIM*Historian Archiver window, the archiver program detects previously
deleted files that have been copied back to a DBPATH directory by a non-AIM*Historian tool
such as Explorer or ftp. The archiver program resets the Deleted flag for the newly restored files.

Application Menu Bar and Tool Bar

The application menu bar provides access to programs for selecting instances and database files,
and for moving and copying files. Many of the menu selections can be accessed using keyboard
shortcuts, such as Ctrl+B to create a backup of a selected database file. Several functions can also
be accessed by clicking icons in the tool bar, which is optionally displayed immediately below the
application menu bar.
Table 4-6 summarizes the menu selections and shows the tool bar icons and keyboard shortcuts
for each selection.

145

B0193YL Rev E

4. Database Management

Table 4-6. AIM*Historian Archiver Functions

Menu
Operations

Submenu
Move (Ctrl+M)

Copy Files (Ctrl+C)

Delete (Ctrl+D)

Instance

View

Remove Archive Flag

(Ctrl+A)
Exit
Select

Filter File List

(Ctrl+F)
Go to File (Ctrl+G)
Tool Bar
Status Bar

Real Time
Database Files
Message
Database Files
Message Index
Database Files
Slow Reduction
Database Files
Medium Reduction
Database Files
Fast Reduction
Database Files

146

Tool Bar
Icon

Description
Moves selected files for an instance to another
directory within the list of directories specified
by the DBPATH attribute for the instance.
Copies selected files of an instance to another
location.
Deletes the selected file after you confirm the
action with a dialog box.
Resets the status of selected file to
non-archived.
Closes the AIM*Historian Archiver window.
The menu pick opens the Select Instance
dialog box. The pull-down menu on the
tool bar displays a list of instances, which you
can scroll by pressing the arrow keys. Both
tools can be used to change to a new
AIM*Historian instance.
Opens the Filter File List dialog box for
specifying database files to be displayed in the
AIM*Historian Archiver window.
Opens a dialog box for retrieving database files
that meet specific criteria.
Displays the AIM*Historian Archiver tool bar
immediately below the application menu bar.
Enables the display of status information and
command descriptions in the lower left corner
of the window.
Selects RTP database files for listing in the
window.
Selects message database files for listing in the
window.
Displays message index information in the files
listing window.
Displays slow reduction database files in the
files listing window.
Displays medium reduction database files in
the files listing window.
Displays fast reduction database files in the files
listing window.

4. Database Management

B0193YL Rev E

Table 4-6. AIM*Historian Archiver Functions (Continued)

Menu
Select

Help

Submenu

Tool Bar
Icon

Description

Check

Checks the selected database file for archiving.

Uncheck

Unchecks the selected database file taking it off

the archiving list.

Uncheck All
Help Topics

Unchecks all database files in the instance.

Displays an index of application-related help
topics.
Displays program version and copyright
information.

About histarc

Selecting Database Files

Before you can use AIM*Historian Archiver menu options, you must first select the appropriate
database files from the list displayed in the window.
Identifying databases files involves these steps:
1. Choose the AIM*Historian instance that contains the database files you want.
Optionally, you can select a filtered list of database files. For example, if you are copying files, select only unarchived files for display.
2. Select the database files from the list in the AIM*Historian Archiver window by
checking or unchecking each file.
With the AIM*Historian Archiver you can selectively display the following types of database files:
Sample
Message
Message Index

Slow Reduction

Medium Reduction
Fast Reduction.

147

B0193YL Rev E

4. Database Management

Files for selected instances are displayed in a six-column format:

Check Box

Shows whether the file has been marked for archiving operations.
Archiving operations only apply to files that are checked. The Select menu
and the tool bar offer checking and unchecking functions.

RTP File

Gives the names of selected files. The column header indicates the type of
file you have selected for display. You can specify the file types using the
View menu.

Start Date &Time

The time stamp (mm/dd/yy and hh:mm:ss) further identifies the contents
of the file.

148

Bytes

The files size is displayed in bytes. This column reads Deleted if the file
has been deleted.

Archived

If the files have been copied, the time and date of the backup are
displayed. If the file has not been archived, the field is blank.

Active Path

The directory path where the file resides according to the DBPATH
attribute of the AIM*Historian instance. The column is blank if the file
has been deleted.

4. Database Management

B0193YL Rev E

Selecting an AIM*Historian Instance

When you open the AIM*Historian Archiver from AIM*Historian Manager, the Archiver
window displays files for the instance that was selected at the end of the previous session. You
can change the instance using a menu selection or the Instance text box on the tool bar.
To select an AIM*Historian instance using the menu bar:
1. Choose Instance > Select.
This pick opens the Select AIM*Historian Instance dialog box, which displays a list of
AIM*Historian instances located on the server (Figure 4-10).

Figure 4-10. Select AIM*Historian Instance Dialog Box

2. Select the instance you want to view and click OK.

To select an instance using the tool bar:
1. Click the down-pointing arrow to the right of the Instance text box.
The selection pulls down a list of four instances including the currently selected
instance (Figure 4-11).

Figure 4-11. Selecting Instances from the Tool Bar

2. Use the arrow keys to scroll the list up or down.

3. Press the Enter key when the correct instance is highlighted.
The selected instance is displayed in the text box.
149

B0193YL Rev E

4. Database Management

Locating a File in the Database List

To find a specific file:
1. Select View > GoTo File, or click the GoTo icon on the tool bar.
This opens the Go To File dialog box (Figure 4-12).

Figure 4-12. Go To File Dialog Box

2. Check the file types, such as RTP and Message, for this GoTo request.
3. Select one of the following:

Oldest non-archived file to display the first database file that has not yet been
copied for the file type you selected, such as RTP.
File with Number in name to select a certain database file with a specific number in the filename by entering the number you want.
File starting at Date/Time to specify a certain database file by mm/dd/yy and
hh:mm:ss format.
4. Click GoTo.
The requested file is displayed with a check mark and can be viewed in the list of
other database files already present in the AIM*Historian Archiver window.

150

4. Database Management

B0193YL Rev E

Filtering the Database List

To refine your search:
1. Select View > Filter File List.
The Archiver opens the Filter File List dialog box (Figure 4-13).

Figure 4-13. Filter File List Dialog Box

2. In the Archive Status group, select the database files you want displayed by clicking
Non-Archived or Archived or both.
3. In the Pack Status group, select the files you want displayed by clicking Packed or
Non-Packed or both.
NOTE

Normally, you would only want to copy packed files. Non-packed files require
more space on the archive media.
4. In the Delete Status group, select the files you want displayed by clicking Non-Deleted
or Deleted or both.
5. If you want to select files from a particular time:
a. Click In Time Span in the Time group.
The options in the Time Span group become active.
b. In the Begin group Date and Time fields, enter the beginning time and date in the
proper mm/dd/yy and hh:mm:ss formats.
c. In the End group Date and Time fields, enter an ending time and date.
6. Click OK to re-display the files with the requested filter settings.

151

B0193YL Rev E

4. Database Management

Checking Files
To select database files using Check:
1. Highlight the database file you want from the list displayed in the AIM*Historian
Archiver window.
2. Click the check box icon to select the database file.
An X appears in the box to the left of the filename. You can also use the menu bar
option Select and then choose Check.
When you are finished marking all the database files you want, you can perform
archiving operations using the operations menu or tool bar.
3. Choose Select > Uncheck to unmark a database file.
4. Choose Select > Uncheck All to unmark all database files.

Deleting Database Files

You can delete checked database files for an AIM*Historian instance in the AIM*Historian
Archiver window. When you delete checked files, they are removed from the directory
specified by Active Path.
To delete files:
1. Check the target database files from the files displayed in the AIM*Historian Archiver
window.
See Selecting Database Files on page 147 for instructions.
2. Select Operations > Delete.
A dialog box appears asking if you want to delete all selected files.
3. Click Yes.
If you are deleting files that have not yet been archived, a warning appears indicating
that certain files have not been archived and that by deleting the files the databases are
irrecoverable.
4. Click Yes if you are ready to delete all checked files, including the non-archived files.
Another dialog box appears asking for confirmation to delete the files. After you
confirm the operation, a Delete Status information box displays the working progress
of the delete operation. When the delete operation is complete, the statistics can be
viewed.
NOTE

If the directories specified in instance DBPATH attribute are not accessible, the
files are not deleted, and a mapping error message (such as
FH_CANNOT_MAP_RTP_FILE) is inserted into historian.log.

152

4. Database Management

B0193YL Rev E

Moving Database Files

You can move checked database files from the active directory displayed in the AIM*Historian
Archiver window to another directory in the DBPATH for the AIM*Historian instance.
NOTE

Moved files are not marked as archived.

To move files:
1. Check the database files you want to move from the file list displayed in the
AIM*Historian Archiver window.
See Selecting Database Files on page 147 for instructions.
2. Select Operations > Move.
A Move Request dialog box opens and displays a list of directories to choose from.
3. Select the destination directory and click OK.
The AIM*Historian Archiver opens a Move Status information box, which displays
move statistics when the operation is complete.

Copying Database Files

You can copy checked database files in the active directory displayed in the AIM*Historian
Archiver window to another directory.
NOTE

Copied files are marked as archived.

To copy files:
1. Check the database files you want to copy from the file list displayed in the
AIM*Historian Archiver window.
See Selecting Database Files on page 147 for instructions.
2. Select Operations > Copy Files.
A Select Directory dialog box opens and displays a list of directories from which to
choose.
3. Select the destination directory and click OK.
The AIM*Historian Archiver opens a Copy Status information box, which displays
copy statistics when the operation is complete.

153

B0193YL Rev E

4. Database Management

Using the AutoArchiver

The AIM*Historian AutoArchiver consists of two components:
archiver (Solaris), archiver.exe (Windows NT)
Main program that manages the scheduled archiving for all instances on a
specific server. The program is installed as part of the
AIM*Historian server installation, and is configured to start on boot-up
of the server host. archiver runs as a daemon on Solaris platforms and as a
startup program on Windows NT stations, and remains in operation even
when the AIM*Historian Server is not running. The program implements
the schedule established for each instance on the server in the instances
individual archive configuration file:
/opt/aim/inst/<instance name>/archiver.cfg on Solaris
d:\opt\aim\inst\<instance name>\archiver.cfg on AW70s
c:\Program Files\aim\inst\<instance name>\archiver.cfg on
non-I/A Series Windows platforms.
AutoArchiver Configurator
Client utility for updating archive configuration files. The configurator is
installed from the AIM*AT CD-ROM as one of the AIM*AT
Utilities. The program can be used to update the configuration files of
AIM*Historian instances on any server in the network.

AutoArchiver Features
The AutoArchiver performs two archiving tasks, copying and deleting, on a schedule that you set.
Configure how the AutoArchiver performs these tasks for each of six file types:

Real-time sample data file, r<n>.fdb

Slow Reduction data files, rs<n>.fdb

Medium Reduction data files, rm<n>.fdb
Fast Reduction data files, rf<n>.fdb
Message data and message index files, m<n>.fdb and im<n>.fdb
Configuration (*.cfg) and cross-reference (rxref.fdb, for example) files.
The copy and delete tasks are scheduled separately for each file type, so you can balance the need
to access certain types of information with conserving disk storage. For example, you can schedule
archive functions for an instance that collects samples from 1,500 RTPs and frequently challenges
the disk resources of the instance host. You can make frequent use of reduction files generated by
the instance, and only review the raw sample files when there is unusual change in the reduction
files. You can schedule the AutoArchiver to copy all sample files older than one day to one archive
directory for bulk storage, while copying reduction data files older than two days to another location for analysis in a long term project. You can also configure the AutoArchiver to delete sample
files from the instance directory when the sample files are more than two days old and to delete
reduction files when they are more than 14 days old. Thus, without intervening, you diminish
storage load of the sample files on the instance machine and have the reduced data readily available in two different locations.
154

4. Database Management

B0193YL Rev E

For each file type in each instance, you can configure the following archiving criteria:
Copy the file to the archive directory after the file is at least <Copy to Archive Age> days
old.
Delete the file from the instance directory after the file is at least <Delete from Instance
Age> days old.

Copy and/or delete files of the specific type to the configured archive directory when
all the files in the instance directory use at least <Max Instance Size> megabytes until
the number of megabytes used in the instance is less than the configured maximum.

Delete individual files from the configured archive directory after the files are at least
<Delete from Archive Age> days old.
Assign priorities to the Archive by Age and Archive by Space actions on a scale of
1 (highest priority) to 10 (lowest priority) for copy actions. File types with the highest
priority are copied first.
NOTE

The three different configured ages (Copy to Archive, Delete from Instance and
Delete from Archive) are set individually for each file type. A single Max Instance
Size limit is applied to all files in the instance.
The age of a file is determined by subtracting the time stamp of the last inserted value from the
current time.
If there was no change in the file since the last time it was automatically copied, the
AutoArchiver does not copy the file.
! CAUTION
Be conservative in configuring the file-size criteria for delete actions. If a large file is
created in the instance directory and the AutoArchiver is configured to delete based
on Max Instance Size, the AutoArchiver may delete more files than you had
planned.
Operation of the AutoArchiver is independent of any on-demand archiving. For example, if you
have scheduled AutoArchiver to copy sample files every 12 hours, the program keeps to the schedule even if you manually copy files during one of the 12-hour intervals. However, the manual
archive actions are recorded in the archiver.cfg file for the instance.

155

B0193YL Rev E

4. Database Management

AutoArchiver Configuration
The AutoArchiver Configurator utility can be selected from the AIM*Historian Manager
window:
1. Open the AIM*Historian Manager window, if it is not already available.
On a Windows NT system:

Choose Start > Programs > AimAT > Historian Manager.

On a Solaris platform:
Open a command tool and enter: /opt/aim/bin/histmgr.
Choose Tools > AutoArchiver.
The selection opens the Configurator window (Figure 4-14).
You can also open the AIM*Historian AutoArchiver without opening AIM*Historian Manager:
On a Windows NT system:

Choose Start > Programs > AimAT > Historian Archiver Configurator.
On a Solaris platform:
Open a command tool and enter: /opt/aim/bin/arccfg.

Figure 4-14. AIM*Historian AutoArchiver Configurator Window

156

4. Database Management

B0193YL Rev E

The AutoArchiver Configurator window consists of eight tabbed pages. The first page is used to
select the instance to be configured. The second page establishes the schedule. The other pages set
copy and delete criteria for each of the six file groups. The window opens to the first tabbed page
(Figure 4-14).
To configure the AutoArchiver for an instance:
1. Use the Select Server and Select Historian pull-down lists on the Historian page to
select the instance.
2. Click Scheduling.
The AutoArchiver Configurator displays the Scheduling page (Figure 4-15).

Figure 4-15. AutoArchiver Scheduling Page

3. Use the three pull-down lists to set the schedule.

Start Time and Phase schedule the first archiving session. In Figure 4-15, the first
session is set for 6:10 a.m. You can select 0 through 24 for Start Time. Phase is set in
ten-minute increments, 0, 10, 20, and so on.
Frequency determines when the session is to be repeated. You can select any
frequency between 1 (hourly) and 24 (every 24 hours).
In Figure 4-15, the automatic archiving occurs every four hours (at 6:10 a.m., 10:10
a.m., 2:10 p.m., and so on). The archiver does not run between midnight and the
Start Time/Phase. Thus, with the settings in Figure 4-15, the last scheduled session is
10:10 pm. and does not run until 6:10 the following morning.

157

B0193YL Rev E

4. Database Management

4. Click Sample.
The AutoArchiver Configurator opens the page for configuring archiving criteria for
real-time sample data (Figure 4-16).

Figure 4-16. AutoArchiver Sample Page

The controls on the Sample page are repeated on the Message page and the three
Reduction pages. For each of these file groups, you can set copy and delete criteria,
and specify the destination drive for copying.
There are two criteria groups: Archive by age and Archive by space. These are not
mutually exclusive; for example, you can specify that sample files be deleted when
they are older than 20 days or when all files in the instance use more than
100 megabytes of disk space on the AIM*Historian server.
5. To set the Archive by age criteria, enter a value in the Copy files after Days and Delete
files after Days controls or by using the spinner buttons to increase or decrease the
numbers.
Before copying or deleting a file, the archiver compares the time stamp of the last
value in the file with the current system time to determine if the file meets the criteria.
An entry of 0 means the function is not performed. For example, the entries in
Figure 4-16 specify no copying based on file age, while r<n>.fdb files that are older
than two days are deleted. If you specify a copy age greater than the (non-zero) delete
age, the archiver forces the delete age to be equal to the copy age so that files are
copied before they are deleted.
6. Use the pull-down list to set the Age priority.
Priority can be set from 1 (the highest) to 10 (lowest). Priority refers to the
importance of the file, so that the highest priority (1) means the file is the first to
be copied.

158

4. Database Management

B0193YL Rev E

7. Set the Archive by space criteria by entering a storage amount in the text box and
checking the Copy and/or Delete options.
The total space is set in megabytes and refers to the total amount of disk space used by
the instance in the instance directory on the host system. When the archiver deletes
files based on the space criteria, it deletes the oldest files in the category and continues
until the space used is below the threshold value.
8. Use the pull-down menu to set the Space priority.
Priority refers to the importance of the file, so that priority (1) means the files of this
type are copied first.
9. If you have specified copy functions, enter a storage location in the Archive Directory
field.
In Figure 4-16, the files are copied to the \\aim1\opt\aim\archive. If no destination is
specified, the archiver does not perform any copy functions for the file type.
! CAUTION
If you have more than one AIM*Historian instance, be sure to configure a different
Archive Directory for each instance. Otherwise, files from the different instances
will be intermixed.

NOTE

If you wish your archived files to remain accessible by AIM*Historian, specify the
Archive Directory for the instance as one of the directories you configured in the
instance DBPATH attribute plus the instance name. For example, if DBPATH is
/opt2/aim_archives, specify the Archive Directory for instance hist01 as
/opt2/aim_archives/hist01, for instance hist02 as /opt2/aim_archives/hist02 and so
on.
The Archive Directory Parameters group includes two other options:
You can set the AutoArchiver to start a script or executable on the Archive
host to compress the files, start a tape backup or perform a similar function.

You can specify that the Archiver delete the copied files from the Archive
Directory after a specified number of days. An entry of 0 in this field means
that the files are not to be deleted.
10. Click Apply.
The AutoArchiver Configurator updates the archiver.cfg file for the instance.
11. Select the other file group pages and set the archive criteria and storage location for
these groups.
The Message, Fast Reduction, Medium Reduction, and Slow Reduction pages are the
same as the Sample page.
The last page, Cfg and Xref, does not include delete functions (Figure 4-17).

159

B0193YL Rev E

4. Database Management

Figure 4-17. Cfg and Xref Page in the AutoArchiver Window

12. When the AutoArchiver for the instance is configured, return to the Historian page
and select another instance or click OK to save the configuration and exit the
AutoArchiver Configurator window.

AutoArchiver Test Mode

The AutoArchiver supports a test mode that allows you to accelerate the Archive by Age
parameter and test your setup over the course of an hour or two. By inserting a Speed Factor in
the AutoArchiver configuration file for a specific instance, you proportionally collapse both the
Copy files after <n> days setting and Delete files after <n> days setting so that an entire archiving
cycle is accomplished in a matter of hours or minutes. For example, if you have scheduled sample
files to be copied after one day and deleted after two, you can accelerate the schedule by a factor of
24 to copy the files after an hour and delete them after two hours. Likewise, a factor of 96 copies
the files when they are 15 minutes old and deletes them after 30 minutes. When a speed factor is
greater than 1, the parameters set on the Scheduling Page (Figure 4-15) are ignored so that the
AutoArchiver is started immediately.
To test an AutoArchiver configuration:
1. Complete the configuration for the specific instance and exit the AIM*Historian
AutoArchiver Configurator.
2. Use a text editor such as Notepad or vi to open the configuration file (archiver.cfg).
The file is located in the instance directory (for example, c:\program
files\aim\inst\hist01 or /opt/aim/inst/hist05).

160

4. Database Management

B0193YL Rev E

3. If there is no Speed Factor entry in the Scheduling Section, insert a line in the format
speed=<n> to set the factor.
For example, enter speed=24 to convert days to hours.
The Speed Factor is applied to a specific Archive by Age Setting for each file type
(sample, message, and so on). Thus, if the original configuration calls for Sample files
to be copied after one day and Slow Reduction files after seven days, a Speed Factor of
48 would copy the sample files after a half-hour and Slow Reduction files after 3
hours.
4. Save the file and exit the text editor.
5. Observe the AutoArchiver performance.
6. Open the archiver.cfg file, and delete the Speed Factor parameter, comment it out, or
set it to 1.

Display of Archived Files

In addition to the Archiver window, you can use AIM*Historian Spy to check whether files have
been archived. The icon for an archived file in the AIM*Historian Spy window is a red file symbol
with the letter A (Figure 4-18). The file listing includes the time stamp of the first sample in the
file, displayed as the seconds from January 1, 1970 in parenthesis and in local time following the
parenthesis. The same display convention is used whether the file was archived on demand or
automatically by the AutoArchiver.

Archived file Icon

Time stamp
of first sample
in the file

Figure 4-18. Display of Archived RTP Files in the AIM*Historian Spy Window

161

B0193YL Rev E

162

4. Database Management

5. Troubleshooting
This chapter outlines troubleshooting tools and techniques for AIM*Historian.
Unless otherwise specified, the utilities described in this chapter are console applications and
reside in the AIM*Historian program directory.
Command line examples in this chapter are for a Solaris server.
! CAUTION
Never shut down an AIM*Historian program by switching the power off or by killing a process with kill -9, or with the Windows NT Task Manager. Such actions
can lead to file corruption.

! CAUTION
Some of the utilities discussed in this chapter were developed as debugging tools
and may have little use in a production environment. Use discretion when employing these resources, especially msgtst, which is a test program that inserts canned
test messages into an AIM*Historian instance. Do NOT use msgtst on an
AIM*Historian instance that is collecting process data.

NOTE

AIM*Historian forces the start time of the first sample file in an instance (r10.fdb)
to be 24 hours prior to the first collected sample. This earlier start time ensures that
samples are not lost because of incorrect time stamp configuration in the instance
and remote collectors. As a side effect, r10.fdb often contains one sample per point,
or no samples at all.

Version Information
Before calling for technical support, you should identify the release number of the AIM*Historian
software:
On a Windows server, choose Help > About AIM*Historian from the menu bar in
AIM*Historian Manager.

On a Solaris machine, run /opt/aim/bin/aim_versionid to display complete version

information.
This utility is available with AIM*AT version 3.0.2 and later.

163

B0193YL Rev E

5. Troubleshooting

Troubleshooting Tools
The following resources can assist you in resolving operational problems with an
AIM*Historian instance:
Release Notes

The Release Notes describe issues and workarounds you need to be aware
of. Check the Release Notes first for an explanation of unexpected
AIM*Historian behavior.

Error Codes

Appendix A Error Codes lists mnemonics corresponding to error codes

returned from AIM*API function calls for AIM*Historian. You can also
examine error codes in files aimapi.h and aimhistorian.h located in the
/opt/aim/include directory.

AIM*Historian
Log File

The AIM*Historian log file is ./inst/historian.log. The file contains

messages generated by AIM*Historian software when it detects error
conditions. You can view these messages with the Log File page in
AIM*Historian Manager. As a troubleshooting aid, the message records
can be copied to another application for analysis or communication with a
service representative (see Log File Page on page 99).
The Process field of the error messages in the historian.log file contains
the process ID and the program name. When applicable, it also includes
additional information to differentiate the process, as follows:

histmain <instance>
repack <instance>
reduce_rtps <instance>
iacol <instance> <collector>

iogatecol <instance> <collector>

soecol <instance> <collector>
histreceive <instance> <remote collector HOSTNAME>

AutoArchiver
Log File

164

histsend <instance machine name> <instance>.

When the AutoArchiver detects an error condition in an instance, it

logs a message to /opt/aim/inst/<instance>/archiver.log. To enable trace
messages, edit the archiver.cfg file to set the VERBOSE key to 1. The
configuration change takes effect on the next AutoArchiver operating
cycle.

5. Troubleshooting

AIM*Historian
Trace File

B0193YL Rev E

The AIM*Historian trace file is supported by AIM*Historian programs

with the -t[<trace_file>] argument. The -t switch turns tracing on and logs
traces to the file specified by trace_file. If you do not specify a file name,
the default file is /tmp/fh_trace.txt on Solaris systems and
c:\tmp\fh_trace.txt on Windows platforms.
Contents of the trace messages vary by program. The trace file is
primarily intended for debugging and troubleshooting by Invensys
personnel.
If tracing is not set, errors are still logged as appropriate to the
AIM*Historian log file.

NOTE

For tracing to be enabled, you need to stop the desired program and rerun it with
the -t argument (and, optionally, with the <trace_file> argument to specify the trace
file name).
The trace feature can be used on hsfetch, hrfetch, histsrv, and ipchisti
programs on both Solaris and Windows platforms. The diagnostic mode,
entered with the -T flag, is a mode not used in normal operation. For
example, specify hsfetch Tc:/tmp/hs.log in start_server.ksh to enable
tracing for the hsfetch program on an AW70. Forward slashes in the log
file path name are recommended on both AW51s and AW70s.
Process Status Tool

The histps script on Solaris systems and the histps.bat batch file on
AW70s provide a list of currently active AIM*API and AIM*Historian
processes, and may also show other processes related to the operation of
AIM*API or AIM*Historian. On Solaris based systems, specifying the
L argument results in a long version which shows how the process was
started up.
The histps.bat tool is not available on non-I/A Series Windows NT
systems. Use the Windows NT Task Manager instead.
The /opt/aim/bin/pid directory contains files that identify the process
IDs of an AIM*Historian process associated with a given instance and
collector. These files are particularly useful on Windows NT stations, as
the Task Manager does not include program arguments in its display.
The files include:
histmain_<instance>_pid.dat
histreceive_<instance>_<collector machine hostname>_pid.dat
histsend_parent_pid.dat
histsend_<instance machine hostname>_<instance>_pid.dat
ipchisti_pid.dat (message collector)
iacol_<instance>_<collector>_pid.dat
iogatecol_<instance>_<collector>_pid.dat

165

B0193YL Rev E

5. Troubleshooting

Diagnostic Utilities
Table 5-1 summarizes the diagnostic utilities available with AIM*Historian. Descriptions of the
utilities follow the table.
Table 5-1. Summary of Diagnostic Utilities

Utility
clearcfg

dumpcvs

Description
Clears all traces of the previous
configuration session. The same
function is provided on the Instance
page of the AIM*Historian Manager
(page 94).
Dumps the current value and status
information.

dumprcol

Dumps the remote collector information.

dumpred

Dumps the reduction information.

histspy

Opens a view-only GUI for examining

the AIM*Historian configuration and
data.
Supports an interactive interface to all
AIM*API functions.
Checks the sanity of message data files
such m10.fdb and im10.fdb.
Use when corruption is suspected.
Fixes the message data files such m10.fdb
and im10.fdb. Use when corruption is
suspected.
Writes and reads the canned I/A Series
event messages.

apitst
msgcheck

msgfix

msgtst

166

Location
Installed with AIM*Historian software to
the /opt/aim/bin directory.

AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities
AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities
AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities
Installed with AIM*Historian software to
the /opt/aim/bin directory.
Installed with AIM*Historian software to
the /opt/aim/bin directory.
Installed with AIM*Historian software to
the /opt/aim/bin directory.
Installed with AIM*Historian software to
the /opt/aim/bin directory.
AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities

5. Troubleshooting

B0193YL Rev E

Table 5-1. Summary of Diagnostic Utilities (Continued)

Utility

Description

Location

sec2asc

Converts a time stamp from internal long

format to human-readable format.

rtpcheck

Checks the sanity of RTP data files such

as r10.fdb. Use when corruption is
suspected.
Fixes the RTP data files such as r10.fdb.
Use when corruption is suspected.
Makes requests to the legacy servers such
as hsfetch (I/A) to test their operation.

AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities
Installed with AIM*Historian software to
the /opt/aim/bin directory.

rtpfix
testhv

testvar

Supports create, ramp, get, and delete of

an I/A Series shared variable.

xrebuild

Rebuilds the AIM*Historian RTP

cross-reference file. Use when corruption
is suspected.
Outputs System Monitor messages from
an AW51.

fh_sacego

Installed with AIM*Historian software to

the /opt/aim/bin directory.
AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities
AIM*AT CD:
/unix/sol2.51/unsp_utilities
/unix/sol8/unsp_utilities
\win\unsp_utilities
Installed with AIM*Historian software to
the /opt/aim/bin directory.
Installed on an AW51s in the
/opt/aim/bin directory

There are additional diagnostic utilities on the AIM*AT CD in the unsp_utilites folder in the
platform specific directory. These utilities include usage notes.

167

B0193YL Rev E

5. Troubleshooting

clearcfg
The clearcfg utility removes all traces of the previous read/write configuration session for a local
AIM*Historian instance. There are rare occasions when the Cleanup button of remote
AIM*Historian Manager can no longer perform this function (see Instance Page on page 94),
or when AIM*Historian Configurator is locked up because of a leftover configuration session. In
these cases, execute clearcfg on the station where the AIM*Historian instance resides.
The clearcfg program removes all files ending in .RW in the directory for the specified
AIM*Historian instance (/opt/aim/inst/<Instance Name>) and resets several flags in the instance
configuration file indicating the status of any configuration session. You should use clearcfg
instead of simply deleting the files, so that the flags are reset.
To use clearcfg:
Open a command window, change to the AIM*Historian program directory, and
invoke the program specifying the instance name.
cd /opt/aim/bin
clearcfg hist01

dumpcvs
The dumpcvs utility enables you to view intermediate reduction buffer contents.
To view buffer contents:
1. Open a command window, change to the AIM*Historian program directory, and
invoke the program specifying the instance name.
cd /opt/aim/bin
dumpcvs hist01

2. Enter y in response to the first prompt if you want a list of pointers to CVS records.
3. At the next prompt, enter the RTP number for the point record.

168

5. Troubleshooting

B0193YL Rev E

dumprcol
The dumprcol utility is a diagnostic run at a remote collector station to view miscellaneous information for a collector.
To use the dumprcol utility:
1. At the collector station, open a command window and change to the AIM*Historian
program directory:
cd /opt/aim/bin

2. Invoke the program using the following syntax:

dumprcol Hist=<Instance> [Col=<Collector>] [V=<Verbosity>]

Where:
Instance
Collector

Verbosity

Name of the AIM*Historian instance.

Name of the real-time collector. Specify a collector when
you want to view the circular file for samples from a
specific collector.
Level of detail:
1 to output the circular file header contents and collector
status information (default).
2 to also include a sanity check on the linked list.
3 for level 2 plus brief output for each message.
4 for level 2 for samples only.
5 for level 2 for event message only.
6 for level 2 for samples and event messages.
7 for level 2 plus the entire message header for each circular
file message.

The dumprcol outputs:

The contents of the circular file header for the requested instance

Status information for the collector

If Verbosity is 2, a PASSED/FAILED status from a sanity check of the linked list of
messages within the circular file (hist_circ_file.dat) for the instance at the remote
collector.
! CAUTION
Use Verbosity level 2 and above with care. For a very large circular file, the time it
takes dumprcol to sanity-check the files linked list and print messages will delay
sample collection at the remote collector.
Figure 5-1 is a sample output from a dumprcol diagnostic.

169

B0193YL Rev E

5. Troubleshooting

Figure 5-1. Sample dumprcol Output

170

5. Troubleshooting

B0193YL Rev E

Table 5-2. Circular File Header Fields in dumprcol Output

Field
Push Offset
Pull Offset
Last Message Offset
Last Inserted Message#
# Messages Overwritten
# Bytes in File
Last Sent Message#
Oldest Message Offset

Highwater #Bytes in File

Collector Time Zone (TZ)
Collector DST
Collector Type
Current synch offset
# Samples Overwritten
# Event Msgs Overwritten

Description
Where the next message goes.
Where histsend retrieves from (0=empty).
Offset to last inserted message.
Number of last inserted message.
Number of messages overwritten in file.
Number of bytes in file currently in use.
Last send message number.
Determines where to start looking for the last message
received by histreceive. This field is used when the
instance reconnects with the remote collector.
Highest number of bytes ever used in the file.
Time zone configured for collectors running on this
machine.
Daylight savings time. Yes is 1. No is 0.
Collector type. See Table E-5 for a description of the
TYPE attribute.
Holds offset to message during synchronization of file
on reconnect.
Number of samples overwritten since last histreceive
startup.
Number of event messages overwritten since last histreceive startup

171

B0193YL Rev E

5. Troubleshooting

dumpred
The dumpred program is a diagnostic utility for viewing packet contents in a reduction data file.
To view packet contents:
1. Open a command window and change to the AIM*Historian program directory:
cd /opt/aim/bin

2. Invoke the program using the following syntax:

dumpred [-vnumber]

Where:
Instance
-vnumber

File Type

File Number

<Instance> <File Type> [<File Number>]

Name of the AIM*Historian instance.

Level of detail:
-v1 Report file name, errors and warnings (default).
-v2 Print file header and detailed file summary.
-v3 Report on each point in the file.
r for RTP.
rf for fast reduction file.
rm for medium reduction file.
rs for slow reduction file.
Target file. Specify the number within the file name,
for example, 10 to specify r10.fdb and rs10.fdb. If the
file number is omitted, all files in the instance are
checked.

The application divides the aggregated operation values by the aggregated time to get
the final reduced values.
A log is generated in the /opt/aim/inst/<Instance Name>/dump_red_files.log.

histspy
The histspy window is a view-only tool for examining configuration and data information for
AIM*Historian instances, and for examining the AIM*Historian log file. Some of the displays
show internal information which can be useful when working with Invensys service personnel to
troubleshoot unexplained AIM*Historian behavior. Unlike the other utilities described in this
section, histspy is a supported utility and is automatically installed with AIM*Historian software.
See AIM*Historian Spy on page 116 for information on using this tool.

172

5. Troubleshooting

B0193YL Rev E

apitst
The apitst program is an interactive, menu-driven utility for exercising and inspecting functions
of AIM*API and AIM*Historian programs. It can be a helpful diagnostic tool during application
development and it does minimal error checking of inputs to allow testing of AIM*API library
routines.
Defaults are enclosed within square brackets. To use the default value, press the return key.
Help text can be obtained for most fields by entering a question mark. Some fields also provide
more extensive help if you enter two question marks.
Below are a few examples of commonly used features of apitst to try when troubleshooting an
AIM*Historian system.

Example 1
To generate hourly reduced values for RTP from an AIM*Historian database:
1. At command line, run /opt/aim/bin/apitst.
2. Select menu item 700 for AIM*Historian functions.
3. Select menu item 14 for fh_FdbReduction function.
4. Enter AIM*Historian instance name for historian.
5. Enter RTP index for index and ignore the next prompt (pname).
6. Enter the date and time for the Start and End times.
7. Default and previous entries are shown in brackets for each prompt. Press the Return
key to accept the default or previous setting.
8. Enter 1 for direction, specifying backward, that is, descending order of values.
9. Enter 8 for reduction, specifying maximum value.
10. Enter 0 for interpolate, which is currently ignored.
11. Enter 3600 for time_interval, specifying get reduced value for one hour interval (3600
seconds).
12. Enter 50 for percent, specifying that at least half the samples in the interval must be
valid for the reduced value to be valid.
13. Enter 10 for numpts specifying all reduced values within oldtime/endtime range.
Alternatively, specify a nonzero number to limit results to fixed number of values.
14. Enter 100 for maxnum, limiting the request to 10 samples returned by an individual
function call.
15. Accept the supplied response to the more prompts.
16. 1 indicates that this is not a first call, that is, it is a continuation of a previous
fh_FdbReduction() call.
17. Observe results and press the Return key when prompted.
18. If more returns 1, repeat the request and press the Return key when prompted to get
the next set of values. Repeat until more returns 0, indicating no more values.
Figure 5-2 shows the prompts and responses for an fh_FdbReduction session, and the
first two lines of the resulting report.

173

B0193YL Rev E

5. Troubleshooting

Figure 5-2. Generating Hourly Reduced Values

NOTE

Enter ? at the Date and Time prompts for help on specifying the start and end time
stamps.

174

5. Troubleshooting

B0193YL Rev E

Example 2
To get the ten most recent samples for an RTP from an AIM*Historian database:
1. At the command line, run /opt/aim/bin/apitst.
2. Select menu item 700 for AIM*Historian functions.
3. Select menu item 13 for fh_FdbGetValues function.
4. Enter AIM*Historian instance name for historian.
5. Enter RTP index for index and rtp (next prompt) is ignored, OR enter 0 for index
then enter the RTP name for rtp.
6. Set Start time and End time to 0 by entering 0 at the Date prompt:
Date? 0
7. Enter 1 for direction, specifying backward; that is, descending order of values.
8. Enter 10 for numpts, limiting the request to 10 samples overall within the specified
time range.
9. Enter 10 for maxnum, limiting the request to 10 samples returned by individual function call.
10. Enter 0 for more indicating that this is a first call; that is, it is not the continuation of
a previous fh_FdbGetValues() call.
11. Observe results and press the Return key when prompted.
12. To repeat this request multiple times, in order to observe how the values are
changing, see Example 4.

Example 3
To get the most recent sample for RTP from an AIM*API database:
1. At command line, run /opt/aim/bin/apitst.
2. Select menu item 300 for Object functions.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

Select menu item 30 for getidx() function.

Enter C1 for compound.
Enter B1 for block.
Enter RI01 for parameter.
Note the returned index. An index of -1 means the object is not in the AIM*API
database.
Select menu item 33 for mreaidx() function.
Enter noted object index for index.
Enter y for end of indexes.
Observe results.
To repeat this request multiple times in order to observe how the values are
changing, see Example 4.

175

B0193YL Rev E

5. Troubleshooting

Example 4
To repeat the previous request multiple times and observe each result:
1. Make an apitst request.
2. Enter 0 for Repeat Last.
3. Enter n for timing test.
4. Enter 5 for num iterations; that is, a reasonable number of repeats.
5. Enter 5 for delay in seconds; that is, a reasonable wait time between requests.
6. Observe results.

Example 5
To do a timing test for a request, observing the final result, with timing figures:
1. Make an apitst request.
2. Enter 0 for Repeat Last.
3. Enter y for timing test.
4. Enter 10 for num iterations; that is, a reasonable number to get a good average time
required to do an individual request.
5. Enter 0 for delay in seconds.
6. Observe results.

msgcheck
When you suspect event message database corruption, use the msgcheck program to check the
integrity of all message data files (m<n>.fdb) in the instance in relation to their associated index
files (im<n>.fdb). Message file corruption can occur when there is a power outage or other
hardware failure.
The msgcheck program successively scans the m-files and im-files, matching the message headers
from both sets of files. The program prints a status line for each file opened and generates a log
file of selectable verbosity which describes any defects found in the files.
The checks take several seconds per file. The utility makes no judgement about the contents of
the message files. The program checks event message files only. Use rtpcheck to check RTP files.
Use the msgfix program to repair identified defects.
NOTE

The program performs only read operations and can therefore be executed online
without shutting down the instance.

176

5. Troubleshooting

B0193YL Rev E

To run msgcheck:
1. Open a command window and change to the AIM*Historian program directory:
cd /opt/aim/bin

2. Invoke the program using the following syntax.

msgcheck [-vnunmber] <instance>

Where:
-vnumber

instance

Level of detail:
-v1 Report errors and summaries (default).
-v2 Print file header and irregular messages.
-v3 Print a synopsis on each message in the file.
-v5 Reserved.
-v7 Reserved.
Name of the AIM*Historian instance.

3. To print a usage synopsis, run msgcheck without arguments.

4. Review the log file in /opt/aim/inst/<Instance Name>/msgcheck.log.
Examples:
To check the message files in hist01, enter: msgcheck hist01

To check message files in hist01 and generate a synopsis of each message,

enter: msgcheck -v3 hist01

Known Problems
The msgcheck program has the following limitations:
The program does not work if the index files (im<n>.fdb) are missing.

The program does not check the message cross-reference file (mxref.fdb).
The program does not consider DBPATH when locating message files.

177

B0193YL Rev E

5. Troubleshooting

msgfix
When msgcheck finds defects in message data files (m<n>.fdb) or their associated index files
(im<n>.fdb), you can attempt to repair these files with the msgfix program. In many cases, msgfix
recovers at least a portion of the messages collected in the files.
Similar to msgcheck, the utility msgfix successively scans the contents of the message files and
index files, matching the message headers from both sets of files. While doing so, it rebuilds the
index files with matching entries for each usable message in the message files. Messages with
defective message headers receive no entry in the new index file under construction, and thus
become inaccessible for all practical purposes. Defective messages are not actually removed from
the message files, only their references in the index files are removed.
Msgfix and msgcheck make no judgement on the actual message contents.
Msgfix is able to recover messages which, for some reason, had lost their reference in the index
file.
Index entries for deleted message files are preserved in the new index file, so that they can be used
after the deleted messages are restored from an archive at a later time.
The amount of data that can be recovered depends on the type of damage, but the resulting files
should again be usable without upsetting the data retrieval applications.
Msgfix prints a status line on the terminal for each file opened, and generates a log file of selectable verbosity which closer describes the defects found and repaired.
Before using msgfix, run the msgcheck utility to determine if the message files contain
correctable defects.
! CAUTION
Since the program performs critical file write operations, the AIM*Historian
instance must be shut down before this program is run. Stop the legacy servers
(especially ipchisti) and all custom applications that access the message files or message index files.

! CAUTION
Back up all message index files (im<n>.fdb) before the program is executed.

! CAUTION
Unlike rtpfix, msgfix does NOT prompt to confirm file modification.

178

5. Troubleshooting

B0193YL Rev E

To use msgfix:
1. Open a command window and change to the AIM*Historian program directory:
cd /opt/aim/bin

2. Invoke the program using the following syntax:

msgfix [-vnumber]

Where:
-vnumber

instance

<instance>

Level of detail:
-v1 Report errors and summaries (default).
-v2 Print file headers and irregular messages.
-v3 Print a synopsis on each message in the file.
-v5 Reserved.
-v7 Reserved.
Name of the AIM*Historian instance.

3. To print a usage synopsis, run msgcheck without arguments.

4. Review the log file in /opt/aim/inst/<Instance Name>/msgfix.log.
Examples:

To repair message file defects in hist01, enter: msgfix hist01

To repair message file defects in hist01 and generate a synopsis of each message,
enter: msgfix -v3 hist01

Known Problems
The following restrictions apply to the present version of msgfix:
Back up the original index files (im<n>.fdb) before msgfix is run in case unanticipated
problems with files cause the program to malfunction. Msgfix replaces the index files
without notice.

The message index files (im<n>.fdb) must exist for the program to run, even though
they are almost completely rebuilt by msgfix.
All AIM*Historian programs, including the legacy servers and all applications that
access the message files and message index files, must be shut down before msgfix is
executed. Otherwise, the index files (im<n>.fdb) cannot be replaced with their
corrected versions and additional file corruptions may occur.
The programs are designed for use with multiple index files (im<n>.fdb), but have
been tested only with a single index file im10.fdb.
The program does not repair the message cross-reference file (mxref.fdb).
Msgfix creates and deletes temporary files without notice.

No mechanism is in place to grow the new index files if it were necessary.

DBPATH is not considered for locating the message files.

179

B0193YL Rev E

5. Troubleshooting

msgtst
The msgtst program tests the AIM*Historian ability to read and write event messages. You
have the choice of reading, writing, or writing then reading event messages. When writing, msgtst
writes a set of 12 canned messages, hard-coded within msgtst. msgtst assumes that the event
message types within the LEGACY message group have been configured for the AIM*Historian
instance as in the example configuration files messages.inp and cfgcmd.inp (refer to Event Message Configuration on page 72).
! CAUTION
DO NOT use msgtst to insert messages into a production AIM*Historian instance.
To use the msgtst utility:
1. Change to the AIM*Historian program directory:
cd /opt/aim/bin

2. Invoke the program using the following format:

<instance> [<put_in>] [<repeat_count>] [<sleep_secs>] [<start_second>]
[<end_second>] [<max_read>] [<print_after>]

msgtst

Where:
instance
put_in

repeat_count
sleep_secs
start_second

end_second

max_read

print_after

180

Name of the AIM*Historian instance.

1 = read messages only (default).
2 = write messages only.
3 = write and read messages.
Number of times 12 canned messages are inserted
(default: 1).
The number of seconds to sleep between repeats
(default: 0).
The starting second when reading
messages, accomplished by msgtst by
calling fh_FdbMsgQuery() (default: 0).
The ending second when reading
messages, accomplished by msgtst calling
fh_FdbMsgQuery() (default: 999999999).
The maximum number of times fh_FdbMsgQuery()
is called to read messages; one message per call.
-1 means read all messages between start_second
and end_second (default).
The number of messages to read before
printing the short progress message.
-1 means wait until all event messages have been read
(default) .

5. Troubleshooting

B0193YL Rev E

Examples:
To read all event messages from instance hist01 from seconds 0 to 999999999,
enter: msgtst hist01
To read all event messages from 955000000 to 965000000 with a progress message
after every 1000 messages, enter: msgtst hist01 1 0 955000000 965000000 -1 1000

To write one set of canned messages, enter: msgtst hist01 2

To write 10 sets of canned messages, enter: msgtst hist01 2 10

To write 20 sets of canned messages, then read all event messages, enter:
msgtst hist01 3 20

To write 20 sets of canned messages, then read all event messages from
965000000 to 999999999 with progress message every 100 messages, enter:
msgtst hist01 3 20 965000000 999999999 -1 100

sec2asc
The sec2asc program converts a time stamp from its internal long format to a more easily
understood format. The conversion function used by the program is tim_asc(), which in turn uses
localtime(), standard on both Solaris and Windows platforms. The localtime() program considers
time zone and DST.
Without argument, the program prints the current time as determined by the system function
time().
With a decimal number as an argument, sec2asc also converts that number into a readable format.
For example:
You enter:
sec2asc 1000000000

The utility returns:

time()=1026941315 - localtime()=07/17/02 17:28:35 - gmtime()=07/17/02 21:28:35
time()=1000000000 - localtime()=09/08/01 21:46:40 - gmtime()=09/09/01 01:46:40

rtpcheck
The AIM*Historian utility rtpcheck verifies the sanity of RTP data files (r<n>.fdb files). When
you suspect there is database corruption, run rtpcheck to check a selected RTP file or all the RTP
files in the instance. Data file corruption has been observed on rare occasions when there was a
sudden power outage or similar traumatic event.
Rtpcheck scans the entire contents of the RTP files, checks the integrity of the linked lists of data
sets, and verifies that each data set belongs to the correct RTP variable. It prints a status line on
the terminal, and generates a log file of selectable verbosity to specify the types of errors found in
the files.
If any corrupted files are found, they can be repaired with rtpfix (see page 157).
The check only takes a few seconds per file, depending on the file size. The program checks RTP
files, but not event message files.

181

B0193YL Rev E

5. Troubleshooting

To use rtpcheck:
1. Open a command tool and change to the AIM*Historian program directory:
cd /opt/aim/bin

2. Run rtpcheck using one or more of the arguments below:

rtpcheck [[-v<number>]

<instance> [<file number>] [-t<type>]]

Where:
-v<number>

instance
file number
type

[No arguments]

Level of detail:
-v1 Reports file names, errors and warnings
(default).
-v2 Prints the file header and a detailed file
summary.
-v3 Reports on each point in the file.
Name of the AIM*Historian instance.
RTP file by number. If not used, all RTP
files are checked.
0 = RTP (default)
1 = RF
2 = RM
3 = RS
Prints a usage synopsis.

NOTE

The rtpcheck program performs only read operations and can therefore be executed
on-line without shutting down the instance.
3. Review the log file /opt/aim/inst/<instance>/rtpcheck.log
Examples:
To check all RTP files in hist01, run: rtpcheck hist01

To check the RTP file r570.fdb in hist01, run: rtpcheck hist01 570
For a report on each point in the RTP file r570.fdb in hist01, run:
rtpcheck -v3 hist01 570

182

To check all RF files for hist01, run: rtpcheck hist01 -t1

5. Troubleshooting

B0193YL Rev E

rtpfix
When errors are found in an RTP data file with rtpcheck, run rtpfix to attempt to repair these
files. In many cases, rtpfix can recover at least a portion of the data collected in the file. Repacked
files, however, have a smaller chance of recovery, and FoxHistory files that were repacked prior to
the installation of Quick Fix #fh12B_6 for FoxHistory Version 1.2B may not be repairable.
The program checks the file in the same way that rtpcheck identifies recoverable errors and completely rebuilds the internal linked list of data sets. The amount of data that can be recovered
depends on the type of damage, but the resulting file should again be usable without upsetting the
data retrieval applications.
NOTE

Since the program performs critical file write operations, the AIM*Historian
instance must be shut down before this program is run.
To run rtpfix:
1. Open a command window and change to the AIM*Historian program directory:
/opt/aim/bin

2. Run rtpfix using one or more arguments below:

rtpfix

[[-v<number>] <instance> <file number> [-t<type>]]

Where:
-v<number>

Level of detail:
-v1 Reports file names, errors and warnings (default).
-v2 Prints the file header and a detailed file summary.
-v3 Reports on each point in the file.

instance
file number
type

[No arguments]

Name of the AIM*Historian instance.

RTP file by number. If not used, all RTP files
are checked.
0 = RTP (default).
1 = RF.
2 = RM.
3 = RS.
Prints a usage synopsis.

The program begins with a prompt to confirm file modification.

3. Review the log file /opt/aim/inst/<instance>/rtpfix.log
Examples:
To repair the RTP file r570.fdb in hist01, run: rtpfix hist01 570
For a report on each point in the RTP file r570.fdb in hist01, run:
rtpfix -v3 hist01 570

To repair all RF files for hist01, run: rtpfix hist01 -t1

183

B0193YL Rev E

5. Troubleshooting

testhv
The console application testhv tests the communication with the legacy servers hsfetch (I/A),
hrfetch (I/A), histsrv (I/A), and ipchisti (I/A), and tests their ability to access AIM*Historian files.
By answering prompts, you can set up and send nearly every type of request message directed to
those servers, and display the server's responses.
In general, the program was intended to be an engineering debug tool. Setting up most request
messages requires intimate knowledge of functions internal to AIM*Historian. However, there
are some functions that may be useful for general troubleshooting, in particular those that simulate the data requests issued by the I/A Series Trend packages. This document describes only how
to use testhv for these message types.
Since testhv uses I/A Series IPC to communicate with the servers, the target servers may be anywhere on the same I/A Series node, and not necessarily on the same machine. While the program
can generally communicate with the legacy I/A Series Historian, all Historian message types may
not be supported.
A prerequisite for running testhv is that servers on the target machine are running. To confirm
that the servers are operating:
1. Open a command window, change to the AIM*Historian program directory, and
display current AIM*Historian processes.
cd /opt/aim/bin
histps

2. If the servers are not running, enter the appropriate start commands as described in
Legacy Interface Servers on page 122.
The servers take about a minute or so to establish the IPC communication channels,
after which time they can be addressed by testhv.
The following sample procedure simulates a Trend data request as issued by the I/A Series Trend
package. As mentioned above, this is just one example of a large variety of tests that can be performed with testhv.

184

5. Troubleshooting

B0193YL Rev E

In all testhv prompts, the default is printed in brackets and is accepted by simply pressing the
return key. A single space clears a previous entry in any particular field.
cd /opt/aim/bin
testhv
h
hst0j1
s
s
m

(
(
(
(
(
(
(
(
(

location of AIM*Historian programs

run testhv
Select Historian
example for a historian instance
Select Server
s for hsfetch (I/A)
setup new message;
what follows is the request message contents:
= SMP_DATA, this is the request type for raw data

Message Type[] 2
flags[00]
Ret
rsp_size[0] Ret
pnt_id(34)[]
( either enter the point name here...
offset[]
( ...or the internal point number here.
oldtime {}[]
( enter the start of the range in the next two prompts:
Date?
( the date and time fields will accept
Time?
( any somewhat reasonable entry format
Is this a timespan request? [y] Ret
endtime {}[]
( enter the end of the range in the next two prompts:
Date?
Time?
tot_pts[0]
Ret
Send/Brief/Vbrief/Revise[]
( s will send the request message off to hsfetch (I/A) and then
( display the entire contents of all response messages,
( b will send the request, but print only the header of the last
( response message and the very last data item,
( v will send the request, and print the header of each response
( and the first data item in each response.
( r will NOT send the message, it goes back to the select menu.
( A request can be repeated by hitting Return enough times.
( Expect up to 101 data values in each response message.
( The number of response messages depends on the amount of data
( collected in the historian and the requested time span.

The other message type requested by the Trend package is the optimized or filtered data request
type 57 = SMP_DATA_T. For this request type, a nonzero number must be entered for tot_pts.
The Trend server hsfetch (I/A) subdivides the requested time span into (n-1) intervals of equal
length, and then returns no more than n values. The values returned are those whose time stamps
either match the calculated times exactly or are closest before those times.

185

B0193YL Rev E

5. Troubleshooting

testvar
The testvar program tests an AIM*Historian servers ability to connect to shared variables and to
collect simulated shared variables without the need of a fully configured I/A Series environment.
Multiple copies of the program can be run in order to simulate more than one point.
In Ramp mode, testvar creates an I/A Series floating-point shared variable and ramps its value up
and down between the values 0.0 and 10000.0. The value is changed once a second, using the
setval() function.
In Get mode, testvar continues to display the variable's current value.
In Del mode, the variable can be deleted when the test is completed.
To use the testvar program:
1. Open a Command Prompt window and run testvar without arguments to display a
usage synopsis.
Figure 5-3 shows the program being run on a Windows server.

Figure 5-3. testvar Usage Synopsis

186

5. Troubleshooting

B0193YL Rev E

2. Run the program in Ramp mode.

testvar Ramp variable_1

The example entry creates the shared variable variable_1 and continuously ramps the
value. If the variable already exists, the warning DUPLICATE is printed, but the
variable is still changed.
3. Open a second command prompt window and run testvar in Get mode.
testvar Get variable_1

The utility returns the variable changes (Figure 5-4).

Figure 5-4. Values Returned by testvar

4. Enter Ctrl+C at the keyboard, or use kill to terminate the program, depending on
whether it was run in the foreground or background.
5. Delete the shared variable after the test is complete.
testvar Del variable_1

6. Close the command prompt windows.

187

B0193YL Rev E

5. Troubleshooting

xrebuild
The program xrebuild is an AIM*Historian emergency utility that rebuilds cross-reference files
when there is a suspicion of database corruption. The cross-reference file is an essential instrument for locating the data by a given time stamp. You can specify that utility rebuild any of the
following cross-reference files:
rxref.fdb for raw sample files (r<n>.fdb)

rfxref.fdb for RTP samples reduced at the fast rate (rf<n>.fdb)

rmxref.fdb for RTP samples reduced at the medium rate (rm<n>.fdb)

rsxref.fdb for RTP samples reduced at the slow rate (rs<n>.fdb)

mxref.fdb and imxref.fdb for message files (m<n>.fdb).

For RTP cross-reference files, xrebuild examines the headers of all existing real-time data files
(r<n>.fdb) and transfers the search information to their appropriate entries in the rxref.fdb file.
Existing entries in the cross-reference file are preserved unless they contradict information found
in the actual data file headers. All RTP files in the directories /opt/aim/inst/<histname> and
/opt/aim/pbk/<histname>, and in all directories listed in the AIM*Historian configuration item
DBPATH are considered. RTP files not found are marked deleted in the cross-reference file.
xrebuild is a console application, executed from a command window. The present rxref.fdb file
should be left in the AIM*Historian instance, but xrebuild can also rebuild it from scratch if
necessary.
To use xrebuild:
1. Use AIM*Historian to turn the AIM*Historian instance off.
2. Run histarc to archive RTP files as necessary.
3. Back up the current cross-reference files (rxref.fdb, rfxref.fdb, rmxref.fdb, and
rsxref.fdb, mxref.fdb, and imxref.fdb) in the instance.
4. Exit all AIM*Historian GUIs.
5. Open the command window and change to the AIM*Historian program directory:
cd /opt/aim/bin

6. Run xrebuild specifying the AIM*Historian instance.

xrebuild <instance> [<type>]:
Where:
instance
type

[No arguments]

Name of the AIM*Historian instance.

0 = RTP files (default).
1 = Fast reduction files.
2 = Medium reduction files.
3 = Slow reduction files.
4 = Messages.
Prints a usage synopsis.

The program writes a log to the console, and then, if the restoration is successful, asks
if you want to commit the change.

188

5. Troubleshooting

B0193YL Rev E

Depending on the extent of the database corruption, the rebuild session may not always be successful. If the session fails because the starting times of consecutive RTP files are out of order, you
may have to decide which RTP files to delete to remedy the situation. To make the choice, use
histspy and examine the present rxref.fdb file as well as the headers of the RTP files in question.
In the event that the original cross-reference file is missing or in such poor condition that individual entries for deleted RTP files cannot be salvaged, the xrebuild program artificially generates
entries for those files to fulfill the requirement for monotonic time stamps in the file.
If, at a later time, a deleted file is restored from an archive and its cross-reference file entry does
not match the actual time stamp in the RTP file header, the conflict may interfere with the data
retrieval functions. To resolve the conflict, run xrebuild again after the RTP file is restored from
the archive. Matching time stamps in the cross-reference file versus the RTP file header can be
verified with histspy.

fh_sacego
This program is an unsupported utility and is used on AW51 systems only.
The fh_sacego program, which was created to fix a problem with Operator Action Journal, produces output in the same format as the original sacego program. fh_sacego can be invoked directly
from a cmdtool and supports the -m argument that causes System Monitor messages to be
printed instead of Operator Action Journal messages.
The -m argument is only available from the command line and not via the Operator Action Journal. Run fh_sacego without arguments for instructions.

Stub Library for Off-Platform Testing

The AIM*API library on non-I/A Series machines contains stub functions to allow programs on
non-I/A Series hosts to collect simulation values, that is, stub samples. On Windows, the library is
aimapi.dll. On Solaris, the library is libaimapi.so.
The library includes the readval() function, which retrieves the current value for an RTP, and the
readsta(), which retrieves the current status for an RTP. readval() returns 0.1, 0.2, 0.3, and so on.
readsta() always returns 0x0623, which represents Float value type.
These stub values are collected and written in the AIM*Historian database if you configure RTPs
for the default real time collector with the same name as the AIM*Historian instance on a
non-I/A Series machine. These values are of no use to a production system, but are useful when
testing the product and could have diagnostic uses.
By default, collectors of type IA_RT_COLLECTOR on non-I/A Series machines do not collect
stub samples. To enable the collection of stub values:
1. Set the ENABLE_STUBS attribute in the Instance component to YES.
2. When the system goes into production, set the component attribute to NO.

189

B0193YL Rev E

5. Troubleshooting

Tailoring Default Collector Stub Values

Below is the definition of a file that can be created to adjust how the readval() stub on a nonI/A Series machine generates values. This can be useful for tasks such as testing negative numbers,
very small or large increments, or very large numbers.
! CAUTION
This is an unsupported feature, subject to change without notice.
The file readval_stub_params.dat is read from the AIM*AT program directory (/opt/aim/bin).
Comment lines ('#' in first column) and newline-only lines are ignored. The line format is:
<Keyword> [=] <Value>
Where:
Keyword can be INIT, BUMP, MAX, or MIN (all characters are forced to uppercase
before checking).
= is optional.
Value is a floating point value. Each value can be any valid floating point value, except
that MAX must be greater than or equal to MIN.
# Sample readval_stub_params.dat
# Parameters for exercising negative values, starting with
# downward ramp.
INIT = -100.0
BUMP = -1.0
MAX = 100.0
MIN = -1000.0

Troubleshooting Procedures
This section contains AIM*Historian troubleshooting procedures in a series of tables that list the
possible causes and remedial actions for the following problems:
There are no RTP values inserted into the .fdb files (Table 5-3).
There are no event messages inserted into the .fdb files (Table 5-4).
There are no RTP values or event messages inserted into the .fdb files (Table 5-5).
There is no TCP/IP connection between histreceive at the instance host and
histsend at the remote collector station (Table 5-6).

Configuration changes are not reflected in RTP Values or event messages at the
remote collector (Table 5-7).
AIM*Historian data did not appear in an I/A Series Trend display (Table 5-8).
I/A Series Trend displays show incorrect AIM*Historian data (Table 5-9).
There are unexplained program crashes, or the programs do not start (Table 5-10).

190

5. Troubleshooting

B0193YL Rev E

When instructed to execute histps:

On Solaris systems, run:
/opt/aim/bin/histps

On AW70s, run:
d:\opt\aim\bin\histps.bat

On other Windows NT systems:

Use the Windows NT Task Manager.

When instructed to check the historian.log file:
1. Run AIM*Historian Manager or histspy.
2. Select the instance.
3. Select viewing of the log file.
Alternatively, you can use a native tool to view the log file:

On Solaris systems:
/opt/aim/inst/historian.log

On Windows platforms:
d:\opt\aim\inst\historian.log

NOTE

On Windows NT systems, you may get a sharing violation when attempting to

view the log file. Copy the file and view the copy.

NOTE

If troubleshooting an I/O Gate Collector, reference the iogatecol program instead

of iacol in the following procedures. Each iogatecol program also writes diagnostic
messages to a log file (/opt/aim/inst/<instance>/<collector>.log).

NOTE

AIM*Historian forces the start time of the first sample file in an instance (r10.fdb)
to be 24 hours prior to the first collected sample. This earlier start time ensures that
samples are not lost because of incorrect time stamp configuration in the instance
and remote collectors.

191

B0193YL Rev E

5. Troubleshooting

No RTP Values Inserted in .fdb Files

Table 5-3. No RTP Values Inserted in .fdb Files

Possible Causes
The collector program (iacol or
iogatecol) is not running.

AIM*API not running.

There are no RTPs configured for
the collector.

The points (specified by the

NAMEINCOL attribute for RTPs)
do not exist in the I/A Series system
accessible from the remote collector
host.
The RTP deltas are too large.
The RTP scan frequencies are
too large.

The RTPs are off.

192

Action
At the collector station, execute histps and see if iacol
(or iogatecol) appears in the list.
To verify that the collector process is running for a
particular instance, examine the process ID number in the
text file: iacol_<inst>_<collector>_pid.dat or
iogatecol_<inst>_
<collector>_pid.dat in the /opt/aim/bin/pid directory, and
check if it appears in the histps output.
Automatic collector startup can be configured by setting the
collectors CSTARTONBOOT attribute to YES.
Startup and shutdown of the collector from the
AIM*Historian Manager is also supported.
If the collector specifies an AIM*Historian instance that
does not exist or a collector that is not configured in the
instance, it logs an error message to historian.log and then
exits.
If there is insufficient free disk space to continue running,
the collector logs an error message to the historian.log file
and exits.
At the collector station, execute histps and verify that the
AIM*API processes appear in the list.
At the instance host system, configure RTPs for
the collector. For each RTP, specify the attribute
COLLECTOR with the collector name. The collector
STATION component must already be configured for
the instance.
Create the points in the I/A Series system.

Specify smaller deltas, if necessary.

Specify smaller scan frequencies, if necessary.
Values are always collected at the RTP fast frequency.
Values are stored at the currently selected frequency, either
the fast or slow rate (fast rate, by default).
Turn the RTPs on using a control group,
fh_GroupControl(), or fh_RTPControl(), or by changing
the RSTRTSTATE attribute to ON and restarting the
instance.

5. Troubleshooting

B0193YL Rev E

Table 5-3. No RTP Values Inserted in .fdb Files (Continued)

Possible Causes

Action

The RTPs are deleted.

The RTPs are not changing value.
RTP values are collected, but with
the wrong time stamps.
Other

Undelete the RTPs.

May not be a problem.
See Note on Time Stamps on page 266 in Appendix E
AIM*Historian Component Attributes.
See Table 5-5.

No Event Messages Inserted in .fdb Files

Table 5-4. No Event Messages Inserted in .fdb Files

Possible Causes

Action

The event messages are not

configured for the instance.
The ipchisti program is not running.

Use messages.inp to configure event messages

(see Configuration Using Input Text Files on page 64).
At the machine where the collector resides, execute histps.
If ipchisti is not in the list, use the start_server command
as described in Legacy Interface Servers on page 122 to
start ipchisti and the legacy servers.
Start Message Manager per the product documentation.
See Table 5-5.

Message Manager is not running.

Other

No RTP Values or Event Messages Inserted in .fdb Files

Table 5-5. No RTP Values or Event Messages Inserted in .fdb Files

Possible Causes

Action

There is no disk space available.

Use AIM*Historian Manager to check the file space available

or use a native tool to check disk free space.
If histreceive is unable to insert updates because of lack of space,
it logs a message and closes the connection with histsend. When
space is available, histreceive reconnects to histsend.
See Table 5-6.

There is no TCP/IP connection

between histreceive at the
instance machine and histsend at
the remote collector.

193

B0193YL Rev E

5. Troubleshooting

No TCP/IP Connection to Remote Collector

Table 5-6. No TCP/IP Connection Between histreceive and histsend
at the Remote Collector

Possible Causes

Action

The collector configuration does

not correctly identify the hostname
of the collector machine.

Check the HOSTNAME attribute of the collector using

the AIM*Historian Configurator (see Collector Stations
on page 68). The name must match the hostname entered
during installation of the AIM*AT software on the collector
machine.
If the names do not match, stop the histreceive process
running on the instance machine, change the collector
HOSTNAME attribute using the AIM*Historian
Configurator, and restart the AIM*Histroian programs.
Make sure that the server connection broadcast feature is
enabled at the instance machine. See Configuring Server
Connections for Wizard Browsing on page 19 for
information on enabling broadcasts.
If broadcast is not enabled, add the collector machine
hostname to the an_init.cfg file on the instance host.
Map the collector hostname to the TCP/IP address in
the hosts file on the instance machine.
Ensure that AIM*API is operating on both the instance
and collector machines.
The histreceive process is not running. Switch to the
Collector page and turn the collector ON, or switch to
the Instance page and turn the instance ON.
Check the collector configuration to see if Start on reboot
is set.
Make sure AIM*API is running on the collector machine.
The histsend (parent) program is not running on the
collector machine. It is started at reboot by histstart. It is
also started by histreceive after histreceive is unable to
connect for 60 seconds (the AIM*API server must be
running). The histsend parent process then spawns a child
process for the specific instance.
At the instance machine, configure the collectors
COLPORT attribute. At the remote collector machine,
specify the COLPORT in the [AISNET] section of
an_init.tcp file.
Refer to the COLPORT description in Table E-5 in
Appendix E AIM*Historian Component Attributes.
Stop the remote collector programs and delete the remote
collector instance directory. Restart the remote collector
programs. histsend copies and implements the new
configuration files.

The histreceive program could not

resolve the IP address of the
collector machine.

The Communications page in the

AIM*Historian Manager shows the
collector Connection State of OFF.

The histsend program has not

started properly.

The default port (44444) or the

configured port was already in use
by another application.

The histsend program does not see a

newly added collector in its .cfg
files.

194

5. Troubleshooting

B0193YL Rev E

Table 5-6. No TCP/IP Connection Between histreceive and histsend

at the Remote Collector (Continued)

Possible Causes
No second Ethernet card installed.

Network problem.

Action
Install the card following the instructions in Ethernet
Controller Upgrade Kit or SCSI Host Adapter Upgrade Kit for
Model AP50, AW50, and WP50 Processors (B0193PT).
Resolve the network problem.

AIM*Historian Client Cannot Connect with Server

The Error Message Server Named Unknown is issued when the client applications such as
AIM*Historian Manager and AIM*Historian Configurator fail to connect with the target server.
Table 5-7. Error Message Server Name Unknown

Possible Causes
Server cannot be reached by broadcast (because it is disabled or there is
an intervening router between the
client and the target server), and the
server hostname is not configured in
the an_init.cfg file on the client host.

Action
Make sure that the server connection broadcast feature is
enabled at the client machine. See Configuring Server
Connections for Wizard Browsing on page 19 for
information on enabling broadcasts.
If broadcast is not enabled, add the server hostname to
the an_init.cfg file on the client host.
Ensure that AIM*API is operating on both the instance
and collector machines.

AIM*Historian Data Not in Trend Display

Table 5-8. Failure to Display AIM*Historian Data in Trend Display

Possible Causes

Action

The AIM*Historian instance

name is not found in the /etc/histln
file on the machine.
Servers histsrv, hsfetch, and hrfetch
are not running.

Verify that the histlnbc program is running. It is run when

AIM*API is started. If a new instance is created, it may take
up to a minute before histlnbc adds the instance to the file.
Refer to Table 5-4.
Manually starting an AIM*Historian instance using histmgr
does NOT start the histsrv, hsfetch, hrfetch, and ipchisti
server programs. If one or more AIM*Historian instances
are configured to start automatically at reboot, the system
DOES start those servers. Legacy Interface Servers on
page 122.
Run AIM*Historian Manager, select the instance from the
list, and observe the state of the instance on the display. See
Chapter 3 AIM*Historian Operation.

The AIM*Historian instance is

not running (needed to collect
data, but not required to view data
that has been collected).

195

B0193YL Rev E

5. Troubleshooting

Table 5-8. Failure to Display AIM*Historian Data in Trend Display (Continued)

Possible Causes
The AIM*API (apimgr.exe) and
AIM*API server (apisvr.exe) are
not running.

Data for the desired RTP for the

desired time range has not been
collected by AIM*Historian.

If the instance host is an AW70,

the Windows NT and I/A Series
times are not in sync.

196

Action
On Solaris systems:
Run histps to check for the processes. If the servers are not
running, start them with aisstart.
On Windows NT systems:
Use the Windows NT Task Manager to check for the
processes. If the servers are not running, start them using the
AIM*API Control Panel applet.
To check if the AIM*Historian instance has collected values:
Run histspy and select the AIM*Historian instance.
Select RTP Database and the most recent r<n>.fdb file
(for example, r30.fdb if you have three files: r10.fdb,
r20.fdb, and r30.fdb).
Double-click the point index for an RTP that you know
should be changing and observe data values in the file.
To check that additional values are being collected:
Close the .fdb file and wait until you know the RTP has
changed by a significant amount.
Reselect the .fdb file and observe additional value in the file.
If values are not being collected, see Table 5-3.
See Appendix C, Additional AIM*Historian Topics, in
the AIM*AT Installation Guide (B0193YM).

5. Troubleshooting

B0193YL Rev E

Incorrect AIM*Historian Data in Trend Display

Table 5-9. Incorrect AIM*Historian Data in Trend Display

Possible Causes

Action

The Trend line is either too high or

too low. The RTP HIRANGE and
LORANGE attributes have inappropriate values.
Trends are in the form of unexpected ramp lines. Your system is
using the stub version of the
AIM*API library (libaimapi.so on
Solaris systems or aimapi.dll on
Windows NT systems) whose readval() API returns a steadily increasing float value (0.1, 0.2, 0.3, and so
on). This situation is probably the
result of a manual copy of the
library.
If the instance host is an AW70, the
Windows NT and I/A Series times
are not in sync.
Trend values have the wrong time
stamps by one or more hours.

Modify the RTP HIRANGE and LORANGE attributes to

have values which reflect the actual range of values for the
RTP.
Reinstall the appropriate library.

See Appendix B, Additional AIM*Historian Topics,

in the AIM*AT Installation Guide (B0193YM).
See Note on Time Stamps on page 266.

197

B0193YL Rev E

5. Troubleshooting

Unexplained Program Crashes; Inability to Start Programs

Table 5-10. Unexplained Crashes; Inability to Start Programs

Possible Causes
The collector (iacol or iogatecol) has
RTPs of the type String whose size
attribute is not large enough to hold
the RTPs largest string value plus a
null terminator.
Insufficient memory available.

198

Action
Configure the RTP SIZE attribute to be equal to the
longest possible string plus one byte for the null
termination.

Check the available memory on the instance host. The

recommended amount of available memory to run
AIM*API with a single AIM*Historian instance with
default attributes (that is, with MAXPTS = 5000,
ARCHSIZE = 10000000) is 90 MB. Instances with higher
sizing attributes will require more space. This is in addition
to memory required to support other applications which
may be running on the station.
Run vmstat to check the amount of available memory
on a UNIX station. See Sample vmstat Output below.
Check the amount listed in column #4, swap. This should
be done without AIM*API, AIM*Historian instance, or
Legacy Servers running on the station.
Add Swap space memory as needed using the procedure
in Adding Swap Space.

5. Troubleshooting

B0193YL Rev E

Sample vmstat Output

The following is example vmstat output on an I/A Series AW51. The total available memory is
91.204 MB.
P7AW03#
P7AW03# vmstat 3
procs
r b w

memory

page

disk

faults

swap free re mf pi po fr de sr m0 m1 m2 m3

0 0 0 48540 9260

5 118 58 59 114 0 37 1 1 0 0

in sy

cpu

cs us sy id

89 677 342 12 14 73

0 0 0 91204 20764

4 0 0 0 0 0 0 0 0 0

14 225 236 0 0 100

0 0 0 91204 20764

0 0 0 0 0 0 0 0 0 0

17 227 238 0 0 100

Adding Swap Space

If there is not enough memory available, you can add physical memory or virtual memory
(swap space).
To add swap space on a Solaris system:
1. Open a command window and create a swap file by entering:
<NN>m /opt/<swapfile>
where NN is the size of the swap file in megabytes and swapfile is the name of the file.
mkfile

2. Enter the following:

swap -a /opt/<swapfile>

3. Modify /etc/vfstab to add the following line:

/opt/<swapfile>

swap

no

199

B0193YL Rev E

200

5. Troubleshooting

Appendix A. Error Codes

This appendix lists AIM*Historian error codes.
The tables in this appendix describe the codes returned by AIM*API calls to access
AIM*Historian as defined in the aimhistorian.h header file.

Error Codes Returned by AIM*API

Table A-1 and Table A-2 list the AIM*API function returns and errors codes respectively when
there is a problem accessing AIM*Historian.
Table A-1. AIM*API Function Returns

Return
0
-1

Name
FH_NO_ERROR
FH_ERROR

Table A-2. AIM*API Error Codes

Error Code
-1
-2
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18

Name
FH_ACT_WHEN_COMP_CREATED
FH_AVAIL_SATELLITE
FH_AVAIL_COLLECTOR
FH_CANNOT_ADDTO_CTRLGROUP
FH_CANNOT_ADDTO_REDUCGROUP
FH_CANNOT_CREATE_CTRLGROUP
FH_CANNOT_CREATE_HIST
FH_CANNOT_CREATE_MSGNAME
FH_CANNOT_CREATE_POINT
FH_CANNOT_MAP_AIMHIST_FILE
FH_CANNOT_MAP_MSG_FILE
FH_CANNOT_MAP_MSG_OFFSET
FH_CANNOT_MAP_MSG_OFFSETNI
FH_CANNOT_MAP_RFDB_FILE
FH_CANNOT_MAP_RTP_FILE
FH_CANNOT_MAP_RTP_NI_FILE
FH_CANNOT_MAP_TRKKEY_FILE
FH_CANNOT_MODIFY_CTRLGROUP
FH_CANNOT_MODIFY_POINT
201

B0193YL Rev E

Appendix A. Error Codes

Table A-2. AIM*API Error Codes (Continued)

Error Code
-19
-20
-21
-22
-23
-24
-25
-25
-26
-27
-28
-29
-30
-31
-32
-33
-34
-35
-36
-37
-38
-39
-40
-41
-42
-43
-44
-45
-46
-47
-48
-48
-49
-50
-51
-52
-52
-53
202

Name
FH_CANNOT_MODIFY_MSG
FH_CANNOT_MODIFY_REDUCGROUP
FH_CANNOT_READ_CFGFILES
FH_CANNOT_START_SESSION
FH_CANNOT_VALIDATE_MSG
FH_CANNOT_VALIDATE_POINT
FH_CANNOT_VALIDATE_SATELLITE/* OLD def */
FH_CANNOT_VALIDATE_COLLECTOR/* NEW def */
FH_CFG_MSGDEFS_CHANGED
FH_CFG_POINTS_CHANGED
FH_COMP_NOT_FOUND
FH_CTRLGROUP_DOESNOT_EXIST
FH_CTRLGROUP_EXISTS
FH_CTRLGROUP_IS_FULL
FH_CTRLGROUP_ISNOT_EMPTY
FH_DELETION_NOTALLOWED
FH_DEL_POINTS_CHANGED
FH_INV_ACTION
FH_INV_ARCH_SIZE
FH_INV_ATTRIBUTE
FH_INV_COLMETHOD
FH_INV_COMPONENT
FH_INV_DATATYPE
FH_INV_DST_OPTION
FH_INV_END_SESSION_OPTION
FH_INV_FIELD_NUMBER
FH_INV_HISTORIAN
FH_INV_IASTATION_OPTION
FH_INV_IATIME_OPTION
FH_INV_MAX_RT_POINTS
FH_INV_MAX_CGROUPS
FH_INV_MAXCGENTS
FH_INV_MAX_LOG
FH_INV_MAX_MSGDEFS
FH_INV_MAX_MSGFILE_SIZE
FH_INV_MAX_RGROUPS
FH_INV_MAXRGENTS
FH_INV_MAX_TIME_BTWN_SAMPLES

Appendix A. Error Codes

B0193YL Rev E

Table A-2. AIM*API Error Codes (Continued)

Error Code
-54
-55
-56
-57
-58
-59
-60
-61
-62
-63
-64
-65
-66
-67
-67
-68
-69
-70
-71
-72
-73
-74
-75
-76
-77
-78
-79
-80
-81
-82
-83
-84
-84
-85
-85
-86
-87
-88

Name
FH_INV_MAX_TRACKKEY
FH_INV_MSG_FIELD_POSITIONS
FH_INV_MSG_GROUP
FH_INV_MSG_KEY
FH_INV_MSG_NAME
FH_INV_MSG_RETENTION_TIME
FH_INV_NUM_OF_ELEMENTS
FH_INV_ODBC_OPTION
FH_INV_OPER
FH_INV_OPER_TYPE
FH_INV_OPSYS_TYPE
FH_INV_POINT
FH_INV_RT_RETENTION_TIME
FH_INV_SATELLITE /* OLD def */
FH_INV_COLLECTOR /* NEW def */
FH_INV_START_STATE
FH_INV_STATION_TYPE
FH_INV_TAG_TYPE
FH_INV_THRESHOLD
FH_INV_TIME_ZONE
FH_INV_TRACE_FLAG
FH_INV_TRACKKEY
FH_INV_TRACK_NAME
FH_INV_UNIT
FH_INV_UPDATEMSGS_OPTION
FH_INV_VALUE
FH_INV_VALUE_LENGTH
FH_MAX_ARCHIZE_SIZE_CHANGED
FH_MAX_MSGFILE_SIZE_CHANGED
FH_MAX_MSGDEFS_CHANGED
FH_MAX_MSGDEF_IS_REACHED
FH_MAX_CGROUPS_CHANGED
FH_MAXCGENTS_CHANGED
FH_MAX_RGROUPS_CHANGED
FH_MAXRGENTS_CHANGED
FH_MAX_TRACKKEY_CHANGED
FH_MAX_LOG_CHANGED
FH_MSGDEF_DATABASE_FULL
203

B0193YL Rev E

Appendix A. Error Codes

Table A-2. AIM*API Error Codes (Continued)

Error Code
-89
-90
-91
-92
-93
-94
-95
-96
-97
-98
-99
-100
-101
-102
-103
-104
-105
-106
-107
-108
-109
-110
-111
-112
-113
-114
-115
-116
-117
-118
-119
-120
-121
-122
-123
-124
-125
-126
204

Name
FH_MSGGROUP_EXISTS
FH_MSGGROUP_DOESNOT_EXIST
FH_MSGGROUP_ISNOT_EMPTY
FH_MSGKEY_EXISTS
FH_MSGKEY_DOESNOT_EXIST
FH_MSGNAME_EXISTS
FH_MSGNAME_DOESNOT_EXIST
FH_NEED_TO_RESTART_HISTORIAN
FH_NO_AVAIL_OPERATIONS
FH_NO_HISTORIAN
FH_NO_SESSION
FH_NO_TRIGGER
FH_NON_UNIQUE_HIST
FH_NON_UNIQUE_MSGKEY
FH_NUM_POINTS_CHANGED
FH_NUMELMS_FOR_ODBC_OPTION
FH_OPERATION_DOESNOT_EXIST
FH_OPERATION_EXISTS
FH_OPERATION_NOTALLOWED
FH_POINT_EXISTS
FH_POINT_IN_CTRLRED_GROUP
FH_READONLY_SESSION
FH_REDUCGROUP_DOESNOT_EXIST
FH_REDUCGROUP_EXISTS
FH_REDUCGROUP_IS_FULL
FH_REDUCGROUP_ISNOT_EMPTY
FH_RTDATABASE_FULL
FH_SESSION_IN_USE
FH_SRC_HIST_DOESNOT_EXIST
FH_STATION_DOESNOT_EXIST
FH_STATION_EXISTS
FH_TRACK_NAME_DOESNOT_EXIST
FH_TRACK_NAME_EXISTS
FH_TRACKKEY_DATABASE_FULL
FH_TRIGGER_TAGTYPE_EXISTS
FH_UNDEL_POINTS_CHANGED
FH_DELETED_POINT
FH_DATABASE_CORRUPTION

Appendix A. Error Codes

B0193YL Rev E

Table A-2. AIM*API Error Codes (Continued)

Error Code
-127
-128
-129
-130
-131
-132
-133
-134
-135
-136
-137
-138
-139
-141
-142
-143
-144
-145
-146
-147

Name
FH_INV_MDE_MODE
FH_CANNOT_GET_CURDIR
FH_INV_HISTORIAN_DIR
FH_INV_GROUP_TYPE
FH_INV_COLNAM
FH_INV_DIRECTION
FH_INV_NUMELEMS
FH_INV_TIME_INTERVAL
FH_TOO_MANY_REDUCTIONS
FH_INV_REDUCTION
FH_INV_TIMESTAMP
FH_RTP_IS_OFF
FH_CANNOT_CONNECT_TO_INSTANCE
FH_INVALID_TIME_CONFIG
FH_CIRC_FILE_FULL
FH_HISTRECEIVE_RUNNING
FH_DOTADDRESS_NOTALLOWED
FH_OBSOLETE_FUNCTION
FH_CANNOT_ACCESS_DBPATH_DIR
FH_INV_HOSTNAME

205

B0193YL Rev E

206

Appendix A. Error Codes

Appendix B. AIM*Historian Sample

Status and Quality
The appendix describes the status and quality words of an AIM*Historian real-time point
(RTP).
An AIM*Historian RTP status has the same format as the status of an I/A Series object, except
that AIM*Historian supports additional value types. The I/A Series Object Manager defines the
object status as a 16-bit word. AIM*Historian represents object status as a 32-bit integer, with bit
31 being the most significant bit (MSB).
Value types 1 to 10 are I/A Series value types. Values for each of the I/A Series value types 1, 2, 3,
5, 6, 8, 9, and 10 are contained within 4 bytes.
To properly interpret I/A Series values, you can use the typedefd union IAXVAL defined in
aimapi.h.
IAXVAL also contains a union member for an I/A Series string (value type 4), causing
sizeof(IAXVAL) to be greater than 4. Therefore, do not perform pointer arithmetic on a pointer
of type (IAXVAL*) when dealing with an array of four-byte values.
This appendix defines the RTP status word for points from I/A Series systems after Version 4.3.
NOTE

Status words from I/O Gate are formatted according to I/A Series Version 4.1, and
use only the Value Type and Bad/Disconnect/OK fields. All other fields are zeroed.

Status Definition for I/A Series Version 4.3 and Later

Table B-1 and the notes that follow it define the RTP status when the points are collected from
processes using I/A Series Version 4.3 and later.

3 to
0 (lsb)

Value Type

7 to 5

Change

OM Connect Status

Bad/Dis/Ok

10
Ack/uncond. init

11

00S

12

Shadow

13

Limited High

14

Limited Low

15

Error

Reserved

31 (msb)
to 16

Sec/Unsec

Table B-1. Status Definition with I/A Series Version 4.3 and Later

207

B0193YL Rev E

Appendix B. AIM*Historian Sample Status and Quality

Where:
Bits 0 to 3

The value type as described in RTP Value Types on page 209.

Non-I/A Series types (21 and greater) exceed the four-bit field allotted for
the value type. If you use any of these value types, you must retrieve the
value type from the RTP configuration using fh_Cfg() or fh_RTPDef() to
be sure of the value type.
For user-defined value types, the value type field is considered to be bits 0
to 7. For array type value types (21 to 31), the value type field is considered to be bits 0 to 4.

Bit 4

Change (setval) (1) / else (0)

Bits 5 to 7

Object Manager connect status:

0
1
2
3
4
6

208

No response
Being scanned
Disconnected
Deleted
Bad data type or unconnectable compound
Non-connectable parameter

Bit 8

The object is BAD (1), disconnected (1), or OK (0).

Bit 9

The parameter is secured (1) or unsecured (0).

Bit 10

Ack/uncond. init (1) or else (0).

Bit 11

The object is out of service (1) or in service (0).

Bit 12

The point is a shadow parameter (1) or not a shadow parameter (0).

Bit 13

The parameter is limited high (1) or not (0).

Bit 14

The parameter is limited low (1) or not (0).

Bit 15

There is an error condition upstream (1) or no upstream error

detected (0).

Bits 16 to 31

Reserved

Appendix B. AIM*Historian Sample Status and Quality

B0193YL Rev E

RTP Value Types

Table B-2 lists the RTP value types with the type numbers and sizes. The first ten types use
I/A Series value type numbers.
NOTE

When you specify an RTP value type (other than FILE), the size of the value is
fixed. The size of a given RTP value is not necessarily the same as that of the target
point in the DCS. For example, the size of the integer type RTP (FH_INTEGER,
2) is 4 bytes. This type is used to collect integer values from an I/A Series system.
Integers in I/A Series software (also referred to as Type 2) are only 2 bytes. Thus,
when collecting integer values from the I/A Series system, AIM*Historian stores
the 2-byte value in a 4-byte field. Likewise, when you write values to an I/A Series
system integer using a demand write RTP, you must limit the range of the value so
that it fits in a 2-byte field. The range for the integer value is 32768 to 32767.

Table B-2. RTP Value Types

Data Type
FH_CHAR
FH_INTEGER
FH_FLOAT
FH_BOOLEAN
FH_LONG
FH_SHORT
FH_INT_PACKED
FH_LONG_PACKED
FH_CHAR_ARRAY
FH_SHORT_ARRAY
FH_INTEGER_ARRAY
FH_LONG_ARRAY
FH_FLOAT_ARRAY
FH_DOUBLE_ARRAY
FH_UCHAR_ARRAY
FH_USHORT_ARRAY
FH_UINT_ARRAY
FH_ULONG_ARRAY

Number
1
2
3
5
6
8
9
10
21
22
23
24
25
26
27
28
29
30

Size
4 bytes
4 bytes
4 bytes
4 bytes
4 bytes
4 bytes
4 bytes
4 bytes
1 byte per element
2 bytes per element
4 bytes per element
4 bytes per element
4 bytes per element
8 bytes per element
1 byte per element
2 bytes per element
4 bytes per element
4 bytes per element

209

B0193YL Rev E

Appendix B. AIM*Historian Sample Status and Quality

Table B-2. RTP Value Types (Continued)

Data Type

210

Number

FH_STRING

31

FH_USER_TYPE_START

50

FH_FILE

51

FH_TIMESTAMP

52

Size
String. The size and number of
elements are user-defined. SIZE must be
large enough to hold the longest possible
string value including a null terminator.
For example, if the maximum configured
length of the string is 6 bytes, specify a
SIZE of 7. The value for strings
always occupies SIZE bytes in the
AIM*Historian database.
User-defined BLOB. The size is userdefined. The number of elements is 1.
File. The size is 1. The number of elements is the number of bytes in the file.
Time stamp. The size is 4. The number
of elements is 1.

Appendix B. AIM*Historian Sample Status and Quality

B0193YL Rev E

Quality Definition
Table B-3 and the notes that follow define the RTP Quality.

30

29

28

27 to 26

25

Peak

RTP Off

Collector Off

Reserved

Trigger Inaccessible

24 to 0 (lsb)

Reserved

31 (msb)
Minimum Peak

Table B-3. RTP Quality Definition with I/A Series Version 4.2 and Later

When an RTP is turned off, AIM*Historian writes a sample with the RTPs latest value, status
and quality, with bit 8 (Bad) set in the status word and bit 29 set in the quality word.
0X20000000 (bit 29 set): The RTP is turned off.
When the collector is turned off, AIM*Historian writes a sample for each RTP in the collector
with the RTPs latest value, status, and quality, with bit 8 (Bad) set in the status word and bit 28
set in the quality word. In the case of an ungraceful termination of the collector, these samples are
written on the subsequent startup of the collector.
(bit 28 set): The collector is turned off.
These actions mark the time ranges when an RTP is not being collected.
0X10000000

Bits 30 and 31 are used for peak detection:

0x40000000 (bit 30

set): Maximum detected in the data stream.

0xC000000 (bits 30 and 31set): The associated value is a Minimum.
The peak values are inserted into the data stream only if the instance is configured with
SCANPEAKS set to YES.
When an RTPs TRGCHANGE attribute is YES and its trigger RTP is not accessible, the
triggered RTP historizes a sample with bit 25 (Trigger Inaccessible) set in the quality word.
0x02000000 (bit 25 set): Trigger Inaccessible.

211

B0193YL Rev E

212

Appendix B. AIM*Historian Sample Status and Quality

Appendix C. AIM*Historian
Reduction Status and Quality
This appendix describes the status and quality returned by AIM*Historian reduction APIs.
The AIM*Historian reduction APIs fh_FdbReduction() and fh_FdbRedArray() return a
32-bit status and quality word, with bit 31 being the most significant bit.
The status contains a value type in the low order bits, which can be FH_FLOAT (3) or
FH_DOUBLE_ARRAY (26). In addition, one or more of the following values may be ORd into
the status, which are defined in aimhistorian.h and are listed from the header for reference:
/* Reduced value status definitions */
#define UNAVAIL

128

/* bit set means unavailable (not

enough good values) */

#define FH_OUT_OF_COLLECTED_RANGE

256

/* bit set means at least part of

interval was out of the collected
range of the RTP database */

#define FH_PARTIAL_INTERVAL

512

/* bit set means corresponding

reduced values are based on a
partial time interval */

Table C-1 and the notes that follow it define the status returned by these APIs.

UNAVAIL

6 to 5

4 to 0
(lsb)

Value Type

Reserved

FH_OUT_OF_COLLECTED_RANGE

Reserved

31 (msb)
to 10

FH_PARTIAL_INTERVAL

Table C-1. Status Returned by Reductions APIs

213

B0193YL Rev E

Appendix C. AIM*Historian Reduction Status and Quality

Bits 0 to 4 define the value type of the reduced data as shown in Table C-2.
Table C-2. Reduction Value Types

Name
FH_FLOAT
FH_DOUBLE_ARRAY

Number
3
26

Type Size
4 bytes
8 bytes

If the reduction request was for peaks, the quality word has bit 30 (the next to the most significant
bit) set. In addition, if the peak was a minimum, bit 31 (the most significant bit) is set. Otherwise, the quality is zero.

214

Appendix D. Data Reduction

Algorithms
This appendix lists the data reduction algorithms used in AIM*Historian, and discusses the
difference between data reduction in I/A Series Historian and the AIM*Historian, and offers
suggestions in configuring reduction intervals to balance data requirements and storage units.

Data Reduction Formulas

Table D-1 describes the data reduction formulas used in AIM*Historian. See Adding Reduction
Groups on page 50 for information on configuring data reduction groups.
Table D-1. Algorithms for Reducing Data

Operation

Algorithm

Summation(SUM)
Maximum(Max)
Minimum(Min)
Average (AVG)

Sum of samples in the reduction period.

Maximum sample value.
Minimum sample value.

(Average of samples2)

sum of samples**2
x**2 = -----------------------------------------------sample count

Variance
Standard deviation
(STDEV)
(Average of samples3)
(Average of samples4)
Coefficient of
Kurtosis
(KURT)

sum of samples
x = -------------------------------------sample count

s**2 = x**2 (x)**2

s**2
sum of samples**3
x**3 = -----------------------------------------------sample count
sum of samples**4
x**4 = -----------------------------------------------sample count
x**4 4*x**3*(x) + 6*x**2*(x)**2 3*(x)**4---------------------------------------------------------------------------------------------------------------------------(s**2)**2

Coefficient of Kurtosis is the measure of the peakedness or height of a

distribution, whereas the standard deviation measures the width of the
sample distribution. The specified algorithm measures the fourth
moment about the mean normalized by the standard deviation, or the
average of:
(((value - average)/standard deviation) ** 4) over the sample set.

215

B0193YL Rev E

Appendix D. Data Reduction Algorithms

Table D-1. Algorithms for Reducing Data (Continued)

Operation

Algorithm

Linearization
Current value (CUR)
Peaks (PEAKS)

Sample value at, or closest before, the time stamp for each time interval.
The current value of the RTP.
A peak is a significant change which is either:
Greater than both the previous and the next change values (A), or
Less than both the previous and the next change values (B).
If a peak does not change significantly for multiple scan periods, that is,
the peak is a plateau (C), the time stamp of the peak is calculated as the
mid-point between the first and last values of the plateau, and the value
for the peak is the last value of the plateau.
A
B
C Value

C Time Stamp

I/A Series and AIM*Historian Data Reduction

There are a number of differences between I/A Series Historians and AIM*Historian instances
for reduction support.
The I/A Series Historian supports the scheduled calculation and storage of reduced values for
points configured in reduction groups. Only those stored reduced values could be retrieved by an
application. Only points specifically configured to be in a reduction group had reduced values.
AIM*Historian supports three reduction file types (slow, medium, and fast) per instance, each
with a configurable reduction period, enabling you to specify the granularity of the values in the
reduction files. Unlike the I/A Series Historian, AIM*Historian reduces all RTPs except
non-numeric points and RTPs whose collection method is MDE.
AIM*Historian is not limited to returning values from the reduction files. Depending on the specific request, AIM*Historian may return data from the reduction files, calculate reduced values
from values in the reduction files, or calculate reduced values on-the-fly from sample data, as
needed to satisfy the request. For example, if reductions of ten minutes, one hour, and one day are
configured, and a request is made for eight-hour averages, the request can be satisfied by calculating values from the one-hour reduction files.
The I/A Series Historian supports cascaded reduction using reduction groups. AIM*Historian
does not explicitly support cascaded reduction; however, the ability to configure reduction intervals which are multiples of each other effectively provides the same support. In addition, the
fh_FdbRedArray() API supports reducing of array values.

216

Appendix D. Data Reduction Algorithms

B0193YL Rev E

Tied to the algorithm for performing reduction, reduction interval has a different meaning.
Whereas a single reduction interval covered the entire requested time range encompassing RTP
values in the I/A Series Historian case, the application using AIM*Historian has the option of
dividing up that range into multiple reduction intervals. Therefore, instead of getting back one
reduced value per point, operation and time range as is the case with the Historian, multiple
reduced values may be returned per point, operation and time range in the AIM*Historian case.
For AIM*Historian, reduction value calculations may include RTP values outside of the specified
time range at the end points for that range. The out-of-range condition is reflected in the status
bit returned with the reduction value. The status bit is defined in Appendix C AIM*Historian
Reduction Status and Quality. Bad status indicators include:
Unavailable

Points outside of collected range

Some points outside of requested time span, a partial reduction status.
In addition to the float data type, AIM*Historian reduces any other numeric data type.
Table D-2 lists AIM*Historian supported operations for on-the-fly reduction and reduction from
files.
Table D-2. Supported Reduction Operations

Operation
Average
Sum
Max
Min
Kurtosis
Standard deviation
Linearization
Current value
Peaks (HiLo)

On-the-Fly
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes

From Files
Yes
No
Yes
Yes
No
Yes
No
No
No

217

B0193YL Rev E

Appendix D. Data Reduction Algorithms

Configuring Reduction Intervals and Managing RTP

Data Files
This section provides tips on configuring reduction intervals and managing RTP data files for
best reduced data results.

Overview of RTP Data File Choice

When AIM*Historian receives a request for reduced data, it satisfies the request by reading intermediate reduced data from one of the reduction file types (slow, medium, or fast) or by performing a reduction on-the-fly from sample files. In addition, reductions on-the-fly are done as needed
to fill in reduced values before or after where reduction file data is available.

Time Stamps of Data in Reduction Files

Data stored in AIM*Historian reduction files have time stamps which are an even multiple of the
configured reduction interval. For example, if the configured interval is 86400 seconds (1 day),
the time stamps are for midnight of each day. If the configured interval is 3600 seconds (1 hour),
the time stamps are on the hour.
NOTE

The instance REDUCPHASE and REDPHASEUNIT attributes determine when

AIM*Historian generates and writes reduced values to the reduction files. They
have no effect on the reduction time stamp values themselves.

Algorithm for Choosing File Type to Satisfy a Reduction Request

Following is the algorithm used by AIM*Historian to choose the file type to satisfy a
reduction request:

If the instance USEREDFILES attribute is NO, AIM*Historian uses reduction onthe-fly from samples.
In all cases, for AIM*Historian to use a reduction file type, its configured interval
must be less than or equal to the requested reduction interval. For example, if a
request is for hourly averages, AIM*Historian can use data from reduction files configured for one hour or less.
If file types are configured and have data such that the start time and the request interval are even multiples of the reduction interval for the file type, and have the entire
requested time range covered, AIM*Historian uses the file type with the longest
reduction interval.

218

Appendix D. Data Reduction Algorithms

B0193YL Rev E

Otherwise, if file types are configured and have data such that the start time and the
request interval are even multiples of the reduction interval for the file type, and have
some of the requested time range covered, AIM*Historian uses the one with the most
data. If more than one file type have the same amount of data, AIM*Historian uses
the file type with the longest reduction interval.
Otherwise, if any medium or fast data is in the requested time range,
AIM*Historian uses the file type with the most data.
Otherwise, if any slow data is in the requested time range, AIM*Historian uses it.
Otherwise (no reduction data in range), AIM*Historian uses reduction on-the-fly
from samples.

Configuring Reduction Intervals

Following are hints for configuring reduction intervals according to the typical reduction requests
you anticipate for the AIM*Historian instance:
If the smallest reduction interval requested is hourly, configure the fast interval for
3600 seconds (1 hour).

If you request reductions of less than an hour, you can either configure a smaller fast
interval such as 1800 seconds (half hour) or 600 seconds (10 minutes), or keep sample
files available and allow reduction on-the-fly to handle all reduction requests with an
interval less than the configured fast interval.
For many systems, it may be sufficient to only configure a fast interval of 3600
seconds (1 hour). If you request frequent reductions of a much longer duration such
as yearly or weekly, you may want to configure an interval for daily reduction data. In
short, for more varied (by interval) and frequent reduction requests, configure more
reduction intervals. You are trading off storage space to hold the reduction data
against time to reduce the reduction data at request time.

219

B0193YL Rev E

Appendix D. Data Reduction Algorithms

Use of Sample Files

Certain reduction requests require the use of sample files (refer to Table D-2 Supported Reduction Operations). If you need to make such reduction requests, be sure to keep sample files available, either in the original instance directory or in an alternate directory specified by the
DBPATH attribute for the instance.

Examples
In all cases, AIM*Historian uses reduction on-the-fly from samples to generate reduced values
before and/or after where there is data from reduction files. The following are examples of how
AIM*Historian satisfies requests for reduced data:

The instance has no reduction data for the requested time range. AIM*Historian uses
on-the-fly reduction from sample files.
For an instance configured with a fast interval of 3600 seconds (one hour) only, all
reduction requests with interval less than 3600 are satisfied by reduction on-the-fly
from samples. All reduction requests of one hour or greater use data from the fast files.
For an instance configured with a fast interval of 10 minutes and medium interval of
one hour, a reduction request with interval 90 minutes uses the fast files (even though
the medium interval is less than or equal to the request interval, the request interval is
not an even multiple of 1 hour). The fast files are used for better accuracy. If, however, there is no fast data, the medium data will be used. A reduction request with
intervals of one hour uses the medium files (one hour is an even multiple of both the
fast and medium intervals), but the medium data is used because it is just as accurate
and takes less time to process.
For an instance configured with 1 day (slow), 1 hour (medium), and 6 minutes (fast)
reduction intervals, with indicated percentages of the request time range with data, X
in Table D-3 marks the file type AIM*Historian uses to generate the reduced values
for each indicated start time.
In Table D-3, since there is NO reduction data in the request range,
AIM*Historian always uses the raw samples to perform reduction on-the-fly to
satisfy the request, regardless of the start time.
Table D-3. Selection of Sample Files for a Reduction Request

File Type
Slow
Medium
Fast
Sample

220

Configured
Reduction
Interval

Percent of
Request
Range with
Data

86400
3600
360
N/A

0
0
0
> 0%

Start Time
12:00 a.m.

Start Time
1:00 a.m.

Start Time
1:12 a.m.

Appendix D. Data Reduction Algorithms

B0193YL Rev E

In Table D-4, each configured reduction interval has data for the whole request range.
For requests starting with 12 a.m., 1 a.m., and 1:12 a.m., AIM*Historian uses slow,
medium, and fast reduction data, respectively, to satisfy the requests. X in Table D-4
marks the file type AIM*Historian uses to generate the reduced values for each indicated start time.
Table D-4. Selection of Reduced Data Files for a Reduction Request

File Type
Slow
Medium
Fast
Sample

Configured
Reduction
Interval

Percent of
Request
Range with
Data

86400
100
3600
100
360
100
Not applicable

Start Time
12:00 a.m.

Start Time
1:00 a.m.

Start Time
1:12 a.m.

X
X
X

In Table D-5, each configured reduction interval has data for the whole request range,
except slow, which only has 60% of the request range covered. For requests starting
with 12:00 a.m., 1:00 a.m., and 1:12 a.m., AIM*Historian uses medium, and
medium and fast reduction data, respectively, to satisfy the requests. X in Table D-5
marks the file type AIM*Historian uses to generate the reduced values for each indicated start time.
Table D-5. Selection of Medium and Fast Reduction Files for a Reduction Request

File Type
Slow
Medium
Fast
Sample

Configured
Reduction
Interval

Percent of
Request
Range with
Data

86400
60
3600
100
360
100
Not applicable

Start Time
12:00 a.m.
X

Start Time
1:00 a.m.

Start Time
1:12 a.m.

X
X

How Long to Keep Data Files

On a typical system, reduction requests for older data will tend to be for longer intervals. Depending on your needs, you could choose to remove old sample files and the faster reduction files.
However, you have the flexibility of keeping or removing any file types you wish, whenever you
wish.

221

B0193YL Rev E

222

Appendix D. Data Reduction Algorithms

Appendix E. AIM*Historian
Component Attributes
This appendix describes the attributes of each AIM*Historian component.
This appendix documents seven AIM*Historian components with the following presentation for
each component:

A description of the component functions

A How To section listing configuration functions by attribute
A table of attribute definitions including default values and supported
configuration actions. Configuration actions that are supported only under certain
conditions are noted.
The attribute definitions give the maximum number of characters in string attribute values
followed by a #define of the form <xxx>_LEN in parentheses such as (FH_TAG_LEN). Read the
following note before programming an application.
NOTE

In the description column of the attribute tables, #defines of the form <xxx>_LEN
are used to indicate the maximum number of characters in string attribute values.
The <xxx>_LEN #defines do not account for a null terminator. When programming an application using the fh_Cfg() API, use the <xxx>_NSIZ #defines, which
do account for a null terminator.
Some attributes, such as put, are specified with the ASCII representation of an integer value such
as 0, then returned (that is, get) with a descriptive string such as NO. For these attributes, three
sets of values are given:
The aimhistorian.h #define for the integer value such as FH_NO. Application
programmers, see note below. Others can ignore the #define value.

The integer value, such as 0.

The descriptive string, such as NO.
NOTE

The aimhistorian.h header file also has #defines for the descriptive strings. For
example, insert A_ in FH_NO to get FH_A_NO. The FH_A_NO argument
represents the string NO. These ASCII versions of #define names are omitted for
conciseness in the tables; however, you can easily derive these #define names as
shown for FH_NO and FH_A_NO.

223

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-1 lists AIM*Historian defined components.

Table E-1. AIM*Historian Components

#define

String

FH_COMP_SESSION
FH_COMP_AIMHIST
FH_COMP_STATION
FH_COMP_POINT
FH_COMP_MSG
FH_COMP_CGROUP
FH_COMP_RGROUP
FH_COMP_FOXHIST

SESSION
AIMHIST
STATION
POINT
MSG
CGROUP
RGROUP
FOXHIST

Description
Configuration session
AIM*Historian instance
Collector station
Real-Time Point (RTP)
Event Message
Control Group
Reduction Group
AIM*Historian Instance
(for backward compatibility)

AIM*Historian defines the actions listed in Table E-2.

Table E-2. AIM*Historian Defined Actions

#define
FH_ACT_CREATE
FH_ACT_GETQTY
FH_ACT_GET
FH_ACT_PUT
FH_ACT_MOD
FH_ACT_DEL
FH_ACT_UNDEL

224

String
CREATE
GETQTY
GET
PUT
MOD
DEL
UNDEL

Description
Create
Get quantity
Get value
Put value
Modify value
Delete
Undelete

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Session Component
AIM*Historian instances are configured using a session, which can be either read-only or
read/write. A session can be opened, saved, restarted, committed, or canceled.

Session Component How To

Identify a Session

NAME

Session name

SESKEY

Session key

Retrieve the State of a Session

SESSTAT

Session state

Session Attribute Descriptions

Table E-3 describes the attributes of the AIM*Historian Session component.
Table E-3. AIM*Historian Session Attributes

Attribute
NAME

SESKEY

SESSTAT

Description
Session name of up to 10 (FH_HIST_LEN) characters. The session name is the
name of the AIM*Historian instance to which the session is established.
Default: None
Actions: CREATE GETQTY GET
Session key of up to 48 (FH_SESSION_LEN) characters. Changing this key allows
you to protect a saved session. Typically, SESKEY is the name of the AIM*Historian instance; this is how the AIM*Historian Configurator uses SESKEY.
Default: Instance name
Actions: GET PUT MOD DEL
Session state. 0 = not modified, 1 = modified (at least one successful operation to
change the configuration).
Default: None
Actions: GET

225

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Instance Component
AIM*Historian is used to historize real-time data and Event messages. You can create and configure an AIM*Historian using one of three methods:

AIM*Historian Configurator
Batch configuration using a configuration input text file (<instance name>.inp)

AIM*API application making calls to the fh_Cfg() API.

Instance Component How To

Identify an Instance

NAME

Instance name

FHDESC

Instance descriptor

Specify Database File Management Information

ARCHSIZE

Maximum size of an RTP or Event message database file

MSGFILE

Maximum size of the Event message configuration file

RTTIME

Maximum time of an RTP database file

DBPATH

Path of database directories

COMPRESS

Enable database file compression

Specify Other Maximums

MAXPTS

Maximum number of RTPs

MSGDEFS

Maximum number of message definitions

MAXRGENTS

Maximum number of entries per reduction group

MAXCGENTS

Maximum number of entries per control group

TRACKKEY

Maximum number of track keys

Specify Reduction Parameters

REDUCLEVEL

Reduction level

PCTVALID

Reduction percent valid

REDUCPHASE

Reduction phase offset from even time base

REDPHASEUNIT
Reduction phase offset units

226

Appendix E. AIM*Historian Component Attributes

REDFASTINT

Fast reduction interval

REDFASTUNIT

Fast reduction interval units

REDMEDINT

Medium reduction interval

REDMEDUNIT

Medium reduction interval units

REDSLOWINT

Slow reduction interval

REDSLOWUNIT

Slow reduction interval units

SCANPEAKS

Collect peaks for RTP values

USEREDFILES

Specify use of reduction data files for reduction

B0193YL Rev E

Retrieve Current Number of Configured RTPs

CFGPTS

Current number of configured RTPs

Retrieve Maximum RTPs per Server

MXSRVPTS

Naming RTPs per server

Specify Time Handling

IATIME

I/A Series time vs UTC time

DST

Specify Daylight Savings Time

Specify Troubleshooting Information

RTTRACE

Real-time server trace

ENABLE_STUBS

Collection of simulation values on an off-platform collector

Specify LRC Calculation for Event Messages

LRCCALC

Specify LRC calculation for Event messages

Create an Instance Like an Existing Instance

LIKE

Replicate an instance

227

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Instance Attribute Descriptions

Table E-4 describes attributes of the AIM*Historian instance component.
Table E-4. AIM*Historian Instance Component Attributes

Attribute
NAME

228

Description
Instance Name. An AIM*Historian instance that is to be accessed by
I/A Series applications for Trends and other uses must have exactly six
lowercase alphanumeric characters in its name. The AIM*Historian
Configurator forces AIM*Historian instance names to be six characters
to ensure I/A Series accessibility to the instances.
An AIM*Historian instance name is unique within the computer on
which it is installed, but AIM*Historian instances on different
computers can have the same name.
The histln, histlns, and histlocs files in the etc directory are automatically updated by the histlnbc server to reflect the creation and deletion of
AIM*Historian instances, with a lag time of up to about one minute.
These files inform the system of available AIM*Historian instances and
I/A Series Legacy Historians.
Although AIM*Historian instances on different computers can have
the same name, if those different computers are on the same I/A Series
network, and two or more AIM*Historian instances or I/A Series
Historians have the same name, only one of them can run its I/A Series
Historian servers (histsrv, hrfetch, hsfetch, ipchisti). Any attempt to start
another set of servers fails. For this reason, you may want to be sure all
your AIM*Historian instance names are unique.
Do not use aimrtp; this instance name is reserved for internal use.
If interoperation with existing I/A Series interfaces is not required, the
AIM*Historian instance name can be up to ten alphanumeric characters.
Default: None
Actions: CREATE GETQTY GET
Example: hist01

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
ARCHSIZE

CFGPTS

Description
Archive Size. Maximum file size in bytes of an RTP or Event message
database file including:
RTP samples (r<n>.fdb)
Event messages (m<n>.fdb)
Event message indexes (im<n>.fdb)
Reduced RTP data (rf<n>.fdb, rm<n>.fdb, rs<n>.fdb).
ARCHSIZE indicates that such files can be backed up to an archive
media. This attribute provides the ability to size the data files so as to
optimize the use of the archive media on the system.
Minimum value is 1000000 (FH_MIN_ARCH_SIZE).
The value is used to determine if another RTP or Event message
database file has to be made.
Default: 10000000
The size defaults to 10 million bytes, but you can set the size to as low
as 1 million.
Actions: GETQTY GET PUT MOD
RTP sample files (r<n>.fdb) are created with a size three times the size
of ARCHSIZE and then are compressed by the AIM*Historian repack
program to be less than ARCHSIZE. However, in certain cases, the
resulting compressed file could be larger than ARCHSIZE. If one
or more of the following could be true, you may wish to specify a
somewhat smaller ARCHSIZE value to prevent the data files from
getting larger than desired:
Your configuration makes heavy use of RTPs with a value
size greater than 4 bytes, such as strings, files, or BLOBs
(less compression occurs).
You make heavy use of MDE insertions with old time stamps,
increasing the size of previously closed RTP files.
You have remote collectors which become disconnected for an
extended period, resulting in a later burst of older samples and
Event messages when communication with the remote collector is
restored. To estimate the possible number of bytes added to the
RTP data files resulting from such a burst, divide the collectors
CIRCFILESIZE by 4.
Number of configured RTPs in the database. CFGPTS is updated by
AIM*Historian.
Default: None
Actions: GETQTY GET

229

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
COMPRESS

DBPATH

EMAIL
ENABLE_STUBS

FHDESC

HISTTRACE

230

Description
Specifies whether data files are to be compressed. When an RTP sample
file is closed, the repack program sorts the file by RTP and combines all
value packets for an RTP into a single value set. If COMPRESS is YES,
the value set is then compressed into one or more value sets of up to
1000 value packets using a proprietary algorithm. When the values sets
are retrieved, the sets are automatically decompressed as needed.
FH_NO, 0, NO or FH_YES, 1, YES.
Default: 0
Actions: GETQTY GET PUT MOD
The database search path is a semicolon-separated list of directory
specifications, totaling up to 256 (FH_DBPATH_LEN) characters. The
attribute specifies the directories to be searched (in the specified order)
for RTP and message data files when retrieving data.
Two consecutive semicolons within the string terminate the search
through DBPATH. AIM*Historian automatically appends the instance
name to each directory.
Do not include the instance name at the end of the directories in
DBPATH. Do not specify more than 30 directories.
AIM*Historian assumes that the first two directories are:
/opt/aim/inst/<instance>
/opt/aim/pbk/<instance>
whether specified in DBPATH or not.
Default: /opt/aim/inst;/opt/aim/pbk
Actions: GETQTY GET PUT MOD
Example: /opt/aim/inst;/opt/aim/pbk;/mysta/mydir
Reserved for future use.
For diagnostics on non-I/A Series servers only. Allows the instance to
use the readval() and readsta() functions in the AIM*API library to
collect simulation, or stub, samples.
FH_NO, 0, NO or FH_YES, 1, YES
Default: 0
You must restart the collector for the change to take effect.
See Stub Library for Off-Platform Testing on page 189.
AIM*Historian instance description of up to 32 characters.
Default: None
Actions: GETQTY GET PUT MOD
Enclose the attribute value in quotation marks if blank spaces are to be
included in the description.
Reserved for future use.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
IATIME

LIKE

LRCCALC
MAXLOG
MAXPTS

Description
Specifies the format in which RTP time stamps are stored in the instance
database: either I/A Series time (Yes) or UTC (No).
FH_NO, 0, NO or FH_YES, 1, YES
Default: 0
Actions: GETQTY GET PUT MOD
See Note on Time Stamps on page 266 for more information.
Create another AIM*Historian instance like an existing instance. The
new instance is identical to the existing instance, including components
such as RTPs and messages, except for the instance name. Attribute
value is the name of the existing AIM*Historian instance.
Default: None
Actions: CREATE
This attribute is not supported in histcfg.
Reserved for future use.
Reserved for future use.
Maximum number of RTPs you can configure in the AIM*Historian
instance.
Minimum: 5000
Default: 5000
Actions: GETQTY GET PUT MOD
In addition to the MAXPTS limit that you configure per
AIM*Historian instance, the maximum number of RTPs you can
configure per station is governed by the AIM*Historian Authorization
Code you received from Invensys when you initially installed and
administered your system.
For example, if you are authorized for 50,000 RTPs on a server, you can
create four AIM*Historian instances with MAXPTS settings of 20000,
20000, 5000, and 5000.
The authorized maximum number of RTPs for a server is returned by
the MXSRVPTS attribute.
You should specify the MAXPTS value to be higher than the
expected maximum number of RTPs to account for RTPs that are
deleted later because of configuration mistakes and other reasons.
You can only increase the value of MAXPTS, and it requires a
restart of the AIM*Historian instance to take effect.
Attempts to decrease the value of MAXPTS are ignored.
See Modifying Maximum Value Attributes on page 84.

231

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
MAXCGENTS

MAXRGENTS

MDEGETMETHOD

232

Description
Maximum number of controlled RTP and Event message entries per
control group.
Default: 1000
Actions: GETQTY GET PUT MOD
You can only increase the value of MAXCGENTS, and it requires
a restart of the AIM*Historian instance to take effect.
Attempts to decrease the value of MAXCGENTS are ignored.
See Modifying Maximum Value Attributes on page 84.
Maximum number of RTP entries in a reduction group.
Default: 1000
Actions: GETQTY GET PUT MOD
You can only increase the value of MAXRGENTS, and it requires
a restart of the AIM*Historian instance to take effect.
Attempts to decrease the value of MAXRGENTS are ignored.
See Modifying Maximum Value Attributes on page 84.
Specifies the method for retrieving MDE samples when a single RTP has
multiple samples with the same time stamp.
AIM*Historian does not allow deletion of manually inserted RTP
values, but stores all values inserted for an MDE RTP even when they
have the same time stamp. (See AIM*Historian Spy on page 116.)
When a client application such as AIM*Historian Data Display or
AIM*Explorer retrieves MDE values, MDEGETMETHOD determines
which values are returned when there are multiple values with the same
time stamp.
For all samples for the RTP:
FH_HTYPE_ALL, 0, ALL
For the first value inserted for each time stamp:
FH_HTYPE_FIRST, 1, FIRST
For the most recent insertion for each time stamp:
FH_HTYPE_LAST, 2, LAST
Default: ALL
Actions: GETQTY GET PUT MOD
MDEGETMETHOD applies to retrievals only and does not
determine what values are stored in the AIM*Historian database.
AIM*Historian Spy displays all MDE values regardless of the
MDEGETMETHOD setting (see AIM*Historian Spy on
page 116).
When the retrieval is a reduction request and the instance
MDEGETMETHOD is ALL, fh_FdbReduction does the retrieval
as if MDEGETMETHOD were LAST.
You can change MDEGETMETHOD at any time to meet an
application requirement. For example, you can set the attribute to
LAST to use the most recently entered value in a trend display, but
change to ALL for audit purposes.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
MSGDEFS

MSGFILE

MSGTIME
MSGTRACE
MXSRVPTS

Description
Maximum number of Event message definitions in the instance.
Default: 1000
Actions: GETQTY GET PUT MOD
You can only increase the value of MSGDEFS, and it requires a
restart of the AIM*Historian instance to take effect.
Attempts to decrease the value of MSGDEFS are ignored.
See Modifying Maximum Value Attributes on page 84.
Maximum size in bytes of a message configuration file. Does not affect
the size of the actual message files.
Minimum: 1000000
Default: 1000000
Actions: GETQTY GET PUT MOD
The attribute limits the size of the message configuration file
(hist_message.cfg(.rw)), not the size of event message files
(m<n>.fdb).
You can only increase the value of MSGFILE, and it requires a
restart of the AIM*Historian instance to take effect.
Attempts to decrease the value of MSGFILE are ignored.
See Modifying Maximum Value Attributes on page 84.
Reserved for future use.
Reserved for future use.
Maximum number of RTPs you can configure in the server machine.
As shipped, you can create and use up to 20 RTPs on a machine. This
number increases when you authorize your server, as described in the
AIM*AT Installation Guide (B0193YM).
Default: 20
Actions: GETQTY GET

233

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
PCTVALID

Description
Percentage (0 to 100) of values within a reduction interval that must
be valid for the corresponding reduced value to be considered valid.
A pctvalid of zero means always consider the reduced value to be valid.
A value is considered to be OK or valid if the corresponding status word
(bit 0 is the least significant bit) is as follows:
The value type (bits 0 to 4) supported by AIM*Historian reduction, that is, one of the following numeric types:
2 (Integer)
3 (Float)
5 (Boolean)
6 (Long)
22 to 26 (Short_array to double_array)
28 to 30 (Ushort_array to Ulong_array)
The BAD bit (bit 8) must be 0, that is, not BAD.
Out-of-Service (OOS) (bit 11) must be 0, that is, in service.
Default: 0
Actions: GETQTY GET PUT MOD

REDFASTINT

REDFASTUNIT

REDMEDINT

REDMEDUNIT

234

Refer to Appendix B AIM*Historian Sample Status and

Quality.
If the value is the result of an MDE insertion, that is, the status
may contain only the value type, the status bit checks are not
done, and those values are considered valid.
Fast reduction interval.
Default: 1
Actions: GETQTY GET PUT MOD
See Note on Reduction Intervals on page 236.
Fast reduction interval units.
Minutes: FH_REDUC_UNIT_MIN, 3, MINUTES.
Hours: FH_ REDUC_UNIT_HOUR, 4, HOURS.
Days: FH_ REDUC_UNIT_DAY, 5, DAYS.
Default: Hours (4)
Actions: GETQTY GET PUT MOD
See Note on Reduction Intervals on page 236.
Medium reduction interval.
Default: 8
Actions: GETQTY GET PUT MOD
See Note on Reduction Intervals on page 236.
Medium reduction interval units.
Minutes: FH_REDUC_UNIT_MIN, 3, MINUTES
Hours: FH_ REDUC_UNIT_HOUR, 4, HOURS
Days: FH_ REDUC_UNIT_DAY, 5, DAYS
Default: Hours (4)
Actions: GETQTY GET PUT MOD
See Note on Reduction Intervals on page 236.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
REDPHASEUNIT

REDSLOWINT

REDSLOWUNIT

REDUCLEVEL

REDUCPHASE

RTTIME

RTTRACE

Description
Reduction phase offset units in minutes.
FH_REDUC_UNIT_MIN, 3, MINUTES
Default: Minutes (3)
Actions: GETQTY GET PUT MOD
Slow reduction interval.
Default: 1
Actions: GETQTY GET PUT MOD
See Note on Reduction Intervals on page 236.
Slow reduction interval units.
Minutes: FH_REDUC_UNIT_MIN, 3, MINUTES.
Hours: FH_ REDUC_UNIT_HOUR, 4, HOURS.
Days: FH_ REDUC_UNIT_DAY, 5, DAYS.
Default: Days (5)
Actions: GETQTY GET PUT MOD
See Note on Reduction Intervals on page 236.
Indicates if reductions are to be calculated on a periodic basis.
0 = no periodic reduction
1 = periodic reduction
When set, AIM*Historian performs the operations AVG, MIN, MAX,
and STDV according to the fast, medium, and slow reduction intervals
(as specified by REDFASTINT/REDFASTUNIT, REDMEDINT/
REDMEDUNIT, and REDSLOWINT/REDSLOWUNIT), and
writes the values to reduced data files rf<n>.fdb, rm<n>.fdb, and
rs<n>.fdb, respectively.
Default: 0
Actions: GETQTY GET PUT MOD
Reduction phase offset from even time base.
0 to 59
Default: 0
Actions: GETQTY GET PUT MOD
Maximum time in seconds before AIM*Historian creates a new RTP
data sample file (r<n>.fdb).
Default: 24*3600
Actions: GETQTY GET PUT MOD
Reduced RTP data files (rf<n>.fdb, rm<n>.fdb, and rs<n>.fdb) are
NOT governed by RTTIME; they are only limited by the file size
specified by ARCHSIZE.
Reserved for future use.

235

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-4. AIM*Historian Instance Component Attributes (Continued)

Attribute
SCANPEAKS

Description
Specifies whether the instance should collect peaks for RTP values.
A peak is a significant change which is either:
Greater than the previous and next change values (A), or
Less than the previous and next change values (B).
If the peak is a plateau (C), that is, the peak value does not change significantly for multiple scan periods, the time stamp of the peak is calculated
at the midway point. The value for such a peak is the value at the trailing
edge of the plateau.
0 = NO, 1 = YES
Default: 0
Actions: GETQTY GET PUT MOD
A
B
C Value

C Time Stamp

USEREDFILES

Specifies whether the instance should use reduction data files for
reduction.
If yes, reduction data files (rf<n>.fdb, rm<n>.fdb, and rs<n>.fdb) are
used as much as possible to satisfy requests for reduced data.
If no, reduction data files are not used, and requests for reduced data are
satisfied by doing a reduction-on-the-fly using RTP sample files
(r<n>.fdb).
FH_NO, 0, NO or FH_YES, 1, YES
Default: 0
Actions: GETQTY GET PUT MOD

Note on Reduction Intervals

The medium reduction interval, taking units into account, must be an even multiple of the fast
reduction interval. The slow reduction interval, taking units into account, must be an even multiple of the medium reduction interval.
To ensure proper validation of the reduction intervals, specify the reduction attributes in the following order: REDFASTINT, REDFASTUNIT, REDMEDINT, REDMEDUNIT,
REDSLOWINT, REDSLOWUNIT.
It is recommended that you specify reduction intervals and keep them, even though it is possible
to change them. If you decrease the length of a reduction interval, subsequent retrieval of reduced
data generated with the longer reduction interval may not be as accurate.

236

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Collector Component
AIM*Historian uses collectors to collect real-time and message data. An AIM*Historian instance
can have up to 100 collectors.
AIM*Historian automatically creates a local I/A Series real-time collector for each
AIM*Historian instance. If you have additional collector stations such as a remote I/A Series realtime collector, you need to explicitly create a collector station.

Collector Component How To

Identify a Collector Station

NAME

Station name

COLDESC

Station descriptor

ISIA

Identify the collector host as an I/A Series station

ISREMOTE

Specify if the remote collector is on or not

NODE

I/A Series node number

PLATFORM

Station platform type

TYPE

Collector type

Specify Time Handling

DST

Specify Daylight Savings Time

TZ

Time zone

Specify Collector Operation

CSTARTONBOOT
Determine whether the collector starts at reboot of the machine on which
the collector runs.
FOLLOWINSTON
Specify automatic start of the collector when the instance is started.
FOLLOWINSTOF
Specify automatic shutdown of the collector when the instance is
shutdown.
MINCOLCYCLE
Set a minimum frequency for the collection cycle.
Specify Remote Collector Information

CIRCFILESIZE

Collector circular file size in bytes

237

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

CONSLEEPSECS

Seconds of sleep after connect retry

HOSTNAME

Hostname used by the remote collector

IPADDR

Hostname used by the remote collector (for backward compatibility with

instances prior to AIM*AT 3.2)

Specify Burst Mode Information for a Remote Collector

BURSTINT

Burst interval

BURSTBTPCT

Burst interval byte threshold percent

BURSTTTPCT

Burst interval time threshold percent

Collector Station Attribute Descriptions

Table E-5 describes the attributes of the Collector Station component.
NOTE

You cannot delete a collector station from an instance.

Several collector attributes pertain to the remote collector machine, or to the remote collector
machine and the instance. All remote collectors running on the same machine (as determined by
the ISREMOTE and HOSTNAME attributes) must have the same value for these common
attributes. For example, all collectors running on the same machine must have the same time zone
(TZ) value.
When a collectors ISREMOTE attribute is changed to YES or its HOSTNAME is changed,
AIM*Historian automatically ensures that common attributes for the collector are appropriately
updated. In addition, changes to the common attributes in one remote collector are automatically
updated for the instances other remote collectors running on the same machine.

238

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

The common attributes are:

BURSTBTPCT

BURSTTTPCT
BURSTINT

CIRCFILESIZE
CONSLEEPSECS

DST

ISIA
NODE

COLPORT
PLATFORM

TZ.
Table E-5. Collector Station Component Attribute

Attribute
NAME

BURSTBTPCT

Description
Station name of up to 48 characters.
Default: None
Actions: CREATE GETQTY GET MOD DEL
You can modify a station only if it has no configured RTPs.
An instance must contain an I/A Series Collector with the same
name as the instance for an I/O Gate Collector to function
properly. The I/A Series Collector need not contain any points.
Burst byte threshold, in percent. BURSTBTPCT is the percent of the
size of the circular file below which histsend must get before histsend
disconnects from the instance. Specify BURSTBTPCT of 0 to empty
the circular file before disconnecting. See BURSTINT for an example.
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Default: 10
Actions: GETQTY GET PUT MOD

239

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-5. Collector Station Component Attribute (Continued)

Attribute
BURSTTTPCT

BURSTINT

240

Description
Burst time threshold, in percent. BURSTTTPCT is the percent
of time before which histsend must get below the byte threshold
specified by BURSTBTPCT before histsend will disconnect. See
BURSTINT for an example. This setting depends on the nature
and cost of your connection.
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Default: 90
Actions: GETQTY GET PUT MOD
Burst interval, in seconds. Zero (0) means non-burst mode collector.
AIM*Historian does not disconnect the collector when BURSTINT
is 0.
If a non-zero value is specified, the collector makes a connection to
the AIM*Historian instance, sends collected data from the circular
file to the instance, disconnects, and sleeps BURSTINT seconds
minus the time spent sending data. The purpose of a burst mode
collector is to save money associated with connect time. This attribute
is only advice to the collector, as the collector does not disconnect
until it has satisfied the criteria specified by BURSTBTPCT (burst
byte threshold percent) and BURSTTTPCT (burst time threshold
percent).
For example, if CIRCFILESIZE is 1000000, BURSTINT is 3600,
BURSTBTPCT is 10, and BURSTTTPCT is 80, histsend does not
disconnect unless and until the number of bytes left in the circular file
is less than 10% of 1000000 bytes (100000) and this byte level is
reached within 80% of the burst interval (2880 seconds). The byte
threshold is designed to guard against overwriting of old data because
the circular file remains too full. The time threshold is designed to
avoid disconnects followed too closely by a reconnect, that is, to avoid
disconnects that do not save much in the way of connection time.
After the specified number of seconds has elapsed, the collector makes
a connection to the AIM*Historian instance, sends collected data to
the instance, and disconnects.
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Default: 0
Actions: GETQTY GET PUT MOD

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-5. Collector Station Component Attribute (Continued)

Attribute
CIRCFILESIZE

COLDESC

CONSLEEPSECS

Description
Circular file size in bytes.
Specifying a larger size minimizes the chances of losing data during
periods of overload at the instance machine or loss of communication.
Each remote collector collects I/A Series or I/O Gate data and writes it
to a circular file. This circular file buffers data to handle cases when the
instance machine temporarily cannot keep up with the incoming
messages. It also buffers data when there is a loss of network
communication.
Minimum: 1000000
Default: 1000000
Actions: GETQTY GET PUT MOD
To change CIRCFILESIZE:
Stop the remote collector programs: the real-time collectors
(iacol and iogatecol), the message collectors (ipchisti or Message
Manager), and histsend.
Verify that the circular file in the instance directory for remote
collector is deleted (for example,
/opt/aim/inst/hist01/hist_circ_file.dat).
Modify the CIRCFILESIZE value.
Restart the programs.
If you modify CIRCFILESIZE while remote collector programs are
still running, the programs continue to operate with the circular file at
its original size. The value for this common attribute must be the same
for all collectors running on the same machine for the same instance.
Collector description of up to 32 (FH_DESCRIPTOR_LEN)
characters.
Default: None
Actions: GETQTY GET PUT MOD
Enclose the attribute value in quotation marks if blank spaces are to
be included in the description.
The number of seconds that histsend sleeps between reconnect retries
following a communication error. A typical system takes the default.
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Default: 5
Actions: GETQTY GET PUT MOD

241

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-5. Collector Station Component Attribute (Continued)

Attribute
COLPORT

CSTARTONBOOT

242

Description
TCP/IP port of the remote collector machine.
Valid port numbers are from 1 to 65535 except port numbers used
for other applications including:
4567, the apihosts port for broadcasts
45678, the AIM*API server port
55555, the FoxApi server port
Examine the services file or run netstat -a to show the ports in use.
If the histreceive process for communicating with a remote collector is
running, that collectors COLPORT attribute cannot be modified.
The remote collectors COLPORT must match the port number
being used by histsend at the remote collector machine.
histsend uses the port number specified in the [AISNET] section of
the /opt/aim/bin/an_init.tcp file.
If you change this COLPORT, you must restart the histsend parent
for the change to take effect.
Default: 44444
Upon upgrade to AIM*AT 3.2, COLPORT for existing remote
collectors defaults to the contents of /opt/aim/inst/port.txt if the file
contains a valid port address. Otherwise, it defaults to 44444.
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
COLPORT is ignored for local collectors.
Actions: GETQTY GET PUT MOD
Specifies whether the collector should start on reboot.
If yes, FH_YES, 1, YES.
If no, FH_NO, 0, NO.
Default: YES (1)
On reboot of the instance machine, for each instance with the Start
on reboot option selected, AIM*Historian starts local collectors with
CSTARTONBOOT enabled and starts histreceive processes needed
to support the instances remote collectors.
On reboot of a remote collector machine, AIM*Historian automatically starts remote collectors with CSTARTONBOOT enabled. Note
that initially, a remote collector must be started manually to copy the
.cfg files from the instance machine to the collector machine. Once
the .cfg files reside on the remote collector machine, automatic start
on reboot can be used.
Actions: GETQTY GET PUT MOD

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-5. Collector Station Component Attribute (Continued)

Attribute
DST

FOLLOWINSTOF

FOLLOWINSTON

Description
Specifies use of Daylight Saving Time.
If no, FH_NO, 0, NO.
If yes, FH_YES, 1, YES.
Default: None
Actions: GETQTY GET PUT MOD
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
See Note on Time Stamps on page 266 for more information.
Specifies whether the collector should follow the instance off.
If no, FH_NO, 0, NO.
If yes, FH_YES, 1, YES.
Default: NO (0)
After AIM*Historian shuts down an instance, it automatically
turns off the instances collectors that are configured with
FOLLOWINSTOF enabled.
If a remote collector has a failed network connection, the collector
turn-off request is held until the connection is restored.
Actions: GETQTY GET PUT MOD
Specifies whether the collector should follow the instance on.
If yes, FH_YES, 1, YES.
If no, FH_NO, 0, NO.
Default: YES (1)
When AIM*Historian starts an instance, it automatically starts the
instances collectors that are configured with FOLLOWINSTON
enabled.
If a remote collector has a failed network connection, the collector
start request is held until the connection is restored.
If the collector is already running, it continues to run and the newly
started collector exits.
Actions: GETQTY GET PUT MOD

243

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-5. Collector Station Component Attribute (Continued)

Attribute
HOSTNAME

IPADDR

ISIA

ISREMOTE

MINCOLCYCLE

244

Description
AIM*AT hostname for a remote collector.
HOSTNAME must be configured all remote collectors. If it is not
configured, histreceive logs an error to historian.log during startup as
it is not able to resolve the HOSTNAME to an IP dot address.
HOSTNAME must match the hostname entered when the
AIM*Historian software was installed on the remote collector
machine.
If the histreceive process for communicating with a remote collector is
running, that collectors HOSTNAME attribute cannot be modified.
If broadcasting is disabled or does not reach the remote collector
because of an intervening router, AIM*Historian obtains the dot
address from the an_init.cfg file. You must use the AIM*AT
hostname for this attribute.
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
HOSTNAME is ignored for local collectors.
Default: None
Actions: GETQTY GET PUT MOD
AIM*AT hostname for a remote collector.
The IPADDR attribute is kept for backward compatibility, but now
provides the same functions as the HOSTNAME attribute.
Specifies whether the collector host is an I/A Series station.
If no, FH_NO, 0, NO.
If yes, FH_YES, 1, YES.
Default: Yes (1)
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Actions: GETQTY GET PUT MOD
Specifies whether the I/A Series or I/O Gate collector is on a
computer other than the instance host.
If no, FH_NO, 0, NO.
If yes, FH_YES, 1, YES.
Default: No (0)
Actions: GETQTY GET PUT MOD
Minimum collection cycle in milliseconds.
Value can be any factor of 1000: 1000, 500, 250, 200, 125, 100, 50,
40, 25, 20, 10, 8, 5, 4, 2, or 1.
Prior to AIM*AT 3.2, a collector checked every 500 milliseconds
for RTPs to scan. Starting with AIM*AT 3.2, a collectors cycle is
calculated as the greatest common denominator of the fast scan rates
of the collectors RTPs. If the calculated rate is less than the configured
MINCOLCYCLE, AIM*Historian clamps the collectors cycle
at MINCOLCYCLE and logs a warning message to historian.log.
Default: 500
Actions: GETQTY GET PUT MOD

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-5. Collector Station Component Attribute (Continued)

Attribute
NODE

PLATFORM

RECVPASSUPDS

SENDPASSSECS

TYPE

TZ

Description
I/A Series node number the collector is located on (1, 2, 3, and so on).
Default: 1
Actions: GETQTY GET PUT MOD
Station platform type:
Sun Solaris: FH_SYS_SOLARIS, 1, SOLARIS
Sun SunOS: FH_SYS_SUNOS, 2, SUNOS
Microsoft Windows NT: FH_SYS_NT, 3, NT
Default: NT (3)
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Actions: GETQTY GET PUT MOD
Beginning with AIM*AT Version 3.2, this attribute is no longer used
but is maintained to allow use of existing .inp files without editing.
Configuration changes are not made and no errors are returned.
Beginning with AIM*AT Version 3.2, this attribute is no longer used
but is maintained to allow use of existing .inp files without editing.
Configuration changes are not made and no errors are returned.
Collector Type
Real-time server: FH_TYPE_REALTIME, 1, REALTIME_SERVER
Message server: FH_TYPE_MESSAGE, 2, MESSAGE_SERVER
I/A Series Real-time collector: FH_TYPE_IA_RT_COLLECTOR 3,
IA_RT_COLLECTOR
I/A Series Message collector: FH_TYPE_IA_MSG_COLLECTOR,
4, IA_MSG_COLLECTOR
I/O Gate collector: FH_TYPE_IOGATE_COLLECTOR, 6,
IOGATE_COLLECTOR
Default: Real-time (3)
Actions: GETQTY GET PUT MOD
Time zone specification. See values in Table E-6.
Default: GMT (1)
The value for this common attribute must be the same for all
collectors running on the same machine for the same instance.
Actions: GETQTY GET PUT MOD
Example: GMT_MINUS_5 for Eastern Time, US and Canada
The TZ attribute should reflect the actual geographic location, and
not necessarily the station settings (which may be forced to GMT on
an I/A Series workstation).
See Note on Time Stamps on page 266.

245

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-6. TZ Attribute Values

FH_GMT
FH_GMT_PLUS_1
FH_GMT_PLUS_2
FH_GMT_PLUS_3
FH_GMT_PLUS_330
FH_GMT_PLUS_4
FH_GMT_PLUS_430
FH_GMT_PLUS_5
FH_GMT_PLUS_530
FH_GMT_PLUS_6
FH_GMT_PLUS_7
FH_GMT_PLUS_8
FH_GMT_PLUS_9
FH_GMT_PLUS_930
FH_GMT_PLUS_10
FH_GMT_PLUS_11
FH_GMT_PLUS_12
FH_GMT_MINUS_1
FH_GMT_MINUS_2
FH_GMT_MINUS_3
FH_GMT_MINUS_330
FH_GMT_MINUS_4
FH_GMT_MINUS_5
FH_GMT_MINUS_6
FH_GMT_MINUS_7
FH_GMT_MINUS_8
FH_GMT_MINUS_9
FH_GMT_MINUS_10
FH_GMT_MINUS_11
FH_GMT_MINUS_12

246

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

GMT
GMT_PLUS_1
GMT_PLUS_2
GMT_PLUS_3
GMT_PLUS_330
GMT_PLUS_4
GMT_PLUS_430
GMT_PLUS_5
GMT_PLUS_530
GMT_PLUS_6
GMT_PLUS_7
GMT_PLUS_8
GMT_PLUS_9
GMT_PLUS_930
GMT_PLUS_10
GMT_PLUS_11
GMT_PLUS_12
GMT_MINUS_1
GMT_MINUS_2
GMT_MINUS_3
GMT_MINUS_330
GMT_MINUS_4
GMT_MINUS_5
GMT_MINUS_6
GMT_MINUS_7
GMT_MINUS_8
GMT_MINUS_9
GMT_MINUS_10
GMT_MINUS_11
GMT_MINUS_12

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

RTP Component
AIM*Historian historizes real-time data collected for real-time points (RTPs). The RTP contains
the necessary information to make this collection possible. Real-time information can be traditional I/A Series process information such as measurements, analog inputs, and Boolean values, or
it can be a Binary Large Object (BLOB), File contents, and arrays of values.
RTPs can be deleted and undeleted. While an RTP is deleted, its attributes cannot be modified
and its data cannot be retrieved. A deleted RTP still occupies a slot in the real-time configuration
file (it does not get removed to make room for another RTP), so it can be thought of as being
deactivated. However, if an RTP has no collected samples yet, the RTP name can be modified.

RTP Component How To

Identify an RTP and its Point in the DCS

NAME

RTP name

COLLECTOR

Collector Name

NAMEINCOL

Name in collector

Describe an RTP

DESC

Descriptor

ENGUNITS

Engineering units

Specify RTP Collection Method

COLMETH

Collection method

Specify a Manual Data Entry (MDE) Point

COLMETH

Manual Data Entry point

Specify RTP Value Format

TYPE

Value type

SIZE

Value size

NUMELEMS

Number of array elements in value

Specify RTP Initial and Restart States

INITSTATE

Initial state

RSTRTSTATE

Restart state
See also: Control Group Component on page 260.

247

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Specify When to Check for Changes for RTPs

FASTFREQ

Fast frequency

FFREQUNITS

Fast frequency units

SLOWFREQ

Slow frequency

SFREQUNITS

Slow frequency units

Specify Criteria for Collecting RTP Changes

READDELTA

Read change delta

When to Force a Sample Regardless of Value

MXSAMTIME

Maximum sample time

MXSAMUNITS

Maximum sample time units

If Force a Sample When Another RTP Changes

TRGCHANGE

Sample on trigger RTP as well as on a change

TRIGGER

Trigger RTP

Specify Range Limits for Trending

HIRANGE

High range

LORANGE

Low range

Create an RTP like an Existing RTP

LIKE

Replicate an RTP

Retrieve an RTP Index for Accessing RTP Information

INDEX

248

Retrieves RTP index

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

RTP Attribute Descriptions

Table E-7 describes the attributes of the RTP component.
Table E-7. RTP Component Attributes

Attribute
NAME

AUDITUPD
COLLECTOR

COLMETH

Description
RTP name of up to 32 (FH_TAG_LEN) characters. RTP names must be
unique within an AIM*Historian instance. The NAME can be the same as
the RTPs NAMEINCOL, or it can be different. For example, if all the
RTPs in the AIM*Historian instance are from an I/A Series system, you may
want to define the NAME and NAMEINCOL for each RTP to be the same
(for simplicity). If your AIM*Historian instance has RTPs for multiple types
of DCS systems, you may want to adopt some other naming scheme for your
RTP names.
Default: None
Actions: CREATE GETQTY GET MOD DEL UNDEL
Modification is only allowed if there are no values inserted for this
RTP in the database.
When you initially create a new RTP with the AIM*Historian
Configurator, it defaults the NAMEINCOL to be the same as the
NAME.
Reserved for future use.
Collector station name of up to 48 (FH_COLLECTOR_LEN) characters,
indicating which collector is responsible for collecting this RTP. In the case
of RTPs with the COLMETH of WRITE, it is the collector responsible for
receiving the data.
Default: Instance name
Actions: GETQTY GET PUT MOD
A valid collector name must be specified; however, it is ignored if RTP has a
collection method (COLMETH) of MDE.
Modification is only allowed if there are no values inserted for this
RTP in the database.
Collection method.
If manually entered data: FH_HTYPE_MDE,1,MDE
If connected data: FH_HTYPE_CONNECTED,2,CONNECTED
If getval, that is, unconnected data: FH_HTYPE_GETVAL, 3, GETVAL
If the RTP values are to be written to the collector: FH_HTYPE_WRITE,
5, WRITE
Default: CONNECTED (2)
Actions: GETQTY GET PUT MOD
COLMETH can change between CONNECTED and GETVAL, but
changes to or from MDE and WRITE are not allowed, unless the change is
made before any data is historized for the RTP.

249

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-7. RTP Component Attributes (Continued)

Attribute
DESC

ENGUNITS

EXPORT

FASTFREQ

FFREQUNITS

250

Description
RTP descriptor of up to 32 (FH_DESCRIPTOR_LEN) characters.
Default: None
Actions: GETQTY GET PUT MOD
Enclose the attribute value in quotation marks if blank spaces are to be
included in the description.
Engineering units descriptor of up to 6 (FH_ENG_UNIT_LEN) characters.
Default: None
Actions: GETQTY GET PUT MOD
Specifies whether samples are to be exported to a database using the Export
to Oracle option (see Appendix G Exporting to Oracle).
If no, FH_NO, 0, NO.
If yes, FH_YES, 1, YES.
Default: NO (0)
Actions: GETQTY GET PUT MOD
The EXPORT attribute is not supported by AIM*Historian Configurator,
but must be batched in from a configuration input file (*.inp), as described
in Configuration Using Input Text Files on page 64.
Fast collection frequency, 1 to 999999. Its units are specified by
FFREQUNITS. The data collectors always check the RTPs for changes at
the fast frequency. Changes are only written to the AIM*Historian RTP
database at the currently selected collection frequency for the RTP, which
could be either fast or slow. By always checking at the fast frequency, the
data collectors are able to make a quick transition from the slow to fast
collection frequency.
Default: 1
Actions: GETQTY GET PUT MOD
FASTFREQ is ignored if COLMETH is MDE, except for purposes of
on-the-fly reduction.
When AIM*Historian does a reduction-on-the-fly for an RTP, it linearizes
the sample input to the reduction calculation based on the configured
FASTFREQ/FFREQUNITS for the RTP. If either of these attributes are
modified, subsequent reduced values calculated from data collected while the
previous FASTFREQ/FFREQUNITS values were in effect could vary from
previously calculated reduced values.
Fast collection frequency units:
Milliseconds: FH_SCAN_UNIT_MILLI, 1, MSECS
Seconds: FH_SCAN_UNIT_SEC, 2, SECONDS
Minutes: FH_SCAN_UNIT_MIN, 3, MINUTES
Hours: FH_SCAN_UNIT_HOUR, 4, HOURS
Days: FH_SCAN_UNIT_DAY, 5, DAYS
Default: Seconds (2)
Actions: GETQTY GET PUT MOD
FFREQUNITS is ignored if COLMETH is MDE or WRITE.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-7. RTP Component Attributes (Continued)

Attribute
HASVALUE
HIRANGE

INDEX

INITSTATE

LIKE

LORANGE

MXSAMTIME

Description
Reserved. Set and used by histsave and histbatch programs to protect the
configurations in .inp files.
High range of the RTPs value in engineering units; used for Trending and
to validate MDE insertions if the RTPs COLMETH is MDE.
Default: 100.0
Actions: GETQTY GET PUT MOD
AIM*Historian assigns a unique INDEX value for an RTP when
AIM*Historian creates the RTP.
Default: Assigned by AIM*Historian
Actions: GETQTY GET
Initial state of the RTP.
Off: FH_START_OFF, 0, OFF
On: FH_START_ON, 1, ON
Default: ON (1)
Actions: GETQTY GET PUT MOD
INITSTATE is only used to set the on/off state of the RTP when it is
created.
RSTRTSTATE dictates the on/off state of the RTP after the instance
restarts.
Name of the existing RTP used to create a new RTP.
Up to 32 (FH_TAG_LEN) characters.
Default: None
Actions: CREATE
Low range of the RTPs value in engineering units, used for Trending and to
validate MDE insertions if the RTPs COLMETH is MDE.
Default: 0.0
Actions: GETQTY GET PUT MOD
Maximum time between samples. Units are specified by MXSAMUNITS. It
must be greater than or equal to the slow collection frequency of the RTP.
For example, if MXSAMTIME is 3600 and MXSAMUNITS is 2, a sample
is collected for the RTP every hour, regardless of the RTPs current value or
status.
Default: 3600
Actions: GETQTY GET PUT MOD
MXSAMTIME is ignored if COLMETH is MDE or WRITE.
Note: If the generation of reduction values is configured for the instance,
ensure that at least one sample is collected for each fast reduction interval by
configuring the maximum time between samples to be less than the fast
reduction interval for the instance.

251

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-7. RTP Component Attributes (Continued)

Attribute
MXSAMUNITS

NAMEINCOL

252

Description
Units for maximum time between samples:
Milliseconds: FH_SCAN_UNIT_MILLI, 1, MSECS
Seconds: FH_SCAN_UNIT_SEC, 2, SECONDS
Minutes: FH_SCAN_UNIT_MIN, 3, MINUTES
Hours: FH_SCAN_UNIT_HOUR, 4, HOURS
Days: FH_SCAN_UNIT_DAY, 5, DAYS
Default: SECONDS (2)
Actions: GETQTY GET PUT MOD
MXSAMUNITS is ignored if COLMETH is MDE or WRITE.
Name, of up to 256 characters, specific to a DCS system, which uniquely
defines a point within an AIM*Historian collector station of the RTP in the
collector station.
Default: RTP name, as specified by NAME attribute
Actions: GETQTY GET PUT MOD
Modification is only allowed if there are no values inserted for this
RTP in the database.
For an RTP whose COLMETH is MDE, NAMEINCOL is ignored.
For an RTP whose COLMETH is GETVAL, NAMEINCOL is an
I/A Series object. However, if the object is a string, and the specified number
of elements (NUMELEMS) is greater than 256 (the maximum length of an
I/A Series shared variable string), the following scheme is used to retrieve all
specified bytes:
There should be as many strings as necessary to fill the array.
Strings look like <root> <root>1, <root>2, <root>3 if multiple strings are
necessary, where <root> is the root name of the shared variable.
Example 1: <root> is TOWER and the value size is 800;
The collector uses the AIM*API sread() call for shared variables TOWER,
TOWER1, TOWER2, and TOWER3.
Example 2: <root> is TOWER and the value size is 200;
The collector uses the AIM*API sread() call for shared variable TOWER.
This scheme allows an application to insert arrays of values; for example,
paper machine profiles, into shared variable strings.
For an RTP whose RTP value type (TYPE) is FILE (51), the NAMEINCOL
is the specification of the file to be collected. For example:
d:\opt\aim\inst\hist01\report.txt for an AW70 or Windows NT server;
/opt/aim/inst/hist01/report.txt for an AW51 or Solaris server.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-7. RTP Component Attributes (Continued)

Attribute
NAMEINCOL
(For I/A Series
objects)

NAMEINCOL
(For I/O Gate)
NUMELEMS

READDELTA

Description
For an I/A Series collector, the NAMEINCOL refers to I/A Series objects,
which can be specified as follows:
I/A Series objects accessible with AIM*Historian are parameters in I/A Series
blocks and I/A Series shared variables of type variable. A compound is a
logical collection of blocks. A block is a member of a set of algorithms that
does a certain control task within the compound scheme. Both compounds
and blocks have a set of parameters that comprise the user interface.
I/A Series objects of type alias, device/letterbug, and process are not accessible with AIM*Historian.
To refer to a compound parameter object, specify the Compound.Parameter;
for example, REFLUX.CINHIB.
To refer to a block parameter object, specify the
Compound:Block.Parameter; for example, REFLUX:F100.MEAS.
To refer to a shared variable, specify the Shared_variable; for example,
SHARED_VAR_234.
Compound, Block, Parameter, and Shared variable names can have any mix
of numerics (0 to 9), uppercase alphabetics (A to Z), and the underscore (_),
with maximum lengths as follows:
Compound: 12
Block: 12
Parameter: 6
Shared Variable: 14
For an I/O Gate collector, the NAMEINCOL syntax is specific to the I/O
Gate Driver on your system. Refer to the AIM*AT I/O Gate Drivers Users
Guide (B0193YU).
Number of array elements in the value of the RTP. For non-array value
types, NUMELEMS must be 1.
For the RTP value type FILE, the number of elements is the number of
bytes in the file when it is collected.
For array and string value types, NUMELEMS must be greater than or equal
to 1 and less than or equal to the AIM*Historian instance ARCHSIZE value
divided by two.
Default: 1
Actions: GETQTY GET PUT MOD
Modification is only allowed if there are no values inserted for the RTP
in the database.
Read change delta, in engineering units, greater than or equal to 0.0.
The RTP value is collected if the float type value changes by an amount
greater than or equal to the delta. Non-float RTPs are collected on any
change.
Default: 0.5
Actions: GETQTY GET PUT MOD
READDELTA is ignored if COLMETH is MDE or WRITE.

253

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-7. RTP Component Attributes (Continued)

Attribute
RSTRTSTATE

SFREQUNITS

SIZE

254

Description
The state of the RTP after AIM*Historian restarts:
Off: FH_START_OFF, 0, OFF
On: FH_START_ON, 1, ON
State prior to the restart: FH_START_AS_PREVIOUS, 2,
PREVIOUS.
Default: AS_PREVIOUS (2)
Actions: GETQTY GET PUT MOD
Slow collection frequency units:
Milliseconds: FH_SCAN_UNIT_MILLI, 1, MSECS
Seconds: FH_SCAN_UNIT_SEC, 2, SECONDS
Minutes: FH_SCAN_UNIT_MIN, 3, MINUTES
Hours: FH_SCAN_UNIT_HOUR, 4, HOURS
Days: FH_SCAN_UNIT_DAY, 5, DAYS
Default: Seconds (2)
Actions: GETQTY GET PUT MOD
SFREQUNITS is ignored if COLMETH is MDE or WRITE.
Size, in bytes, of the RTP value. If a predefined value type, the SIZE is also
predefined and cannot be changed. If the value type is user-defined, either
FH_USER_TYPE_START (50) or FH_STRING (31), the SIZE can be 1
to 32000.
For the RTPs of the value type FH_STRING(31), the SIZE must be large
enough to hold the longest possible string value including a null terminator.
For example, if the maximum configured length of the string is 6 bytes,
specify a SIZE of 7. The value for strings always occupies SIZE bytes in the
AIM*Historian database.
Default: 4
Actions: GETQTY GET PUT MOD
Modification is only allowed if there are no values inserted for this
RTP in the database.
If a predefined type (other than FILE) is entered, the SIZE default is entered
for the RTP. For the type FILE, the size is the size of the file collected. For
user-defined types, the default size is 1.
The size of a given RTP value is not necessarily the same as that of the target
point in the DCS. For example, the size of the integer type RTP
(FH_INTEGER, 2) is 4 bytes. This type is used to collect integer values
from an I/A Series system. Integers in I/A Series software (also referred to as
Type 2) are only 2 bytes. Thus, when collecting integer values from the
I/A Series system, AIM*Historian only uses two bytes. Likewise, when you
write values to an I/A Series system integer using a demand write RTP, you
must limit the size of the value to two bytes. The range for the integer value
is
-32768 to 32767.
See Appendix B AIM*Historian Sample Status and Quality, for details
concerning the RTP SIZE and NUMELEMS attributes for each RTP
type.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-7. RTP Component Attributes (Continued)

Attribute
SLOWFREQ

TRGCHANGE

TRIGGER

Description
Slow collection frequency: 1 to 999999 with units specified by
SFREQUNITS.
Default: 1
Actions: GETQTY GET PUT MOD
See FASTFREQ for more explanation of fast versus slow collection
frequencies.
SLOWFREQ is ignored if COLMETH is MDE or WRITE.
Determines whether the RTP value for this RTP is to be collected when a
triggering RTP changes. If Yes, and RTP specified by TRIGGER changes,
AIM*Historian sends a value for this RTP.
See the TRIGGER attribute for further explanation of the feature.
If No, FH_NO, 0, NO
If Yes, FH_YES, 1, YES
Default: No (0)
Actions: GETQTY GET PUT MOD
TRGCHANGE is ignored if COLMETH is MDE or WRITE.
Name of an existing RTP to be used as a triggering RTP for this RTP, up to
32 (FH_TAG_LEN) characters long. When the triggering RTP changes by
the amount specified in its own READDELTA, AIM*Historian collects a
value for this RTP.
The triggering only occurs when the triggering RTP changes by a significant
amount.
The triggering does NOT occur if the triggering RTP has a new sample
collected only because of its MXSAMTIME and MXSAMUNITS attributes.
Default: None
Actions: GETQTY GET PUT MOD
Triggering and triggered RTPs must be in the same collector.
TRIGGER is ignored if COLMETH is MDE or WRITE.
The READDELTA for a triggered RTP should be relatively small.
Even though the value is externally triggered, the value is not read if the
READDELTA is not met.
The frequency values (FASTFREQ, SLOWFREQ, FFREQUNITS,
SFREQUNITS, MXSAMTIME, and MXSAMUNITS) for a triggered
RTP should be large if the RTP is to be collected only when it is
triggered.
The triggering does not occur if the triggering RTP has made
a transition from accessible to inaccessible, or if the triggering
RTP is inaccessible when the collector is started. When either
condition occurs, AIM*Historian writes an entry to the
FH_TRIGGER_INACCESSIBLE quality bit set. This is done
to avoid delays associated with scanning an inaccessible RTP.

255

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-7. RTP Component Attributes (Continued)

Attribute
TYPE

Description
One of the data types listed in table.
Default: Float (3)
Actions: GETQTY GET PUT MOD
See Appendix B AIM*Historian Sample Status and Quality, for details
concerning the RTP SIZE and NUMELEMS attributes for each RTP
type.
Use TYPE 50 to define an RTP as having a binary large object (BLOB)
value.
Table E-8. RPT Data Types

FH_CHAR
FH_INTEGER
FH_FLOAT
FH_BOOLEAN
FH_LONG
FH_SHORT
FH_INT_PACKED
FH_LONG_PACKED
FH_CHAR_ARRAY
FH_SHORT_ARRAY
FH_INTEGER_ARRAY
FH_LONG_ARRAY
FH_FLOAT_ARRAY
FH_DOUBLE_ARRAY
FH_UCHAR_ARRAY
FH_USHORT_ARRAY
FH_UINT_ARRAY
FH_ULONG_ARRAY
FH_STRING
FH_USER_TYPE_START
FH_FILE
FH_TIMESTAMP

256

1
2
3
5
6
8
9
10
21
22
23
24
25
26
27
28
29
30
31
50
51
52

CHAR
INTEGER
FLOAT
BOOLEAN
LONG
SHORT
INT_PACKED
LONG_PACKED
CHAR_ARRAY
SHORT_ARRAY
INTEGER_ARRAY
LONG_ARRAY
FLOAT_ARRAY
DOUBLE_ARRAY
UCHAR_ARRAY
USHORT_ARRAY
UINT_ARRAY
ULONG_ARRAY
STRING
USER
FILE
TIMESTAMP

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Event Message Component

An Event message in AIM*Historian consists of a message definition that is kept in the message
configuration file, and historized message instances of the defined Event message that are stored
in the message database files. The message definition of a message is needed to marshall and
demarshall messages when they are sent to or received from an AIM*Historian instance.
NOTE

Refer to /opt/aim/examples/histbatch.inp for the definition of I/A Series legacy

and iaalarm message groups.

Event Message Component How To

Identify a Group and Message Name

GROUP

Message group

NAME

Message name (Message Group and Message Name in

AIM*Historian Configurator)

Specify Message Format

DEFN

Message definition (Keyword, ODBC Option, Type, and Number of

Elements in AIM*Historian Configurator)

Create a Message Like an Existing Message

LIKE

Replicates a message

Retrieve a Message Index for Accessing Message Information

INDEX

Get an Index

NOTE

Unlike RTPs and Reduction Groups, event messages do not support an EXPORT
attribute for use with Export to Oracle. Configuration for export of messages to an
Oracle database is accomplished in the msg.ini file, as described in Data Export
Configuration Files on page 279.

257

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Event Message Attribute Description

Table E-9 describes the attributes of the Event Message component.
Table E-9. Event Message Component Attributes

Attribute
NAME

DEFN

DEFN
(Example)

258

Description
Message name, consisting of a message group name and a message name, each
32 characters long and separated by a space.
Example: MyMessageGroup AlarmMsg
The message group must be created using the GROUP attribute before the
message name can be created within the group.
Default: None
Actions: CREATE GETQTY GET DEL
You can delete only if there are no Event messages inserted for this
message type in the database.
Definition of a message field or key within a message consisting of a string
with substrings, defined as follows:
<Keyword> = <Sequence> <ODBC> <Type> <Number of Elements>
where:
<Keyword> is a key word of up to 14 (FH_MSG_KEYWORD_LEN)
characters.
<Sequence> is the sequence number (1, 2, 3, and so on) of the key within the
message. It is used at the end of a configuration session to verify if all keys are
entered.
<ODBC> is Y if the key is to be accessible through the ODBC interface, N if
it is not to be accessible. If the <Number of Elements> is greater than 1 and
the <Type> is something other than STRING, <ODBC> must be specified as
N.
<Type> The value type of the key. All value types listed for the RTP TYPE
attribute are allowed except 50 (FH_USER_TYPE_START) and 51
(FH_FILE).
<Number of Elements> is the number of array elements of the specified type.
For example:
String of 80 characters, accessible to ODBC
Array of 3 floating point values, not accessible to ODBC
Single integer, accessible to ODBC
my_text_string = 4, Y, string, 80
my_float_array = 5, Y, float, 3
my_int_ = 6, Y, int, 1
The first three definitions for all messages must be:
group = 1, Y, string, 32
message = 2, Y, string, 32
time = 3, Y, long, 1
Default: None
Actions: GETQTY GET PUT MOD
Modification is only allowed if there are no Event messages inserted for
this message type in the database.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-9. Event Message Component Attributes (Continued)

Attribute
GROUP

INDEX

LIKE

UPDATE

Description
Message group of up to 32 (FH_MSG_GROUP_LEN) characters.
Default: None
Actions: CREATE GETQTY GET DEL
Deletion is only allowed if there are no Event messages inserted for this
message type in the database.
A unique message number assigned by AIM*Historian to INDEX for a
message when AIM*Historian creates the message.
Default: Assigned by AIM*Historian
Actions: GETQTY GET
Message name, consisting of a message group of up to 32
(FH_MSG_GROUP_LEN) characters, a space, and a message name of up to
32 (FH_MSG_NAME_LEN) characters, used to create a new message.
The message group and message name must already exist.
Example: MyMessageGroup AlarmMsg
Default: None
Actions: CREATE
Reserved for future use.

259

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Control Group Component

Some applications require groups of AIM*Historian RTPs or messages to be switched in one
operation between the following states: On and Off, BAD and OK, and fast collection and slow
collection frequency.
You can specify RTPs, Event messages or both to be controlled by a control group. You can also
optionally specify one RTP as the trigger RTP for each of the above mentioned states.

Control Group Component How To

Identify a Control Group

NAME

Control group name (Group Name in AIM*Historian Configurator)

Describe a Control Group

DESC

Descriptor (Group Descriptor in AIM*Historian Configurator)

Specify RTPs and Messages Controlled by the Control Group

TAG

Controlled RTP

MSGNAME

Controlled message (Tag, Msg Group, and Msg Name in

AIM*Historian Configurator)

Specify Trigger RTPs for a Control Group

TAG

260

Trigger RTP (e.g., TAG <RTP> <trigger type> <threshold>)

(Trigger Tag and Trigger Threshold for ON and OFF, BAD and OK,
and FAST and SLOW states in AIM*Historian Configurator)

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Control Group Attribute Descriptions

Table E-10 describes the attributes of the Control Group component.
Table E-10. Control Group Component Attributes

Attribute
NAME

DESC

MSGNAME

TAG

Description
Control group name of up to 10 (FH_GROUPNAME_LEN) characters.
Default: None
Actions: CREATE GETQTY GET DEL
Control group descriptor of up to 32 (FH_DESCRIPTOR_LEN) characters.
Default: None
Actions: GETQTY GET PUT MOD
Enclose the attribute value in quotation marks if blank spaces are to be
included in the description.
Message to be controlled, consisting of message group and message name,
separated by a space. The message group and message name must already
exist. Controlled messages can only be switched between the on and off
states.
The maximum number of controlled members you can define per control
group is defined by the MAXCGENTS attribute for the AIM*Historian
instance.
Default: None
Actions: GETQTY GET PUT DEL
If a controlled RTP, TAG is defined as follows:
TAG <ControlledRTP>
where:
<ControlledRTP> is the name of the RTP to be controlled, which must
already exist.
Example: TAG UC01_LEAD:SINE.PNT
If a trigger RTP, TAG is defined as follows:
TAG <TriggerRTP> <TriggerType> <Threshold>
where:
<TriggerRTP> is the trigger RTP, which must already exist.
<TriggerType> is onoff, badok, or fastslow. The onoff trigger applies to all
controlled RTPs and messages in the group. The badok and fastslow triggers
only apply to controlled RTPs in the group.
<Threshold> is a floating point value which governs when state changes
occur. Transitions in the trigger RTP value to less than threshold result in the
controlled messages and RTPs going to the off, ok, or slow state according to
the trigger type. Transitions in the trigger RTP value to greater than or equal
to threshold result in the controlled messages and RTPs going to the on, bad,
or fast state according to the trigger type.
Default: None
Actions: GETQTY GET PUT DEL

261

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Table E-10. Control Group Component Attributes (Continued)

Attribute
TAG
(Example)

262

Description
Example: To turn on all controlled RTPs and messages in the control group
when UC01_LEAD:SINE.MEAS transitions to a value greater than or equal
to 1.0:
TAG UC01_LEAD:SINE.MEAS onoff 1.0
consists of the RTP name, trigger type, and threshold, separated by spaces.
The trigger type can be: onoff, badok, or fastslow. The threshold governs
when state changes occur. Transitions in the trigger RTP value to less than
threshold result in the controlled messages and RTPs going to the off, ok, or
slow state according to the trigger type. Transitions in the trigger RTP value
to greater than or equal to threshold result in the controlled messages and
RTPs going to the on, bad, or fast state according to the trigger type.
Controlled messages do not have badok or fastslow states.
Whether a controlled or trigger RTP, the RTP must already exist.
The maximum number of controlled members you can define per control
group is defined by the MAXCGENTS attribute for the AIM*Historian
instance.

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Reduction Group Component

A reduction group supports the retrieval of reduction data by libhist.a applications, including
AIM*API applications which call an_hist_values(). The reduction group contains all the information needed to translate a function call by a libhist.a application for reduced data to the
AIM*Historian access methods.
NOTE

Reduction groups are NOT required to retrieve reduced data from the
AIM*Historian database, whether by reducing on-the-fly or by retrieving already
reduced data from the reduction data files, except as mentioned above. For
additional information, see Configuring Reduction Intervals and Managing RTP
Data Files on page 218.

Reduction Group Component How To

Identify a Reduction Group

NAME

Reduction group name (Group Name in AIM*Historian Configurator)

Describe a Reduction Group

DESC

Descriptor (Group Descriptor in AIM*Historian Configurator)

Specify RTPs in the Reduction Group

TAG

RTP in the reduction group (Tag in AIM*Historian Configurator)

Specify a Reduction Operation

OPER

Operation (OPER <operation name> <operation type>)

(Operation Name and Operation Type, in AIM*Historian Configurator)

Specify the Reduction Frequency (time between reduced values)

FREQ

Reduction frequency

FREQUNITS

Reduction frequency units (Frequency and Frequency Units, in

AIM*Historian Configurator)

Specify the Percentage of Good Values Required for a Reduced Value

PCTVALID

Percent valid (PercentValid, in AIM*Historian Configurator)

263

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Reduction Group Attribute Descriptions

Table E-11 describes the attributes of the Reduction Group component.
Table E-11. Reduction Group Component Attributes

Attribute
NAME

DESC

EXPORT

FREQ

FREQUNITS

264

Description
Group name of up to 10 characters (FH_GROUPNAME_LEN).
Default: None
Actions: CREATE GETQTY GET DEL
Reduction group descriptor of up to 32 (FH_DESCRIPTOR_LEN) characters.
Default: None
Actions: GETQTY GET PUT MOD
Enclose the attribute value in quotation marks if blank spaces are to be included
in the description.
Specifies whether the groups reduced values are to be exported to a database
using the Export to Oracle option (see Appendix G Exporting to Oracle).
If no, FH_NO, 0, NO.
If yes, FH_YES, 1, YES.
Default: NO (0)
Actions: GETQTY GET PUT MOD
The EXPORT attribute is not supported by AIM*Historian Configurator,
but must be batched in from a configuration input file (*.inp), as described in
Configuration Using Input Text Files on page 64.
Reduction frequency is the time interval over which samples get reduced to
generate one value. Its units are specified by FREQUNITS.
Example: For hourly averages, specify a FREQ of 1 and FREQUNITS of
HOURS (4).
Default: 1
Actions: GETQTY GET PUT MOD
Frequency units:
Milliseconds: FH_REDUC_UNIT_MILLI,1, MSECS
Seconds: FH_REDUC_UNIT_SEC,2,SECONDS
Minutes: FH_REDUC_UNIT_MIN,3, MINUTES
Hours: FH_REDUC_UNIT_HOUR,4, HOURS
Days: FH_REDUC_UNIT_DAY,5, DAYS
Default: SECONDS (2)
Actions: GETQTY GET PUT MOD

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Table E-11. Reduction Group Component Attributes (Continued)

Attribute
OPER

PCTVALID

TAG

Description
Name and type of reduction operation, separated by a space. The operation
name is user-defined and can be up to 18 (FH_OPER_NAME_LEN)
characters.
The operation type is one of the following:
Sum: FH_A_OPER_SUM,SUM
Average: FH_A_OPER-AVG, AVG
Maximum: FH_A_OPER_MAX, MAX
Minimum: FH_A_OPER_MIN, MIN
Standard deviation: FH_A_OPER_STDV, STDV
Kurtosis: FH_A_OPER_KURT, KURT
Histogram: FH_A_OPER_HIST, HIST
AIM* Historian does not support the histogram reduction.
User-defined: FH_A_OPER_USER, USER
AIM*Historian does not support the user reduction in reduction groups.
Default: None
Actions: GETQTY GET PUT MOD DEL
For example, to define an average reduction named myaverage,
specify: myaverage avg
Percentage (0 to 100) of values within a reduction interval that must be valid for
the corresponding reduced value to be considered valid. A pctvalid of zero
means always consider the reduced value to be valid. A value is considered
OK, that is, valid, if the corresponding status word is as follows (bit 0 is least
significant bit):
The value type (bits 0-4) must be one supported by AIM*Historian reduction;
that is, a numeric type:
2 (INTEGER), 3 (FLOAT), 5 (BOOLEAN), 6 (LONG)
22 (SHORT_ARRAY) to 26 (DOUBLE_ARRAY), or
28 (USHORT_ARRAY) to 30 (ULONG_ARRAY).
The BAD bit (bit 8) must be 0.
If the value is the result of an MDE insertion, that is, if the status only
contains the value type, the status bit checks are not done, and those values are
considered valid.
Default: 0
Actions: GETQTY GET PUT MOD
Name of a RTP to be included in the reduction group. The RTP must already
exist.
The maximum number of RTP entries you can define per reduction group is
defined by the MAXRGENTS attribute for the AIM*Historian instance.
Defaults: None
Actions: GETQTY GET PUT DEL

265

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Note on Time Stamps

AIM*Historian gives you the ability to store time stamps of collected data in either I/A Series
time or UTC format. The collectors convert the time stamps before storing the data in the
instance based on the time settings.
A time stamp conversion only needs to be considered when there are collectors with stations that
have a different time setting than the data storage format indicated by the IATIME parameter. A
common example is an off-platform AIM*Historian instance storing time stamps in UTC format
and receiving data from one or more remote I/A Series collectors. The reverse example is an I/O
Gate collector on an off-platform station sending data to an instance that stores time stamps in
I/A Series format.
Time stamps are displayed from the client machines frame of reference. For example, a value is
recorded on the instance machine which is set to I/A Series time and is stamped 2:00 p.m. A
client machine in the next time zone displays the time stamp as 1:00 p.m., the time when the
value was recorded at the client machine.
You must use UTC (IATIME = NO) if any collectors or client applications are in a different time
zone than the instance.
In general, it is recommended that an AIM*Historian instance store real-time data in the
format native to its host machine. You must configure the AIM*Historian instance to store time
stamps in UTC when collectors or client applications are in different time zones. Because
I/A Series time stamps do not contain any information about time zone or daylight savings time,
the conversion relies on the correct configuration of the instance and collector time settings.
! CAUTION
The configuration of time settings is not difficult, but it must be done carefully
because there is no protection against configuration errors.

IATIME Parameter Change

The IATIME parameter controls what format the data is to be stored in the instance. This is the
only time setting parameter that applies to the instance itself. If it is set to YES, the instance stores
time stamps in I/A Series format. If it is set to NO, instance storage is in UTC format. If the
parameter is omitted, it defaults to NO.
To set I/A Series time using histbatch, include the following input line:
1 PUT AIMHIST hist01 IATIME yes

266

Appendix E. AIM*Historian Component Attributes

B0193YL Rev E

Collector Time Format

A collector delivers time stamp information to the instance in I/A Series format or in UTC format
as specified by the instance IATIME parameter. If the collector machine has I/A Series time, but
the instance IATIME = NO, the collector adjusts the time stamp to UTC format. If the collector
machine does not have I/A Series time, but the instance IATIME = YES, the collector adjusts the
time stamp to I/A Series format. Otherwise, the collector does not adjust the time stamp before
sending the data to the instance.

TZ and DST Parameters

TZ and DST parameters must be set the same for all LOCAL collectors, including the local
default collector, REALTIME_SERVER, MESSAGE_SERVER, and local I/O Gate collectors.
Different values for one of the local collectors may yield unpredictable results.

TZ Parameter
The TZ parameter specifies in which Time Zone the collector actually resides. If a time stamp
conversion takes place, this parameter and the DST parameter determine the quantity of the
adjustment. For collectors on non-I/A Series stations, TZ must be configured to match the
machines system settings.
It is important the TZ parameter also reflects the physical location of an I/A Series collector
machine, even when the machine settings may be different as dictated by I/A Series rules
(GMT with DST off).
To specify the TZ to the Eastern US time zone using histbatch, include the following input line:
1 PUT STATION hist01 GMT_MINUS_5

DST Parameter
The DST parameter specifies whether or not an additional adjustment needs to be made for
Daylight Savings Time. The parameter is not used on non-I/A Series collector stations. The
switch to and from daylight savings time is done automatically by the operating system. I/O Gate
collectors obtain the current setting from the system.
On I/A Series stations, however, the switch to and from DST must be done manually. I/A Series
systems require the operator to manually advance or set back the internal system clock by one
hour when DST goes into or out of effect. This change causes what appears to be time stamp
irregularities in AIM*Historian data. Until I/A Series timekeeping is redesigned, there is an
apparent one hour data gap when the time is set forward to accommodate DST, and there is one
hour of no data collection when the change from DST is made.
Beginning with AIM*AT 3.0.2, this has been resolved for off-platform instances collecting in
UTC time format.

267

B0193YL Rev E

Appendix E. AIM*Historian Component Attributes

Manual intervention is still required to change the DST parameter for remote I/A Series
collectors. For collectors using I/A Series time, use the following steps when the time changes.
Execute these instructions at a time of day that causes the least impact on your data.
1. Use the AIM*Historian Manager to turn off all remote I/A Series collectors that
feed data to Historian instances configured to collect in UTC time format
(IATIME = NO).
It is not necessary to turn the instances off.
2. Using the I/A Series master timekeeper display, change the I/A Series system clock as
described in the I/A Series documentation.
3. While the remote I/A collectors are still off, use an AIM*Historian Configurator,
histcfg, or histbatch to change the collectors DST parameter.
In the spring, at the transition to daylight savings time, change DST to YES (1),
and in fall, at the transition back to standard time, change the DST parameter to
NO (0).
The following is an example of a histbatch .inp file used to transition to daylight
savings time:
CREATE SESSION hist01 SESKEY hist01 rw
1 PUT STATION remcol1 DST yes
1 PUT STATION remcol2 DST yes
1 DEL SESSION hist01 SESKEY hist01 commit
EXIT

4. Turn the collectors on.

Migrating Data from Previous Versions

The IATIME default is No if you were collecting in I/A Series Time with FoxHistory Version 2.0.
If you are migrating to AIM*Historian and want to continue collecting in I/A Series Time, you
must set the attribute to YES in the AIM*Historian instance.

268

Appendix F. Sizing Guidelines

This appendix provides guidelines for determining the amount of disk space required to hold
AIM*Historian database files.
There are several control parameters in the AIM*Historian that need to be configured according
to the your specific system requirements and constraints. The default values of these variables are
often not optimal for all users.
The Excel spreadsheet HistSize.xls and the Microsoft Word document HistSize.doc in the
/Documents directory on the AIM*AT CD can be used to estimate several configuration
parameters.

Sizing Factors
AIM*Historian requires 50 megabytes of fixed disk space for software and 20 megabytes for each
AIM*Historian instance configured with the default maximum number of RTPs.
Use the following guidelines to estimate additional disk space required for RTPs and event message data.

RTP Samples
NOTE

You can configure AIM*Historian to compress all RTP Sample database files in an
instance (see COMPRESS listed in Table E-4 beginning). If you plan to use the
compression feature, reduce the following estimate by 60%.
Each RTP sample with an I/A Series value type requires 16 bytes:
Time stamp (seconds): 4 bytes
Milliseconds: 2 bytes

Status: 2 bytes
Quality: 4 bytes
Value: 4 bytes.
For value types that require more or less than 4 bytes for the value, adjust the sizing
accordingly. For example, if the value type is a double array with three elements per value,
you need (8 x 3 =) 24 bytes per value, or 36 bytes per sample.

269

B0193YL Rev E

Appendix F. Sizing Guidelines

Reduction Values
Each reduction value in a slow, medium or fast reduction file requires 52 bytes.

Event Messages
Each event message requires space for a message header built by AIM*Historian upon
message insertion and for a message body.
Each message header of type USR_FH_MSG_DBS_REC defined in aimhistorian.h requires:
Record size: 4 bytes

LRC: 4 bytes

Message number: 4 bytes

Time stamp (seconds): 4 bytes

Message group (+null): up to 33 bytes (plus pad bytes to ensure word boundary)

Message name (+null): up to 33 bytes (plus pad bytes to ensure word boundary)
Number of keys: 4 bytes

Offset to message body: 4 bytes

Array of key offsets: 4 bytes per message key.
Each message body requires an amount of disk space which depends on the message
definition. For example, for message group I/A Series message name unknown, with the
DEFN attribute values as follows:

Group = 1, Y, string, 32 +null = up to 33 bytes (plus pad bytes to ensure word

boundary)
Message= 2, Y, string, 32 +null = up to 33 bytes (plus pad bytes to ensure word
boundary)
Time = 3, Y, long, 1 4 bytes
Text = 4, Y, string, 1025 +null = up to 1026 bytes (plus pad bytes to ensure word
boundary).

270

Appendix F. Sizing Guidelines

B0193YL Rev E

Other Sizing Considerations

Finding an Appropriate Data Collection Rate
A very important consideration is how much data to collect in a particular time frame, and how to
best control the rate of data collection. Not collecting enough data causes problems that are well
understood by the plant engineer and operators, such as trends not showing critical deviations
and insufficiently accurate reports.
Collecting too much data also has drawbacks that may become quite severe in a poor
configuration:
Disk space is wasted

Data retrieval speed is slow

Increased computer resource requirements

Overall system performance can be affected by a fast point collection

Excessive maintenance is required to transfer data to make room for new data.
Users have the tendency to over configure the rate of data collection, because determining an
optimal configuration can be quite time consuming. The process requires knowledge of the
properties of each variable and a good judgement about the usage of the resulting stream of data.
The result is often a very ambitious configuration, just to make sure...
No formula has been determined to estimate the greatest possible combined sample rate that any
particular system can handle. It would depend on many variables particular to the individual systems, like platform operating system, machine type, processor speed, disk speed, requirements of
other applications running on the machine, and so on. An indication of a configuration that is
too ambitious may be a degradation of the overall system performance. Also, when data samples
for any particular point continue to be collected at a slower rate than expected considering the
collected delta and collection rate, that may be an indication that the RTP collection is maxed out.

Data Collection Rate Parameters

The AIM Historian provides several control parameters to throttle the data collection rate. These
include the change delta (deadband), fast and slow collection frequencies and the maximum time
between samples.

271

B0193YL Rev E

Appendix F. Sizing Guidelines

Read Delta

The RTP Read Delta attribute (READDELTA) specifies the minimum change of a variable relative to the previous collected value after which a collection occurs. It is specified in engineering
units. For example, if the delta is configured to 8.7 and the last collected value was 432.1, no
value is collected until the value becomes either greater than or equal to 440.8 or less than or
equal to 423.4. The delta can be modified at any time and becomes effective immediately. A
change delta value is assigned to every variable that has data collected by AIM*Historian.
The delta should be the key controlling variable for the data collection rate. If the delta is properly
configured, the other variables are, in many cases, of secondary importance. Unfortunately, the
delta can be the most difficult of the controlling variables to configure. It requires the knowledge,
on a per-point basis, how much of a change in the points value is significant enough to log a data
value in the database. If the delta is set too high, significant changes may be missed. If the delta is
too low, too many redundant data values are collected. If the delta is configured to a value smaller
than the transmitters accuracy, a stream of noise may be collected that has no practical value.
Another consideration should be the use of the data. If the main purpose for data collection is
trend displays, then the deadband should not be much smaller than the equivalent of the height
of one pixel. Smaller changes would not be visible on the trends unless the read-out bar is used
frequently to determine the points exact value at certain times.
NOTE

The AIM*Historian Deadband Wizard can also be used to estimate disk storage
requirements. See Optimizing Disk Space Usage for RTP Files on page 133.
Collection Frequency Rates

There are two collection frequencies:

Fast Collection Frequency (determined by two attributes: FASTFREQ and

FFREQUNITS)
Slow Collection Frequency (determined by two attributes: SLOWFREQ and
SFREQUNITS)
Only one of these parameters is in effect at any time, and the switch from one to the other can be
accomplished by means of a control group. By default, the fast frequency is in effect, and in many
implementations there is little need to ever switch to the slow frequency.
The collection frequency is the second most important parameter to control the data collection
rate. If the frequency is set to 20 seconds, no data points are collected for at least 20 seconds after
the previous sample, even if the point value has exceeded the deadband in the meantime.
In many cases, making the collection frequency the controlling variable is used as a convenient
alternative to fine-tuning the individual deltas. The deltas could be set small, and the frequency to
a value that allows for an adequate resolution. The approach overrides the advantages of the
change-driven data concept, and may cause an internal high data flow, because the data still arrive
at the historian at a rate dictated by the small delta, but most values are simply discarded until the
next sample time has arrived.

272

Appendix F. Sizing Guidelines

B0193YL Rev E

Maximum Time Between Samples

This parameter is set with two attributes, MXSAMTIME and MXSAMUNITS. It can be considered to have the opposite functionality as the collection frequencies. If it is set to 3600 seconds, it
guarantees a value is placed in the database at least every hour, regardless of whether the value has
changed more than the delta since the last collection.

Which Points to Collect

If you are never going to look back at a points data, then dont collect it! The selection, of course,
is not always easy to make, and again, the result is often a configuration with many points whose
data just fill up storage devices but have no practical value because they are never referred to again.
Before starting the point configuration, take enough time to decide which points to collect and
which to ignore.

Specifying RTP File Sizes

The values for all points are combined and collected into the same RTP files. A new RTP file is
started whenever the active one becomes full, or when a specified time has expired. A new file is
also started on every reboot.
The finished files are eventually repacked, which shrinks their sizes to about one-third without
compression, and by an additional 40% to 60% when compression is on.
Data retrieval is less efficient from a large number of small files compared to retrieving from a
small number of large files. Every file contains some overhead that is not used for sample data
storage. This reserved file space amounts to about 120 KB per file. With small files, this would be
a considerable amount of wasted space. With larger files, it becomes less significant. For example,
for 1 MB files, there is about 12% overhead; for 10 MB files, the overhead is just over 1%, a much
more tolerable use of space.
However, files that are too large can also cause severe performance problems. When the RTP file
does not comfortably fit into physical memory, the disk activity increases dramatically to a point
where the entire system performance degrades. This is particularly obvious when RTP files are
being repacked, at which time it is crucial to keep three of the RTP files in memory: the active one
for continued fast data collection, the file to be repacked, and the resulting repacked file. Of
course, there must still be enough memory for all the other applications to run.

273

B0193YL Rev E

Appendix F. Sizing Guidelines

RTP file size is controlled by the ARCHSIZE and RTTIME parameters.

Archive Size (ARCHSIZE)

The ARCHSIZE attribute controls the size of the RTP files. When the files are first created to
become the active RTP files, their size is three times that configured value. When the files are
repacked, they shrink to about this configured size. If compression is on, the files are shrunk even
more, to about half of the configured size. Furthermore, files are smaller when a new RTP file is
started not because it was full, but because its retention time has expired (see RTTIME below).
Experience shows that a good compromise is to configure ARCHSIZE to a value that results in
about one or two RTP file per day. To estimate that size, determine the combined sample rate of
all points per day. For example, if there are 40 points configured at a collection rate of 2 seconds,
200 points at 20 seconds, and 900 points at 60 seconds, the combined daily sample rate is (provided the change-driven samples actually come in at that rate):
Combined Rate

= 86400 sec/day * (40 vals/2 sec + 200 vals/20 sec + 840 vals/60 sec)
= 3,801,600 vals/day.

Every value occupies 16 bytes in a repacked file, so that ARCHSIZE should be 60,825,600 or
about 60 MB, if you wanted to generate about one RTP file per day. Half of that (ARCHSIZE =
30,000,000) would then result in about two RTP files per day.
The largest recommended ARCHSIZE can be estimated to about 1/8 of the physical memory
size. For example, if your computer has 256 MB of memory, ARCHSIZE should not be
configured greater than 32 MB.
Real-Time Retention Time (RTTIME)

RTTIME is the interval at which new RTP files are generated, regardless of whether the previous
active RTP file was full. When a new file is started, the previous file is repacked and shrunk to the
smallest size necessary to accommodate all collected data values. A good value for RTTIME is
usually 86400 seconds (1 day).

274

Appendix G. Exporting to Oracle

This appendix provides guidelines for exporting AIM*Historian data to an Oracle database so
that the data may be accessed by applications.
Exporting data from one or more instances of AIM*Historian to an Oracle database is
accomplished by three AIM*Historian programs:
HistExport

HistExport generates Oracle .sql (for export messages only) and .ctl files
until the remaining allotted hard drive space is used.

HistMove

HistMove copies the .sql and .ctl files to the Oracle host using standard
methods like ftp or copy, and deletes them from the AIM*Historian host
after the .sql and .ctl files have been copied successfully to the Oracle host.
Note that the .sql and .ctl files cannot be copied when the network fails or
when the partition on the Oracle host is full.

Hist2Oracle

Hist2Oracle, which runs on the Oracle host, initially executes SQL*Plus

for all created .sql files, including a standard createtable.sql script file
containing statements that create all static tables. Hist2Oracle then
executes SQL*Plus for the .sql files previously generated by HistExport
for dynamic message tables only.
SQL*Loader is also executed by Hist2Oracle for each .ctl file copied onto the Oracle host. All files
are removed after a successful insertion.
Scheduling of HistExport and HistMove is specified in the export.ini file on the
AIM*Historian host.
The relationship between the HistExport, HistMove, and Hist2Oracle programs, and the functions they perform are illustrated in Figure G-1.

275

B0193YL Rev E

Appendix G. Exporting to Oracle

AIM*Historian Host
Configuration
Information
AIM*Historian
Instance

Historized
Data

HistExport
Creates export files

Exported
Data

Instance/Export
Directory
(Holds the .ctl, .sql,
.dat and .tim files)

Frequency at which
data must be exported

export.ini
(Export schedule and
Oracle destination)

Export
Files

HistMove
Moves the export files
from AIM*Historian
to Oracle

Oracle Database Host

Hist2Oracle

Oracle Database

SQL*Plus is executed for

every .sql file that creates
tables in the database.
SQL*Loader is executed for
every .ctl file that loads
exported data into the tables.
Updates data, log, and
reject directories.

/<export directory>
/data/<machine>
/<instance>directory
(Stores the .ctl and
.sql files. You can
specify the path.)

Figure G-1. A Summary of the AIM*Historian Data Export Process

276

Appendix G. Exporting to Oracle

B0193YL Rev E

HistExport
HistExport is installed on the same system as the AIM*Historian instance. It starts automatically
when the hosted is booted and runs as a daemon on Solaris and as a service on Windows NT. The
program runs continuously until stopped. The program can be restarted from the command line.
HistExport checks the export.ini configuration file for processing frequencies. When the specified
interval has elapsed, HistExport creates .sql files (for export messages only) and .ctl files for all
RTPs, reduction groups and messages that are configured to be exported. The resulting .sql and
.ctl files are stored in the <instance>/export directory (for example, /opt/aim/inst/hist01/export).
HistExport uses the export.ini file to determine the export frequency of the sample data. The following steps take place at export time:
1. HistExport uses the saved time stamp of a specific point in the sample.dat file to
determine when the last data export took place. If the sample.dat file is not present,
HistExport uses the export.ini file to determine how far back it has to go in order to
start exporting samples.
2. HistExport creates three types of .ctl files that contain the table columns definitions
and the exported data: one having the name format rtps_pts_<time>.ctl, another having the name format rtps_strings_<time>.ctl and the last one having the name format
rtps_numbers_<time>.ctl.
3. HistExport updates the time stamp for a specific point in the sample.dat file with the
last exported time stamp.
HistExport uses the export.ini file to determine the export frequency of the message data. The
following steps take place at export time:
1. HistExport uses the saved time stamp for a specific message in the CreatedMsg.dat file
to determine when the last data export took place. If the CreatedMsg.dat is not
present, it uses the export.ini file to determine how far back it has to start exporting
messages.
2. HistExport creates two types of .ctl files that contain the table column definitions and
the exported data: one having the name format msg_def_<time>.ctl and the other one
having the name format msg_data_<msggroup>_<msgname>_<time>.ctl.
3. HistExport updates a specific message in the CreatedMsg.dat file with its own last
exported time stamp.

277

B0193YL Rev E

Appendix G. Exporting to Oracle

HistExport uses the export.ini file to determine the export frequency of the sample reduction.
The following steps take place at export time:
1. HistExport uses the saved time stamp in the red_<rgroup>.tim file to determine when
the last data export took place. If red_<rgroup>.tim is not present, it uses the
export.ini file to determine how far back it has to go to start exporting samples.
2. HistExport creates a rgroup_data_<time>.ctl file that contains the exported data.
3. HistExport updates red_<rgroup>.tim file with the last exported time stamp.
NOTE

Export files are not copied when the network connection is broken. The creation of
export files resumes as soon as the network connection is reestablished and export
files are copied to the Oracle system (and are removed from the <instance>/export)
to reduce disk usage. Note that HistExport remembers when the last export finishes
and starts a new export based upon the last stored export time.

HistMove
HistMove is responsible for copying the .ctl, and .sql files from the AIM*Historian host to the
Oracle host as well as deleting them from the AIM*Historian host after a successful copy.
Synchronization between HistExport and HistMove is needed in order to ensure a successful
transfer of data files to the Oracle host. This is accomplished by allowing HistMove to be invoked
by HistExport following the generation of necessary files. If HistMove is already active,
HistExport signals HistMove to transfer data files to the Oracle host.
HistMove reads the login specifications from the export.ini. A .loading file is created by
HistMove in a /opt/dbexport/data/<host>/<instance> directory, or another directory specified by
the user, on the Oracle host before all .sql and .ctl files are copied onto it. The existence of the
.loading file signifies that HistMove is active and is in the process of copying files to the Oracle
server.
The HistMove program copies the files to the /opt/dbexport/data/<host>/<instance> directory, or
another directory specified by the user, in the order that they are created. A file is removed from
the <instance>/export directory on the AIM*Historian instance host after it is successfully copied
to the Oracle host.
After all .sql and .ctl files have been copied, the .loading file is removed from the Oracle host.
NOTE

The export files cannot be moved or processed when the network is down.
This results in an increase of disk space usage on the AIM*Historian host, which
eventually causes the creation of new .ctl files to end. Files are copied again as soon
as the network is back up, and export files creation resumes as there are files moved
to the Oracle system.

278

Appendix G. Exporting to Oracle

B0193YL Rev E

Hist2Oracle
Hist2Oracle is responsible for processing the .ctl, and .sql file on the Oracle host. The program is
configured to run as a daemon at boot time and runs continuously.
To ensure synchronization with HistMove, Hist2Oracle checks for the existence of the
.loading file in /opt/dbexport/data/<historian server>/<instance> on a Solaris server, or
d:\opt\dbexport\data\<historian server>\<instance> on a Windows NT system. You can specify
another directory.
In the event that the .loading is present, it signifies that HistMove is still active and still copying
files to the Oracle host. If the .loading file does not exist in the
/opt/dbexport/data/<host>/<instance> directory, the <instance> directory is renamed to allow
Hist2Oracle to process all files.
Hist2Oracle executes SQL*Plus with an .sql file for any message table being created and then
executes SQL*Loader with every .ctl file. After the SQL*Plus or SQL*Loader are executed
successfully, the file is removed from the /opt/dbexport/data/<host>/<instance> directory.
If the data insert is not successful, rejected rows are copied to .bad files within the reject directory.

Data Export Configuration Files

This section describes the files used to configure the data export from AIM*Historian to Oracle.
The export.ini and Msg.ini files are placed in the AIM*AT program directory (/opt/aim/bin on a
Solaris server or d:\Program Files\AIM\bin on a Windows NT system) as part of the installation
process. The Hist2Oracle.ini is located on the Oracle host. These keyword files can be created
and edited with a text editor such as vi or Notepad.

The export.ini File

HistExport checks the export.ini configuration file for processing frequencies. When specified
interval has elapsed, HistExport creates .sql files (for export messages only) and .ctl files for all
RTPs, reduction groups and messages that are configured to be exported. The following listing is
a sample configuration.
[HistExport]

#Name of section

Log=1

#Activates information logging to the histexport.log; when

#equal to 0, logging is deactivated.

MsgFreq=3600

#Message frequency ... export takes place every 3600 seconds

SmplFreq=3600

#RTP frequency ... export takes place every 3600 seconds

RgrpFreq=3600

#Reduction group frequency in seconds

Delay=60

#Delay in seconds; allows retrieval of historical data up to

#(current time - delay).

NO_SUM_NO_KURT=1

#When equal to 1 the sum and the Kurtosis are not calculated as
#reduced values. Otherwise, it is equal to 0.

[HistMove]

#Name of section

Log =1

#Activates information logging to the histmove.log;

#when equal to #0, logging is deactivated.

Program= ftp or copy

#Transfer program used to copy files from AIM*Historian machine

#to the Oracle server machine.

279

B0193YL Rev E
DstDir=/opt/oracle

Appendix G. Exporting to Oracle

#If the transfer program is "copy", DstDir is the destination
#mount point on the AIM*Historian machine representing the
#destination directory on the Oracle Server machine. If the
#transfer program is ftp, DstDir represents the destination
#directory on the Oracle Server machine.

LogName=anonymous

#user name for ftp

Password=mypassword

#password relating to the LogName for ftp

DatabaseServer=152.155.155.99

#Name or TCP/IP address of Oracle machine

[RepeatDataLoad]

#Name of section

DaysBack=2

#Number of days you want to go back to export data when the cycle
#runs the very first time.

The msg.ini File

The msg.ini file is used to designate the messages to be exported. The following listing is a sample
configuration:
[<instance_name>]
iaalarm_alarmmesg=1

#Message will be exported

iaalarm_alackmesg=0

#Message is not exported

The hist2oracle.ini File

The hist2oracle.ini file contains the Oracle database logging information. The following is a
sample configuration:
H2O_ROOTDIR=D:\opt\dbexport

#Root directory for export files

H2O_DBAPASSWORD=system

#DBA password to create user account

H2O_DBALOGIN=manager

#DBA login to create user account

H2O_FREQ=600

#Frequency in seconds

H2O_DATADIR=D:\opt\data

#Optional: data directory; when specified

#overrides the path of H2O_ROOTDIR

H2O_LOGDIR= D:\opt\log

#Optional: log files directories; if not

#specified defaults to D:\opt\dbexport\log

H2O_REJECTDIR=D:\opt\reject

#Optional: reject files directory; if not

#specified defaults to
#D:\opt\dbexport\reject

280

KEEP_LOGFILE=1

#Reserved for future use

KEEP_DATAFILE=1

#Reserved for future use

Appendix G. Exporting to Oracle

B0193YL Rev E

The createtables.sql Script File

The createTables.sql script file is executed initially by the Hist2Oracle executable and contains
the following DDL statements:
CREATE TABLE MSGS (
MSGCFG_ID

NUMBER(10),

MSGGROUP

VARCHAR2(128) NOT NULL,

MSGNAME

VARCHAR2(128) NOT NULL,

MSG_TABLE

VARCHAR2(128),

CONSTRAINT MSGS_PK PRIMARY KEY (MSGCFG_ID)

);
CREATE TABLE RTPS (
POINT_ID

NUMBER(10),

POINT_NAME

VARCHAR2(128),

POINT_TYPE

NUMBER(10),

CONSTRAINT RTPS_PK PRIMARY KEY (POINT_ID)

);
CREATE TABLE RTPS_STRINGS (
POINT_ID

NUMBER(10) REFERENCES RTPS(POINT_ID),

TIME_STAMP

DATE,

MSEC

NUMBER(3),

VALUE

VARCHAR2(1024),

STATUS

NUMBER(10),

QUALITY

NUMBER(10),

CONSTRAINT RTPS_STRINGS_PK
PRIMARY KEY (POINT_ID, TIME_STAMP, MSEC)
);
CREATE TABLE RTPS_NUMBERS (
POINT_ID

NUMBER(10) REFERENCES RTPS(POINT_ID),

TIME_STAMP

DATE,

MSEC

NUMBER(3),

VALUE

NUMBER,

STATUS

NUMBER(10),

QUALITY

NUMBER(10),

CONSTRAINT RTPS_NUMBERS_PK
PRIMARY KEY (POINT_ID, TIME_STAMP, MSEC)
);

281

B0193YL Rev E

Appendix G. Exporting to Oracle

CREATE TABLE RGROUP_DATA (

RGROUP_NAME

VARCHAR2(128),

POINT_ID

NUMBER(10) REFERENCES RTPS(POINT_ID),

TIME_STAMP

DATE,

PERCENT_VALID

NUMBER(3),

SUM

NUMBER NULL,

AVG

NUMBER NULL,

MAX

NUMBER NULL,

MIN

NUMBER NULL,

STDV

NUMBER NULL,

KURT

NUMBER NULL,

STATUS

NUMBER(10) NULL,

QUALITY

NUMBER(10) NULL,

CONSTRAINT RGROUP_DATA_PK
PRIMARY KEY (RGROUP_NAME, POINT_ID, TIME_STAMP)
);

Created Files
The are two files updated when RTPs or messages are exported:
createdMsg.dat

The createdMsg.dat file is a non-viewable file in binary format. The file is

used to store the last exported time stamp for each individual message,
whose name is comprised of the message group and message name
connected by an underscore as in the msg.ini file sample.
Each 260 bytes corresponds to one messagethe first 4 bytes contain the
time stamp and the remaining 256 bytes contain the message name.

sample.dat

282

The sample.dat file is a non-viewable file in binary format. It is used to

store the last exported time for each individual RTP. Each 4 bytes
represents a time stamp.

Appendix G. Exporting to Oracle

B0193YL Rev E

Database Tables
This section provides examples of the different tables created by Hist2Oracle to store exported
data. Each example begins with the relevant AIM*Historian configuration as shown in the form
of a configuration input file (<Instance>.inp) and sample column values. The example then shows
the name and contents of the resulting control files and, where appropriate, the name and content
of resulting SQL scripts.
Table G-1 summarizes the general naming convention used to differentiate the type and purpose
of several Oracle database tables that are created to store AIM*Historian data.
NOTE

A one-to-one relationship exists between an Oracle user account and an

AIM*Historian instance. The name of the Oracle user account is based on the
<host>_<instance> name convention.

Table G-1. Oracle Database Tables Used to Store Historian Data

Database Table

Description

msgs
<msggroup>_<msgname>

rtps
rtps_strings
rtps_numbers
rgroup_data

A table listing all exported messages.

A separate table for each exported Message type holding all
messages of that type. The variable <msggroup> represents the
message group name. The variable <msgname> represents the
message name.
A table listing all exported RTPs.
A table listing all exported RTP values of type string.
A table listing all exported RTP values other than type string.
A table listing exported data for all reduction groups with the
EXPORT attribute set to TRUE.

Database Table: msgs

The msgs database table stores exported messages. Messages that can be uniquely identified by the
primary key msgcfg_id. Table G-2 describes the table structure.
Table G-2. Columns in the msgs Database Table

Column

Data Type and Size

msgcfg_id

number (10)

msggroup
msgname
msg_table

varchar2 (128)
varchar2 (128)
varchar2 (128)

Description
Message configuration ID also referred to as
message number; it would match the value of the
primary key msgcfg_id of the table name contained
in the msg_table field.
Message group name.
Message name.
The name of the message table where the message
values can be found.
283

B0193YL Rev E

Appendix G. Exporting to Oracle

Messages Table Example

AIM*Historian Configuration Input File
0 CREATE AIMHIST hist01
0 CREATE SESSION hist01 SESKEY hist01 rw
#
1 CREATE MSG "iaalarm alarmmesg"
DEFN "group

1,Y,string,32"

DEFN "message

2,Y,string,32"

DEFN "time

3,Y,long, 1"

DEFN "date_time

5,Y,string,21"

DEFN "letterbug

6,Y,string, 8"

DEFN "compound_name

7,Y,string,15"

DEFN "block_name

8,Y,string,15"

DEFN "point_name

9,Y,string,15"

DEFN "long_string

10,Y,string,1500"

Sample Column Values

Column

Value

msgcfg_id

44

msggroup

iaalarm

msgname

alarmmesg

msg_table

iaalarm_alarmmesg

Resulting Control File Name

msg_def_942850477.ctl

Resulting Control File Contents

load data
infile *
append
into table msgs
fields terminated by ',' optionally enclosed by '"'
(msgcfg_id, msggroup, msgname, msg_table)
begindata
44,"iaalarm","alarmmesg", "iaalarm_alarmmesg"

284

Appendix G. Exporting to Oracle

B0193YL Rev E

Database Table: <msggroup>_<msgname>

This database table stores data relating to all key definitions configured in the message group
section of the configuration file. Table rows can be accessed through the msgcfg_id primary key
field also found in the msgs table. The columns in this table have the same name and the same
sequence order as the keys configured for the message. Each message has its own table.

Message Name Table Example

Example Table Name
iaalarm_alarmmesg

NOTE

The <msggroup>_<msgname> table name can only contain alphanumeric and the
_ characters. HistExport will convert all other characters to _.
Table G-3 shows that six key definitions (columns) were configured for a specific message
referenced by the msgcfg_id field.
Table G-3. Columns in the <msggroup>_<msgname> Database Table

Column

Data Type and Size

msgcfg_id

number

msgtime
date_time
letterbug
compound_name
block_name
point_name
long_string

date
varchar2 (21)
varchar2 (8)
varchar2 (42)
varchar2 (42)
varchar2 (44)
varchar2 (1024)

Description
Message configuration ID also referred to as message number; matches the msgcfg_id field found in
the related msgs table.
Time that the message was inserted (in UTC).
Key 1
Key 2
Key 3
Key 4
Key 5
Key 6

285

B0193YL Rev E

Appendix G. Exporting to Oracle

AIM*Historian Configuration Input File

0 CREATE AIMHIST hist01
0 CREATE SESSION hist01 SESKEY hist01 rw
#
1 CREATE MSG

"iaalarm alarmmesg"

DEFN "group

1,Y,string,32"

DEFN "message

2,Y,string,32"

DEFN "time

3,Y,long, 1"

DEFN "date_time

5,Y,string,21"

DEFN "letterbug

6,Y,string, 8"

DEFN "compound_name

7,Y,string,15"

DEFN "block_name

8,Y,string,15"

DEFN "point_name

9,Y,string,15"

DEFN "long_string

10,Y,string,1500"

Sample Column Values

Column

Value

msgcfg_id

44

msgtime

12/10/99 01:09:51

date_time

12/10/99 01:10:51

letterbug

UC0001

compound_name

UC01_LEAD

block_name

SINE

point_name

MEAS

long_string

This is a message string.

Resulting SQL Script File Name

iaalarm_alarmmesg.sql

Resulting SQL Script File Contents

create table iaalarm_alarmmesg
( msgcfg_id number,
msgtime

date,

date_time varchar2(21),
letterbug varchar2(8),
compound_name varchar2(42),
block_name varchar2(42),
point_name varchar2(44),
long_string varchar2(1024));

286

Appendix G. Exporting to Oracle

B0193YL Rev E

Resulting Control File Name

msg_data_iaalarm_alarmmesg_942850477.ctl

Resulting Control File Contents

load data
infile *
append
into table iaalarm_alarmmesg
fields terminated by ',' optionally enclosed by '"'
( msgcfg_id,
msgtime,
date_time,
letterbug,
compound_name,
block_name,
point_name,
long_string)
begindata
44, "12/10/99 01:09:51", "12/10/99 01:10:51","UC0001","UC01_LEAD", "SINE",
"MEAS", "This is a message string"

Database Table: rtps

The rtps database table stores all RTPs exported from the AIM*Historian instance. The RTPs are
uniquely identified by the primary key point_id field. Table G-4 describes the columns in the
database table.
Table G-4. Columns in the rtps Database Table

Column

Data Type and Size

point_id

number (10)

point_name
eng_units
point_desc
point_type

varchar2 (128)
varchar2 (10)
varchar2 (32)
number (10)

Description
Point ID that refers to the RTP index; it would
match the value of the point_id field contained in
the rtp_strings or rtp_numbers table.
Point name.
Engineering unit.
Point descriptor.
Point type: If point is of type string, the new point
value will be inserted into the rtps_strings table,
otherwise the new point value will be stored in the
rtps_numbers table.

287

B0193YL Rev E

Appendix G. Exporting to Oracle

RTP Table Example

AIM*Historian Configuration Input File
0 CREATE AIMHIST hist01
0 CREATE SESSION hist01 SESKEY hist01 rw
#
1 CREATE POINT 16:AI01.PNT
1 PUT POINT 16:AI01.PNT TYPE FLOAT
DESC

"Neutralization B1613 PH"

AUDITUPD

NO

COLLECTOR

rtcol1

COLMETH

CONNECTED

ENGUNITS

PH

FASTFREQ

FFREQUNITS

MINUTES

HIRANGE

14.00000000

INITSTATE

ON

LORANGE

0.00000000

MXSAMTIME

3600

MXSAMUNITS

SECONDS

NAMEINCOL

1600:AI_1601.PNT

NUMELEMS

READDELTA

0.05000000

RSTRTSTATE

PREVIOUS

SFREQUNITS

MINUTES

SIZE

SLOWFREQ

TRGCHANGE

NO

Sample Column Values

Column

Value

point_id

11

point_name

16:AI01.PNT

eng_units

PH

point_desc

Neutralization B1613 PH

point_type

Resulting Control File Name

rtps_pts_942850477.ctl

288

Appendix G. Exporting to Oracle

B0193YL Rev E

Resulting Control File Contents

load data
infile *
append
into table rtps
fields terminated by ',' optionally enclosed by '"'
(point_id,
point_name,
eng_units,
point_desc,
point_type)
begindata
11, "16:AI01.PNT","PH", "Neutralization B1613 PH",3

Database Table: rtps_strings

The rtps_strings database table (Table G-5) stores data relating to all exported RTPs of
type string. These RTPs can be accessed through the point_id field in the rtps table (Table G-4).
Each row can be uniquely accessed through a primary key that combines the point_id,
time_stamp and msec.
Table G-5. Columns in the rtps_strings Database Table

Column

Data Type and Size

point_id

number (10)

time_stamp

date

msec

number (3)

value

varchar2 (1024)

status
quality

number (10)
number (10)

Description
Point ID that refers to the RTP index; it matches
the point_id field found in a related rtps table.
Time stamp indicating date and time (in UTC) at
which the point was collected (includes hh:mm:ss).
Indicates the milliseconds within the time_stamp at
which the point was collected.
String value of the point referred to by the point_id
field.
Status value.
Quality value.

289

B0193YL Rev E

Appendix G. Exporting to Oracle

String Type RTP Table Example

AIM*Historian Configuration Input File
0 CREATE AIMHIST hist01
0 CREATE SESSION hist01 SESKEY hist02 rw
#
1 CREATE POINT StringPtn
1 PUT POINT StringPtn TYPE STRING
DESC

"This is of type string"

AUDITUPD

NO

COLLECTOR

hist01

COLMETH

CONNECTED

ENGUNITS
FASTFREQ

FFREQUNITS

SECONDS

HIRANGE

100.00000000

INITSTATE

ON

LORANGE

0.00000000

MXSAMTIME

3600

MXSAMUNITS

SECONDS

NAMEINCOL

StringPtn

NUMELEMS

READDELTA

0.50000000

RSTRTSTATE

PREVIOUS

SFREQUNITS

SECONDS

SIZE

256

SLOWFREQ

TRGCHANGE

NO

Sample Column Values

Column

Data Type

point_id

11

time_stamp

12/05/99 01:05:23

msec

000

value

This is a string value for point StringPtn.

status

623

quality

Resulting Control File Name

rtps_strings_942850477.ctl

290

Appendix G. Exporting to Oracle

B0193YL Rev E

Resulting Control File Contents

load data
infile *
append
into rtps_strings
fields terminated by ',' optionally enclosed by '"'
(point_id,
time_stamp,
msec,
value,
status,
quality)
begindata
11, "12/05/99 01:05:23",000,"This is a string value",623,0

Database Table: rtps_numbers

The rtps_numbers database table (Table G-6) stores data relating to all exported RTPs of type
other than string. These RTPs can be accessed through the point_id field also found in the rtps
table (Table G-4). Each row can be uniquely accessed through a primary key that combines the
point_id, time_stamp and msec.
Table G-6. Columns in the rtps_numbers Database Table

Column

Data Type and Size

point_id

number (10)

time_stamp

date

msec

number (3)

value

number

status
quality

number (10)
number (10)

Description
Point ID that refers to the RTP index; it matches
the point_id field found in a related rtps table.
Time stamp indicating date and time point was
collected (includes hh:mm:ss in UTC).
Indicates the milliseconds within the time_stamp at
which the point was collected.
Numeric value of the point referred to by the
point_id field.
Status value.
Quality value.

291

B0193YL Rev E

Appendix G. Exporting to Oracle

Non-String RTP Table Example

AIM*Historian Configuration Input File
0 CREATE AIMHIST hist01
0 CREATE SESSION hist01 SESKEY hist01 rw
#
1 CREATE POINT 16:AI01.PNT
1 PUT POINT 16:AI01.PNT TYPE FLOAT
DESC

"Neutralization B1613 PH"

AUDITUPD

NO

COLLECTOR

rtcol1

COLMETH

CONNECTED

ENGUNITS

PH

FASTFREQ

FFREQUNITS

MINUTES

HIRANGE

14.00000000

INITSTATE

ON

LORANGE

0.00000000

MXSAMTIME

3600

MXSAMUNITS

SECONDS

NAMEINCOL

1600:AI_1601.PNT

NUMELEMS

READDELTA

0.05000000

RSTRTSTATE

PREVIOUS

SFREQUNITS

MINUTES

SIZE

SLOWFREQ

TRGCHANGE

NO

Sample Column Values

Column

Value

point_id

11

time_stamp

12/05/99 01:05:23

msec

000

value

0.2

status

623

quality

Resulting Control File Name

rtps_numbers_942850477.ctl

292

Appendix G. Exporting to Oracle

B0193YL Rev E

Resulting Control File Contents

load data
infile *
append into rtps_numbers
fields terminated by ',' optionally enclosed by '"'
(point_id,
time_stamp,
msec,
value,
status,
quality)
begindata
11, "12/05/99 01:05:23",000,0.2,623,0

Database Table: rgroup_data

The rgroup_data database table (Table G-7) stores all exported reduced values, which are
uniquely identified by a primary key that is a combination of the rgroup_name, point_id and
time_stamp fields.
Table G-7. Columns in the rgroup_data Database Table

Column

Data Type and Size

rgroup_name
point_id

varchar2 (128)
number (10)

time_stamp
percent_valid

date
number (3)

sum
avg
max
min
stdv
Kurt
status
quality

number
number
number
number
number
number
number (10)
number (10)

Description
Reduction group name.
Point ID that refers to the RTP index; it would
match the value of the point_id field found in the
rtps table.
Reduction time stamp.
Percentage of valid values, for a particular time
interval, needed before reduction is applied.
Sum of samples in time interval.
Average.
Maximum.
Minimum.
Standard deviation.
Kurtosis.
Status value.
Quality value.

293

B0193YL Rev E

Appendix G. Exporting to Oracle

Reduction Group Example

The sample configuration input file in this example uses the RTP configured with the input file
shown. You can configure the reduction group when you configure the RTP, or you can batch
configuration at another time.
AIM*Historian Configuration Input File
0 CREATE AIMHIST hist01
0 CREATE SESSION hist01 SESKEY hist01 rw
#
1 CREATE RGROUP red_group1
1 PUT RGROUP red_group1 DESC
FREQ

FREQUNITS

NO

PCTVALID

rtcol1

OPER

max MAX

OPER

avg AVG

OPER

sum SUM

OPER

min MIN

OPER

stdv STDV

OPER

kurt KURT

OPER

hist HIST

OPER

hilo HILO

TAG

16:AI01.PNT

EXPORT=

reductions group 1

Sample Column Values

Column

294

Value

rgroup_name

red_group1

point_id

11

time_stamp

12/01/99 10:23:20

percent_valid

50

sum

8.2

avg

3.15

max

5.5

min

1.1

stdv

kurt

status

1571

quality

Appendix G. Exporting to Oracle

B0193YL Rev E

Resulting Control File Name

rgroup_data_942850477.ctl

Resulting Control File Contents

load data
infile *
append
into rgroup_data
fields terminated by ',' optionally enclosed by '"'
(rgroup_name,
point_id,
time_stamp,
percent_valid,
sum,
avg,
max,
min,
stdv,
kurt,
status,
quality)
begindata
red_group1, 11,"12/01/99 10:23:20",50,8.2,3.15,5.5,1.1,0,,0,1571,0

A red_group.tim file would have data similar to the following:

942850477

Running Data Export

Generally HistExport runs as a Windows NT Service or as a daemon on Solaris. However, you
can start HistExport with a command line entry. HistMove is automatically executed as well, if it
is not already running.
To run the Data Export programs:
1. Make sure that the AIM*Historian instances and their respective collectors have
started.
Use the AIM*Historian Manager or the command line entries as described in
Chapter 3 AIM*Historian Operation.
2. From a command line window, enter the platform-appropriate command:
On AW70s:
On other Windows platforms:
Solaris systems:

d:\opt\aim\bin\HistExport
d:\Program files\aim\bin\HistExport
/opt/aim/bin/HistExport

295

B0193YL Rev E

Appendix G. Exporting to Oracle

HistExport and HistMove can both be executed with the following options:
<executable name> -stop
Stop the current instance of the executable program, HistExport or HistMove.
<executable name> -pulse
Force a new cycle of the specified executable.

<executable name> -status

Check if an instance of the executable program is running.

For the Windows NT platform, Hist2Oracle requires execution of the

D:\opt\dbexport\Ntinstallation\InstallH2O.bat batch file, which causes Hist2Oracle to run as a
service.
For the Solaris platform, Hist2Oracle requires execution of the
/etc/rc2.d/S99Hist2OracleDaemon script file, which causes Hist2Oracle to run as a daemon.

Naming Conventions for Exported Files

The following naming conventions apply to files generated by HistExport in each data category.

Message Files
The following naming conventions apply to message files generated by HistExport:

msg_def_<time_stamp>.ctl
msg_data_<msggroup>_<msgname>.ctl

<msggroup>_<msgname>.sql
CreatedMsg.dat.

RTP Files
The following naming conventions apply to RTP files generated by HistExport:
rtps_pts_<time_stamp>.ctl
rtps_numbers_<time_stamp>.ctl
rtps_strings_<time_stamp>.ctl
sample.dat
sample_idx.idx.

Reduction Groups
The following naming conventions apply to reduction group files generated by HistExport:
red_<reduction_group_name>.tim
rgroup_data_<time_stamp>.ctl.
where:
time_stamp is the time stamp in UTC time
msggroup is the message group name used as prefix to the message name
msgname is the message name that is part of the full message name
reduction_group_name is a reduction group name configured as part of an instance.
296

Appendix H. AIM*OLE DB Provider

This appendix documents the interface and data structures used by the AIM*OLE DB
Provider to enable access to AIM*Historian data by customer-developed OLE DB applications.
AIM*OLE DB Provider is an optional AIM*AT program that enables you to develop OLE DB
clients using Visual Basic, ActiveX Document Objects (ADO) code, and similar tools.
With AIM*OLE DB Provider, you can connect to an AIM*Historian instance and make SQL
queries of the database for:
Configurations

RTPs values, both linearized and reduced data

Message data.
You can also use the interface to insert values for RTPs that are configured for manual data entry
(COLMETH is MDE).

Client/Server Architecture and Remote Access

AIM*OLE DB Provider is implemented using client/server architecture based on COM. All data
objects are implemented as COM/DCOM servers and can be accessed via DCOM from clients.
These clients must run Windows NT 4.0 Server or Workstation with Service Pack 5 or later.

Supported Standards
The entire object hierarchy is presented in COM automation objects, facilitating development of
client applications in C++, Java, and Visual Basic. The use of COM also enables the use of
Internet Information Server IIS 5.0 to publish data using Active Server Pages.
OLE DB is the successor of ODBC on Microsoft platforms. Many of the database tools can be
used for presentation via OLE DB, including report generators such as Crystal Reports.

Installation and Authorization

AIM*OLE DB is installed from the AIM*AT CD, as described in Chapter 2, Installation on
Windows Platforms in AIM*AT Installation Guide (B0193YM). If you select AIM*OLE DB in
the component selection dialog box, the Setup program installs the DLLs and makes the necessary
registry updates.
After installation, you need to authorize use of the interface and set security access privileges using
the API Admin utility as described in Chapter 4, Configuration in AIM*AT Installation Guide
(B0193YM). The product code is OLEDB1.

297

Sample Project
A sample application of the interface is included on the AIM*AT CD. The project includes a
viewer, code examples for making a connection, SQL queries of an instance database, and an
insert to MDE type RTPs.
You can copy the project, ADODB, to a local drive to model SQL statements and familiarize
yourself with the interface. The project is located on the CD in the \win\unsup_utilities folder.

Data Structures
The section describes the tables that are implemented by the AIM*OLE DB Provider. The
OLE_DB data source consists of one or more catalogs, each of which consists of one or more
schemas. A schema, in turn, contains a set of tables. Table H-1 shows the table hierarchy.
Table H-1. AIM*OLE DB Provider Table Hierarchy

Schema

Table

DICTIONARY

INSTCFG

DICTIONARY
DICTIONARY

RTPCFG
MSGTABLECFG

DICTIONARY

MSGFIELDCFG

DICTIONARY

COLLECTORSTATIONCFG

DICTIONARY

CONTROLGROUPCFG

DICTIONARY

CONTROLGROUPRTPS

DICTIONARY

CONTROLGROUPMSGS

DICTIONARY

REDUCTIONGROUPCFG

DICTIONARY

REDUCTIONGROUPRTPS

DICTIONARY

CSA_STATIONS

DICTIONARY
DICTIONARY
MSGGROUP1

CSA_COMPOUNDS
CSA_BLOCKS
MSGNAME1

MSGGROUP1

MSGNAME2

Contents
Configuration parameters of the instances
on the selected AIM*Historian server.
RTPs configured in the connected instance
Configured messages of the connected
instance.
Configured message fields of the connected
instance
Collector stations of the connected
instance.
Configured control groups in the connected
instance.
Configured control group RTPs in the connected instance.
Configured control group messages in the
connected instance.
Configured reduction groups in the connected instance.
Configured reduction group RTPs of the
connected instance.
Stations delivered by I/A Series Compound
Summary Access (CSA).
Compounds delivered by CSA.
Blocks delivered by CSA.
Archived messages of
<msggroup1>.<msgname1>
Archived messages of
<msggroup1>.<msgname2>

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

Table H-1. AIM*OLE DB Provider Table Hierarchy (Continued)

Schema
MSGGROUPi

Table
MSGNAMEj
RTPENTRIES
LINEARRTPENTRIES

Contents
Archived messages of
<msggroupi>.<msgnamej>
All archived RTP values in the connected
Instance
Reduction values as delivered by
GetTimeLinearData

Dictionary Schema
InstCfg
The Instance Configuration (InstCfg) schema contains the AIM*Historian configuration
information (Table H-2).
Table H-2. AIM*OLE DB Provider Table InstCfg

Column Name
NAME
CFGPTS
MXSRVPTS
DBPATH
MSGDEFS
TRACKKEY
ARCHSIZE
MSGTIME
RTTIME
MAXCGENTS
MAXRGENTS
MSGFILE
MAXLOG
RTTRACE
FHDESC
PCTVALID
REDUCPHASE
REDPHASEUNIT
REDUCLEVEL
USEREDFILES
SCANPEAKS
REDFASTUNIT
REDMEDUNIT

Data Type
STRING(64)
INT
INT
STRING(256)
INT
INT
INT
INT
INT
INT
INT
INT
INT
BOOL
STRING(128)
SHORT
INT
SHORT
SHORT
BOOL
BOOL
SHORT
SHORT

Comment
Historian name
Configured RTPs this instance
Maximum RTPs for the server
Database search path
Maximum number of message definitions
Maximum number of track key definitions
Maximum size of tar medium
Maximum message retention time
Maximum real-time retention time
Maximum number of entries in a control group
Maximum number of entries in a reduction group
Maximum message file size
Log file size
Tracing on or off
Historian description
Reduction percent valid
Reduction phase offset from event time base
Reduction phase offset units
Reduction level
Use reductions data files for reduction
Scan and collect peaks for RTP values
Fast reduction interval units
Medium reduction interval units

299

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

Table H-2. AIM*OLE DB Provider Table InstCfg (Continued)

Column Name
REDSLOWUNIT
REDFASTINT
REDMEDINT
REDSLOWINT
COMPRESS
IATIME

Data Type
SHORT
INT
INT
INT
BOOL
BOOL

Comment
Slow reduction interval units
Fast reduction interval
Medium reduction interval
Slow reduction interval
Compress database files
Historian stores data in I/A time or UTC

RTPCfg
The RTP Configuration Table (RTPCfg) contains configuration information for the RTPs in the
instance (Table H-3).
Table H-3. AIM*OLE DB Provider Table

Column Name
NAME
COLLECTOR
NAMINCOL
DESCRIPTION
READDELTA
HIRANGE
LORANGE
ENGUNITS
TYPE
SIZE
NUMELEMS
COLMETH
TRGCHANGE
TRIGGER
FASTFREQ
FFREQUNITS
SLOWFREQ
SFREQUNITS
MXSAMTIME
MXSAMUNITS
AUDITUPD
INITSTATE
RSTRTSTATE

300

Data Type
STRING(128)
STRING(64)
STRING(256)
STRING(128)
DOUBLE
DOUBLE
DOUBLE
STRING(32)
SHORT
SHORT
SHORT
SHORT
BOOL
STRING(128)
SHORT
SHORT
SHORT
SHORT
INT
SHORT
BOOL
SHORT
SHORT

Comment
Historian RTP Name
Collector where RTP is located
Name in collector
Descriptor
Significant change delta
High range for trending
Low range for trending
Engineering units
Data type
Size of data type in bytes
Number of elements in the value
Collection method
Trigger and change, or change only
Triggering RTP
Fast scan rate count
Fast scan rate units
Slow scan rate count
Slow scan rate units
Maximum time between samples count
Maximum time between samples units
Send update message if updated
Initial state
Restart state

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

Table H-3. AIM*OLE DB Provider Table (Continued)

Column Name
FirstValueInserted

Data Type
DATE

Comment
The UTC or I/A Series time stamp, per the
IATIME attribute of the AIM*Historian instance,
of the first value in the AIM*Historian database for
this RTP; 0 if no values yet.

MsgTableCfg
The Message Configuration Table (MsgTableCfg) contains the message group and message
names in the instance (Table H-4).
Table H-4. AIM*OLE DB Provider Table MsgTableCfg

Column Name
MSGGROUP
MSGNAME

Data Type
STRING(128)
STRING(128)

Comment
Message Group
Message Name

MsgFieldCfg
The Message Field Configuration Table (MsgFieldCFG) contains the field configuration for each
message (Message Group and Message Name). The configuration parameters are listed in
Table H-5.
Table H-5. AIM*OLE DB Provider Table MsgFieldCfg

Column Name
MSGGROUP
MSGNAME
FIELDINDEX
FIELDNAME
ODBCOPTION
FIELDTYPE
NUMELEMENTS
COLDESC

Data Type
STRING(128)
STRING(128)
SHORT
STRING(128)
BOOL
SHORT
SHORT
STRING(64)

Comment
Message Group
Message Name
Field Index (1 .. n)
Field Name
ODBC option
Data type
Number of Elements
Column description

301

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

CollectorStationCfg
The Collector Station Configuration Table (CollectorSataionCfg) provides access to the
parameters for the collectors in the instance (Table H-6).
Table H-6. AIM*OLE DB Provider Table CollectorStationCfg

Column Name
NAME
COLLECTORTYPE
DST
HOSTNAME
DESCRIPTION
PLATFORM
TIMEZONE
CIRCULARFILESIZE
BURSTBYTEPERCENT
BURSTTIMEPERCENT
BURSTINTERVAL
RECONNECTSLEEP
COLLECTORISREMOTE
ISIA
CSTARTONBOOT
FOLLOWINSTON
FOLLOWINSTOF
COLCYCLE

Data Type
STRING(128)
SHORT
BOOL
STRING(32)
STRING(128)
SHORT
SHORT
INT
SHORT
SHORT
SHORT
SHORT
BOOL
BOOL
BOOL
BOOL
BOOL
INT

Comment
Historian collector name
Collector type
Collector uses daylight savings time
AIM*AT Hostname of the remote collector
Historian collector description
Collector processor type
Historian server time zone
Size of collector circular file in bytes
Burst mode byte threshold in percent
Burst mode time threshold in percent
Seconds between burst mode updates
Seconds of sleep after connect retry
Collector is remote
Is this an I/A collector
Collector starts on Reboot
Turn on when Instance turns on
Turn off when Instance turns off
Collectors minimum collection cycle in
milliseconds

ControlGroupCfg
The parameters accessible from the Control Group Configuration Table (ControlGroupCFG)
are listed in Table H-7.
Table H-7. AIM*OLE DB Provider Table ControlGroupCfg

Column Name
NAME
DESCRIPTION
RTP_ONOFF
RTP_BADOK
RTP_FASTSLOW
THRESHOLD_ONOFF
THRESHOLD_BADOK
THRESHOLD_FASTSLOW
302

Data Type
STRING(128)
STRING(128)
STRING(128)
STRING(128)
STRING(128)
FLOAT
FLOAT
FLOAT

Comment
Control group name
Control group description
Controlling RTP for On/Off
Controlling RTP for Bad/Ok
Controlling RTP for Fast/Slow
Threshold for On/Off
Threshold for Bad/Ok
Threshold for Fast/Slow

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

ControlGroupRTPs
The Control Group RTPs Table (ControlGroupRTPs) lists the RTPs included in each control
group (Table H-8).
Table H-8. AIM*OLE DB Provider Table ControlGroupRTPs

Column Name

Data Type

NAME
RTPNAME

STRING(128)
STRING(128)

Comment
Control group name
Controlled RTP name

ControlGroupMsgs
The Control Group Messages Table (ControlGroupMsgs) lists the messages included in each
control group (Table H-9).
Table H-9. AIM*OLE DB Provider Table ControlGroupMsgs

Column Name

Data Type

NAME
MSGGROUP
MSGNAME

STRING(128)
STRING(128)
STRING(128)

Comment
Control group name
Controlled MSG group
Controlled MSG name

ReductionGroupCfg
The ReductionGroupCfg Table (Table H-10) contains the parameters for each reduction group in
the instance.
Table H-10. AIM*OLE DB Provider Table ReductionGroupCfg

Column Name
NAME
DESCRIPTION
PERCENT
FREQUENCY
FREQUENCYUNIT
STORE_AVG
STORE_STDDEV
STORE_MAX
STORE_MIN
STORE_SUM
STORE_KURT
STORE_LINEAR
STORE_HILO

Data Type

Comment

STRING(128)
STRING(128)
SHORT
SHORT
SHORT

Reduction group name

Reduction group description
Reduction in percent
Frequency count
Frequency count unit

BOOL
BOOL
BOOL
BOOL
BOOL
BOOL
BOOL
BOOL

Store average
Store standard deviation
Store maximum
Store minimum
Store sum
Store kurtosis
Store linearization
Store Hi/Low

303

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

REDUCTIONGroupRTPs
The ReductionGroupRTPs Table (Table H-11) lists the RTPs included in each reduction group
in the instance.
Table H-11. AIM*OLE DB Provider Table ReductionGroupRTPs

Column Name
NAME
RTPNAME

Data Type

Comment

STRING(128)
STRING(128)

Reduction group name

Controlled RTP name

Message Schemas
For every message group there is one schema defined which contains one table for each message
name. The table names use the format <Message Group>.<Message Name>. The table consists of
the name and data type of each field in the message (Table H-12).
Table H-12. AIM*OLE DB Provider Table <MsgGroup>.<MsgName>

Column Name
TIME
<FIELDNAME1>
<FIELDNAME2>
<FIELDNAMEn>

Data Type

Comment

DATE
<FIELDTYPE1>
<FIELDTYPE2>
<FIELDTYPEn>

Archiving Time
1st column of the message
2nd column of the message
nth column of the message

RTP Data Schema

The RTP data schema is the default schema, which includes two tables, one for raw samples collected for the RTPs in the instance, the other for reduced RTP values.

RTPEntries
The RTP Values Table (RTPEntries) contains the historized RTPs, and includes value, status
information, and time stamps (Table H-13).
Table H-13. AIM*OLE DB Provider Table RTPEntries

Column Name
RTPNAME
TIMESTAMP
TIMESTAMPMSEC
STATUS
QUALITY
VALUE_STRING
VALUE_FLOAT
VALUE_INT

304

Data Type
STRING (128)
DATE
INT
INT
INT
STRING (128)
FLOAT
INT

Comment
RTP name
Historized time
Historized time - milliseconds
RTP status
RTP quality
String value
Float value
Integer value

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

LinearRTPEntries
The LinearRTPEntries table contains various data reduction values for the collected RTPs in the
instance, along with status data and time stamps (Table H-14).
Table H-14. AIM*OLE DB Provider LinearRTPEntries

Column Name
RTPNAME
TIMESTAMP
STATUS
PERCENT_VALID
SUM_VALUE
AVG_VALUE
MIN_VALUE
MAX_VALUE
STDV_VALUE
KURT_VALUE
LIN_VALUE
HILO_VALUE

Data Type
STRING(128)
DATE
INT
INT
FLOAT
FLOAT
FLOAT
FLOAT
FLOAT
FLOAT
FLOAT
FLOAT

Comment
RTP name
Historized Time
RTP status
PCT_VALID parameter of GetTimeLinearData
Sum operation
Average operation
Minimum operation
Maximum operation
Standard deviation operation
Kurtosis operation
Linearized operation
High/Low operation

AIM*OLE DB Provider Schemata

The AIM*OLE DB Provider Schemata listed in Table H-15 enable connectivity to popular OLE
DB tools such as Visual Basic and Crystal Reports.
Table H-15. AIM*OLE DB Provider Schemata Tables

AIM*OLE DB Provider Schemata

DBSCHEMA_TABLES
DBSCHEMA_COLUMNS
DBSCHEMA_PROVIDER_TYPES
DBSCHEMA_STATISTICS
DBSCHEMA_PRIMARY_KEYS
DBSCHEMA_INDEXES
DBSCHEMA_CATALOGS
DBSCHEMA_SCHEMATA

Description
All tables
All columns of AIM*OLE DB Provider tables
All supported data types
Number of rows per table
Primary key of all tables (none)
Indexes of all tables (non)
All catalogs
All schemata

305

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

Usage
You can access AIM*OLE DB Provider using either OLE DB or, preferably, ADO code.
This section describes how to use ADO code to:
Connect to the interface

Construct select statements

Insert values for MDE RTPs.

The code snippets in this section are from the sample project on the AIM*AT CD.

Connect Statement
The first step in using the interface is to make the connection to AIM*OLE DB provider and
specify the AIM*Historian server and instance as the location and catalog, respectively.
The User ID parameter is an authorized user id for AIM*OLE DB Provider. The data source is
always AIMApiCOM.Root.
An example of using ADO and VB to establish a connection:
Private Sub cmdConnect_Click()
On Error GoTo ErrorHandler
Dim s As String
s = "Provider=AIMHistProv.OLEDB;Data Source=AIMApiCOM.Root;Initial
Catalog=hist01;Location=AW70RT;User ID=auserid;Mode=Read"
conn.CursorLocation = GetCursorLocation()
conn.Open txtConnectString.Text
If conn.State = adStateOpen Then cmdConnect.Enabled = False
Exit Sub
ErrorHandler:
MsgBox Err.Description, vbOKOnly, App.Title
cmdConnect.Enabled = True
End Sub

306

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

Table H-16 describes the connects arguments.

Table H-16. Connect Arguments

Argument
Provider
Data Source
Initial Catalog

Location

User ID

Mode

Usage
Specify AIMHistProv.OLEDB
The data source is AIMApiCOM.Root
The initial catalog is the AIM*Historian instance you wish to
query. If this argument is left blank, AIM*OLE DB Provider
displays a dialog box for specifying the catalog and the location
(Figure H-1). You can select the instance name from a
pull-down list in the Select AIM*Historian Instance field.
Location is the AIM*Historian server where the instance is
configured. Use the AIM*AT hostname. If this argument is
left blank, AIM*OLE DB Provider displays a dialog box for
specifying the catalog and the location (Figure H-1). You can
select the server name from a pull-down list in the Select
AIM*Historian Instance field.
Enter an AIM*AT user name that is permitted to access the
interface. If the argument is left blank, the current user is
selected.
Mode specifies the type of usage as Read, Write, or Read-Write.
If you are establishing the connection to insert MDE
values, specify Write or Read-Write
If the argument is left blank, Mode defaults to Read,
which is appropriate for all other uses.
Access to data is also controlled by AIM*Historian
privileges configured for a user.

If you have not set the Location or Catalog argument in the connect statement, the interface
displays the AIM*OLE DB Provider dialog box, which enables you to specify theses properties
using pull-down lists (Figure H-1).

307

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

Location

Initial
Catalog

Figure H-1. AIM*OLE DB Provider Dialog Box

308

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

Select Statement
AIM*OLE DB Provider includes a simplified SQL-like language for accessing AIM*Historian
data. The select statement is a subset of the standard SELECT statement:
select <column expr>, ... <column expr> from <table spec> [where <condition>]
[group by <integer const> [seconds | minutes | hours | days]] [order by <column
name>, ... <column name>]
Examples:
select * from rtpentries where timestamp between 10/3/2002 10:45 AM and
10/3/2002 1:45 PM

Retrieves all RTP values in the instance with a time stamp in the specified range.
select rtpname,timestamp,status, value_float from rtpentries where rtpname =
WWTEST01:CALC0.BIO1

Gets the name, time stamp, status, and values for all values recorded for the RTP
WWTEST01:CALC0.BIO1.
select * from opc011.DICTIONARY.RTPCFG

Retrieves the RTP configurations for the instance opc011.

select * from LINEARRTPENTRIES where rtpname = "read_float_1" and timestamp
between "10/3/2002 8:48 AM" and "10/3/2002 8:52 AM" group by 30 seconds

Retrieves linearized values from the RTP read_float_1 with time stamps in the
specified range and groups with a value every 30 seconds.
NOTE

RTPs with high scan rates may result in very large retrievals that take a long time to
complete. Use the TIMESTAMP field to narrow the selection. If you do not specify
a time range, the query defaults to the most recent hour. If no data is found within
the range, the last collected value is returned.
The implementation of the select statement does not support optimization of the select
condition. All rows are fetched for the given time span and then compared to the criteria in the
where clause. The only way to improve response time is to limit the time span.
The following is a more detailed description of the select statement clauses.

309

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

Column Exp
The syntax for the column expression is:
[<function name>] (<column spec>) [ as <ID> ]
Function name specifies a data reduction function and is only applicable to queries of the
LinearRTPEntries table. The functions are:
avg
linear
kurt
max
min
stddev
sum

Average
Linearized
Kurtosis
Maximum
Minimum
Standard Deviation
Sum

If no function is specified, the query returns raw samples.

Use the Group By clause to specify the data reduction frequency. The default interval is one
day.
NOTE

When requesting data from the LinearRTPEntries table, do not use the status
column if you are requesting more than one column of data. The interface retrieves
data one column at a time and the returned status reflects the last column selected.
When accessing reduction data, you can also specify the percentage of good required to be valid
by setting the percentage_valid field in the where clause of the SQL statement. The default is
60%.
The as clause allows you to rename the table to a shorter or more meaningful term when the
data is displayed in the client application. This alias can be used in subsequent expressions in the
select statement, such as in where conditions.

Table Spec
When specifying the table, you can include the schema and rename the table using the as
function:
[<schema name>].<table name> [as <ID>]

310

Appendix H. AIM*OLE DB Provider

B0193YL Rev E

Condition
You can specify multiple conditional operations using the following syntax:
where <condition>

<comparison>
where <condition> <comparison> <logic op> <condition> |
where <condition> not

<condition> <logic op> and | or

The comparison term can be structured as follows:
<operand> <compare op> <operand>
operand can be a column expression or a constant.
compare op is < | <= | > | >= | = | <>.
<column expr> between <constant> and <constant>
<column expr> like <constant>
<column expr> in (<constant>, ..., <constant>)

Lexicon
Table H-17 lists the lexical elements recognized by OLE-DB Provider.
Table H-17. Lexical Elements Used in AIM*OLE DB Provider

Category

Recognized Elements

White Space
Keywords

space, tab, new line, form feed

and, as, asc, avg, between, by, count, days, desc, from,
group, linear, hours, in, kurt, max, min, minutes, not, or,
order, seconds, select, stddev, sum, where

Operators

. , ?
* %

Constants

integer: [0-9]+
string
date: determined by the Windows regional settings
(for example, the U.S.: mm/dd/yy hh:MM:ss.HHH)
parameter: ? used for parameterized commands
[a-zA-Z][_0-9a-zA-Z]*

ID

<

<= =<

==

!=

<>

>= => >

()

Insert Statement
You can use AIM*OLE DB Provider to insert values in AIM*Historian RTPs if the following conditions are met:

The target RTPs are configured with the MDE collection method
(COLMETH=MDE).
The mode argument in the connect statement is either Read-Write or Write.
Write access is available in the AIM*Historian instance and there are no restrictions to
accessing the target RTPs.
The syntax of the insert requires that only the RTPENTRIES table name be specified in the SQL
statement. The statement then requires that the Values section contains a ? for each of the eight
columns.
311

B0193YL Rev E

Appendix H. AIM*OLE DB Provider

The syntax of the insert is:

insert into <table_spec> values (?, ?)
A VB 6.0 example of an insert is shown below.
Private Sub cmdInsert_Click()
On Error GoTo ErrorHandler
Dim s As String
If conn.State = adStateClosed Then
MsgBox "Not connected to Datasource"
Exit Sub
End If
Dim cmd As New ADODB.Command
cmd.ActiveConnection = conn
cmd.CommandType = adCmdText
cmd.CommandText = "insert into rtpentries values (?, ?, ?, ?, ?, ?, ?, ?)"
cmd.Parameters("RTPNAME") = rtpname.Text
cmd.Parameters("TIMESTAMP") = Now
If InsertFloat.Value Then
cmd.Parameters("STATUS") = 3
cmd.Parameters("VALUE_FLOAT") = CSng(TxtValue.Text)
End If
If InsertInt.Value Then
cmd.Parameters("STATUS") = 2
cmd.Parameters("VALUE_Int") = CInt(TxtValue.Text)
End If
If InsertStr.Value Then
cmd.Parameters("STATUS") = 31
cmd.Parameters("VALUE_String") = TxtValue.Text
End If
cmd.Parameters("QUALITY") = 33
cmd.Execute
cmdInsert.Caption = "Insert RTP"
Exit Sub
ErrorHandler:
MsgBox Err.Description, vbOKOnly, App.Title
cmdInsert.Caption = "Insert RTP"
End Sub

312

Index
A
AIM*API
Error Codes 201
Interface 15
AIM*AT Server Filter 29, 32
AIM*Historian
Architecture 2
Archiver 116, 128
Archiver Functions 146
Archiver Window 144
Component
Collector 237
Control Group 260
Event Message 257
Instance 226
Reduction Group 263
RTP 246
Session 225
Components 223
Configuration 17
Configurator 17
Setup 20
Data collector 59
Data Display 101
Defining Data 102
Manual Entry 112
Data Not in Trend Display 195
Data Reduction 215
Database 127
Database tables 283
DB Wizard 133
Editor 18
Application Menu Bar 26
Command Buttons 26
Components Tree 24
Editor Session 63
Error Codes 201
Exporting to Oracle 15, 275
Features 1
Instance 3
Components 4
Creation 27
Instance deletion 132
Interface Structure 13, 16
313

B0193YL Rev E

AIM*API 15
I/A Series 15
ODBC 15
Interfaces 13
Log File 164
Manager Window 87, 93
Application Menu Bar 89
Collector Page 96
Communications Page 97
Components Tree 91
Instance Page 94
Server Page 94
Tool Bar 89
Operation 87
Product Structure 3
Reduction APIs 213
Retrieving Reduced Data 50
Spy 116
Troubleshooting 164
AIM*OLE DB Provider 297
Connect Statement 306
Connect Statement Arguments 307
Data Structures 298
Dialog Box 308
Insert Statement 311
Installation and Authorization 297
Lexical Elements 311
Select Statement 309
apitst 173
Applicom 6
Architecture 2
Archiver 152, 156
Archiving
Archiver window 144
AutoArchiver 154
Configuration 156
Features 154
Scheduling 157
Test Mode 160
Copying files 153
Deleting files 152
Filtering files 151
Functions 146
Moving files 153
On-Demand 143
Selecting an Instance 149
Selecting database files 147

314

Index

Index

B0193YL Rev E

B
BASEstar 6
Block-Compound
Sort option 33
C
cfgcmd.inp 17
CHIP 6
clearcfg 168
Client/Server Architecture 2
Collection Frequency Rates 272
Collector
Attributes 238
Component 237
Configuration 59, 68
Page 96
Troubleshooting 194
Collectors 4
Command Buttons 26
Committing an Instance Configuration 63
Communications Page 97
Component
Control Group 260
Event Message 257
Instance 226
Reduction Group 263
RTP 246
Session 225
Tree 24, 91
Compound-Block
AND parameters 37
Filter 29
OR parameters 38
Search option 37
Sort option 33
Compound-Block Filter 33
Sorted by Block 34
Sorted by Compound 33
Configuration 279
AIM*Historian 17
Configuration window 17, 56
Control Group 77
Event Message 72
File Windows 24
Instance 77
Messages 42
Overview 17
Reduction Group 76
Reduction Intervals 219
315

B0193YL Rev E

RTP 28, 41, 69

Server connections 19
Tools 17
Using Input Text Files 64
Connect statement Arguments 307
Control Group 11
Attributes 261
Component 260
Configuration 77
Control Groups 11
Creating an Instance 19
D
Data Export
HistExport 275, 295
Data Object Tree 40
Data Object Wizard 29
AIM*AT Server Filter 29, 32
Compound-Block Filter 29
Filter Page controls 29
I/A Descriptor Filter 29
Parameter Type Filter 29
Results page 38
Search options 37, 38
Compound-Block 37
Parameters 38
Data Reduction
AIM*Historian versus I/A Series Historian 216
Algorithms 215
Data Retrieval from AIM*Historian 3
Database
Collecting simulation values 189
Configuration 129
Copy 128, 153
Deleting files 128, 152
Disk Usage 133
Filter 151
Locating files 150
Manage 127
Message 130
Moving files 128, 153
Selection 147
Tables 283
Wizard 134
DB Wizard 134
Filtering RTPs 138
Menus 138
Modifying RTP Disk Usage 141
Optimization Window 140
316

Index

Index

B0193YL Rev E

Selecting RTPs 140

DBPATH 127, 128, 143, 148, 153, 159, 177, 179, 188, 220, 230
DDE 6
Dead Band Wizard (see DB Wizard) 134
Default Collector Configuration 5
Diagnostic Utilities 166
Document Conventions xxi
Document Overview xix
DST Parameter 267
dumpcvs 168
dumprcol 169
dumpred 172
E
Error Codes 164
Event Message 9, 130, 270
Attributes 258
Checking database files 176
Collector 5, 237
Component 257
Configuration 42, 72
Directory 127
Fixing database files 178
Historizing 226
Naming Conventions 296
Reading and writing 180
Sizing 270
Troubleshooting 193
Exporting to Oracle 15
F
Filter
Compound-Block 33
Description 36
Parameter type 35
Filter Page
controls 29
FORCE_DELETE 78
forces 130
G
Go To File 150
H
histbatch 81
histcbatch 83
HistExport 275, 277, 295
317

B0193YL Rev E

Message files 296

Naming conventions 296
RTP 296
histmain 87, 191, 192
HistMove 278, 295
Historian
Setup Wizard 20, 22, 27
histsave 17, 64, 79, 87
histsend 6, 84, 132, 194
histspy 87, 116, 132, 172, 189, 191, 196
I
I/A Descriptor Filter 29
I/A Series Historian 1
I/A Series Interface 15
I/A Series Real-Time Collector 5
I/A Series software 1
I/O Gate Data Collector 2, 6, 7, 120, 191, 266, 267
I/O Gate Drivers
Applicom 6
BASEstar 6
CHIP 6
DDE 6
ModbusPlus 6
ModbusTCP 6
OPC 6
REMIO 6
IATIME 266
Instance
Archive selection 149
Attributes 228
Collector Component 237
Component 226
Components 4
Configuration 65, 77
Configuration File Window 55
Configuration with AutoArchiver 157
Configuration with histbatch 81
Configuration with histcbatch 83
Configuration with histsave 79
Control Group Component 260
Creating 27
Deleting 132
Directory 127
Event Message Component 257
Maximum Values 84
Reduction Group Component 263
RTP Component 246
Select 22
318

Index

Index

B0193YL Rev E

Selection Dialog Box 22

Session Component 225
Storing Time Stamps 266
Troubleshooting 195, 197
Troubleshooting tools 164
Instances
Monitoring Operation 93
Interface Structure 16
ipchisti 5, 84, 98, 165, 178, 184, 193, 195, 228, 241
L
leg2fh 17
Legacy Interface Servers 122
Linearization 216
M
Manual Data Entry 112
see MDE 112
Maximum Value Attributes 84
MDE 112
Annotation Window 115
Tool Bar 113
Window 112
Message files 296
Messages
Configure 42
Directory 127
Locating 150
Message Definition dialog box 43
Page 42
ModbusPlus 6
ModbusTCP 6
Moving Database Files 153
msgcheck 176
msgfix 176, 178
msgtst 163, 180
O
Object Search dialog box 37
ODBC Interface 15
OLE DB Tables 298
OPC 6
Oracle
Configuring files for export 279, 285
Copying files to 278
Copying with HistMove 278
Data Export 275, 295
Database tables 283
319

B0193YL Rev E

Exporting from AIM*Historian 15, 275

Exporting with HistExport 277
P
Parameter Type Filter 29, 35
Results page 29
Parameters search option 38
Peaks 216
Permanent deletion of RTPs 78
Product Features 2
Product Structure 3
R
readval 189
Real-Time Collector 5, 9, 120, 237
Real-Time Points 7
Reduction Formulas 215
Reduction Group 12
Adding 50
Attributes 264
Component 263
Configuration 76
Naming Conventions 296
Operations 54
Reduction Values
Sizing 270
Related Documents xix
REMIO 6
Request For Comments xxii
Results page 38
Revision Information xviii
RTP 1, 4, 7, 207, 296
Attributes 8, 249
Collection frequency 9
Collector 5, 9, 120, 237
Component 246
Configuration 28, 41, 69
Configuration Window 56
Data Object Wizard 29
delete 59, 78
Directory 127
Editing Configurations 58
File Size 273
Files 130
Filtering 138
Fixing database files 183
Historizing 226
In Control Groups 11
320

Index

Index

B0193YL Rev E

Locating files 150

Managing reduced data 218
Modifying Disk Usage 141
Naming Conventions 296
Optimization 140
Page 23
Read Delta 133, 137, 253, 272
Rebuilding cross-references 188
Reduced files 131
RTTIME 274
Sample Data 102
Samples 130, 269
Sanity check 181
Selection 140
Simulation values 189
Sizing 269
Status Word 207
Troubleshooting 192
Value types 209
rtpcheck 181
rtpfix 183
S
Server Status 62, 119
Session
Attributes 225
Component 225
Sizing Guidelines 269, 275
Stub Values 189
T
Technical Assistance xxii
testhv 184
testvar 186
Trend Data Request 184
Troubleshooting
Configuration Changes Not Made to RTPs, Messages 195
Incorrect AIM*Historian Data in Trend Display 197
No Event Messages Inserted in .fdb Files 193
No RTP Values Inserted in .fdb Files 192
No RTP Values or Event Messages Inserted in .fdb Files 193
No TCP/IP Connection to Remote Collector 194
Procedures 190
Tools 164
TZ Parameter 267

321

B0193YL Rev E

Index

V
vmstat 199
W
Wizard Browsing 19
X
xrebuild 188

33 Commercial Street
Foxboro, Massachusetts 02035-2099
United States of America
www.foxboro.com
Inside U.S.: 1-866-PHON-IPS (1-866-746-6477)
Outside U.S.: 1-508-549-2424 or contact your local Foxboro representative.
Facsimile: 1-508-549-4999
Printed in U.S.A.

1202