b0193bl L

B0193BL
REV L
I/A Series®
Historian
July 20, 2007
Invensys, Foxboro, and I/A Series are trademarks of Invensys plc, its subsidiaries, and affiliates.
All other brand names may be trademarks of their respective owners.
Copyright 1990-2007 Invensys Systems, Inc.

All rights reserved
SOFTWARE LICENSE AND COPYRIGHT INFORMATION

Before using the Invensys Systems, Inc. supplied software supported by this documentation, you
should read and understand the following information concerning copyrighted software.
1. The license provisions in the software license for your system govern your obligations
and usage rights to the software described in this documentation. If any portion of
those license provisions is violated, Invensys Systems, Inc. will no longer provide you
with support services and assumes no further responsibilities for your system or its
operation.
2. All software issued by Invensys Systems, Inc. and copies of the software that you are
specifically permitted to make, are protected in accordance with Federal copyright
laws. It is illegal to make copies of any software media provided to you by
Invensys Systems, Inc. for any purpose other than those purposes mentioned in the
software license.
Contents
Figures.................................................................................................................................... ix
Tables..................................................................................................................................... xi
Preface................................................................................................................................. xiii
Audience ................................................................................................................................ xiii
Contents ................................................................................................................................ xiii
Revision Information ............................................................................................................. xiv
Related Documentation ......................................................................................................... xiv
1. Introduction ...................................................................................................................... 1
Historian Functions .................................................................................................................. 1
Historian Reports ...................................................................................................................... 2
Multiple Historians ................................................................................................................... 3
Remote Functions ..................................................................................................................... 3
2. Functional Overview ......................................................................................................... 5

Data Collection ......................................................................................................................... 5
Point Samples ....................................................................................................................... 8
Sample Collection ................................................................................................................ 9
Reduced Values .................................................................................................................. 10
Messages ............................................................................................................................. 11
Archives .............................................................................................................................. 12
Manual Data Entry Values ................................................................................................. 13
Workstation Interface ............................................................................................................. 13
Configuring the Historian .................................................................................................. 14
Scheduling Historian Functions ......................................................................................... 14
Displaying Historical Data ................................................................................................. 14
Archiving Historical Data ................................................................................................... 15
Accessing Historian Displays .............................................................................................. 15
Help ................................................................................................................................... 15
Screen Control Functions ................................................................................................... 15
Application Interface ............................................................................................................... 16
Time Adjustment .................................................................................................................... 17
Security Features ..................................................................................................................... 17
Installation .............................................................................................................................. 17
iii
B0193BL – Rev L Contents
3. Configurator.................................................................................................................... 19
User Interface .......................................................................................................................... 19
Working in the Configurator Screens ................................................................................. 21
Buttons and Icons .............................................................................................................. 22
Top Menu Bar ................................................................................................................... 23
Guidelines for Entries ......................................................................................................... 23
Configuring Member Points ................................................................................................... 24
Collection Point Fields ....................................................................................................... 24
Options .............................................................................................................................. 25
Defining Reduction Groups .................................................................................................... 26
Reduction Group Parameters ............................................................................................. 26
Cascaded Reduction Groups .............................................................................................. 27
Members and Multiple Selection Buttons ........................................................................... 27
Defining Archive Groups ........................................................................................................ 27
Archive Group Parameters .................................................................................................. 28
Members and Multiple Selection Buttons ........................................................................... 29
Defining MDE Groups and Variables ..................................................................................... 29
MDE Parameters ................................................................................................................ 30
Multiple Selection Button .................................................................................................. 30
Configuring Message Collection ............................................................................................. 31
Message Group Parameters ................................................................................................. 31
4. Scheduling....................................................................................................................... 33
Top Menu Bar ........................................................................................................................ 33
Accessing Scheduler Displays .................................................................................................. 33
Starting or Stopping Historians ............................................................................................... 34
Scheduling Groups .................................................................................................................. 34
5. Data Display ................................................................................................................... 37

Top Menu Bar ........................................................................................................................ 37
Accessing the Data Display Module ........................................................................................ 37
Selecting a Database ................................................................................................................ 38
Selecting a Data Collection Period .......................................................................................... 40
Selecting Reduction Data ........................................................................................................ 41
Displaying Messages ................................................................................................................ 41
6. Archiving......................................................................................................................... 43
Accessing the Archiving Function ........................................................................................... 44
Editing Tape Size .................................................................................................................... 46
Archive Devices ....................................................................................................................... 46
Backing Up Archive Data ........................................................................................................ 46
iv
Contents B0193BL – Rev L
Archive Backup Messages ................................................................................................... 47

Restoring Archives ................................................................................................................... 47
Deleting Restored Archives ..................................................................................................... 48
7. Manual Data Entry.......................................................................................................... 49

Top Menu Bar ........................................................................................................................ 49
Accessing the MDE Editor ...................................................................................................... 49
Editing MDE Values ............................................................................................................... 50
WYSE Terminal and Foreign Database Interface .................................................................... 52
Execution ........................................................................................................................... 52
Input Data ......................................................................................................................... 52
Directives ........................................................................................................................... 53
Samples .............................................................................................................................. 54
Prefix/Suffix Notation ........................................................................................................ 54
Examples ............................................................................................................................ 54
Input File ...................................................................................................................... 54
Program Log .................................................................................................................. 55
8. Calls Overview ................................................................................................................ 57

Linking Application Programs ................................................................................................. 57
Sending Data .......................................................................................................................... 57
Retrieving Data ....................................................................................................................... 58
Changing Configuration Data ................................................................................................. 58
9. Configuration Calls ......................................................................................................... 59

db_init — Database Initialization ........................................................................................... 61
get_sum — Get Type Summary .............................................................................................. 61
add_cfg — Add Group Configuration .................................................................................... 62
mod_cfg — Modify Group Configuration .............................................................................. 65
del_cfg — Delete Group Configuration .................................................................................. 66
get_cfg — Get Group Configuration ...................................................................................... 67
add_mem — Add Group Members ........................................................................................ 68
del_mem — Delete Group Members ...................................................................................... 69
get_mem — Get Group Members .......................................................................................... 70
add_opr — Add Operations .................................................................................................... 72
del_opr — Delete Operations ................................................................................................. 73
get_opr — Get Operations ..................................................................................................... 74
mde_apnt — Add/Modify/Delete MDE Point Configuration ................................................ 75
mde_rpnt — Read MDE Point Configuration Data ............................................................... 77
v
mde_agrp — Add/Modify/Delete MDE Group Configuration Data ...................................... 77

mde_rgrp — Read MDE Group Configuration Data ............................................................. 79
mde_amem — Add/Delete MDE Group Member Point ........................................................ 80
mde_rmem — Read MDE Group Members ........................................................................... 81
10. Operation Calls ............................................................................................................. 83

Collection Group State Changes ............................................................................................. 83
get_sta — Get Group Status .............................................................................................. 85
chg_sta — Change Group Status ....................................................................................... 86
Direct Storage of User Data .................................................................................................... 87
req_add — Request Data Add ............................................................................................ 87
add_dat — Add Data ......................................................................................................... 89
get_gmt — Get Greenwich Mean Time ............................................................................. 90
11. Data Retrieval Calls....................................................................................................... 91

Using rq_oval and get_val to Retrieve Reduced Data ......................................................... 92
Using rq_pt and get_pt to Retrieve Data on AP20 ............................................................. 93
Using get_data to Retrieve Data ......................................................................................... 93
db_init — Database Initialization ...................................................................................... 95
rq_oval — Request Operation Values ................................................................................. 95
get_val — Get Values ......................................................................................................... 97
get_key — Get Keys ........................................................................................................... 98
get_nam — Get Names ...................................................................................................... 98
db_dlet — Database Removal ............................................................................................ 99
rq_pt — Request Point Data .............................................................................................. 99
get_pt — Get Point Data ................................................................................................. 101
get_data — Get Point Data .............................................................................................. 102
mde_asmp — Add/Modify/Delete MDE Sample ................................................................. 104
mde_rsmp — Read MDE Samples ....................................................................................... 105
12. Writing Historian Reports .......................................................................................... 107

Historian Database Tables ..................................................................................................... 107
all_groups Table ............................................................................................................... 108
all_points Table ................................................................................................................ 108
reduc_cfg Table ................................................................................................................ 108
arch_cfg Table .................................................................................................................. 110
messag_cfg Table .............................................................................................................. 111
pnt_memb Table .............................................................................................................. 111
grp_memb Table .............................................................................................................. 111
reduc_op Table ................................................................................................................ 112
tnd_memb Table .............................................................................................................. 112
arch_sets Table ................................................................................................................. 113
messages Table ................................................................................................................. 113
sysmonmsg Table ............................................................................................................. 114
opraction Table ................................................................................................................ 114
vi
Contents B0193BL – Rev L
Reduction Group Table ................................................................................................... 115

Report Writing Using INFORMIX-ACE Report Writer ...................................................... 116
Basic ACE Report Specification Structure ............................................................................. 116
Report Specification File Sections ..................................................................................... 117
Using C Functions with ACE Report Specification .......................................................... 119
Generating a Report ......................................................................................................... 122
Examples of Report Specifications .................................................................................... 124
Example 1 ................................................................................................................... 124
Example 2 ................................................................................................................... 128
Example 3 ................................................................................................................... 132
Report Writing Using Spreadsheet - AP20 ............................................................................ 138
Scheduling Reports ............................................................................................................... 139
13. Managing Databases.................................................................................................... 143

Accessing VT100 Mode ........................................................................................................ 143
Initializing the Historian Database ........................................................................................ 143
AP20/PW Database Initialization ..................................................................................... 143
AP50/51 Database Initialization ....................................................................................... 144
Copying an AP20/PW Configuration Database .................................................................... 144
Replacing an Existing Database ............................................................................................. 145
Deleting the Archive Database .............................................................................................. 146
Deleting an AP20/PW Archive Database .......................................................................... 146
Deleting an AP50/51 Archive Database ............................................................................ 146
Converting the AP20/PW Database to AP50/51 Database .................................................... 147
Optimizing the AP50/51 Historian Database ........................................................................ 148
Optimizing with Collection Point Grouping .................................................................... 148
Optimizing by Saving Disk Space ..................................................................................... 148
Saving the AP50/51 Historian Database ................................................................................ 149
Reloading the AP50/51 Historian Database .......................................................................... 149
Merging AP50/51 Historian Databases ................................................................................. 150
Merging Databases on the Same AP ................................................................................. 150
Merging Databases from Different Media ........................................................................ 150
Appendix A. Data Reduction Algorithms .......................................................................... 153
Appendix B. Object Manager Status Tag Processing ......................................................... 155
Appendix C. Disk Space Required for Sampling Points..................................................... 157
Appendix D. Sizing Guidelines.......................................................................................... 159

AP20 Workstations ............................................................................................................... 159
Sizing Historians .............................................................................................................. 159
vii
Rules for Collection Point Sampling ............................................................................ 159

Rules for Reduction Groups ........................................................................................ 159
Rules for Fixed Size Files ............................................................................................. 160
Rules for Reduction Data and Index File ..................................................................... 160
Rules for Message Data Files ........................................................................................ 160
Rules for Archives ........................................................................................................ 161
Rules for Extended Sample Files .................................................................................. 161
Displaying Archive Disk Usage ......................................................................................... 161
Sizing Disks for Extended Sampling ................................................................................. 162
AP50/AW50 Workstations .................................................................................................... 164
Bulk Storage Sampling Data ............................................................................................. 165
Bulk Storage Reduction Data ........................................................................................... 165
Bulk Storage Manual Data ............................................................................................... 166
AP51A/AW51A Workstations .............................................................................................. 166
Processing Load ................................................................................................................ 166
Number of Workstations ............................................................................................. 166
Number of Collection Points ....................................................................................... 167
Historian Reduction Points Per Minute ...................................................................... 168
Historian Bulk Storage ..................................................................................................... 168
Sampling Disk Space Requirements ............................................................................. 168
Reduction Disk Space Requirements ........................................................................... 168
Manual Data Entry Groups Disk Space ....................................................................... 169
AP51B/AW51B Workstations ............................................................................................... 169
Sampling Rate .................................................................................................................. 170
Reduction Rate ................................................................................................................. 170
Bulk Storage Requirements .............................................................................................. 171
Sampling Disk Space Requirements ............................................................................. 171
Reduction Disk Space Requirements ................................................................................ 171
Manual Data Entry Groups Disk Space ............................................................................ 172
AW51C Workstations ........................................................................................................... 172
AW51C Sampling Rate .................................................................................................... 172
AW51C Reduction Rate .................................................................................................. 173
Index .................................................................................................................................. 175
viii
Figures
1-1. Tabular Display of Reduced Data ................................................................................. 1
1-2. Historian Application Diagram ..................................................................................... 2
1-3. Historian Data Report Generation ................................................................................ 3
1-4. Historian Data Trend Display ....................................................................................... 4
2-1. Historian Data Collection ............................................................................................. 6
2-2. Historian Data Flow ..................................................................................................... 7
2-3. Historian Functional Block Diagram ............................................................................ 7
2-4. Historian Point Sample Collection in AP Memory ....................................................... 8
2-5. Historian Point Sample Storage on AP Disk ................................................................. 9
2-6. Historian Reduction Group Data Storage ................................................................... 10
2-7. Cascaded Reduction Diagram ..................................................................................... 11
2-8. Historian Application Message Collection ................................................................... 12
2-9. Historian Workstation Interface Menu Structure ........................................................ 13
3-1. Typical Historian Configurator Screen ........................................................................ 21
3-2. Multiple Selection Screen 3 ......................................................................................... 22
3-3. Point Collection Configuration Screen ........................................................................ 24
3-4. Main Reduction Group Screen ................................................................................... 26
3-5. Main Archive Group Screen ........................................................................................ 28
3-6. MDE Group Configuration Screen ............................................................................. 29
3-7. Message Group Configuration Screen ......................................................................... 31
4-1. Historian Scheduler Main Menu ................................................................................. 34
4-2. Historian Scheduler Detail Display ............................................................................. 35
5-1. Data Display Main Menu ........................................................................................... 38
5-2. Membership Screen ..................................................................................................... 40
5-3. Message Data Display Screen ...................................................................................... 42
6-1. Archive Backup and Restore Display ........................................................................... 45
7-1. Manual Data Single Variable Edit Display .................................................................. 50
ix
B0193BL – Rev L Figures
x
Tables
7-1. Console Program (mdew1) Examples .......................................................................... 52
7-2. Historian Directives .................................................................................................... 53
9-1. Configuration Calls ..................................................................................................... 59
10-1. Operation Calls ........................................................................................................... 83
10-2. Collection Group States .............................................................................................. 83
10-3. Group State Control Signal ......................................................................................... 84
10-4. State Transitions for Scheduled Groups ...................................................................... 84
10-5. State Transitions for Message Groups ......................................................................... 85
11-1. Data Retrieval Calls ..................................................................................................... 91
12-1. Example of all_points Database Table ....................................................................... 107
12-2. Example of Reduction Group Database Table ........................................................... 107
12-3. all_groups Table Definition ...................................................................................... 108
12-4. all_points Table Definition ....................................................................................... 108
12-5. reduc_cfg Table Definition ....................................................................................... 108
12-6. arch_cfg Table Definition ......................................................................................... 110
12-7. messag_cfg Table Definition ..................................................................................... 111
12-8. pnt_memb Table Definition ..................................................................................... 111
12-9. grp_memb Table Definition ..................................................................................... 112
12-10. reduc_op Table Definition ........................................................................................ 112
12-11. tnd_memb Table Definition ..................................................................................... 113
12-12. arch_sets Table Definition ........................................................................................ 113
12-13. messages Table Definition ......................................................................................... 113
12-14. sysmonmsg Table Definition ..................................................................................... 114
12-15. opraction Table Definition ........................................................................................ 114
12-16. reduction_group_name Table Definition .................................................................. 115
A-1. Algorithms for Reducing Data .................................................................................. 153
D-1. Message Data File Sizes ............................................................................................. 160
D-2. Sample Loading ........................................................................................................ 163
D-3. Time Duration Examples for Maximum File Size ..................................................... 163
D-4. Time Duration Examples for 120 MB Disk .............................................................. 164
D-5. Time Duration Examples for 80 MB Disk ................................................................ 164
D-6. AP51A Sampling Rate ............................................................................................... 168
D-7. AP51B Sampling Rates ............................................................................................. 170
D-8. AP51B/AW51B Sampling Disk Space ....................................................................... 171
D-9. AP51B/AW51B Disk Space Requirements ................................................................ 172
D-10. AW51C Sampling Rates ........................................................................................... 173
xi
B0193BL – Rev L Tables
xii
Preface
This document provides guidelines for using the I/A Series Historian and describes how to config-
ure and operate the Historian. The document also describes how to retrieve data from the Histo-
rian using an I/A Series workstation or application programs.
Audience
This book is intended for anyone who needs to install, configure, or use the Historian to collect or
retrieve data.
Contents
The illustrations in this book show the sample screen displays for major Historian functions. His-
torian screens can contain the following areas: a list of selectable objects, edit windows, filters for
entry fields, buttons, and navigational icons. Each chapter describes a major Historian function
and how to use the screens to access Historian functions. This book contains the following chap-
ters and appendixes:
Chapter 1 “Introduction” provides a top level description of the Historian.
Chapter 2 “Functional Overview” describes the relationship of the major Historian functions,
data collection concepts, and the Historian database structure.
Chapter 3 “Configurator” describes the Historian user interface and explains how to use the Con-
figurator to define sample points and data collection groups.
Chapter 4 “Scheduling” describes how to start or stop Historians and data collection groups.
Chapter 5 “Data Display” describes how to produce summaries or tabular displays of data or mes-
sages from the Historian databases.
Chapter 6 “Archiving” describes how to backup, restore, and delete archived databases from dif-
ferent media.
Chapter 7 “Manual Data Entry” describes how to manually enter values for variables that are
members of Historian manual data entry groups.
Chapter 8 “Calls Overview” describes how application programs can interface with the
Historian.
Chapter 9 “Configuration Calls” describes the Foxboro supplied subroutines that configure col-
lection groups in applications.
Chapter 10 “Operation Calls” describes the Foxboro supplied subroutines that retrieve or modify
the operational state of collection groups in applications.
Chapter 11 “Data Retrieval Calls” describes the Foxboro supplied subroutines that access data in
applications.
Chapter 12 “Writing Historian Reports” describes using the INFORMIX™-ACE Report Writer
and I/A Series Spreadsheet utilities to generate reports containing Historian collected data.
xiii
B0193BL – Rev L Preface
Chapter 13 “Managing Databases” describes typical database procedures including copying,

deleting, and merging databases.
Appendix A “Data Reduction Algorithms” contains a table of algorithms for reducing data.
Appendix B “Object Manager Status Tag Processing” describes the fields in the Object
Manager status word.
Appendix C “Disk Space Required for Sampling Points” describes sizing guidelines for
Historian databases on AP20 and 50 Series platforms.
Appendix D “Sizing Guidelines” contains rules for sizing disks for extended sampling,
Historians, and archive disk usage on both the AP20 and the Model 50/51 platforms.
Revision Information
For this release of the document (B0193BL-L), the following changes were made:
Chapter 12 “Writing Historian Reports”
♦ Updated the oaj.ace script in Table 12-15 on page 114.
Related Documentation
For further information on related topics, refer to the following I/A Series documentation:
♦ Display Configurator for 20/30 Series Workstation (B0193AR)
♦ Object Manager Calls (B0193BC)
♦ Process Operations and Displays (B0193MM)
♦ Real-Time Database Manager: INFORMIX™-SQL Relational Database
Management System Version 1.10 (B0193BT)
♦ Statistical Process Control Package (SPCP) (B0193JP)
♦ System Configurator (B0193JH)
♦ System Operations Guide (B0193CR)
♦ Workstation Configuration (B0193AG)
♦ Software Installation (Solaris™ Platform) (B0193JG)
♦ Spreadsheet (10/20/30 Series) (B0193BM).
xiv
1. Introduction
This chapter describes Historian functions, Historian and I/A Series software interfaces, and
Historian reports.
The Historian collects, stores, processes, and archives process data from the control system to pro-
vide data for trends, Statistical Process Control charts, logs, reports, spreadsheets, and application
programs.
The Historian is a tool for collecting, organizing, and storing data for later retrieval. It contains
built-in algorithms for reducing data, and provides workstation displays to retrieve and display
data (Figure 1-1). Typical data are process analog and/or digital points.
Historian Functions
Use the Historian to collect process control point samples, reduced point samples, applica-
tion-generated messages, and manual data entry (MDE) values. The process points accessible
through the Object Manager are either compound:block.parameters from control processors or
shared variables.
Figure 1-1. Tabular Display of Reduced Data
Figure 1-2 shows an application diagram for the Historian.
1
B0193BL – Rev L 1. Introduction
I/A Series Other User I/A Series

Workstations I/A Series Application Control
Industrial Programs Processors
Software and
Gateways
Real-Time Object
Database Manager
Manager
Historian
Figure 1-2. Historian Application Diagram
Examples of I/A Series industrial software that use the Historian are:
♦ Batch Plant Management
♦ Data Validatory
♦ Display Manager
♦ Operator Action Journal
♦ Operator Message Interface
♦ Spreadsheet
♦ Statistical Process Control Package (SPCP)
♦ System Monitor
♦ Report Writer 20.
The Historian uses the Real-Time Database Manager (INFORMIX) to organize data that it col-
lects for reduction, archive, and message groups as well as manually entered data.
Historian Reports
The Real-Time Database Manager allows you to use the ACE Report Writer to generate detailed
reports of historical data for management information. It also allows you to use the other facilities
of the database manager to form relationships and make on-line queries.
The I/A Series Report Writer 20, a display-driven software package, lets you build, configure, and
schedule real-time and historical data reports on an Application Processor 20 (AP20).
Figure 1-3 shows the data flow for ACE reports. Refer to “Writing Historian Reports” on
page 107 and Real-Time Database Manager: INFORMIX-SQL Relational Database Management
System Version 1.10 (B0193BT) for details on how to use the ACE Report Writer and other facili-
ties of the database manager.
2
1. Introduction B0193BL – Rev L
Ace
Database Data Report Report
Manager Writer
Format
Information
Historian
Relational
Database
Figure 1-3. Historian Data Report Generation
The Historian supports trending of historical point samples and reduced data via the Display
Manager. Figure 1-4 shows a typical trend display for historical data. You can build displays for
trending historical data by using the Display Builder and Display Configurators software. For
trending purposes, workstation displays can access historical data from multiple distributed His-
torians.
The Historian also supports the Statistical Process Control Package (SPCP), which provides
charts for analyzing of process quality variables using historical point samples, reduced data, and
MDE data.
Multiple Historians
Multiple independent Historians may be distributed within an I/A Series network, one
Historian package per AP, PW, or AW.
Remote Functions
From workstations hosted by an AP with a Historian, you can perform the following historian
functions on a remote station with a Historian:
♦ Configure the Historian
♦ Retrieve reduction data
♦ Access historical sample data for trending
♦ Access recent sample data for trending
♦ Access reduction data for trending
♦ Start or stop the Historian
♦ Initiate the archive backup, restore, or delete function if the remote AP has a
5.25-inch diskette or streaming tape drive.
3
B0193BL – Rev L 1. Introduction
12:22:891 13:24:391 HT3

2:22:8912: 3:24:3913: CALC1
22:89 24:39 RI01
pct 100.0
25.54
0.0
41.67 pct
61.57 pct HT3
81.64 pct CALC1
RI02
100.0
0.0
HT3
CALC1
RI03
100.0
0.0
HT3
CALC1
RI04
100.0
0.0
Figure 1-4. Historian Data Trend Display
4
2. Functional Overview
This section provides a functional overview of the Historian, describing data collection
concepts, workstation, and application interfaces, and the Historian database structure.
The Historian consists of three basic parts:
♦ Data collection
♦ Workstation interface
♦ Application interface.
The workstation interface provides displays for the following basic functions:
♦ Configuration
♦ Scheduling
♦ Data display
♦ Archive backup/restore
♦ MDE edit entry.
The application interface provides subroutines for the following basic functions:
♦ Configuration
♦ Scheduling
♦ Data retrieval.
The Historian also has internal functions that retrieve point samples and reduced data to support
SPCP chart displays and Display Manager trend displays. These Historian retrieval processes,
hs_fetch and hr_fetch, are invisible to you. They run continuously, even when the Historian is
stopped.
Data Collection
Figure 2-1 shows the data collection process. The Historian collects four classes of data:
♦ Point samples
♦ Reduced values
♦ Messages
♦ MDE values.
5
B0193BL – Rev L 2. Functional Overview
Archive
Groups
Database
Historian Manual
Manager
Data
Entry
Groups
Name, Time
Value, Tag
Sample Application
Reduction Message
Points Groups Groups
Figure 2-1. Historian Data Collection
Point samples are collected in separate files, one for each point.
The Historian has four types of user-configured, data-collection groups:
♦ Reduction
♦ Message
♦ MDE
♦ Archive.
You can configure multiple groups for each of these group types.
Select process points as members of the point sample collection. You can extend sample collection
on an AP20 with an optional second hard disk.
You select members of the point sample collection as members of reduction groups. Reduction
groups can be nested forming cascaded groups with other reduction groups as members.
Message groups are created automatically for each application message format (class) registered
with the Historian (for example, operator action, system monitor, and alarm messages).
You configure (create) MDE variables, and assign them as members of MDE groups.
You select members of the extended sample collection: reduction, cascaded reduction, message, or
MDE groups as members of archive groups (if applicable).
Figure 2-2 is a data flow diagram for the Historian. Figure 2-3 is a functional block diagram for
the Historian.
6
2. Functional Overview B0193BL – Rev L
Process Data (Analog & Digital)
Object Application Messages

2
Manager
Application Supplied Data
I/A Series Configuration Data

and User Configuration Data
Application
Programs Manual Entry Data Historian
Manual Entry Data
I/A Series
Workstations Archived Data
Reduced Data
Application Messages
Not available to user Samples
1 1
application programs
Generic data object I/A Series and I/A Series

2
interface software User Application Workstations
Programs
Figure 2-2. Historian Data Flow
Historian Application Object Historian

Application
Configuration Programs Manager Manual Data
Programs
Displays Entry Displays
Collect Collect Collect Collect

Reduce
Configuration Samples Messages MDE Data
Data
Data
Point Dynamic
Sample Archive
Configuration Historian Alarm
Collection Data
Database Database History
* Alarm
Trend Application Historian
Data Archived History
Displays Programs Databases
Displays Displays
* Reduced Data and
= External to the Historian
Messages Only
Figure 2-3. Historian Functional Block Diagram
Referring to Figure 2-3, data collection consists of:

♦ Collecting configuration data from Configurator displays or application programs
and storing the data in relational database files
7
♦ Collecting point samples from process databases and storing them in flat files
♦ Collecting point samples from process databases, reducing them, and storing the
reduced values in relational database files
♦ Collecting shared variables from application programs, reducing these variables, and
storing the reduced values in relational database files
♦ Collecting messages from application programs and storing these messages in rela-
tional database files
♦ Collecting MDE data and storing it in relational database files
♦ Collecting point samples, reduced data, and messages from the relational database and
storing them in archive data base files.
Point Samples
Figure 2-4 shows historical point sample collection in the AP. The Historian connects to process
points through the Object Manager which sends it an updated point data value (sample) when
the point value exceeds the last stored value by a specified amount (deadband). The Historian
stores point samples by:
♦ Point identifier
♦ Time stamp
♦ Value
♦ Status tag.
When configuring points into the historical database, specify the change deadband for each point
and a minimum time threshold (update time) for storing changes. The available update times are:
1s, 2 s, 4 s, 10 s, 20 s, 30 s, 1 min, 2 min, 5 min, and 10 min. Historical point samples are not
updated until the specified deadband and update time has been reached.
In addition, every second, the 50 Series Historian updates the point with the oldest data to sup-
port trending of quiet points.
Point 1 Samples
Point 2 Samples
Point 3 Samples
Name
Value Object Historian Point 4 Samples
Time Manager
Tag
Point n Samples
* 100 Samples per point maximum for AP50
10 Samples for AP20 Collection Point Buffer*
Figure 2-4. Historian Point Sample Collection in AP Memory
8
Figure 2-5 shows historical point sample storage in the AP. The Historian stores the basic point
samples on the system disk in one circular file that contains up to 99,999,000 samples per point
for the AP50/51, and 200 samples per point for the AP20. On the AP50/51, the number of sam-
ples per point defaults to 600, but you can configure (extend) up to 99,999,000 samples per point
for the AP50 and 99,200 for the AP20. When the maximum number of samples for any point is
reached, the Historian overwrites the oldest samples for that point.
The maximum number of points for sample collection is:
♦ 8000 points for an AP51, Style B or C and AW51, Style B or C
♦ 4000 points for an AP50, AW50, AP51, or AW51
♦ 500 points for an AP20 or PW.
Sample Collection
On the AP50, the Historian stores up to the most recent 100 collected sample values for each
configured collection point in shared memory. When sample 100 is collected for a point, the His-
torian writes the contents of the shared memory buffer for that point to the associated SAM file,
which is located in /opt/fox/hstorian/sample.
If a collection point is not configured for extended sampling, the number of samples defaults to
600. To configure a collection point for extended sampling, specify the number of samples to col-
lect.
Collection Point 1 Samples

Point Point 2 Samples
Buffer
Point n Samples
Basic Collection Points*
Point 1 Samples
Point 2 Samples
System Disk
Point n Samples
Point Historian Extended Collection
Samples
Points**
* 99,999,000 Samples for AP50

200 Samples for AP20
** 99,200 Samples for AP20
AP20 Optional Disk
Figure 2-5. Historian Point Sample Storage on AP Disk
The Historian also provides extended sample collection on an AP20 with an optional second hard
disk. The second hard disk is dedicated to collecting extended samples, archiving them, and play-
ing back these archives.
9
The Historian stores the extended point samples on the optional disk in circular files, one for each
point (see Figure 2-5); each file can contain up to 99,200 samples on an AP20 or 99,999,000 on
an AP50. When the maximum number of samples is reached, the Historian overwrites the oldest
samples.
Reduced Values
The Historian provides the following data reduction operations, which are defined in Appendix A
“Data Reduction Algorithms”:
♦ Average
♦ Maximum
♦ Minimum
♦ Standard deviation
♦ Kurtosis
♦ Summation
♦ Histogram.
Reduced data is stored in an historical database at varying time periods (for example, by hour,
shift, day, or week).
Cascaded reduction groups use input data from other reduction groups. Specifiable reduction
operations for a cascaded group are: average, maximum, minimum, and summation.
You specify data reductions when configuring the Historian. You must specify the minimum
amount of data required for a data reduction operation and the retention time span for the
reduced data values.
Figure 2-6 shows the data storage layout for a reduction group. The Historian stores data records
for a reduction group in a database. When the maximum number of records specified by the con-
figuration is reached, the Historian deletes the oldest reduction data. To retain the data for long
term storage, archive the reduction group.
Data reductions execute on a user-configured schedule. Scheduled executions can be delayed;
specifying a delay factor allows leveling of the data-reduction processing load on the AP.
Variable 1 Variable 2 Variable n

Time Slot 1 Value/Tag Value/Tag Value/Tag
Time Slot 2 Value/Tag Value/Tag Value/Tag
Value/Tag Value/Tag Value/Tag Value/Tag
Figure 2-6. Historian Reduction Group Data Storage
The Historian collects samples to calculate running sums, products, and maximum and mini-
mum values. It uses these calculated values to compute the reduced values on a scheduled basis.
For a cascaded reduction group, input data is retrieved from the specified source reduction group
over the specified time span.
10
The time stamp stored with a reduced value corresponds to the end of the period specified for the
input data, whether or not input data is available.
You can specify the minimum amount of data required for reducing the data. This allows data to
be reduced when some of the input data is not available. Status information for reduced data val-
ues is derived from the input data availability.
You can use the history of reduced values as input for further data reduction via cascaded groups.
Higher order reductions typically calculate long term values from short-term values (for example,
averages, maximums, minimums). Figure 2-7 shows examples of cascaded reductions.
When you configure the Historian, create reduction groups and select member points for reduc-
tion groups from members of the point sample collection.
8 Hours (1 Shift)
1 Hour
Average
Std. Dev. *
Maximum
Minimum
1 Day 1 Week 1 Day

Shift Avg. Shift Maximum, Minimum 4-Hour
Sliding Avg.
1 Week 52 Weeks
Day Avg. Week Maximum, Minimum
* Standard Deviation
Figure 2-7. Cascaded Reduction Diagram
Messages
The Historian collects messages sent to it by I/A Series software or application programs to pro-
vide an information base for display by the Historian and use by other application software. For
example, the system monitors send the Historian messages to indicate system alarm conditions.
Each message contains a message identifier, and one or more data fields in a specified format.
Figure 2-8 shows historical message collection in the AP.
♦ Control processes send the Historian messages to indicate process alarm conditions.
Process alarm messages are stored in a separate file. You can access these messages
through the Alarm History display (refer to Process Operations and
Displays (B0193MM) for details on how to access the Alarm History display). The
maximum number of alarm messages is a system generation parameter that defaults to
504.
The Historian includes some standard message formats required to support I/A Series software,
for example, operator action, and batch plant management message formats. The maximum
number of messages defaults to 100.
11
Message 1
Message 2
Message Group 1
Message n
Message 1
Message 2
Messages Historian Message Group 2
Message n
Message 1
Message 2
Message Group n
Message n
Figure 2-8. Historian Application Message Collection
Message groups are defined by group name, message format fields, and other group attributes.
You configure the maximum number of stored messages.
Archives
The Historian archiving functions allow you to store and manage historical data on streaming
tape or 5.25-inch diskette. This allows unlimited off-line storage of historical data.
Archives consist of named databases, which can reside on several types of storage media to provide
a continuous history. A time stamp is appended to the database name for later reference.
You can archive extended point samples, reduction, cascaded reduction, message, and MDE
groups over a specified time span. Specify the archive group name, members, time span, and
archive period for each archive group during Historian configuration.
When the archive period is reached, the Historian creates a new archive database for the archive
group, and then deletes the old one, if it exists. The system then notifies the operator to back up
the database through a message that is displayed on the message line of all workstations config-
ured for the node. The operator has until the next archive operation for that group to back up the
archive database.
The Historian provides workstation displays for backing up, restoring, and deleting archive group
data. The backup function allows you to store archive group data on streaming tape or 5.25-inch
diskettes. The restore function allows you to restore archive data from these media. The delete
function allows you to delete restored archive data.
On the AP20, the Historian creates and restores archive databases for extended samples on the
hard disk that is dedicated to extended sample collection.
Use the following ways to access restored data on an AP containing Historian software:
♦ Trend objects on user displays
12
♦ Historian data retrieval displays

♦ Historian subroutine calls
♦ ACE Report Writer.
The 50 Series workstations and the AP20 archive formats differ. To avoid format conflicts, restore
archives to the same platform workstation type that created them.
Archiving executes on a user-defined schedule. To delay scheduled executions, you set the phase
delay parameter that specifies a delay factor to level the archive-processing load on the AP.
Manual Data Entry Values

The Historian allows you to configure MDE variables and MDE collection groups. MDE
values can be used by I/A Series application programs, for example, the SPCP.
Workstation Interface
The Historian workstation interface is menu-driven. Figure 2-9 shows the Historian workstation
interface menu structure. The available Historian functions are:
♦ Configuration
♦ Scheduling
♦ Data display
♦ Archiving backup/restore
♦ MDE edit entry
The Historian displays allow you to move through a hierarchy of menus and select the desired
function. These displays provide forward and backward scrolling of data list menus and editing
options where they are required.
The Help function opens a window of Help text on the display when you select Help from the
environment menu bar.
Historian Historian Historian Historian MDE Con- MDE Edit

Configuration Operation Data Display Archiving ffiguration Entry
Point Sample Group Add Group Messages

**
Collection Name/Type Delete Group Reduced Data
Reduction Review/Modify
Add/Delete Group
Message
Points *
Archive
* You can review/modify message groups (except alarm message groups) from the Historian
configuration displays, but you cannot add or delete them.
** Alarm history displays retrieved alarm messages.
Figure 2-9. Historian Workstation Interface Menu Structure
13
Configuring the Historian

Configure the Historian from a workstation or an application program. You can configure:
♦ Point collection members
♦ Groups
♦ Group members
♦ Reduction group operations
♦ MDE variables.
You can configure the following types of data collections:
♦ Point sample collection
♦ Reduction groups
♦ Message groups
♦ Archive groups
♦ MDE groups.
For the point sample collection, add or delete points from the collection and select one of nine
update times for each point. For reduction data, you define the groups, group members, and
reduction operations. For archive data, you define the groups and group members. For MDE
data, you define the variables, groups, and group members. Message groups are pre-configured.
Scheduling Historian Functions

From a workstation you can:
♦ Start and stop a Historian
♦ Start, stop, or clear and start data collection for each reduction, archive, and message
group
♦ Get the operational status of each reduction, archive, and message group.
Displaying Historical Data

The Historian data display function produces tabular displays of historical data on a workstation
screen (see Figure 2-1). Selecting this function allows you to display:
♦ Sample data
♦ Reduced data
♦ Manual data
♦ Messages
♦ Archived data.
The Historian provides a set of displays to show a list of data groups in the historical database, to
summarize the contents of the various data types, and to show, in the most detailed displays, the
actual values or messages. The displays provide options for paging through data lists, and moving
through the data hierarchy.
You can also view sample, extended sample, reduction, and archive data using configurable trend
objects contained in the Display Builder and configured through the Display Configurator.
14
Archiving Historical Data

From a workstation, you can back up and restore archive group data. The backup function allows
you to store archive group data on streaming tape or diskettes. The restore function allows you to
restore archive data to the hard disk from these media.
Accessing Historian Displays

To access Historian displays from a user environment (Figure 2-1):
1. Select Config from the Environment menu bar to display the Configurator pull-down
menu.
2. Select Historian from the Configurators menu to display the Historian pull-down
menu.
3. Select the desired function from the Historian menu to access the initial display. The
available Historian functions are:
Configurator
Scheduler
Data_Display
Local_DB_BKUP
Archive_Backup
MDE_Edit.
For more information on the environment menu bar and pull-down menus in standard operating
environments, refer to System Operations Guide (B0193CR).
Help
Help provides information and assistance for the Historian Configurator, Scheduler, and Data
Display functions. The information available through Help relates to the current display, current
program operation, or selection. It changes as you proceed through the program to provide you
with appropriate information.
Select Help from the menu bar at the top of the screen. A menu of topics relating to the current
display or selection appears on the screen. Selecting a topic from the menu displays the Help text
in a partial screen overlay.
Selectable icons at the bottom of each Help overlay provide screen control functions that include
return, next screen, previous screen, and exit Help.
Screen Control Functions

Select the function you want from the screen display by using whatever pointer device is attached
to the workstation, for example, touchscreen, trackball, or mouse (refer to Process Operations and
Displays (B0193MM) and System Operations Guide (B0193CR) for further information). The
touchscreen option should not be used with the configurator displays; use a high resolution
pointer device, that is, a mouse or trackball.
In the displays, use the pointer device to move from one entry field to another or to select a soft
key. When you select a data entry field, a dialog box appears around the entry field to define it.
Menus in some displays contain icons that you can select to close the menu, page up or down, or
go to the beginning (home) or end of the menu. Other displays have soft keys for paging the
menus. All displays have a soft key for exiting the display.
15
Before accepting the configuration data, the Historian verifies the information and identifies any
discrepancies for correction. The Historian displays input error messages in a window on the
screen when errors occur. To recover from these errors, select the CONTINUE key and correct the
keyboard input.
Use the following keystroke commands with the Historian Configuration, Scheduling, and Data
Display functions:
♦ Shift + arrow (up, down, left, and right arrows in the numeric keypad) moves the
cursor from one entry field to another.
♦ Return or Enter following data that you type in an entry field enters the data in
memory.
♦ Backspace deletes one character to the left of the cursor within an entry field.
♦ Ins toggles between the insert and overtype modes.
♦ Del deletes the character at the cursor position within an entry field.
♦ Shift + arrow (left and right arrows in the numeric keypad) moves the cursor within
an entry field.
♦ Shift + Home moves the cursor to the beginning of an entry field.
♦ Shift + End moves the cursor to the end of an entry field.
♦ Shift + Del deletes characters from the cursor position to the end of the field.
Application Interface
For more flexibility, user programs written in the C language can interface with the Historian
through calls to configuration, scheduling, and data retrieval subroutines in the Historian library.
A user-written program can interface with the Historian to:
♦ Request or schedule data collection for reduction, message, or archive groups.
♦ Retrieve sample, reduced, MDE, and archive data for one point name.
♦ Retrieve reduced data for a list of point names.
♦ Start and stop data reduction, message collection, and archiving.
♦ Configure reduction and archive groups and modify message group configurations.
For reduction groups, add and delete groups, group members, and operations.
♦ Perform bulk transfers of data values from user application programs to the
Historian reduced database.
Application programs can use the Historian to manage a history of events or values and reduce
and archive the data. Historian sample, reduced, MDE, and archive data can be read by any pro-
gram.
The Historian supports the following data access functions:
♦ Get reduced data for a group name, point name list, operation list, and time span.
♦ Get configuration information for a reduction, message, or archive group.
♦ Get configuration information for a reduction, or archive group member.
♦ Get sample data for a point name, and time span or number of values.
♦ Get reduced data for a group name, point name, operation name, and time span or
number of values.
16
♦ Get MDE data for a group name, point name, and time span or number of values.
♦ Get sample, reduced, or MDE data for an archive group name, point name, and time
span or number of values.
To perform additional functions, user-written programs can access the Real-Time Database Man-
ager.
Time Adjustment
The System Monitor notifies the Historian of operator-initiated changes to the system time. The
System Monitor sends both the old and new system times to the Historian. The Historian uses
time change data to adjust its master clock and operating functions.
The Historian labels stored time values with a sequence number that increments whenever the
system time is changed. You can configure the Historian to log time change messages as applica-
tion messages from the System Monitor.
Security Features
You can modify and control Historian operations through a workstation or an application pro-
gram. You can configure the I/A Series environment so that Historian configuration and opera-
tion functions via a workstation are restricted to a particular user’s environment, but you cannot
restrict access to these functions via an application program. You can configure a reduction or
archive group so that only one user-written program can change the configuration data for that
group.
Installation
The Historian is supplied on a set of diskettes which contain all necessary load modules, applica-
tion libraries, help files and automated procedures. For instructions on how to load these dis-
kettes, refer to Software Installation (Solaris Platform) (B0193JG).
The Historian provides extended sample collection on an AP20 with an optional second 80 MB
hard disk. The optional hard disk is dedicated to collecting extended samples, archiving them,
and playing back these archives. Only an 80 MB system disk is supported at this time. For a fault-
tolerant AP, the capacity of the optional disk on the shadow processor must match that of the pri-
mary processor.
The optional disk drive now automatically does a file system check.
17
18
3. Configurator
This chapter explains how to work with the Historian Configurator, the buttons, icons and
menu options that define sample points, and data collection groups.
The Historian Configurator lets you define sample points for data collection and define configure
groups for reduction and archiving. Also, you can configure manual data entry and message
groups.
A historian is a collection of statistical databases about events and messages on the network. The
historian collects data from a variety of devices on the network and stores them for subsequent
analysis. You can configure as many historians as necessary to meet your application’s needs, pro-
vided that only one historian resides on any one AP.
To configure data collection for the specified historian, proceed as follows:
1. Select Config from the top menu bar to display the Configurators pull-down menu.
2. Select Historian from the Config menu to display the Historian pull-down menu.
3. Select Configurator from the Historian menu to display the Configurator main
menu.
4. Click a Historian from the Historian pull-down menu to select it. The menu lists
available historians on the network and their associated host stations. If the selected
Historian is active, the Configurator displays a dialog box that lets you turn off the
Historian or continue in read-only mode. Read-only mode lets you review existing
settings; you must turn off the Historian before you can make any changes to its data-
base.
5. Configure members for sample collection.
The following steps are optional:

6. Define reduction groups and add members to the groups. It is at this stage that you
decide what operations to perform on the data.
7. Define archive groups and add member points.
8. Define manual data entry (MDE) groups.
9. Specify the number of messages (the default number of messages is 100).
User Interface
You can reach the various Historian configuration functions from the Edit menu. The menu con-
tains five selections:
♦ Archive Groups
♦ Collection Points
♦ Manual Data Groups
♦ Message Groups
♦ Reductions Groups.
19
B0193BL – Rev L 3. Configurator
On some of the screens, action buttons provide access to additional functions. Below is a sum-
mary of the functions available from the Edit menu:
Archive Groups
Archive Group
Multiple Selection Members
Button
Multiple Selection
Button Archive Multiple
Selection Screen
Collection Points
Manual Data Groups
Multiple Selection
Button Select Table
Variables Screen
Message Groups
Reduction Groups
Reduction Group
Members Button Members
Multiple Selection Reduction Multiple
Button Selection Screen
20
3. Configurator B0193BL – Rev L
Working in the Configurator Screens

The typical Configurator screen contains the following areas (Figure 3-1):
Figure 3-1. Typical Historian Configurator Screen
♦ A list of selectable objects (for example, group names, group members, operations).
Usually, a local filter helps you narrow the list of selectable objects displayed on the
current screen. Filters also modify the content of subsequent members and multiple
selection screens.
♦ An edit menu displays the parameters associated with a particular object. When you
select an object in a list, the fields in the edit window are filled with the current values.
You can add, delete, or reconfigure any value in the edit window.
♦ Some screens contain a detailed display screen of objects and associated parameters.
For example, in the Collection Point menu, each entry (collection point) in the list
contains a collection point name, description, index, deadband value, scan rate, and a
total number of sample records. If you click an entry in a list, you can add, delete, or
reconfigure the entry.
♦ From some screens, such as the Reduction Group Members, Archive Group Members,
and Manual Data Entry, a Multiple Selection button displays a multiple selection
screen that lets you select multiple items from a list of available objects and configure
them simultaneously. For example, you can select a group of member points to add to
a reduction group.
21
Buttons and Icons

Most screens contain buttons that provide single keystroke functionality, such as Done, Delete,
Add All, Delete All, and so on. Other buttons, such as Members and Multiple Selection pro-
vide access to another layer of the Configurator. For example, the Members button in the Archive
Group screen displays the current list of archive members and allows you to edit the members list,
item by item.
If you want to select more than one member at a time, enter a character string in the filter field
(optional) and click the Multiple Selection button from a members screen.
Multiple selection screens (Figure 3-2) consist of two columns: one contains the list of available
items, the other the list of selected items. Click a name to move an item from one list to the other.
Choose one or more items and click the Add All button to add all currently selected items.
Use the standard Foxboro icons (arrows, triangles, and octagons) to scroll through or close the dis-
play.
NOTE
When you finish editing or reviewing a screen, select another function from the
Edit menu to continue configuration, or click the Exit button in the top menu bar
to leave the Configurator.
Figure 3-2. Multiple Selection Screen 3
22
Top Menu Bar

The top menu bar provides the following buttons that are available from every Configurator
screen:
Help Displays a menu of topics relating to the current display, program opera-
tion, or selection. Select a topic to display more information.
Historian Lists the available Historians and their associated host stations. Click an
entry to select a Historian. You must turn off the Historian before you can
make any changes to its database. If the selected Historian is active, the
Configurator displays a dialog box that allows you to turn off the Histo-
rian or continue in read-only mode.
File The Store option lets you save the current configuration as a file and can
be used when the Historian is active. The Load option lets you merge an
existing configuration file with the current configuration. During the
merge, the Historian requests that you deactivate the current Historian
before loading.
NOTE
The Load... function merges information from the new file only for parameters
missing from the current configuration. Load does not remove anything from the
current configuration; existing parameters with data are not replaced.
Both options open a file selection overlay that allow you to enter either a
specific pathname, or a search string to display a list of existing files.
Edit Lists the configuration options as follows: Archive Groups, Collection
Points, Manual Data Entry Groups, Message Groups, and Reduction
Groups. Click an entry to open the option’s initial display.
Reports Allows you to select a printer, select a report type, and then start a report.
Always choose the printer and report type before starting the report.
Switch To Allows you to go directly to another Historian function without returning
to the Display Manager. The available Historian functions are:
Data_Display and Scheduler.
Exit Quits the Historian application and returns you to the Display Manager.
Guidelines for Entries

♦ Do not use INFORMIX reserved words.
♦ Historian names must begin with an alphabetic character (A-Z).
♦ Use only alphanumeric characters and underscores.
♦ Enter dates as shown on the screen.
♦ Use asterisks as wildcard characters in filters.
♦ Use Backspace to delete one character to the left of the cursor.
23
♦ Use Delete to delete the character under the cursor.
NOTE
For workstations without a mouse or pointing device, press the Shift key and one
of the numeric keypad arrow keys to move from one data entry field to another.
Configuring Member Points

From the Edit menu, select Collection Points to access the point collection configuration
screen (Figure 3-3).
Figure 3-3. Point Collection Configuration Screen
The display contains three sections:

♦ The list of existing collection points. Each entry contains the collection point name,
description, index, deadband, scan rate, and the total number of samples for each
point. Click an entry to delete or reconfigure a collection point in the edit window.
♦ A list of options.
♦ A parameter edit window.
Collection Point Fields

Each collection point has the following attributes that you can modify:
24
compound:block.parameter
Lets you enter a specific point name in the edit menu window.
Description Is a user-defined character string (32 characters maximum).
Deadband Is a change in point value in engineering units that must be detected
before updating the member point data. Decimal value. Default: 2.0.
Number of Is a total number of point samples to be collected. Your entry is rounded
samples up to the next larger 100-sample resolution.
Retention span Defines the time period, in hours, to collect samples for historical trend-
ing. At the end of this period, the Historian overwrites the oldest samples.
Entered values are rounded up to correspond to the next larger 100-sam-
ple resolution.
Update time Is the minimum update time for member point data. Values can be 2
(default), 4, 10, 20, or 30 seconds, or 1, 2, 5, or 10 minutes for an AP20.
For an AP50/51, values can be 1 (default), 2, 4, 10, 20, or 30 seconds, or
1, 2, 5, or 10 minutes. Point data are not updated until both the specified
deadband and the update times are reached.
Options
Global variable Allows you to add, delete, or reconfigure a reference to an Object Manager
shared variable in the edit window.
C:B.P Allows you to add, delete, or reconfigure a reference to a com-
pound:block.parameter in the edit window.
Select C:B.P Opens the compound selection window allowing you to search the Com-
from List pound Summary Access list of compound names, block names, or block
types. Click an entry to make a selection. You can add, delete, or reconfig-
ure a reference to the variable in the edit window.
Show Collection Displays the scan rate, the number of points configured for both basic and
Summary extended sampling at each scan rate, and summaries.
25
Defining Reduction Groups

From the Edit menu, select Reduction Groups to access the main reduction group screen
(Figure 3-4).
Figure 3-4. Main Reduction Group Screen
The display contains four sections:

♦ A reduction group list and filter
♦ A group edit window
♦ List of available operations
♦ List of currently configured reduction operations.
Reduction Group Parameters

Name Selected reduction group name. Enter a 10-character name or select one
from the list.
Description User-defined character string (32-characters maximum).
Initial state State of the processing group on or off when the Historian starts.
Phasing delay Delay used to level the processing load on the AP.
26
Sampling period Time period for scheduling the collection of point sample data required
for a non-cascaded reduction group. Enter 0 for cascaded reduction
groups, described in the following subsection.
Minimum span Minimum time span required for valid reduction operations when some
of the input data is not available. The time span must be less than or equal
to the reduction period.
Reduction period Time period (hours or minutes) for scheduling the execution of data
reduction operations. Do not configure this period in seconds.
Reduction span Time span for retaining historical data for the group. When the
historian executes a reduction, it deletes data older than this time span.
Operations List of operations you can run on a scheduled basis.
User task Full pathname of a user program. The program may call standard applica-
tion packages or your own reduction programs to perform calculations not
provided by the Historian.
Cascaded Reduction Groups

When the members of a reduction group are other reduction groups, the group is considered a
cascaded reduction group. Cascaded reduction groups require heavy system resources. To mini-
mize the impact on an AP:
♦ Use regular (non-cascaded) reduction groups whenever possible.
♦ Set the reduction period for cascaded reduction groups to at least one hour.
♦ If a reduction group is a member of a cascaded reduction group, set the retention span
to the minimum. For example, the recommended retention span for a 5-minute
reduction group that feeds a 1-hour cascaded reduction group is 90 minutes.
Members and Multiple Selection Buttons

The Members button displays the Reduction Group Members screen, which displays the current
list of member points or groups, allowing you to edit the members list, item by item.
Clicking on the Multiple Selection button displays the Point Members Multiple Selection
screen, which lets you select more than one member at a time. Choose one or more items and
click the Add All button to add all currently selected items.
To limit the Multiple Selection Screen display to only those entries that contain a specified
string, enter a character string containing the asterisk (*) as a wildcard character in the Filter
field of the Reduction Group Members screen before clicking on the Multiple Selection
button.
Defining Archive Groups

From the Edit menu, select Archive Groups to access the main archive group screen (Figure 3-5).
27
Figure 3-5. Main Archive Group Screen
The display contains two sections:

♦ A list of archive groups
♦ An edit window.
Archive Group Parameters

Name Selected archive group name. Choose new names that are 6 characters or
fewer because the archive database backup function appends a 4-character
time stamp to the name.
Description User-defined character string (32-characters maximum).
Archive type Type of data collected: reduction, message, MDE, or extended sample.
Initial state State of the processing group on or off when the Historian starts.
Phasing delay Delay used to level the processing load on the AP.
Archive period Time period for scheduling the execution of archiving operations for the
group. When the archive period is reached, the collected data is stored in a
new archive database.
Archive time All data within the specified time span is transferred to the new archive
span database.
28
Members and Multiple Selection Buttons

The Members button displays the archive group members screen, which displays the current list of
members and allows you to edit the members list, item by item.
Clicking on the Multiple Selection button displays the archive members multiple selection
screen, which lets you select more than one member at a time. Choose one or more items and
click the Add All button to add all currently selected items.
To limit the multiple selection screen display to only those entries that contain a specified string,
enter a character string containing the asterisk (*) as a wildcard character in the Filter field of the
archive group members screen before clicking on the Multiple Selection button.
Defining MDE Groups and Variables

From the Edit menu, select Manual Data Groups to access the manual data group configuration
screen (Figure 3-6).
Figure 3-6. MDE Group Configuration Screen
The MDE screen contains four sections:

♦ MDE group list and filter. Use a character string containing an asterisk as a wildcard
to narrow the selection of items displayed in the window.
♦ Members list and filter. Use a character string containing an asterisk as a wildcard to
narrow the selection of items displayed in the window. This filter also modifies the list
of available names in the Multiple Selection screen.
29
♦ Group edit window.

♦ Member edit window.
MDE Parameters
Group name An existing or new MDE group name of maximum 10 characters. Do not
use INFORMIX reserved words.
Description User-defined character string (32 characters maximum).
Retention span Time period, in days, to retain samples for MDE. At the end of this
period, the Historian overwrites the oldest samples.
Member name An existing or new MDE member name of maximum 10 characters. Do
not use INFORMIX reserved words. Each member name must be unique.
Low limit Minimum value for the variable, with a lower limit of -99999999.
High limit Maximum value for the variable, with an upper limit of 99999999.
Units Unit of measurement (6 characters maximum).
Multiple Selection Button

Clicking on the Multiple Selection button displays the MDE members multiple selection
screen, which lets you remove more than one member at a time. Choose one or more items and
click the Delete All button to remove all currently selected items.
To limit the multiple selection screen display to only those entries that contain a specified string,
enter a character string containing the asterisk (*) as a wildcard character in the Filter field of the
MDE group members screen before clicking on the Multiple Selection button.
30
Configuring Message Collection

From the Edit menu, select Message Groups to access the message group configuration screen
(Figure 3-7).
Figure 3-7. Message Group Configuration Screen
The display contains two sections:

♦ A list of standard Foxboro supplied message group names
♦ A message group edit menu.
Message Group Parameters

Name Selected predefined message group name.
Description User-defined editable character string (32 characters maximum).
Initial state State of the message group on or off when the Historian starts. The state
can be reset.
Maximum number Maximum queue length. After it receives the maximum number of mes-
of messages sages, the Historian discards the oldest message. The default is 100 mes-
sages.
31
32
4. Scheduling
This chapter contains information on scheduling, including accessing scheduler displays,
starting or stopping Historians, and scheduling groups.
The Historian Scheduler allows you to start or stop multiple Historians simultaneously, as well as
allowing changes to the operational status of reduction, message, or archive groups. When you
start the Historian, point sample collection starts automatically.
If you make an invalid entry or selection, the Scheduler displays an error message. To acknowl-
edge an error message and continue the operation, click on the CONTINUE button in the error mes-
sage dialog box.
Top Menu Bar

The top menu bar provides the following buttons, which are available from every Scheduler
screen:
Historian Lists the available Historians and their associated host station’s letterbug.
Click an entry to select a Historian for group scheduling functions.
to the Display Manager. The available Historian functions are: Configu-
rator and Data_Display.
Accessing Scheduler Displays

To access the Historian Scheduler displays:
1. Select Config from the top menu bar to display Configurators pull-down menu.
2. Select Historian from the Config menu to display Historian pull-down menu.
3. Select Scheduler from the Historian menu to display the Scheduler main menu
(Figure 4-1). You can schedule both Historians and data collection groups from this
menu.
33
B0193BL – Rev L 4. Scheduling
Figure 4-1. Historian Scheduler Main Menu
Starting or Stopping Historians

To start or stop Historians:
1. Access the Scheduler main menu.
2. Click the Schedule Historians button to display the list of Historian names and
current status (ON/OFF). Select individual Historians from the list or click the
Select All button. If there are more than thirty Historians, use the icons to scroll
through the list of names.
3. Select START or STOP as appropriate.
Scheduling Groups
To schedule groups:
1. Access the Historian Scheduler main menu as described in the previous section.
2. Select a data collection group type, either Reduce, Archive, Message or All, from the
Schedule Groups window to display the group names and status information. Specify
a group name, or enter a character string containing the wildcard character asterisk (*)
in the Name Filter field to display a partial list.
34
4. Scheduling B0193BL – Rev L
3. Optionally, select the Detail display. The Detail display (Figure 4-2) provides more
information on the following attributes:
Current Status ON, OFF, RO (Run Once for Archive groups only)
Group Type Reduced, Message, or All (R, M, or A)
Group Name Existing Data Collection Group Names
Description A user-defined string (32 characters maximum)
Next Execution Applies to active groups only.
The Brief display (the default) lists summarized information.
Figure 4-2. Historian Scheduler Detail Display
4. To select individual groups, click the appropriate boxes from the list. If there are more
than thirty groups, use the icons to scroll through the list of names.
5. Use the Select All or Deselect All buttons to select or deselect the entire list. The
status line at the bottom of the screen displays the total number of selected items.
6. Optionally, click the Date button to specify the first time to execute the selected
groups. Enter the date in the selected format, typically mm/dd/yy. The default date is
the current date. The Scheduler accepts USA, European, and ISO date formats as
specified in the system file /etc/dateform. If both the date and time fields are blank,
the Scheduler sets the default value to the next scheduled execution date plus the con-
figured phase delay.
35
B0193BL – Rev L 4. Scheduling
7. Click the Time button to specify the first periodic execution time for the selected
groups. Enter time as hhmmss (for example, 080000). If both the date and time fields
are blank, the Scheduler sets the default value to the next scheduled execution date
plus the configured phase delay.
For example, if the current time is 2:45 P.M. and data collection is performed hourly,
the Scheduler sets the value of time to 150000.
8. Click the Clr Start button to erase all data previously collected for reduction or mes-
sage groups, and schedule the groups.
NOTE
The Clr Start button erases all data.
36
5. Data Display
This chapter contains information on data displays, including accessing the data display
module, selecting a database, selecting a data collection period, selecting reduction data, and
displaying a message.
The Historian Data Display function produces tabular displays of data or messages from the His-
torian database. You display current process plant data, as well as archived data.
The Data Display module lists available data groups in the historical database, summarizes the
various data types, and displays the number of values available for a specific data collection period.
If you make an invalid entry or selection, the Data Display module displays an error message. To
acknowledge an error message and continue the operation, click the CONTINUE button in the error
message dialog box. Note that while Data Display retrieves data, the cursor changes to an hour-
glass shape.
Top Menu Bar

The top menu bar provides the following buttons available from every Configurator screen:
Historian Lists the available Historians and their associated host station’s letterbug.
Click an entry to select a Historian.
Reports Allows you to write a report to an ASCII file, to print a report to a printer,
or to cancel printing of a report. Always write a report to a file before
printing it.
rator and Scheduler.
Accessing the Data Display Module

To access the Historian data retrieval displays:
1. Select Config from top menu bar to display Configurators pull-down menu.
2. Select Historian from Configurators menu to display Historian pull-down menu.
3. Select Data_Display from the Historian menu to display the Data Display main
menu (Figure 5-1).
4. Select a database, data type, data collection group, and sample period as described in
the following sections.
37
B0193BL – Rev L 5. Data Display
Figure 5-1. Data Display Main Menu
Selecting a Database
To select the Historian database name and data type:
1. Access the Data Display main menu as described in the previous section.
2. Select Historian from the top menu bar to display the Historian pull-down menu.
The number of Historians supported in a pull-down menu is 60. Click an entry to
select a Historian. The selected Data Display module shows the currently selected
Historian’s name in the Historian field.
3. Choose the data type:
Current Data Selects the process plant database.
Archive Data Selects an archived database.
Playback Data Selects a restored archived database.
To display archived information from streaming tape or diskette, restore the data from
the storage medium before you access the Data Display module. Then select group
name from list of local archive database names.
38
5. Data Display B0193BL – Rev L
4. Select a data type from the current data column to access the data type’s membership
screen:
Sample Displays the current process plant data available for the selected
Historian. The display includes: Historian name, description,
index, preset deadband value, data collection rate, and whether or
not any extended sampling data exists.
Reduction Displays the available reduction groups, points, or operations.
For more information, see the section “Selecting Reduction Data”
on page 41.
Message Displays the available Message Group Names and descriptions.
The display includes: date, time, data type, message identifier,
and source host letterbug. For more information, see the section
“Displaying Messages” on page 41.
MDE Displays the available manual data entry groups, variable names
and data.
5. Enter a member point name in the Filter Point Name field to retrieve the specific
member points, or click the Filter Point Name button to retrieve all member points.
6. The individual data type membership screens consist of two windows (Figure 5-2).
The top window contains a list of currently available but not yet selected members
and descriptions. Click an entry in the top window to select it. The bottom window
displays your current selections. Click an entry in the bottom window to deselect it.
Use the paging icons at the bottom of each window to scroll through the lists.
7. After making your selections, click the octagonal icon to return to the main menu to
specify the data collection period.
39
Figure 5-2. Membership Screen
Selecting a Data Collection Period

The Data Display function allows you to request a specific number of values, request a specific
data collection period, or display the statistics since data collection began. To specify a data collec-
tion period from the main menu:
1. Click the Summary button to show:
♦ The oldest and newest date and time for the selected data points
♦ The largest of the points counts for the selected data points.
2. To request a specific sample, use the following:
CLEAR Erases the current values contained in the following fields: Start
Date, End Date, Start Time, End Time, and Number of Values.
Number of Values Indicates the total number of values available within the specified
collection period. To request a specific number of values, enter a
positive integer.
40
5. Data Display B0193BL – Rev L
Start/End Time Indicates the data collection time of oldest and most recent data
available. To request a specific time period, use the format hhmmss.
For example, the period 000000 to 120000 specifies a 12-hour data
collection period.
Start/End Date Indicates the oldest and most recent data available. To request a
specific range, use the selected format, typically mmddyy. For exam-
ple, the range 060192 to 123192 specifies a 6-month data collection
period. The Data Display module accepts USA, European, and ISO
date formats as specified in the system file /etc/dateform.
3. Click the DATA button to display the data available within the specified time period
and requested number of values. The default start date/time is the current time minus
eight hours. The default end date/time is the current time.
Selecting Reduction Data

To display reduction groups, reduction points, or reduction operations:
1. To access a reduction group membership screen, enter a group name in the Group field
to list the members of a specific group, or click the Group button to list all available
reduction groups for the specified Historian.
2. To access a reduction points membership screen, click the Filter Point Name
button to list selected point names. To select an additional point name, click the Fil-
ter Point Name button, or enter a character string in the Filter Point Name field to
list a subset.
Enter any character string containing the wildcard character asterisk (*) as follows:
string* Lists group names beginning with the character string
*string Lists group names ending with the character string
*string* Lists group names containing the character string
To list all point names, enter * or leave the Filter Point Name field empty.
3. To access the reduction operations screen, perform Steps 1 and 2. After the reduction
operations display lists the available operations and the storage column, click an entry
to select it.
4. Click the octagonal icon to return to the main menu and specify a data collection
period.
Displaying Messages
To display messages for a group from the main menu:
1. To display a specific message, enter the message identifier (up to 32 alphanumeric
characters) in the Message Identifier field.
2. To display messages from a specific host, enter the letterbug of the source host in the
Originating Station field.
41
3. To access the reduction operations screen, perform Steps 1 and 2. After the reduction
operations display lists the available operations and the storage column, click an entry
to select it.
4. Click the Data button to display the actual messages (Figure 5-3).
Figure 5-3. Message Data Display Screen
42
6. Archiving
This section includes information on archiving historian databases. Accessing the archiving
function, editing tape size, backing up, restoring and deleting restored archives are all covered
in this section.
The Historian Backup, Restore, and Delete functions operate on archived Historian databases
that may be either local or remote.
Use the Backup function to back up previously archived databases to either diskette or streaming
tape.
Use the Restore function to restore previously backed up archive databases from diskette or
streaming tape to the hard disk. Restored databases are loaded into the playback area of the hard
disk.
Use the Delete function to delete restored archive databases from the playback area.
From a workstation on an AP that hosts a Historian, you can access archive databases on any
remote AP that in turn hosts a Historian that has a streaming tape or diskette drive.
When an archive operation executes, it stores data for the archive group members in an archive
database. The database name is built from the 6-character group name, a 4-character time stamp,
and an _arc or _pbk suffix on the AP50/51, or a .dbs suffix on the AP20; these suffixes are trans-
parent to the user.
If the configured archive group name is shorter than 6 characters, the Archive function fills the
remaining spaces with underscores.
The start time for the archive data is as follows:
Start Time = Time Stamp - Archive Time Span
The Archive Time Span is a configurable group parameter.
Time stamp format is: mddt
where:
m = month (1–9, a, b, c) (Jan.–Sept., Oct., Nov., Dec.)
dd = day (1–31)
t = hour (a–x) (12:00 am–11:00 PM)
NOTE
1. Record the year on the archiving media label for your reference.
2. With this database naming convention, an archive may run at most once per
hour.
When you restore an archive database, the Archive Restore function lists the database names
stored on the media for reference.
When an archive group executes, it creates a new database that overwrites the existing one. To
avoid losing archive data, periodically use the Archive Backup function to store archive data onto
43
B0193BL – Rev L 6. Archiving
streaming tape or floppy disk. Use the Archive Delete function to periodically delete restored
archive databases that are no longer needed.
Accessing the Archiving Function

NOTE
The default parameter TAPESIZE in INFORMIX’s tbconfig is 10 MB. That is the
maximum amount of data that can be put on tape for each database. For larger
archive databases, change the parameter to the maximum tape size, that is, 150,000
for the 150 MB tape drive or 2,000,000 for the 4 mm/8 mm in /opt/infor-
mix/etc/tbconfig. Reboot the host station for INFORMIX on-line to reinitialize.
Do not remove the # comment text after the tape size, for example:
TAPESIZE 2000000 # Maximum amount of data to put on tape (Kbytes)
To access the Historian archiving function:

1. Select Config from the top menu bar to display the Configurator pull-down menu.
2. Select Historian from the Configurator menu to display the Historian pull-down
menu.
3. Select Archive_Backup from the Historian menu to invoke the Archive Backup &
Restore Display shown in Figure 6-1.
44
6. Archiving B0193BL – Rev L
Figure 6-1. Archive Backup and Restore Display
The top area of the display is used for selecting the backup mode for backup operations to tape,
and for selecting the archive device for backup and restore operations. The rest of the display is
divided into three vertical sections, one each for backup (left), restore (right), and the deletion of
restored archives (middle).
Use the Archive Backup & Restore Display to perform the following operations:
♦ Back up local or remote Historian Archive database(s)
♦ Back up the main database of the currently selected Historian
♦ Restore a database from tape or diskette
♦ Delete a restored archive.
NOTE
The maximum number of archive or playback databases is 250. Scroll down to 90
databases at a time, then select CLOSE and ARCHIVE or PLAYBACK again for the next 90
databases.
45
Editing Tape Size

To edit the tape size for Historian archiving, perform the following procedure:
1. Change the directory /opt/fox/hstorian/bin.
2. Open the ASCII file histadev in the directory.
3. Review the instructions at the beginning of the file.
4. Modify the first few lines of the file histadev according to that file’s instructions.
5. Save the modified version of the file in the same directory (/opt/fox/hstorian/bin).
For example, to modify the default AW51 archiving tape (3.5-inch diskette drive, conventional
streamer tape used with DC6150 cartridges) to the 5 GB tape drive (4 mm or 8 mm digital tape),
the following lines must appear in the file histadev:
TAPE=/dev/rst5
TAPE_NR=/dev/nrst5
TSIZ=2000M
Now the archiving process recognizes the 5 GB tape drive as the archive device.
Archive Devices
The Historian supports the following archive devices:
♦ 4 mm/8 mm 50 Series tapes store up to 2 GB of data.
♦ Streaming tape. 50 Series tapes store up to 150 MB of data; AP20 tapes store up to
150 MB or 40 MB of data.
♦ Diskette. Databases can span more than one diskette but no more than one database
can be stored on one diskette. If a database spans more than one diskette, the backup
function labels each diskette with a sequential number.
Backing Up Archive Data

To back up archive data:
1. Click the Historian pop-up to select the historian whose database you want to back
up. The name of the default historian is shown in the upper left corner of the display.
(The name of the hosting station appears in parentheses after the name of the histo-
rian.)
In the backup (left column), the program lists all the new archives that exist for the
default historian. If there are too many archives to fit in the column, a scroll bar
appears to the left of the list to let you scroll through the archives.
2. Click the checkbox to the left of each individual archive you want to select, or click
the New Archives checkbox at the top of the column to select all the archives. (The
New Archives checkbox appears only if there is more than one archive in the list.)
3. Select the archive device by clicking on either the Floppy or Tape buttons.
4. If you choose to back up to tape, click the New Tape or Append buttons to select a
backup mode.
46
6. Archiving B0193BL – Rev L
♦If you select New Tape, the program overwrites the archive already on the tape.
♦ If you select Append, the current database is appended to the current contents of
the tape.
5. Click the Backup button.
6. If you chose to backup to diskette, the program prompts you to insert the diskettes in
the appropriate sequence. Follow these prompts.
To back up the main database:
Click the Backup Main Database button at the bottom of the display.
The backup function appends a 4-character time stamp to the database name. The backed up
databases are not in tar format.
NOTE
The Backup function does not delete an archive group database.
Archive Backup Messages

The backup function generates the following messages:
A Historian name must be selected.
An archive name must be selected.
Archive does not exist.
Insert Archive Tape.
Insert Diskette 1.
Medium write error. Insert Diskette 1.
Medium full. Insert Diskette 2.
If a message is issued, perform the action indicated by the message and select the message overlay
to continue the backup.
The error message Write Error. Tape no longer available for APPEND. indicates that the
current backup has failed. Although you cannot retrieve the database that was being backed up
when the failure occurred, you can restore any other databases archived on the same tape.
Tapes can be erased and formatted for reuse with the aid of the New Tape function.
Restoring Archives
To restore archive data:
1. Select the archive device from which you want to perform the restore operation.
2. If you selected to restore from tape, click the Get Archive Directory button.
The program displays the message Retrieving Tape Directory and lists the archives
found on the table in the Tape Directory column.
3. Click the checkbox to the left of each individual archive you want to restore, or click
the Tape Directory checkbox at the top of the column to select all the archives. (The
Tape Directory checkbox appears only if there is more than one archive in the list.)
4. Click the Restore button.
47
If you selected to restore from diskette, the program prompts you to insert the appro-
priate diskettes.
The Restore function generates the following messages:
Can’t create directory
Can’t create file
Can’t write to file
Tape rewind error
Unable to read from medium
Wrong sequence number
Wrong directory label.
If a message is issued, perform the action indicated by the message and select the message overlay
to continue the restore.
Deleting Restored Archives

Archives that have been restored to the hard disk are listed in the Restored Archives column in
the center of the Archive Backup & Restore Display. To delete restored archives from the hard
disk:
1. Click the checkbox to the left of each individual archive you want to delete, or click
the Restored Archives checkbox at the top of the column to select all the archives.
(The Restored Archives checkbox appears only if there is more than one archive in
the list.)
2. Click the Delete button.
NOTE
This function deletes only archives that have been restored from backup media.
48
7. Manual Data Entry
This chapter contains information on manual data entry (MDE), including accessing the
MDE Editor, editing MDE values, WYSE terminal and foreign database interface.
You can use the Historian manual data entry (MDE) displays to type in, from a workstation, val-
ues for variables that are members of Historian MDE groups. MDE variable values are stamped
with a user-entered date and time.
Top Menu Bar

The top menu bar provides the following buttons, which are available from every manual data
entry screen:
Historian Lists the Historian and its associated workstation letterbug.
rator, Data_Display, and Manual Data Entry.
Exit Quits the Historian application and returns you to Display Manager.
The general procedure for editing MDE values involves the following steps:
1. Select MDE_Edit from the Historian menu.
2. Select the group and variable whose data you want to edit.
3. Search for the desired date and time stamp.
4. Enter the necessary edits.
If you make an invalid data entry in the manual data entry display, or if you perform an invalid
operation, the Historian displays an error message. Use the icons to page through lists and close
displays.
Accessing the MDE Editor

To access the MDE editor:
1. Select Config from the menu bar at the top of screen to display the Configurators
pull-down menu.
2. Select Historian from the Configurators menu to display the Historian pull-down
menu.
3. Select MDE_Edit from the Historian menu to call up the Manual Data Single Vari-
able Edit display shown in Figure 7-1. The example shows the type of data that can
appear in the various fields. When the display first comes up, all the fields are empty.
49
B0193BL – Rev L 7. Manual Data Entry
Figure 7-1. Manual Data Single Variable Edit Display
The display is divided into several sections:

♦ The upper right corner contains a group and variable selections area that lets you
choose the desired MDE group and variable.
♦ The lower right part of the display contains the fields you can use to enter date, time,
and variable values, and a scrollable Edit History window that shows your entries.
♦ The data view window in the left side of the display lets you search for a data MDE by
date and time.
♦ Three time fields in the lower left corner of the display let you set automatically incre-
mented time intervals.
♦ The Status field at the bottom of the display shows whether a value is within range
(Good) or out of range (Bad).
Editing MDE Values

To edit existing MDE variable values:
1. Click the MDE Group pop-up in the upper right corner of the display.
50
7. Manual Data Entry B0193BL – Rev L
2. When the groups pop-up window appears listing the available groups, scroll to the
desired group and click it to select it.
3. After the name of the selected group appears next to the MDE groups label, click the
Variable pop-up.
4. When the Variable pop-up window appears, listing the available variables, scroll to
the desired variable and click it to select it.
NOTE
Variables must be in uppercase.
The Historian fills the Description, Units, High Range, and Low Range fields with
data.
5. Optionally, enter a date (mmddyy) and time (hhmmss) in the Search Date/Time
input boxes and click the Find button.
A list of values nearest to the search date and time appears in the data view window.
You can use the Next and Previous buttons to page through the list.
6. To edit one of the values, click the desired value.
The Historian copies the entire line of data into the three data entry boxes
(mmddyy, hhmmss, and Value) in the lower right corner of the display.
7. Modify the values in these boxes as needed, pressing Enter after each change.
After you modify the data in the Value data entry box and press Enter, the new value
is entered into the group and the new line of data appears in the Edit
History window just above the three data entry boxes. Every new line of data you
enter appears in the Edit History window.
To modify values you have just entered:

Click the desired line in the Edit History window.
The date, time, and value of the variable reappears in the three data entry boxes, where
you can modify them as needed. Pressing Enter while the cursor is in the Value box,
updates the values in the group and the Edit History window.
To add new values to a variable:

a. Click in the mmddyy field, enter the date of the value, and press Enter.
b. Click in the hhmmss field, enter the time of the value, and press Enter.
c. Click in the Value field, enter the value, and press Enter. Now the data is entered
in the database.
If the value you enter is within the range specified in the High Range and Low Range
fields, the status at the bottom of the display appears as GOOD. If you enter a value out-
side this range, a message box appears with the following prompt:
Value out of range. Add it anyway? With a BAD status.
If you click OK, the value is added to the list. In this case, the status at the bottom of
the display appears as BAD.
If you enter large numbers of values manually, you can have the Historian automatically incre-
ment the value in the time field with the increment of your choice. Enter the increment in the
51
hours, mins, and secs fields at the lower left of the display. Press Enter to move through the time
and date fields to get to the value field. Using this typing aid, you can quickly add large amounts
of new data by typing only in the Value field, while the hhmmss field is incremented automatically
each time you press Enter.
You can delete an existing data line by clicking on it with the cursor to select it, then clicking the
Delete button.
WYSE Terminal and Foreign Database Interface

The console program mdew1 provides an alternate way of entering sample data into the MDE
database. mdew1 can be executed from a WYSE terminal or from a WP in VT100 mode. All
input to the program is read from stdin, and the output log and error messages are written to std-
out (by default, both are the terminal).
Using standard UNIX I/O redirection, the program may receive its input from a file. You may
create the file using a text editor. Alternatively, the input data can be generated by the report
writer of your database management system.
The input data consist of a small set of directives and pairs of variable names and values.
Use the program only for data entry and modification. Before using mdew1, configure the groups
and variables referenced in the input data with the Historian Configurator.
Execution
On an AP20, the mdew1 program resides in /usr/fox/historian/bin; on a 50 Series
workstation, the program resides on /opt/fox/historian/bin.
Assuming that the environment variable path includes the location of the program mdew1, you
may execute the program as shown in the following examples:
Table 7-1. Console Program (mdew1) Examples
mdew1 Input is from the terminal, and the output is logged to the terminal.
mdew1 | tee mdelog Same as above, but the log also goes to file mdelog.
mdew1 <dbrep >>mdelog Input is read from the file <dbrep>, and the program log is
appended to the file mdelog.
mdew1 -t <dbrep> Input is read from the file <dbrep>, and the log goes to the
terminal. The -t (test) option checks the input file for syntax errors
without committing the samples to the MDE database.
Input Data
Input commands consist of a free formatted stream of directives and pairs of variable names on
the one hand, and sample values on the other. All fields are separated by one or more white spaces
(space, tab, return, newline, or form feed). Therefore, no variable name, directive or parameter
can contain a white space character.
Any number of commands may appear on one line, but one command cannot extend across line
boundaries.
Input data is not case sensitive. All characters are converted to lowercase before they are
interpreted.
52
Comments may appear anywhere in the input stream and must be enclosed in braces: { ... }.
Nested comments are allowed: { ... { ... } ... }.
Directives
Directives are identified by a leading dot (.). Words starting with other characters are interpreted
as variable names or as parameters to directives, if applicable.
Only the first character of a directive is interpreted. But you can expand it to any number of (non-
space) characters.
For example, the two directives:
.h hist01
.Historian hist01
perform the same function.
Directives stay in effect until they are issued again with a different parameter, or are cancelled by
another directive.
Table 7-2. Historian Directives
.historian <hstnam> Select the historian <hstnam>. This directive must be issued before data
samples are entered.
.group <mdegroup> Select the MDE group name <mdegroup> for subsequent variables.
.status Status word in hexadecimal notation. Default is 0003.
<statusword>
.date <datespec> Define the date for subsequent samples. Initial default is the date of
program start. <datespec> can be in the formats: mm-dd-yy, mm/dd/yy –
(any non-numerical character works as a separator); mmddyy – if no
separators are used, day and month must be exactly two characters long);
mm-dd, mmdd – (the year is not changed if omitted); /dd – (only the day
is changed); dd.mm.yy, dd.mm., dd. – (Anything with a dot is interpreted
as European format.).
.time <timespec> Define the 24-hour clock time for subsequent samples. Initial default is the
time of program start. <timespec> can be in one of the following
formats: hh:mm:ss, hh:mm, hh – (minutes and seconds are set to zero if
omitted); hhmmss, hhmm – (if no separators are used, hours and minutes
must be two characters long).
.override Disable value range checking.
.nooveride Enable range checking (initial default).
.+ Select add mode (initial default).
.- Select delete mode. In delete mode, the sample to be deleted is identified by
the variable name and the given time and date. The actual value is ignored,
although a dummy number must be supplied to complete a name/value
pair.
.% Select modify mode. Subsequent samples replace existing ones with the
same name and time stamp.
.quit or .x Exit. May be omitted when input is from a file.
53
Samples
A sample is a pair consisting of a variable name followed by a numeric value. Whenever a sample
is detected in the input stream, it is sent to the currently selected historian. At that time, the data
record is also written to the log output for verification by the operator.
Examples of samples are:
bat23_avg 78.5
bat23_min 71.2 bat23_max 82.1
level_ab 55 level_fg 66.5
Prefix/Suffix Notation
To save typing, variable names can be defined as prefix/suffice combinations. A prefix is identified
by a trailing hyphen (’), and a suffix is identified by a leading hyphen. A prefix stays in effect until
you change it. A stand-alone hyphen is a valid suffix if the current prefix defines the whole vari-
able name. The notation (’) can be used like a wildcard to define repeat substrings in a name. The
previous samples can be entered as:
bat23_’ ’avg 78.5 ’min 71.2 ’max 82.1
level_’
’ab 55
’fg 66.5
Examples
Input File
{ md1.add Test file for mdew1.}
.h htsmpl { select historian }
.+ { Specify ADD mode. Redundant, because it’s the default. }

.n { No Override for out-of-range checking. Also redundant. }
.g testgrp1 { Specify the group name for subsequent variables. }
{ The MDE variable “entrylog” associates the current

time and date of this MDE session with a batch number.
The variable “batchlog” associates the batch number
with the time stamp used for data samples. }
entrylog 22
.t 8 { 8 o’ clock in the morning. }

.d 9-25 { Time and date stay in effect until changed again. }
batchlog 22
kero_’
’temp 123.4 ’dens .789 ’visc 1.350
goop_’ ’temp 234 ’dens 3.45 ’visc 200.2
.OVERRIDE { Allow out-of-range values. }
k20’
’v1 123.456
’v2 23.45
’v3 44.77
54
.q { .x or .q are not required when using a file as input }
Program Log
MDE session opened at 12/17/90_10:19:04
L003: Historian “htsmpl” selected.

L005: ADD mode selected.
L006: Value range checking ENABLED.
L013: G=testgrp1 T=09/27/90_10:19:04 P=entrylog V= 22.000 S=0003
L018: G=testgrp1 T=09/25/90_08:00:00 P=batchlog V= 22.000 S=0003
L021: G=testgrp1 T=09/25/90_08:00:00 P=kero_temp V= 123.400 S=0003
L021: G=testgrp1 T=09/25/90_08:00:00 P=kero_dens V= 0.789 S=0003
L021: G=testgrp1 T=09/25/90_08:00:00 P=kero_visc V= 1.350 S=0003
L023: G=testgrp1 T=09/25/90_08:00:00 P=goop_temp V= 234.000 S=0003
L023: G=testgrp1 T=09/25/90_08:00:00 P=goop_dens V= 3.450 S=0003
L023: G=testgrp1 T=09/25/90_08:00:00 P=goop_visc V= 200.200 S=0003
L025: Value range checking DISABLED.
L028: G=testgrp1 T=09/25/90_08:00:00 P=k20v1 V= 123.500 S=0003
MDE session closed at 12/17/90_10:19:23
55
56
8. Calls Overview
This chapter describes how user application programs written in the C language can interface
with the Historian through calls to configuration, scheduling, and data retrieval routines in the
Historian library.
A user-written program can interface with the Historian to:
♦ Request or schedule data collection for reduction, message, or archive groups.
♦ Start and stop data reduction, message collection, and archiving.
♦ Configure reduction and archive groups and modify message group configurations.
For reduction groups, you can add and delete groups, group members, and
operations.
♦ Perform bulk transfers of data values from user application programs to the
Historian reduced database.
An application program can use the historical database as a source of information for trend plots
and reports. It can also use the Historian to maintain a history of variables that can only be
manipulated by the application program. For example, a program may retrieve a group of histori-
cal reduced measurement values, statistically correct them, and return the results to another
reduction group in the historical database.
Application programs can use the Historian to manage a history of events or values and reduce
and archive the data. Historian sample, reduced, MDE, and archive data can be read by any pro-
gram.
Linking Application Programs

To make calls to Historian interface functions from your application programs, link your pro-
grams to the Historian function library (libhist.a). Object modules compiled in the
C programming language can be linked to Historian interface function modules to create an exe-
cutable program by using one statement. If the object modules that make calls to the Historian
are myprog.o, func1.o, and func2.o, and the program is myprog, then the appropriate statement
is:
cc -o myprog myprog.o func1.o func2.o -lhist
-lisam -lfox -lPW
The -lhist option provides the link to the Historian library.
Sending Data
Application programs send data to the Historian for storage by calling the Historian interface
functions. Programs use the Historian to keep a history of data values (analog or discrete) by:
57
B0193BL – Rev L 8. Calls Overview
♦ Storing values in a Historian global variable and configuring the global variable into a
collection group
♦ Storing values in a Historian reduction group that is configured as a data source to
data reduction and archiving operations, and other similar operations.
Retrieving Data
User application programs can access Historian configuration and collected data, including
dynamic, on-line data and archived data. Programs access this data by making calls to Historian
interface functions. These functions return the requested data to the caller.
Collected data includes sample, reduced, MDE, and archive data. The Historian supports the fol-
lowing data access functions:
♦ Get reduced data for a group name, point name list, operation list, and time span
♦ Get configuration information for a reduction, message, or archive group
♦ Get configuration information for a reduction, or archive group member
♦ Get sample data for a point name, and time span or number of values
♦ Get reduced data for a group name, point name, operation name, and time span or
number of values
♦ Get MDE data for a group name, point name, and time span or number of values
♦ Get sample, reduced, or MDE data for an archive group name, point name, and time
span or number of values.
NOTE
Group members are points for non-cascaded reduction groups. Group members are
groups for cascaded reduction and archive groups.
Use the Historian data retrieval displays to view application messages. Subroutine calls are not
provided for retrieving historical messages. Use the database manager to retrieve messages, except
alarm messages, from user-created application programs.
Changing Configuration Data

User application programs can change Historian configuration data by making calls to
Historian interface functions. A program may change the Historian configuration to:
♦ Add, modify, and delete reduction and archive groups and their associated configura-
tion parameters
♦ Add and delete reduction and archive group members
♦ Modify message group configuration parameters.
NOTE
Do not set up a group or operation as a single-user type.
58
9. Configuration Calls
This chapter describes the Foxboro subroutines that configure collection groups in other
applications.
You can configure collection groups from any application program that includes the
hstorian.h file and links to the libhist.a library. The Historian configuration calls and their
functions are listed in Table 9-1.
The hstorian.h file is included with the Historian software and contains error codes and the size
of data types used in the configuration calls, as well as data structures/elements reserved for future
use. User applications that call these subroutines must include the hstorian.h file.
NOTE
You must use a workstation to add or delete member points for the Historian point
sample collection.
Table 9-1. Configuration Calls
Call Function
add_cfg Inserts the supplied group configuration into the configuration
(group_id, type, cfg) database.
add_mem Inserts the supplied member names and associated data into the
(group_id, member) member lists of the specified group.
add_opr Inserts the supplied operations into the operations list of the
(group_id, oper) specified reduction group.
db_init (domain) Selects a database domain for subsequent Historian calls.
del_cfg (group_id) Removes the specified group configuration and all group type
specific lists from the configuration database.
del_mem Removes the supplied members from the member list of the
(group_id, member) specified group.
del_opr Removes the supplied operations from the operations list of the
(group_id, oper) specified reduction group.
get_cfg Returns all of the group configuration parameters for the specified
(group_id, type, cfg) group.
get_mem Retrieves the name and associated parameters of all members of the
(group_id, type, member) specified group.
get_opr Retrieves the operations and associated parameters for the specified
(group_id, oper) group.
get_sum (type, buffer) Retrieves the name and description of all groups of the specified type.
mod_cfg Allows you to modify an existing group’s configuration parameters in
(group_id, type, cfg) the configuration database.
59
B0193BL – Rev L 9. Configuration Calls
Table 9-1. Configuration Calls (Continued)
Call Function
mde_apnt Allows adding, modifying, or deleting the configuration for an MDE
(flags, cfgrec) point.
mde_rpnt (flags, pnt_id, Reads configuration data for one or more MDE points.
numrec, cfgrecs)
mde_agrp (flags, cfgrec) Allows adding, modifying or deleting the configuration for an MDE
group.
mde_rgrp (flags, grp_id, Reads configuration data for one or more MDE groups.
numrec, cfgrecs)
mde_amem Allows adding or deleting an MDE member point to/from an MDE
(flags, grp_id, pnt_id) group.
mde_rmem (flags, grp_id, Reads one or more entries from the MDE group member
pnt_id, numrec, cfgrec) configuration.
NOTE
Before using these calls, call db_init to select the applicable database.
In previous versions of the Historian, the application program registered and activated the process
with Interprocess Communications (IPC). This is not required for the Version 3.0 Historian. The
db_init call handles all preliminary setup.
The calls that can be used for reduction, archive, and message groups are:
Reduction Group Archive Group Message Group MDE Group
db_init db_init db_init db_init
get_sum get_sum get_sum mde_apnt
add_cfg add_cfg dfin_ms mde_rpnt
del_cfg del_cfg undf_ms mde_agrp
mod_cfg mod_cfg mde_rgrp
get_cfg get_cfg mde_amem
add_mem add_mem mde_rmem
del_mem del_mem
get_mem get_mem
add_opr
del_opr
get_opr
The Historian performs the following configuration error checks:

♦ Duplicate group names
♦ Duplicate member point or group names within a group
♦ Existence of a specified member group
♦ Parameter specified for a group of the wrong type.
60
9. Configuration Calls B0193BL – Rev L
You can add or modify a group configuration at any time.
NOTE
Release the buffer after calls to get_sum, get_cfg, get_mem, or get_opr.
The following pseudo-code fragment code shows you how to deallocate a buffer:
cc = get_cfg ( ...);
free (query.buffer);
db_init — Database Initialization

This call selects a database domain for subsequent Historian interface function calls.
Format: db_init (domain)
char*domain;
where:
*domain Pointer to an existing data_base name (character type data of size

DBNM_SIZ). Terminate this string with a null character.
Return Codes:
ENO_DB No database exists for the specified name.
SUCCESS db_init has selected the database.
get_sum — Get Type Summary

This call retrieves the name and description of all collection groups of the specified type.
Format: get_sum (type, buffer)
grp_typ type;
struct TYP_SUMM **buffer;
where:
type Group type (enumerated type data) for which you want a summary list.
Valid group types are:
REDUCE; ARCHIVE; MESSAGE; ALL_TYP.
**buffer Pointer to a pointer (returned by get_sum) to a buffer that is structured as

an array of TYP_SUMM data structures consisting of the following
elements:
id Group identifier (character type data of size GPID_SIZ).
desc Group description (character type data of size DESC_SIZ). get_sum uses
this buffer to return the above data for all groups of specified type in the
database.
61
NOTE
1. The end of the buffer is terminated by a null ID field.
2. The buffer is sorted in ascending order using the group identifier.
3. If there are no groups of the specified type, the SUCCESS code and a buffer con-
taining one null record is returned.
4. When you are through with the buffer, release it.
Return Codes:
E_MEMORY Cannot create the buffer.
E_INFRMX Cannot access data. INFORMIX error is returned in external

integer errno. You may not have selected the database via the db_init
function. INFORMIX error codes are listed in Real-Time Database Man-
ager: INFORMIX-SQL Relational Database Management System Version
1.10 (B0193BT).
EBAD_TYP Specified group type is not a valid type.
add_cfg — Add Group Configuration

This call inserts the supplied group configuration definition into the Historian configuration
database.
Format: add_ cfg (group_id, type, cfg)
char *groupid;
grp_typ type;
union CFG_DAT *cfg;
where:
*group_id Pointer to the group identifier (character type data of size GPID_SIZ) for
the group configuration that you want to add to the database. The group
must not already exist in the database.
type Group type (enumerated type data) for the group configuration that you
want to add to the database. The group types are: REDUCE and
ARCHIVE.
*cfg Pointer to buffer of data structures containing the configuration data you
are passing for the groups you want to add to the database. These data
structures and their elements are:
Reduction Group:
desc Group description (character type data of size DESC_SIZ).
usage Group usage (enumerated type data) flag: SINGLE or MULTIPLE.
path Storage directory path (character type data of size PATH_SIZ) for the
group configuration data.
62
period Time period (short integer), hours, minutes, or seconds, for scheduling
the execution of data reduction operations for the group. Configuring this
period in seconds is not recommended.
per_fact Time units (enumerated type data) for the element period:
SECONDS = 1, MINUTES = 60, HOURS = 3600.
delay Phasing delay (short integer), time delay in hours, minutes, or seconds, for
leveling the data-reduction processing load on the application processor.
del_fact Time units (enumerated type data) for the element delay:
SECONDS = 1; MINUTES = 60; HOURS = 3600.
tim_span Time span (short integer) — hours, minutes, or seconds — for the data to
be included in the reduction process (cascaded groups only).
tim_fact Time units (enumerated type data) for the element tim_span:
min_span Minimum time span, hours, minutes, or seconds, required for valid reduc-
tion operations when some of the input data is not available. This time
span must be period element.
min_fact Time units (enumerated type data) for the element min_span:
smpl_per Time span (short integer), hours, minutes, or seconds, for scheduling the
collection of point sample data required for a noncascaded reduction
group. Set smpl_per equal to zero (0) to configure a cascaded reduction
group.
smpl_fac Time units (enumerated type data) for the element smpl_per:
max_span Maximum time span (short integer), hours, minutes, or seconds, for
retaining historical data for the group. When the Historian executes a
reduction, it deletes data that is older than this time span.
max_fact Time units (enumerated type data) for the element max_span.
usr_task Task name (character type data of size TASK_SIZ) for your reduction pro-
cess.
cfg_err Error (long integer) returned for the logical OR results of the following
configuration data errors:
E_DELAY; E_PERIOD; EDEL_FAC; EMAX_FAC; EMAX_SPN;
ENULL_I;D EPER_FAC; ETIM_FAC; ETIM_SPN;
ARCHIVE GROUP.
63
usage Group usage (enumerated type data) flag:

NULL_USE; SINGLE; MULTIPLE.
volum_id Archive volume name (character type data of size VOLM_SIZ).
period Total time period (short integer), hours, minutes, or seconds, for
scheduling execution of archiving operations for the group.
per_fact Time units (enumerated type data) for the element period:
delay Phasing delay (short integer), delay factor in hours, minutes, or seconds,
for leveling the archive processing load on the application processor.
del_fact Time units (enumerated type data) for the element delay:
tim_span Time span (short integer), hours, minutes, or seconds, for retaining histor-
ical data for the group. When the Historian executes an archiving opera-
tion, it deletes archived reduction data that is older than this time span.
span_fac Time units (enumerated type data) for the element tim_span:
configuration data errors:
E_DELAY; E_PERIOD; EDEL_FAC; ENULL_ID; EPER_FAC;
ETIM_FAC; ETIM_SPN
NOTE
The Historian verifies the configuration to ensure that all time quantities, time fac-
tors, and maximum counts exceed zero. Violations are returned as function status
code EBAD_CFG, and the specific error(s) are returned via the cfg_err configura-
tion parameter.
Return Codes:
EGRP_DEF One or more group definition parameters is in error.
EBAD_TYP Group type is not consistent with the other configuration parameters.
EBAD_CFG One or more configuration parameters is in error.
EBAD_XEC Cannot create the data table for a reduction group.
E_INFRMX Cannot access the database. INFORMIX error is returned in external

64

1.10 (B0193BT).
SUCCESS add_cfg has inserted the group configuration data into the database.
mod_cfg — Modify Group Configuration

This call allows you to modify the configuration parameters of a group that exists in the
Historian configuration database.
Format: mod_cfg (group_id, type, cfg)
char *group_id;
grp_typ type;
union CFG_DAT *cfg;
where:
the group configuration that you want to modify in the database.
type Group type (enumerated type data) for the group configuration that you
want to modify in the database. The group types are:
REDUCE; ARCHIVE; MESSAGE.
*cfg Pointer to buffer of data structures containing the configuration data you
are passing for the groups you want to modify in the database.
For reduction and archive groups, these data structures and their elements
are defined in “Defining Reduction Groups” on page 26 and “Defining
Archive Groups” on page 27.
For message groups, these data structures and their elements are:
usage Group usage (enumerated type data) flag: SINGLE; MULTIPLE.
configuration data errors: EBAD_CNT; ENULL_ID.
NOTE
The Historian verifies the configuration to ensure that all time quantities, time fac-
tors, and maximum counts exceed zero. Violations are returned as function status
code EBAD_CFG, and the specific error(s) are returned via the cfg_err configura-
tion parameter.
Return Codes:
EGRP_DEF One or more group definition parameters is in error.
65
EBAD_TYP Group type is not consistent with the other configuration parameters.
EBAD_CFG One or more configuration parameters is in error.
EBAD_XEC Configuration data table for a reduction group cannot be created.
E_INFRMX Database cannot be accessed. INFORMIX error is returned in external

1.10 (B0193BT).
SUCCESS mod_cfg has changed the group configuration data into the database.
del_cfg — Delete Group Configuration

This call removes the specified group configuration and group type specific lists from the Histo-
rian configuration database.
Format: del_cfg (group_id)
char *group_id;
where:
the group configuration that you want to delete from the database.
NOTE
1. All data that the Historian has logged for the group is deleted.
2. Requirements for deleting a group are:
- Group is not active.
- Group is not referenced by another group.
- Group is not a message group — you cannot delete message groups.
- Group is a either a single-user group created by the requesting program or a
multiple_user group.
3. You can delete the group definition from the data collection control table by issu-
ing a REMOVE signal via the chg_stat subroutine.
Return Codes:
ENOT_DEF Specified group does not exist.
ENOT_OWN Requestor does not own specified single-user group.
EBAD_STA Status of the specified group is active.
EBAD_TYP Specified group is a message or unrecognized group.
EGRP_MEM Specified group is referenced by another group.
66

1.10 (B0193BT).
SUCCESS del_cfg has deleted the group from the configuration database.
get_cfg — Get Group Configuration

This call returns the configuration parameters for a group that exists in the Historian configura-
tion database.
Format: get_cfg (group_id, type, cfg)
char *group_id;
grp_typ *type;
union CFG_DAT **cfg;
where:
which you want the group configuration parameters stored in the data-
base.
*type Pointer to the group type (enumerated type data) returned by get_cfg for
the returned configuration data. The group types are:
REDUCE; ARCHIVE; MESSAGE.
**cfg Pointer to a pointer (returned by get_cfg) to a buffer of data structures

used by get_cfg to return the configuration data for the specified group.
NOTE
When you are through with the buffer, release it.
Return Codes:
EBAD_TYP An unknown group type exists in the configuration database.

1.10 (B0193BT).
E_MEMORY get_cfg cannot create the buffer required for returning the configuration
data.
SUCCESS get_cfg has returned the group configuration data.
67
add_mem — Add Group Members

This call inserts the supplied member names and associated data for the group into the configura-
tion database.
Format: int add_mem (group_id, type, member)
char *group_id;
mem_typ type;
union MEMB_DAT *member;
where:
which you want to add member names and associated configuration data
to the database. Specify a single-user group configured (owned) by the
calling program or a multiple-user group.
type Member type (enumerated type data) for the group member that you
want to add to the database. The member types are: POINT; GROUP.
*member Pointer to buffer of data structures containing the member names and
associated configuration data you are passing for the members that you
want to add to the database. The elements of these data structures are:
Member Points — Reduction Groups:
id Point identifier (character type data of size PTID_SIZ) for the member
point that you want to add to the group. Terminate the list of point iden-
tifiers with a null ID field.
desc Point description (character type data of size DESC_SIZ).
db The change deadband (floating point type) for the member point. The
change deadband must be greater than zero (0).
status Configuration status (long integer) for the member point. You do not pass
status data. add_mem uses this field to insert the configuration status of the
point (see Note 7).
Member Groups — Reduction and Archive Groups:
id Group identifier (character type data of size GPID_SIZ) for the member
group that you want to add to the specified group. Terminate the list of
group identifiers with a null ID field.
status Configuration status (long integer) for the member group. You do not
pass status data. add_mem uses this field to insert the configuration status
of the group (see Note 7).
68
NOTE
1. Member groups that you are adding must exists in the database.
2. Configuration data for the specified group identifier must exist in the database.
3. Message groups do not have group members.
4. You cannot add group members of one archive group to another archive group.
5. You cannot add point members of one reduction group to another reduction
group.
6. Add member groups to a cascaded reduction group, not a noncascaded one.
7. When add_mem returns the EBAD_DAT error code, it inserts the logical OR
results of the following errors, as appropriate, into the status field of each member
point or group that is rejected:
EMEM_D; EFE_DELTA; EMEM_ARC; EBAD_MEM;
ETIM_SPN; ETIM_FAC.
8. The change deadband is the change in point value that the Object Manager must
detect before it updates the point data.
Return Codes:
EBAD_DAT Error in the member point or member group data passed by the caller.
EBAD_TYP Specified group identifier is for an invalid group type (that is, message
group).

1.10 (B0193BT).
ENOT_DEF Specified group identifier does not exist in the configuration database.
SUCCESS add_mem has inserted the specified member(s) in the configuration data-
base for the specified group.
del_mem — Delete Group Members

This call removes the supplied group members from the member list of the group in the configu-
ration database.
Format: int del_mem (group_id, member)
char *group_id;
struct MEMB_ID *member;
where:
which you want to delete member names in the configuration database.
69
Specify a single-user group configured (owned) by the calling program or

a multiple-user group.
*member Pointer to buffer of data structures containing the member names that you
want to delete from the member list for the group in the database. The
data structure contains one element:
id Point or group identifier (character type data of size PTID_SIZ) for the
member point or group that you want to delete from the group. Termi-
nate the list of point/group identifiers with a null ID field.
NOTE
1. The specified group identifier must exist in the database.
Return Codes:
group).

1.10 (B0193BT).
SUCCESS del_mem has deleted the specified member(s) in the configuration database
for the specified group.
get_mem — Get Group Members

This call retrieves the name and associated parameters for all members of the specified group.
Format: int get_mem (group_id, type, member)
char *group_id;
mem_typ *type;
union MEMB_DAT **member;
where:
which you want to retrieve the names and associated configuration data
from the database.
*type Pointer to a member type (enumerated type data returned by get_mem) for
the group member names and associated data returned by get_mem. The
member types are: POINT; GROUP.
70
**member Pointer to a pointer (returned by get_mem) to the buffer of data structures

containing the member names and associated configuration data returned
by get_mem for the group that you requested. Elements of these data
structures are:
Member Points — Reduction Groups:
id Point identifier (character type data of size PTID_SIZ) for the returned
member point. The list of point identifiers is terminated with a null ID
field.
desc Point description (character type data of size DESC_SIZ).
db The change deadband (floating-point type) for the returned point.
status Not used.

Member Groups — Reduction and Archive Groups:
id Group identifier (character type data of size GPID_SIZ) for the member
groups returned by get_mem. The list of group identifiers is terminated
with a null ID field.
status Not used.
NOTE
1. Configuration data for the specified group identifier must exist in the database.
3. The change deadband is the change in point value that the Object Manager must
detect before it updates the point data.
Return Codes:
group).

1.10 (B0193BT).
E_MEMORY get_mem cannot create the buffer required for returning the member point
or group data.
SUCCESS get_mem has returned the specified point or group members for the speci-
fied group in the configuration database.
71
add_opr — Add Operations

This call inserts the supplied reduction operations into the operations list of the specified reduc-
tion group.
Format: int add_opr (group_id, oper)
char *group_id;
struct R_OPER *oper;
where:
*group_id Pointer to a reduction group identifier (character type data of size

GPID_SIZ) for which you want to add reduction operations. Specify a
single-user group configured (owned) by the calling program or a multi-
ple-user group.
*oper Pointer to a buffer of R_OPER data structures (last one contains null
data) required for entering the reduction operation paramaters into the
configuration database. Elements of this structure are:
op_code Reduction operation (enumerated type) for which you are supplying
parameters:
SUM; AVG; MAX; MIN; STDV; KURT; HIST; USER.
Each operation must be unique within the group. Use NULL_OP for the
op_code of the last data structure in the buffer.
col_name Storage table column name (character type data of size CNAM_SIZ)
where the reduced data is to be stored.
src_name Source column name (character type data of size CNAM_SIZ) for the
data to be reduced — cascaded group only.
value_1 Low range value (floating point) for the histogram bin.
value_2 High range value (floating point) for the histogram bin.
status Configuration status (long integer) for the operation. You do not pass sta-
tus data. add_opr uses this field to insert the configuration status of the
operation (see Note 3).
NOTE
1. If a user task name (nonnull) is specified in the group configuration, you can
configure the group for user-defined reduction operations.
2. For a cascaded reduction group (sampling period equals zero), SUM, AVG,
MAX, and MIN are the only operations that you can specify.
3. In the status field of each R_OPER structure it receives with an error, add_opr
inserts the results of a logical OR operation that it performs on the EMEM_DEF,
EUSR_TSK, and EBAD_OPR error codes.
4. In addition to modifying the configuration database, add_opr also manipulates
each record within the specified reduction group’s data table.
72
Return Codes:
E_INFRMX add_opr cannot access data. INFORMIX error is returned in external

1.10 (B0193BT).
EBAD_DAT Error in received R_OPER structure data. Status field of each R_OPER
structure in error contains the EBAD_OPER code.
EBAD_TYP Group is not a reduction group.
SUCCESS add_opr has inserted the supplied operations in the configuration

database.
del_opr — Delete Operations

This call removes the supplied reduction operations from the operations list of the specified
reduction group.
Format: int del_opr (group_id, oper)
char*group_id;
struct R_OPER*oper;
where:

GPID_SIZ) from which you want to delete reduction operations. Specify
a single-user group configured (owned) by the calling program or a
multiple-user group.
*oper Pointer to a buffer of R_OPER data structures (last one contains null
data) that contain the reduction operation parameters to be deleted from
the configuration database. Elements of this structure are:
op_code Reduction operation (enumerated type) for which you are supplying
parameters:
SUM; AVG; MAX; MIN; STDV; KURT; HIST; USER; NULL_OP.
Use NULL_OP for the op_code of the last data structure in the buffer.
data to be reduced.
73
status Not used.
NOTE
In addition to modifying the configuration database, del_opr also manipulates each
record within the specified reduction group’s data table.
Return Codes:
E_INFRMX del_opr cannot access data. INFORMIX error is returned in external

1.10 (B0193BT).
SUCCESS del_opr has deleted the supplied operations from the configuration data-
base. If an operation is not a member of the specified group’s operation
list, del_opr still returns the Success code.
get_opr — Get Operations

This call retrieves the reduction operations and associated parameters for the specified reduction
group.
Format: int get_opr (group_id, oper)
char*group_id;
struct R_OPER**oper;
where:

GPID_SIZ) for which you want to retrieve reduction operations and asso-
ciated parameters. Specify a single-user group configured (owned) by the
calling program or a multiple-user group.
**oper Pointer to a pointer (returned by get_opr) to a buffer of R_OPER data

structures (last one contains null data) containing the reduction operation
parameters for the specified group, from the database. Elements of this
structure are:
op_code Reduction operation (enumerated type): SUM; AVG; MAX; MIN;

STDV; KURT; HIST; USER; NULL_OP.
NULL_OP is returned for the op_code of the last data structure in the
buffer.
74
col_nam Storage table column name (character type data of size CNAM_SIZ)
data to be reduced.
status Not used.
NOTE
When you are through with the buffer, release it.
Return Codes:
E_INFRMX get_opr cannot access data. INFORMIX error is returned in external

1.10 (B0193BT).
E_MEMORY get_opr cannot create the buffer required for returning the reduction
operation parameters for the specified group.
SUCCESS get_opr has returned the reduction operation parameters for the specified
group in the configuration database.
mde_apnt — Add/Modify/Delete MDE Point

Configuration
This call allows adding, modifying, or deleting the configuration for an MDE point.
Format: erc = mde_apnt (flags, cfgrec);
where:
flags Bits 0-1:

0 = (NA)
1 = Add point configuration record.
2 = Delete point configuration record.
3 = Modify point configuration record.
Bit 3:
(for Delete mode only:)
0 = soft delete, mark record as deleted,
1 = crowbar delete, remove record.
75
cfgrec: Point Configuration Record (struct M_pntcfg).
pnt_no Point Number. Unique among all MDE points within a database. Not re-
used when points are deleted. In Add mode, the new point number is
returned to the caller in pntno.
pnt_id Point name. This is the only field used in Delete mode, the remainder of
the record is ignored if present.
desc Point description.
units Engineering units.
cfgstat Configuration status. 0 = OK; -1 = point deleted.
validate Data entry validation flags:

Bit 0 = 1: Validate data against lo_span.
Bit 1 = 1: Validate data against hi_span.
Bit 2 = 1: Validate time stamp against val_date.
lo_span Low value for data entry validation.
hi_span High value for data entry validation.
val_date Time limit for data entry validation.

In Add mode, the record in the request is added to the configuration file. If the point name is not
unique, the request is rejected. The point number is internally assigned (with isuniqueid()) and
returned to the requestor.
In Modify mode, the record in the request overwrites the existing one. The record is identified by
the point name. The record may be active or marked as deleted. If the point name is not found,
the request is rejected. Since the point name identifies a configuration record, it cannot be modi-
fied.
If the name needs to be changed, it must be deleted and then added again.
In Delete mode, only the point name is used in the configuration record.
If the crowbar flag is 0, the record is marked as deleted, but not removed from the file. A record
deleted in this way is re-used if a point with the same name is added later.
If the crowbar flag is 1, the point’s record is deleted from the file. Also, all entries in the member
file that belong to this point are deleted. The function does not attempt to delete data records that
may belong to the point.
Return Codes
REM_DONE 1 Function completed without error.
BAD_PTNAME -4 Variable name or number not found.
E_OPNMPT -60 Cannot open mde_points.
E_WRTMPT -62 Error writing mde_points.
E_OPNMMB -66 Cannot open mde_memb.
E_INVP -170 Invalid parameter or argument.
E_UNIQUE -171 Point, group name, or sample point/time not unique.
76
mde_rpnt — Read MDE Point Configuration Data

This call reads configuration data for one or more MDE points.
Format: erc = mde_rpnt (flags, pnt_id, numrec, cfgrecs);
where:
flags Bit 0:
0 = ascending order (next),
1 = descending order (prev).
Bit 1:
0 = start after specified point (useful for consecutive requests)
1 = include specified point.
Bit 2: 0
Bit 3:
0 = skip deleted records,
1 = read all records.
Bits 4-5:
0 = point number and names only,
1 = include point description
2 = send full records
pnt_id Starting point name (0-padded). If pntid[0] = 0, start is at the beginning

or the end of the file, depending on the reading direction.
numrec Number of records requested. The actual number of records read is

returned in tot_pts in the response. Numrec is clipped at the following
max. values:
72 in name-only mode,
21 in description mode,
14 in full-record mode.
offset Not used.
cfgrecs Pointer to a buffer big enough to contain the expected number of point
configuration records. For struct M_pntcfg, see function mde_apnt().
Return Codes:
>0 Number of data records actually returned in sbuf.
0 No data matching request.
NO_DATA -13 No group, point, member or sample (in given range)
mde_agrp — Add/Modify/Delete MDE Group

Configuration Data
This call allows adding, modifying or deleting the configuration for an MDE group.
Format: erc = mde_agrp (flags, cfgrec);
77
where:
flags Bits 0-1:

0 = (NA)
1 = Add group configuration record.
2 = Delete group configuration record.
3 = Modify group configuration record.
Bit 3:
(for Delete mode only:)
0 = soft delete, mark record as deleted,
1 = crowbar delete, remove record.
cfgrec: Group Configuration Record: (struct M_grpcfg).
grp_id Group name to be added or deleted. The actual name must not be longer
than 10 characters and should be padded with trailing zeros.
desc Group description.
usage Usage: 2 = multiple (currently not used).
cfgstat Configuration status. 0 = OK; -1 = deleted
time_span Data retention time limit in hours.
time_factor Hours code = 3600.
policy 0, currently not used.

In Add mode, a record for the requested group name is added to all_groups and mde_cfg. Also,
an (empty) INFORMIX table is built for the group’s sample data. That includes entries in the
INFORMIX system catalogues systables, syscolumns, sysindexes and systabauth. If the group
name is not unique in the database, the request is rejected.
In Delete mode with the crowbar flag = 0, the group’s record in mde_cfg is marked as deleted.
(all_groups, mde_memb or the group’s data file are not affected.)
In Delete mode with the crowbar flag = 1, the group’s records in both all_groups and mde_cfg
are deleted. All records from mde_memb that belong to the group are deleted. The group’s sample
data file is also removed.
In Modify mode, the group’s records in all_points and mde_cfg are replaced with data in the
message. Since the group name is used to identify the records, it cannot be modified. If a group
name needs to be changed, the group must be deleted and re-added.
Return Codes:
BAD_GROUP -5 Group not found.
E_OPNSYS -31 Cannot open systables.
E_OPNCOL -33 Cannot open syscolumns.
E_OPNALG -45 Cannot open all_groups.
E_WRTSYS -52 Cannot write to systables.
78
E_WRTCOL -53 Cannot write to syscolumns.

E_OPNTAU -54 Cannot open systabauth.
E_WRTTAU -56 Cannot write to systabauth.
E_OPNIDX -57 Cannot open sysindexes.
E_WRTIDX -59 Cannot write to sysindexes.
E_OPNMCF -63 Cannot open mde_cfg.
E_WRTMCF -65 Error writing mde_cfg.
E_WRTALG -69 Error writing all_groups.
E_NOTIMPL1 -151 No entry for template in systables.
E_NOTIMPL2 -152 No entry for template in systabauth.
E_NOTIMPL3 -153 No entry for template in syscolumns.
E_NOTIMPL4 -154 No entry for template in sysindexes.
E_NOSDF1 -155 No entry for sample data file in systables.
E_NOSDF2 -156 No entry for sample data file in systabauth.
E_NOSDF3 -157 No entry for sample data file in syscolumns.
E_NOSDF4 -158 No entry for sample data file in sysindexes.
E_NOSDF0 -159 Sample data file not found.
E_SDFCRE -161 Cannot create sample data file.
E_INVP -170 Invalid parameter or argument.
E_CORUPT -172 Database corruption.
mde_rgrp — Read MDE Group Configuration Data

This call reads configuration data for one or more MDE groups.
Format: erc = mde_rgrp (flags, grp_id, numrec, cfgrecs);
where:
flags Bit 0:
0 = ascending order (next)
1 = descending order (prev)
Bit 1:
0 = start after the specified group, relative to the reading direction (useful
for consecutive requests)
1 = include specified group.
Bit 2: 0
Bit 3:
0 = skip deleted records,
1 = read all records.
Bits 4-5:
79

2 = send full records
grp_id Group name at which to start. If grp_id[0] = 0, then reading starts at the
beginning or end of the file, depending on the reading direction.

max. values:
cfgrec Pointer to a buffer for the configuration records. For struct M_grpcfg, see
function mde_cgrp().
Return Codes:
0 No data matching request.
NO_DATA -13 No group, point, member or sample (in given range).
mde_amem — Add/Delete MDE Group Member

Point
This call allows adding or deleting an MDE member point to/from an MDE group.
Format: erc = mde_amem (flags, grp_id, pnt_id);
where:
flags Bits 0, 1:
0 = (NA)
1 = Add
2 = Delete
3 = (N/A, modify not supported)
grp_id Owner group name.
pnt_id Point name to be added or deleted as a group member.

Return Codes:
E_OPNALG -45 Cannot open all_groups.
80

E_WRTMMB -68 Error writing mde_memb.
mde_rmem — Read MDE Group Members

This call reads one or more entries from the MDE group member configuration.
Format: erc = mde_rmem (flags, grp_id, pnt_id, numrec, cfgrecs);
where:
flags Bit 0:
0 = ascending order (next)
1 = descending order (prev)
Bit 1:
0 = start after the specified point, relative to the reading direction (useful
for consecutive requests)
1 = include specified point.
Bit 2: 0
Bit 3: not used.
Bits 4-5:
2 = send full records.
grp_id Owner group name.
pnt_id Starting point name. If pnt_id[0] = 0, reading starts at the beginning or

end of the file, depending on the reading direction.

max. values:
cfgrecs Pointer to a buffer big enough to contain the expected number of member
point configuration records. For struct M_pntcfg, see function
mde_apnt().
Return Codes:
NO_ERROR 0 Alternate no-error code, or no data matching request.
81
82
10. Operation Calls
This chapter describes operation calls, including collection group state changes and direct
storage of user data.
The operation functions retrieve or modify the operational state of collection groups. They also
allow you to add data values to the reduced database. Table 10-1 lists the operation function calls.
The hstorian.h file is included with the I/A Series Historian software. This file contains error
codes and the size of data types used in the configuration calls, as well as data structures and ele-
ments reserved for future use. User applications that call these subroutines must include the hsto-
rian.h file.
Table 10-1. Operation Calls
Call Function
add_data (query) Transfers user data into reduction group database.
chg_sta (group_id, chg_sgn1, Changes group operating status.
chg_time)
get_gmt (h_time) Converts Historian time structure into Greenwich Mean Time.
get_sta (group_id, grp_stat) Gets group operating status.
req_add (group_id, oper, query) Prepares Historian for receiving user data.
Collection Group State Changes

To retrieve or modify the operational state of a collection group from application programs, call
the following function subroutines:
get_sta — get group state
chg_sta — change group state.
get_sta retrieves the operational state of a collection group. chg_sta changes the operational
state of a group. Application programs that call these functions must include header file
hstorian.h.
You can request a state change at any time. Collection group states and state control signals are
respectively defined in Table 10-2 and Table 10-3. Allowable state transitions for scheduled and
message groups are respectively shown in Table 10-4 and Table 10-5.
Table 10-2. Collection Group States
STATE Description
NOT_ACTV Inactive state. Group definition resides in memory.
LOADING Inactive state. Group definition is being loaded from the configuration database.
Initiated at any time by RELOAD signal. Not applicable to message groups.
IDLE Quiet state. Group is waiting for external event.
83
B0193BL – Rev L 10. Operation Calls
Table 10-2. Collection Group States (Continued)
STATE Description
SCHEDULD Quiet state. Group is scheduled for periodic data collection.
PROCESSN Active state. Data collection or processing in progress.
Table 10-3. Group State Control Signal
SIGNAL Description
RELOAD Reload signal. Updates group definition in memory using current information
from the configuration database. If the group definition already resides in
memory, the state is restored to the pre-LOADING state.
REMOVE Delete signal. Deletes any data history.
CLR_STRT Start signal. Deletes any data history.
START Start signal. Preserves any data history.
MANL_REQ Start signal. Manual request for data collection or processing.
CANCEL Stop signal. Skips a pending data collection or processing cycle. Group remains
active.
STOP Stop signal. Active data collection or processing completes, at which time group
becomes inactive.
NOTE
If you have configured a new group for an existing historian, you can do a Start or
other operation for the group without doing a Reload operation. If you have recon-
figured an existing group, you must do a Reload operation for the group before
doing a Start or other operation.
Table 10-4. State Transitions for Scheduled Groups
State Signal New State

(any) RELOAD (unchanged)
NOT_ACTV REMOVE --------
NOT_ACTV CLR_STRT SCHEDULD
NOT_ACTV START SCHEDULD
NOT_ACTV MANL_REQ PROCESSN
SCHEDULD CANCEL SCHEDULD
SCHEDULD STOP NOT_ACTV
PROCESSN STOP NOT_ACTV
84
10. Operation Calls B0193BL – Rev L
Table 10-5. State Transitions for Message Groups
State Signal New State

NOT_ACTV CLR_STRT PROCESSN
NOT_ACTV START PROCESSN
PROCESSN STOP NOT_ACTV
chg_sta returns the following error codes:

EBAD_SIG for an invalid request to change states.
ENOT_OWN for a request to modify the state of a single-user group by programs other
than the owner (that is, the program that created the collection group).
ENOT_DEF for a request to modify the status of a collection group that does not exist.
get_sta — Get Group Status

This call retrieves the operational status for the specified collection group.
Format: int get_sta( group_id, grp_stat)
char *group_id;
struct G_STAT *grp_stat;
where:
*group_id Pointer to a group identifier (character type data of size GPID_SIZ) for
which you want status data.
*grp_stat Pointer to a data structure used to return status data. Elements of this data
structure are:
state Current state (enumerated type) of the group: NOT_ACTV;

LOADING; IDLE; SCHEDULD; DELAYING PROCESSN.
These states are described in Table 10-2.
savd_st Last saved state (enumerated type) for the group (see above).
schd_tim Next process execution time in seconds (long integer type) for the group.
savd_sig Last state change signal (enumerated type) processed for the group:
NULL_SIG; RELOAD; REMOVE; CLR_STRT; START; MANL_REQ;
CANCEL STOP.
These signals and the resulting state transitions are described in Table 10-3, Table 10-4, and
Table 10-5.
period Process scheduling period in seconds (long integer type) for the group.
delay Process delay factor (phasing delay) in seconds (long integer type) for the
group.
error Most recent processing error (short integer type) for the group.
85
Return Codes:
ENOT_DEF Group does not exist.
ENO_PATH Cannot send group status.
SUCCESS Status data has been returned.
chg_sta — Change Group Status

This call changes the operational status of the specified collection group.
Format: int chg_sta( group_id, chg_sgnl, chg_time)
char *group_id;
h_signl chg_sgnl;
struct H_TIME *chg_time;
where:
*group_id Pointer to a group identifier (character type data of size GPID_SIZ) for
which you want to change the status. Specify a single-user group config-
ured (owned) by the calling program or a multiple-user group.
chg_sgnl Status change signal (enumerated type): RELOAD;

REMOVE CLR_STRT; START MANL_REQ; CANCEL; STOP.
These signals and the resulting state transitions are described in Table 10-3, Table 10-4, and
Table 10-5.
*chg_time Pointer to a data structure containing the time you want the group
status to change (used only for CLR_STRT and START signals). If you
pass a null pointer, the current time is used. Elements (unsigned character
type) of this data structure are:
year(19__) hour(0 to 23)
month(1 to 12) min(0 to 59)
day(1 to 31) sec(0 to 59)
Return Codes:
EBAD_REQ Request is not valid.
EBAD_SIG Status change signal is not valid.
EBAD_STA Signal not allowed for current status.
ENO_PATH Local routines cannot generate a response or send the group status within
10 seconds.
ENOT_DEF Specified group or group members do not exist.
SUCCESS Operational status of the specified group has been changed.
86
Direct Storage of User Data

You can add data values from your application programs directly to a specified reduction group in
the Historian database. To do this, use Historian functions:
req_add — request add data
add_data — add data
req_add initializes the process of entering data from user programs into the reduction group data-
base. add_data transfers data from user programs to the reduction group database.
These functions allow you to collect and manipulate data values directly while using the
Historian to automatically reduce, retrieve, and archive the data. They also allow you to reduce
data directly while using the Historian to automatically retrieve and archive the data.
req_add — Request Data Add

This call enables you to enter data reduced by you into the reduction group database. req_add
returns information that you need to send reduced data via subsequent calls to add_dat.
Format: int req_add( group_id, oper, query)
char *group_id;
struct R_OPER *oper;
struct DBQ_DAT *query;
where:

GPID_SIZ) to which you want to send reduced data. Specify a single-user
group configured (owned) by the calling program or a
multiple-user group.
*oper Pointer to a list of R_OPER data structures (last one contains null data)
required for entering reduced data into the database. Elements of this
structure are:
op_code Reduction operation (enumerated type) that you used to reduce the data
you are supplying: SUM; AVG; MAX; MIN; STDV; KURT; HIST;
USER; NULL_OP.
Only specify operations configured for the group. Use NULL_OP for the op_code of the last data
structure in the list.
where your reduced data is to be stored.
src_name Not used.
value_1 Not used.
value_2 Not used.
status Not used.
87
*query Pointer to a data structure used for returning information required for
subsequent add_dat calls. Elements of this data structure are:
*alias Pointer to an alias (character type data of size ALIA_SIZ) for the buffer
where you place your reduced data. req_add creates the alias.
*buffer Pointer to a buffer (character type) where you place your reduced data.
You transfer data in the buffer to the reduction group database via
add_dat calls.
buf_size The size (short integer) of the buffer where you place your reduced data.
rec_size The record size (short integer) you use for placing your reduced data in
the buffer.
NOTE
1. req_add moves the operation names contained within the R_OPER structure and
the alias to the allocated (or default) buffer.
2. req_add inserts the EBAD_OPER error code in the status field of each R_OPER
structure it receives with an error.
3. req_add creates a data buffer of the size required by the request (up to
1024 bytes). When available memory space is not sufficient, req_add uses a default
buffer of 128 bytes.
Return Codes:
E_INFRMX Cannot access data. INFORMIX error is returned in int errno. You may
not have selected the database via db_init function. INFORMIX error
codes are listed in Real-Time Database Manager:
INFORMIX-SQL Relational Database Management System Version 1.10
(B0193BT).
EBAD_DAT Error in received R_OPER structure data. Status field of each R_OPER
structure in error contains the EBAD_OPER code.
ENO_PATH Cannot send buffer to database manager.
ENO_ROOM Buffer cannot contain all the operation identifiers.
SUCCESS Buffer has been created and sent to the database manager, and buffer
information required for add_dat calls has been returned.
88
add_dat — Add Data

This call transfers user-reduced data from a buffer to the reduction group database. You send user
data records to a storage buffer created by a prior call to req_add.
Format: int add_dat (query)
where:
*query Pointer to a data structure created by a prior call to req_add. This struc-
ture contains information required to transfer user-reduced data from a
buffer to the reduction group database. Elements of this data structure are:
*alias Pointer to an alias (character type data of size ALIA_SIZ) for the buffer
where you placed your reduced data.
*buffer Pointer to the buffer (character type) where you placed your reduced data.
buf_size The size (short integer) of the buffer (up to 1024 bytes) where you placed
your reduced data.
rec_size The record size (short integer) that you used for placing your reduced data
in the buffer. Each record consists of:
♦ Monotonic time count (short integer type). This counter is incre-
mented each time the current system time is reset.
♦ Time tag (long integer type). This is the current VENIX™
system time.
♦ Point identifier key (short integer type).
♦ Point status tag (unsigned short integer type); optional use.
♦ Point values (floating-point type); includes one value for each user
reduction operation specified by req_add call.
NOTE
1. Call get_dtime to obtain the current system time and monotonic time count (see
Object Manager Calls (B0193BC)).
2. Move the date and time returned by get_dtime to the h_time structure and call
get_gmt to convert the h_time structure to VENIX system time.
3. Call get_key to obtain the keys for existing point identifiers.
4. add_dat uses the alias to communicate with a Historian server process. It trans-
fers your data value records from the buffer to the database.
5. Use add_dat in a loop, sending one buffer of data for each set of user variables.
6. Use zero for the identifier key in the last record of the last buffer you send via
add_dat.
7. When add_dat receives a zero identifier key, it destroys the alias; it is not available
for future add_dat calls. If you want to re-establish data entry to the reduction data-
base, you must call req_add again.
Return Codes:
89
ENO_PATH Cannot communicate with the database manager.
SUCCESS User-reduced data has been transferred to the reduction group database.
get_gmt — Get Greenwich Mean Time

This call converts the time you supply into equivalent Greenwich Mean Time (GMT) value that
is returned as the value of the function.
Format: long get_gmt (h_time)
struct H_TIME *h_time;
where:
*h_time Pointer to a data structure containing the time you want to convert to
GMT. Elements (unsigned character type) of this data structure are:
year(19__) hour(0 to 23)
month(1 to 12) min(0 to 59)
day(1 to 31) sec(0 to 59)
NOTE
1. GMT values (VENIX time) are required for time tags in data records that you are
passing to the Historian for storage in a database.
2. If you cannot use the VENIX time (2) function to get the current VENIX time
for your system, call get_gmt to convert your time to a GMT value.
3. You can use get_gmt for time conversion when you want direct access to the His-
torian database, which is required for retrieval of messages and allowed for retrieval
of other data classes.
Return Codes: (none)
90
11. Data Retrieval Calls
This chapter contains information on using data retrieval calls.
The Historian supports the following data access functions:
To retrieve archive data from a storage medium, restore the archive database via the Historian
archiving displays, then, use the data retrieval calls.
An application program that includes one or more valid header files (hstorian.h, histuser.h, or
hist_err.h), and that has been linked to the libhist.a library can use the data retrieval calls.
The header files are included with the I/A Series Historian software. This file contains error codes
and the size of data types used in the configuration calls, as well as data structures and elements
reserved for future use. User applications that call these subroutines must include the header files.
The user calls rq_pt and get_pt only access data from AP20 Historians. Use these calls in AP20
platform user programs only. Use the get_data call, which is available on both AP20 and
AP50/51 platforms, as a replacement.
Table 11-1 lists the data retrieval function calls.
Table 11-1. Data Retrieval Calls
Call Function
db_dlet (domain) Removes a database domain created by the Archive Restore
function.
db_init (domain) Selects a database domain for subsequent Historian calls.
get_keys (names, keys) Provides a point identifier key for each supplied point identifier.
get_nam (keys, names) Provides a point identifier for each supplied point identifier key.
get_val (query) Retrieves database records from the database manager initialized
by a prior call to rq_oval.
rq_oval (o_req, query) Initializes the database manager for accessing reduction group
database.
get_data Provides sample, reduced, MDE, or archived data for the
(args, option, bufpt, done) specified collection point name.
rq_pt (rqs_info, query) Issues a request for sample, reduced, MDE, or archive data to the
Historian server executable hist_srv via Interprocess
Communications (IPC).
get_pt (query) Retrieves data requested in the last call to rq_pt.
mde_asmp Adds, modifies, or deletes an MDE sample.
(flags, grp, pt, pno, sample)
91
B0193BL – Rev L 11. Data Retrieval Calls
Table 11-1. Data Retrieval Calls (Continued)
Call Function
mde_rsmp Reads MDE samples.
(flags, grp, pt, offset, oldtime,
endtime, tot_pts, sbuf )
The Historian does not provide message retrieval functions. Use INFORMIX-SQL or Perform to
retrieve messages.
Using rq_oval and get_val to Retrieve Reduced Data

To retrieve data from the reduction group database using rq_oval and get_val:
1. Call db_init to select the Historian database domain from which you want to retrieve
data.
2. Call get_mem to get a list of member points for the reduction group (non-cascaded).
3. Call get_key to get a list of point identifier keys for the points you want.
4. Call rq_oval to initialize the database manager and create a buffer for retrieving
reduced data. You pass the group identifier, reduction operations, point identifier
keys, and time span via rq_oval.
5. Make repeated calls to get_val to receive buffer loads (one per call) of reduced data.
NOTE
After calling rq_oval, call get_val in a loop until all the data is retrieved from the
buffer. Do not issue any other Historian library call until get_val retrieves all the
data.
The Historian returns an error message only when it cannot find a collection group or when the
collection group is not compatible with the request. It returns value records for nonexistent
points; the data value is undefined and the status tag indicates that the data is unavailable.
Retrieval of data from a reduction group requires several seconds to several minutes, depending on
the number of records returned.
When making calls to get_val, get_key, or get_nam, release the buffer when you are through
with it. The following pseudo code fragment shows a typical calling sequence:
cc = rq_oval ( ... );
buf_size = query.buf_size;
while end of data not detected
{
cc = get_val ( ... );
}
if (buf_size > 128)
free (query.buffer);
Because the buffer size is zeroed on the last buffer, user applications must save it outside the
get_val loop.
92
11. Data Retrieval Calls B0193BL – Rev L
Using rq_pt and get_pt to Retrieve Data on AP20

To retrieve sample, reduced, MDE, and archive data using rq_pt and get_pt:
1. Call db_init to select the Historian database domain from which you want to retrieve
data.
2. Call rq_pt to request data from hist_svr and create a buffer for retrieving the data.
3. Make repeated calls to get_pt to receive buffer loads (one per call) of data.
NOTE
After calling rq_pt, call get_pt in a loop until all the data is retrieved from the
buffer. You should not issue any other Historian library call until get_pt retrieves all
the data.
When making calls to get_pt, release the buffer when you are through with it. The following
pseudo code fragment shows a typical calling sequence:
loop through C:B.P in list
{
rq_pt()
loop until query.buf_size == 0

{
get_pt()
}
free (query.buffer)
}
Using get_data to Retrieve Data

To retrieve sample, reduced, MDE, and archive data using get_data:
1. Call db_init to select the Historian domain (six-characters) from which you wish to
retrieve data. This call may be made in the program any time prior to using the
get_data call.
2. Create a 1200 byte character array buffer into which the get_data call may place the
retrieved data.
3. Establish a done flag of type short that notifies the calling process that the data request
has completed. Pass the address of the done flag as an argument to the get_data call.
4. Fill in the fields of the struct DATA_RQS with appropriate information for your
request.
5. Fill in the option argument if data is to be retrieved from an archived or restored data-
base.
6. Make repeated calls to get_data to receive up to 100 data records of struct DREC
(histuser.h) per call in the user buffer. The return value from the get_data call con-
tains either a negative error code (hstorian.h or hist_err.h) or the number of data
records that have been returned and placed in the user buffer (0 to 100). When the
done argument is nonzero, all available data has been retrieved for the request.
7. If you want to terminate the get_data request transaction before all requested data
has been returned, that is, before the done flag has been set by get_data, set the
93
option argument of the get_data call to DELETED (hstorian.h) or -1.
NOTE
Unlike the calls rq_oval and rq_pt, you own the buffer into which get_data places
the retrieved data. Therefore, the type of buffer to be used for the data (that is, static
or allocated) is up to you. If an allocated buffer is used, the freeing of the buffer is
up to your discretion. The buffer does not necessarily need to be released at the
completion of a get_data request.
The following pseudo code fragment shows a typical calling sequence:

#include <hstorian.h>
#include <histuser.h>
#include <hist_err.h>
.
.
.
main
{
struct DATA_RQS ureq;
char buffer[1200];
char mybuf[1200];
short done;
short opt;
int count;
int ret;
.
.
.
/*
* Initialization
*/
(void)memset((char *)&ureq,0,sizeof(struct DATA_RQS));

(void)memset(buffer,0,sizeof(buffer));
(void)memset(mybuf,0,sizeof(mybuf));
ret = db_init(hist01);
if(ret < 0)
{
/* error handling */
.
.
.
}
done = 0;
count = 0;
/*
* Set up the arguments to the get_data() call, i.e.
* fill in the struct DATA_RQS with the appropriate
* information and set “opt” to zero, “ARCHIVE”,
* or “PLAYBACK”.
*/
.
94
.
.
/*
* Request and process data
*/
do
{
count = get_data(&ureq, opt, buffer, &done);
if(count <= 0)
{
break;
}
(void)memcpy(mybuf,buffer, (count * sizeof(struct DREC)));

} while(!done);
.
.
.
} /* end myprog */
db_init — Database Initialization

This call selects a database domain for subsequent Historian data retrieval function calls.
Format: db_init (domain)
char *domain;
where:
*domain Pointer to an existing data_base name (character type data of size

DBNM_SIZ). Terminate this string with a null character.
Return Codes:
ENO_DB No database exists for the specified name.
SUCCESS db_init has selected the database.
rq_oval — Request Operation Values

This call enables the retrieval of data from the reduction group database. Call get_val to retrieve
the reduced data records.
Format: int rq_oval (o_req, query)
struct OPR_LST *o_req;
where:
*o_req Pointer to a buffer that has a data structure consisting of the following ele-
ments (user-supplied):
95
*grp_id Pointer to an existing reduction group identifier (character type data of

size GPID_SIZ).
*poper Pointer to a list of opr_ids (character type data of size CNAM_SIZE).

opr_id is the name of the storage column containing the reduction opera-
tion.
*pkey Pointer to a list of point identifier keys (short integer type) for the group.
Terminate this list with a null (zero) key. Call get_keys to obtain these
keys.
*span Pointer to a data structure consisting of start and finish that define the
time span for data retrieval. Start and finish are data structures consisting
of the following elements (unsigned character type):
start:
year (19__) hour (0 to 23)
month (1 to 12) min (0 to 59)
day (1 to 31) sec (0 to 59)
finish (same as start)
*query Pointer to a data structure used by get_val for returning reduced data val-
ues. Elements of this data structure are:
*alias Pointer to an alias (character type data of size ALIA_SIZ) for a buffer used
by get_val for returning data. The alias is created from the login name
and identifier of the calling program.
*buffer Pointer to a buffer (character type) used by get_val for returning data.
buf_size Size (short integer) for the buffer used by get_val for returning data.
rec_size Size (short integer) for the records used by get_val for returning data.
Each record consists of:
♦ Monotonic time count (short integer type). This counter is incre-
mented each time the current system time is reset.
♦ Time tag (long integer type). This is the current VENIX system
time.
♦ Point identifier key (short integer type).
♦ Point status tag (unsigned short integer type).
♦ Point values (floating point type): one value for each user reduc-
tion operation specified by prior call to rq_oval.
Guidelines:
3. Call get_key to obtain the keys for existing point identifiers.
96
4. rq_oval moves information contained within the OPR_LST structure and the alias to
the allocated (or default) buffer.
5. rq_oval creates a data buffer of the size required by the request (up to 1024 bytes).
When available memory space is not sufficient, rq_oval uses a default buffer of 128
bytes.
Return Codes:
ENO_PATH Buffer cannot communicate with the database manager.
ENO_ROOM Buffer cannot contain all the operation identifiers and point_id keys.
ENOT_DEF Specified group, point, or operation identifiers do not exist.
SUCCESS Buffer has been created and sent to the database manager, and buffer
information required for get_val calls has been returned.
get_val — Get Values

This call retrieves data from the reduction group database using a buffer created by a prior call to
rq_oval.
Format: int get_val (query)
where:
*query Pointer to a data structure used for returning data values. This structure
was created by a prior call to rq_oval.
Guidelines:
1. Do not confuse this call with the Object Manager call getval; they are not the same.
For more information on the Object Manager calls, see Object Manager Calls
(B0193BC).
2. get_val uses the buffer alias to communicate with the database manager. It transfers
data from the database to the buffer.
3. Use get_val in a loop, receiving one buffer of data for each set of data records
retrieved.
4. get_val sorts the values for each point in chronological order and places the sorted
list in the buffer.
5. get_val returns records for each point you request, even if data is not available. The
status tag indicates data availability (3 = OK, 131 = UNAVAIL).
6. get_val returns values for each operation requested by rq_oval; it returns a value of
MAXFLOAT for undefined reduction operations.
7. The last buffer returned contains a record with a null (zero) id_key field.
Return Codes:
ENO_PATH Buffer cannot establish communication with the database manager within
10 seconds.
97
SUCCESS Buffer of data values has been returned.
get_key — Get Keys

This call provides you with a list of point identifier keys (serial, database keys); one key for each
group member point name that you pass.
Format: int get_key (names, keys)
struct PT_ID *names;
short **keys;
where:
*names Pointer to a list of IDs (character type data of size PTID_SIZ). ID is the
name (identifier) of a group member point. Terminate this list with a null
ID.
**keys Pointer to a pointer (returned by get_keys) to an array containing the

point identifier keys (short integer type) for the point names passed by
you.
Guidelines:
1. Each point identifier key serves as the alias for all references to that point name in
other configuration and operation tables in the database.
2. The point names may contain wildcard characters that are allowed within the Infor-
mix ESQL/C SELECT statement.
3. get_keys creates a buffer structured as an array of short integers and fills it with the
requested point identifier keys. A key value of zero terminates the array.
4. When get_keys returns the ENOT_DEF code, it places a negative integer in the keys
list for each faulty point name. The absolute value of the integer indicates the position
of the faulty string within the point name (identifier) list.
Return Codes:
ENOT_DEF Buffer cannot match one or more point names with point identifier keys.
E_MEMORY Buffer cannot create buffer.
SUCCESS get_keys has returned a point identifier key for each requested point
name.
get_nam — Get Names

This call provides you with a list of point names; one for each point identifier key (serial, database
key) that you pass.
Format: int get_nam (keys, names)
short *keys;
struct PT_ID* *names;
where:
98
*keys Pointer to a buffer containing a list of point identifier keys (short integer
type).
**names Pointer to a pointer (returned by get_nam) to a list of IDs (character type

data of size PTID_SIZ) for the point identifier keys passed by you. ID is
the name (identifier) of a group member point.
Guidelines:
1. get_nam creates a buffer structured as a list of point identifiers and fills it with names
for the point identifier keys passed by the caller.
2. When get_nam returns the ENOT_DEF error code, it places a null string in the point
identifier list. The position of the null string corresponds with the position of the
faulty key within the point identifier key list.
Return Codes:
ENOT_DEF Buffer cannot match one or more point identifier keys with point names.
E_MEMORY Buffer cannot create buffer.
SUCCESS get_nam has returned a point identifier for each requested key.
db_dlet — Database Removal

This call removes a restored archive database on the local AP.
Format: int db_dlet (domain)
char *domain
where:
*domain Pointer to a database name (character type data; up to 10 characters). Use

a null character to terminate the string.
Return Codes:
ENOT_DEF Specified database does not exist.
EDB_BUSY Database is being used by another application program.
SUCCESS db_dlet has deleted the database.
rq_pt — Request Point Data

This call issues a request for sample, reduced, MDE, or archive data for one point (variable) to
Historian server hist_srv via IPC. You must include the hstorian.h, histuser.h, and
histdrs.h files in your program.
Format: int rq_pt (rqs_info, query)
struct RQS_INFO *rqs_info;
where:
99
*rqs_info Pointer to a data structure holding the request information. This structure
consists of the following elements:
datatype A short integer indicating the data type to retrieve. It can have the follow-
ing #define values:
SMP_DATA = sample data
SMP_ARCH = extended sample archive
RED_DATA = reduced data
ARC_DATA = archived reduced data
MDE_RDSMP = MDE samples
MDE_RDARC = archived MDE samples
pt_ids Point name (PT_ID structure) for which you want to retrieve data.
arch_name Archive group name (character array) for which you want to retrieve data.
grp_name Reduction group name (character array) for which you want to retrieve
data. col_name storage column name (character array) for which you want
to retrieve reduced data.
span An H_SPAN structure consisting of start and finish that define the
time span for data retrieval. Start and finish are H_TIME structures con-
sisting of the following elements (unsigned character type):
start:
year (19__) hour (0 to 23)
month (1 to 12) min (0 to 59)
day (1 to 31) sec (0 to 59)
The start and finish times are always in chronological order, regardless of
the direction of data retrieval. For example, to retrieve data from 2:00 to
1:00, then start = 1:00 and finish = 2:00).
numpts Number of points (integer) requested.
direct Direction (short integer) for retrieving data. It can have the following
#define values:
FORWARD
BACKWARD.
*query Pointer to the data structure where data is returned. Elements of this data
structure are:
alias Alias that is used for this request. This routine fills in the alias.
*buffer Pointer to the buffer where data is returned. This routine assigns the
pointer and allocates the buffer.
buf_size Size of allocated buffer. This routine assigns the buffer size.
rec_size Size of each data record in the allocated buffer. This routine assigns the
record size.
100
Guidelines:
Return Codes:
0 No error.
NO_DB No historian name supplied.
ENO_DBNM No server alias found.
EBAD_IPC IPC error.
ENO_ROOM Out of memory.
EBAD_TYP Invalid data type.
EBAD_ARG Invalid database name.
get_pt — Get Point Data

This call retrieves the data requested in the last call to rq_pt. You must include the hstorian.h
and histuser.h files in you program. You should call get_pt in a loop until all response messages
are retrieved.
Format: int get_pt (query)
where:
*query Pointer to the data structure where data is returned. Elements of this data
structure are:
alias Alias that is used for this request. A previous call to rq_pt filled in the
alias.
*buffer Pointer to the buffer where data is returned as DTREC structures. A pre-
vious call to rq_pt assigned the pointer and allocated the buffer. The
DTREC structure consists of the following elements:
Point value (floating point).
Time tag (long integer). This is the current VENIX system time.
Point status tag (short integer).
buf_size Size of allocated buffer. A previous call to rq_pt assigned the buffer size.
rec_size Size of each data record in the allocated buffer. This routine returns the
record size.
Guidelines:
1. Call get_pt in a loop until all the data is retrieved from the buffer. You should not
issue any other Historian library call until get_pt retrieves all the data.
101
2. When buf_size = 0, the buffer contains the last set of data. If get_pt() is called
again, an error occurs.
3. get_pt returns records for the point, even if data is not available. The status tag indi-
cates data availability (3 = OK, 131 = UNAVAIL).
4. When you are through with the buffer, free it.
Return Codes:
0 No error.
EBAD_IPC IPC error.
EBAD_DAT Bad response from server.
EBAD_ARG Invalid database name.

Any error returned by server.
get_data — Get Point Data

The libhist.a get_data call allows you to retrieve sample, reduced, or manual data for one vari-
able at a time from either the main database of the selected Historian or an archived or restored
database of a selected Historian. The request for data may be either for a time span or a number of
data records.
The get_data call issues an IPC request for data records to the Historian server hist_srv, which
resides in the same AP as the database of interest. This function exists on both the AP20 and
AP50/51 platforms and is able to retrieve data across platforms.
Prior to the get_data call being made in a user program the libhist.a function call db_init
must be made to select a Historian and perform proper initialization.
You must include the header files hstorian.h, histuser.h, and hist_err.h when using this
function call in a C program.
Format: int get_data(urqs,option,bufptr,done)
struct DATA_RQS *urqs;
short option;
char bufptr;
short *done;
where:
*urqs Pointer to the user structure which contains the request information. This
structure is defined in histuser.h and consists of the following fields:
datatype SAMPLE 1 sample data (hstorian.h)

REDUCE 2 reduction data (hstorian.h)
MDE 8 manual data (hstorian.h)
pntid Collection point name (character array).
arch_name Archive database name if applicable, otherwise zeroed out.
grp_name Reduction or MDE group name if applicable, otherwise zeroed out.
102
col_name Reduction operation (column) name if applicable, otherwise zeroed out.
start Contains the start (oldest) time in UNIX time.
finish Contains the finish (most recent) time in UNIX time.
numpts If zero, all data in the start-finish range is returned. If a positive value is
supplied, that many data records in the range are returned.
flags 0 – Data returned in presentation of oldest to newest values.

1 – Data returned in presentation of newest to oldest values.
Guidelines:
1. The start and finish times are always in chronological order regardless of selected data
presentation in the flags field.
2. Because sample data is change driven, not periodic, if the start and finish times of a
SAMPLE request do not match the time stamps of the requested data exactly, a previ-
ous and/or post data record is returned with the request.
option -1 DELETE Delete or cancel call.

If the arch_name field in the user request structure has an entry, the fol-
lowing codes apply for option.
0 Search the archive directory first, then the playback directory
for a match on the full 10-character archive database name. If
only a 6-character archive group name is supplied, only the
archive directory is searched.
3 PLAYBACK Search only the playback directory (histuser.h)
4 ARCHIVE Search only the archive directory (hstorian.h). If
the arch-name field in the user request structure is zeroed, the
main Historian database is selected.
bufptr Pointer to a 1200 byte structure supplied by the user.
done Pointer to a variable of type short that indicates that the request has com-
pleted.
Return Codes:
Positive value The number of data records returned.
EBAD_FIL -7 Unable to read file.
EBAD_IPC -8 IPC error.
EBAD_OPN -9 Unable to open file.
EBAD_TYP -14 Invalid data type.
ENO_ARCH -22 Bad archive name supplied.
ENO_DB -23 No historian name supplied.
ENO_DBNM -24 Bad database name supplied.
EBAD_PNT -38 Bad point name supplied.
EBAD_GRP -39 Bad group name supplied.
103
EBAD_TIM -41 Request is for data older than file.

ENO_DATA -42 No data in the requested span.
mde_asmp — Add/Modify/Delete MDE Sample

This allows you to add, modify, or delete an MDE sample.
Format: erc = mde_asmp (flags, grp_id, pnt_id, pntno, sample);
where:
flags Bits 0-1:

0 = (NA)
1 = ADD a sample.
2 = DELETE a sample.
3 = MODIFY a sample.
grp_id Group name. If the group name is supplied, the change is made only in
that group’s data file. If grp_id[0] = 0, the member file is searched for
pnt_id, and the change is made in all groups of which the point is a mem-
ber.
pnt_id Point name, ignored if pntno non-zero.
pntno Point number. If zero, pnt_id is used to look up the point number in the
mde_points file.
struct (TRNDREC*) sample

Sample record
value Floating-point sample value.
time Time stamp of sample. In Delete and Modify mode, a sample record is
identified by its point number (or, indirectly, point name) and its time
stamp. Within a group, a point cannot have two sample records with the
same time stamp. A sample’s time stamp cannot be modified. If a time
stamp needs to be changed, the sample must be deleted (identified by its
old time stamp) and re-added with the new time stamp.
status Sample status word. The sample value and the status word are not used in
Delete mode. In Modify mode, they overwrite the existing data.
In Add mode, the sample is added to all applicable group data files. Before the new sample is
added, the oldest sample for the point is deleted if it is older than the configured data retention
time span. It is not useful to delete more than one record for each newly added sample, since the
file does not actually shrink when a record is deleted.
In Modify mode, the sample record matching the point number and time stamp is rewritten with
the new data in all applicable group data files.
In both Add and Modify modes, the request is rejected if data validation is configured and the
data value is out of range.
104
In Delete mode, the sample record matching the point number and time stamp is deleted from all
applicable group data files.
Return Codes:
E_SDFCRE -161 Cannot create sample data file.
E_RANGE -173 Value out of range.
mde_rsmp — Read MDE Samples

This call reads MDE samples.
Format: mde_rsmp (flags,group,pnt_id,offset,oldtime,endtime,tot_pts,sbuf);
where:
flags Bit 0:
0 = ascending order (= FORWARD),
1 = descending order (= BACKWARD).
Bits 1-2:
0 = start after oldtime (FORWARD), or before endtime (BACKWARD).
1 = start at or just after oldtime (FORWARD), at or just before
endtime (BACKWARD).
2 = start at or just before oldtime (FORW.), at or just after endtime
(BACKWARD).
3 = start just before oldtime (FORWARD), just after endtime
(BACKWARD).
In either direction, 3 is the most inclusive, 0 is the least inclusive mode. In
all modes, the last sample returned either has the exact time stamp
requested, or the nearest one beyond that time, such that the requested
time span is entirely embraced in the returned samples.
struct (TRNDREC*) sbuf

Pointer to a buffer big enough to contain the expected number of sample
records, even if internally obtained by more than one response message.
Tot_pts should match the available buffer size to prevent buffer overflow.
For struct TRNDREC, see function mde_asmp().
group Group name.
pnt_id Point name. Not used if “offset” is nonzero. If the point number is known
to the user, it should be used to reduce disk access.
105
offset Point number. If zero, pnt_id is used to look up the point number in the
mde_points file.
oldtime Lower limit of the requested time span. If 0L, the top of file is used as a
default.
endtime Higher limit of the requested time span. If 0L, the end of file is used as a
default.
tot_pts Maximum number of samples to return. The buffer sbuf must be sized
accordingly.
Return Codes:
0 Number of samples actually returned to sbuf.
0 No data matching requested range.
NO_DATA -13 No group, point, member or sample (in given range)
E_NOSDF4 -158 No entry for sample data file in sysindexes.
E_NOSDF0 -159 Sample data file not found.
106
12. Writing Historian Reports
This chapter contains information on writing Historian reports, including the INFORMIX-
ACE Report Writer and I/A Series Spreadsheet.
You can use the INFORMIX-ACE Report Writer to generate reports containing the values of
process variables collected and reduced by the Historian. On the AP20, use the I/A Series spread-
sheet to generate Historian data reports. The following sections briefly describe how to use these
packages to write the report. Also provided in this section are some simple examples.
For further details on the ACE Report Writer refer to:
♦ INFORMIX-SQL Version 4.10 Reference Manual (documentation for 50 Series
workstations)
♦ Real-Time Database Manager: INFORMIX-SQL Relational Database Management Sys-
tem Version 1.10 (B0193BT) for AP20 workstations
For details on the spreadsheet for the AP20, refer to Spreadsheet (B0193BM).
Historian Database Tables

This section briefly describes the contents of the tables in the Historian (INFORMIX) database.
On the 50 Series, the Historian database is not part of the UNIX file system. On the AP20, the
Historian database is a subdirectory of /usr/fox/hstorian/bin, and its UNIX name is the Histo-
rian name with a .dbs extension. Table 12-1 and Table 12-2 are examples of the all_points and
reduction group tables.
Table 12-1. Example of all_points Database Table
all_points
id pkey
TANK1_COMP:LEVEL_MEAS.PNT 1
GLOBAL_VARIABLE_NAME_EXAMPLE_001 2
COMPOUND_002:BLOCK_003.PARM_1 3
Table 12-2. Example of Reduction Group Database Table
1 601917197 1 3 49.79 49.79

1 601917197 3 3 5.00 5.00
1 601916897 2 3 4.95 4.95
1 601916897 1 3 49.79 49.79
1 601917897 3 3 5.00 5.00
1 601917197 2 3 4.95 4.95
1 601916597 3 3 5.00 5.00
1 601916597 1 3 49.79 49.79
107
B0193BL – Rev L 12. Writing Historian Reports
Table 12-2. Example of Reduction Group Database Table (Continued)
1 601916597 2 3 4.95 4.95
Definitions for the most frequently used Historian database tables follow.
all_groups Table
The all_groups table contains a record for each configured reduction, MDE, archive and message
group in the Historian. Table 12-3 defines this table.
Table 12-3. all_groups Table Definition
Column Name Data Type Description

id char(10) Group name.
gtyp smallint Group Type:
2 - reduction
4 - reduction archive
5 - message
7 - sample archive
8 - MDE
owner char(8) Owner name. Many groups are owned by historian, others by root.
gkey smallint Archive group index.
all_points Table
The all_points table contains a record for each sample collection point for which data is being col-
lected. Table 12-4 defines this table.
Table 12-4. all_points Table Definition

id char(32) Collection point name. Either a global or a process control
variable C:B.P.
pkey serial Unique point identifier key assigned to collection points.
reduc_cfg Table
The reduc_cfg table contains a record for each configured reduction group. Each record contains
the configuration data needed for the group. Table 12-5 defines this table.
Table 12-5. reduc_cfg Table Definition

id char(10) Reduction group name.
description char(32) Description parameter for the reduction group.
108
12. Writing Historian Reports B0193BL – Rev L
Table 12-5. reduc_cfg Table Definition (Continued)

usage smallint Group initial state flag:
0 - OFF
1 - ON
2 - AUTO (Reserved for future use)
config_stat smallint Configuration status (for internal use only):
0 - no change
1 - configuration change
2 - member change
4 - operation change
period smallint Reduction period, that is, time period for scheduling the
execution of data reduction operations for the group.
per_factor smallint Unit of time for period:
1 - Seconds
60 - Minutes
3600 - Hours
delay smallint Phasing delay for leveling the data reduction processing load on
the Historian.
del_factor smallint Unit of time for delay:
1 - Seconds
60 - Minutes
3600 - Hours
time_span smallint Time span for the data to be included in the reduction process
(for cascaded groups only).
time_factor smallint Unit of time for time_span:
1 - Seconds
60 - Minutes
3600 - Hours
min_span smallint Minimum time span required for reducing the data when some
of the input is unavailable.
min_factor smallint Unit of time for min_span:
1 - Seconds
60 - Minutes
3600 - Hours
max_span smallint Data retention time span.
max_factor smallint Unit of time for max_span:
1 - Seconds
60 - Minutes
3600 - Hours
smpl_period smallint Data sampling period. A value of 0 identifies a cascaded
reduction group.
109
Table 12-5. reduc_cfg Table Definition (Continued)

smpl_factor smallint Unit of time for smpl_period:
1 - Seconds
60 - Minutes
3600 - Hours
vbufsiz smallint Buffer size (for internal use).
user_task char(64) Task name for a user-defined reduction process.
arch_cfg Table
The arch_cfg table contains a record for each configured archive group. Each record contains the
configuration data needed for the group. Table 12-6 defines this table.
Table 12-6. arch_cfg Table Definition

id char(10) Archive group name.
gkey serial Archive group index.
description char(32) Description parameter for the archive group.
0 - OFF
1 - ON
2 - AUTO (reserved for future use)
config_stat smallint Configuration status (for internal use).
period smallint Archive period, that is, time period for scheduling the
execution of archiving operations for the group.
per_factor smallint Unit of time for period:
1 - Seconds
60 - Minutes
3600 - Hours
delay smallint Phasing delay for leveling the archive process load on the
Historian.
del_factor smallint Unit of time for delay:
1 - Seconds
60 - Minutes
3600 - Hours
time_span smallint Time span for retaining historical data for the group.
span_factor smallint Unit of time for time_span:
1 - Seconds
60 - Minutes
3600 - Hours
grp_type smallint Archive group type:
0 - reduction or message group
1 - sample data
110
Table 12-6. arch_cfg Table Definition (Continued)

medium smallint Medium of storage:
0 - floppy disk
1 - stream tape
volume_id char(14) Archive volume name.
messag_cfg Table
The messag_cfg table contains a record for each configured message group. Each record contains
the configuration data needed for the group. Table 12-7 defines this table.
Table 12-7. messag_cfg Table Definition

id char(10) Message group name.
description char(32) Description parameter for the message group.
0 - OFF
1 - ON
2 - AUTO (Reserved for future use)
config_stat smallint Configuration status (for internal use only).
max_msgs smallint Maximum number of messages which can be stored.
policy smallint Archive policy when the maximum number of messages is reached.
0 - null
1 - save
2 - overwrite
3 - reject
pnt_memb Table
The pnt_memb table contains a record for each sample collection point that is a member of a
reduction group. Table 12-8 defines this table.
Table 12-8. pnt_memb Table Definition

owner_id char(10) Reduction group name of which the point is a member.
id_key smallint Point identifier key associated with the member point.
description char(32) Description parameter for the member point.
chg_delta smallfloat Currently not used.
grp_memb Table
The grp_memb table contains a record for each group which is a member of another group.
Reduction groups can be members of either another reduction group (that is, cascaded reduction
111
group) or an archive group. Message groups can only be members of archive groups. Archive
groups cannot be members of other groups. Table 12-9 defines the grp_memb table.
Table 12-9. grp_memb Table Definition

owner_id char(10) Reduction or archive group name to which the member group
belongs.
member_id char(10) Name of the member group.
time_span smallint Currently not used.
span_factor smallint Currently not used.
reduc_op Table
The reduc_op table contains a record for each reduction operation defined in the database. This
table is a cross section of the operations for all reduction groups. Table 12-10 defines this table.
Table 12-10. reduc_op Table Definition

owner_id char(10) Reduction group name containing the operation.
op_code smallint Operation code:
0 - null
1 - user defined operation
2 - summation
3 - average
4 - maximum
5 - minimum
6 - standard deviation
7 - kurtosis
8 - histogram
col_name char(18) Name of the storage column where the reduces data is to be stored.
src_name char(18) Name of the source column for the data to be reduced (for
cascaded reduction groups only).
value_1 smallfloat Histogram bin low range value.
value_2 smallfloat Histogram bin high range value.
tnd_memb Table
The tnd_memb table contains a record for each sample collection point. The actual values for
trending are not stored in the INFORMIX database.
On an AP20, the most recent 200 samples for each point are stored in
/usr/fox/hstorian/bin/__tdata. Extended samples are stored in
/u0/sam/<dbname>/SAM001...SAM500.
On the 50 Series, the samples are stored in
/opt/fox/hstorian/bin/samples/SAM0001...SAM2000.
112
The number in the SAM file names corresponds to indx in the tnd_memb table.
Table 12-11 defines the tnd_memb table.
Table 12-11. tnd_memb Table Definition

id char(32) Collection point name. Either a global or a process control
variable C:B.P.
description char(32) Description parameter.
chg_delta smallfloat The change deadband.
indx smallint Point number (this is also the point’s SAM file number).
rate smallint Collection rate in seconds.
new_member smallint Configuration status (for internal use).
max_rec smallint (AP20) Maximum number of extended sample points/100 (that is,
long (AP50/51) 992 maximum for AP20; 999,990 for AP50/51).
arch_sets Table
The arch_sets table contains a record for each time the database is archived. The name of the
archive database can be derived from the data in this table. Table 12-12 defines this table.
Table 12-12. arch_sets Table Definition

seq smallint Monotonic time count.
time_tag integer VENIX time.
id char(10) Configured group name.
aset smallint Count of the number of archive sets created.
dbname char(10) Full database pathname without the .dbs extension.
filename char(14) Not used.
status char(1) Not used.
messages Table
The messages table contains a record for each message available in the database. Table 12-13
defines this table.
Table 12-13. messages Table Definition

format_name char(10) Name of the message format (for example, sysmonmsg or opraction).
id char(32) Message tag.
station char(8) Station logical name.
time_tag integer VENIX time when the message was recorded in the database.
113
Table 12-13. messages Table Definition (Continued)

mono_count smallint Monotonic time count (number of times System Management time
has been set).
0 - never set
1 - set once
etc.
arch_status char(1) Status of Message:
(blank) - not archived
A - archived
msg_key integer Message ID key. This is unique within a particular message format.
sysmonmsg Table
The sysmonmsg table contains a record for each system alarm message. Table 12-14 defines this
table.
Table 12-14. sysmonmsg Table Definition

msg_key serial Unique message ID key.
time_tag char(20) Converted time/date when the message was recorded.
valid_time smallint Flag indicating whether or not time is OK.
mono_count smallint Monotonic time count (number of times System Management
time has been set):
0 - never set
1 - set once
etc.
seq_no smallint Sequence number.
priority smallint Message priority.
msg_name char(10) Message tag.
smon_name char(8) System monitor name.
src_name char(26) Name of the process that generated the message.
text char(80) Message text.
opraction Table
The opraction table contains a record for each operator action recorded by the Operator Action
Journal software. Table 12-15 defines this table.
Table 12-15. opraction Table Definition

msg_key serial Unique message ID key.
114
Table 12-15. opraction Table Definition (Continued)

act_type char(3) Action type:
E - change environment
A - application
S - script
M - manual change
O - compound on/off
* - all other message types
time_tag char(20) Converted time/date when the message was recorded.
compound char(14) Depends on value of act_type. If act_type:
E - CHG ENV
A - APPLIC
S - SCRIPT
M - compound name
O - compound name
block char(14) Depends on value of act_type. If act_type:
E-b
A-b
S-b
M - Block name or b for a compound parameter
O - Block name or b for a compound parameter
parm char(8) Depends on value of act_type If act_type:
E-p
A-p
S-p
M - parameter name
O - parameter name
description char(64) Description of the operator action.
Reduction Group Table

The reduction_group_name table takes on the name of the reduction group. This table is created
whenever a reduction group is configured in the Historian. Each reduction group table consists of
four standard columns and one or more custom columns. The custom columns are the storage
column names you specify when configuring operations for the reduction group. Table 12-16
defines the reduction_group_name table.
Table 12-16. reduction_group_name Table Definition

seq smallint Monotonic time count (number of times System Management
time has been set):
0 - never set
1 - set once
etc.
115
Table 12-16. reduction_group_name Table Definition (Continued)

time_tag integer VENIX time when the value was recorded in the database.
pt_id_key smallint Unique point identifier key assigned to collection point.
status_tag smallint Status of the data:
3 - OK
131 - not available
oper1_col smallfloat Used for storing the reduced data associated with the configured
operation.
oper2_col smallfloat Used for storing the reduced data associated with the configured
operation.
Report Writing Using INFORMIX-ACE Report Writer

All ACE report specification files created with INFORMIX on the AP20 are compilable and exe-
cutable on the 50 Series.
The paths to the Historian and INFORMIX files are:
AP20 50 Series
----------------- -----------------
/usr/fox/hstorian /opt/fox/hstorian
/usr/informix /opt/informix
The following sections use the AP20 path. To write reports on the 50 Series, substitute the appro-
priate paths.
Basic ACE Report Specification Structure

The following is a description of the sections in a report specification. The words in bold are key
words that are required in each report. The comments, enclosed in curly braces {}, describe each
section.
DATABASE
{
This section specifies the database to be used by this
report. Only one name can be specified per report
specification.
}
END
DEFINE
{
This section allows you to declare variables and user
defined C functions that you will be using in the report and
the parameters that the report can accept from the command line.
}
END
INPUT
{
This section allows you to produce an interactive report
by prompting the user and accepting input while the
report is running.
}
116
END
OUTPUT
{
This section allows you to direct the output of the
report to the screen, printer, file or a VENIX command.
It also allows you to control the page margins and
length.
}
END
SELECT
{
This section specifies the actual data to be extracted
from the database and used in the report.
}
END
FORMAT
{
This section is used to control the layout of the
report. You can use the variables, parameters and
columns defined/selected earlier in calculations. You
can also call C functions from here.
}
END
Report Specification File Sections

Within each section of the report specification, there are statements that accomplish the purpose
of that section. The following table summarizes some of the available statements for each section.
These statements are explained by the comments. Refer to Real-Time Database
Manager: INFORMIX-SQL Relational Database Management System Version 1.10 (B0193BT) for
a complete list of options for statements available in ACE.
NOTE
Key words are in uppercase and user entries are in lowercase.
DATABASE
database name
END
DEFINE { num - specifies the position of }
PARAM [num] vname type { the argument in the command line }
VARIABLE vname type { vname - the name assigned by the }
END { user to the parameter or variable
type - available types are DATE,
CHAR(length), DECIMAL, FLOAT,
INTEGER, SMALLINTEGER, SMALLFLOAT,
MONEY }
INPUT
PROMPT FOR vname USING “message”
END
OUTPUT { You may only have one REPORT TO }
REPORT TO “filename” { statement in a report }
REPORT TO PIPE “program” { specification. If you leave it }
REPORT TO PRINTER { out, then the report will be sent}
LEFT MARGIN n { to the terminal. You can set as }
RIGHT MARGIN n { many of the margins as you wish.}
TOP MARGIN n {Default settings are: }
BOTTOM MARGIN n { left margin - 5 spaces }
PAGE LENGTH n { right margin - 132 characters
END top margin - 3 lines
117
bottom margin - 3 lines

page length - 66 lines
++ (includes top and bottom margins)}
SELECT
column name(s) or *
FROM table name(s)
WHERE join condition AND/OR comparison clause
ORDER BY column name(s)
{
The column names are a comma separated list, or an asterisk
can be specified to get all the columns in the specified
tables. The column names have to be unambiguous. Therefore,
if a couple or more tables have the same column name, the
table name is prefixed to the column name, i.e.,
tablename.columnname.
The table names are also a comma separated list. Both the
table names and column names can be assigned a unique id, a
display label, for future reference. For example:
SELECT
one.col_one col1,
one.col_two col2
FROM table_one one
END
The WHERE clause is used to specify the search criteria,
such that only the rows that meet that criteria will be
chosen. The WHERE clause is also used to specify a join
condition, whereby a temporary composite table can be
formed from two or more of the previously specified tables,
based on the relationship between the column(s) in each
table. The temporary table is the cross product of each
table. Thus, the performance of the report writer falls
exponentially as the sizes of the joined tables increase.
Therefore, it is advisable to configure a reduction group
appropriately and minimize on joining tables.
The ORDER BY clause is used to sort the qualifying rows
from the joined table, based on the specified (comma
separated list) column name(s). The column name(s) cannot
be of the form tablename.columnname. If the column name is
not unique, define a display label and use that name.
}
END
FORMAT FORMAT
EVERY ROW OR ON EVERY ROW
END ON LAST ROW
AFTER GROUP OF
BEFORE GROUP OF
FIRST PAGE HEADER
PAGE HEADER
PAGE TRAILER
END
{
The simplest FORMAT section prints every row qualified by
the SELECT section. For the more complex FORMAT section,
each statement represents a control block responsible for
the layout of a specific section of the report. Each
control block must contain at least one action to be taken,
such as PRINT, SKIP n LINES. The control blocks can be
placed in any order within the FORMAT section.
On each page of the report, the PAGE HEADER block will be
executed prior to the rest of the blocks. On the first page
only, the FIRST PAGE HEADER will be executed instead of the
PAGE HEADER. At the bottom of each page, the PAGE TRAILER
118
block will be executed.

In the body of the report, a BEFORE GROUP OF block will be
executed prior to the ON EVERY ROW block for the rows in
the specified group. When every row of data for the group
has been processed by the ON EVERY ROW block, an AFTER
GROUP OF block will be executed. After all rows have been
processed and the final AFTER GROUP OF block has been
executed, the ON LAST ROW block will be executed. When more
than one column is specified in the ORDER BY clause of the
SELECT section, there may be a set of BEFORE GROUP OF and
AFTER GROUP OF blocks for each ordered column.
}
READ STATEMENT ON AP50
ACE for INFORMIX on the AP50 supports an additional section not described in
this document:
READ statement
END
The purpose of this statement is to support the ability to incorporate non-INFORMIX data into
a report. It must be in INFORMIX unload format, that is, an ASCII file with columns separated
by delimiters, as if it were unloaded from an INFORMIX table. The read statement is just a select
statement on any data which has been converted to INFORMIX format. It is useful, for example,
for capturing real-time data which is snapshot into that format.
Syntax for the read statement is shown in INFORMIX-SQL Version 4.10 Reference Manual.
Also needed, if the read statement is used, is the ASCII statement, which tells ACE how to inter-
pret the data format in the ASCII file to be read. It goes into the define section.
Syntax for the ASCII statement is shown in INFORMIX-SQL Version 4.10 Reference Manual.
Using C Functions with ACE Report Specification

On the 50 Series, the C function support is available only with the optional program develop-
ment package. A C function is declared in the define section of the report specification, as
follows:
DEFINE
FUNCTION funcname
END
A C function call can be placed wherever a constant can be placed in an ACE
statement. The C functions are called within the FORMAT section in either of
the following ways:
CALL funcname([expression list])
funcname([expression list])
The CALL keyword is used if the C function does not return a value. The C
function call may have an argument list of one to ten expressions, separated
by commas.
Examples:
FIRST PAGE HEADER
CALL tounix(“date”)
ON EVERY ROW
PRINT lname, logarithm(salary/(today - hire_date))
The C function being used in the report specification must contain the
appropriate declarations. The following is a general structure of a C function
that includes 2 user defined functions.
#include “/usr/informix/incl/ctools.h”
/*
* On the AP50, substitute “/opt” for “/usr” in above #include
* Add other header files here, as desired.
*/
119
valueptr func1();
valueptr func2();
/*
* All functions must be of type valueptr and they must be
* declared before the ufunc structure is initialized
*/
struct ufunc userfuncs[] =
{
“myfunc1”, func1,
“myfunc2”, func2,
0,0
}
/*
* This structure is required for ACE to call these functions
* at run time. The quoted strings are the names used in the
* report specification; func1 and func2 are pointers. The two
* zeros at the end are required terminators.
*
* Other global declarations can follow
*/
valueptr func1()
{
/*
* The body of func1 goes here. func1 takes no arguments and
* returns a character string using a special macro
*/
strreturn(s, len);
}
valueptr func2(arg1,arg2)
valueptr arg1,arg2;
{
/*
* The body of func2 goes here. func2 takes 2 arguments and
* does not return any values
*/
}
All functions that you call in ACE must be declared as returning pointers to a value structure, val-
ueptr. Furthermore, all arguments of the functions must also be declared to be of type
valueptr. The following table shows the defines contained in ctools.h that can be used to detect
the data type of the argument and to get the value of the argument (arg).
Defines Description
arg->v_charp pointer to string
arg->v_len length of string
arg->v_int integer value
arg->v_long long value
arg->v_float float value
arg->v_double double value
arg->v_decimal decimal value
arg->v_type data type
arg->v_ind null indicator*
arg->v_prec datetime/interval qualifier*
* 50 Series only.
120
The data type of arg can be determined by checking arg->v_type against a series of integer con-
stants defined in ctools.h, as shown in the following table:
v_type RDSQL Type C Type
SQLCHAR CHAR char, string, or fixchar
SQLSMINT SMALLINT short
SQLINT INTEGER long
SQLFLOAT FLOAT double
SQLSMFLOAT SMALLFLOAT float
SQLDECIMAL DECIMAL dec_t
SQLSERIAL SERIAL long
SQLDATE DATE long
SQLMONEY MONEY dec_t
SQLDTIME * DATETIME dtime_t
SQLINTERVAL * INTERVAL intrvl_t
* 50 Series only.
Therefore, if arg->v_type is SQLCHAR, then the pointer to the string is available in arg->v_charp
and the number of characters in the string (length) is available in arg->v_len. The string is not
null terminated.
The following functions, provided in ctools.h, forces conversion of a valueptr argument into a C
data type of your choice:
Function Returned Type
toint() int
tolong() long
tofloat() double
todouble() double
todate() long
todecimal() dec_t
todatetime() * dtime_t
tointerval() * intrvl_t
* 50 Series only.
The above functions take a valueptr and return a value of the type indicated. The todecimal()
function takes a second argument which is a pointer to the dec_t structure. If the type conversion
is unsuccessful, the global integer toerrno is set to a negative value.
Both arguments passed in and returned values must be valueptrs. ctools.h contains the following
macros to perform a conversion for you:
Macro Type Returned

intreturn(i) returns integer i
121
Macro Type Returned

lngreturn(l) returns long l
floreturn(f ) returns float f
dubreturn(d) returns double d
strreturn(s,c) returns strings of length c (short)
decreturn(d) returns decimal d (of type dec_t)
dtimereturn(d) * returns datetime d (of type dtime_t)
invreturn(i) * returns interval i (of type intrvl_t)
50 Series only.
Generating a Report
The report specification file must be saved with a .ace extension, compiled and linked in order to
generate the report. The compiler then creates a file with a .arc extension if the compilation was
successful, or a file with a .err extension if it was unsuccessful. The .err file is a text file and it flags
the point at which the error was encountered and gives a brief explanation of the error condition.
Once the report is compiled successfully, then you can run it anytime using ACEGO, the ACE
Report Writer.
The paths to the Historian and INFORMIX files are:
AP20 50 Series
----------------- -----------------
/usr/fox/hstorian /opt/fox/hstorian
/usr/informix /opt/informix
The steps to be taken to compile and execute a report, without any C function calls, from the
VT100 mode are as follows (on the 50 Series, substitute the appropriate paths):
1. Change directory to where the database resides:
cd /usr/fox/hstorian/bin
2. Initiate the compiler by calling the script saceprep:
/usr/informix/bin/saceprep rep_file
NOTE
1. The .ace extension should not be typed in. It is assumed by the compiler to be
ACEPREP.
2. Refer to Real-Time Database Manager: INFORMIX-SQL Relational Database Man-
agement System Version 1.10 (B0193BT) and INFORMIX-SQL Version 4.10 Reference
Manual for further details on arguments that can be supplied to the saceprep script.
3. Execute the compiled report by calling the script sacego:

/usr/informix/bin/sacego rep_file
122
NOTE
1. The .arc extension should not be typed in. It is assumed by the compiler to be
ACEGO.
2. Refer to Real-Time Database Manager: INFORMIX-SQL Relational Database Man-
agement System Version 1.10 (B0193BT) and INFORMIX-SQL Version 4.10 Reference
Manual for further details on arguments that can be supplied to the sacego script.
Other than executing the report from the VT100 mode, you can also have a menu entry on a
workstation that generates the report every time it is selected. For example, if you want to have a
menu entry called Report under the SftMnt menu, then you must write two scripts.
The first one, /usr/fox/soft/Report, basically commands the display manager to call another
script (on the 50/51, terminate the last command with a space and &):
dmcmd script
applic /usr/fox/rep_exec
The second script, /usr/fox/rep_exec, actually executes the compiled report specification:
# The following environment variables have to be set
PATH=:/bin:/usr/bin:/usr/informix/bin
INFORMIXDIR=/usr/informix
DBPATH=/usr/fox/hstorian/bin
read TZ < /etc/tz
export DBPATH INFORMIXDIR PATH TZ
# Now the report is being generated
# Change directory to where the report specification resides
sacego -q rep_file
# If the report was being sent to a file - rep_file.out,
# and you want it sent to a printer, then add the following
# statement also
lp -o-t -o-e rep_file.out
On the 50/51, the /usr/fox/rep_exec script that executes the compiled report specification is as
follows:
PATH=:/bin:/usr/bin:/opt/informix/bin
INFORMIXDIR=/opt/informix
DBPATH=/opt/fox/hstorian/bin
export DBPATH INFORMIXDIR PATH
# Change directory to where the report specification resides
cd /opt/fox/hstorian/bin
sacego -s rep_file
# and you want it sent to printer LP21, then add the following
# statement also
lp -dLP21 -o-t -o-e rep_file.out
To generate a report that has C function calls in it, you need to create a custom version of sacego.
The shell script, cace, simplifies the task of compiling and linking the C program to sacego. Cace,
which resides in /usr/informix/bin, can be used as though it is the same as the standard C com-
piler/linker, cc. The syntax is as follows:
cace cprogram.[c|ec] -o custprog cc_options
123
where:
cace The shell script that creates a custom version of sacego.
cprogram The name of the C program that contains your functions.
c The extension for cprogram if it does not contain any ESQL/C

statements.
ec The extension for cprogram when there are ESQL/C statements in it.
custprog The name of the customized version of sacego.
! CAUTION
Do not enter sacego in this field. If you do, this corrupts the sacego program.
cc_options The arguments that you would like to pass to the standard cc program.
Once the compilation is successful, to generate the report you just follow the instructions for a
report specification without C function calls while substituting all instances of sacego with cust-
prog.
On the Models 50/51, space for linking C functions into the report is available only in the
optional program development package.
Examples of Report Specifications

The following sections show three examples, in increasing difficulty. The first example is a simple,
row-based, report which also includes two C function calls. The C functions and the compilation
and linking command are listed following the report specification. The second example is a more
complicated row-based report specification. The final example presents the application of two
configuration tables, a configuration entry form and a configurable ACE column-based report
specification. This report need only be built once and the rest involves configuration through a
perform screen. Each example includes sample output.
Example 1
REPORT SPECIFICATION – example1.ace
{ This report specification produces a report of a reduction group, whereby for each point the val-
ues at all time tags are reported. Alternatively, you could get the values for all points at each time
tag. The time tag is converted from VENIX time using a C function. A C function is also used to
obtain real time values for the points from the Object Manager. }
database
demo { use the name of the historian you are reporting on }
end
define
function om_get {gets the current value of points}
function date_time {converts VENIX time}
variable status char(1) {status of a process point}
variable error char(3) {indicates availability of real time value for a
process variable}
variable temp float {temporarily holds current value }
end
124
output
top margin 2
bottom margin 4
left margin 1
right margin 80
page length 66
report to “eg.out”
end
select
all_points.pkey,
all_points.id,
eg_red.time_tag,
eg_red.pt_id_key,
eg_red.status_tag,
eg_red.eg_red_avg,
eg_red.eg_red_std_dev
from all_points, eg_red
where all_points.pkey = eg_red.pt_id_key
order by id { the table is sorted by the point names }
end
format
first page header
print “-----------------------------------------------------------------
print “ SAMPLE HOURLY REPORT"
print “-----------------------------------------------------------------
skip 1 line
print “ Report run date : “, today using “mmm dd, yyyy”
print “ Report run time : “, time
skip 1 line
print “------------------------------------------------------------------”
skip 2 lines
print “ CRUDE Report”, column 62, “Page “, pageno using”<“
skip 2 lines
print “ DATE AND TIME “, column 27, “STATUS”,
column 38, “AVERAGE”, column 51, “STAND DEV”
print “-----------------------”, column 27, “------”,
column 38, “-------”, column 51, “---------”
skip 1 line
page header
print “------------------------------------------------------------------”
skip 1 line
print “ Report run date : “, today using “mmm dd yyyy”
print “ Report run time : “, time
skip 1 line
print “------------------------------------------------------------------”
skip 2 lines
print “ CRUDE Report”, column 62, “Page “, pageno using”<“
skip 2 lines
print “ DATE AND TIME “, column 27, “STATUS”,
column 38, “AVERAGE”, column 51, “STAND DEV”
print “-----------------------”, column 27, “------”,
column 38, “-------”, column 51, “---------”
skip 1 line
before group of id
skip 2 lines
print id { title each set of data with the point name }
skip 1 line
on every row
need 3 lines
if status_tag>3 then let status = “U” {status indicates unavailable }
print date_time(time_tag), column 25, status,
column 35, eg_red_avg using “######.&&”,
125
column 48, eg_red_std_dev using “#####.&&”

after group of id
skip 2 lines
let temp = om_get(id)
if temp = -1.0
then print “Current value = N/A”
else print “Current value = “, temp
skip 1 line
page trailer
skip 2 lines
print column 35, “Page “, pageno using “<“
end
C PROGRAM -- myfuncs.c
#include <ctools.h>
#include <time.h> /* required for the date_time function */
#include <stdio.h>
#include <fox/om_udef.h> /* required for the omget function */
/* declare the functions */
valueptr omget();
valueptr date_time();
/* map the functions to the names used in the report specification */
struct ufunc userfuncs[] =
{
“om_get”, omget,
“date_time”, date_time,
0, 0
};
/* The omget function calls an Object Manager function, getval, to get the
value of the point. Omget returns -1 if the Object Manager was unsuccessful
*/
valueptr omget(pointname)
valueptr pointname;
{
int length, status, err_ret;
float val, error;
length = sizeof(long);
/* Since pointname is a string, the v_charp field, which is the pointer to
the string, fulfills the first argument to getval. Refer to the Object
Manager Calls document for details on the argument list for getval
*/
err_ret = getval(pointname->v_charp, VARIABLE, 1, (char *)&val, &status,
&length);
if (err_ret != 0)
{
error = -1.0;
floreturn(error);
}
else
floreturn(val);
}
/* The date_time function calls a VENIX time conversion function to breakdown
the VENIX time into days, month, year, hour, minute and seconds. A string is
then constructed with the desired date and time format. Refer to the VENIX
User Reference Manual document for further details */
valueptr date_time(timetag)
valueptr timetag;
{
long tloc;
struct tm *convert;
char datetime[19];
/* time_tag is of type “INTEGER” in RDSQL, therefore it corresponds to “long”
in C. Thus the v_long field contains the value of the time_tag argument. Refer
126
to the table in Section 12.2.3 */

tloc = timetag->v_long;
convert = localtime(&tloc);
sprintf(datetime, “%02d/%02d/%02d %02d:%02d”, convert->tm_mon+1,
convert->tm_mday, convert->tm_year, convert->tm_hour,
convert->tm_min);
strreturn(datetime, 19);
}
COMMAND TO COMPILE AND LINK EXAMPLE1.ACE AND MYFUNCS.C
saceprep example1
/usr/informix/bin/cace myfuncs.c -o custacego -lfox -I/usr/informix/incl
COMMAND TO GENERATE REPORT
custacego example1
SAMPLE OUTPUT
-------------------------------------------------------------------------
SAMPLE HOURLY REPORT
-------------------------------------------------------------------------
Report run date : Jul 20, 1990
Report run time : 13:37:14
-------------------------------------------------------------------------
CRUDE Report Page 1
DATE AND TIME STATUS AVERAGE STAND DEV
----------------------- ------ ------- ---------
UC01_LEAD:COSINE.MEAS
05/25/90 08:43 50.58 32.05
05/25/90 09:43 50.46 32.15
05/25/90 10:43 49.91 31.65
05/25/90 11:43 50.40 31.79
05/25/90 12:43 50.46 31.70
05/29/90 15:08 52.61 33.40
05/30/90 09:22 48.94 32.78
05/30/90 10:22 52.02 32.90
05/30/90 11:22 52.02 32.90
Current value = 71.93
UC01_LEAD:COSINE.OUT
05/25/90 08:43 50.93 32.72
05/25/90 09:43 50.86 32.61
05/25/90 10:43 50.93 31.40
05/25/90 11:43 50.37 31.44
05/25/90 12:43 50.88 32.09
05/29/90 15:08 50.41 31.31
05/30/90 09:22 50.53 31.94
05/30/90 10:22 49.97 31.87
05/30/90 11:22 50.10 31.89
UC01_LEAD:COSINE.SPT
05/25/90 08:43 51.00 .00
Page 1
-------------------------------------------------------------------------
Report run date : Jul 20 1990
Report run time : 13:37:14
-------------------------------------------------------------------------
CRUDE Report Page 2
DATE AND TIME STATUS AVERAGE STAND DEV
----------------------- ------ ------- ---------
05/25/90 09:43 51.00 .00
05/25/90 10:43 51.00 .00
05/25/90 11:43 51.00 .00
05/25/90 12:43 51.00 .00
05/29/90 15:08 51.00 .00
05/30/90 09:22 51.00 .00
05/30/90 10:22 51.00 .00
127
05/30/90 11:22 51.00 .00

UC01_LEAD:RAMP_INT.MEAS
05/25/90 08:43 .00 .00
05/25/90 09:43 .00 .00
05/25/90 10:43 .00 .00
05/25/90 11:43 .00 .00
05/25/90 12:43 .00 .00
05/29/90 15:08 .00 .00
05/30/90 09:22 .00 .00
05/30/90 10:22 .00 .00
05/30/90 11:22 .00 .00
Example 2
This example produces a shift report. The following assumptions are made:
♦ The reduction group retains data for 8 hours.
♦ The shift is an 8-hour shift.
♦ No two consecutive points have the same description field in the pnt_memb table. It
is best if each point has a unique description.
♦ The reduction group has 50 points.
♦ You must run the report at the end of each shift. You also must specify the end time of
the shift on-line. The specified time is used to put up the headers and does not affect
the time tags or data retrieved from the historian.
REPORT SPECIFICATION – shift.ace
database
demo {use the name of the Historian you are reporting on}
end
define
param[1] hourarg smallint {current hour for report}
variable esc char(1) {ascii escape code}
variable currhour smallint {hour values for header}
variable hour1 smallint {hour values for header}
variable i integer {counter}
variable j integer {counter}
variable minhour integer {1=[1-24:00] 0=[0-23:00]}
variable lf char(1) {printer line feed}
variable ff char(1) {printer form feed}
variable value0 decimal {dummy data for historian bug}
variable value1 decimal {data for row format}
variable olddesc char(30)
128
end
output
PAGE LENGTH 400
BOTTOM MARGIN 5
RIGHT MARGIN 125
LEFT MARGIN 5
REPORT TO “shift.out”
end
select unique {eliminates duplicate rows in the temporary table}
owner_id,
pt_id_key,
time_tag,
description,
eg_red_avg,
id_key
from eg_red,
pnt_memb
where pt_id_key = id_key AND owner_id = “eg_red”
order by id_key, time_tag
end
format
FIRST PAGE HEADER
LET i = 1
LET j = 1
LET minhour = 0
LET esc = ASCII 27
LET lf = ASCII 10
LET ff = ASCII 12
LET currhour = hourarg - 1 {current hour sampled at 10 of.
Historian buffer eats intervening hour}
{set up time tags for the shift}
LET hour1 = currhour - 7
{Keep with the 24 hour format}
IF hour1 < minhour THEN LET hour1 = hour1 + 24
ON EVERY ROW
IF description = olddesc OR i = 1 THEN BEGIN
LET i = i + 1 { The data is collected for all eight }
LET olddesc = description { timetags and then printed out on a }
LET value9 = 0 { line. As long as the description has }
{ not changed, it is the same point and }
LET value0 = value1 { we continue reading values. }
LET value1 = value2 { Each value read is assigned to the }
LET value2 = value3 { bottom of the list while the previous }
LET value3 = value4 { value is shifted up. }
LET value4 = value5
LET value5 = value6
LET value6 = value7
LET value7 = value8
LET value8 = eg_red_avg
END
129
ELSE BEGIN
{ If a complete list of 8 values has been read for a point, then it is
printed on a line (output row). j is the count of output rows. The printing
of page headers and column headers is done based on the current output row. }
IF (j = 1 OR j = 43 OR j = 80) THEN BEGIN
PRINT ff,lf
PRINT COLUMN 25, "PLANT SHIFT REPORT";
PRINT 30 SPACES, "REQUESTED AT ", TIME
SKIP 1 LINE
PRINT DATE, COLUMN 19, "HOUR", COLUMN 29;
PRINT hour1 USING "#&", ":00", 6 SPACES;
PRINT currhour USING "#&", ":00", lf
END
IF j = 1 THEN PRINT "RAWSTOCK", lf
IF j = 9 THEN PRINT lf, 5 SPACES, "REACTOR", lf
IF j = 27 THEN PRINT lf, 5 SPACES, "BOILER", lf
IF j = 43 THEN PRINT lf, 5 SPACES, "CONDENSER", lf
PRINT olddesc CLIPPED, COLUMN 28;
PRINT value1 using "######.##", 2 SPACES;
PRINT value8 using "######.##", 1 SPACE
LET value0 = 0
LET value1 = 0
LET value2 = 0
LET value3 = 0
LET value4 = 0
LET value5 = 0
LET value6 = 0
LET value7 = 0
LET value8 = eg_red_avg
LET olddesc = description
LET value9 = 0
LET j = j + 1
END
ON LAST ROW
PRINT olddesc CLIPPED, COLUMN 28;
PRINT value8 using "######.##", 2 SPACES
PRINT ff
end
COMMAND TO COMPILE AND GENERATE REPORT

saceprep shift
130
sacego shift 17
SAMPLE OUTPUT
The following sample output is actually 132 characters wide, but spaces have been removed to
compressed the report to a width of 80 characters, which is the maximum page width for elec-
tronic documentation.
PLANT SHIFT REPORT REQUESTED AT 08:19:03
Fri Jul 27 1990 HOUR 9:00 10:00 11:00 12:00 13:00 14:00 15:00 16:00
RAWSTOCK
Description line # 1 51.00 51.00 51.00 51.00 51.00 51.00 51.00 51.00
REACTOR
Description line # 10 .00 .00 .00 .00 .00 .00 .00 .00
BOILER
CONDENSER
131
Example 3
This report allows you to configure the process variable points to be reported, the descriptive
header information about each point, and the association of data points with various reporting
groups. The best way to integrate this information with the database process information is to
capture the format information in a relational table also.
Therefore, two new tables are added for this report: a logging group table and a logging point
table. The logging group table is a master table which defines the group name and the number of
columns allowed in that group. The logging point table is a detail table which defines the report
column number, the point name, the data representation format, and up to three lines of header
information, for each entry in the logging group table. You must have configuration data screens
to enter data into the logging tables.
The logging tables, whose rows are in the selection criteria, define the arrangement of process vari-
able reduction data. The first select statement just extracts the unique Historian time tags and
holds them in a temporary table. The second select statement is there to help simplify the overall
select code. It could have been combined with the third select statement, which outputs the final
Historian information. Comments within the report specification describe the select statements
in further detail. The let statement is used to format the data in a character buffer, exactly as it
would be printed to output.
CONFIGURATION TABLES SPECIFICATION (COMMAND FILE) – colrep.sql
database demo; {use the name of the Historian you are reporting on}
create table log_groups
(
grp_number serial(1),
grp_name char(80),
max_columns smallint
);
create table log_points
(
log_grp integer,
log_column integer,
pt_name char(32),
dec_places smallint,
desc_line1 char(12),
desc_line2 char(12),
desc_line3 char(12)
);
create unique index i_grp on log_groups (grp_number);
create unique index i_grp_c on log_points (log_grp, log_column);
create index i_log_g on log_points (log_grp);
create index i_log_c on log_points (log_column);
create index i_pt_nm on log_points (pt_name);
update statistics;
COMMAND TO CREATE TABLES USING colrep.sql
/usr/informix/bin demo colrep.sql
NOTE: Substitute the name of your historian name for demo.
FORM TO CONFIGURE SCREENS -- colrep.per
database demo { use the name of the historian you are reporting on }
screen
{
--------------------------------------------------------------------------
| FOXBORO DATA LOG REPORTING GROUPS CONFIGURATION |
--------------------------------------------------------------------------
132
| |
| GROUP NUMBER [f000 ] |
| GROUP NAME [f001 ] |
| [f002 ] |
| |
| MAXIMUM NUMBER OF COLUMNS ALLOWED IN GROUP [f003 ] |
| |
| *** PRESS DETAIL KEY TO CONFIGURE MEMBERS OF LOG REPORTING GROUP *** |
| |
--------------------------------------------------------------------------
}
screen
{
--------------------------------------------------------------------------
| FOXBORO DATA LOG REPORTING MEMBERS CONFIGURATION |
--------------------------------------------------------------------------
| |
| GROUP NUMBER [f000 ] |
| GROUP NAME [f001 ] |
| [f002 ] |
| |
| MAXIMUM NUMBER OF COLUMNS ALLOWED IN GROUP [f003 ] |
| |
| REPORT COLUMN POSITION [f005 ] Historian Key [g000 ] |
| GROUP MEMBER POINT NAME [f006] |
| NUMBER OF REPORTED DECIMAL PLACES [f007] |
| |
| COLUMN DESCRIPTOR LINE 1 [f008 ] |
| LINE 2 [f009 ] |
| LINE 3 [f010 ] |
| |
| *** PRESS MASTER TO DISPLAY LOG REPORTING GROUPS *** |
--------------------------------------------------------------------------
}
end
tables
log_groups
log_points
all_points
attributes
f000 = *log_groups.grp_number = log_points.log_grp, NOENTRY;
f001 = log_groups.grp_name[1,40],
COMMENTS = “Enter a name for this logging group”;
f002 = log_groups.grp_name[41,80],
COMMENTS = “Continue entering the name for this logging group”;
f003 = log_groups.max_columns, DEFAULT = 6, REQUIRED,
COMMENTS = “Enter MAXIMUM columns (1-10) allowed for this group”,
INCLUDE = ( 1 TO 10 ) ;
f005 = log_points.log_column, REQUIRED,
COMMENTS = “Enter column number from 1 to MAXIMUM”,
INCLUDE = ( 1 TO 10 ) ;
f006 = log_points.pt_name, REQUIRED, UPSHIFT,
COMMENTS = "Enter COMPOUND:BLOCK:PARAMETER name of
historian member",
LOOKUP g000 = all_points.pkey JOINING *all_points.id;
f007 = log_points.dec_places, DEFAULT=2,
COMMENTS = "Enter number of decimal places (0-6)",
INCLUDE = ( 0 TO 6 ) ;
f008 = log_points.desc_line1,
COMMENTS = "Enter line 1 column descriptor ";
133
instructions
log_groups MASTER of log_points;
AFTER EDITADD EDITUPDATE OF log_points.log_column
IF f005 > f003 THEN
BEGIN
COMMENTS BELL REVERSE "This number exceeds MAXIMUM group columns "
NEXTFIELD = f005
END
AFTER ADD UPDATE DISPLAY OF log_points
IF COUNT OF f006 = f003 THEN
COMMENTS REVERSE " This logging group has the MAXIMUM report columns "
end
COMMAND TO COMPILE FORM - colrep.per
/usr/informix/bin/sformbld colrep [This will create colrep.frm if successful
or colrep.err if unsuccessful ]
You can only run sformbld (forms compiler) on the 50/51 if have the optional
program development package. Otherwise, form specification file developed on
the AP20 should compile and run on the 50/51.
COMMAND TO ENTER DATA INTO TABLES
/usr/informix/bin/sperform colrep
REPORT SPECIFICATION - colrep.ace
{
**************************************************************************
* EXAMPLE General Purpose CONFIGURABLE Log Report *
* *
* For use with INFORMIX 1.10.12 (I/A SYSTEM) *
**************************************************************************
}
database
demo { use the name of the historian you are reporting on }
end
define
variable cur_col smallint { Current column }
variable end_col smallint { Current column end }
variable start_col smallint { First column position }
variable size_col smallint { Column size }
variable head_ready smallint { Header ready indicator}
variable head_01 char(132) { Header line 1 }
variable under_s char(132) { Header underscores }
variable out_line char(132) { Data output line }
variable df float { Float type day }
variable di integer { Integer type day }
variable hf float { Float type hour }
variable hi integer { Integer type hour }
variable mf float { Float type month }
variable mi integer { Integer type month }
variable old_di integer { Previous day }
variable TRUE smallint { This is true }
variable FALSE smallint { This is false }
end
output
top margin 2
bottom margin 4
left margin 1
right margin 80
page length 66
report to "colrep.out"
end
134
select DISTINCT eg_red.time_tag from eg_red INTO TEMP timetags;

{
The DISTINCT keyword puts only one instance of each unique time tag into
a temporary table. The report uses the temporary table “timetags” in the
“OUTER JOIN” of the last select statement
}
select
log_groups.*, log_points.*
from log_groups, log_points
where log_groups.grp_number = log_points.log_grp
into temp def_groups;
{
This separate select and temporary table is not necessary. It is included
here to make the last select statement clearer.
}
select
def_groups.*, eg_red.*
from all_points, def_groups, timetags, eg_red
where def_groups.pt_name = all_points.id AND
all_points.pkey = eg_red.pt_id_key AND
timetags.time_tag = eg_red.time_tag
order by grp_number, time_tag, log_column
end
{
The “JOIN” in this select statement is the workhorse which allows column
header printing. You will see that the column heading information is
“attached” to the time slot rows from the reduction tables. The column
heading may not appear for newly added points until the reduction table
has accumulated time slots the full retention time
}
format
first page header
print ASCII(12) { Kick the page up to the perforation }
print "=================================================================="
print " CONFIGURABLE GENERAL SHIFT LOG"
print "=================================================================="
skip 1 line
print "=================================================================="
print " Report run date: ", today using "mmm dd, yyyy"
print " Report run time: ", time
print "=================================================================="
let start_col = 9 { Starting column position is 9 }
let size_col = 12 { Column standard size is 12 }
let TRUE = 1
let FALSE = 0
page header
skip 1 line
print "=================================================================="
print " Report run date: ", today using "mmm dd, yyyy"
print " Report run time: ", time
print "=================================================================="
skip 2 lines
before group of grp_number
need 12 lines
let head_ready = FALSE { Must build new column descriptors }
{ These statements clear the column description buffers }
let under_s = 132 spaces
let head_01 = 132 spaces
let old_di = 0 { Compare for next day }
skip 2 lines
135
print "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"
print grp_name
skip 1 line
before group of time_tag
let df = time_tag/(60*60*24) { Calculate day plus fraction }
let di = df*1 { This truncates day to integer }
let hf = (df-di) * 24 { Calculate hour plus fraction }
let hi = hf*1 { This truncates hour to integer}
let mf = (hf-hi) * 60 { Calculate minute plus fraction}
let mi = mf*1 { This truncates minute to integer}
{
Initialize line output character buffer. This buffer stores the line as
data is gathered by EVERY ROW. It is also initialized with the historian
time_tag
}
let out_line = hi USING "&&", ":", mi USING "&&", 127 spaces
before group of log_column
{
Each column comes in order for each historian time slot. This calculates
the column position required
}
let cur_col = ( log_column -1 ) * size_col + start_col
let end_col = cur_col + size_col - 1
on every row
if NOT head_ready then
begin
let head_01[cur_col, end_col] = desc_line1
let under_s[cur_col, end_col] = "__________"
end
{ Each row may have historian data and formatting }
if dec_places = 0 then
let out_line[cur_col, end_col] = eg_red_avg USING "##########"
else
let out_line[cur_col, end_col] = eg_red_avg USING "#########.#"
else
let out_line[cur_col, end_col] = eg_red_avg USING "########.##"
else
let out_line[cur_col, end_col] = eg_red_avg USING "#######.###"
else
let out_line[cur_col, end_col] = eg_red_avg USING "######.####"
else
let out_line[cur_col, end_col] = eg_red_avg USING "#####.#####"
else
let out_line[cur_col, end_col] = eg_red_avg USING "####.######"
else
let out_line[cur_col, end_col] = eg_red_avg
after group of time_tag
if NOT head_ready then
begin
let head_ready = TRUE
print head_01 CLIPPED { If you have configured the group column }
print head_02 CLIPPED { maximum correctly, the CLIPPED phrase }
print head_03 CLIPPED { will keep the printer from printing extra}
print under_s CLIPPED { lines on short carriage printers }
136
end
if old_di <> di then
begin { Print date if new day }
skip 1 line
print date(di)+mdy(1,1,1970) USING "mm/dd/yyyy"
let old_di = di
end
print out_line CLIPPED { Output the line buffer }
on last row
skip 2 lines
print "END OF REPORT"
page trailer
skip 2 lines
print column 15, "Page ", pageno using "<<"
end
COMMAND TO COMPILE AND GENERATE REPORT

saceprep colrep
sacego colrep
SAMPLE OUTPUT
==================================================================
CONFIGURABLE GENERAL SHIFT LOG
==================================================================
==================================================================
Report run date: Aug 01, 1990
Report run time: 08:57:23
==================================================================
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Crude Unit Logging Group -------------- Demonstration
Gas Light SR Naptha Kerosene Diesel Atmospheric
Flow Rate Gas Flow Flow Flow Flow Gas Flow
SCFM SCFM BPD BPD BPD BPD
---------- ---------- ---------- ---------- ---------- -----------
07/26/1990
02:50 49.06755 52.07 51.0000 52.079 49.59 50.00
03:50 49.61890 51.59 51.0000 51.597 49.12 50.00
04:50 51.33492 51.53 51.0000 51.537 51.31 50.00
05:50 49.08761 52.06 51.0000 52.064 49.62 50.00
06:50 49.64559 52.38 51.0000 52.380 50.06 50.00
07:50 49.77342 51.99 51.0000 51.999 49.72 50.00
08:50 51.57986 50.52 51.0000 50.523 51.60 50.00
09:50 50.03846 52.03 51.0000 52.031 49.98 50.00
10:50 50.17110 52.02 51.0000 52.020 50.12 50.00
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Depropanizer Unit --------------------- Demonstration
Top Product Tray Number
Analysis 3
Percent Flow BPM
----------- ----------
07/26/1990
02:50 49.06 52.07
03:50 49.61 51.59
04:50 51.33 51.53
05:50 49.08 52.06
06:50 49.64 52.38
07:50 49.77 51.99
08:50 51.57 50.52
09:50 50.03 52.03
137
10:50 50.17 52.02

END OF REPORT
Report Writing Using Spreadsheet - AP20

Spreadsheet is a workstation-operated software package that allows you to perform row/column
operations. It runs on an I/A Series AP20 or PW. Spreadsheet allows you to mix live process data,
historical data, data from INFORMIX databases, and keyboard-entered data in one report.
Spreadsheet has the additional capability of accessing multiple databases (that is, local and
remote). The Spreadsheet is also capable of producing graphical representations of the data.
This section provides an example of how to generate a historical report. Please refer to
Spreadsheet (B0193BM) to familiarize yourself with the layout of the Spreadsheet and to under-
stand the commands used to access the above mentioned data. The process data is retrieved using
some of Spreadsheet’s built-in functions; historical and INFORMIX database data is retrieved
using the Options menu.
In the Spreadsheet, you can create the report interactively by selecting the appropriate command
from the menu and answering all the prompts/requests, or you can incorporate all the required
information into a macro. Macros are scripts that you create for performing repetitive spreadsheet
tasks. A macro is a string of keystrokes that you would have executed if you were to accomplish
this task interactively.
If you create the report interactively, you have a single copy of the report. Future regeneration of
the report requires you to enter the Spreadsheet and repeat the sequence of instructions. However,
if you use macros to create the report, you have a copy of the instruction set, thus you can easily
reproduce the report or make modifications and rerun the report.
In the following example report, the following assumptions are made:
♦ eg_red_grp is an hourly reduction group.
♦ Data retention time span for eg_red_grp is 8 hours.
♦ When it is necessary to be explicit about the cell number, the contents of the cell are
preceded by the cell number, which is in bold and surrounded by colons.
♦ The macro is typed in cell A1 of the Spreadsheet and the retrieved data is displayed in
cell AA10. Headers, titles, and so forth for the report begin at cell AA1. Therefore, the
section of the Spreadsheet that is printed out is AA1 to AE21.
♦ The macros are as follows:
@@E(:A1:)/OHRRA10..A11{cr}AA10{cr}demo{cr}eg_red_grp{cr}{cr}{cr}
8:00{cr}16:00{cr}avg,status_tag{cr}h{cr}
@@E(:A2:)/CFDGHH:MI{cr}AA10..AA21{cr}
@@E(:A3:)#/PRAA1..AE21{cr}report.out{cr}
@@E(:A4:)!lp -o-t report.out{cr}
Cell A1 contains the macro that does the historical data retrieval. The point names to be retrieved
are in cells A10 to A11. The name of the Historian is demo. The start and end dates are the cur-
rent date. The start time is 8:00 am and the end time is 4:00 pm. The columns to be retrieved are
the average operation storage column and the status tag column.
Cell A2 contains the macro that formats the time_tag column into hour:minute format. The time
tags are originally returned as the number of days from January 1 1970.
138
Cell A3 contains the macro that prints out the report to a file report.out. The “#” forces an update
of all the cells in the Spreadsheet, that is, all functions and formulas are re-evaluated/re-executed.
This is necessary to update the time and date stamp being added to the report header.
Cell A4 contains the macro to send the report to the printer. The VENIX utility, lp, is being used
here.
Cell AC6 and AC7 contain a call to the Spreadsheet function today(), which returns the current
time and date as the number of days from January 1, 1970. Cell AC6 has been formatted using
/CFDG HH:MM, and cell AC7 has been formatted using /CFDG MM/DD/YY.
To generate the report, execute the macro in cell A1. This is accomplished by typing \A1. Once
this macro has completed its task, the macros in cell A2, A3 and A4 are automatically processed.
You do not need to initiate them individually.
The front portion of the spreadsheet may look as follows:
A B C D E F
1 /OHRRA10..A11{cr}AA10{cr}demo{cr}eg_red_grp{cr}{cr}{cr}
2 /CFDGHH:MI{cr}AA10..AA21{cr}
3 #/PRAA1..AE21{cr}report.out{cr}
4 !lp -o-t report.out{cr}
5
6
7
8
9
10 CMP:BLK_1.PARM
11 CMP:BLK_2.PARM
12
The latter part of the spreadsheet may look as follows:

AA AB AC AD AE AF
1
2 Example Report
3 For Plant XYZ
4
5
6 Run time:15:00
7 Run date:12/12/90
8
9
10 CMP:BLK_1.PARM CMP:BLK_2.PARM
11 AVG STATUS_TAG AVG STATUS_TAG
12 8:00 49.54244 OK 50.89009 OK
13 9:00 50.77232 OK 49.23892 OK
14 10:00 51.35556 OK 51.01086 OK
15 11:00 50.40864 OK 53.12399 OK
16 12:00 50.44994 OK 50.92536 OK
17 13:00 49.16627 OK 50.85907 OK
18 14:00 50.99953 OK 50.92375 OK
19 15:00 53.13809 OK 49.54244 OK
20 16:00 50.90161 OK 50.77232 OK
21
Scheduling Reports
To schedule the report to run at regular intervals, you can use the VENIX cron daemon, which is
documented in VENIX User Reference Manual (B0193BV). The commands to set up environ-
139
ment variables and to execute the report can be placed in a script file which is scheduled and exe-
cuted by cron.
The scheduling statement consists of six fields, each separated by spaces or tabs. They are as fol-
lows:
Field 1 Minutes (0-59)
Field 2 Hours (0-23)
Field 3 Day of the month (1-31)
Field 4 Month (1-12)
Field 5 Day of the week (0-6)
0 = Sunday 1 = Monday
2 = Tuesday 3 = Wednesday
4 = Thursday 5 = Friday
6 = Saturday
Field 6 Command to be executed

The entries for fields 1 to 5 can be a valid integer or an asterisk (denoting all valid values) or a
comma separated list of valid integers or two numbers separated by a minus sign (denoting an
inclusive range).
Since only one cron table can exist for each user account on an AP, the scheduling statement is
entered in /usr/applic/mastercron, and the syntax to schedule is:
crontab /usr/applic/mastercron
Examples of scheduling statements:
1. 0,2,4,6 12 * * 3 /usr/applic/xyz/sched_rep
In the above statement, the script, sched_rep, is executed every Wednesday at 12:00,
12:02, 12:04 and 12:06.
2. 0 * * * * 1,2,3,4,5 /usr/applic/xyz/sched_rep
In the above statement, sched_rep is executed every hour, every weekday (that is,
excluding Saturday and Sunday).
If the report to be generated is an ACE report, then the contents of sched_rep is similar to the
script used to generate a report from a menu pick, that is:
PATH=:/bin:/usr/bin:/usr/informix/bin
INFORMIXDIR=/usr/informix
read TZ < /etc/tz
export DBPATH INFORMIXDIR PATH TZ
# Change directory to where the report specification
# resides
sacego -q rep_file
# and you want it sent to a printer, then add the following
# statement also
140
lp -o-t -o-e rep_file.out
If the report is a spreadsheet, then the script is as follows (refer to Spreadsheet (B0193BM) for fur-
ther details):
#set the environment variables
read TZ < /etc/tz
export DBPATH TZ
#change directory to where the Spreadsheet programs reside
cd /usr/prelude/bin
#generate the report
ss -n report.ss -m “\\\A1{cr}/QY{cr}”
NOTE
The Historian uses I/A Series system time and cron uses VENIX time. There could
be a discrepancy there. One way to assure that both use the same time is to put the
following two statements in /etc/rc and /etc/nrc before the startup of back-
ground daemons.
read TZ < /etc/tz

export TZ
141
142
13. Managing Databases
This chapter contains directions for the following database procedures: initializing the
database, copying an AP20/WP configuration database, replacing an existing database,
deleting an archive database, converting an AP20/PW database to an AP50/51 database,
optimizing an AP50/51 database, saving an AP50/51 database, reloading an AP50/51
database, and merging AP50/51 databases.
Accessing VT100 Mode

Several procedures in this chapter require you to access VT100 mode and enter commands. To
access VT100 mode:
1. Select Sys from the top menu bar.
2. Select Change_Env from the System menu.
3. Select Proc_Eng_Env from the Change Environment menu.
4. Select the SftMnt button on the top menu bar and select VT100 from the pull-down
menu.
5. Enter commands at the # prompt. While in VT100 mode, always wait until a com-
mand completes before entering the next command.
6. To exit VT100 mode and return to the Proc_Eng_Env environment, type EXIT at the
# prompt.
If necessary, see System Operations Guide (B0193CR) for instructions to switch to VT100 mode.
Initializing the Historian Database

To initialize a Historian database, that is, to delete the current configuration and reset the Histo-
rian to a blank, unconfigured state, proceed as follows:
AP20/PW Database Initialization

1. Back up the current database (optional).
2. Select Config from the top menu bar.
3. Select Historian from the Config menu.
4. Select Scheduler from the Historian menu.
5. Select Schedule Historians to display the list of Historian names and status.
6. Select the appropriate Historian name and click on the Stop button.
7. Go to the VT100 mode.
8. Enter the following commands at the # prompt, where apname is the AP station’s six-
character letterbug:
cd /usr/fox/sp/files/pkg_inits
p_init.HST20 apname NOTYET
143
B0193BL – Rev L 13. Managing Databases
9. If you use an extended database, enter the following commands at the command line
prompt (#), where dbname is the extended database name:
cd /u0/sam/dbname
rm *
AP50/51 Database Initialization

1. Back up the current database (optional).
6. Select the appropriate Historian name and click on the Stop button.
8. Enter the following commands at the # prompt:
dbinit50
cd ../sample
rm *
Copying an AP20/PW Configuration Database

You can create a configuration database on a personal computer that runs I/A Series software and
later copy the new database to an AP20/PW as follows:
At the personal computer:
1. Go to VT100 mode.
2. Enter the following command at command line prompt (#), where dbname is the
database name:
cd /usr/fox/hstorian/bin/dbname.dbs
3. Insert a high density diskette in drive fh0 and enter the following command:
tar cvf /dev/fh0 *
4. At the application processor, make sure that the Historian is off:
a. From a user environment, select Config from top menu bar.
b. Select Historian from pull-down menu.
c. Select Scheduler from pull-down menu.
d. Verify that the Historian is off.
6. Enter the following command:
cd /usr/fox/hstorian/bin/dbname.dbs
7. Insert the diskette containing the Historian configuration database in drive fh0.
8. Enter the following commands:
tar xvf /dev/fh0
rm __* (__ is two underscores)
144
13. Managing Databases B0193BL – Rev L
cd ..
rm __* (__ is two underscores)
exit
9. To start the Historian:
d. Select Schedule Historians.
e. Select the Historian and click on the Start button.
Replacing an Existing Database

To replace an existing Historian database with a restored database at the application processor:
1. Make sure that the Historian off:
d. Verify that the Historian is off.
2. Go to VT100 mode.
3. If you do not use extended sampling go to Step 5. If extended sample points were
added but none were deleted between time the database was backed up and restored,
go to Step 5; otherwise, go to Step 4.
4. If extended sample points were deleted and new ones added between the time the
database was backed up and restored, there is a mismatch between the configuration
files and the contents of extended sample data files /u0/sam/dbname/SAMxxx. Use Step
a to delete the SAMxxx files for the points in question. If you are not sure which index
number has changed, use Step b to delete all SAM files (or rename or move them to
another directory).
a. To delete specific SAM files, enter the following commands in sequence:
cd /usr/sam/dbname>
rm filename1 filename2...filenamen
b. To delete all SAM files:
cd /usr/sam/dbname
rm SAM*
5. Enter following commands at the # prompt, where histname.dbs is the current data-
base name and newhist.dbs is the replacement database:
rm -r histname.dbs
mv newhist.dbs histname.dbs
exit
6. From the user environment top menu bar, select Config.
a. From the Config menu, select Historian.
145
b. Select Configurator from Historian pull-down menu.

c. Select the Historian from the Historian menu.
d. Select Collection Points option from Edit menu.
e. Delete a collection point, add the point and exit the Configurator. See Chapter 3
“Configurator” for more information.
7. To start the Historian,
a. Select Scheduler from the Historian pull-down menu.
b. Select Schedule Historians.
c. Select the Historian and click on the Start button.
8. Re-initialize the workstation processors hosted by the Historian’s host AP, by resetting
the time and date on every WP, even if the time is already correct. For procedures on
how to set time and date, see System Operations Guide (B0193CR).
Deleting the Archive Database

An operator can back up the archive either to diskette or streaming tape before the next time the
archive group is scheduled to run and delete the archives to free up space.
Deleting an AP20/PW Archive Database

2. Enter the following commands at the # prompt, where agrouptime is the six-
character archive group name plus 4-character time stamp:
cd /usr/fox/hstorian/archive
-rm -r agrouptime.dbs
Deleting an AP50/51 Archive Database

2. Enter the following commands at the # prompt to set up INFORMIX environment
variables:
setenv INFORMIXDIR /opt/informix
setenv TBCONFIG tbconfig
setenv PATH ${PATH}:/opt/informix/bin
3. Run isql in interactive mode (applies to both development and run-time
INFORMIX packages):
isql - - <Return>
4. When the > prompt appears, enter the following command:
> drop database agrouptime_arc;
where agrouptime is the six-character archive group name plus the 4-character time
stamp.
5. Press Ctrl+C to exit isql.
The # prompt reappears.
146
Converting the AP20/PW Database to AP50/51

Database
To convert an AP20/PW Historian INFORMIX 1.10 database to an AP50/51 INFORMIX On
Line Database:
Download the database at the AP20/PW:
1. At the AP20/PW where the database resides, verify that /usr/fox/bin/tools direc-
tory has the following files:
dbconv50 load50.ace
dbdump50 unload50.ace
indexes.ec create.ace
NOTE
Although it is not necessary, turning off the Historian on the AP20/PW
expedites the process and is a good precaution.

cd /usr/fox/bin/tools
dbconv50
4. The dbconv50 program requests the database name. If no name is entered, it defaults
to the current Historian database name.
5. The dbconv50 program requests the target AP50/51 letterbug. If no letterbug is
entered, the converted database is stored on local diskettes.
6. If you supply a letterbug, the dbconv50 program attempts to mount the AP50/51
remotely. If it is successful, it downloads the database across the network to the
AP50/51 /usr/tmp/dbname.exp directory, where dbname is the name of the
AP20/PW’s database. When the operation is complete, the dbconv50 program dis-
plays an acknowledgment. If the dbconv50 program cannot remotely mount the
AP50/51, it displays the message: AP50/51 is not mountable - operation
aborted.
7. When downloading the database to diskette, the dbconv50 program transfers the data-
base to the local /usr/tmp/dbname.exp directory and prompts for a diskette:
Insert Floppy and Press Enter Key.
The dump mechanism uses tar format. If necessary, it prompts for more diskettes.
You must now convert the 5.25-inch diskette to a 3.5-inch diskette to load into the
AP50/51.
Database Uploading at the AP50/51:
cd /opt/informix/bin
dbconv50
3. The dbconv50 program requests the name of the database to upload. If no name is
entered, the dbconv50 program defaults to the current Historian database on the
147
AP50/51. If the database name is the same, or no name is entered, the dbconv50 pro-
gram turns off the Historian. When the dbconv50 program requests the load medium,
to upload from diskette, enter 0 and follow the prompts to insert the diskettes, other-
wise enter 1 to upload directly from the hard disk. The dbconv50 program loads the
new database onto the on-line system.
Optimizing the AP50/51 Historian Database

Once a Historian database grows to its configured size, you can optimize the database in two
ways:
♦ Collection point grouping
♦ Saving disk space from deleted records.
These optimization methods are described in the following subsections.
Optimizing with Collection Point Grouping

To optimize sample collection points, the following procedures can be performed from VT100
mode. The procedure includes the following steps:
1. Turn the Historian off.
For 50 Series workstations, use the directory /opt/fox/hstorian/bin.
For AP20/PW workstations, use the directory /usr/fox/hstorian/bin.
3. Run the optimize_hist program
>optimize_hist
4. Restart the Historian.
5. Run the hist_offset utility on all trend displays that get data from this Historian
(/usr/fox/wp/bin/tools).
Optimizing by Saving Disk Space

To optimize the database by saving disk space from the deleted records:
1. Turn the Historian off.
3. To check free space, type tbstat -d. You must have at least 1 MB of free space avail-
able to optimize a database.
saveh50
loadh50
9. Select the appropriate Historian name and click on the Start button.
148
10. Restart the Historian.

If there is not enough free space in the on-line partition for the saveh50 program to run success-
fully, the program notifies you of the situation, gives statistics of the on-line space, and aborts. You
must then add a cooked data space of at least 5% of the raw partition space before you can run the
saveh50 program.
For example:
> touch cooked
>chown informix cooked
> l cooked
> chgrp informix cooked
> chmod 666 cooked
> l cooked
> tbspaces -a rootdbs -p /opt/fox/hstorian/bin/cooked -o 0 -s 100000
Saving the AP50/51 Historian Database

To save an AP50/51 database:
saveh50
3. The saveh50 program turns off the Historian, copies the database to a local directory
dbname.exp, and requests the storage media. Enter the device number: 0 for diskette
(bar format), 1 for tape (tar format), 2 for cassette (tar format), or 3 for hard disk
(default).
Reloading the AP50/51 Historian Database

loadh50
3. The loadh50 program requests the loading device. Enter the load medium: 0 for dis-
kette, 1 for tape, 2 for cassette, 3 for hard disk (default).
4. If you select 0, 2, or 3, the loadh50 program requests you to insert diskette, tape, or
cassette tape.
5. The loadh50 program loads the database onto the on-line system.
6. You must restart the Historian manually. If the hard disk option was selected, delete
the temporary directory /opt/fox/hstorian/bin/dbname.exp.
149
Merging AP50/51 Historian Databases

An AP20/PW INFORMIX 1.10 Historian database must be converted to an INFORMIX on-
line database before you can merge it into an AP50/51 Historian database. Always back up your
target database before you merge databases.
Merging Databases on the Same AP

To merge two Historian databases that reside in the same rootdbs and create a third database, pro-
ceed as follows:
1. If the target database is the current Historian database, turn the Historian off.
dbmerge dbname 1dbname2dbname3
To merge the second database into the target database, proceed as follows:
1. If the target database is the current Historian database, turn the Historian off.
dbmerge dbname1dbname2
Merging Databases from Different Media

To merge a database from a diskette or streaming tape in dbexport format into a database on the
hard disk, use the dbexport program to dump the database from a different node or file server to
diskette or streaming tape. Then use the dbmerge program with the same arguments to merge the
database into the target database.
1. Turn off the Historian.
3. At the AP50/51 where the second database is located:
Enter the following commands at the # prompt:
setenv INFORMIXDIR /opt/informix
setenv PATH ${PATH}:/opt/informix/bin
a. For 150 MB tape, enter the following command:
dbexport dbname2 -t /dev/rst0 -b 20 -s 150000
b. For diskette, enter the following command:
dbexport dbname2 -t /dev/fd0 -b 1440 -s 2000
4. At the AP50/51 where the first database is located:
a. For 150 MB tape, enter the following commands:
dbmerge dbname1 -t /dev/rst0 -b 20 -s 150000
b. For diskette, enter the following commands:
dbmerge dbname1 -t /dev/fd0 -b 1440 -s 2000
150
To merge a database on streaming tape or diskette with a database located on the hard disk and
create a third database, enter the following commands at the # prompt:
a. For 150 MB tape, enter the following commands:
dbmerge dbname1 -t /dev/rst0 -b 20 -s 150000 dbname3
b. For diskette, enter the following commands:
dbmerge dbname1 -t /dev/fd0 -b 1440 -s 2000 dbname3
Use the following guidelines when you merge databases.
♦ For duplicate table names, especially for reduction and manual data entry groups, the
dbmerge program generates the following warning:
Duplicate group table name = name
Do you want to continue: Enter y/n
♦ Enter n to exit. Enter y to continue. The dbmerge program attempts to insert rows
with the same table name but with different group_ids, point_ids, or owner_ids into
the same table. If the number of columns is different, then the insert operation and
the merger fail.
♦ For message group tables, the data from the second database is unloaded to a directory
named dbname2.msg (or hisdb2.msg in case of merging from diskette or streaming
tape). The file name is the table name with an extension .unl. No attempt is made to
merge these tables.
♦ For sample collection points, if the sum of the collection points of the two databases is
greater than the configured Historian size (/etc/histsize), then the merge fails and
dbmerge generates the following error message:
Error: too many trend members to be merged -- dbmerge exits

♦ The dbmerge program writes INFORMIX error messages, such as failing to update or
alter a table, in the dbmerge.log file. Refer to the INFORMIX-ESQL/C Programmer's
Manual Embedded SQL and Tools for C (B0193BU) for descriptions of these errors
messages.
151
152
Appendix A. Data Reduction
Algorithms
This appendix contains a table of algorithms for reducing data.
Table A-1. Algorithms for Reducing Data
OPERATION ALGORITHM
Summation (SUM) Sum of samples in the reduction period.
Maximum (Max) Maximum sample value.
Minimum (Min) Minimum sample value.
x = sum
Average (AVG) of samples
--------------------------------------
sample count
(Average of samples2) x**2 = sum of samples**2-

-----------------------------------------------
sample count
Variance s**2 = x**2 – (x)**2

Standard deviation (STDEV) s**2
x**3 = sum of samples**3-
(Average of samples3) -----------------------------------------------
sample count
x**4 = sum of samples**4-

(Average of samples4) -----------------------------------------------
sample count
Coefficient of Kurtosis x**4 – 4*x**3*(x) + 6*x**2*(x)**2 – 3*(x)**4-

----------------------------------------------------------------------------------------------------------------------------
KURT (s**2)**2
NOTE
Coefficient of Kurtosis is the measure of the peakedness or height of a distribution
whereas the standard deviation measures the width of the sample distribution. The
specified algorithm measures the fourth moment about the mean normalized by the
standard deviation, or the average of:
((value - average)/standard deviation) ** 4
over the sample set.
153
B0193BL – Rev L Appendix A. Data Reduction Algorithms
154
Appendix B. Object Manager Status
Tag Processing
This appendix describes the fields in the Object Manager status word used by the status tag
processing.
The following fields in the Object Manager status word are used by status tag processing
algorithms in the Historian:
TYPE (bits 0 to 4) = data type
OMST (bits 5 to 7) = Object Manager connection status
BAD (bit 8) = bad I/O flag
OOS (bit 11) = out-of-service flag
Algorithm for Change-Driven Sample Data

If (OMST == 0) or (TYPE != 2, 3, 5 or 6)
then
the value is set to 0,
TYPE is set to 0.
else
the value is converted to floating point,
TYPE is set to 3 = FLOAT.
Algorithm for Reduction Data

If (OMST != 1) or (TYPE != 2, 3, 5 or 6) or (BAD != 0) or (OOS != 0)
then
the sample value is neither converted nor used to update
intermediate results.
When reduced data is built from intermediate results, if enough data samples were collected in the
intermediate results,
then
the reduced value is calculated according to the operation,
the status is set to 3 = FLOAT.
else
the reduced value is set to 0.0,
the status is set to 0x83 = (UNAVAIL | FLOAT).
155
B0193BL – Rev L Appendix B. Object Manager Status Tag Processing
Unreduced Data
The following data types are handled as is:
♦ Boolean
♦ Packed
♦ Packed Long
These data types are sampled but are not reduced.
156
Appendix C. Disk Space Required
for Sampling Points
This appendix shows how to estimate disk requirements for the AP50 and AP20.
In the calculations below, the following variables are used:
num_recs Number of sample records configured for a particular collection point.

There are 100 samples in each record, therefore num_recs is the number
of samples configured for a point, divided by 100, that is:
numrecs 36 * retention time hours/sample period seconds
num_points Total number of collection points configured with the num_recs > 0. (If
num_recs = zero, no samples are collected into a SAMxxx file.)
AP50
For Historian databases resident on an AP50, the disk requirement can be estimated as follows:
4830 bytes * num_points
+1224 bytes * (Total of all num_recs)
For example, with 1200 collection points configured, each to retain 20,000
samples (numrec = 200), the required disk space in megabytes (MB) is:
(1200 * 4830) + (1224 * 1200 * 200) = 5.8 MB + 293.8 MB = 300 MB
AP20
For Historian databases resident on an AP20, the disk requirement can be estimated as follows:
4320 bytes * num_points
+1024 bytes * (Total of all num_recs)
For example, with 400 collection points configured, each to retain 20,000 samples
(numrec = 200), the required disk space in megabytes (MB) is:
(400 * 4320) + (1024 * 400 * 200) = 1.8 MB + 81.9 MB = 84 MB
The numbers quoted above account for disk space actually used for data samples, as well as
approximate allowances for file headers, other files required by the sampling process (for example,
__tdir, __mdata), directory entries, and average fill space at the end of data files, up to the next
sector boundary.
All results should be rounded up.
For an existing database, use cfgpts -s utility to obtain these results. The results may vary
slightly due to the different calculation methods.
157
B0193BL – Rev L Appendix C. Disk Space Required for Sampling Points
158
Appendix D. Sizing Guidelines
This appendix contains the following guidelines for sizing Historians on AP20 and on
50 Series workstations.
AP20 Workstations
This section contains information for the AP20 workstations on the following:
♦ Sizing Historians
♦ Displaying archive disk usage
♦ Sizing disks for extended sampling.
Sizing Historians
This section discusses sizing guidelines Historians. These guidelines assume the following:
♦ A full historian database exists.
♦ There are 500 data collection points.
♦ All basic sampling points are configured for extended sampling.
♦ Deadbands for collection point sampling are set so that the average exception ratio is
at least 3:1.
Rules for Collection Point Sampling

1. AP20 running a Historian with other applications:
Samples/min value from basic sampling plus one half the samples/min value from
extended sampling should not exceed 2000.
2. AP20 dedicated to the Historian:
Samples/min value from basic sampling plus one half the samples/min value from
extended sampling should not exceed 3000.
Rules for Reduction Groups

These recommendations are subject to the restrictions imposed by the average reduction
load:
1. For non-cascaded groups, set the reduction periods ≥ one minute.
2. For cascaded groups, set the reduction periods ≥ 30 minutes.
3. Schedule reduction groups to run at least one minute apart from each other to even
out loading.
4. The average reduction load should not exceed 40 points/minute.
5. For best performance, reduction groups have 50 or fewer members.
6. No reduction group should have more than 120 members.
159
B0193BL – Rev L Appendix D. Sizing Guidelines
Rules for Fixed Size Files

The INFORMIX overhead files, Historian configuration tables, message index files and
system disk collection point sampling files are relatively fixed in size as follows:
INFORMIX overhead files (.dat and .idx) = 70 KB:
syscolauth syscolumns sysindexes
sysabauth systables
Historian configuration tables (.dat and .idx) = 250 KB:

all_points tnd_memb pnt_memb
all_groups grp_memb reduc_cfg
reduc_op messag_cfg messages
notes arch_cfg arch_sets
Message index files (.idx) = 60 KB:

applic batch equipment
form mesgsys opraction
path path_excep procedure
report run sysmonmsg
unit unknown
Collection point files = 1.2 MB:

__tdata __tdir __mdata
__olddir __omlist __save
Rules for Reduction Data and Index File

The computation for reduction data files (.dat files) is:
(10 bytes + 4 bytes/operation) per sample
Reduction .idx files seem to range between 30% and 90% of the size of the corresponding .dat
files.
Rules for Message Data Files

The amount of disk space required for message .dat files depends on the types of messages you
expect to receive and store in the Historian. The file sizes of the various message .dat files are listed
in Table D-1:
Table D-1. Message Data File Sizes
Message .dat File Size (KB) Message .dat File Size (KB)
applic 54 path_excep 13
batch 22 procedure 19
equipment 19 report 25
form 20 run 14
mesgsys 31 sysmonmsg 19
160
Appendix D. Sizing Guidelines B0193BL – Rev L
Table D-1. Message Data File Sizes (Continued)
Message .dat File Size (KB) Message .dat File Size (KB)
opraction 74 unit 17
path 16 unknown 112
Rules for Archives

If you archive data, allow space for another whole database plus space for each archive set that
resides on the system. Resident archive sets contain all INFORMIX overhead files plus reduction
and message .dat and .idx files that belong to members of the archive set.
Rules for Extended Sample Files

On the second hard disk, there is one file for each collection point that is configured for extended
sampling. Each file has a 4096 byte header, and a data section of 1,024 bytes for every 100 sam-
ples. The file size can be configured in increments of 100 samples. The maximum file size is
1,019,904 bytes (1,015,808+4,096) enough for 99,200 samples.
Displaying Archive Disk Usage

The directory structure for archiving data is:
/usr/fox/hstorian/archive for reduction, message, and MDE archives.
/usr/fox/hstorian/bin for restored reduction, message, and MDE archives.
/u0/sam/archive for sample data archives.
/u0/sam/playback for restored sample data archives.
To see how much disk storage space is free for archiving data or restoring data archives, use the
VENIX df command as follows:
2. To display the number of free blocks in the /u0 and /usr directories, enter the follow-
ing commands at the # prompt:
cd /
du
exit
NOTE
There are 512 bytes in a block.
To see how much disk space is being used for archiving data or restoring data archives, use the
VENIX du command as follows:
2. To display the detailed number of free blocks in the directory dirname, where dirname
is the full pathname of the directory, enter the following commands at the # prompt:
cd dirname
du
exit
3. To display the total usage the directory dirname, where dirname is the full pathname
of the directory, enter the following commands at the # prompt:
161
cd dirname
du -s dirname
exit
Sizing Disks for Extended Sampling

The maximum Historian extended sample file is 1,019,904 bytes in size, representing 99,200 data
samples, and the minimum Historian extended sample file is 5,120 bytes in size, representing 100
data samples.
The structure of an extended sample file is as follows:
♦ 4096 bytes for header information
♦ 1024 bytes for each 100 data samples written (one record).
An extended sample file is initially 5120 bytes and contains the header and first 100 data samples.
It grows in increments of one record for each additional 100 samples of data, until it reaches its
maximum configured size. Once the maximum configured file size is reached, wraparound occurs
and the oldest samples are overwritten.
A general formula for determining extended sample disk usage or time duration is as follows:
Let:
F = 1440 minutes/day
R1 ... RN = sampling rates in seconds
D = approximate disk usage in MB; this number should not exceed 114 MB for the
120 MB disk, or 76 MB for the 80 MB disk
T = time duration over which a file retains data (in days)
x = number of samples needed per day
y = number of records needed per day
z = number of bytes needed per day
C1 = number of points at R1
CN = number of points at RN
CE = number of extended points
General Formulas:
x = F * [C1 * (60/R1) + ... CN * (60/RN)]
y = x/100; rounded up
z = y * 1024
The equations below solve for either needed disk space (D), or time duration (T):
D = [CE * 4096] + [T * z]
T = [D - (CE * 4096)] / z
Example:
Determine the maximum number of days for which data can be stored on a 120 MB extended
disk before it gets overwritten if:
♦ 500 points are configured for basic sampling.
♦ Each point is also configured for extended sampling.
162
♦ No room is reserved on the disk for archiving or playback.

♦ All points are to retain data for the same length of time.
♦ Sample loading is as shown in the Table D-2.
Table D-2. Sample Loading
Sampling Rate (min) Number of Points

1 50
2 100
5 300
10 50
Solve the general formulas:

x = 1440 [(50 * 1) + (100 * 1/2) + (300 * 1/5) + (50 * 1/10)]
x = 1440 * 165 = 237,600 samples per day
y = x/100 = 237,600/100 = 2376 records per day
z = 2376 * 1024 = 2,433,024 bytes = 2.433 MB per day
Solve for T, using D = 114 MB and z = 2.433MB:
T = [D - (CE * 4096)] / z
T = [114 000 000 - (500 * 4096)] / 2,433,000
T = 46 days.
For an 80 MB disk, solve for T, using D = 76 MB and z = 2.433MB:
T = [76 000 000 - (500 * 4096)] / 2,433,000
T = 30.4 days.
Table D-3 shows the approximate time duration an extended sample file covers if configured to
hold the maximum of 99,200 samples at a specified sample rate. With the current memory limita-
tions, all 500 points may not be configured for the maximum extended sample file size.
Table D-3. Time Duration Examples for Maximum File Size
Sampling Rate Time Duration (days)

No Exception 3:1 Exception 5:1 Exception
2s 2.3 6.9 11.5
4s 4.6 13.8 23.0
10 s 11.5 34.5 57.5
20 s 23.0 69.0 115.0
30 s 34.4 103.2 172.0
1m 68.0 204.0 340.0
2m 137.7 413.1 688.5
5m 344.4 1033.2 1722.0
10 m 688.8 2066.4 3444.0
163
Table D-4 and Table D-5 show the approximate maximum time duration each extended
sample file covers if all 500 points are configured at the same sample rate. To accommodate all
500 points at each sample rate, the extended sample files must contain less than 99,200 samples.
The time durations are based on using 114 MB of the 120 MB hard disk and 76 MB of the 80
MB hard disk, including headers and overhead. No disk space is reserved for archiving or play-
back.
Table D-4. Time Duration Examples for 120 MB Disk
Sampling Rate Samples Per File Time Duration (days)

1m 21,900 21.9 65.7 109.5
2m 21,900 43.8 131.4 219.4
5m 21,900 109.7 329.1 548.5
10 m 21,900 219.4 658.2 1097.0
Table D-5. Time Duration Examples for 80 MB Disk
Sampling Rate Samples Per File Time Duration (days)

1m 14 400 10 30 50
2m 14 400 20 60 100
5m 14 400 50 150 250
10 m 14 400 100 300 500
AP50/AW50 Workstations
This section describes sizing guidelines for a Historian on AP50 or the AW50 workstation. Bulk
storage topics in this section are:
♦ Sampling Data
♦ Reduction Data
♦ Manual Data.
The maximum number of sample points allowed is a system-configurable option. Available
options are 500, 1000, 1500, 2000 and 4000, 8000 (AW51 Style B and C workstations only)
sample points.
All sample points can be scanned at any of the configurable frequencies. The total change-driven
load (number of points changing) can be no more than 200 points per second on 12 MB AP50s
and all AW50s. The maximum change-driven load for 24 MB and 48 MB AP50s is 250 points
per second.
All the configured sample points can be reduced. The AP50 with the 424 MB disk is capable of
reducing all 2000 points every 10 minutes (an average of 200 points per minute). The AP50 with
the 1.3 GB disk is capable of reducing all 2000 points every 5 minutes (an average of 400 points
per minute).
164
The Historian provides for up to 99,999,000 on-line sample values for each configured point.
Bulk Storage Sampling Data

Sample data is stored in the /opt partition. Maximum sample file size is 1.2 GB.
Total disk space required for sample data with a maximum of 99,999,000 records:
500 Points 600 GB
1000 Points 1200 GB
1500 Points 1800 GB
2000 Points 2400 GB
4000 Points 4600 GB
8000 Points 9300 GB
Use the following formulas to calculate total disk space required:

Total = (( P * ( RT / SP ) * 12 ) / 1024 ) + 8 [ in KB ]
or = (( P * NS * 12 ) / 1024 ) + 8 [ in KB ]
where:
P is the number points
RT is the retention time
SP is the sampling period (both RT and SP must use the same time units)
NS is the number of retained samples (less than or equal to 99,999,000)
RT / SP must be <= 99,999,000.
Bulk Storage Reduction Data

Reduction data is stored in the INFORMIX database area. Maximum amount of reduction data
is function of the size of the INFORMIX database area.
Use the following formula to calculate the total disk space required. For each reduction group cal-
culate:
A = P * ( RT / RP )
B = NO * 4 + 10 + 27 (index size)
Total = A * B / 1024 [ in KB]
where:
A is the number of rows.
B is the row size and index size.
RT is the retention time.
RP is the reduction period.
NO is the number of operations (MAX, MIN, AVG, etc.).
P is the number of points.
165
Bulk Storage Manual Data

Manual data entry groups are stored in the INFORMIX database area. Use the following formula
to calculate the total disk space required:
Total = (14 * A * B / 1024) * 2
where:
A is the number of points.
B is the number of samples per point.
AP51A/AW51A Workstations
This section describes sizing guidelines for a Historian on the AP51 and AW51A workstations.
Topics in this section are:
♦ Processing Load (workstations, collection points, and reduction points per min)
♦ Bulk Storage Disk Space (sampling, reduction, and manually-entered data).
The performance limit of the Historian on a 50 Series server is the total number of points chang-
ing per second. For the AP51A and the AW51A, this number has a maximum of 250 points per
second.
NOTE
Turning the Historian on or off takes longer on an AP51 than on AP50 running
V3.1 (10 minutes vs. 6 minutes).
The amount of physical memory in the station also places a limit on the reduction load. For
example, the 4000-point Historian requires 24 MB minimum on the AP51A workstation.
Processing Load
To calculate the number of AP51s required for an application, take the largest number of:
T1 (Number of workstations)
T2 (Historian sampling rate)
T3 (Historian reduction rate)
T4 (CPU scoreboard).
Number of Workstations
Divide the total number of WPs required in the I/A Series system that are to be hosted by AP51s
(logical host in the case of WP50s and WP51s) and divide by 16. Round up to the next whole
number. Call this T1.
If, for example, 36 WP30s are needed for your configuration.
36 / 16 = 2.25
so T1 = 3
166
Number of Collection Points

When factoring the number of Historian collection points, the total number of APs required for a
given application is a function of package size and the sampling change rate.
The sampling change rate is based on the sampling configured rate and the percentage of points
changing within the configured sampling period. The sample change rate is always defined as the
number of points changing per second. For example, configuring 4000 points, all at 10 seconds,
yields a sampling configured rate of 400 points per second. If 50% of those 4000 points change
by more than the deadband within 10 seconds, the sampling change rate is 200 points per second.
For a 16 MB AP51, the maximum sampling change rate is 250 sample points per second. These
rates are independent of Historian package size. This is 25% better than the default AP50 and
equivalent to the larger memory AP50s.
AP51 (16 MB)
Total sample change rate / 250 = BH (Base Historian)
T2 = (BH) rounded to next highest integer
For example, to sample 4,000 points every 4 seconds, the sampling configured rate is 1,000 sam-
ple points per second.
167
Table D-6. AP51A Sampling Rate
% Points Sampling AP51s

Changed Change Rate (T2)
25 250 1
50 500 2
100 1000 4
Historian Reduction Points Per Minute

An AP51 is capable of reducing 400 sample points per minute or 4000 points per 10 minutes
(some phasing may be required, see “Reduction Group Parameters” on page 26.)
Divide the total desired reduction points per minute by 400 and round up. Call this T3.
# Reduction Points per Minute / 200 = T3
Examples:
To reduce 4000 points of data every 10 minutes, one AP51 with the 4000-point Historian can be
applied to the job.
To reduce 2000-points of data every 4 minutes, the total reduction load is 500 reduction points
per minute. Two AP51s, each with the 1000-point Historian, are needed.
Historian Bulk Storage

Historian sampling data files are stored in the /opt partition. Historian reduction data and manu-
ally entered data are saved in the INFORMIX database area.
Sampling Disk Space Requirements

At 1.2 GB maximum per sampling point:
A 2000-point Historian requires a maximum disk space of 2300 GB.
A 4000-point Historian requires a maximum disk space of 4600 GB.
Use the following formula to calculate the required disk space:
Total = ( (P * (RT / SP) ⋅ 12) / 1024 ) + 8 (in KB)
— or —
( (P ⋅ NS ⋅ 12) / 1024 ) + 8 (in KB)
where:
RT is the Retention Time.
SP is the Sampling Period (both RT and SP must use the same time units).
NS is the number of retained samples (must be ≤99,999,000).
RT / SP must be ≤99,999,000.
Reduction Disk Space Requirements

For each reduction group, calculate:
A = P * (RT / RP)
168
B = Number Operations * 4 + 10 (row size without operations) + 27 (index size)

Total = A * B / 1024 (in KB)
where:
B is row size.
The amount of disk space allocated for Historian reduction data is a function of the system disk
size. Additional disk space can be allocated for dedicated use by INFORMIX. This space, in addi-
tion to the space required for sampling data, dictates how much bulk storage is required.
For 535 MB system disk:
INFORMIX disk space = 32 MB
For the 1.05 GB system disk
INFORMIX disk space = 55 MB
Manual Data Entry Groups Disk Space

Manual data entry groups are saved in the INFORMIX database. Total manual data entry group
storage is calculated as follows:
(14 * A * B / 1024) * 2
where:
AP51B/AW51B Workstations
This section describes sizing guidelines specific to a Historian on the AP51B or the AW51B work-
station. Topics in this section are:
♦ Sampling Rate
♦ Reduction Rate
♦ Bulk Storage
♦ Disk Space Requirements.
The dominant application for AP products is the Historian with its various sample point capaci-
ties. The performance limit is the total number of points changing per second. For the AP51B,
this number has a maximum of 750 points per second (compared to 200 on the AP 50 and 250
on the AP51A).
Bulk storage requirements for sample data and reduction groups remain unchanged from the
AP51A. (See page 165.)
169
NOTE
The 4000-point Historian requires a minimum of 24 MB of RAM on the AP51B.
The 8000-point Historian requires a minimum of 32 MB.
It is important to note that for a 4000-point Historian with all points at maximum retention span
(99,999,000 samples each), a total of 4600 GB of bulk storage is required. To get the maximum
amount of Historian data requires disk concatenation and the 2.1 GB disk drives.
Available disk space for Historian sample points (/opt) on the AP51B’s 535 MB disk drive is sig-
nificantly less than the AP50 on the 424 MB disk drive. Therefore, AP51Bs with the Historian
have less default capacity than an equivalent AP50-based system.
Sampling Rate
When factoring the number of Historian collection points, the total number of AP workstations
required for a given application is a function of package size and the sampling change rate.
Sampling change rate is based on the sampling configured rate and the percentage of points
changing within the configured sampling period. The sample change rate always is defined as the
number of points change per second.
For example, configuring 4000 points, all at 10 seconds, yields a sampling configured rate of 400
points per second. If 50% of those 4000 points change by more than the deadpanned within 10
seconds, the sampling change rate is 200 points per second.
For the AP51 B, the maximum sampling change rate is 750 sample points per second, three times
the AP51A’s maximum sampling change rate. These rates are independent of Historian package
size.
Total sample change rate / 750 = BH (Base Historian)
For example, to sample 4000 points every four seconds, the sampling configured rate is 1000
sample points per second.
Table D-7. AP51B Sampling Rates
% Points Sampling Number of

Changed Change Rate AP51Bs
25 250 1
75 750 1
100 1000 2
Reduction Rate
An AP51B is capable of reducing 600 sample points per minute or 4000 points every 7 minutes.
(Some phasing might be required as described in “Reduction Group Parameters” on page 26.)
Divide the total desired reduction points per minute by 600 and round up:
Number of Reduction Points per Minute / 600
For example, to reduce 3600 points of data every 6 minutes, one AP51B with the 4000-point
Historian can be applied to do the job. However, to reduce 2000 points of data every 2 minutes,
170
is a total reduction load of 1000 reduction points per minute. Two AP51Bs, each with a 1000-
point Historian, are needed to do the job.
Bulk Storage Requirements

Historian sampling data files are stored in the /opt partition. Historian reduction data and manu-
ally entered data are saved in the INFORMIX database area.
Sampling Disk Space Requirements

1.2 GB maximum per sampling point (99,999,000 retained samples)
Table D-8. AP51B/AW51B Sampling Disk Space
Historian Total Maximum Disk

Size Space Required
2000 2300 GB
4000 4600 GB
8000 9300 GB
To calculate the disk space required, use the following formula:

Total = ( (P x (RT/SP) x 12) / 1024) + 8 (in kilobytes)
or ( (P x NS x 12) / 1024) + 8 (in kilobytes)
where:
P is number of points.
RT is retention time.
SP is sampling period (both RT and SP must use the same time units).
NS is number of retained samples (must be less than 99,999,000).
RT / SP must be less than 99,999,000.
Reduction Disk Space Requirements

For each reduction group, calculate:
A = P *( RT / RP )
B = NO * 4 + 10 + 27 (index size)
Total = A * B / 1024 [in KB]
where:
B is the row size and index size.
NO is the number of operations (MAX, MIN, AVG, etc.).
171
The amount of disk space allocated for Historian reduction data is a function of the system disk
size. Additional disk space can be allocated for dedicated use by INFORMIX. This space, in addi-
tion to the space required for sampling data, dictates how much bulk storage is required.
Table D-9. AP51B/AW51B Disk Space Requirements
System Disk Size INFORMIX Disk Space

535 MB 32 MB
1.5 GB 55 MB
2.1 GB 55 MB
Manual Data Entry Groups Disk Space

Manual data entry (MDE) groups are saved in the INFORMIX database. Total MDE group stor-
age is:
(14 x A x B / 1024 ) x 2
where:
AW51C Workstations
This section describes sizing guidelines for a Historian on the AW51C workstation. Topics in this
section are:
♦ Sampling Rate
♦ Reduction Rate.
The performance of the Historian package collection points (sampling) running on the
AW51C workstation must be constrained as to the total number of points changing per second.
For the AW51C, this upper limit is 1250 points per second, compared to 750 points per second
on the AW51B workstation. The limitation is due to the performance of the SCSI hard disks,
which serve as the file system for data points collection.
Bulk storage requirements for sample data and reduction groups remain unchanged from the orig-
inal AP51 as described previously in “Bulk Storage Sampling Data” on page 165.
AW51C Sampling Rate

The total number of AW51Cs required for a given application when factoring the number of His-
torian collection points is a function of package size and sampling change rate.
The sampling change rate is based on the sampling configured rate and the percentage of points
changing within the configured sampling period. The sample change rate always is defined as the
number of points changing per second. For example, configuring 4000 points, all at ten seconds,
yields a sampling configured rate of 400 points per second. If 50% of those 4000 points change
by more than the deadpanned within ten seconds, then the sampling change rate is 200 points per
second.
For an AW51C, the maximum sampling change rate is 1250 sample points per second. These
rates are independent of Historian package size.
172
Total sample change rate / 1250 = BH

T2 = (BH) rounded to the next highest integer
For example, to sample 4000 points every two seconds, the sampling configured rate is 2000 sam-
ple points per second.
Table D-10. AW51C Sampling Rates
Percentage of Sampling AW51Cs

Points Changed Change Rate Required
25 500 1
50 1000 1
100 2000 2
AW51C Reduction Rate

An AW51C is capable of reducing 600 sample points per minute or 4000 points every 7 minutes.
(Some phasing might be required as described in “Reduction Group Parameters” on page 26.)
To calculate the reduction rate, divide total reduction points required per minute by 600 and
round the result to the next highest integer – number of reduction points per minute / 600. For
example, you can reduce 3600 data points every 6 minutes with a single AW51C with a 4000-
point Historian. However, to reduce 2000 data points every 2 minutes, the total reduction load is
1000 reduction points per minute; and two AW51Cs, each with a 1000-point Historian, are
needed.
173
174
Index
A
ACE Report Writer 2, 13, 107, 116, 122
Report specification 116, 119
add_cfg 59, 60, 62, 65
add_data 83, 87
add_mem 60, 68, 69
add_opr 59, 60, 72, 73
AP20
Converting database 147
Copying database 143, 144
database initialization 143
AP50 143
databases 143
AP51
Archive data 8, 12, 14, 15, 16, 38, 43, 46, 47, 57, 58, 91, 93, 99, 161
Archive groups
Archive period 12, 28, 110
Archive time span 28, 43
Parameters 28
Phasing delay 26, 28, 63, 64, 85, 109, 110
Type 28
Archive time span 28, 43
Archiving Historical Data 15
Asterisk 27, 29, 30, 34, 41, 118, 140
Auto increment feature 51
B
Bad status 51
C
Changing Configuration Data 58
Collection points 11, 19, 24, 27, 59, 68, 71, 92
Fields 24
Grouping 148
Compound
Block.Parameter 25, 93, 108, 113
Configuration
Historian 10, 14
Configuration calls
add_cfg – Add Group Configuration 62
add_mem – Add Group Members 68
add_opr – Add Operations 72
175
B0193BL – Rev L Index
db_init – Database Initialization 61

del_cfg – Delete Group Configuration 66
del_mem – Delete Group Members 69
del_opr – Delete Operations 73
get_cfg – Get Group Configuration 67
get_mem – Get Group Members 70
get_opr – Get Operations 74
get_sum – Get Type Summary 61
mde_agrp – Add/Modify/Delete MDE Group Configuration Data 77
mde_amem – Add/Delete MDE Group Member Point 80
mde_apnt – Add/Modify/Delete MDE Point Configuration 75
mde_rgrp – Read MDE Group Configuration Data 79
mde_rmem – Read MDE Group Members 81
mde_rpnt – Read MDE Point Configuration Data 77
mod_cfg – Modify Group Configuration 65
Configuration Entries 23
Configurator
Icons 15, 22, 34, 35, 39
Converting database 147
Copying database 143, 144
Current data 38
D
Data display
Archive data 8, 12, 14, 15, 16, 38, 43, 46, 47, 57, 58, 91, 93, 99, 161
Current data 38
Database selection 38
Description 14
Originating station 41
Sample data 37, 39
Data retrieval calls
db_dlet – Database Removal 99
db_init – Database Initialization 95
get_data – Get Point Data 102
get_data – Retrieve Data 93
get_key – Get Keys 98
get_nam – Get Names 98
get_pt – Get Point Data 101
get_val – Get Values 97
mde_asmp – Add/Modify/Delete MDE Sample 104
mde_rsmp – Read MDE Samples 105
rq_oval – Request Operation Values 95
rq_oval and get_val – Retrieve Reduced Data 92
rq_pt – Request Point Data 99
rq_pt and get_pt – Retrieve Data on AP20 93
Database initialization 144
Databases
AP20 database initialization 143
176
Index B0193BL – Rev L
AP50 143
AP50 database initialization 144
Archive data 8, 12, 14, 15, 16, 38, 43, 46, 47, 57, 58, 91, 93, 99, 161
Converting AP20 147
Copying AP20 143, 144
Current data 38
Deleting 146
Managing 143
Sample data 37, 39
Saving AP50 databases 149
db_dlet 91, 99
db_init 59, 60, 61, 62, 64, 66, 67, 69, 70, 71, 73, 74, 75, 88, 91, 92, 93, 94, 95, 102
Defining MDE groups 29
Deleting the archive database 146
Deselect all button 35
dfin_ms 60
Direct storage of user data 87
Disk space 148
Disk space requirements 157, 160
Display Builder 14
Display field
Top menu 19, 22, 23, 33, 37, 38, 44, 49, 143, 144, 145, 148
Displaying Historical Data 14
E
Editing MDE values 50
Entry guidelines 23
Exit button 15, 22, 23, 33, 37, 49, 143, 145, 146, 151, 161, 162
G
Guidelines, configuration entries 23
H
Header files 59, 83
Historian
Library 57, 92, 93, 101
Security features 17
Starting or stopping 34
Historian database tables
all_groups table 108
all_points table 108
pnt_memb table 111, 128
tnd_memb table 112, 113
hr_fetc 5
hs_fetch 5
hstorian.h file 59, 83
177
I
Icons 15, 22, 34, 35, 39
INFORMIX database manager 2
INFORMIX-SQL 107, 119
L
Linking application programs 57
Load option 23
M
Main Archive Group Screen 27, 28
Main Reduction Group Screen 26
Manual data entry 49
Manual Data Entry groups 19, 29
Maximum queue length 31
MDE 5, 6, 8, 12, 13, 14, 16, 17, 19, 28, 29, 30, 39, 49, 57, 58, 91, 93, 99, 100, 102, 108, 161
auto increment 51
Bad status 51
MDE groups 19, 29
Definition 29
MDE values
how to edit 50
Member points 11, 19, 24, 27, 59, 68, 71, 92
Members button 27, 29
Message groups 6, 12, 14, 19, 31, 36, 60, 65, 66, 69, 70, 71, 83, 112
Parameters 31
Queue length 31
Multiple selection 27, 29
N
Number of messages 111
Number of samples 9, 10, 25, 162
O
Object
Manager 8, 25, 96, 97, 101, 124, 126, 155
Modules 57
Operation calls
add_dat – Add Data 89
chg_sta – Change Group Status 86
get_gmt – Get Greenwich Mean Time 90
get_sta – Get Group Status 85
Group State Changes 83
Group State Control Signals 83
Group States 83
req_add – Request Data Add 87
state transitions 83
178
Index B0193BL – Rev L
storing user data 87

Optimizing 148
Originating station 41
Overwriting old data 31
P
Phasing delay 26, 28, 63, 64, 85, 109, 110
Point collection configuration screen 24
Point samples 5, 6, 8, 9, 10, 12, 25
Collection 6, 8, 11, 14, 33, 59
Point identifier 8, 68, 71, 89, 91, 92, 96, 98, 99, 108, 111, 116
R
Read-only mode 19
Reduction operations 10
rq_oval 91, 92, 94, 95, 96, 97
S
Sample data 37, 39
Sampling
Disk space requirements 157, 160
Saving AP50 databases 149
Saving Disk Space 148
Scheduler
Deselect all button 35
Detail display 35
Select all button 34, 35
Starting or stopping Historians 34
Screen control, pointer device 15
Screen format
Top menu 19, 22, 23, 33, 37, 38, 44, 49, 143, 144, 145, 148
Security features 17
Select all button 34, 35
Starting or Stopping Historians 34
State transitions 83, 85, 86
Store option 23
T
Terminal emulation 122, 123, 143, 144, 145, 146, 147, 148, 149, 150, 161
Time change messages 17
Time span
Archive 28, 43
Time, adjustment 17
Top menu bar 19, 22, 23, 33, 37, 38, 44, 49, 143, 144, 145, 148
Trending 3
179
U
Update time span 8, 25
User applications
add_cfg call 59, 60, 62, 65
add_data call 83, 87
add_mem call 60, 68, 69
add_opr call 59, 60, 72, 73
Changing configuration data 58
db_dlet call 91, 99
db_init call 59, 60, 61, 62, 64, 66, 67, 69, 70, 71, 73, 74, 75, 88, 91, 92, 93, 94, 95, 102
dfin_ms call 60
Direct data storage 87
Header files 59, 83
Linking 57
rq_oval call 91, 92, 94, 95, 96, 97
State transitions 83, 85, 86
V
VT100 mode 122, 123, 143, 144, 145, 146, 147, 148, 149, 150, 161
W
Wildcard character 27, 29, 30, 34, 41, 118, 140
33 Commercial Street
Foxboro, Massachusetts 02035-2099
United States of America
www.foxboro.com
Inside U.S.: 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. 0707

b0193bl L

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

b0193bl L

Uploaded by

Copyright:

Available Formats

B0193BL

Copyright 1990-2007 Invensys Systems, Inc.

SOFTWARE LICENSE AND COPYRIGHT INFORMATION

2. Functional Overview ......................................................................................................... 5

5. Data Display ................................................................................................................... 37

Archive Backup Messages ................................................................................................... 47

7. Manual Data Entry.......................................................................................................... 49

8. Calls Overview ................................................................................................................ 57

9. Configuration Calls ......................................................................................................... 59

mde_agrp — Add/Modify/Delete MDE Group Configuration Data ...................................... 77

10. Operation Calls ............................................................................................................. 83

11. Data Retrieval Calls....................................................................................................... 91

12. Writing Historian Reports .......................................................................................... 107

Reduction Group Table ................................................................................................... 115

13. Managing Databases.................................................................................................... 143

Appendix A. Data Reduction Algorithms .......................................................................... 153

Appendix B. Object Manager Status Tag Processing ......................................................... 155

Appendix C. Disk Space Required for Sampling Points..................................................... 157

Appendix D. Sizing Guidelines.......................................................................................... 159

Rules for Collection Point Sampling ............................................................................ 159

Index .................................................................................................................................. 175

Chapter 13 “Managing Databases” describes typical database procedures including copying,

Figure 1-1. Tabular Display of Reduced Data

Figure 1-2 shows an application diagram for the Historian.

I/A Series Other User I/A Series

Figure 1-2. Historian Application Diagram

Figure 1-3. Historian Data Report Generation

12:22:891 13:24:391 HT3

Figure 2-1. Historian Data Collection

Process Data (Analog & Digital)

Object Application Messages

I/A Series Configuration Data

Generic data object I/A Series and I/A Series

Figure 2-2. Historian Data Flow

Historian Application Object Historian

Collect Collect Collect Collect

Figure 2-3. Historian Functional Block Diagram

Referring to Figure 2-3, data collection consists of:

Figure 2-4. Historian Point Sample Collection in AP Memory

Collection Point 1 Samples

* 99,999,000 Samples for AP50

Variable 1 Variable 2 Variable n

Time Slot 2 Value/Tag Value/Tag Value/Tag

Value/Tag Value/Tag Value/Tag Value/Tag

Figure 2-6. Historian Reduction Group Data Storage

1 Day 1 Week 1 Day

Figure 2-8. Historian Application Message Collection

♦ Historian data retrieval displays

Manual Data Entry Values

Historian Historian Historian Historian MDE Con- MDE Edit

Point Sample Group Add Group Messages

Figure 2-9. Historian Workstation Interface Menu Structure

Configuring the Historian

Scheduling Historian Functions

Displaying Historical Data

Archiving Historical Data

Accessing Historian Displays

Screen Control Functions

The following steps are optional:

Manual Data Groups

Working in the Configurator Screens

Figure 3-1. Typical Historian Configurator Screen

Buttons and Icons