Professional Documents
Culture Documents
AIM Historian Users Guide
AIM Historian Users Guide
REV E
I/A Series®
Information Suite
AIM*Historian™ User’s 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.
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 .......................................................................................... 13
AIM*API Interface ............................................................................................................. 15
ODBC Interface ................................................................................................................. 15
I/A Series Interface ............................................................................................................. 15
Export to Oracle ................................................................................................................. 15
AIM*AT OPC Server ......................................................................................................... 15
AIM*AT OLE DB Provider ............................................................................................... 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 ............................................................ 19
Starting the AIM*Historian Configurator .......................................................................... 20
Selecting an Instance .......................................................................................................... 22
AIM*Historian Components Tree ...................................................................................... 24
Configuration File Windows .............................................................................................. 24
Application Menu Bar ........................................................................................................ 26
Command Buttons ............................................................................................................. 26
Creating an AIM*Historian Instance ....................................................................................... 27
Configuring Real-time Points .................................................................................................. 28
Adding RTPs with the Data Object Wizard ....................................................................... 29
Filter Page Controls ............................................................................................................ 29
AIM*AT Server Filter ......................................................................................................... 31
I/A Series Compound-Block Filter ..................................................................................... 33
Parameter Type Filter ......................................................................................................... 35
Filtering by I/A Series Descriptions ............................................................................... 36
Searching Dialog Box .................................................................................................... 37
Results Page ....................................................................................................................... 38
Defining the RTP Configuration ....................................................................................... 41
Configuring Messages ............................................................................................................. 42
Creating Control Groups ........................................................................................................ 45
Adding Reduction Groups ...................................................................................................... 50
Editing Configuration Files ..................................................................................................... 55
Instance Configuration File ................................................................................................ 55
RTP Configuration Window .............................................................................................. 56
Editing RTPs ................................................................................................................. 57
Deleting RTPs ............................................................................................................... 59
Adding a Collector ............................................................................................................. 59
Other Configuration File Windows .................................................................................... 62
Server Status ............................................................................................................................ 62
Finishing an AIM*Historian Configurator Session .................................................................. 63
Configuration Using Input Text Files ..................................................................................... 64
Instance Configuration ....................................................................................................... 65
Collector Stations ............................................................................................................... 68
Real-Time Points ............................................................................................................... 69
Event Message Configuration .................................................................................................. 72
I/A Series Legacy Message Groups ...................................................................................... 72
I/A Series Alarms ................................................................................................................ 74
Reduction Groups .............................................................................................................. 76
Control Groups .................................................................................................................. 77
Committing the Session ..................................................................................................... 77
Permanent Delete ............................................................................................................... 78
iv
Contents B0193YL – Rev E
3. AIM*Historian Operation............................................................................................... 87
AIM*Historian Manager Window .......................................................................................... 87
Application Menu Bar and Tool Bar .................................................................................. 89
AIM*Historian Components Tree ...................................................................................... 91
Tree Menu .................................................................................................................... 92
AIM*Historian Manager Pages ........................................................................................... 93
On/Off Controls ........................................................................................................... 93
Server Page .................................................................................................................... 94
Instance Page ................................................................................................................. 94
Collector Page ............................................................................................................... 96
Communications Page ................................................................................................... 97
Log File Page ................................................................................................................. 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 ......................................................................... 102
Saving, Opening, and Deleting Configurations ........................................................... 103
Selecting the AIM*Historian Instance and Server ........................................................ 103
Specifying the Time Interval and Data Type for the RTPs .......................................... 103
Assigning RTPs to Report Columns ............................................................................ 104
Viewing the Data Report or Trend Display ................................................................. 105
Exiting the AIM*Historian Data Display ..................................................................... 105
Viewing the Data Report .................................................................................................. 105
The Data Report Window Format .............................................................................. 106
Using the Data Report Menu Bar ................................................................................ 107
Printing Reports ............................................................................................................... 107
Printer Setup .................................................................................................................... 108
Viewing the Data Trend Display ...................................................................................... 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
v
B0193YL – Rev E Contents
5. Troubleshooting............................................................................................................ 163
Version Information .............................................................................................................. 163
Troubleshooting Tools .......................................................................................................... 164
Diagnostic Utilities ............................................................................................................... 166
clearcfg ............................................................................................................................. 168
dumpcvs ........................................................................................................................... 168
dumprcol .......................................................................................................................... 169
dumpred .......................................................................................................................... 172
vi
Contents B0193YL – Rev E
vii
B0193YL – Rev E Contents
viii
Contents B0193YL – Rev E
ix
B0193YL – Rev E Contents
x
Figures
1-1. AIM*Historian Client/Server Architecture .................................................................... 2
1-2. AIM*Historian Instance ................................................................................................ 4
1-3. Sample Message Definition ......................................................................................... 10
1-4. AIM*Historian Data Retrieval .................................................................................... 14
1-5. AIM*Historian Interface Structure .............................................................................. 16
2-1. AIM*Historian Configuration Overview ..................................................................... 17
2-2. Server Connection Dialog Box .................................................................................... 19
2-3. AIM*Historian Configurator Window ........................................................................ 21
2-4. Instance Selection Dialog Box ..................................................................................... 22
2-5. Real Time Points Page ................................................................................................ 23
2-6. AIM*Historian Components Tree .............................................................................. 24
2-7. AIM*Historian Configurator Window with Instance Configuration File Open .......... 25
2-8. Create AIM*Historian Instance Dialog Box ................................................................ 27
2-9. Real Time Points Page ................................................................................................ 28
2-10. Data Object Wizard Filter Controls ............................................................................ 29
2-11. Selected Server Stations Dialogue Box ......................................................................... 30
2-12. Data Object Wizard Server Filter Page ........................................................................ 32
2-13. Compound-Block Filter Page Sorted by Compound ................................................... 33
2-14. Compound-Block Filter Page Sorted by Block ............................................................ 34
2-15. Parameter Type Filter Page ......................................................................................... 35
2-16. Description Filter Page ................................................................................................ 36
2-17. Object Search Dialog Box ........................................................................................... 37
2-18. Data Object Wizard Results Page ................................................................................ 38
2-19. Add Item Dialog Box .................................................................................................. 39
2-20. Data Object Tree in the RTP/Message Dialog Box ..................................................... 40
2-21. Messages Page ............................................................................................................. 42
2-22. Message Definition Dialog Box ................................................................................... 43
2-23. New Key Dialog Box ................................................................................................... 44
2-24. Control Page in the Groups Dialog Box ...................................................................... 45
2-25. Control Group Dialog Box ......................................................................................... 46
2-26. Trigger RTPs Dialog Box ............................................................................................ 47
2-27. Controlled RTPs Dialog Box ...................................................................................... 48
2-28. Controlled Messages Dialog Box ................................................................................. 49
2-29. Reduction Group Dialog Box ..................................................................................... 51
2-30. Parameters Dialog Box ................................................................................................ 52
2-31. Reduction Group RTPs Dialog Box ............................................................................ 53
2-32. Reduction Group Operations Dialog Box ................................................................... 54
2-33. AIM*Historian Cfg Window and Instance Parameters ................................................ 55
2-34. RTP Configuration Window ...................................................................................... 57
2-35. Edit RTP Window ...................................................................................................... 58
2-36. Collector Station Configuration File Window ............................................................. 60
2-37. Collector Station Type Dialog Box ............................................................................. 60
2-38. Collector Setup Window ............................................................................................. 61
2-39. Server Status Dialog Box ............................................................................................. 62
xi
B0193YL – Rev E Figures
xii
Figures B0193YL – Rev E
xiii
B0193YL – Rev E Figures
xiv
Tables
1-1. RTP Data Types ........................................................................................................... 8
1-2. RTP Trigger Values .................................................................................................... 12
2-1. AIM*Historian Configurator Application Menu Bar ................................................... 26
2-2. Message Definition Fields ........................................................................................... 43
2-3. RTP Trigger Values .................................................................................................... 48
2-4. Default AIM*Historian Installation Directories .......................................................... 64
3-1. AIM*Historian Manager Functions ............................................................................ 89
3-2. Components Tree Pop-Up Menus .............................................................................. 92
3-3. Data Report Window Menu Bar ............................................................................... 107
4-1. Reduced RTP Files .................................................................................................... 131
4-2. Samples and Storage for Different Deltas .................................................................. 133
4-3. DB Wizard Functions ............................................................................................... 138
4-4. RTP Information Provided in the Optimization Window ......................................... 140
4-5. Archivable Database Files .......................................................................................... 144
4-6. AIM*Historian Archiver Functions ........................................................................... 146
5-1. Summary of Diagnostic Utilities ............................................................................... 166
5-2. Circular File Header Fields in dumprcol Output ....................................................... 171
5-3. No RTP Values Inserted in .fdb Files ........................................................................ 192
5-4. No Event Messages Inserted in .fdb Files .................................................................. 193
5-5. No RTP Values or Event Messages Inserted in .fdb Files ........................................... 193
5-6. 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 Tables
xvi
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.
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™ User’s Guide (B0193YU)
♦ AIM*API™ User’s Guide (B0193YN)
♦ AIM*SPC™ User’s Guide (B0193YH)
♦ AIM*DataLink™ User’s Guide (B0193YJ)
♦ AIM*Explorer™ User’s Guide (B0193YK)
♦ AIM*API User’s Guide (B0193YN)
♦ AIM*AT OPC Server User’s Guide (B0400DG)
♦AIM*Inform User’s Guide (B0400DS)
♦ Wonderlink I/O Server User’s Guide (B0193YP)
♦ NetAPI MFC Class User’s 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.
xix
B0193YL – Rev E Preface
Chapter 5 “Troubleshooting”
Diagnostic utilities and troubleshooting tables.
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 con-
figured 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 vari-
ous 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.
xxi
B0193YL – Rev E Preface
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.
1
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 col-
lected 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.
I/O Gate
Device
Process Unit
Process Unit
Figure 1-1. AIM*Historian Client/Server Architecture
2
1. Overview B0193YL – Rev E
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.
3
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 Reduction
Collectors Groups
Real-Time Control
Points Groups
Event
Messages
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 con-
nection 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.
4
1. Overview B0193YL – Rev E
The collectors are installed from the AIM*AT CD. AIM*Historian provides three distinct collec-
tor 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 col-
lectors is not provided in this document, but is supplied with the application.
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.
5
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 pre-
defined 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 collec-
tor writes its messages directly to the message data files for the instance, that is, to
m10.fdb, m20.fdb, and so on.
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 Inter-
face Program (CHIP) provided by Fisher-Rosemount.
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.
6
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 pro-
gram. 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 User’s 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 real-
time 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 val-
ues 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
User’s Guide (B0193YN) for information on the use of these calls.
7
B0193YL – Rev E 1. Overview
Data Type
Category Data Type Number of Bytes Number of Elements
I/A Series Integer 4 Bytes 1 Element
array types Float
Long
Boolean
Character
Packed integer
Packed long
non-I/A Series Character array 1 Byte User-defined
array types Short array 2 Bytes
Unsigned short array 2 Bytes
Integer array 4 Bytes
Unsigned integer array 4 Bytes
Float array 4 Bytes
Double array 8 Bytes
String String User-defined, including User-defined
the longest possible
string plus null
terminator byte.
BLOBS Binary large objects User-defined 1 Element
The data content of BLOBs is unknown to AIM*Historian.
Files 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 Time stamp for distin- 4 Bytes 1 Element
guishing a time value
from a long data type
8
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 con-
figuration. 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 fre-
quency of one every five minutes. The collector always sends the data to the instance at the one-
per-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 file’s 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 exist-
ing 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.
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 modi-
fied 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 group’s RTPs to Off, OK, or Slow. A triggering value rising to or
above the threshold value turns the control group’s 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.
Trigger
Type If the trigger value is: Then:
OnOff 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.
BadOK 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.
FastSlow 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 group’s 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
13
B0193YL – Rev E 1. Overview
AIM*Historian Database
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.
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”.
15
B0193YL – Rev E 1. Overview
Internal
AIM*Historian • AIM*Historian Instance is activated.
AIM*Historian • Configuration changes are checked.
Applications
Database • Data from collectors is updated and
Collector
stored in AIM*Historian databases.
16
2. AIM*Historian Configuration
This chapter describes setup of AIM*Historian instances with AIM*Historian Configurator
and instance configuration using a text editor.
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.
I/A Series
Historian
Configuration leg2fh text editor cfgcmd.inp
Information (Sample File)
fh_Cfg()
AIM*Historian calls using
histbatch histcbatch histsave
Configurator AIM*API
AIM*Historian
Configurator can
also be installed
separately on a AIM*Historian Instance Configuration Files
networked PC. (e.g., *.cfg files in /opt/aim/inst/hist01)
Figure 2-1. AIM*Historian Configuration Overview
17
B0193YL – Rev E 2. AIM*Historian Configuration
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 net-
work 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
4. Enter the IP name of the I/A Series station’s 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
20
2. AIM*Historian Configuration B0193YL – Rev E
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 mes-
sages 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 cov-
ers selection of an existing instance in order to describe other features of the AIM*Historian Con-
figurator 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).
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
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.
23
B0193YL – Rev E 2. AIM*Historian Configuration
Server icon
and name
Configuration files
of the selected
instance
Instance icon
and name
24
2. AIM*Historian Configuration B0193YL – Rev E
Figure 2-7. AIM*Historian Configurator Window with Instance Configuration File Open
25
B0193YL – Rev E 2. AIM*Historian Configuration
Command Buttons
The five command buttons immediately below the application menu bar are applied to the cur-
rently 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
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 pro-
vide 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.
3. Click Add.
28
2. AIM*Historian Configuration B0193YL – Rev E
Compound-Block Filter
Identifies blocks in the selected stations as sources of the control objects.
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.
29
B0193YL – Rev E 2. AIM*Historian Configuration
Filter 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.
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.
31
B0193YL – Rev E 2. AIM*Historian Configuration
32
2. AIM*Historian Configuration B0193YL – Rev E
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
34
2. AIM*Historian Configuration B0193YL – Rev E
35
B0193YL – Rev E 2. AIM*Historian Configuration
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
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.
37
B0193YL – Rev E 2. AIM*Historian Configuration
Parameters This is the only option presented if you did not select blocks in the Com-
pound-Block Filter page but did choose parameter types in the next win-
dow. 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.
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 histor-
ized 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, sec-
ond, 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).
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.
39
B0193YL – Rev E 2. AIM*Historian Configuration
Source Type
Server
Data Object
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.
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.
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.
NOTE
Blue text means that the keys are committed and cannot be changed.
Field Description
Message Group Message group of up to 32 characters.
Message Name Message name of up to 32 characters.
Messages will be logged Indicates if the messages collected can be updated in the database.
Select Yes or No.
Keyword Keyword of up to 14 characters, to identify the name of the field
in the message.
43
B0193YL – Rev E 2. AIM*Historian Configuration
Field Description
ODBC Option 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.
Type 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 Elements 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.
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
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).
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).
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 select-
ing object names beginning with FHLE.
6. Select a point for each trigger type by highlighting the RTP and clicking the right-
pointing 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
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).
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
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
50
2. AIM*Historian Configuration B0193YL – Rev E
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).
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 Value type A numeric: 2, 3, 5, 6, 22 to 26, or 28 to 30
Bit 8 Bad bit Not Bad: 0
Bit 11 Out Of Service (OOS) In service: 0
bit
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).
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 select-
ing 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
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
55
B0193YL – Rev E 2. AIM*Historian Configuration
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 Compo-
nent Attributes”.
56
2. AIM*Historian Configuration B0193YL – Rev E
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 sin-
gle 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
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 sys-
tem 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 con-
nection 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
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).
60
2. AIM*Historian Configuration B0193YL – Rev E
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.
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).
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.
63
B0193YL – Rev E 2. AIM*Historian Configuration
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 vari-
ous 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.
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 com-
mand 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
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
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.
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
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 User’s 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 collec-
tion 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.
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
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 ref-
erence 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.
71
B0193YL – Rev E 2. AIM*Historian Configuration
72
2. AIM*Historian Configuration B0193YL – Rev E
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
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.
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 reduc-
tion group is defined by the MAXRGENTS attribute for the instance.
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.
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, COLLEC-
TOR, 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.
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 ( ) to open the histsave
window (Figure 2-56).
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 dis-
plays 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
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.
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.
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
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.
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
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 col-
lector 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
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 2. AIM*Historian Configuration
86
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).
87
B0193YL – Rev E 3. AIM*Historian Operation
Tabs
AIM*Historian
Components
Tree
Status Bar
88
3. AIM*Historian Operation B0193YL – Rev E
89
B0193YL – Rev E 3. AIM*Historian Operation
90
3. AIM*Historian Operation B0193YL – Rev E
Server
Instance
Collector
Right-click on any
component for its
short-cut menu.
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 Man-
ager 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
92
3. AIM*Historian Operation B0193YL – Rev E
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 collec-
tor 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.
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.
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
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 con-
figured 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 con-
figured 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
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).
97
B0193YL – Rev E 3. AIM*Historian Operation
98
3. AIM*Historian Operation B0193YL – Rev E
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.
100
3. AIM*Historian Operation B0193YL – Rev E
101
B0193YL – Rev E 3. AIM*Historian Operation
102
3. AIM*Historian Operation B0193YL – Rev E
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 start-
ing 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 cor-
responding 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.
NOTE
You can remove an RTP assignment by clicking the column’s corresponding Clear
button (1 to 8).
104
3. AIM*Historian Operation B0193YL – Rev E
105
B0193YL – Rev E 3. AIM*Historian Operation
Report
Statistics
and Column
Headers
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 column’s 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
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).
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).
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).
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).
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).
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
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
NOTE
Manually entered values are only entered into the AIM*Historian databases. They
have no effect on the control system databases.
112
3. AIM*Historian Operation B0193YL – Rev E
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 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.
♦ Annotations group Allows you to add comments for RTPs with manually
entered values.
♦ Time Stamp group 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
114
3. AIM*Historian Operation B0193YL – Rev E
The window displays all the annotations made to manually entered values for the
selected RTP. The information is displayed in seven columns:
Annotation Time The time and date the annotation was made.
The time stamp is automatically generated by
AIM*Historian.
RTP Name The name of the annotated MDE RTP.
Key1, Key2, Key3 Optional search keys for retrieving annotations.
Event Time Optional time stamp entered with the
annotation.
Annotations 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 win-
dow 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.
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
117
B0193YL – Rev E 3. AIM*Historian Operation
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).
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
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.
an_write_valstat() 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).
120
3. AIM*Historian Operation B0193YL – Rev E
Refer to AIM*API User’s 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.
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
NOTE
Only one version of these servers can be running at a given time on one machine.
where:
FH 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.
IA 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.
STOP Stops all legacy servers.
WHICH 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
122
3. AIM*Historian Operation B0193YL – Rev E
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 nor-
mally 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:
♦ 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).
124
3. AIM*Historian Operation B0193YL – Rev E
4. Select the AIM*Historian tab to display the AIM*Historian page (Figure 3-26), and
click Stop AIM*Historian Applications.
125
B0193YL – Rev E 3. AIM*Historian Operation
126
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.
127
B0193YL – Rev E 4. Database Management
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 instance’s 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 con-
serve 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 con-
figuration 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 configu-
ration 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_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
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.
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 incre-
mented by 10 as each RTP file is filled.
Reduction
Frequency Filename Description
Fast rfxref.fdb Indexes into the rf<n>.fdb files, and cross references between time
and file.
rf<n>.fdb RTP values reduced at the fast reduction period.
Medium rmxref.fdb Indexes into the rm<n>.fdb files, and cross references between time
and file.
rm<n>.fdb RTP values reduced at the medium reduction period.
Slow rsxref.fdb Indexes into the rs<n>.fdb files, and cross references between time
and file.
rs<n>.fdb RTP values reduced at the slow reduction period.
131
B0193YL – Rev E 4. Database Management
132
4. Database Management B0193YL – Rev E
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 stor-
age 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 RTP’s storage load by increasing the point’s Read Delta
♦ Evaluate the effects of optimization settings before applying the settings.
133
B0193YL – Rev E 4. Database Management
134
4. Database Management B0193YL – Rev E
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 nor-
mal historian operation. During plant upsets the RTPs associated with the disrup-
tion 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
136
4. Database Management B0193YL – Rev E
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
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 fil-
ter 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.
139
B0193YL – Rev E 4. Database Management
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
The group to the right of the Hard Disk Optimization group shows the predicted results based on
the selected interval (Figure 4-6).
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
142
4. Database Management B0193YL – Rev E
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 commer-
cially 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.
144
4. Database Management B0193YL – Rev E
Menu
Bar
Tool Bar
Database Listings
Status
Bar
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.
145
B0193YL – Rev E 4. Database Management
Tool Bar
Menu Submenu Icon Description
Operations Move (Ctrl+M) Moves selected files for an instance to another
directory within the list of directories specified
by the DBPATH attribute for the instance.
Copy Files (Ctrl+C) Copies selected files of an instance to another
location.
Delete (Ctrl+D) Deletes the selected file after you confirm the
action with a dialog box.
Remove Archive Flag Resets the status of selected file to
(Ctrl+A) non-archived.
Exit Closes the AIM*Historian Archiver window.
Instance Select 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.
View Filter File List Opens the Filter File List dialog box for
(Ctrl+F) specifying database files to be displayed in the
AIM*Historian Archiver window.
Go to File (Ctrl+G) Opens a dialog box for retrieving database files
that meet specific criteria.
Tool Bar Displays the AIM*Historian Archiver tool bar
immediately below the application menu bar.
Status Bar Enables the display of status information and
command descriptions in the lower left corner
of the window.
Real Time Selects RTP database files for listing in the
Database Files window.
Message Selects message database files for listing in the
Database Files window.
Message Index Displays message index information in the files
Database Files listing window.
Slow Reduction Displays slow reduction database files in the
Database Files files listing window.
Medium Reduction Displays medium reduction database files in
Database Files the files listing window.
Fast Reduction Displays fast reduction database files in the files
Database Files listing window.
146
4. Database Management B0193YL – Rev E
Tool Bar
Menu Submenu Icon Description
Select Check Checks the selected database file for archiving.
147
B0193YL – Rev E 4. Database Management
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.
Bytes The file’s 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.
148
4. Database Management B0193YL – Rev E
149
B0193YL – Rev E 4. Database Management
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 num-
ber 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
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.
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
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.
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
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 loca-
tion 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 avail-
able 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 sched-
ule 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.
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).
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).
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.
159
B0193YL – Rev E 4. Database Management
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.
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.
Figure 4-18. Display of Archived RTP Files in the AIM*Historian Spy Window
161
B0193YL – Rev E 4. Database Management
162
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 kill-
ing 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 employ-
ing 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.
164
5. Troubleshooting B0193YL – Rev E
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.
166
5. Troubleshooting B0193YL – Rev E
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 infor-
mation 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 Name of the AIM*Historian instance.
Collector Name of the real-time collector. Specify a collector when
you want to view the circular file for samples from a
specific collector.
Verbosity 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.
! CAUTION
Use Verbosity level 2 and above with care. For a very large circular file, the time it
takes dumprcol to sanity-check the file’s linked list and print messages will delay
sample collection at the remote collector.
169
B0193YL – Rev E 5. Troubleshooting
170
5. Troubleshooting B0193YL – Rev E
Field Description
Push Offset Where the next message goes.
Pull Offset Where histsend retrieves from (0=empty).
Last Message Offset Offset to last inserted message.
Last Inserted Message# Number of last inserted message.
# Messages Overwritten Number of messages overwritten in file.
# Bytes in File Number of bytes in file currently in use.
Last Sent Message# Last send message number.
Oldest Message Offset Determines where to start looking for the last message
received by histreceive. This field is used when the
instance reconnects with the remote collector.
Highwater #Bytes in File Highest number of bytes ever used in the file.
Collector Time Zone (TZ) Time zone configured for collectors running on this
machine.
Collector DST Daylight savings time. Yes is 1. No is 0.
Collector Type Collector type. See Table E-5 for a description of the
TYPE attribute.
Current synch offset Holds offset to message during synchronization of file
on reconnect.
# Samples Overwritten Number of samples overwritten since last histreceive
startup.
# Event Msgs Overwritten Number of event messages overwritten since last histre-
ceive 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] <Instance> <File Type> [<File Number>]
Where:
Instance Name of the AIM*Historian instance.
-vnumber 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.
File Type r for RTP.
rf for fast reduction file.
rm for medium reduction file.
rs for slow reduction file.
File Number 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
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 func-
tion 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. Select menu item 30 for getidx() function.
4. Enter C1 for compound.
5. Enter B1 for block.
6. Enter RI01 for parameter.
7. Note the returned index. An index of -1 means the object is not in the AIM*API
database.
8. Select menu item 33 for mreaidx() function.
9. Enter noted object index for index.
10. Enter y for end of indexes.
11. Observe results.
12. 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 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.
instance Name of the AIM*Historian instance.
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 select-
able 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 mes-
sage 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] <instance>
Where:
-vnumber 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.
instance Name of the AIM*Historian instance.
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 Mes-
sage Configuration” on page 72).
! CAUTION
DO NOT use msgtst to insert messages into a production AIM*Historian instance.
180
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> 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 Name of the AIM*Historian instance.
file number RTP file by number. If not used, all RTP
files are checked.
type 0 = RTP (default)
1 = RF
2 = RM
3 = RS
[No arguments] Prints a usage synopsis.
NOTE
The rtpcheck program performs only read operations and can therefore be executed
on-line without shutting down the instance.
182
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 com-
pletely 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 Name of the AIM*Historian instance.
file number RTP file by number. If not used, all RTP files
are checked.
type 0 = RTP (default).
1 = RF.
2 = RM.
3 = RS.
[No arguments] Prints a usage synopsis.
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 simu-
late 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 any-
where 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 per-
formed 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 ( location of AIM*Historian programs
testhv ( run testhv
h ( Select Historian
hst0j1 ( example for a historian instance
s ( Select Server
s ( s for hsfetch (I/A)
m ( setup new message;
( what follows is the request message contents:
Message Type[] 2 ( = SMP_DATA, this is the request type for raw data
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 server’s 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.
186
5. Troubleshooting B0193YL – Rev E
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 instru-
ment 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 Name of the AIM*Historian instance.
type 0 = RTP files (default).
1 = Fast reduction files.
2 = Medium reduction files.
3 = Slow reduction files.
4 = Messages.
[No arguments] 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 suc-
cessful. 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 individ-
ual 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, pro-
duces 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 Jour-
nal. Run fh_sacego without arguments for instructions.
189
B0193YL – Rev E 5. Troubleshooting
! 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
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
192
5. Troubleshooting B0193YL – Rev E
193
B0193YL – Rev E 5. Troubleshooting
194
5. Troubleshooting B0193YL – Rev E
195
B0193YL – Rev E 5. Troubleshooting
196
5. Troubleshooting B0193YL – Rev E
197
B0193YL – Rev E 5. Troubleshooting
198
5. Troubleshooting B0193YL – Rev E
199
B0193YL – Rev E 5. Troubleshooting
200
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.
Return Name
0 FH_NO_ERROR
-1 FH_ERROR
201
B0193YL – Rev E Appendix A. Error Codes
202
Appendix A. Error Codes B0193YL – Rev E
203
B0193YL – Rev E Appendix A. Error Codes
204
Appendix A. Error Codes B0193YL – Rev E
205
B0193YL – Rev E Appendix A. Error Codes
206
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 typedef’d 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.
Table B-1. Status Definition with I/A Series Version 4.3 and Later
31 (msb) 3 to
to 16 15 14 13 12 11 10 9 8 7 to 5 4 0 (lsb)
OM Connect Status
Ack/uncond. init
Limited High
Limited Low
Bad/Dis/Ok
Value Type
Sec/Unsec
Reserved
Shadow
Change
Error
00S
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 consid-
ered to be bits 0 to 4.
Bit 12 The point is a shadow parameter (1) or not a shadow parameter (0).
Bits 16 to 31 Reserved
208
Appendix B. AIM*Historian Sample Status and Quality B0193YL – Rev E
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.
209
B0193YL – Rev E Appendix B. AIM*Historian Sample Status and Quality
210
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.
Table B-3. RTP Quality Definition with I/A Series Version 4.2 and Later
31 (msb) 30 29 28 27 to 26 25 24 to 0 (lsb)
Trigger Inaccessible
Minimum Peak
Collector Off
RTP Off
Reserved
Reserved
Peak
When an RTP is turned off, AIM*Historian writes a sample with the RTP’s 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 RTP’s 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.
0X10000000(bit 28 set): The collector is turned off.
These actions mark the time ranges when an RTP is not being collected.
Bits 30 and 31 are used for peak detection:
0x40000000 (bit 30set): 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 RTP’s 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 Appendix B. AIM*Historian Sample Status and Quality
212
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 OR’d into
the status, which are defined in aimhistorian.h and are listed from the header for reference:
Table C-1 and the notes that follow it define the status returned by these APIs.
31 (msb) 4 to 0
to 10 9 8 7 6 to 5 (lsb)
FH_OUT_OF_COLLECTED_RANGE
FH_PARTIAL_INTERVAL
Value Type
UNAVAIL
Reserved
Reserved
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.
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. Other-
wise, 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.
Operation Algorithm
Summation(SUM) Sum of samples in the reduction period.
Maximum(Max) Maximum sample value.
Minimum(Min) Minimum sample value.
Average (AVG) sum of samples
x = --------------------------------------
sample count
sum of samples**4
(Average of samples4) x**4 = ------------------------------------------------
sample count
215
B0193YL – Rev E Appendix D. Data Reduction Algorithms
Operation Algorithm
Linearization Sample value at, or closest before, the time stamp for each time interval.
Current value (CUR) The current value of the RTP.
Peaks (PEAKS) 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
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.
217
B0193YL – Rev E Appendix D. Data Reduction Algorithms
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.
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.
219
B0193YL – Rev E Appendix D. Data Reduction Algorithms
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, how-
ever, 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.
Percent of
Configured Request
Reduction Range with Start Time Start Time Start Time
File Type Interval Data 12:00 a.m. 1:00 a.m. 1:12 a.m.
Slow 86400 0
Medium 3600 0
Fast 360 0
Sample N/A > 0% X X X
220
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 indi-
cated start time.
Percent of
Configured Request
Reduction Range with Start Time Start Time Start Time
File Type Interval Data 12:00 a.m. 1:00 a.m. 1:12 a.m.
Slow 86400 100 X
Medium 3600 100 X
Fast 360 100 X
Sample Not applicable
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 indi-
cated start time.
Table D-5. Selection of Medium and Fast Reduction Files for a Reduction Request
Percent of
Configured Request
Reduction Range with Start Time Start Time Start Time
File Type Interval Data 12:00 a.m. 1:00 a.m. 1:12 a.m.
Slow 86400 60
Medium 3600 100 X X
Fast 360 100 X
Sample Not applicable
221
B0193YL – Rev E Appendix D. Data Reduction Algorithms
222
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 program-
ming 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
224
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.
Attribute Description
NAME 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
SESKEY 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*Histo-
rian instance; this is how the AIM*Historian Configurator uses SESKEY.
Default: Instance name
Actions: GET PUT MOD DEL
SESSTAT 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 config-
ure 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.
REDPHASEUNIT
Reduction phase offset units
226
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
227
B0193YL – Rev E Appendix E. AIM*Historian Component Attributes
Attribute Description
NAME 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 automati-
cally 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”
228
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
ARCHSIZE 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 collector’s
CIRCFILESIZE by 4.
CFGPTS 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
Attribute Description
COMPRESS 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
DBPATH 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
EMAIL Reserved for future use.
ENABLE_STUBS 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.
FHDESC 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.
HISTTRACE Reserved for future use.
230
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
IATIME 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.
LIKE 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.
LRCCALC Reserved for future use.
MAXLOG Reserved for future use.
MAXPTS 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
Attribute Description
MAXCGENTS 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.
MAXRGENTS 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.
MDEGETMETHOD 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.
232
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
MSGDEFS 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.
MSGFILE 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.
MSGTIME Reserved for future use.
MSGTRACE Reserved for future use.
MXSRVPTS 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
Attribute Description
PCTVALID 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 reduc-
tion, 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
♦ 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.
REDFASTINT Fast reduction interval.
Default: 1
Actions: GETQTY GET PUT MOD
♦ See “Note on Reduction Intervals” on page 236.
REDFASTUNIT 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.
REDMEDINT Medium reduction interval.
Default: 8
Actions: GETQTY GET PUT MOD
♦ See “Note on Reduction Intervals” on page 236.
REDMEDUNIT 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.
234
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
REDPHASEUNIT Reduction phase offset units in minutes.
FH_REDUC_UNIT_MIN, 3, MINUTES
Default: Minutes (3)
Actions: GETQTY GET PUT MOD
REDSLOWINT Slow reduction interval.
Default: 1
Actions: GETQTY GET PUT MOD
♦ See “Note on Reduction Intervals” on page 236.
REDSLOWUNIT 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.
REDUCLEVEL 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
REDUCPHASE Reduction phase offset from even time base.
0 to 59
Default: 0
Actions: GETQTY GET PUT MOD
RTTIME 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.
RTTRACE Reserved for future use.
235
B0193YL – Rev E Appendix E. AIM*Historian Component Attributes
Attribute Description
SCANPEAKS 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 signif-
icantly 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
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
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 real-
time collector, you need to explicitly create a collector station.
TZ Time zone
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.
237
B0193YL – Rev E Appendix E. AIM*Historian Component Attributes
IPADDR Hostname used by the remote collector (for backward compatibility with
instances prior to AIM*AT 3.2)
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 collector’s 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 instance’s other remote collectors running on the same machine.
238
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
NAME 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.
BURSTBTPCT 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 exam-
ple.
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
Attribute Description
BURSTTTPCT 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
BURSTINT 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
240
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
CIRCFILESIZE 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.
COLDESC 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.
CONSLEEPSECS 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
Attribute Description
COLPORT 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 collector’s COLPORT attribute cannot be modified.
The remote collector’s 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
CSTARTONBOOT 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 instance’s remote collectors.
On reboot of a remote collector machine, AIM*Historian automati-
cally 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
242
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
DST 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.
FOLLOWINSTOF 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 instance’s 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
FOLLOWINSTON 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
instance’s 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
Attribute Description
HOSTNAME 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 collector’s 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
IPADDR 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.
ISIA 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
ISREMOTE 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
MINCOLCYCLE 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 collector’s 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 collector’s cycle
at MINCOLCYCLE and logs a warning message to historian.log.
Default: 500
Actions: GETQTY GET PUT MOD
244
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
NODE I/A Series node number the collector is located on (1, 2, 3, and so on).
Default: 1
Actions: GETQTY GET PUT MOD
PLATFORM 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
RECVPASSUPDS 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.
SENDPASSSECS 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.
TYPE 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
TZ 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
FH_GMT 1 GMT
FH_GMT_PLUS_1 2 GMT_PLUS_1
FH_GMT_PLUS_2 3 GMT_PLUS_2
FH_GMT_PLUS_3 4 GMT_PLUS_3
FH_GMT_PLUS_330 5 GMT_PLUS_330
FH_GMT_PLUS_4 6 GMT_PLUS_4
FH_GMT_PLUS_430 7 GMT_PLUS_430
FH_GMT_PLUS_5 8 GMT_PLUS_5
FH_GMT_PLUS_530 9 GMT_PLUS_530
FH_GMT_PLUS_6 10 GMT_PLUS_6
FH_GMT_PLUS_7 11 GMT_PLUS_7
FH_GMT_PLUS_8 12 GMT_PLUS_8
FH_GMT_PLUS_9 13 GMT_PLUS_9
FH_GMT_PLUS_930 14 GMT_PLUS_930
FH_GMT_PLUS_10 15 GMT_PLUS_10
FH_GMT_PLUS_11 16 GMT_PLUS_11
FH_GMT_PLUS_12 17 GMT_PLUS_12
FH_GMT_MINUS_1 18 GMT_MINUS_1
FH_GMT_MINUS_2 19 GMT_MINUS_2
FH_GMT_MINUS_3 20 GMT_MINUS_3
FH_GMT_MINUS_330 21 GMT_MINUS_330
FH_GMT_MINUS_4 22 GMT_MINUS_4
FH_GMT_MINUS_5 23 GMT_MINUS_5
FH_GMT_MINUS_6 24 GMT_MINUS_6
FH_GMT_MINUS_7 25 GMT_MINUS_7
FH_GMT_MINUS_8 26 GMT_MINUS_8
FH_GMT_MINUS_9 27 GMT_MINUS_9
FH_GMT_MINUS_10 28 GMT_MINUS_10
FH_GMT_MINUS_11 29 GMT_MINUS_11
FH_GMT_MINUS_12 30 GMT_MINUS_12
246
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 tradi-
tional 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.
Describe an RTP
DESC Descriptor
247
B0193YL – Rev E Appendix E. AIM*Historian Component Attributes
248
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
NAME 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 RTP’s 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.
AUDITUPD Reserved for future use.
COLLECTOR 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.
COLMETH 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
Attribute Description
DESC 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.
ENGUNITS Engineering units descriptor of up to 6 (FH_ENG_UNIT_LEN) characters.
Default: None
Actions: GETQTY GET PUT MOD
EXPORT 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.
FASTFREQ 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.
FFREQUNITS 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.
250
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
HASVALUE Reserved. Set and used by histsave and histbatch programs to protect the
configurations in .inp files.
HIRANGE High range of the RTP’s value in engineering units; used for Trending and
to validate MDE insertions if the RTP’s COLMETH is MDE.
Default: 100.0
Actions: GETQTY GET PUT MOD
INDEX AIM*Historian assigns a unique INDEX value for an RTP when
AIM*Historian creates the RTP.
Default: Assigned by AIM*Historian
Actions: GETQTY GET
INITSTATE 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.
LIKE Name of the existing RTP used to create a new RTP.
Up to 32 (FH_TAG_LEN) characters.
Default: None
Actions: CREATE
LORANGE Low range of the RTP’s value in engineering units, used for Trending and to
validate MDE insertions if the RTP’s COLMETH is MDE.
Default: 0.0
Actions: GETQTY GET PUT MOD
MXSAMTIME 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 RTP’s 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
Attribute Description
MXSAMUNITS 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.
NAMEINCOL 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.
252
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
NAMEINCOL For an I/A Series collector, the NAMEINCOL refers to I/A Series objects,
(For I/A Series which can be specified as follows:
objects) 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 accessi-
ble 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
NAMEINCOL For an I/O Gate collector, the NAMEINCOL syntax is specific to the I/O
(For I/O Gate) Gate Driver on your system. Refer to the AIM*AT I/O Gate Drivers User’s
Guide (B0193YU).
NUMELEMS 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.
READDELTA 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
Attribute Description
RSTRTSTATE 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
SFREQUNITS 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 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.
254
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
SLOWFREQ 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.
TRGCHANGE 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.
TRIGGER 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
Attribute Description
TYPE 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 1 CHAR
FH_INTEGER 2 INTEGER
FH_FLOAT 3 FLOAT
FH_BOOLEAN 5 BOOLEAN
FH_LONG 6 LONG
FH_SHORT 8 SHORT
FH_INT_PACKED 9 INT_PACKED
FH_LONG_PACKED 10 LONG_PACKED
FH_CHAR_ARRAY 21 CHAR_ARRAY
FH_SHORT_ARRAY 22 SHORT_ARRAY
FH_INTEGER_ARRAY 23 INTEGER_ARRAY
FH_LONG_ARRAY 24 LONG_ARRAY
FH_FLOAT_ARRAY 25 FLOAT_ARRAY
FH_DOUBLE_ARRAY 26 DOUBLE_ARRAY
FH_UCHAR_ARRAY 27 UCHAR_ARRAY
FH_USHORT_ARRAY 28 USHORT_ARRAY
FH_UINT_ARRAY 29 UINT_ARRAY
FH_ULONG_ARRAY 30 ULONG_ARRAY
FH_STRING 31 STRING
FH_USER_TYPE_START 50 USER
FH_FILE 51 FILE
FH_TIMESTAMP 52 TIMESTAMP
256
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
NOTE
Refer to /opt/aim/examples/histbatch.inp for the definition of I/A Series “legacy”
and “iaalarm” message groups.
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
Attribute Description
NAME 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.
DEFN 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.
DEFN For example:
(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.
258
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
GROUP 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.
INDEX 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
LIKE 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
UPDATE Reserved for future use.
259
B0193YL – Rev E Appendix E. AIM*Historian Component Attributes
260
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
NAME Control group name of up to 10 (FH_GROUPNAME_LEN) characters.
Default: None
Actions: CREATE GETQTY GET DEL
DESC Control group descriptor of up to 32 (FH_DESCRIPTOR_LEN) charac-
ters.
Default: None
Actions: GETQTY GET PUT MOD
Enclose the attribute value in quotation marks if blank spaces are to be
included in the description.
MSGNAME 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
TAG 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
Attribute Description
TAG Example: To turn on all controlled RTPs and messages in the control group
(Example) 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.
262
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
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.
263
B0193YL – Rev E Appendix E. AIM*Historian Component Attributes
Attribute Description
NAME Group name of up to 10 characters (FH_GROUPNAME_LEN).
Default: None
Actions: CREATE GETQTY GET DEL
DESC 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.
EXPORT Specifies whether the group’s 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.
FREQ 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
FREQUNITS 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
264
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
Attribute Description
OPER 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
PCTVALID 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
TAG 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
! CAUTION
The configuration of time settings is not difficult, but it must be done carefully
because there is no protection against configuration errors.
266
Appendix E. AIM*Historian Component Attributes B0193YL – Rev E
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
machine’s 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.
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 mes-
sage 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
271
B0193YL – Rev E Appendix F. Sizing Guidelines
Read Delta
The RTP Read Delta attribute (READDELTA) specifies the minimum change of a variable rela-
tive 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 point’s 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 transmitter’s 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 point’s 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.
272
Appendix F. Sizing Guidelines B0193YL – Rev E
273
B0193YL – Rev E Appendix F. Sizing Guidelines
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.
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 func-
tions they perform are illustrated in Figure G-1.
275
B0193YL – Rev E Appendix G. Exporting to Oracle
AIM*Historian Host
Configuration
Information Exported Instance/Export
AIM*Historian HistExport Data Directory
Instance Creates export files (Holds the .ctl, .sql,
Historized .dat and .tim files)
Data
Frequency at which
data must be exported Export
Files
export.ini HistMove
(Export schedule and Moves the export files
Oracle destination) from AIM*Historian
to Oracle
Hist2Oracle
/<export directory>
SQL*Plus is executed for
every .sql file that creates /data/<machine>
tables in the database. /<instance>directory
Oracle Database
SQL*Loader is executed for (Stores the .ctl and
every .ctl file that loads .sql files. You can
exported data into the tables. specify the path.)
Updates data, log, and
reject directories.
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 fol-
lowing 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 hav-
ing 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.
279
B0193YL – Rev E Appendix G. Exporting to Oracle
280
Appendix G. Exporting to Oracle B0193YL – Rev E
281
B0193YL – Rev E Appendix G. Exporting to Oracle
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 message—the first 4 bytes contain the
time stamp and the remaining 256 bytes contain the message name.
282
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.
283
B0193YL – Rev E Appendix G. Exporting to Oracle
284
Appendix G. Exporting to Oracle B0193YL – Rev E
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.
285
B0193YL – Rev E Appendix G. Exporting to Oracle
286
Appendix G. Exporting to Oracle B0193YL – Rev E
287
B0193YL – Rev E Appendix G. Exporting to Oracle
288
Appendix G. Exporting to Oracle B0193YL – Rev E
289
B0193YL – Rev E Appendix G. Exporting to Oracle
290
Appendix G. Exporting to Oracle B0193YL – Rev E
291
B0193YL – Rev E Appendix G. Exporting to Oracle
292
Appendix G. Exporting to Oracle B0193YL – Rev E
293
B0193YL – Rev E Appendix G. Exporting to Oracle
294
Appendix G. Exporting to Oracle B0193YL – Rev E
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.
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).
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.
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.
Dictionary Schema
InstCfg
The Instance Configuration (InstCfg) schema contains the AIM*Historian configuration
information (Table H-2).
299
B0193YL – Rev E Appendix H. AIM*OLE DB Provider
RTPCfg
The RTP Configuration Table (RTPCfg) contains configuration information for the RTPs in the
instance (Table H-3).
300
Appendix H. AIM*OLE DB Provider B0193YL – Rev E
MsgTableCfg
The Message Configuration Table (MsgTableCfg) contains the message group and message
names in the instance (Table H-4).
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.
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).
ControlGroupCfg
The parameters accessible from the Control Group Configuration Table (ControlGroupCFG)
are listed in Table H-7.
302
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).
ControlGroupMsgs
The Control Group Messages Table (ControlGroupMsgs) lists the messages included in each
control group (Table H-9).
ReductionGroupCfg
The ReductionGroupCfg Table (Table H-10) contains the parameters for each reduction group in
the instance.
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.
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).
RTPEntries
The RTP Values Table (RTPEntries) contains the historized RTPs, and includes value, status
information, and time stamps (Table H-13).
304
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).
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
Argument Usage
Provider Specify AIMHistProv.OLEDB
Data Source The data source is AIMApiCOM.Root
Initial Catalog 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 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.
User ID 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 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
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 Average
linear Linearized
kurt Kurtosis
max Maximum
min Minimum
stddev Standard Deviation
sum Sum
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.
Insert Statement
You can use AIM*OLE DB Provider to insert values in AIM*Historian RTPs if the following con-
ditions 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
Dim s As String
If conn.State = adStateClosed Then
MsgBox "Not connected to Datasource"
Exit Sub
End If
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 Index
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 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 Index
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 B0193YL – Rev E
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 Index
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 B0193YL – Rev E
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 Index
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 B0193YL – Rev E
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